makemd/docs/blueprints/frontend-integration/logistics-health-ui.md

前端集成方案：物流渠道稳定性实时热力分析 (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)
• 响应结构:

  {
    "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