# 前端集成蓝图：建议采纳 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] 确保在多租户环境下，数据隔离边界绝对严密。