makemd/docs/blueprints/frontend-integration/stock-planner-ui.md

前端集成蓝图：大促库存安全水位预测 (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）及日均销量。
  • 补货建议操作：支持修改补货量并一键生成采购单。
• 交互草图：

  +-----------------------------------------------------------+
  | [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 提供兜底预测逻辑提示。