需求预测管理系统 — 产品需求文档（PRD）¶
原名：配件销量预测系统
定位：企业级通用需求预测与供需协同平台
文档版本：V1.1（评审修订版）
📌 文档导航¶
- 一、产品概述
- 二、目标用户与角色分析
- 三、用户故事与功能映射
- 四、系统架构总览
- 五、模块详解
- 5.1 基础管理层
- 5.2 数据层
- 5.3 促销活动管理
- 5.4 预测引擎层
- 5.5 调整与决策层
- 5.6 供应与库存协同层
- 5.7 复盘分析层
- 5.8 AI/CLI接入层
- 六、非功能需求
- 七、MVP 建议与迭代路线图
- 八、核心数据模型（ER图）
- 九、页面 UI 清单
- 十、验收标准
- 十一、部署与集成架构
- 十二、权限模型详解
- 十三、模型插件接口规范
- 十四、附录：关键术语定义
一、产品概述¶
1.1 产品定位¶
需求预测管理系统（Demand Prediction & Management System, DPMS）是一套面向企业供应链场景的通用需求预测与供需协同平台。它的核心使命是：
让需求预测从"拍脑袋"变成"有据可依"，打通预测→计划→采购→生产→库存的供应链闭环。
1.2 核心价值¶
| 角色 | 痛点 | 价值 |
|---|---|---|
| 计划员 | 手工Excel预测耗时易错，难以追溯 | 一键预测+自动择优，减少80%手工计算工作量 |
| 采购/生产 | 预测不准导致缺货或库存积压 | 多模型择优+供应约束校验，输出可执行的采购/生产计划 |
| 销售/运营 | 市场变化无法快速反映到预测 | 手工调整+定性规则快速响应，调整全链路可追溯 |
| 管理层 | 决策缺乏数据支撑，复盘靠经验 | 准确率分析+不准原因钻取，持续改进预测能力 |
1.3 产品边界¶
系统涵盖范围： 数据接入 → 数据治理 → 预测建模 → 调整优化 → 库存推演 → 复盘改进
不在本系统范围： - ERP/进销存核心交易（采购订单、销售订单的执行） - WMS 库位级管理（系统提供库存水位建议，不参与库位调度） - 生产排程（提供需求输入，排程由 MES/APS 完成）
1.4 成功度量指标¶
| 维度 | 指标 | 测量方式 |
|---|---|---|
| 效率提升 | 预测耗时从 X 小时降至 Y 分钟 | 上线前后对比调研 |
| 预测质量 | 整体 MAPE ≤ 25%（成熟期） | 系统自动计算 |
| 库存优化 | 缺货率下降 X% / 库存周转率提升 Y% | 对接 ERP 数据 |
| 用户采纳 | 月活跃用户 ≥ 目标用户 80% | 系统埋点 |
| 系统稳定性 | 可用性 ≥ 99.5% | 监控平台 |
1.5 预测准确率目标值¶
| 维度 | 指标 | 初期目标（3个月内） | 成熟期目标（1年后） | 说明 |
|---|---|---|---|---|
| 整体 | MAPE | ≤ 35% | ≤ 25% | 综合加权平均 |
| 快消品 | MAPE | ≤ 30% | ≤ 20% | 需求稳定、数据充足 |
| 耐用品 | MAPE | ≤ 40% | ≤ 30% | 需求波动大 |
| 间歇性需求 | MAE | 人工判断为主 | Croston/TSB 基准 | 大量零值序列 |
| A 类 SKU（贡献 80% 销量） | MAPE | ≤ 25% | ≤ 15% | 重点品严格管控 |
| 新品（无历史数据） | - | V1.0 不支持 | V2.0 类比准确率 ≥ 60% | 依赖相似品匹配 |
| 促销期间 | MAPE | 不纳入评估 | 促销活动登记后 ≤ 35% | 需先有促销管理模块 |
参考基准：零售/消费品行业，MAPE 20-35% 属于可接受范围，<20% 为优秀，>50% 基本不可用。
二、目标用户与角色分析¶
2.1 角色体系（扩展）¶
| 角色 | 典型用户 | 核心场景 | 关注指标 | 系统使用频率 |
|---|---|---|---|---|
| 业务操作员 | 订单专员、业务员 | 导入数据、查看预测结果、手工调整 | 预测值准确度 | 每日 |
| 计划员 | 生产计划员、物料计划员 | 配置预测任务、库存推演、下单建议 | MAPE、安全库存覆盖率 | 每周 |
| 销售主管 | 销售部长、区域经理 | 输入促销/市场信息、修正预测 | 偏差率、市场响应速度 | 每周 |
| 供应链经理 | 供应链总监 | 供需平衡分析、策略制定、复盘 | 库存周转率、缺货率 | 每月 |
| 实施顾问 | POC团队 | 系统搭建、模型选型、指标配置 | 响应时间、配置灵活性 | 项目初期 |
| 系统管理员 | IT/运维 | 用户管理、租户管理、数据源配置 | 系统稳定性、数据安全 | 按需 |
2.2 角色痛点与场景描述¶
业务操作员
"每个月月初要花三天时间，把各区域的销量数据从系统导出到 Excel，跑公式、做预测、调参数，然后生成报表发出去。数据稍微变一下就要重来一遍。"
计划员
"历史数据里经常有'双十一'的异常高峰，模型根本分不清是真实趋势还是促销脉冲。每次都要手动标出来，但下次又忘了哪些处理过。"
供应链经理
"预测做了，采购也买了，结果发现仓库堆满了不需要的货，需要的反而没到。缺的不是预测，是预测和库存决策之间的断链。"
三、用户故事与功能映射¶
3.1 用户故事清单（按模块分组）¶
基础管理层¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-001 | 作为业务操作员，我希望按产品层级配置维度的级次结构，以便后续预测时能按不同粒度聚合拆分 | P0 | V1.0 | 产品层级管理 |
| US-002 | 作为计划员，我希望按周类型灵活配置（周一~周日 / 周日~周六 / 4-4-5财务日历），以适配不同行业的日历习惯 | P0 | V1.0 | 日期层级 |
| US-003 | 作为实施顾问，我希望支持导入仓库网络结构，以便预测能关联到仓配体系 | P0 | V1.0 | 仓网结构 |
| US-004 | 作为管理员，我希望用角色+权限控制功能可见性和数据范围，以确保不同部门只能看自己的数据 | P0 | V1.0 | 用户与权限 |
数据层¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-005 | 作为业务操作员，我希望通过上传 Excel/CSV 文件导入历史销售数据，并自动完成字段映射和校验 | P0 | V1.0 | 文件导入 |
| US-006 | 作为实施顾问，我希望连接外部数据库并定时同步数据，以减少人工导出导入的工作量 | P1（评审修订） | V1.1 | 数据库接入 |
| US-007 | 作为计划员，我希望系统自动检测历史数据中的异常值，并用直观方式标出来，以便我判断是否需要处理 | P0 | V1.0 | 数据感知（异常检测） |
| US-008 | 作为计划员，我希望对异常数据点执行替换或过滤操作，并推荐合理的修复值，以便获得干净的训练数据 | P0 | V1.0 | 数据治理 |
修订说明：US-006 从原 P0 调整为 P1，与 V1.1 版本规划对齐。MVP 阶段仅支持 Excel/CSV 文件导入，降低首版复杂度。
预测引擎¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-009 | 作为计划员，我希望按产品×地区×时间维度组合创建预测任务，并自动运行多个模型择优输出 | P0 | V1.0 | 预测任务 |
| US-010 | 作为计划员，我希望模型参数开箱即用，同时支持高级自定义，以适应不同品类的时间序列特征 | P0 | V1.0 | 模型参数配置 |
| US-011 | 作为实施顾问，我希望通过注册新模型文件来扩展算法库，以适应特定行业的预测需求 | P0 | V1.0 | 模型插件化架构 |
调整与决策¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-012 | 作为计划员，我希望配置定性调整规则（如同比增长率+5%），一键应用到指定维度组合 | P0 | V1.0 | 定性调整规则 |
| US-013 | 作为销售主管，我希望直接在表格或曲线上手工修改预测值，并记录修改原因，以便后续追溯 | P0 | V1.0 | 手工调整 |
| US-014 | 作为供应链经理，我想输入"竞品降价10%"场景，看对未来销量的影响，以便提前制定应对策略 | P1 | V1.1 | 假设分析 |
供应与库存协同¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-015 | 作为计划员，我希望系统根据预测结果和设置的库存策略自动计算安全库存和再订货点 | P1 | V1.1 | 安全库存计算 |
| US-016 | 作为供应链经理，我希望系统在预测时考虑供应侧约束（产能瓶颈、物料可用量、采购提前期），确保预测是可执行的 | P1 | V1.1 | 供需平衡校验 |
| US-017 | 作为计划员，我希望系统综合考虑多渠道库存水位，提示补货优先级，以避免"一端爆仓一端断货" | P2 | V1.2 | 多级库存推演 |
| US-018 | 作为销售主管，我希望引入渠道库存和POS数据作为预测信号，以更早感知真实终端需求 | P2 | V2.0 | 需求感知信号接入 |
| US-SC01（占位） | 作为计划员，我希望系统根据历史预测误差和服务水平目标，自动计算每个 SKU 的安全库存建议值 | P2（占位） | V1.2 | 安全库存计算 |
| US-SC02（占位） | 作为采购员，我希望系统对比预测需求与当前库存+在途量，标识出供需缺口 | P2（占位） | V1.2 | 供需平衡校验 |
| US-SC03（占位） | 作为供应链经理，我希望在一个看板中看到多级仓库（总仓→区域仓→门店）的库存推演结果 | P2（占位） | V2.0 | 多级库存推演 |
复盘分析¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-019 | 作为供应链经理，我希望按产品/地区维度查看预测准确率，并判断偏差方向（偏高/偏低），以便发现系统性问题 | P1 | V1.1 | 准确率分析 |
| US-020 | 作为计划员，我希望能钻取某个不准的预测，追溯到是模型不准、规则调整错了还是手工调坏了 | P1 | V1.1 | 不准原因钻取 |
AI/CLI 接入¶
| ID | 用户故事 | 优先级 | 版本 | 对应功能 |
|---|---|---|---|---|
| US-021 | 作为技术用户，我希望通过命令行完成所有功能操作，以便集成到自动化流程中 | P0 | V1.0 | CLI |
| US-022 | 作为AI Agent（如Claude/OpenClaw），我希望通过标准MCP协议调用系统，以便自主完成预测任务 | P0 | V1.0 | MCP API |
| US-023 | 作为业务操作员，我希望用自然语言提问就能得到预测数据，不需要学复杂操作 | P1 | V1.2 | AI对话窗口 |
四、系统架构总览¶
注：以下架构图在原版基础上增加了 "供应与库存协同层" ，完善了供应链闭环。
┌─────────────────────────────────────────────┐
│ AI / CLI 接入层 │
│ (CLI / MCP / API / AI对话窗口 / 插件) │
├─────────────────────────────────────────────┤
│ 复盘分析层 │
│ (准确率分析 / 原因钻取 / 调整追溯 / 知识库) │
├─────────────────────────────────────────────┤
│ 调整与决策层 │
│ (定性调整规则 / 手工调整 / 假设分析 / │
│ 多方案对比) │
├─────────────────────────────────────────────┤
│ 供应与库存协同层 │
│ (安全库存 / 供需校验 / 多级库存 / POS信号) │
├─────────────────────────────────────────────┤
│ 预测引擎层 │
│ (模型管理 / 训练调度 / 择优 / 结果对比) │
├─────────────────────────────────────────────┤
│ 数据层 │
│ ┌──────────┬──────────┬──────────────────┐ │
│ │ 数据接入 │ 数据感知 │ 数据治理 │ │
│ │ (导入/ │ (异常检测 │ (修复推荐→确认 │ │
│ │ 字段映射 │ Z-Score │ →应用/过滤) │ │
│ │ 数据校验)│ IQR/ │ │ │
│ │ │ 移动平均)│ │ │
│ ├──────────┴──────────┴──────────────────┤ │
│ │ 促销活动管理 │ │
│ │ (活动登记 / 影响基线推算 / 预测参考) │ │
│ └─────────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│ 基础管理层 │
│ (维度管理 / 用户权限 / 租户 / 配置管理) │
└─────────────────────────────────────────────┘
数据流（简版业务流程）¶
数据源 → 数据接入 → 数据治理 → 预测训练 → 模型择优
↓
原始预测值
↓
外部信息（促销/市场变化）→ 定性规则 → 手工调整
↓
最终预测值
↓
┌──────────┴──────────┐
↓ ↓
供应约束校验 库存策略推演
↓ ↓
可执行预测值 安全库存/补货建议
↓ ↓
输出到ERP/采购 输出到WMS/排产
五、模块详解¶
5.1 基础管理层¶
维度管理¶
供应商维度 - 为了后续将预测与采购计划联动，系统支持维护供应商基础信息 - 层级：供应商类别 → 供应商 → 供应物料 - 关键属性：供应商编码、名称、行业分类、信用等级、交付准时率
SKU/物料主数据维度 - 支持从 ERP 同步物料主数据 - 关键属性：物料编码、名称、规格型号、单位、物料分组、ABC分类 - ABC分类用于后续库存策略差异化（A类高频监控，C类简化管理）
库存策略配置¶
在基础管理层面，为后续库存协同预埋配置：
| 配置项 | 说明 | 示例 |
|---|---|---|
| 目标服务水平 | 期望订单满足率，决定安全库存系数 | 95%（Z=1.65）/ 99%（Z=2.33） |
| 采购提前期 | 从下订单到入库的平均天数 | 国内7天 / 海外30天 |
| 订货策略 | 固定周期 / 固定数量 / (R,s,S)策略 | 每周订货 |
| 安全天数 | 在安全库存之上再加的缓冲天数 | 3天 |
| 最小起订量（MOQ） | 供应商要求的最小采购量 | 100件 |
5.2 数据层¶
数据接入¶
补充数据源类型（按优先级） - ERP/API 接口：通过 REST API 直接拉取 - 渠道库存数据：各渠道/仓库的实时库存水位（用于需求感知信号） - POS/零售数据：终端实际销售数据，避免渠道库存失真导致的预测偏差
数据校验增强 - 供需一致性校验：导入的销量数据 + 库存变动数据，校验逻辑闭环（期初+入库-出库=期末）
数据感知¶
异常分类增强 - 补充业务语义层面的异常分类建议系统（指从供应链数据治理实践中提炼的分类体系，后续可基于规则自动标注）： - 已知促销脉冲：标记为"促销影响"，不视为脏数据 - 真实事件：如疫情、台风停产（需保留，可手动标记） - 数据录入错误：如销量多了一个零（应清洗） - 结构性变化：如产品换代导致销量骤降（需模型重新训练）
5.3 促销活动管理¶
¶
活动影响定量分析方法
建议在活动登记和分析中加入以下量化方法：
- 对比分析法：活动期 vs 非活动同期（同比），消除季节因素
- 回归分析法：建立活动力度（折扣率/宣传投入）与销量提升量的回归关系
- 基线推算：用移动平均/Prophet模型推算"如果没有活动"的基线销量
精度沉淀轮次说明：
第一轮：活动开始前，仅凭历史相似活动估算影响系数（粗估）
↓ 活动结束后
第二轮：用实际活动期数据修正影响系数（修正版）
↓ 活动结束后N周（消化完脉冲影响）
第三轮：剔除活动脉冲后，正常基线预测的偏差回溯（用于后续同类活动参考）
活动回填 - 在训练模型中，系统应提供从历史数据中剥离活动影响的选项 - 避免模型把促销脉冲当成常态需求模式
5.4 预测引擎层¶
模型选型指引¶
| 数据特征 | 推荐模型 | 适用场景 |
|---|---|---|
| 有稳定趋势+季节性 | Prophet / ARIMA | 常规销量预测 |
| 多特征影响预测 | LightGBM / XGBoost | 考虑促销、价格、节假日等多因素 |
| 强周期性+长期依赖 | LSTM / Transformer | 海量历史数据，复杂非线性模式 |
| 数据极少或无历史 | 不建模型，仅输出简单统计值+人工录入预估 | 新品上市 |
| 稀疏数据（间歇性需求） | Croston / TSB | 备件、低周转SKU |
新品预测策略¶
针对没有历史销量数据的 SKU：
- 类比法：用户选择"相似产品"的历史数据作为训练集（如：新口味薯片参考旧口味上线初期的销售曲线）
- 属性回归法：如果系统积累了足够多的同类产品历史，可建立"产品属性→首月销量"的回归模型
- 人工录入基准值：由业务人员输入首月/首季预估，系统在此基础上按季节性模板扩展
分阶段预测策略¶
预测策略配置:
- 短期预测（1~4周）:
粒度: 日/周
用途: 补货计划、运输调度
模型倾向: 移动平均、LSTM
- 中期预测（1~6个月）:
粒度: 月
用途: 采购计划、产能规划
模型倾向: Prophet、LightGBM
- 长期预测（6~24个月）:
粒度: 月/季
用途: 战略规划、供应商合同
模型倾向: 趋势外推、情景分析
5.5 调整与决策层¶
调整流程¶
原始预测值
│
├── (可选) 运行定性调整规则 → 定性调整后预测值
│
├── (可选) 促销活动修正 → 促销修正预测值
│
├── (可选) 供需约束校验 → 供给约束后预测值
│
└── (可选) 手工调整 → 最终手工调整值
│
▼
输出到库存推演/ERP
建议： 所有调整步骤对用户可选，每步保留快照用于追溯。界面设计采用"预测值→建议值→最终值"的对比视图，用户看到的是多个候选预测值的并列比较，而非单一数值的逐次变换。
调整原因标签体系¶
为便于后续分析，调整原因分类建议采用分层标签：
一级：市场因素/运营因素/外部事件/数据问题/其他
二级：市场因素→竞品行为/宏观经济/行业政策/消费者偏好变化
运营因素→促销活动/渠道策略/定价调整/包装变更
外部事件→疫情/自然灾害/政策法规/供应链中断
数据问题→历史数据口径变化/产品拆分/合并
允许用户自定义二级标签。
5.6 供应与库存协同层¶
5.6.1 安全库存计算¶
输入： - 预测值（均值 + 预测误差标准差） - 服务水平（目标缺货概率） - 采购提前期 - 需求波动修正因子（考虑提前期内的需求波动）
算法：
安全库存 = Z × σ_dlt × √L
其中：
Z = 服务水平对应的 Z 值（95%→1.65, 99%→2.33）
σ_dlt = 预测误差的标准差（或需求的标准差，取较大者）
L = 采购提前期（天）
再订货点（ROP）：
ROP = 提前期内的平均需求 + 安全库存
= d_avg × L + SafetyStock
界面展示： - SKU × 仓库维度：当前库存水位 vs 安全库存 vs 再订货点 - 可视化：库存水位线+安全库存线+ROP线的趋势图 - 预警：低于安全库存的 SKU 标红提示
5.6.2 供需平衡校验¶
概念： 模型输出的预测值可能超出供应能力上限，需要"拉回来"。
约束来源：
| 约束类型 | 数据来源 | 校验机制 |
|---|---|---|
| 产能上限 | MES / 手工输入 | 预测值 > 产能上限 → 标记"供不应求" |
| 物料可用量 | ERP 齐套检查/N 日库存可供应量 | 关键物料库存不足以覆盖 → 标记风险 |
| 采购提前期 | 供应商主数据 | 预测开始时间早于最晚下单日 → 标记"过期" |
| 仓库容量 | WMS 库容数据 | 预测入库量 > 余量 → 标记超容 |
校验结果输出： - ✅ 通过：预测值可直接用于采购/生产 - ⚠️ 警告：部分超出或风险提示，给出调整建议 - ❌ 不可行：预测值无法满足，需人工调整
页面流程建议： 1. 计划员看到最终预测值 2. 点击"供需校验"按钮 3. 系统逐项检查约束条件，生成校验报告 4. 建议用户调整范围（如"华东区产能不足，建议下调至XX"） 5. 用户确认或手工调整
5.6.3 多级库存推演¶
场景： 产品从中心仓发到区域仓再到前置仓，各仓库存水位不同。
推演逻辑：
输入：
- 各层级仓库的当前库存水位
- 各层级的预测需求（按仓维度）
- 补货提前期（各层级间运输时间）
- 补货策略（推式/拉式/柔性）
输出：
- 各层级未来N周的库存水位变化曲线
- 各层级缺货时间点和缺货量预测
- 补货建议（何时、向谁、补多少）
策略模式说明： - 推式：上游主动向下游分配库存（适合大批量、均衡需求） - 拉式：下游按需向上游要货（适合小批量、波动需求） - 柔性：比例分配 + 响应调拨（推荐方案）
5.6.4 需求感知信号接入¶
核心问题： 传统需求预测只依赖历史销量，但历史销量"已经晚了"——它代表已经发生的需求，不代表正在发生的需求。
补充信号源（优先级排序）：
| 信号 | 获取方式 | 提前期 | 成熟度 |
|---|---|---|---|
| 渠道库存水位 | API/文件导入 | T-7~30天 | P2 |
| POS/零售终端数据 | API直连 | T-1天 | P2 |
| 电商搜索/浏览指数 | API | T-实时 | P3（远期） |
| 社交媒体趋势 | NLP文本分析 | T-实时 | P3（远期） |
逻辑闭环：
信号源 → 特征工程 → 与历史销量关联分析
↓
提升模型预测准确率（修正因子/新特征）
↓
输出更接近真实需求的预测值
5.6.5 订单承诺（ATP）¶
场景： 销售接单时判断"我能不能答应客户这个交期？"
输入：
- 预测值（已调整+已校验）
- 当前库存 + 在途库存
- 安全库存预留（承诺后不能跌破安全线）
- 产能/采购约束
输出：
- 每个时间段的可承诺量（Available-to-Promise）
- 示例：6月第三周 ATP = 500件（其中新订单接单上限450件，预留50件做安全库存）
5.7 复盘分析层¶
复盘分析维度和指标¶
建议沉淀的关键指标体系：
| 维度 | 指标 |
|---|---|
| 整体准确率 | 产品线加权 MAPE、分产品 MAPE 分布 |
| 偏差方向 | 偏高率（预测>实际）、偏低率（预测<实际） |
| 调整贡献 | 原始预测MAPE vs 最终预测MAPE，规则调整贡献度 vs 手工调整贡献度 |
| 库存影响 | 按照预测采购后的实际库存周转率变化、缺货次数/缺货天数 |
| 成本影响 | 过剩库存持有成本估算、缺货损失估算 |
复盘会议输出物¶
系统应支持在每次复盘周期结束时一键生成复盘报告（PDF/Excel），包含： 1. 本周期预测准确率总览（仪表板） 2. TOP5 准和 TOP5 不准的产品/地区（含偏差原因分析） 3. 调整操作汇总（谁调了哪些，效果如何） 4. 供应链影响评估（库存水位变化、缺货事件） 5. 改进建议（识别系统性偏差模式，建议调整模型参数或规则配置）
5.8 AI/CLI 接入层¶
AI Agent 典型场景¶
| 场景 | 用户输入示例 | 系统响应 |
|---|---|---|
| 数据查询 | "华南区上个月销量多少" | 返回数据+趋势图 |
| 创建预测 | "帮我预测下季度华北区各品类销量，用LightGBM" | 创建任务+返回结果 |
| 调整预测 | "把A产品的下月预测提高10%，因为要搞促销" | 执行调整+记录原因+返回 |
| 异常检查 | "看看这批数据有没有问题" | 运行异常检测+展示结果 |
| 复盘分析 | "上个月预测哪里不准了" | 准确率分析+原因钻取 |
Agent 权限控制¶
- CLI/API/MCP 操作继承用户角色权限
- AI对话窗口的操作权限独立配置（可限制仅查询，或允许执行）
- 操作日志中记录操作来源（是用户手动操作，还是AI Agent 自动执行）
六、非功能需求¶
6.1 性能要求¶
| 指标 | 目标值 | 说明 |
|---|---|---|
| 数据导入 | 10万条/分钟 | 基于 100MB Excel 文件 |
| 预测任务 | 单个任务 < 30秒 | LightGBM 模型，1000个 SKU × 36个月历史 |
| 并发任务 | 支持 20 个任务并行 | |
| 页面加载 | < 2秒 | 含可视化图表 |
| 数据存储 | 支持 3-5 年历史数据在线 | 冷数据归档到对象存储 |
6.2 安全要求¶
- 数据加密：传输层 TLS 1.3，存储层 AES-256
- 审计日志：所有修改操作记录不可篡改（写日志表+签名校验）
- 数据备份：每日全量备份 + 每小时增量备份
- 租户隔离：严格的数据隔离，禁止跨租户数据泄露
6.3 可用性¶
- 目标可用性：99.5%（月度 3.6 小时不可用以内）
- 预测任务的离线容错：预测任务失败自动重试 3 次，重试间隔递增
6.4 可扩展性¶
| 维度 | 扩展方式 |
|---|---|
| 维度层级 | 用户自定义，不硬编码 |
| 预测模型 | 插件注册制，新增模型 == 上传文件+注册（详见第十三章接口规范） |
| 数据源类型 | 插件适配器模式，新增类型 == 实现适配器接口 |
| 异常检测算法 | 扩展检测器接口 |
| 定性规则指标 | JSON 配置新指标 |
| 库存策略 | 插件化策略，新增策略 == 实现策略接口 |
七、MVP建议与迭代路线图¶
7.1 版本规划¶
V1.0 MVP ─── V1.1 ─── V1.2 ─── V2.0
(P0) (P0+P1) (P1) (P2+P3)
7.2 V1.0 MVP 范围¶
核心目标：跑通"数据输入→预测→结果输出"的最小闭环。
必须包含： - ✅ 基础管理：维度管理（产品/地区/日期固定层级）、用户权限 - ✅ 数据接入：Excel/CSV 文件导入 + 字段映射 + 校验（数据库接入排至 V1.1） - ✅ 数据感知：异常检测（Z-Score / IQR，支持批量处理） - ✅ 数据治理：异常点修复推荐（同期/相似/平滑三种方案）或过滤 - ✅ 预测引擎：至少含 2 个模型（Prophet + LightGBM），自动择优 - ✅ 手工调整：表格/曲线编辑 + 原因记录 - ✅ 结果导出：Excel/CSV
MVP 不包括： - ❌ 数据库接入（优先级调整至 P1，V1.1） - ❌ 促销活动管理 - ❌ 假设分析 - ❌ 复盘分析 - ❌ 供应与库存协同 - ❌ AI 对话窗口、MCP 接口（但 RESTful API 建议做）
7.3 V1.1 增强版¶
- 数据库接入（US-006）
- 促销活动管理（登记 + 影响基线推算 + 预测参考）
- 定性调整规则引擎
- 复盘分析（准确率 + 调整追溯）
- CLI + MCP 接口
7.4 V1.2 供应链协同版¶
- 安全库存计算 + 再订货点
- 供需平衡校验
- 假设分析
- 多模型参数调优界面
- AI 对话窗口
7.5 V2.0 智能版¶
- 多级库存推演
- 需求感知信号接入（渠道库存/POS）
- 订单承诺（ATP）
- 新品预测类比推荐
- 复盘知识库（AI 自动生成改善建议）
- 社交媒体/搜索趋势信号
7.6 风险与缓解措施¶
| 风险 | 影响 | 缓解 |
|---|---|---|
| 模型在真实数据上不准 | 用户信任度下降 | MVP 阶段只输出各模型对比，不强推"最优"；短期+中长期分层验证 |
| 数据质量差导致预测不可用 | 系统无法交付价值 | 数据治理先行，数据感知+清洗做扎实再跑预测 |
| 用户手工调整过多、失去预测意义 | 预测流程变成手工报表 | 通过复盘分析量化调整合理性，引导用户减少不必要的调整 |
| 供应侧数据整合困难 | 供应约束校验失效 | P2 再纳入，前期预测独立输出+手工输入约束条件 |
八、核心数据模型（ER图）¶
8.1 核心实体关系¶
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Product │ │ Warehouse │ │ Calendar │
│ (产品维度) │ │ (仓库维度) │ │ (时间维度) │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ id │ │ id │ │ id │
│ sku_code │ │ wh_code │ │ date │
│ name │ │ name │ │ week_type │
│ category_id │ │ region_id │ │ quarter │
│ level │ │ type │ │ is_holiday │
│ parent_id │ │ parent_id │ │ ... │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌────────▼────────┐
│ HistoricalData │
│
│ (历史销售数据) │
├─────────────────┤
│ id │
│ product_id (FK) │
│ warehouse_id(FK)│
│ date (FK) │
│ quantity │
│ revenue │
│ is_abnormal │
│ abnormal_type │
└────────┬────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌───────▼──────┐
│ Forecast │ │ Adjustment │ │ Promotion │
│ (预测结果) │ │ (手工调整) │ │ (促销活动) │
├──────────────┤ ├─────────────┤ ├──────────────┤
│ id │ │ id │ │ id │
│ task_id │ │ forecast_id │ │ name │
│ product_id │ │ product_id │ │ type │
│ warehouse_id │ │ date │ │ start_date │
│ date │ │ orig_value │ │ end_date │
│ model_name │ │ adj_value │ │ product_ids │
│ pred_value │ │ reason │ │ impact_ratio │
│ ci_lower │ │ operator │ └─────────────┘
│ ci_upper │ └─────────────┘
└──────────────┘
九、页面 UI 清单¶
MVP（V1.0）页面清单¶
| 序号 | 页面名称 | 所属模块 | 主要使用者 | 核心功能点 |
|---|---|---|---|---|
| 1 | 登录/注册页 | 基础管理 | 所有用户 | 账号登录、密码重置 |
| 2 | 维度管理-产品层级 | 基础管理 | 系统管理员 | 产品分类树、SKU 管理 |
| 3 | 维度管理-地区层级 | 基础管理 | 系统管理员 | 区域树的增删改查 |
| 4 | 维度管理-日期配置 | 基础管理 | 实施顾问 | 日历类型切换 |
| 5 | 仓库网络管理 | 基础管理 | 实施顾问 | 仓网结构导入与编辑 |
| 6 | 用户与权限管理 | 基础管理 | 系统管理员 | 角色配置、用户分配 |
| 7 | 数据导入 | 数据层 | 业务操作员 | 上传文件、字段映射、校验预览 |
| 8 | 导入历史 | 数据层 | 业务操作员 | 查看历史导入记录与状态 |
| 9 | 异常检测看板 | 数据层 | 计划员 | 异常列表、图表标注、批量选择 |
| 10 | 异常修复工作台 | 数据层 | 计划员 | 替换方案推荐、过滤确认 |
| 11 | 预测任务配置 | 预测引擎 | 计划员 | 选择 SKU/时间范围/模型、发起预测 |
| 12 | 预测结果对比 | 预测引擎 | 计划员 | 多模型图表对比、指标卡片、择优选择 |
| 13 | 手工调整工作台 | 调整决策 | 业务操作员/销售主管 | 表格编辑、曲线拖拽、原因填写 |
| 14 | 结果导出 | 调整决策 | 业务操作员 | 选择维度、导出 Excel/CSV |
V1.1 新增页面¶
| 序号 | 页面名称 | 所属模块 |
|---|---|---|
| 15 | 促销活动管理 | 促销活动 |
| 16 | 定性规则配置 | 调整决策 |
| 17 | 复盘分析看板 | 复盘分析 |
| 18 | 数据源管理（数据库接入） | 数据层 |
V1.2 新增页面¶
| 序号 | 页面名称 | 所属模块 |
|---|---|---|
| 19 | 安全库存配置 | 供应协同 |
| 20 | 供需平衡看板 | 供应协同 |
| 21 | 假设分析工作台 | 调整决策 |
| 22 | 模型参数调优 | 预测引擎 |
| 23 | AI 对话窗口 | AI/CLI接入 |
十、验收标准¶
10.1 验收标准格式说明¶
本章为 P0 用户故事补充 Given/When/Then 验收条件，作为开发交付标准。
10.2 P0 用户故事验收标准¶
US-005：文件导入¶
功能：Excel/CSV 文件导入历史销售数据
优先级：P0
验收标准1 - 正常导入流程：
Given 用户已登录并有数据导入权限
When 上传一个 10 万行 × 20 列的 Excel 文件（100MB）
Then 系统在 1 分钟内完成解析
And 自动识别日期列、产品列、数值列并提示用户确认映射
And 校验通过的数据进入"待处理"状态
And 校验失败的行记录到错误报告，标注行号和失败原因
验收标准2 - 格式校验拒绝：
Given 用户上传了格式不符的文件
When 文件不是 .xlsx / .xls / .csv 格式
Then 系统拒绝上传并提示"仅支持 Excel(.xlsx/.xls) 和 CSV 格式"
验收标准3 - 必填字段检查：
Given 用户上传的文件缺少必填字段
When 文件中没有日期列 或 没有数值列
Then 系统提示"缺少必填字段：日期、数值"，并高亮缺失项
验收标准4 - 数据校验：
Given 用户上传的文件包含错误数据
When 日期格式错误或数值超出范围
Then 系统逐行标记错误，显示"第 X 行：日期格式错误"
And 用户可选择"忽略错误行继续导入"或"修正后重新上传"
US-001：产品层级管理¶
验收标准1 - 多级支持：
Given 系统管理员在维度管理页面
When 创建产品层级结构，设置 3 级分类（大类→中类→SKU）
Then 系统支持无限层级创建
And 每个层级可自定义名称
验收标准2 - 级联操作：
Given 产品层级已存在（大类→中类→SKU）
When 管理员重命名某个中类
Then 该中类下的所有 SKU 的所属关系不变
And 该中类名称在所有已存在的预测任务中自动更新
验收标准3 - 数据导入：
Given 管理员在层级管理页面
When 上传包含产品层级结构的 Excel 文件
Then 系统解析并创建层级树
And 校验产品编码唯一性，重复编码拒绝导入并提示
US-004：用户与权限¶
验收标准1 - 角色配置：
Given 系统管理员进入角色管理页面
When 创建一个新角色并勾选"数据导入"、"预测任务"、"手工调整"权限
Then 该角色下的用户仅能访问被授权的功能模块
验收标准2 - 数据权限隔离：
Given 用户 A 属于"华东区"，用户 B 属于"华南区"
When 两用户分别登录系统查看数据
Then 用户 A 只能看到华东区的数据
And 用户 B 只能看到华南区的数据
US-007：异常检测¶
验收标准1 - 检测阈值配置：
Given 计划员打开异常检测页面
When 配置 Z-Score 阈值为 ±2.5
Then 系统按新阈值重新标记异常
验收标准2 - 批量处理上限：
Given 系统正在运行异常检测
When 数据量超过 100 万行
Then 系统按产品维度分批处理，每批不超过 10 万行
And 显示处理进度百分比
US-009：模型训练与预测¶
验收标准1 - 最少数据量要求：
Given 计划员创建预测任务，选择的 SKU 只有 6 个月历史数据
When 用户选择 Prophet 模型
Then 系统提示"Prophet 模型建议至少 24 个月历史数据，是否继续？"
And 允许用户确认后继续执行
验收标准2 - 失败通知：
Given 预测任务正在执行
When 任务因数据异常失败
Then 系统在任务列表标记"失败"
And 通知创建者失败原因（如"训练数据不足"或"模型参数异常"）
US-011：手工调整¶
验收标准1 - 调整幅度限制：
Given 计划员在手调界面编辑某 SKU 的预测值
When 用户输入的值超过原始预测值的 ±50%
Then 系统弹窗提示"调整幅度超过 50%，请确认"
And 用户确认后可继续
验收标准2 - 冲突处理：
Given 用户 A 和用户 B 同时对同一 SKU 同一月份进行手工调整
When 用户 B 点击保存
Then 系统检测到冲突，提示"该数据已被用户 B 修改，请刷新后重试"
And 展示两个版本的值供对比
十一、部署与集成架构¶
11.1 部署架构¶
┌──────────────┐
│ Nginx/CDN │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌────────▼───┐ ┌────▼─────┐ ┌───▼────────┐
│ Web 前端 │ │ REST API │ │ 预测微服务 │
│ (Vue 3) │ │ (Go/Py) │ │ (Python) │
│ Port: 80 │ │ Port:8080│ │ Port: 9090 │
└────────────┘ └────┬─────┘ └───┬────────┘
│ │
┌─────▼─────┐ ┌────▼─────┐
│ PostgreSQL│ │ Redis │
│ (业务数据) │ │ (任务队列)│
└───────────┘ └──────────┘
11.2 部署方式¶
- 私有化部署： Docker Compose / K8s Helm Chart
- SaaS 多租户： 共享应用实例 + 数据库级隔离
- 预测引擎： 独立 Python 微服务，通过消息队列异步通信
11.3 待明确关键决策¶
- 前端框架：建议沿用关联项目的 Vue 3 + Element Plus
- 后端语言与框架
- Python 预测引擎的模型持久化方式（pickle / ONNX / MLflow）
- 任务调度实现方式（Celery / 自研 / 云服务）
十二、权限模型详解¶
12.1 角色预定义¶
| 角色 | 功能权限范围 | 数据范围 |
|---|---|---|
| 业务操作员 | 数据导入、查看预测、手工调整、结果导出 | 所辖区域 |
| 计划员 | 业务操作员权限 + 预测任务配置、异常处理 | 所辖品类/区域 |
| 销售主管 | 查看预测、手工调整（含原因）、输入促销信息 | 所辖团队区域 |
| 供应链经理 | 全部查看权限 + 复盘分析 + 策略配置 | 全公司 |
| 实施顾问 | 系统配置（维度、数据源、模型）、所有查看权限 | 项目范围 |
| 系统管理员 | 用户管理、租户管理、系统配置、审计日志 | 全系统 |
12.2 权限控制粒度¶
功能权限：页面级（可见/不可见）→ 按钮级（可点/不可点）→ 字段级（只读/可编辑）
数据权限：租户 → 区域 → 品类 → 仓库
操作审计：谁(who) + 何时(when) + 做了什么(what) + 来源(手动/API/AI Agent)
十三、模型插件接口规范¶
13.1 插件接口契约¶
所有预测模型插件必须实现以下接口：
class ForecastModelPlugin:
"""所有预测模型插件必须实现的接口"""
# --- 元信息 ---
name: str # 模型唯一标识，如 "prophet_v1"
display_name: str # 展示名称，如 "Prophet (Meta)"
version: str # 语义化版本，如 "1.0.0"
min_data_points: int = 24 # 最少需要的历史数据点数
supports_intermittent: bool # 是否支持间歇性需求
# --- 训练 ---
def fit(self, df: DataFrame, params: dict) -> None:
"""训练模型。df 必须包含 ds(日期) 和 y(数值) 列"""
...
# --- 预测 ---
def predict(self, periods: int) -> DataFrame:
"""返回 df，包含 ds, yhat, yhat_lower, yhat_upper 列"""
...
# --- 评估 ---
def evaluate(self, actual: DataFrame) -> dict:
"""返回 {"mape": 0.15, "rmse": 23.4, "mae": 18.2}"""
...
# --- 序列化 ---
def save(self, path: str) -> None: ...
def load(self, path: str) -> None: ...
十四、附录：关键术语定义¶
| 术语 | 定义 |
|---|---|
| MAPE | Mean Absolute Percentage Error，平均绝对百分比误差。值越低越好。 |
| RMSE | Root Mean Square Error，均方根误差。对大偏差更敏感。 |
| MAE | Mean Absolute Error，平均绝对误差。直观反映平均偏差量。 |
| 安全库存 | 为应对需求波动和供应不确定性而额外持有的库存量。 |
| 再订货点（ROP） | 库存降到该水平时发出补货订单的点。 |
| 服务水平 | 不出现缺货的概率。95%服务水平 ≈ 每20个周期中有1期缺货。 |
| 提前期 | 从发出订单到收到货物的时间间隔。 |
| 推式补货 | 上游主动向下游分配库存。 |
| 拉式补货 | 下游按需向上游要货。 |
| ATP | Available-to-Promise，可以承诺给客户的数量。 |
| MOQ | Minimum Order Quantity，供应商要求的最小采购批量。 |
| 4-4-5 日历 | 财务日历：每季度 4-4-5 周模式，确保季度对齐。 |
| Z-Score | 标准化分数，(x-μ)/σ，用于判断数据点偏离均值的程度。 |
| IQR | 四分位距，Q3-Q1，稳健的离散度度量。 |
| Croston | 针对间歇性需求的时间序列预测方法。 |
| TSB | Teunter-Syntetos-Babai，改进的间歇性需求预测方法。 |