makemd/docs/blueprints/frontend-integration/dynamic-routing-failover.md

前端集成蓝图：全球动态路径对冲与风险熔断 (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)。
• 交互草图：

  +-----------------------------------------------------------+
  | [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 轨迹。