docs: 新增V30.0版本相关设计文档与指南

新增服务器启动文档、设计说明书、风险清单等核心文档补充前端集成蓝图、多租户实施清单、上线红线检查清单添加质量保障文档与早期业务规格书
2026-03-16 01:31:26 +08:00
commit 6759d47de4
74 changed files with 9310 additions and 0 deletions
--- a/docs/blueprints/frontend-integration/TEMPLATE.md
+++ b/docs/blueprints/frontend-integration/TEMPLATE.md
@@ -0,0 +1,40 @@
+# 前端集成蓝图：[功能名称]
+
+> **[AI-X @ YYYY-MM-DD]**：由后端 Agent 在完成功能逻辑后产出，用于指导 Console 端全栈实现。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：描述前端如何呈现后端建议，以及如何通过交互提升商业 ROI。
+- **关联后端 Service**：`[ServiceName].ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：(例如：Console -> 供应链管理 -> 调价建议)
+- **展示组件**：
+    - [ ] **建议卡片**：展示关键指标（如：预期利润提升 %）。
+    - [ ] **因果叙述区**：呈现 `causalChain` 字段，支持 Markdown 渲染。
+    - [ ] **对比视图**：展示“当前价格” vs “建议价格”的差异。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 智能调价建议 (AGI Suggested)                       |
+    +-----------------------------------------------------------+
+    | 建议：跟降 $2.00 | 预期毛利提升：+15% | 信心度：92%       |
+    +-----------------------------------------------------------+
+    | [?] 为何建议？                                            |
+    | "监测到竞品 XYZ 正在压价，且我方仍有 22% 利润空间..."     |
+    +-----------------------------------------------------------+
+    | [ 拒绝建议 ]                      [ 一键应用并同步平台 ]  |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/suggestions?module=PRICING`
+- **关键字段映射**：
+    - `causal_chain` -> 叙述文案
+    - `factors` -> 影响因子热力图
+- **状态流转**：
+    - 点击 [应用] -> `POST /api/v1/suggestions/approve` -> 按钮进入 `Loading` 状态 -> 成功后 Toast 提示并刷新列表。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 移动端适配性校验。
+- [ ] 关键数据脱敏展示。
+- [ ] 错误边界处理（API 500 时的 Fallback 视图）。
--- a/docs/blueprints/frontend-integration/approval-center.md
+++ b/docs/blueprints/frontend-integration/approval-center.md
@@ -0,0 +1,34 @@
+# Frontend Integration: Approval Center (通用审批中心)
+
+## 🎨 UI Layout Sketch
+- **Page Path**: `/governance/approval`
+- **Component Structure**:
+  - `ApprovalSummary`: Top metrics (Pending Approvals, Approved, Rejected).
+  - `ApprovalTabs`: "My Pending", "My History", "All (Admin only)".
+  - `ApprovalCardList`: Grid showing:
+    - Type icon (e.g., `HIGH_VALUE_ORDER` in red, `PRICE_CHANGE` in blue).
+    - Status Badge (e.g., `PENDING` in orange, `APPROVED` in green).
+    - Stage indicator: `Stage 1/2` (Manager), `Stage 2/2` (Finance).
+    - Requester & Date.
+    - Resource ID & Description.
+  - `ApprovalDetailModal`:
+    - Full details (Metadata, Amount, etc.).
+    - Decision log (who approved which stage).
+    - Decision Narrative from `DecisionExplainabilityEngine`.
+    - "Approve", "Reject", "Comment" actions.
+
+## 🔄 Interaction State Machine
+- `INITIAL`: Fetching pending requests.
+- `PENDING`: Request listed for approver.
+- `STAGE_TRANSITION`: Request moving from Stage 1 to Stage 2.
+- `APPROVED`: Final approval reached.
+- `REJECTED`: Request terminated at any stage.
+
+## 🔗 API Mapping
+- `GET /api/v1/approval/pending`: Fetches `cf_approval_requests` with `status=PENDING`.
+- `POST /api/v1/approval/approve`: Triggers `ApprovalService.approve`.
+- `GET /api/v1/approval/history`: Fetches `cf_approval_requests` with `status=APPROVED|REJECTED`.
+
+## 📈 ROI Visualization
+- "Compliance Audit Trail": 100% visibility of sensitive actions.
+- "Approval Latency": Average time from request to final decision.
--- a/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md
+++ b/docs/blueprints/frontend-integration/biz-gov-05-roi-dashboard.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：建议采纳 ROI 实时看板 (ROI Dashboard)
+
+> **[AI-2 @ 2026-03-14]**：基于 `DecisionExplainabilityEngine.ts` 补全。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：让管理层实时看到 AI 建议对公司财务的正面贡献，通过“建议执行后预估收益”增强 AGI 的商业互信。
+- **关联后端 Service**：[DecisionExplainabilityEngine.ts](file:///d:/trae_projects/crawlful-hub/server/src/core/ai/DecisionExplainabilityEngine.ts)
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 经营决策 -> ROI 看板
+- **展示组件**：
+    - **累计贡献指标卡 (Metrics)**：
+        - 已采纳建议总收益 (Actual Savings/Profit)
+        - 待处理建议潜在收益 (Potential Savings/Profit)
+    - **模块收益分布 (Module Split)**：饼图展示 Pricing, Sourcing, Inventory 各自贡献。
+    - **趋势分析图 (Trend)**：时间轴展示“AI 建议执行量”与“利润增长”的协同性。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [累计 AI 贡献]：$1,250,000 | 待处理潜在收益：$340,000       |
+    +-----------------------------------------------------------+
+    | 建议分布: [Pricing 45%] [Sourcing 30%] [Inventory 25%]    |
+    +-----------------------------------------------------------+
+    | 最近执行建议 (Recent Execution)                           |
+    | - SKU-01: 调价方案 (+$500)   - SKU-05: 1688 换源 (+$1,200) |
+    | - SKU-09: 缺货预警 (避免损耗 $800)                         |
+    +-----------------------------------------------------------+
+    | [ 下钻明细 (Detail) ]               [ 导出月度 ROI 报告 ]  |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/analytics/roi-metrics?tenantId=T123`
+- **关键字段映射**：
+    - `total_profit_delta` -> 已采纳收益
+    - `potential_savings` -> 待处理潜在收益
+    - `causalChain` -> 建议的宏观因果描述
+- **状态流转**：
+    - 自动刷新机制：每 5 分钟轮询或 WebSocket 推送最新 ROI 变动。
+
+## 4. 生产校验项 (FE Readiness)
+- [x] 金额展示需符合租户币种精度配置。
+- [x] 需对异常大额 ROI 波动进行弹窗预警。
+- [x] 确保在多租户环境下，数据隔离边界绝对严密。
--- a/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md
+++ b/docs/blueprints/frontend-integration/biz-mkt-30-dynamic-pricing.md
@@ -0,0 +1,40 @@
+# 前端集成蓝图：智能动态调价建议 (Dynamic Pricing)
+
+> **[AI-1 @ 2026-03-14]**：基于 `DynamicPricingService.ts` 产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：帮助运营人员在保护利润红线的前提下，快速响应市场竞争，通过 AGI 叙述消除“为何改价”的疑虑。
+- **关联后端 Service**：[DynamicPricingService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/DynamicPricingService.ts)
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 商品管理 -> 价格竞争看板
+- **展示组件**：
+    - **决策因果流 (Narrative Timeline)**：左侧展示商品现状，右侧展示 AGI 模拟出的调价后利润曲线。
+    - **风险预警色**：如果调价后利润率接近 15% (B2B) 或 20% (B2C) 红线，组件背景需变为浅黄色。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | SKU: SKU-12345 | 当前价: $25.00 | 建议价: $22.99 (-$2.01) |
+    +-----------------------------------------------------------+
+    | [AGI 分析报告]                                            |
+    | 1. 监测到 AliExpress 竞品降价 12%。                       |
+    | 2. 调价后预计销量提升 40%，月利润提升 $450。              |
+    | 3. 调价后净利润率为 21.5% (高于 20% 预警线)。             |
+    +-----------------------------------------------------------+
+    | [ 查看证据链 (XAI) ] | [ 忽略 ] | [ 一键执行调价建议 ]    |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/pricing/suggestions?status=PENDING_REVIEW`
+- **核心逻辑映射**：
+    - 后端 `suggested_price` -> 前端输入框默认值。
+    - 后端 `causalChain` -> 前端“AGI 分析报告”文案。
+- **状态流转**：
+    - 点击 [一键执行] -> 调用 `POST /api/v1/pricing/batch-approve`。
+    - 按钮状态切换：`Normal` -> `Processing` -> `Completed` (Green Check)。
+
+## 4. 生产校验项 (FE Readiness)
+- [x] 价格输入框需支持“低于成本价”二次确认弹窗。
+- [x] 需联动 `DecisionExplainabilityEngine` 展示热力图。
+- [x] 确保在不同屏幕分辨率下，AGI 叙述长文本能优雅折叠。
--- a/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md
+++ b/docs/blueprints/frontend-integration/biz-sup-15-sourcing-optimization.md
@@ -0,0 +1,42 @@
+# 前端集成蓝图：1688 极速降本比价建议 (Sourcing Optimization)
+
+> **[AI-1 @ 2026-03-14]**：基于 `SupplyChainService.ts` 补全。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：通过实时比价锁定 1688 源头工厂，为运营提供一键切换货源的决策支持，直接降低采购成本。
+- **关联后端 Service**：[SupplyChainService.ts](file:///d:/trae_projects/crawlful-hub/server/src/services/SupplyChainService.ts)
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链 -> 降本建议
+- **展示组件**：
+    - **货源对比矩阵 (Source Matrix)**：左侧为当前供应商，右侧为 1688 推荐供应商，对比单价、MOQ、交期。
+    - **ROI 预测环**：展示“切换后年化节省总额”。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [货源切换建议] SKU-8899 | 预期单均节省：$1.50 (降幅 18%)    |
+    +-----------------------------------------------------------+
+    | 当前源 (Local) | VS | 推荐源 (1688 Direct Factory)        |
+    | 单价: $8.50    |    | 单价: $7.00                         |
+    | 交期: 3天      |    | 交期: 5天 (风险可控)                |
+    +-----------------------------------------------------------+
+    | [?] AGI 深度分析：                                        |
+    | "该 1688 供应商为勋章工厂，评分 4.8，与当前款式匹配度 98%..." |
+    +-----------------------------------------------------------+
+    | [ 暂时保留 ]                      [ 一键更新采购路由 ]    |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/sourcing/suggestions?type=COST_DOWN`
+- **关键字段**：
+    - `current_source_info` -> 当前货源详情
+    - `suggested_source_info` -> 1688 货源详情
+    - `causalChain` -> 供应商信誉与匹配度分析
+- **状态流转**：
+    - 应用建议 -> `POST /api/v1/sourcing/apply-suggestion` -> 自动更新 `cf_product_sourcing` 关联。
+
+## 4. 生产校验项 (FE Readiness)
+- [x] 需支持 1688 商品主图点击预览。
+- [x] 利润提升计算逻辑需包含“跨境运费摊销”差异。
+- [x] 针对大额节省（> $10,000/年）需有特殊高亮动画。
--- a/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md
+++ b/docs/blueprints/frontend-integration/carbon-credit-trading-ui.md
@@ -0,0 +1,46 @@
+# 前端集成蓝图：碳信用交易撮合建议 (Carbon Credit Trading)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_60 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：聚合租户碳足迹数据，撮合碳抵扣额度购买，提升品牌绿色合规等级，增强 DTC 品牌溢价。
+- **关联后端 Service**：`CarbonCreditTradingService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 绿色供应链 -> 碳信用交易
+- **展示组件**：
+    - [ ] **碳中和看板**：展示租户已抵消的碳排放量。
+    - [ ] **碳信用交易列表**：展示 AGI 撮合的碳抵扣交易（Credits, Cost, Provider）。
+    - [ ] **绿色合规证书**：展示租户已获得的碳中和证书及对应订单。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 碳信用交易管理 (Carbon Credit Trading)           |
+    +-----------------------------------------------------------+
+    | [ 累计抵消: 4,500 kg CO2 ] [ 状态: 已抵消 (SETTLED) ]      |
+    +-----------------------------------------------------------+
+    | [ 碳抵扣撮合建议 (Credit Match) ]                         |
+    | --------------------------------------------------------- |
+    | 建议抵扣: 250 kg | 成本: $6.25 | 供应商: Carbon-Pool-X    |
+    +-----------------------------------------------------------+
+    | [ AGI 绿色建议 (Green Insight) ]                          |
+    | "该订单 (ORD-1122) 碳足迹为 25.5 kg。建议购买碳信用 |
+    | 以抵销。抵消后可解锁：'绿色品牌' 标签及 10% 税务减免。" |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 确认购买并抵扣 ]       |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/green/trading/matches`
+- **关键字段映射**
+    - `credits_purchased` -> 抵扣额度
+    - `cost_amount` -> 交易成本
+    - `provider_did` -> 提供商 DID
+- **状态流转**：
+    - 撮合建议 -> `PENDING` -> 交易确认 -> `SETTLED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 碳信用池数据的准实时性核对。
+- [ ] 碳抵消成本的财务对账报表。
+- [ ] 导出包含交易证明的绿色合规证书。
--- a/docs/blueprints/frontend-integration/carbon-pledge-ui.md
+++ b/docs/blueprints/frontend-integration/carbon-pledge-ui.md
@@ -0,0 +1,47 @@
+# 前端集成蓝图：自动化供应链碳配额质押建议 (Carbon Pledge)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_60 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：允许租户将积累的碳抵扣额度作为“绿色资产”质押，换取更优的采购账期、更低的手续费或更高的授信额度。
+- **关联后端 Service**：`CarbonPledgeService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 绿色供应链 -> 碳配额质押
+- **展示组件**：
+    - [ ] **可质押资产看板**：展示租户当前的累计碳信用额度。
+    - [ ] **权益兑换建议表**：展示 AGI 建议的质押方案及对应收益。
+    - [ ] **质押合约状态流**：展示已生效的质押记录及其对账期的影响。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 碳配额质押建议 (Carbon Pledge)                   |
+    +-----------------------------------------------------------+
+    | [ 可质押总额: 5,000 kg ] [ 已质押: 1,200 kg ]             |
+    +-----------------------------------------------------------+
+    | [ AGI 权益建议 (Pledge Suggestion) ]                      |
+    | --------------------------------------------------------- |
+    | 建议质押: 2,500 kg | 目标收益: 账期延长 15 天 (Net-45)    |
+    | 收益价值: 预估节省资金成本 $120.00/月                    |
+    +-----------------------------------------------------------+
+    | [ AGI 洞察 ]                                              |
+    | "监测到您的碳信用充足，通过质押 50% 的配额，可显著优化 |
+    | 资金周转率。该操作不会影响您的绿色品牌评级。"            |
+    +-----------------------------------------------------------+
+    | [ 拒绝建议 ]                      [ 确认质押并应用权益 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/green/pledge/suggestions`
+- **关键字段映射**
+    - `pledge_amount` -> 质押量
+    - `target_benefit` -> 目标收益
+    - `status` -> 质押状态
+- **状态流转**：
+    - 触发质押 -> `PENDING` -> 供应商/平台确认 -> `ACTIVE`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 碳信用资产的锁定与释放逻辑界面。
+- [ ] 账期变动在财务模块的实时映射。
+- [ ] 导出包含绿色金融贡献的租户年度审计报告。
--- a/docs/blueprints/frontend-integration/cashflow-prediction.md
+++ b/docs/blueprints/frontend-integration/cashflow-prediction.md
@@ -0,0 +1,50 @@
+# 📋 前端实现方案：未来 30 天现金流预测 (Cashflow Prediction)
+
+## 1. UI 布局草图 (UI Layout Sketch)
+
+```
+-------------------------------------------------------------------------+
+| [Breadcrumb: Console > Finance > Cashflow Forecast]                     |
+-------------------------------------------------------------------------+
+| [Current Cash: $50,000.00] [Projected Day 30: $12,450.00]               |
+-------------------------------------------------------------------------+
+| [现金流瀑布图 (Cashflow Waterfall)]                                       |
+| [Chart: 当前(柱) -> +待收(绿) -> -待付(红) -> 预计(柱)]                   |
+|-------------------------------------------------------------------------|
+| [收支详情 (Breakdown)]                                                   |
+| +---------------------------------------------------------------------+ |
+| | 类型 (Type)             | 金额 (Amount) | 关键来源 (Source)         | |
+| |-------------------------|---------------|---------------------------| |
+| | 待结回款 (Receivables)  | +$80,000.00   | Amazon/TikTok Shipped Orders| |
+| | 供应商欠款 (Payables)   | -$110,000.00  | Pending Purchase Orders   | |
+| | 运营成本 (OpEx)         | -$7,550.00    | Salaries/Tools/Server     | |
+| |-------------------------|---------------|---------------------------| |
+| | 预计净变化 (Net)        | -$37,550.00   |                           | |
+| +---------------------------------------------------------------------+ |
+-------------------------------------------------------------------------+
+| [风险预警 (Risk Alert)]                                                 |
+| > [WARNING] 预计 25 天后现金余额将低于安全阈值 (20%)。建议推迟部分采购计划。   |
+-------------------------------------------------------------------------+
+```
+
+## 2. 交互状态机 (Interaction FSM)
+
+- **INIT**: 初始化加载。
+- **PREDICTING**: 调用 `/api/finance/cashflow/predict`。
+- **ALERTING**: 若 `projectedCash < 0` 触发全局红色顶栏告警。
+- **SIMULATING**: 支持手动调整“待收回款比例”查看不同情景下的预测。
+
+## 3. 核心 API 字段映射 (API Field Mapping)
+
+| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) |
+| :--- | :--- | :--- |
+| 当前可用现金 | `currentCash` | 实时账户余额 |
+| 未来30天预计 | `projectedCash` | 计算后的期末余额 |
+| 待收总额 | `totalReceivables` | 已发货未结算订单总额 |
+| 待付总额 | `totalPayables` | 待支付采购单总额 |
+| 风险等级 | `riskLevel` | LOW/WARNING/CRITICAL |
+
+## 4. ROI 可视化逻辑 (ROI Visualization)
+
+- **生存天数 (Burn Rate)**: 自动算出按当前净支出速度，现金还能支撑多少天。
+- **资金缺口建议**: 联动 `SovereignCreditPoolService` 展示可申请的贷款额度建议。
--- a/docs/blueprints/frontend-integration/circuit-breaker-ui.md
+++ b/docs/blueprints/frontend-integration/circuit-breaker-ui.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：全自动执行熔断控制 (Circuit Breaker UI)
+
+> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 Batch 56 熔断器逻辑后产出，用于指导 Console 端全栈实现。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：保护企业资产，当 AGI 执行出现连续异常或资金回撤时，自动切断全自动执行链路，强制转回人工审批模式。
+- **关联后端 Service**：`AutoCircuitBreakerService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> AI 控制台 -> 风险熔断器
+- **展示组件**：
+    - [ ] **全模块熔断状态矩阵**：显示各业务模块（调价、采购、库存）的实时熔断状态。
+    - [ ] **熔断根因展示**：最近一次触发熔断的异常日志。
+    - [ ] **手动控制开关**：人工手动强制熔断或重置。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] AGI 熔断保护墙 (Circuit Breaker Status)            |
+    +-----------------------------------------------------------+
+    | 模块: 动态调价 | 状态: [ OPEN (已熔断) ] | 失败数: 5/5    |
+    +-----------------------------------------------------------+
+    | 模块: 供应链采购 | 状态: [ CLOSED (正常) ] | 失败数: 0/5   |
+    +-----------------------------------------------------------+
+    | [!] 熔断触发详情:                                         |
+    | "模块 '动态调价' 已触发熔断保护 (原因: 连续 5 次执行异常)" |
+    | 时间: 2026-03-14 15:30:22                                 |
+    +-----------------------------------------------------------+
+    | [ 导出异常报告 ]              [ 手动重置并恢复全自动 ]    |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/circuit/status` (返回 `cf_circuit_breaker_status` 数据)
+- **关键字段映射**
+    - `status` -> 状态 (OPEN/CLOSED)
+    - `failure_count` -> 连续失败次数
+    - `last_failure_at` -> 最近失败时间
+- **状态流转**：
+    - 点击 [手动重置] -> `POST /api/v1/circuit/reset` -> 恢复正常。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 熔断状态需使用显眼的红色/绿色标签。
+- [ ] 重置操作必须包含二次确认弹窗。
+- [ ] 熔断触发时应在全局通知栏推送 CRITICAL 级别告警。
--- a/docs/blueprints/frontend-integration/compliance-certificate-ui.md
+++ b/docs/blueprints/frontend-integration/compliance-certificate-ui.md
@@ -0,0 +1,47 @@
+# 前端集成蓝图：合规证书自动化生成 (Compliance Certificate)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_50 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动提取订单数据并生成符合目的国要求的电子合规证书（原产地证、CE、FDA），减少人工录入 90%，确保合规过关。
+- **关联后端 Service**：`ComplianceCertificateService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 合规中心 -> 合规证书
+- **展示组件**：
+    - [ ] **已生成证书流水**：展示每笔订单生成的电子合规证书及其状态。
+    - [ ] **合规证书预览**：展示证书详情及对应的 DID 签名。
+    - [ ] **多国合规政策提示**：展示各国所需的证书类型。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 合规证书管理 (Compliance Certificates)           |
+    +-----------------------------------------------------------+
+    | [ 证书 ID: CERT-2233 ] [ 状态: 已生成 (GENERATED) ]       |
+    +-----------------------------------------------------------+
+    | 证书类型: 原产地证 (ORIGIN) | 颁发机构: DID-Gov-Hub     |
+    +-----------------------------------------------------------+
+    | [ 证书预览 (Certificate Preview) ]                         |
+    | 订单 ID: ORD-5566 | 目的地: 德国 (DE) | 有效期: 12 个月  |
+    +-----------------------------------------------------------+
+    | [ AGI 合规建议 (Compliance Insight) ]                    |
+    | "系统已基于订单数据自动生成电子原产地证。已通过 DID 签 |
+    | 名，符合欧盟 IOSS 合规通关要求。"                      |
+    +-----------------------------------------------------------+
+    | [ 撤销证书 ]                      [ 下载电子正本 (PDF) ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/compliance/certificates?order_id=ORD-5566`
+- **关键字段映射**
+    - `certificate_type` -> 证书类型
+    - `digital_signature` -> 电子签名
+    - `valid_until` -> 有效期
+- **状态流转**：
+    - 触发生成 -> `GENERATED` -> 被海关/第三方验证 -> `VERIFIED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 证书生成逻辑的准实时性核对。
+- [ ] 证书预览界面的水印保护。
+- [ ] 导出包含数字签名的 PDF 证书。
--- a/docs/blueprints/frontend-integration/courier-credit-ui.md
+++ b/docs/blueprints/frontend-integration/courier-credit-ui.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：众包物流配送员 DID 信用分级 (Courier Credit)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_70 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：建立基于 DID 的配送员信用体系，通过自动化评分与等级划分，筛选优质众包资源，降低末端派送风险。
+- **关联后端 Service**：`CourierCreditService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 履约中心 -> 众包资源 -> 配送员信用
+- **展示组件**：
+    - [ ] **配送员信用分布图**：展示活跃配送员的信用等级分布 (Platinum, Gold, etc.)。
+    - [ ] **信用明细卡片**：展示特定配送员的履约率、争议率及 AGI 评价。
+    - [ ] **派单优先级设置**：允许管理员配置不同信用分对应的派单权重。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 配送员信用分级管理 (Courier Credit)               |
+    +-----------------------------------------------------------+
+    | [ 配送员: Courier-Alpha ] [ 信用分: 95.5 ] [ 等级: 铂金 ] |
+    +-----------------------------------------------------------+
+    | 成功派送: 1,200 | 争议案件: 2 | 准时率: 99.2%             |
+    +-----------------------------------------------------------+
+    | [ AGI 信用洞察 (Credit Insight) ]                         |
+    | "该配送员信用极佳，近 30 天无任何投诉。建议提升其在核心 |
+    | 商业区的派单优先级，并解锁 '高货值商品' 派送权限。"      |
+    +-----------------------------------------------------------+
+    | [ 降低权限 ]                      [ 提升派单权重 (1.2x) ]  |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/logistics/courier/credit?did=DID-123`
+- **关键字段映射**
+    - `rating` -> 信用分
+    - `successful_deliveries` -> 成功数
+    - `dispute_count` -> 争议数
+- **状态流转**：
+    - 配送完成 -> 调用 `CourierCreditService.updateCourierScore` -> 更新 UI 评分。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 信用分变动的历史趋势曲线图。
+- [ ] 恶意差评的信用申诉处理界面。
+- [ ] 导出包含信用背景的配送员准入清单。
--- a/docs/blueprints/frontend-integration/crm-hub.md
+++ b/docs/blueprints/frontend-integration/crm-hub.md
@@ -0,0 +1,35 @@
+# Frontend Integration: CRM Hub (客户中枢)
+
+## 🎨 UI Layout Sketch
+- **Page Path**: `/business/crm`
+- **Component Structure**:
+  - `CustomerStats`: Top metrics (Total Customers, Bronze/Silver/Gold/Platinum count).
+  - `CustomerFilter`: Filtering by level, tags, spend, and order count.
+  - `CustomerTable`: List of customers with:
+    - Level badge (e.g., `GOLD` in yellow, `PLATINUM` in purple).
+    - Order count & Total Spend.
+    - Credit Score (e.g., 95 in green).
+    - Tags (e.g., "Frequent Buyer", "B2B", "Low Return Rate").
+  - `Customer360Drawer`: Full profile on click:
+    - `ProfileHeader`: Name, Email, Level, Credit Score.
+    - `OrderHistory`: Timeline of past 10 orders (from `ConsumerOrderService`).
+    - `TransactionHistory`: Reconciliation status of past 5 transactions (from `FinanceReconService`).
+    - `DisputeHistory`: Past complaints and resolutions (from `DisputeArbitrationService`).
+    - `SummaryStats`: Reliability indicator and active disputes count.
+  - `ActionButtons`: "Edit Profile", "Update Credit", "Send Coupon".
+
+## 🔄 Interaction State Machine
+- `INITIAL`: Fetching global customer profiles.
+- `FILTERING`: User applying criteria.
+- `VIEWING`: Drawer open with 360 view.
+- `UPDATING`: User adjusting credit score or tags.
+- `COMMUNICATING`: User sending email or coupon.
+
+## 🔗 API Mapping
+- `GET /api/v1/crm/list`: Fetches `cf_customer_profiles`.
+- `GET /api/v1/crm/360?customerId={id}`: Triggers `Customer360Service.getCustomer360`.
+- `POST /api/v1/crm/credit`: Triggers `Customer360Service.updateCreditScore`.
+
+## 📈 ROI Visualization
+- "Customer Lifetime Value (LTV)": Total spend per customer over time.
+- "Churn Rate": Percentage of customers without orders in 90 days.
--- a/docs/blueprints/frontend-integration/cross-node-settlement-ui.md
+++ b/docs/blueprints/frontend-integration/cross-node-settlement-ui.md
@@ -0,0 +1,45 @@
+# 前端集成蓝图：跨节点自治清算协议 (Cross-Node Settlement)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 SOV_NET_02 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：实现 Hub 节点间的自动化利润分润与资金清算，构建去中心化的全球贸易价值网。
+- **关联后端 Service**：`CrossNodeSettlementService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 跨节点清算
+- **展示组件**：
+    - [ ] **节点拓扑图**：展示当前 Hub 与其它贸易 Hub 间的连接状态。
+    - [ ] **清算流水表**：展示跨节点分润的详细记录（Source, Target, Amount, Status）。
+    - [ ] **清算证明卡片**：展示基于 DID 与 ZKP 的清算证据链。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 跨节点自治清算 (Cross-Node Settlement)           |
+    +-----------------------------------------------------------+
+    | [ 当前节点: Hub-Local ] <----( $1,200 )----> [ Hub-Remote ] |
+    +-----------------------------------------------------------+
+    | [ 最近清算记录 ]                                          |
+    | ID: CN-7788 | 目标: Node-Alpha | 金额: $450.00 | ✅ 已确认 |
+    +-----------------------------------------------------------+
+    | [ AGI 清算洞察 ]                                          |
+    | "系统已自动识别跨节点订单 ORD-9900 的分润协议。预估结算 |
+    | 金额：$120.00。清算证据已通过 DID 存证并发送至目标节点。" |
+    +-----------------------------------------------------------+
+    | [ 撤回请求 ]                      [ 查看 ZKP 证据链 ]      |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/settlement/cross-node`
+- **关键字段映射**
+    - `source_node_id` -> 发起节点
+    - `target_node_id` -> 目标节点
+    - `settlement_proof_hash` -> 证明哈希
+- **状态流转**：
+    - 发起结算 -> `PENDING` -> 目标节点确认 -> `EXECUTED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 跨节点网络延迟的实时监控。
+- [ ] 节点间身份握手证书的有效性校验。
+- [ ] 导出包含多节点路径的全球财务汇总。
--- a/docs/blueprints/frontend-integration/crowdsourced-logistics.md
+++ b/docs/blueprints/frontend-integration/crowdsourced-logistics.md
@@ -0,0 +1,45 @@
+# 前端集成蓝图：最后一公里众包路由优化 (Crowdsourced Last-mile)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_30 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：在传统物流商瘫痪时，自动调度众包资源，确保履约不中断，提升物流韧性。
+- **关联后端 Service**：`CrowdsourcedLogisticsService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 履约中心 -> 众包物流管理
+- **展示组件**：
+    - [ ] **众包代理地图**：展示各城市活跃的众包代理 (Crowdsourced Agents)。
+    - [ ] **调度请求表**：展示已分配的众包任务 (Assigned Tasks)。
+    - [ ] **成本对比看板**：展示传统物流 vs 众包物流的成本差异。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 众包物流调度 (Crowdsourced Logistics)             |
+    +-----------------------------------------------------------+
+    | [ 状态：已分配 (ASSIGNED) ]                               |
+    | 订单 ID: ORD-9012 | 城市: 伦敦 (London) | 代理: Agent-X  |
+    +-----------------------------------------------------------+
+    | 预估成本: £12.50 | 传统成本: £8.00 | 差额: +£4.50         |
+    +-----------------------------------------------------------+
+    | [ AGI 韧性建议 (Resilience Insight) ]                    |
+    | "传统物流商 (Royal Mail) 罢工，建议启用众包路由。       |
+    | 虽成本增加 £4.50，但可避免 5 天延误，保护 DSR 评分。"    |
+    +-----------------------------------------------------------+
+    | [ 取消调度 ]                      [ 确认派单并通知代理 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/logistics/crowdsourced/requests`
+- **关键字段映射**
+    - `agent_did` -> 代理 DID
+    - `city` -> 城市
+    - `estimated_cost` -> 预估成本
+- **状态流转**：
+    - 点击 [确认派单] -> 调用 `POST /api/v1/logistics/crowdsourced/approve` -> 状态变为 `IN_TRANSIT`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 众包代理状态的实时监控（Online/Offline）。
+- [ ] 众包派送费用的精准核算。
+- [ ] 集成众包 App 的推送通知。
--- a/docs/blueprints/frontend-integration/did-settlement.md
+++ b/docs/blueprints/frontend-integration/did-settlement.md
@@ -0,0 +1,49 @@
+# 前端集成蓝图：基于 DID 的自治清算协议 (DID Settlement)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_40 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动化处理品牌方、代运营与达人的三方自动分润，降低结算争议 95%，实现“无感清算”。
+- **关联后端 Service**：`DIDSettlementService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 自治清算管理
+- **展示组件**：
+    - [ ] **DID 合约看板**：展示各主体的 DID 身份与分成比例。
+    - [ ] **清算记录表**：展示每笔订单的清算状态与隐私存证证明。
+    - [ ] **分润热力图**：展示各主体的历史收益占比。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 自治清算管理 (DID-based Settlement)               |
+    +-----------------------------------------------------------+
+    | [ 当前合约状态：已激活 (ACTIVE) ]                         |
+    | - 品牌方 (Brand): 70% [DID: brand-001] [✅ Verified]      |
+    | - 代运营 (Ops):   20% [DID: ops-002]   [✅ Verified]      |
+    | - 达人 (KOL):     10% [DID: kol-003]   [✅ Verified]      |
+    +-----------------------------------------------------------+
+    | [ 最近清算记录 (Last 10 Settlements) ]                    |
+    | --------------------------------------------------------- |
+    | Order ID | Party | Amount | Status | ZKP Proof          |
+    | ORD-1234 | Brand | $140.0 | ✅ Done | [ View Proof ]     |
+    | ORD-1234 | Ops   | $40.0  | ✅ Done | [ View Proof ]     |
+    | ORD-1234 | KOL   | $20.0  | ✅ Done | [ View Proof ]     |
+    +-----------------------------------------------------------+
+    | [?] 审计备注：所有清算均通过 ZKP 存证，隐私且不可篡改。   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/settlement/did`
+- **关键字段映射**：
+    - `party_did` -> DID 标识
+    - `party_role` -> 角色
+    - `amount` -> 清算金额
+    - `proof_hash` -> ZKP 证明哈希
+- **状态流转**：
+    - 点击 [View Proof] -> 调用 `PrivateAuditService.verifyProof` -> 展示验证通过标识。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] DID 身份的实名/实体认证校验。
+- [ ] 大额清算的二次确认机制。
+- [ ] 导出加密格式的清算审计流水。
--- a/docs/blueprints/frontend-integration/dispute-arbitration-ui.md
+++ b/docs/blueprints/frontend-integration/dispute-arbitration-ui.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：智能争议仲裁建议 (Dispute Arbitration)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_CSM_30 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动化处理售后纠纷与退款争议，基于全链路证据链给出公正仲裁建议，降低客服工作量。
+- **关联后端 Service**：`DisputeArbitrationService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 客户成功 -> 争议仲裁工作台
+- **展示组件**：
+    - [ ] **争议详情卡片**：展示订单 ID、买家 DID、争议理由。
+    - [ ] **全链路证据链**：聚合订单、物流、支付的全量数据。
+    - [ ] **AGI 仲裁建议**：展示 `decision_suggested` 及 `causal_chain`。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 智能争议仲裁建议 (Dispute Arbitration)           |
+    +-----------------------------------------------------------+
+    | [ 状态：已建议 (SUGGESTED) ]                             |
+    | 订单 ID: ORD-1234 | 买家: DID-ABC | 争议理由: 未收到    |
+    +-----------------------------------------------------------+
+    | [ AGI 仲裁书 (Arbitration Opinion) ]                     |
+    | "建议决策：驳回退款 (REJECT_REFUND)。                   |
+    | 证据链：物流轨迹显示订单已于 2026-03-12 10:20 妥投，    |
+    | 买家主张“未收到”与证据不符。"                            |
+    +-----------------------------------------------------------+
+    | [ 人工介入 ]                      [ 一键执行仲裁决定 ]     |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/customer/arbitration`
+- **关键字段映射**
+    - `decision_suggested` -> 仲裁决策
+    - `causal_chain` -> 仲裁理由
+    - `status` -> 仲裁状态
+- **状态流转**：
+    - 点击 [执行仲裁决定] -> 调用 `POST /api/v1/customer/arbitration/approve` -> 更新订单退款状态。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 证据链中物流轨迹的完整性展示。
+- [ ] 退款金额的货币符号正确显示。
+- [ ] 导出加密且防篡改的仲裁报告 (ZKP)。
--- a/docs/blueprints/frontend-integration/dynamic-routing-failover.md
+++ b/docs/blueprints/frontend-integration/dynamic-routing-failover.md
@@ -0,0 +1,49 @@
+# 前端集成蓝图：全球动态路径对冲与风险熔断 (Global Route Failover)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_20 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：在黑天鹅事件发生时，自动切换最优路径并对冲物流成本上涨，保护时效。
+- **关联后端 Service**：`DynamicRoutingFailoverService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 路由与风险看板
+- **展示组件**：
+    - [ ] **全球物流热力图**：展示各港口/航线的健康度。
+    - [ ] **路径对比试图**：展示“当前路径” vs “最优建议路径”的时效与成本差异。
+    - [ ] **风险预警卡片**：展示各渠道的风险评分 (RiskScore)。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 物流路由与风险看板 (Route & Risk)                 |
+    +-----------------------------------------------------------+
+    | [ 当前健康度 (Global Health) ] [🟢 Healthy] [🟡 Congested]|
+    | - US-West (Sea): [🟡 拥堵中 (Level: 0.75)]                |
+    | - EU-Main (Air): [🟢 正常 (Level: 0.12)]                  |
+    +-----------------------------------------------------------+
+    | [ AGI 路由自愈建议 (Failover Suggestion) ]                |
+    | --------------------------------------------------------- |
+    | 建议：切换至 [US-East (Air Bypass)]                       |
+    | 时效：-48h (节省 2 天) | 成本：+$12.5/kg (建议成本对冲) |
+    | --------------------------------------------------------- |
+    | [?] 为何建议？                                            |
+    | "洛杉矶港口罢工导致延误 >15天，虽然空运成本高，但可保单。"|
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 一键切换并更新运费模板 ] |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/logistics/routing/optimal`
+- **关键字段映射**：
+    - `isFailoverTriggered` -> 是否触发自愈建议
+    - `riskLevel` -> 风险等级 (CRITICAL, WARNING, SAFE)
+    - `estimatedCost` -> 预估成本
+    - `estimatedLeadTime` -> 预估时效
+- **状态流转**：
+    - 点击 [一键切换] -> 调用 `POST /api/v1/logistics/routing/approve` -> 更新后端路由状态。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 航线健康数据的实时性校验（< 5 min 延迟）。
+- [ ] 成本对冲方案的详细财务核算展示。
+- [ ] 对接 Google Maps/Three.js 渲染 4D 轨迹。
--- a/docs/blueprints/frontend-integration/finance-recon.md
+++ b/docs/blueprints/frontend-integration/finance-recon.md
@@ -0,0 +1,30 @@
+# Frontend Integration: Finance Reconciliation (财务对账引擎)
+
+## 🎨 UI Layout Sketch
+- **Page Path**: `/erp/finance/reconciliation`
+- **Component Structure**:
+  - `ReconciliationSummary`: Top stats (Total Orders, Matched Count, Discrepancy Amount).
+  - `DiscrepancyCalendar`: Calendar view of discrepancy days.
+  - `ReconTable`: Detailed reconciliation list:
+    - Order ID & Status (Matched, Discrepancy).
+    - Expected Amount (from Order) vs Actual Amount (from Settlement).
+    - Gap ($ Delta).
+    - AI Reasoning (e.g., "Logistics Fee Overcharge", "Tax Miscalculation").
+  - `DetailDrilldown`: Click order to see `DecisionExplainabilityEngine` factors (Expected, Actual, Gap).
+  - `ResolutionCenter`: "Manual Adjust" or "Dispute with Platform" buttons.
+
+## 🔄 Interaction State Machine
+- `INITIAL`: Waiting for settlement data.
+- `RECONCILING`: `FinanceReconService` processing orders.
+- `MATCHED`: Amount aligns within threshold.
+- `DISCREPANCY`: Discrepancy detected, awaiting action.
+- `RESOLVED`: Discrepancy cleared (e.g., through adjustment or refund).
+
+## 🔗 API Mapping
+- `POST /api/v1/finance/reconciliation/run`: Triggers `FinanceReconService.performReconciliation`.
+- `GET /api/v1/finance/reconciliation/list`: Fetches `cf_finance_reconciliation` records.
+- `GET /api/v1/xai/narrative?resourceId={orderId}`: Fetches `DecisionExplainabilityEngine` logic.
+
+## 📈 ROI Visualization
+- "Recovered Funds" from disputes.
+- "Revenue Leakage" trend line.
--- a/docs/blueprints/frontend-integration/fraud-shared-ui.md
+++ b/docs/blueprints/frontend-integration/fraud-shared-ui.md
@@ -0,0 +1,41 @@
+# 前端集成蓝图：恶意买家跨租户黑名单共享 (Fraud Shared UI)
+
+> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_OPS_137 逻辑后产出，用于指导 Console 端全栈实现。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：跨租户识别高频退款、欺诈性索赔的恶意买家，提供基于共享数据的黑名单建议，降低多租户共同损失。
+- **关联后端 Service**：`FraudSharedService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 客户成功 -> 欺诈与风控 -> 黑名单建议
+- **展示组件**：
+    - [ ] **恶意买家卡片**：展示买家 Email/Phone。
+    - [ ] **威胁分级**：根据跨租户举报次数（如 3次以上）标注红色高危。
+    - [ ] **因果叙述区**：展示跨租户的具体举报原因和证据摘要。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 跨租户欺诈风险预警 (Fraud Intelligence)           |
+    +-----------------------------------------------------------+
+    | 买家: buyer@gmail.com | 举报次数: 3 | 威胁等级: 高危      |
+    +-----------------------------------------------------------+
+    | [?] 为何预警？ (Causal Chain)                             |
+    | "该买家在其他 3 个租户中存在多次'虚假单号'与'恶意索赔'记录" |
+    +-----------------------------------------------------------+
+    | [ 允许交易 (不拉黑) ]               [ 一键拉黑 (不再接单) ] |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/fraud/suggestions` (返回 `cf_blacklist_audit` 数据)
+- **关键字段映射**
+    - `buyer_email` -> 买家标识
+    - `anomaly_type` -> 异常类型 (e.g., CROSS_TENANT_FRAUD_HISTORY)
+    - `reason` -> 叙述文案
+- **状态流转**：
+    - 点击 [一键拉黑] -> `POST /api/v1/fraud/blacklist` -> 成功后自动拦截该买家的后续订单。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 数据脱敏：前端脱敏显示部分邮箱 (e.g., b***r@gmail.com)。
+- [ ] 按钮防误触：拉黑操作需二次确认。
+- [ ] 举报来源匿名化处理。
--- a/docs/blueprints/frontend-integration/fx-hedging-risk.md
+++ b/docs/blueprints/frontend-integration/fx-hedging-risk.md
@@ -0,0 +1,46 @@
+# 📋 前端实现方案：多币种自动锁汇避险 (FX Hedging)
+
+## 1. UI 布局草图 (UI Layout Sketch)
+
+```
+-------------------------------------------------------------------------+
+| [Breadcrumb: Console > Finance > FX Risk]                               |
+-------------------------------------------------------------------------+
+| [Currency Pair: USD/CNY] [Current Rate: 7.2450] [Volatility: 2.4%]      |
+-------------------------------------------------------------------------+
+| +-------------------------+ +-------------------------+ +-------------+ |
+| | 待结汇金额 (Receivable) | | 预估汇损风险 (Risk)     | | 建议操作    | |
+| | $250,000.00             | | -$1,250.00              | | [立即锁汇]  | |
+| +-------------------------+ +-------------------------+ +-------------+ |
+-------------------------------------------------------------------------+
+| [汇率趋势与风险等级 (FX Trend & Risk Level)]                              |
+| [Chart: 过去30天汇率波动曲线]                                             |
+| > 风险等级: [MEDIUM] (波动率超过 2%)                                      |
+-------------------------------------------------------------------------+
+| [锁汇建议详情 (Hedging Advice)]                                          |
+| > AI 建议锁定 50% 的待结汇款项以对冲近期人民币升值风险。                     |
+| [输入框: 锁汇比例 [%]] [按钮: 发起锁汇请求 (Execute Hedge)]                 |
+-------------------------------------------------------------------------+
+```
+
+## 2.交互状态机 (Interaction FSM)
+
+- **IDLE**: 页面初始加载。
+- **AUDITING**: 调用 `/api/finance/fx/audit/:pair` 分析风险。
+- **RECOMMENDING**: 渲染避险建议与操作按钮。
+- **EXECUTING**: 点击“发起锁汇”，调用 `MultiAssetSettlementService.lockExchangeRate`。
+- **VERIFIED**: 锁汇指令已发送至银行/支付网关，进入 PENDING_REVIEW。
+
+## 3. 核心 API 字段映射 (API Field Mapping)
+
+| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) |
+| :--- | :--- | :--- |
+| 当前汇率 | `latestRate` | 实时同步的中间价 |
+| 波动率 | `volatility` | 过去30天的标准差波动 |
+| 风险级别 | `riskLevel` | LOW/MEDIUM/CRITICAL |
+| 建议动作 | `suggestion` | 具体的避险操作叙述 |
+
+## 4. ROI 可视化逻辑 (ROI Visualization)
+
+- **风险热力**: 波动率 > 5% 触发红色闪烁告警。
+- **损耗模拟**: 自动计算“若不锁汇且汇率变动 1%，预计损耗金额”。
--- a/docs/blueprints/frontend-integration/global-dispute-router-ui.md
+++ b/docs/blueprints/frontend-integration/global-dispute-router-ui.md
@@ -0,0 +1,48 @@
+# 前端集成蓝图：跨节点争议自动仲裁转发 (Global Dispute Router)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 SOV_NET_04 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：在多节点贸易中，实现证据链的自动化路由与转发，支持跨节点的 AGI 联合仲裁，提升争议处理透明度。
+- **关联后端 Service**：`GlobalDisputeRouter.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 客户成功 -> 全球争议工作台
+- **展示组件**：
+    - [ ] **争议路由地图**：展示争议案件在不同主权节点间的流转路径。
+    - [ ] **联合证据链试图**：聚合来自不同 Hub 节点的原始证据。
+    - [ ] **跨节点仲裁共识建议**：展示各节点 AGI 的仲裁意见汇总。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 全球争议路由与仲裁 (Global Dispute Router)       |
+    +-----------------------------------------------------------+
+    | [ 争议 ID: ARB-1122 ] [ 状态: 路由中 (ROUTED) ]           |
+    +-----------------------------------------------------------+
+    | 发起节点: Hub-CN | 当前处理节点: Hub-DE | 待确认节点: Hub-UK |
+    +-----------------------------------------------------------+
+    | [ 跨节点共识 (Consensus) ]                                |
+    | - Hub-CN: [✅ 建议退款] "物流延误证明有效"                |
+    | - Hub-DE: [⏳ 仲裁中] 正在核实海外仓签收单                |
+    +-----------------------------------------------------------+
+    | [ AGI 路由建议 ]                                          |
+    | "该争议涉及跨国清算，建议将物流签收证据转发至目的国节点 |
+    | 以触发联合仲裁。转发成功率预估：98%。"                  |
+    +-----------------------------------------------------------+
+    | [ 强制终止 ]                      [ 一键转发证据链 ]       |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/customer/dispute/router/status`
+- **关键字段映射**
+    - `source_node_id` -> 来源节点
+    - `target_node_id` -> 目标节点
+    - `arbitration_result` -> 仲裁意见汇总
+- **状态流转**：
+    - 发起路由 -> `ROUTED` -> 节点 AGI 介入 -> `ARBITRATING` -> 达成共识 -> `RESOLVED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 跨节点证据同步的一致性校验 (ZKP)。
+- [ ] 不同国家/地区仲裁法规的合规性提示。
+- [ ] 导出加密格式的跨节点仲裁决定书。
--- a/docs/blueprints/frontend-integration/green-supply-chain-ui.md
+++ b/docs/blueprints/frontend-integration/green-supply-chain-ui.md
@@ -0,0 +1,46 @@
+# 前端集成蓝图：绿色供应链碳足迹核算与抵扣 (Green Supply Chain)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_40 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动计算订单与商品的碳排放，提供减排建议并建议购买碳抵扣额度，提升品牌绿色竞争力。
+- **关联后端 Service**：`GreenSupplyChainService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 绿色供应链
+- **展示组件**：
+    - [ ] **碳足迹仪表盘**：展示累计碳排放与抵消额度。
+    - [ ] **订单碳足迹记录**：展示每笔订单的碳排放明细 (Logistics, Production, Packaging)。
+    - [ ] **减排建议卡片**：展示减排策略 (Strategy, Reduction, Cost)。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 绿色供应链碳足迹 (Green Supply Chain)             |
+    +-----------------------------------------------------------+
+    | [ 累计碳排放: 1,500 kg CO2 ] [ 抵消金额: $37.50 ]          |
+    +-----------------------------------------------------------+
+    | [ 订单 ID: ORD-1122 ] [ 碳足迹: 25.50 kg CO2 ]            |
+    | --------------------------------------------------------- |
+    | 物流: 15.00 kg | 生产: 10.00 kg | 包装: 0.50 kg          |
+    +-----------------------------------------------------------+
+    | [ AGI 减排建议 (Green Insight) ]                          |
+    | "建议：将空运转为海运 (LCL)，预估可减少 75% 碳排放。    |
+    | 相比空运节省成本：$200。时效增加：10 天。"               |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 购买碳抵扣额度 ]       |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/green/footprint?order_id=ORD-1122`
+- **关键字段映射**
+    - `total_co2` -> 累计碳排放
+    - `offset_cost` -> 抵扣金额
+    - `status` -> 状态 (ESTIMATED, OFFSET_COMPLETED, etc.)
+- **状态流转**：
+    - 点击 [购买碳抵扣额度] -> 调用 `GreenSupplyChainService.recordFootprint` -> 更新 `status` 为 `OFFSET_COMPLETED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 碳足迹计算模型的参数可配置界面。
+- [ ] 碳中和路径的长期跟踪看板。
+- [ ] 导出包含详细证据链的绿色供应链报告。
--- a/docs/blueprints/frontend-integration/intermodal-failover-ui.md
+++ b/docs/blueprints/frontend-integration/intermodal-failover-ui.md
@@ -0,0 +1,49 @@
+# 前端集成蓝图：弹性多式联运自动对冲引擎 (Intermodal Failover)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_LOG_50 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：当全球主航道发生黑天鹅事件时，自动计算并执行多式联运切换（如海转铁），最小化时效延误。
+- **关联后端 Service**：`IntermodalFailoverService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 履约中心 -> 多式联运调度
+- **展示组件**：
+    - [ ] **全球航道监控图**：展示苏伊士运河、巴拿马运河等关键航道的实时拥堵度。
+    - [ ] **多式联运切换建议列表**：展示 AGI 生成的 Failover 建议（SEA_TO_RAIL, SEA_TO_AIR）。
+    - [ ] **时效-成本平衡图**：对比原始海运路径与多式联运路径的时效提升与成本增加。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 多式联运自愈看板 (Intermodal Failover)           |
+    +-----------------------------------------------------------+
+    | [ 原始路径: 苏伊士运河 (Sea) ] [ 状态: 严重堵塞 (BLOCKED) ] |
+    +-----------------------------------------------------------+
+    | 目的地: 伦敦 (London) | 预估延误: 25 天                    |
+    +-----------------------------------------------------------+
+    | [ AGI 路由自愈建议 (Failover Suggestion) ]                |
+    | --------------------------------------------------------- |
+    | 建议：切换至 [中欧班列 (Sea-to-Rail)]                     |
+    | 时效：-10 天 (缩短 10 天) | 成本：+$5.2/kg (建议对冲)     |
+    | --------------------------------------------------------- |
+    | [?] 为何建议？                                            |
+    | "苏伊士运河发生长达 15 天的严重拥堵，海转铁成本仅增加 |
+    | $5.2/kg，但可避免 10 天以上的订单违约风险。"            |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 确认切换并对冲运费 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/logistics/failover/calculate?original_route_id=SEA-001`
+- **关键字段映射**
+    - `method` -> 切换方法 (SEA_TO_RAIL, etc.)
+    - `estimated_cost` -> 预估切换成本
+    - `timeframe_days` -> 预估时效
+- **状态流转**：
+    - 切换发现风险 -> 调用 `IntermodalFailoverService.calculateFailover` -> 重新渲染成本对比图。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 实时获取全球航道拥堵数据。
+- [ ] 支持针对大批量订单的一键批量切换。
+- [ ] 导出包含多式联运切换路径的物流报告。
--- a/docs/blueprints/frontend-integration/inventory-aging-ui.md
+++ b/docs/blueprints/frontend-integration/inventory-aging-ui.md
@@ -0,0 +1,51 @@
+# 前端集成方案：海外仓库龄过长清仓建议 (Aging Inventory) - [BIZ_OPS_156]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：识别在海外仓积压超过 90 天的“死货”，通过自动化的打折、清仓建议释放资金流，降低仓储成本。
+- **用户收益**：提升库存周转率，减少坏账计提，实时掌握全球各仓的资金沉淀情况。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **顶部看板 (Aging KPIs)**:
+  - `Dead Stock Value`: 积压超过 90 天的库存总价值（美元）。
+  - `Avg Inventory Age`: 全球平均库龄。
+  - `Potential Cash Release`: 预计通过清仓可释放的现金总额。
+- **中部：库龄分布直方图 (Aging Distribution Chart)**:
+  - X 轴：库龄区间（0-30, 31-60, 61-90, 90+ 天）。
+  - Y 轴：SKU 数量或库存金额。
+- **底部：积压 SKU 清单 (Aging SKU List)**:
+  - 表格列：SKU ID、仓库、库龄（天）、库存价值、建议操作（`DISCOUNT`, `CLEARANCE`, `LIQUIDATE`）。
+  - 操作项：`Apply Discount`（一键同步到多平台改价）、`View Causal Chain`（查看 AI 清仓理由）。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `InventoryAgingService.analyzeAging(tenantId)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "data": [
+      {
+        "skuId": "SKU-9981",
+        "warehouseId": "US-WEST-01",
+        "agingDays": 125,
+        "stockValue": 5200.50,
+        "suggestedAction": "CLEARANCE"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 提示词：`DecisionExplainabilityEngine.getDecisionNarrative`
+  - 示例：“该 SKU 已在美西仓积压 125 天，且过去 30 天零动销，资金沉淀 $5200.50，建议执行 5 折清仓以释放库位。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **Init**: 加载时按仓库维度聚合库龄。
+- **Filter**: 支持按仓库、价格区间、类目筛选。
+- **Bulk Action**: 勾选多个 SKU 批量执行 `Batch Approve Suggestions`。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **资产释放率**: 清仓完成后展示回笼资金量。
+- **仓储费节省**: 预计可节省的月度仓储费用（基于库位占用率）。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_156](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md
+++ b/docs/blueprints/frontend-integration/inventory-forecast-replenishment.md
@@ -0,0 +1,48 @@
+# 📋 前端实现方案：AGI 销量预测与智能补货 (Inventory Forecast)
+
+## 1. UI 布局草图 (UI Layout Sketch)
+
+```
+-------------------------------------------------------------------------+
+| [Breadcrumb: Console > Inventory > Smart Replenish]                     |
+-------------------------------------------------------------------------+
+| [Search SKU: [__________]] [Filter: Low Stock Only [x]]                 |
+-------------------------------------------------------------------------+
+| +---------------------------------------------------------------------+ |
+| | SKU: SKU-9988 (Handheld Blender)                                    | |
+| |---------------------------------------------------------------------| |
+| | [当前库存: 45 PCS] [7天日均销量: 12.5 PCS] [预计可用天数: 3.6 Days]     | |
+| |---------------------------------------------------------------------| |
+| | [销量预测 (7 Days Forecast)]                                         | |
+| | [Chart: 历史销量(蓝线) vs AI 预测销量(绿虚线)]                         | |
+| |---------------------------------------------------------------------| |
+| | [AI 补货建议 (Replenishment Advice)]                                 | |
+| | > 建议立即补货: 200 PCS                                              | |
+| | > 理由: 销售速率增长 20%，当前库存无法支撑至下次补货到货 (Lead time: 7d) | |
+| | [按钮: 生成采购单 (Create PO)] [按钮: 忽略建议 (Ignore)]               | |
+| +---------------------------------------------------------------------+ |
+-------------------------------------------------------------------------+
+```
+
+## 2. 交互状态机 (Interaction FSM)
+
+- **IDLE**: 展示待补货列表。
+- **PREDICTING**: 点击“刷新预测”按钮，调用 `/api/trade/inventory/forecast/:skuId`。
+- **ADVISING**: 渲染 AI 建议与 PO 预填单。
+- **EXECUTING**: 点击“生成采购单”，调用 `TradeService.createPurchaseOrder`，按钮进入 Loading。
+- **COMPLETED**: 采购单生成成功，自动跳转至 PO 详情页。
+
+## 3. 核心 API 字段映射 (API Field Mapping)
+
+| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) |
+| :--- | :--- | :--- |
+| 7天日均销量 | `avgDailySales7d` | 最近一周的真实动销速率 |
+| AI 预测总量 | `forecastNext7d` | 未来一周的预测销量 |
+| 信心指数 | `confidenceScore` | AI 对预测结果的把握度 (0-1) |
+| 建议补货量 | `policy.orderQuantity` | 来自 RL 算法的最优订单量 |
+| 补货触发点 | `policy.reorderPoint` | 当库存低于此值时建议补货 |
+
+## 4. ROI 可视化逻辑 (ROI Visualization)
+
+- **缺货风险分值**: 红色 (Risk > 80) / 橙色 (Risk > 50) / 绿色 (Safe)。
+- **补货 ROI 预估**: 联动 `InventoryRLService` 展示“补货后预计挽回的缺货损失” vs “仓储成本增加额”。
--- a/docs/blueprints/frontend-integration/logistics-health-ui.md
+++ b/docs/blueprints/frontend-integration/logistics-health-ui.md
@@ -0,0 +1,58 @@
+# 前端集成方案：物流渠道稳定性实时热力分析 (Logistics Health) - [BIZ_OPS_155]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：为运营人员提供全球物流渠道的实时健康度监控，识别哪些承运商正在经历严重的延迟或异常，从而及时调整发货策略。
+- **用户收益**：降低物流纠纷率，提升买家时效体验，量化物流服务商（3PL）的表现。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **顶部概览 (Stats Overview)**:
+  - `Total Active Carriers`: 正在使用的承运商总数。
+  - `Global Avg Delivery Time`: 全球平均签收时效（天）。
+  - `Critical Channels`: 处于异常状态的渠道数量（高亮红色）。
+- **中间：实时热力图 (Logistics Heatmap)**:
+  - 利用 `Three.js` 或 `ECharts-GL` 展示全球包裹流动线路。
+  - 线路颜色：绿色（正常）、黄色（延迟）、红色（高异常/拥堵）。
+- **底部：承运商明细列表 (Carrier Detail List)**:
+  - 表格列：承运商名称、平均时效、异常率、稳定性评分 (0-100)、当前状态。
+  - 操作项：`Reroute Strategy`（建议切换路由）、`View RCA`（查看 AI 根因分析）。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `ChannelStatusService.analyzeChannels(tenantId)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "data": [
+      {
+        "carrier": "FedEx",
+        "avgDeliveryTime": 5.2,
+        "exceptionRate": 0.015,
+        "stabilityScore": 88,
+        "status": "HEALTHY"
+      },
+      {
+        "carrier": "USPS",
+        "avgDeliveryTime": 12.4,
+        "exceptionRate": 0.085,
+        "stabilityScore": 42,
+        "status": "CRITICAL"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 悬浮展示 `DecisionExplainabilityEngine.getDecisionNarrative` 产出的叙述。
+  - 示例：“USPS 渠道稳定性评分仅为 42，主因是异常率 (8.5%) 远超基准 (2.0%)，建议切换至 FedEx。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **Init**: 进入页面自动调用 `analyzeChannels`。
+- **Loading**: 展示骨架屏（Skeleton Screen）模拟全球包裹流动。
+- **Failover Action**: 点击 `Reroute` 按钮弹出二次确认框，联动 `POST /api/v1/suggestions/batch-approve` 执行策略变更。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **对比指标**: 展示切换前后的平均时效提升值（$ \Delta Time $）与 纠纷减少量（$ \Delta Dispute $）。
+- **经济收益**: 计算因降低纠纷而节省的退款总额（$ \Delta Refund $）。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_155](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/membership-ltv-ui.md
+++ b/docs/blueprints/frontend-integration/membership-ltv-ui.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：基于 LTV 预测的自动化会员治理 (LTV Membership)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_MKT_60 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：根据 AGI 预测的客户长期价值 (LTV)，自动晋升等级并解锁对应权益，提升高价值客户粘性。
+- **关联后端 Service**：`MembershipLTVService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 客户成功 -> 会员等级管理
+- **展示组件**：
+    - [ ] **客户 LTV 分布图**：展示不同等级客户的预测 LTV 分布。
+    - [ ] **晋升记录流**：展示最近自动晋升的客户及其预测理由。
+    - [ ] **等级权益看板**：展示 BRONZE, SILVER, GOLD, PLATINUM 对应的权益。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 自动化会员等级管理 (LTV Membership)               |
+    +-----------------------------------------------------------+
+    | [ 客户 DID: DID-7890 ] [ 当前等级: GOLD ] [ 预测 LTV: $2,500 ] |
+    +-----------------------------------------------------------+
+    | 历史消费: $1,200 | 订单数: 15 | AGI 预测理由: "高复购潜力"    |
+    +-----------------------------------------------------------+
+    | [ AGI 权益建议 (Tier Benefits) ]                          |
+    | "该客户已自动晋升至 GOLD 等级。已解锁：专属客服、         |
+    | 满 $100 减 $20 优惠券、新品优先抢购权。"                  |
+    +-----------------------------------------------------------+
+    | [ 撤销晋升 ]                      [ 发送晋升通知给客户 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/marketing/membership/evaluate?did=DID-7890`
+- **关键字段映射**
+    - `predicted_ltv` -> 预测 LTV
+    - `tier` -> 建议等级
+    - `historical_spend` -> 历史消费额
+- **状态流转**：
+    - 系统定时任务 -> 调用 `MembershipLTVService.evaluateTier` -> 更新 UI 中的等级状态。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] LTV 预测模型的参数可配置界面。
+- [ ] 等级晋升的消息推送模板配置。
+- [ ] 导出包含 LTV 预测报告的客户名单。
--- a/docs/blueprints/frontend-integration/multi-currency-recon.md
+++ b/docs/blueprints/frontend-integration/multi-currency-recon.md
@@ -0,0 +1,45 @@
+# 前端集成蓝图：跨主权多币种对冲对账引擎 (Multi-Currency Recon)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_50 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动化处理汇率波动导致的对账偏差，保护商户资金主权，减少财务核对成本。
+- **关联后端 Service**：`MultiCurrencyHedgingReconService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 多币种对账
+- **展示组件**：
+    - [ ] **汇率波动看板**：展示下单汇率 vs 结算汇率。
+    - [ ] **对账偏差列表**：高亮显示 `fx_drift` 超过阈值的订单。
+    - [ ] **对冲建议卡片**：展示建议的对冲动作（如：锁定汇率）。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 多币种对冲对账 (Multi-Currency Recon)             |
+    +-----------------------------------------------------------+
+    | [ 状态：发现异常 (DISCREPANCY) ]                           |
+    | 订单 ID: ORD-5678 | 订单金额: €1,000 | 汇损: -$45.20      |
+    +-----------------------------------------------------------+
+    | 下单汇率: 1 USD = 0.92 EUR | 当前汇率: 1 USD = 0.88 EUR      |
+    +-----------------------------------------------------------+
+    | [ AGI 对冲建议 (Hedging Advice) ]                         |
+    | "监测到欧元大幅贬值，建议对未来 7 天的欧元结算订单执行 |
+    | 锁汇操作，预估可挽回损失：$320.00。"                     |
+    +-----------------------------------------------------------+
+    | [ 忽略 ]                      [ 一键执行锁汇对冲 ]         |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/recon/fx`
+- **关键字段映射**
+    - `fx_drift` -> 汇损金额
+    - `order_rate` -> 下单汇率
+    - `current_rate` -> 当前汇率
+- **状态流转**：
+    - 点击 [执行对冲] -> 调用 `POST /api/v1/finance/hedging/approve` -> 状态变为 `HEDGED`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 汇率数据的实时刷新（< 1 min）。
+- [ ] 汇损金额的货币格式化校验。
+- [ ] 导出包含汇率路径的对账明细。
--- a/docs/blueprints/frontend-integration/multi-touch-attribution.md
+++ b/docs/blueprints/frontend-integration/multi-touch-attribution.md
@@ -0,0 +1,46 @@
+# 前端集成蓝图：多触点归因与利润分析 (Multi-Touch Attribution)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_MKT_40 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：识破平台广告的虚假繁荣，还原真实的流量贡献度，优化营销预算分配。
+- **关联后端 Service**：`MultiTouchAttributionService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 营销中心 -> 流量归因分析
+- **展示组件**：
+    - [ ] **归因模型切换器**：支持 FIRST_CLICK, LAST_CLICK, LINEAR, TIME_DECAY。
+    - [ ] **渠道贡献饼图**：展示各 Source/Campaign 的成交金额占比。
+    - [ ] **LTV/CAC 趋势图**：对比各渠道的获客成本与长期价值。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 流量归因分析 (Multi-Touch Attribution)           |
+    +-----------------------------------------------------------+
+    | 当前模型：[ 线性归因 (LINEAR) ▼ ] | 时间范围：[ 过去 30 天 ▼ ] |
+    +-----------------------------------------------------------+
+    | [ 渠道贡献度 (Revenue Contribution) ]                     |
+    | - Google Ads: 45% ($12,000) [==========----------]       |
+    | - Facebook:   30% ($8,000)  [=======------------]       |
+    | - TikTok:     15% ($4,000)  [===----------------]       |
+    | - Organic:    10% ($2,600)  [==-----------------]       |
+    +-----------------------------------------------------------+
+    | [?] AGI 深度洞察：                                        |
+    | "TikTok 渠道虽然 LAST_CLICK 转化低，但在 FIRST_CLICK 模型 |
+    | 下贡献了 40% 的初始流量，建议保持品牌曝光预算。"          |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/marketing/attribution?model=LINEAR`
+- **关键字段映射**：
+    - `source` -> 流量来源
+    - `weight` -> 贡献权重
+    - `attributed_value` -> 归因成交额
+- **状态流转**：
+    - 切换模型 -> 发起 API 请求 -> 重新渲染图表。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 支持大数量级日志的异步聚合加载。
+- [ ] 归因模型参数配置的持久化存储。
+- [ ] 导出 PDF 格式的归因分析报告。
--- a/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md
+++ b/docs/blueprints/frontend-integration/node-liquidity-forecast-ui.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：跨主权多节点资金流动性自动预测 (Liquidity Forecast)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_90 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：预测全球贸易 Hub 节点的资金缺口，自动建议跨节点资金调拨，确保全球清算网络的高效运行。
+- **关联后端 Service**：`NodeLiquidityForecastService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 节点流动性看板
+- **展示组件**：
+    - [ ] **全球节点流动性热力图**：展示各 Hub 节点的资金盈余/缺口状态。
+    - [ ] **资金流入/流出趋势图**：展示特定节点的预测资金流向。
+    - [ ] **头寸调拨建议列表**：展示 AGI 生成的资金重平衡建议。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 节点流动性自动预测 (Liquidity Forecast)           |
+    +-----------------------------------------------------------+
+    | [ 节点: Hub-EU-01 ] [ 状态: 预警 (TIGHT) ] [ 缺口: $12,500 ] |
+    +-----------------------------------------------------------+
+    | 预计流入: $45,000 | 预计流出: $57,500 | 风险等级: 中高 (TIGHT) |
+    +-----------------------------------------------------------+
+    | [ AGI 调拨建议 (Rebalancing Advice) ]                     |
+    | "监测到 Hub-EU-01 明日清算量激增，建议从 Hub-CN-01 调拨 |
+    | $15,000 以对冲流动性风险。手续费预估：$12.00。"          |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 一键发起节点间调拨 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/liquidity/forecast?node_id=Hub-EU-01`
+- **关键字段映射**
+    - `net_liquidity` -> 净头寸
+    - `risk_level` -> 风险等级
+    - `estimated_inflow` -> 预计流入
+- **状态流转**：
+    - 风险发现 -> 调用 `NodeLiquidityForecastService.forecastNodeLiquidity` -> 触发预警。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 跨节点资金到账的实时追踪。
+- [ ] 调拨费用的动态核算。
+- [ ] 导出包含流动性分析的全球财务月报。
--- a/docs/blueprints/frontend-integration/node-resource-quota-ui.md
+++ b/docs/blueprints/frontend-integration/node-resource-quota-ui.md
@@ -0,0 +1,51 @@
+# 前端集成蓝图：跨节点资源共享配额管理 (Resource Quota)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_SOV_14 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：实现全球 Hub 节点间的资源弹性共享，基于声誉分数动态分配算力与存储配额，确保高信用节点在资源紧张时拥有优先权。
+- **关联后端 Service**：`NodeResourceQuotaService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 节点治理 -> 资源共享配额
+- **展示组件**：
+    - [ ] **配额使用进度条**：展示当前算力、存储的已用配额与总配额。
+    - [ ] **配额分配记录表**：展示最近由于声誉变化导致的配额调整历史。
+    - [ ] **跨节点任务监控**：展示当前正在借用其它节点算力执行的任务。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 跨节点资源配额 (Resource Quota)                   |
+    +-----------------------------------------------------------+
+    | [ 当前声誉: 92.5 ] [ 配额状态: 充足 ]                     |
+    +-----------------------------------------------------------+
+    | 算力配额 (Compute): [==========----------] 450/925 Units  |
+    | 存储配额 (Storage): [=====---------------] 2.1/9.2 GB     |
+    +-----------------------------------------------------------+
+    | [ 配额调整日志 ]                                          |
+    | --------------------------------------------------------- |
+    | 时间       | 事件           | 算力变更 | 存储变更         |
+    | 2026-03-14 | 声誉更新(+5)   | +50      | +500 MB          |
+    | 2026-03-01 | 系统例行分配   | 875      | 8.7 GB           |
+    +-----------------------------------------------------------+
+    | [ AGI 资源建议 ]                                          |
+    | "您的存储配额利用率较低，建议质押部分存储资源给 Hub-DE-01 |
+    | 以赚取额外的声誉分。"                                    |
+    +-----------------------------------------------------------+
+    | [ 申请临时扩容 ]                  [ 资源外借设置 ]         |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/governance/resource/quota?node_id=Node-Alpha`
+- **关键字段映射**：
+    - `compute_quota` -> 总算力配额
+    - `storage_quota` -> 总存储配额
+    - `reputation_score` -> 关联声誉分
+- **状态流转**：
+    - 声誉变动 -> 调用 `NodeResourceQuotaService.allocateQuota` -> 数据库更新 -> UI 重新渲染。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 算力与存储配额消耗的准实时性核对（误差 < 1%）。
+- [ ] 临时配额申请的自动化审批工作流。
+- [ ] 导出包含跨节点资源贡献的年度技术审计报告。
--- a/docs/blueprints/frontend-integration/oms-workbench.md
+++ b/docs/blueprints/frontend-integration/oms-workbench.md
@@ -0,0 +1,32 @@
+# Frontend Integration: OMS Workbench (统一订单工作台)
+
+## 🎨 UI Layout Sketch
+- **Page Path**: `/erp/oms/workbench`
+- **Component Structure**:
+  - `OrderStats`: Top metrics (Total Orders, Pending Audit, Waiting Shipment, Exceptions).
+  - `OrderFilter`: Multi-dimensional filtering (Platform, Site, Status, Date, Amount, Customer).
+  - `OrderTable`: Detailed list of orders with:
+    - Status badges (e.g., `PENDING_AUDIT` in orange, `WAITING_SHIPMENT` in blue).
+    - Platform/Site icons.
+    - Items summary.
+    - Total Amount & Currency.
+    - Action column: "Audit", "Ship", "Mark Exception", "Reroute".
+  - `BatchActionPanel`: "Batch Audit", "Batch Ship", "Batch Export".
+  - `OrderDetailDrawer`: Full details on click, including Health Check results and Auto-Heal logs.
+
+## 🔄 Interaction State Machine
+- `INITIAL`: Fetching multi-platform orders.
+- `FILTERING`: User applying criteria.
+- `AUDITING`: `ConsumerOrderService.batchAudit` processing.
+- `SHIPPING`: `ConsumerOrderService.batchShip` processing.
+- `EXCEPTION_HANDLING`: User resolving exception reason.
+
+## 🔗 API Mapping
+- `GET /api/v1/orders/list`: Fetches `cf_consumer_orders`.
+- `POST /api/v1/orders/batch-audit`: Triggers `ConsumerOrderService.batchAudit`.
+- `POST /api/v1/orders/batch-ship`: Triggers `ConsumerOrderService.batchShip`.
+- `POST /api/v1/orders/reroute`: Triggers `ConsumerOrderService.autoReroute`.
+
+## 📈 ROI Visualization
+- "OMS Efficiency": Orders processed per minute compared to manual.
+- "Error Reduction": Exception rate before and after AI Health Check.
--- a/docs/blueprints/frontend-integration/order-profit-analysis.md
+++ b/docs/blueprints/frontend-integration/order-profit-analysis.md
@@ -0,0 +1,54 @@
+# 📋 前端实现方案：订单级 P&L 穿透分析 (Order P&L Analysis)
+
+## 1. UI 布局草图 (UI Layout Sketch)
+
+```
+-------------------------------------------------------------------------+
+| [Breadcrumb: Console > Finance > Order Analysis]                        |
+-------------------------------------------------------------------------+
+| [Order ID: #ORD-12345] [Status: Delivered] [Platform: Amazon US]        |
+-------------------------------------------------------------------------+
+| +-------------------------+ +-------------------------+ +-------------+ |
+| | 营收 (Revenue)          | | 基础净利 (Base Profit)  | | 真实毛利 (ROI) | |
+| | $120.00                 | | $35.50                  | | 24.5%       | |
+| +-------------------------+ +-------------------------+ +-------------+ |
+-------------------------------------------------------------------------+
+| [穿透式成本拆解 (Deep Cost Breakdown)]                                    |
+| +---------------------------------------------------------------------+ |
+| | 项 (Item)               | 金额 (Amount) | 备注 (Note)               | |
+| |-------------------------|---------------|---------------------------| |
+| | 商品成本 (COGS)         | -$40.00       | 采购价 + 运费              | |
+| | 平台佣金 (Fee)          | -$18.00       | Amazon Referral Fee (15%) | |
+| | 物流费用 (Logistics)    | -$25.00       | Last-mile delivery        | |
+| | 隐形成本 (Hidden Cost)  | -$1.50        | [ERP/工具费摊销] (Amortized)| |
+| | 汇损/手续费 (FX/Bank)   | -$0.50        | 提现损耗                  | |
+| |-------------------------|---------------|---------------------------| |
+| | 最终真实净利 (Net)      | $35.00        | 剔除所有隐形成本           | |
+| +---------------------------------------------------------------------+ |
+-------------------------------------------------------------------------+
+| [AI 建议 (AI Insights)]                                                 |
+| > 该订单隐形成本占比 1.25%，处于健康范围。建议保持当前物流路径。             |
+-------------------------------------------------------------------------+
+```
+
+## 2. 交互状态机 (Interaction FSM)
+
+- **IDLE**: 页面初始加载。
+- **LOADING**: 调用 `/api/finance/order-profit/:orderId` 获取穿透数据。
+- **SUCCESS**: 渲染仪表盘与成本表格。
+- **ERROR**: 弹出错误提示，支持“重试”按钮。
+
+## 3. 核心 API 字段映射 (API Field Mapping)
+
+| 前端字段 (Frontend) | 后端 API 字段 (Backend) | 说明 (Description) |
+| :--- | :--- | :--- |
+| 营收 | `platformAmount` | 订单总金额 |
+| 基础净利 | `baseNetProfit` | 未剔除摊销前的利润 |
+| 隐形成本 | `hiddenCost` | ERP/工具费等分摊成本 |
+| 真实净利 | `realNetProfit` | 最终到手利润 |
+| 真实毛利率 | `realMargin` | `realNetProfit / platformAmount` |
+
+## 4. ROI 可视化逻辑 (ROI Visualization)
+
+- **进度条**: 使用颜色渐变 (Red < 10% < Yellow < 20% < Green) 展示毛利率。
+- **因果叙述**: 联动 `DecisionExplainabilityEngine` 展示隐形成本的计算依据（如：本月总工具费 $500 / 总订单 5000 = $0.1/单）。
--- a/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md
+++ b/docs/blueprints/frontend-integration/platform-fee-watcher-ui.md
@@ -0,0 +1,47 @@
+# 前端集成方案：多平台佣金比例变动自动抓取建议 (Platform Fees) - [BIZ_OPS_158]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：当电商平台（如 Amazon）调整佣金比例时，系统自动捕捉变化并评估其对商户利润的影响，提供精准的调价建议。
+- **用户收益**：防止利润被无声侵蚀，确保每一笔交易都符合利润红线（B2C > 20%），自动化处理复杂的成本核算。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **费用变动看板 (Fee Event Feed)**:
+  - 列表展示：平台、品类、旧费率、新费率、生效日期。
+  - 状态：`AUDITED`（已评估）、`ACTION_REQUIRED`（需要调价）。
+- **利润侵蚀模拟器 (Margin Erosion Simulator)**:
+  - 展示受影响 SKU 的利润率跌幅。
+  - 对比图：调价前利润 vs 调价后利润。
+- **调价建议表 (Adjustment Suggestions)**:
+  - 表格列：SKU、当前售价、建议新售价、预估利润率。
+  - 操作：`Batch Update Prices`（一键同步到各平台）。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `PlatformFeeWatcher.auditFeeChanges(tenantId, updates)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "suggestions": [
+      {
+        "productId": "SKU-AMZ-001",
+        "advice": "Amazon 佣金上调 1%，预计毛利降至 19.5%（跌破红线）。建议调价至 $59.99。"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 浮窗展示：`DecisionExplainabilityEngine.getDecisionNarrative`
+  - 叙述：“根据 V30.0 利润保护协议，B2C 利润率必须 > 20%。由于佣金上涨导致原 20.5% 的利润跌至 19.5%，系统自动生成保单建议。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **New Event**: 系统捕获到费率变动，图标闪烁预警。
+- **Review**: 用户进入详情，查看受影响 SKU 列表。
+- **Commit**: 点击“执行调价”，联动 `DynamicPricingService` 发起远程平台 API 调用。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **利润挽回值**: 计算执行调价建议后，相比“不调价”挽回的净利润（$ Recovered Profit $）。
+- **合规达标率**: 展示租户下所有 SKU 符合利润红线的比例。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_158](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/private-lc-ui.md
+++ b/docs/blueprints/frontend-integration/private-lc-ui.md
@@ -0,0 +1,47 @@
+# 前端集成蓝图：基于 ZKP 的链上隐私信用证 (Private L/C)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_70 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：利用 ZKP 保护商业机密（如供应商 ID、具体利润），同时向金融机构证明交易真实性以换取信贷。
+- **关联后端 Service**：`SovereignPrivateLCService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 隐私信用证管理
+- **展示组件**：
+    - [ ] **信用证看板**：展示信用证合约列表 (ID, Amount, Status, Expiry)。
+    - [ ] **ZKP 证明验证卡**：展示隐私存证证明的哈希与验证状态。
+    - [ ] **交易流转追踪**：展示信用证的签发、议付、承付全过程。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 隐私信用证管理 (Private L/C)                      |
+    +-----------------------------------------------------------+
+    | [ 状态：已签发 (ISSUED) ] [ 合约 ID: LC-5544 ]            |
+    +-----------------------------------------------------------+
+    | 开证行: DID-Bank-X | 受益人: DID-Supplier-Y | 金额: $50,000 |
+    +-----------------------------------------------------------+
+    | [ ZKP 隐私存证 (Private Proof) ]                          |
+    | 证明哈希: 0x8f2...e3d | [ 验证证明真实性 ] [ 隐私设置 ]     |
+    +-----------------------------------------------------------+
+    | [ AGI 金融建议 (Finance Insight) ]                       |
+    | "该信用证已通过 ZKP 存证，隐私且不可篡改。供应商 ID 已 |
+    | 被屏蔽，开证行无法识别底层供应源，保护商业机密。"        |
+    +-----------------------------------------------------------+
+    | [ 撤销合约 ]                      [ 发起议付请求 ]         |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/lc/contracts`
+- **关键字段映射**
+    - `zkp_proof_hash` -> ZKP 证明哈希
+    - `status` -> 合约状态 (ISSUED, HONORED, etc.)
+    - `expiry_date` -> 过期日期
+- **状态流转**：
+    - 点击 [验证证明真实性] -> 调用 `PrivateAuditService.verifyProof` -> 展示验证通过标识。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 针对不同层级（如银行、供应商、平台）的隐私级别设置界面。
+- [ ] 信用证到期自动提醒机制。
+- [ ] 导出包含 ZKP 证明的信用证正本。
--- a/docs/blueprints/frontend-integration/reputation-perks-ui.md
+++ b/docs/blueprints/frontend-integration/reputation-perks-ui.md
@@ -0,0 +1,50 @@
+# 前端集成蓝图：声誉驱动的阶梯费率与流量倾斜 (Reputation Perks)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_SOV_13 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：通过自动化声誉分级体系，为高信用节点提供更低的结算费率与更高的流量分配优先级，构建正向激励的主权网络。
+- **关联后端 Service**：`ReputationPerksService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 节点治理 -> 声誉权益中心
+- **展示组件**：
+    - [ ] **声誉等级金字塔**：展示当前节点的声誉分数及其所在的权益阶梯。
+    - [ ] **权益应用记录流**：展示最近由于声誉变动导致的费率折扣与流量权重调整。
+    - [ ] **激励策略预览表**：展示不同声誉区间对应的具体权益（费率、流量、配额）。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 声誉权益中心 (Reputation Perks)                   |
+    +-----------------------------------------------------------+
+    | [ 当前节点: Node-Alpha ] [ 声誉分: 92.5 ] [ 等级: 卓越 ]   |
+    +-----------------------------------------------------------+
+    | 尊享权益：                                                |
+    | - 结算费率折扣: -20.00% (已生效)                          |
+    | - 流量倾斜系数: 1.5x (已生效)                             |
+    +-----------------------------------------------------------+
+    | [ 权益变更历史 ]                                          |
+    | --------------------------------------------------------- |
+    | 日期       | 变动原因       | 权益调整                   |
+    | 2026-03-14 | 声誉升至 90+   | 费率折扣提升至 20%         |
+    | 2026-03-10 | 完成大额清算   | 声誉分 +2.5                |
+    +-----------------------------------------------------------+
+    | [?] AGI 激励建议：                                        |
+    | "保持当前的履约成功率，预计下月声誉分可达 95，届时将解锁 |
+    | '跨节点零费率结算' 试用权。"                             |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/governance/reputation/perks?node_id=Node-Alpha`
+- **关键字段映射**：
+    - `reputation_score` -> 声誉分
+    - `applied_discount` -> 已应用折扣
+    - `applied_traffic_weight` -> 已应用流量权重
+- **状态流转**：
+    - 声誉系统更新分数 -> 触发 `ReputationPerksService.applyPerks` -> UI 自动显示新权益。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 支持权益变动的实时消息推送通知。
+- [ ] 权益详情与计费模块、流量分配模块的最终一致性校验。
+- [ ] 导出包含声誉权益贡献的节点经营分析报告。
--- a/docs/blueprints/frontend-integration/sandbox-roi-ui.md
+++ b/docs/blueprints/frontend-integration/sandbox-roi-ui.md
@@ -0,0 +1,47 @@
+# 前端集成蓝图：自治执行沙盒与 ROI 评估 (Sandbox & ROI UI)
+
+> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 Batch 56 沙盒系列逻辑后产出，用于指导 Console 端全栈实现。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：为 AGI 决策提供“数字孪生”验证环境。在建议正式生效前，通过沙盒模拟执行并自动回测 ROI，降低全自动化带来的资金回撤风险。
+- **关联后端 Service**：`AutonomousSandboxService.ts`, `SandboxROIAdvisor.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> AI 控制台 -> 执行沙盒
+- **展示组件**：
+    - [ ] **沙盒执行流展示**：以时间轴形式展示模拟执行的步骤与结果。
+    - [ ] **ROI 回测仪表盘**：对比“执行前”与“模拟后”的关键财务指标（毛利、周转率）。
+    - [ ] **风险预警标记**：若模拟结果触发业务红线（如 B2B 利润 < 15%），自动高亮显示。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] AGI 执行沙盒回测 (Autonomous Sandbox)              |
+    +-----------------------------------------------------------+
+    | 建议 ID: SUG-882 | 模块: 动态调价 | 模拟状态: [ 成功 ]    |
+    +-----------------------------------------------------------+
+    | ROI 预估: +$150.50 (基于过去 30 天销量回测)               |
+    | 利润率变化: 22% -> 24.5%                                  |
+    +-----------------------------------------------------------+
+    | [?] 模拟链路摘要 (Execution Trace)                        |
+    | 1. 镜像当前 SKU 库存与成本数据...                         |
+    | 2. 应用新价格 $29.9 -> $32.5...                           |
+    | 3. 计算预估成交量漂移 (-2%)...                            |
+    | 4. 汇总最终毛利提升...                                    |
+    +-----------------------------------------------------------+
+    | [ 重新模拟 ]                  [ 采纳建议并正式执行 ]      |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/sandbox/executions` (返回 `cf_sandbox_executions` 数据)
+- **关键字段映射**
+    - `simulated_output` -> 模拟输出详情
+    - `estimated_roi` -> 预估收益
+    - `status` -> 执行状态 (SUCCESS/RISK_DETECTED)
+- **状态流转**：
+    - 点击 [采纳] -> `POST /api/v1/suggestions/approve` -> 正式生效。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 确保 `estimated_roi` 的货币单位跟随租户设置。
+- [ ] 增加“沙盒隔离模式”标识，防止用户误以为是真实数据。
+- [ ] 模拟执行期间显示加载动画 (Loading State)。
--- a/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md
+++ b/docs/blueprints/frontend-integration/sea-freight-advisor-ui.md
@@ -0,0 +1,47 @@
+# 前端集成方案：全球物流拥堵指数与航线优化建议 (Sea Freight Advisor) - [BIZ_OPS_160]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：全球贸易环境复杂，罢工、恶劣天气或港口瓶颈会严重拖慢发货时效。系统通过监控全球港口实时拥堵指数，为商户提供“避坑”建议和自动绕路方案。
+- **用户收益**：规避超长延迟，降低消费者退款率，提升供应链应对“黑天鹅”事件的韧性。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **全球港口状态地图 (Global Port Map)**:
+  - 地图标记：主要国际港口（LAX, RTM, NGB, SIN 等）。
+  - 标记颜色：绿色（畅通）、黄色（拥堵）、红色（瘫痪/罢工）。
+- **受影响订单雷达 (Affected Shipments)**:
+  - 动态滚动条展示正在经过“红色”港口的订单号。
+  - 预计延迟天数实时更新。
+- **自适应路由策略 (Adaptive Routing Suggestions)**:
+  - 方案 A: `Switch to Air`（切换至空运，展示差价）。
+  - 方案 B: `Alternative Port`（切换至临近备选港口）。
+  - 方案 C: `Customer Notification`（自动向受影响买家发送道歉信并赠送优惠券）。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `SeaFreightAdvisor.auditRoutes(tenantId, indices)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "routingSuggestions": [
+      {
+        "port": "Los Angeles (LAX)",
+        "affectedCount": 150,
+        "advice": "LA 港口罢工导致平均等待期延长至 14 天。建议后续订单路由至 Long Beach (LGB) 或切换空运。"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 叙述：“根据实时海运遥测，LA 港口的作业效率下降 60%，触发预警门槛。系统建议对高货值订单执行空运 Failover。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **Hover Mark**: 鼠标悬停在港口图标上，展示该港口过去 30 天的拥堵趋势图。
+- **Apply Failover**: 点击“执行绕路”，系统自动更新 `cf_logistics_route` 优先级。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **时效保全值**: 计算通过绕路成功规避的平均延迟天数。
+- **退款预防额**: 基于历史数据，预估通过提前通知买家而减少的“未收到货”纠纷退款。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_160](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/stock-planner-ui.md
+++ b/docs/blueprints/frontend-integration/stock-planner-ui.md
@@ -0,0 +1,46 @@
+# 前端集成蓝图：大促库存安全水位预测 (Stock Planner UI)
+
+> **[AI-2 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_OPS_136 逻辑后产出，用于指导 Console 端全栈实现。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：通过历史大促波峰分析，自动预测未来高峰期的 SKU 安全库存，并生成一键补货建议，防止爆款缺货导致流量浪费。
+- **关联后端 Service**：`StockPlannerService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 库存预测建议
+- **展示组件**：
+    - [ ] **水位预警卡片**：展示当前库存 vs 建议安全水位。
+    - [ ] **波峰分析视图**：展示历史波峰乘数（如 5.2x）及日均销量。
+    - [ ] **补货建议操作**：支持修改补货量并一键生成采购单。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 爆款缺货风险预警 (AGI Prediction)                  |
+    +-----------------------------------------------------------+
+    | SKU: SKU-12345 | 当前库存: 50 | 建议安全水位: 260         |
+    +-----------------------------------------------------------+
+    | [?] 预测依据 (Causal Chain)                               |
+    | "基于去年 11.11 期间 5.2x 的销量激增，当前库存无法支撑..." |
+    +-----------------------------------------------------------+
+    | 因子分析:                                                 |
+    | - 波峰乘数: 5.2x (权重 50%)                               |
+    | - 补货周期: 7 天 (权重 30%)                               |
+    | - 日均销量: 10 (权重 20%)                                 |
+    +-----------------------------------------------------------+
+    | [ 忽略 ]                      [ 一键生成采购建议 ]        |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/inventory/suggestions` (返回 `cf_inventory_audit` 数据)
+- **关键字段映射**
+    - `current_stock` -> 当前库存
+    - `suggested_stock` -> 建议水位
+    - `reason` -> 叙述文案 (Causal Chain)
+- **状态流转**：
+    - 点击 [生成采购建议] -> `POST /api/v1/suggestions/approve` -> 联动 `TradeService.createPurchaseOrder`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 确保 `suggested_stock` 为整数。
+- [ ] 颜色编码：红色表示库存严重不足，黄色表示接近水位。
+- [ ] 针对零历史销量的 SKU 提供兜底预测逻辑提示。
--- a/docs/blueprints/frontend-integration/style-war-ui.md
+++ b/docs/blueprints/frontend-integration/style-war-ui.md
@@ -0,0 +1,47 @@
+# 前端集成方案：SKU 视觉同质化导致的价格战预警 (Same Style War) - [BIZ_OPS_159]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：识别那些与市场上大量商品长得几乎一模一样、且正在陷入恶性价格战的 SKU。通过 AI 提醒商户避开“红海”竞争，采取差异化策略。
+- **用户收益**：保护毛利率，避免盲目跟降，通过视觉或包装差异化重塑商品竞争力。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **红海 SKU 警告看板 (Red Sea Alert Panel)**:
+  - 列表展示受威胁的 SKU 图片。
+  - 右侧并排展示“最强竞品”的图片，并标注相似度得分（如 98%）。
+- **价格对比走势图 (Price Disadvantage Chart)**:
+  - 展示过去 7 天我方售价 vs 竞品售价的背离趋势。
+- **差异化行动清单 (Differentiation Actions)**:
+  - 卡片式建议：
+    - `Change Creative`: 更换主图（场景化、模特化）。
+    - `Bundle Offer`: 增加赠品或合包。
+    - `Exclusive Label`: 申请专利或私模认证标识。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `StyleWarService.analyzeCompetition(tenantId, similarities)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "alerts": [
+      {
+        "productId": "SKU-BAG-01",
+        "riskLevel": "HIGH",
+        "advice": "该款与市场上 50+ 竞品视觉重合度 > 95%，且竞品已降价 15%。建议增加个性化挂件作为赠品进行合包销售。"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 叙述：“AI 检测到该商品的视觉指纹与行业标杆高度重合，且流量正在向低价侧偏移。单纯降价将导致毛利跌破 15%，故生成差异化竞争建议。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **Visual Comparison**: 鼠标悬停在相似度得分上，自动弹出两张图片的像素级对比热力图。
+- **Apply Strategy**: 点击建议项，自动生成任务包发送给 AI-1 (Creative) 生成新主图。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **利润保护额**: 计算采取差异化策略后，维持原价所保住的利润 vs 跟降后的利润损失。
+- **点击率提升**: 监控更换主图后的 CTR 变化。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_159](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/supplier-capacity-watch.md
+++ b/docs/blueprints/frontend-integration/supplier-capacity-watch.md
@@ -0,0 +1,45 @@
+# 前端集成蓝图：自动化供应商产能预警 (Supplier Capacity Watch)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_30 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：提前感知供应商交期延误风险，通过 AGI 预测产能饱和度，自动建议切换备选源。
+- **关联后端 Service**：`SupplierCapacityWatchService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 供应商产能看板
+- **展示组件**：
+    - [ ] **产能饱和度图表**：展示各供应商的积压比例 (Backlog Ratio)。
+    - [ ] **风险预警列表**：高亮显示 `risk_score` 超过阈值的供应商。
+    - [ ] **交期延误预测**：展示各供应商的预估延误天数。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 供应商产能看板 (Supplier Capacity Watch)           |
+    +-----------------------------------------------------------+
+    | [ 状态：严重预警 (CRITICAL) ]                             |
+    | 供应商 ID: SUP-001 | 积压比例: 145% | 预估延误: 8 天     |
+    +-----------------------------------------------------------+
+    | 最大日产能: 10,000 | 当前积压: 14,500 | 平均交期: 7 天    |
+    +-----------------------------------------------------------+
+    | [ AGI 风险洞察 (Capacity Insight) ]                      |
+    | "供应商 SUP-001 产能严重过载，积压比例达 145%，预估   |
+    | 交期延误 8 天。建议切换备选源 SUP-002，其目前产能充足。"|
+    +-----------------------------------------------------------+
+    | [ 保持现状 ]                      [ 切换至备选源 SUP-002 ] |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/supplier/capacity`
+- **关键字段映射**
+    - `backlog_ratio` -> 积压比例
+    - `estimated_delay_days` -> 预估延误天数
+    - `risk_score` -> 风险评分
+- **状态流转**：
+    - 点击 [切换备选源] -> 调用 `POST /api/v1/trade/sourcing/failover` -> 更新后端采购路由。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 供应商产能数据的准实时性（< 1 hour 延迟）。
+- [ ] 备选源的产能余量实时检查。
+- [ ] 导出包含风险预测的采购报告。
--- a/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md
+++ b/docs/blueprints/frontend-integration/supplier-risk-radar-ui.md
@@ -0,0 +1,49 @@
+# 前端集成方案：供应商经营风险自动探测 (Supplier Risk Radar) - [BIZ_OPS_157]
+
+## 1. 业务场景描述 (Business Context)
+- **目标**：监控供应商的经营合规性，识别潜在的法律诉讼、经营异常或财务危机，防止供应链突然中断。
+- **用户收益**：规避违约风险，保障货源稳定，建立供应商全生命周期的风险闭环。
+
+## 2. UI 布局草图 (UI Layout Sketch)
+- **风险雷达图 (Risk Radar Chart)**:
+  - 五个维度：`Quality`, `Lead Time`, `Financial Stability`, `Legal Compliance`, `Price Stability`。
+  - 不同颜色的区域代表不同的风险级别。
+- **高危预警列表 (Critical Alerts)**:
+  - 红色卡片展示：供应商名称、风险等级（CRITICAL/HIGH）、触发原因。
+  - 操作：`Start Audit`（发起实地审厂）、`Switch Source`（寻找替代货源）。
+- **供应商档案详情 (Supplier Dossier)**:
+  - 展示法务公告原文、历史处罚记录、工商变更流水。
+
+## 3. 核心 API 字段映射 (API Mapping)
+- **后端服务**: `SupplierRiskRadar.scanRisks(tenantId)`
+- **响应结构**:
+  ```json
+  {
+    "success": true,
+    "data": [
+      {
+        "supplierId": "SUP-007",
+        "name": "义乌某某电子厂",
+        "riskLevel": "CRITICAL",
+        "notices": ["经营异常名录", "劳动争议诉讼"],
+        "lastScanAt": "2026-03-14T10:00:00Z"
+      }
+    ]
+  }
+  ```
+- **因果链呈现 (XAI Integration)**:
+  - 调用 `DecisionExplainabilityEngine.getDecisionNarrative`
+  - 示例：“该供应商已被列入经营异常名录，且过去 3 个月质量破损率从 2% 飙升至 12%，建议立即停止新订单下发。”
+
+## 4. 交互状态机 (Interaction State Machine)
+- **On Dashboard Load**: 执行全量租户供应商扫描。
+- **Risk Expansion**: 点击风险等级可展开具体的法务/工商证据链。
+- **Mitigation Action**: 选择 `Switch Source` 自动跳转至 `VisualSourcing` 页面。
+
+## 5. ROI 可视化逻辑 (ROI Tracking)
+- **风险规避值**: 计算若该供应商突然倒闭可能导致的未交付订单总损失（$ Expected Loss $）。
+- **供应链韧性**: 展示通过多元化货源分散风险后的系统稳定性提升。
+
+---
+**蓝图维护者**: AI-2 (Internal) | **版本**: V1.0  
+**相关任务**: [BIZ_OPS_157](file:///d:/trae_projects/crawlful-hub/docs/governance/collaboration-board.md)
--- a/docs/blueprints/frontend-integration/tax-routing-optimizer.md
+++ b/docs/blueprints/frontend-integration/tax-routing-optimizer.md
@@ -0,0 +1,44 @@
+# 前端集成蓝图：跨主权税务路由优化引擎 (Tax Routing Optimizer)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_60 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：在多个目的国发货时，自动选择税务成本最低（如 IOSS vs OSS）的路由，保护商户资金。
+- **关联后端 Service**：`TaxRoutingOptimizerService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 税务路由管理
+- **展示组件**：
+    - [ ] **多国税务政策对比图**：展示 IOSS, OSS, DDP, DDU 在不同国家的成本差异。
+    - [ ] **税务路由建议表**：展示已生成的路由建议（Method, Tax, Cost）。
+    - [ ] **合规风险雷达图**：展示不同方法的风险评估（Risk Level）。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 税务路由优化管理 (Tax Routing)                    |
+    +-----------------------------------------------------------+
+    | [ 目的国: 德国 (DE) ] [ 订单金额: €120 ] [ 路由建议: IOSS ] |
+    +-----------------------------------------------------------+
+    | 预估税额: €24.00 | 合规费用: €1.50 | 总成本: €25.50      |
+    +-----------------------------------------------------------+
+    | [ AGI 路由洞察 (Tax Insight) ]                            |
+    | "该订单金额低于 €150，使用 IOSS 路由可享受极低合规成本。|
+    | 相比 DDP 节省：€3.50。风险等级：低 (LOW)。"               |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 应用 IOSS 路由策略 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/tax/routing/optimize?country=DE&value=120`
+- **关键字段映射**
+    - `chosen_method` -> 建议税务方法
+    - `estimated_tax` -> 预估税额
+    - `total_cost` -> 总合规成本
+- **状态流转**：
+    - 切换目的国 -> 调用 `TaxRoutingOptimizerService.optimizeTaxRoute` -> 重新渲染成本对比。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 各国税率数据的实时性核对（< 24 hour 延迟）。
+- [ ] 货币转换的实时汇率应用。
+- [ ] 导出包含税务路径选择理由的财务报表。
--- a/docs/blueprints/frontend-integration/trade-compliance-ui.md
+++ b/docs/blueprints/frontend-integration/trade-compliance-ui.md
@@ -0,0 +1,45 @@
+# 前端集成蓝图：AGI 驱动的全球合规与制裁扫描 (Compliance Scan)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_TRADE_40 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：自动扫描订单与 SKU，识别全球贸易禁令与出口管制风险，防止商户产生合规违约金。
+- **关联后端 Service**：`TradeComplianceService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 供应链管理 -> 合规中心
+- **展示组件**：
+    - [ ] **风险扫描仪表盘**：展示当前待审核订单的合规风险评分。
+    - [ ] **违规详情卡片**：列出具体的制裁项或禁运理由。
+    - [ ] **合规热力图**：展示全球各目的国的风险等级分布。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 全球合规与制裁扫描 (Trade Compliance)             |
+    +-----------------------------------------------------------+
+    | [ 订单 ID: ORD-9988 ] [ 风险等级: 高 (HIGH) ] [ 评分: 90 ] |
+    +-----------------------------------------------------------+
+    | 目的国: 伊朗 (IR) | 风险详情: 该国家目前处于 OFAC 全面制裁名单 |
+    +-----------------------------------------------------------+
+    | [ AGI 合规建议 (Compliance Insight) ]                    |
+    | "建议决策：阻断 (BLOCK)。订单目的国属于制裁名单，继续履 |
+    | 约将面临极高法律风险。系统已自动挂起该订单。"            |
+    +-----------------------------------------------------------+
+    | [ 强制放行 ]                      [ 取消订单并退款 ]       |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/trade/compliance/scan?order_id=ORD-9988`
+- **关键字段映射**
+    - `risk_score` -> 风险评分
+    - `is_compliant` -> 是否合规
+    - `violations` -> 违规项列表
+    - `suggested_action` -> 建议动作
+- **状态流转**：
+    - 扫描发现风险 -> 订单自动进入 `PENDING_REVIEW` -> 管理员在 Console 端确认。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 实时更新全球制裁名单库。
+- [ ] 支持针对特定 SKU 类别的分级合规检查。
+- [ ] 导出包含详细证据链的合规审计报告。
--- a/docs/blueprints/frontend-integration/trade-insurance-ui.md
+++ b/docs/blueprints/frontend-integration/trade-insurance-ui.md
@@ -0,0 +1,46 @@
+# 前端集成蓝图：跨主权贸易信用保险自动投保 (Trade Insurance)
+
+> **[AI-3 @ 2026-03-14]**：由后端 Agent 在完成 BIZ_FIN_80 逻辑后产出。
+
+## 1. 业务意图 (Business Intent)
+- **核心价值**：针对高价值跨国订单，基于风险评分自动建议投保方案，保护商户免受坏账与货损风险。
+- **关联后端 Service**：`TradeInsuranceService.ts`
+
+## 2. UI/UX 布局方案 (Layout Design)
+- **页面入口**：Console -> 财务中心 -> 贸易保险管理
+- **展示组件**：
+    - [ ] **待投保订单列表**：展示 AGI 建议投保的高价值/高风险订单。
+    - [ ] **保险方案对比卡片**：展示不同保司的保费、保额及承保范围。
+    - [ ] **风险评分仪表盘**：展示订单与供应商的实时风险评估分数。
+- **交互草图**：
+    ```text
+    +-----------------------------------------------------------+
+    | [Icon] 贸易信用保险管理 (Trade Insurance)               |
+    +-----------------------------------------------------------+
+    | [ 待处理建议: 3 ] [ 累计保障额度: $150,000 ]               |
+    +-----------------------------------------------------------+
+    | [ 订单 ID: ORD-5566 ] [ 风险评分: 65 (中高) ]              |
+    | --------------------------------------------------------- |
+    | 建议保费: $25.00 | 保障额度: $1,250.00 | 承保商: Insure-Global |
+    +-----------------------------------------------------------+
+    | [ AGI 投保建议 ]                                          |
+    | "该订单供应商评分较低且金额较大，建议投保 '综合货损险'。|
+    | 投保成本仅占订单额 2%，可 100% 覆盖潜在拒付风险。"       |
+    +-----------------------------------------------------------+
+    | [ 忽略建议 ]                      [ 一键投保并锁定费率 ]   |
+    +-----------------------------------------------------------+
+    ```
+
+## 3. API 交互契约 (API Integration)
+- **数据获取**：`GET /api/v1/finance/insurance/suggestions`
+- **关键字段映射**
+    - `premium_amount` -> 保费
+    - `coverage_amount` -> 保额
+    - `status` -> 状态 (SUGGESTED, ACTIVE, etc.)
+- **状态流转**：
+    - 点击 [一键投保] -> 调用 `TradeInsuranceService.suggestPolicy` -> 更新状态为 `ACTIVE`。
+
+## 4. 生产校验项 (FE Readiness)
+- [ ] 供应商风险评分的实时展示。
+- [ ] 投保成功后的电子保单下载。
+- [ ] 导出包含投保成本的利润核算报表。