makemd/docs/blueprints/frontend-integration/TEMPLATE.md

前端集成蓝图：[功能名称]

[AI-X @ YYYY-MM-DD]：由后端 Agent 在完成功能逻辑后产出，用于指导 Console 端全栈实现。

1. 业务意图 (Business Intent)

• 核心价值：描述前端如何呈现后端建议，以及如何通过交互提升商业 ROI。
• 关联后端 Service：[ServiceName].ts

2. UI/UX 布局方案 (Layout Design)

• 页面入口：(例如：Console -> 供应链管理 -> 调价建议)
• 展示组件：
  • 建议卡片：展示关键指标（如：预期利润提升 %）。
  • 因果叙述区：呈现 causalChain 字段，支持 Markdown 渲染。
  • 对比视图：展示“当前价格” vs “建议价格”的差异。
• 交互草图：

  +-----------------------------------------------------------+
  | [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 视图）。