# r1-engineer.md · 工程师主笔章节

**作者视角**: 工程师（实现细节 / 边界异常 / 可测试性 / 性能）
**基线**: proposal-v1.md FR-1 ~ FR-16（含 R3 共识新增 FR-14/15/16，编号与本文对齐见 §12.2）
**日期**: 2026-05-23

> 编号对齐说明：proposal-v1.md §3.2 列了 FR-1 ~ FR-15。R3 共识"批量接受配责任回路"实际是独立功能，本稿单列为 FR-14（批量接受+责任回路）；原 FR-14（60/90 天上游预警）→ FR-15；原 FR-13（SKU 分类）→ FR-16。完整映射见 §12.2。

---

## §5 详细功能说明

### 5.1 通用约定（时区 / 格式 / 货币 / i18n / 命名）

| 项 | 约定 | 说明 |
|---|------|------|
| 时区 | 所有持久化时间用 UTC（ISO 8601, 含毫秒+Z） | 解决 R1-T8 |
| 业务日切 | 按"美西站点本地时间"日切（PST/PDT，含夏令时） | 销量/库存以亚马逊站点为准；其他站点扩展时单独配置 |
| 展示时区 | UI 默认 Asia/Shanghai，用户可切换 | 顶部时区指示器 |
| 货币 | 原值以销售站点币种存储（USD 为主）；展示按"原币 + 折算 CNY"双显示 | 汇率每日 9:00 UTC 拉取，缓存 24h |
| 数量精度 | 件 = 整数；金额 = 2 位小数；天数 = 1 位小数；百分比 = 1 位小数 | 所有 UI/导出一致 |
| SKU 编号 | 内部 SKU ID = UUIDv4；展示用 seller-sku（卖家自定义字符串，≤ 40 字符） | 解耦 ASIN 与 SKU |
| 时间窗口 | 决策计算窗口 T = 90 天滚动；历史训练窗口 = 365 天（不足按可得长度） | |
| 空值规则 | 必填缺失 → 拒绝写入并标 error；可选缺失 → null + 标 warning | |
| i18n | v1 仅中文（zh-CN）；预留 i18n key，不硬编码字符串 | v1.5 可加英文 |
| 文件导出 | CSV 用 UTF-8 BOM（Excel 兼容）；时间列附 ISO 字符串列 | |
| ID 幂等 | 所有创建型 API 必须接受 client_request_id（幂等键，TTL 24h） | 解决重复提交 |
| 取整规则 | 数量上取整（ceil），金额四舍五入（half-even） | |

### 5.2 FR-1 数据接入 Adapter

**位置**: 系统底座 / 后台模块"数据源管理"页 + "数据快照"页

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 数据源列表（12+4 项 D1~D16） | Table | 显示名称/类型/最后同步/状态徽章（绿/黄/红） | 点击进详情 | 用户无 admin 权限时只读 |
| 模式切换 Toggle | Switch | "Mock" 模式（v1 默认） | 切到 Real 模式弹二次确认；切换记录 audit log | Real 数据源未完成接入时禁用 Real 档 |
| 同步频率选择 | Dropdown | 日（凌晨 02:00 UTC） | 可选 实时/15min/1h/日；改动需 admin 确认 | 数据源不支持 push 时实时档禁用 |
| 立即同步按钮 | Button | 可点 | 触发即时拉取，进度条显示 | 上次同步 < 60s 内禁用（防抖） |
| 数据质量校验报告 | Panel | 折叠 | 展开显示 缺失率/异常值数/重复键数 + 每项的 sample 5 行 | 无最近一次同步时禁用 |
| 数据快照列表 | Table | 倒序 30 天 | 选中可"复制为决策输入"用于回测 | 快照已被引用于在生效的决策时禁用删除 |
| Schema 字段映射器 | Form | v1 预填 FBA API 标准 schema | 修改保存后版本号 +1，旧版本仍可回滚 | 字段类型与下游约束不符时保存按钮禁用并红字提示 |

**交互逻辑**:
1. **Adapter 抽象层**：使用 Strategy 模式定义 `IDataAdapter`接口（`fetch(since, until) -> RawBatch`、`normalize(RawBatch) -> CanonicalBatch`、`validate(CanonicalBatch) -> ValidationReport`）；v1 提供 `MockAdapter` 与 `FBAStubAdapter`（按真实 FBA Reports schema 反向设计），v1.5 切换只换实现不动接口。
2. **数据写入**：每次同步形成不可变 snapshot（snapshot_id = uuid + sha256(payload)），写 append-only 表 `data_snapshots`；当前指针表 `current_snapshot_ref` 单条记录指向最新有效快照。
3. **统一标准时间**：每条 raw record 入库时附 `source_tz`、`source_ts`、`utc_ts`、`business_date_pst` 四个字段，全链路用 utc_ts 计算，展示按 business_date_pst 聚合。
4. **数据质量校验**：6 类规则——必填非空 / 类型校验 / 值域校验（如销量 ≥0、价格 >0）/ 引用完整性（SKU 存在）/ 异常值（z-score>4 标黄、>6 标红）/ 时序连续性（缺日填 0 标 warning）。
5. **Mock→Real 切换审计**：每次切换记录操作人/时间/前后模式/原因，写 `audit_log` 表；UI 顶部沙盘斑马条样式由模式决定（FR-10 联动）。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 网络异常 | 数据源 API 超时（>30s） | 重试 3 次（指数退避 1s/4s/16s）；仍失败 → 用上次快照 + 顶部红条提示 + 写 alert |
| 网络异常 | DNS 解析失败 | 立即降级到 last-known-good 快照；推送 P1 告警 |
| 数据异常 | 字段缺失 > 5% | 拒绝整批写入，保留上次快照；UI 弹错误详情 + 下载 sample 失败行 |
| 数据异常 | 销量出现负值/价格为 0 | 该 SKU 标 quarantine，不进入优化；通知用户人工处理 |
| 数据异常 | 同一 SKU 同一天两条不同库存 | 取 source_ts 最新；记 conflict log |
| 权限不足 | 用户切 Real 模式但无 admin | 弹"无权限"toast，按钮恢复 Mock 态 |
| 并发冲突 | 两个 admin 同时改 Schema 映射 | 乐观锁（version 字段），后保存方报 409 + 提示"已有更新，请刷新" |
| 第三方失败 | FBA API 返 5xx | 重试 + 降级；连续 24h 失败 → 升级为 P0 告警（推送给管理员） |
| 第三方失败 | API 限流 429 | 按 Retry-After 头退避；记 rate-limit metric |
| 设备差异 | 移动端查看时数据源列表过宽 | 横向滚动 + 关键列固定（名称/状态） |
| 用户操作冲突 | 删除快照时该快照正被回测引用 | 阻止删除 + 提示"被回测任务 X 引用，先取消任务" |

**边界数值**:
- 单源单次拉取上限：10 万行；超出则分页（page_size=1万，cursor 模式）
- 数据保留：原始快照 90 天，归档冷存（S3 Glacier）至 2 年
- 单 SKU 单日多条记录：保留最近 1 条（其余进 history 表）
- API 调用预算：单源 ≤ 1000 req/min（避免限流）
- snapshot 写入超时：单次 ≤ 120s

---

### 5.3 FR-2 销量预测（区间预测）

**位置**: 后台 / "预测中心" + 主 Dashboard 内嵌区间图

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| SKU 选择器 | Combo | 默认显示 Top 20 销量 SKU | 多选 + 搜索 + 标签筛选 | 数据源未初始化禁用 |
| 预测窗口 | Slider | 30 天 | 7/30/60/90 可选 | - |
| 预测曲线图 | Chart | 中位数实线 + p10/p90 阴影 + 历史虚线 | hover 显示当日数值与置信区间 | 训练数据 <14 天时只画历史 + 灰色"数据不足" |
| 模型版本 | Tag | 显示当前 model_id + 训练日期 | 点击进 模型详情/对比 | - |
| 重新训练按钮 | Button | 可点（需 admin） | 触发后台 job，进度条 | 上次训练 <6h 内禁用 |
| 特征贡献条 | Bar | 默认折叠 | 展开显示 销量历史/广告/BSR/季节因子 占比 | 模型不支持解释时灰显 |
| 置信度等级标签 | Badge | 高/中/低 | 根据 p90-p10 区间宽度自动 | - |

**交互逻辑**:
1. **模型方案**：分层路由 —— 稳定 SKU（FR-16 输出"稳定"类）用季节性朴素法 + Holt-Winters；波动 SKU 用 LightGBM 分位数回归（quantile 0.1 / 0.5 / 0.9 三个模型同训）；长尾 SKU 直接出"低需求标签 + 安全库存常数"。
2. **特征**：销量历史（滞后 1/7/14/28）/ 7 天均值与标准差 / DOW / 月内位次 / 广告 spend / BSR / 价格 / 是否促销日（外部日历）/ 是否缺货历史日。
3. **训练频率**：每日凌晨 01:00 UTC 增量训练（在线学习的实现：保留模型 + 用最新 30 天微调）；每周日全量重训。
4. **区间→优化引擎对接**：FR-2 输出 `{p10, p50, p90}`；FR-4 引擎在 §5.5 N2 解决方案中明确——"v1 用 p50 求最优 + 用 p10/p90 跑 robust 情景，三套解的差异作为决策稳健度指标"。
5. **置信度→人话翻译**（FR-6 联动）：区间宽度 / p50 ≤ 0.3 → 高；0.3–0.6 → 中；>0.6 → 低。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | SKU 历史 <14 天 | 走"新品冷启动"分支：用同品类均值 ×0.5；标注"低置信度，建议人工确认" |
| 数据异常 | 全 0 历史（从未售出） | 不出预测，进入"长尾"分类（FR-16），决策清单不展示 |
| 数据异常 | 单日异常峰值（>10× p99） | 检测为 outlier，训练前 winsorize（截断到 p99）；UI 标"已修正异常值" |
| 网络异常 | 训练 job 节点崩溃 | 通过 job 重启策略恢复；保留上一个稳定模型快照（不影响在线预测） |
| 并发冲突 | 重训中触发再训请求 | 队列化，第二个请求合并到当前（去重） |
| 第三方失败 | 外部日历（促销日）API 失败 | 该特征 fallback 为 0；模型权重不变 |
| 设备差异 | 移动端图表过窄 | 自动切换为"数值表"形式 |
| 用户操作冲突 | 用户回滚到旧模型时旧模型已被清理 | 弹错并列出可用版本 |

**边界数值**:
- 训练窗口下限：14 天（不足则只出 p50 简单滑动均值）
- 异常值截断：z-score > 6 winsorize
- 模型保留版本数：30 个（roll-off）
- 训练单 SKU 时长上限：30 s；超时记 timeout、用上版本预测
- 区间显示精度：销量单位件，p50 取整；区间下界 max(0, floor(p10))

---

### 5.4 FR-3 经济目标函数实现

**位置**: 后端核心服务"计算引擎 / 目标函数模块"（无独立 UI；通过 FR-6 "可解释面板"间接展示）

**界面元素与展示规则**（仅"参数管理"页 UI）:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 参数列表（5 项 + 3 个全局） | Table | 显示当前值/默认值/单位/最后修改人 | 点编辑弹 Modal | 用户非 admin 只读 |
| 缺货排名恢复倍数 | NumberInput | 3.0（默认） | 区间 [1, 10]，步长 0.1；保存即生效（影响下次计算） | - |
| 年化资金成本率 | NumberInput | 10%（默认） | 区间 [0, 50]，步长 0.5% | - |
| FBA 费率表导入 | FileUpload | 显示当前生效版本日期 | 上传 CSV 替换；保存前自动 diff 显示新旧差异 | 文件格式错时禁用保存 |
| 参数变更历史 | Timeline | 默认最近 10 条 | 可回滚到任意历史版本 | 当前正在跑的决策任务关联的版本不可删 |

**交互逻辑**:
1. **目标函数实现**：采用插件式函数注册 —— 每项成本/收益作为一个 `CostComponent`（输入：决策变量 + 参数 + 预测；输出：标量值 + 梯度签名）；总目标 = Σ components；新增/替换组件不动求解器。
2. **缺货分段**：缺货损失分两段——day 0..14 线性（=日销售额）；day 15..∞ 加 `rank_recovery_multiplier × decay(d)` 项（decay = 指数衰减 30 天衰到 1）。
3. **存储**：所有参数版本化（`parameters` 表 with effective_from / effective_to），决策计算时绑定 snapshot 的参数版本号，确保事后可复现。
4. **单位一致性**：所有金额内部用 USD 微元（micro-USD = 1e-6 USD，整数）避免浮点误差。
5. **目标函数 self-test**：每次发布前跑 50 条预置 case（已知期望值的极简场景），失败则阻断发布。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | FBA 费率表 SKU 体积缺失 | 该 SKU 用品类平均费率，并标 warning |
| 数据异常 | 缺货倍数被改成负数 | 表单校验拦截；后端兜底 max(0.1, x) 并记 audit |
| 并发冲突 | 决策跑到一半参数被改 | 决策绑定参数 snapshot，本次任务不受影响；下次任务用新参数 |
| 权限不足 | 普通用户改参数 | 403 + UI 隐藏编辑按钮 |
| 第三方失败 | 汇率 API 失败 | 用最近 24h 缓存；超 24h 用 30 天均值并标 warning |
| 用户操作冲突 | 回滚参数到已被清理的版本 | 提示并阻止 |

**边界数值**:
- 参数版本保留：100 个 + 永久保留"被引用于已执行决策"的版本
- 单次目标函数评估 < 5 ms（200 SKU × 90 天 × 2 物流方式 = 36000 变量）
- 浮点容差：1e-6 USD

---

### 5.5 FR-4 MINLP 优化引擎

**位置**: 后端核心 / 调度任务（无独立 UI；通过 FR-6 "决策清单"展示结果）+ "求解器监控"管理页

**界面元素与展示规则**（管理页）:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 当前任务进度 | ProgressBar | 0%（无任务）/ 实时百分比 | hover 显示当前阶段（loading/preprocessing/solving/postprocess） | - |
| 历史任务表 | Table | 最近 30 天，倒序 | 列：runId/触发方式/SKU 数/求解时长/状态/decision_id | - |
| 求解器配置 | Panel | 显示当前 backend（SCIP/Gurobi）+ time_limit + gap_tolerance | 改后下次任务生效 | 非 admin 只读 |
| 失败任务详情 | Modal | - | 显示日志 + 求解器 stderr + 重跑按钮 | - |
| 求解性能图表 | Chart | 30 天求解时长趋势 | hover 显示当日详情 | - |

**交互逻辑**:
1. **求解器选型**（响应工程 R3 N1）：v1 默认开源 SCIP（Python via `pyscipopt`）；如 license 允许 fallback Gurobi（更快）；接口抽象为 `IOptimizer`。
2. **问题形式化**：
   - 决策变量：`x_s,t,m ∈ Z_+`（SKU s × 时间窗 t × 物流方式 m）；时间窗 t 用周聚合（13 周 = 90 天）降维。
   - 目标：max Σ (revenue - cost components)
   - 约束：库存平衡递推；FBA Restock Limit；总资金；批量经济量（订单最小起订）。
3. **维度控制**：200 SKU × 13 周 × 2 物流 = 5200 整数变量（远低于 36000 周日级，对应 §10.B 性能需求）。
4. **预处理**：对超低需求 SKU（FR-16 长尾）跳过优化直接走规则；对当前库存 >120 天可卖的 SKU 跳过。
5. **后处理**：将 t（周）拆分回当周内的最早可发日；输出含 per-SKU 的成本/收益拆解（喂给 FR-6 可解释面板）。
6. **接口阻抗**（响应工程 R3 N2）：v1 用 p50 求基础解；用 p10/p90 各跑一次得到"乐观/悲观"对照解；输出"基础决策 + 三场景差异"。Robust optimization 留 v1.5。
7. **缓存**：相同 input_hash（snapshot_id + params_version + 预测版本）24h 内命中缓存。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 模型 infeasible（约束冲突，如 Restock Limit < 必须补量） | 自动放松"软约束"（按优先级：先放总资金 +20%，再放 Restock Limit），并在结果里标注"约束放松" |
| 数据异常 | 求解器返回 unbounded | 阻断；通知管理员；fallback 用上次决策 |
| 第三方失败 | 求解器进程崩溃 / OOM | 监控 + 自动重启 1 次；二次失败上报 P0 |
| 并发冲突 | 同一 snapshot 被两个调度同时触发 | 分布式锁（Redis SETNX, TTL 30min）；后到的等待并复用结果 |
| 性能 | 求解超时（>30 min） | 接受次优解（current best），并标"未达最优 gap = X%" |
| 用户操作冲突 | 用户点"重跑"时上一个任务未结束 | 提示"上一个任务进行中"或选"取消并重跑" |
| 设备差异 | 管理页移动端宽度不足 | 关键列固定，详情进二级页 |

**边界数值**:
- 单次求解时长上限：1800 s（30 min）
- gap 容忍：默认 1%（即接受 1% 内的次优）
- 内存峰值：< 8 GB
- 并发任务上限：1（v1 单租户单实例）
- 求解输入缓存 TTL：24 h

---

### 5.6 FR-5 灵敏度分析模块

**位置**: 后端模块 + Dashboard 二级 Tab "灵敏度"

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 参数选择 Chip 组 | Chip Group | 默认勾选 "缺货倍数 / 资金成本率 / 销量 p50" | 多选触发重跑 | 优化引擎任务进行中禁用 |
| 扰动范围 | RadioGroup | ±20% | ±10/±20/±30/自定义 | - |
| 龙卷风图（Tornado Chart） | Chart | 横向条形，按参数对总收益的影响排序 | hover 显示当前+扰动后的总收益数值 | 无最近一次基础决策时禁用 |
| 决策稳定性指标 | Card | 显示"核心决策稳定率 X%" | hover 解释计算口径 | - |
| 单 SKU 决策切换表 | Table | 默认隐藏 | 展开显示"参数扰动后变更物流方式或数量的 SKU 清单" | - |
| 跑灵敏度按钮 | Button | 可点 | 触发后台 batch 任务 | 上次跑 <30min 内禁用 |

**交互逻辑**:
1. **执行模式**：each-at-a-time（一次扰动一个参数）+ 关键参数组合扫描（默认 3 个关键参数的 3³ = 27 个场景）。
2. **核心决策稳定率定义**："核心决策" = top-30 总成本 SKU 的"是否发货 + 物流方式" 二元决策；稳定率 = (扰动后与基础一致的核心决策数) / 30。
3. **结果存储**：灵敏度 run 是独立 entity（`sensitivity_runs`），关联到基础 decision_id；保留 90 天。
4. **触发时机**：每日基础决策后自动跑一次（凌晨 03:00 UTC）；用户也可手工触发。
5. **可解释面板**联动：FR-6 单条建议里嵌"该建议在 ±20% 扰动下稳定/不稳定"小图标。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 性能 | 27 场景 × 30 min = 13.5h 超长 | 默认采用启发式：基础解为热启动 + warm-start MIP；目标 27 场景 < 60min |
| 数据异常 | 某个扰动场景 infeasible | 该场景标"infeasible"，不计入稳定率分母 |
| 并发冲突 | 用户手工触发与定时任务冲突 | 队列化 |
| 第三方失败 | 求解器在第 N 个场景失败 | 跳过该场景，记 log；不影响其他 |
| 设备差异 | 龙卷风图在小屏失真 | 切换为表格视图 |

**边界数值**:
- 单场景求解时长（heuristic）：≤ 120 s
- 总 batch 时长上限：3600 s（1h）
- 稳定率统计 SKU 数：top 30（按总成本）

---

### 5.7 FR-6 决策清单 + 可解释面板

**位置**: 主 Dashboard 首页"今日决策" Tab

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 顶部摘要卡片 | Card | "今日扫描 200 SKU，建议发货 N 项，预估总收益影响 +$X" | 数据更新时间戳 + Mock/Real 模式徽章 | 无最近决策时显示空态 |
| 决策清单 | Table | 默认按"建议优先级"倒序（高/中/低 = 红/橙/绿） | 列：SKU/当前库存/可卖天数/建议数量/物流/置信度/预估收益/操作 | 决策任务跑挂时显示"昨日 11:23 决策"+ 红条 |
| 空清单态 | EmptyState | "今日 200 SKU 都健康，最近临界 SKU 还有 45 天" + 库存全景缩略图 | 点缩略图进 FR-9 仪表盘 | - |
| 单条操作按钮组 | ButtonGroup | "接受/调整/改物流/跳过/查看详情" | 点"调整"弹数量输入 Modal；改后实时重算 landed cost 并显示新预估收益；接受/跳过后该行折叠+置灰 + 决策状态变 PendingExecution | "已执行"行禁用所有操作 |
| 批量选择框 | Checkbox | 未勾 | 勾选后顶部出现"批量接受 N 条"按钮（联动 FR-14） | 用户非 decision_owner 时禁用 |
| 可解释面板（侧抽屉） | Drawer | 关闭 | 点行展开，分 3 层：①一句话理由 ②6 项收益/成本分解条形图 ③数学展开（公式 + 参数版本 + 预测区间 + 灵敏度小图） | - |
| "今日已决"折叠区 | Section | 默认折叠 | 展开看今日已处理的决策（含跳过原因） | - |
| 信息密度切换 | Toggle | 精简（默认） | 切换"详细" → 表格多 4 列（资金成本/仓储费/缺货损失/运费），切换"专业"显示数学符号 | - |

**交互逻辑**:
1. **三层信息分层**（响应设计 R3）：摘要 30 秒 / 决策清单 5 分钟 / 可解释面板 数学层（专业模式）。
2. **拍板交互闭环**：
   - "接受" → 写 `decisions` 表 status=accepted，触发 FR-7 助理任务创建
   - "调整数量" → 弹 Modal 输入新数量；实时重算 landed cost / 预估收益 / 置信度变化；保存后状态 = accepted_modified（带原值与新值 diff）
   - "改物流" → 切换 sea↔air；后端重算成本并显示对比"原方案 $X vs 现方案 $Y"
   - "跳过" → 必须填原因（下拉 + 自由文本，可不填但 UI 提示）；status = skipped
   - "查看详情" → 抽屉
3. **置信度文案**：高 = "本建议在多场景下稳定，可放心执行"；中 = "本建议受 1-2 个参数较大影响，建议看下详情"；低 = "本建议不稳定，建议人工判断"。
4. **landed cost 实时重算**：前端送参数 → 后端 `/preview-decision` API（< 200ms）；前端 debounce 300ms。
5. **空清单设计**：除"今日健康"文字外，下方展示"未来 7/14/30 天最早到临界 SKU"倒计时（来自 FR-15）。
6. **决策版本**：每次基础决策跑出来后，原本未处理的"昨日清单"自动归档（标 superseded）；用户拍板的已 accepted 不受影响。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 决策清单后端返回但缺关键字段（如预估收益 null） | 该行显示"数据异常"+ 灰色 + 禁用接受 |
| 网络异常 | "调整"重算 landed cost 接口超时 | 输入框旁红字提示，按钮禁用；3 秒后允许重试 |
| 并发冲突 | 用户接受某条时该条已被助理标"已执行" | 弹"已被执行，刷新查看最新状态" |
| 并发冲突 | 同时打开两个 tab 各自拍板 | 后端用 decision_id + version 乐观锁；后到的提示冲突 |
| 权限不足 | 助理打开本页 | 仅可"查看"，所有操作按钮置灰；顶部提示"无拍板权限" |
| 第三方失败 | 求解器昨晚失败导致今日无清单 | 顶部红条 "决策任务昨夜失败" + "查看原因"链接 + "用前日决策"按钮 |
| 设备差异 | 移动端表格无法横滚 | 切换"卡片视图"：每条决策为卡片（SKU/数量/物流/操作） |
| 用户操作冲突 | "调整数量"调到 0 | 拦截：提示"请用'跳过'代替 0 数量" |
| 用户操作冲突 | 重复接受同一条 | 幂等键（decision_id+action）防重 |

**边界数值**:
- 单页最大显示：200 条；超出分页
- "调整"数量上限：建议值 × 3（防误输入）
- 操作日志：永久保留
- API 响应 < 500ms（清单加载），< 200ms（preview-decision）

---

### 5.8 FR-7 助理操作视图 + 状态回写

**位置**: 助理专用工作台（独立顶部菜单"待办" Tab；权限 = assistant role）

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 待办列表 | Table | 按"截止时间"升序；列：SKU/数量/物流/截止/CEO 备注/状态 | 点行进详情/操作 | 无授权时整页 403 |
| 状态徽章 | Badge | pending（蓝）/in_progress（黄）/shipped（绿）/blocked（红）/returned（灰） | - | - |
| 操作按钮 | ButtonGroup | "标记派单/标记执行中/标记已发货/标记问题"+ "退回 CEO（24h 否决权）" | 每个操作弹确认 + 备注输入；保存后 broadcast 给 CEO 视图（FR-6） | "已发货"或"已退回"后操作禁用 |
| 附件上传 | FileUpload | - | 发货后必须上传"运单号 + 截图"，否则状态不能进 shipped | - |
| 时间线 | Timeline | 显示该决策从 accepted → 各状态的时间戳 + 操作人 | - | - |
| 24h 否决倒计时 | Countdown | 显示自 accepted 起的倒计时 24h | 倒计时归零后"退回 CEO"按钮禁用 | - |

**交互逻辑**:
1. **状态机**：accepted → pending → in_progress → shipped；任何状态可 → blocked（带原因）；24h 内可 → returned_to_ceo（FR-7 助理否决权，响应商业 R3）。
2. **状态回写**：助理操作后 webhook 推送到 CEO 视图实时刷新（WebSocket / SSE）。
3. **运单信息**：shipped 状态写入 `shipments` 表：tracking_no、carrier、eta、proof_attachment_url。
4. **数据隔离**：助理只能看自己被分配 SKU 的决策；CEO 全可见。
5. **退回 CEO**：弹 Modal 必填原因 + 建议（如"建议数量改 100"）；CEO 视图收到新通知，原决策恢复 pending_review。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 网络异常 | 状态保存请求超时 | 本地暂存 + 重试 3 次；失败提示"网络问题，请检查后重试" |
| 数据异常 | 附件超过 10 MB | 拦截 + 提示压缩 |
| 数据异常 | 运单号格式不合法 | 简单正则校验（≥6 字符）；通过即接受（不强校验各承运商） |
| 权限不足 | 助理尝试操作非分配给自己的决策 | 403 + 提示 |
| 并发冲突 | 两个助理同时改同一条 | 乐观锁；后到的提示冲突 + 显示对方修改 |
| 第三方失败 | WebSocket 断连 | 自动重连（指数退避）+ 状态轮询兜底（30s 一次） |
| 设备差异 | 助理在手机上操作 | 移动端单卡片 + 大按钮设计 |
| 用户操作冲突 | 助理"已发货"后 CEO 还想改 | 阻止 CEO 编辑；提示"已发货，需新建决策或联系助理" |

**边界数值**:
- 单附件大小：10 MB；图片 + PDF
- 退回 CEO 时限：24 h（从 accepted 起）
- 一条决策最多状态切换：20 次（防滥用）

---

### 5.9 FR-8 缺货预警系统

**位置**: 后台监控任务 + 顶部"预警铃铛" + 独立"预警中心"页

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 顶部铃铛 | IconButton | 未读数徽章（红） | 点开下拉看最新 5 条 | 无未读时无徽章 |
| 预警中心列表 | Table | 倒序时间；列：触发时间/SKU/类型/严重度/可卖天数/操作 | 行点击进 FR-6 详情 | - |
| 严重度徽章 | Badge | critical（红）/ warning（橙）/ info（蓝） | - | - |
| 静音控制 | Panel | 默认全开 | 按 SKU/全局 设置静音 + 时长（1h/8h/24h/直到下次决策） | - |
| 聚合配置 | Form | 默认 5 分钟聚合窗口 | 1/5/15/60 min 可选 | 非 admin 只读 |
| 推送渠道配置 | Form | 默认企微 + Bark | 多选；测试发送按钮 | 渠道未配置 token 时禁用 |

**交互逻辑**:
1. **触发规则**（3 类）：
   - 库存可卖天数 ≤ 安全阈值（默认 21 天，per SKU 可配） → critical
   - 销量 7 日均值 > 历史 30 日均值 × (1+x%) 且 x ≥ 50%（默认 50%） → warning
   - 物流报价单价变动 > 20%（环比上次） → info
2. **聚合**（响应设计 R1 D6）：5 分钟窗口内同一 SKU 的多个预警合并为一条；多 SKU 同类型合并为"5 个 SKU 触发库存预警 [展开列表]"。
3. **去重 vs 日报**（响应工程 R3 反驳设计 R1）：**预警与日报独立 entity，不合并到收件箱**。但 FR-6 决策清单中"已触发预警的 SKU"行加红色左边框 + 小铃铛图标，形成视觉关联。
4. **推送渠道**（响应商业 R1 B6）：默认企微应用 / Bark / Telegram；每渠道独立模板；失败 fallback 到下一个渠道。
5. **静音**：写 `mute_rules`（scope=sku|global, until=ts）；推送前查 rule。
6. **SLA**：从触发到推送 ≤ 15 分钟（覆盖锚点 §3.2 的"立刻"，与原"1 小时"冲突取严）。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 历史 30 天数据缺失 | 跳过该 SKU 的"销量异常"规则；记 warning |
| 网络异常 | 推送渠道不可达 | 重试 3 次（1s/4s/16s）+ fallback；全失败时写本地未送达队列 + 顶部铃铛红色异常徽章 |
| 第三方失败 | 企微 token 过期 | 自动尝试 refresh；失败标渠道为"异常"并通知 admin |
| 并发冲突 | 同时触发与静音设置 | 静音以触发时刻 query 为准 |
| 权限不足 | 助理改聚合配置 | 403 |
| 设备差异 | 移动端弹窗推送 | iOS 走 Bark，Android 走企微 |
| 用户操作冲突 | 静音规则与紧急 critical | critical 级别可配置"穿透静音"（默认开） |

**边界数值**:
- 触发到推送 SLA：≤ 15 min（含聚合等待）
- 单 SKU 同类预警节流：1 小时内最多 1 条
- 历史保留：180 天
- 推送渠道并发：3 个并行

---

### 5.10 FR-9 周报 Dashboard

**位置**: 主菜单"周报"页（每周一上午自动生成）

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 周报选择器 | DateRange | 默认本周 | 切换历史周 | 无历史数据时禁用 |
| 摘要卡片组 | CardGrid | 4 卡：决策数 / 接受率 / 总收益预估 vs 实际 / 缺货事件 | hover 显示同比/环比 | - |
| 库存全景表 | Table | 200 SKU 全量；列：SKU/库存/可卖天数/趋势 sparkline/类别（FR-16） | 排序 + 筛选 + 导出 CSV | - |
| 三策略对比卡 | Card | 来自 FR-11 | 点进 FR-11 详情 | 无回测数据时灰显 |
| 决策日志查看 | Section | 折叠；展开看本周决策的逐条事后正确率（FR-12） | - | - |
| PDF 导出按钮 | Button | 可点 | 生成 PDF（含 chart） | 生成中禁用 |

**交互逻辑**:
1. **生成时机**：每周一 09:00 Asia/Shanghai 定时任务；含上周数据全闭环。
2. **指标计算**：覆盖锚点 §5.1 北极星（缺货天数 / 周转 / 物流成本）+ 锚点 §5.2 体验（接受率 / 响应延迟）。
3. **导出**：PDF 用服务端渲染（Puppeteer），CSV 用 streaming export 避免内存爆。
4. **空数据态**：v1 用 mock，3 周前没数据则展示 "回测演练数据" 标签。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 某指标无法计算（除 0） | 显示"–"+ tooltip 解释 |
| 网络异常 | PDF 生成超时 | 显示"生成失败"+ 重试按钮 |
| 并发冲突 | 周报生成中触发再生成 | 队列化 |
| 设备差异 | 移动端表过宽 | 关键列固定 + 横向滚动 |
| 用户操作冲突 | 用户查看时后台正在重生成 | 显示"正在更新"提示，不阻塞读 |

**边界数值**:
- 周报历史保留：永久（每周 1 个 snapshot）
- PDF 大小上限：20 MB
- 生成时长：< 60 s

---

### 5.11 FR-10 Mock/Real 模式切换

**位置**: 全局（顶部固定栏 + 设置页 + 全 UI 视觉差异）

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 顶部斑马条 | Banner | Mock 模式：黄黑斑马条 + "演练数据 · 决策不影响真实库存" | Real 模式：无条 | - |
| 模式徽章 | Tag | 所有页面右上角，Mock=黄、Real=绿 | 点击可跳设置页 | - |
| 设置页切换器 | Switch | 当前模式 | 切到 Real 弹二次确认（输 "我确认" 文字） + 记 audit | Real 数据源未完成接入时 Real 档禁用 |
| 数据来源指示 | Footer | 每个数据展示下方："数据来源：Mock 生成器 v2.3" 或 "数据来源：FBA API 2026-05-23 02:00 UTC" | - | - |
| Mock 数据生成器参数页 | Form | 默认参数（销量分布/库存初值/广告波动等） | 调整后下次生成生效 | Real 模式下禁用 |

**交互逻辑**:
1. **隔离**：Mock / Real 模式数据物理隔离（独立 schema 或独立 DB）；切换前 flush 缓存。
2. **影子模式**（FR-13 联动）：影子模式 = Real 模式的子集，标记为 shadow=true 的 SKU 子集，不污染主数据。
3. **决策输出隔离**：Mock 模式下生成的决策决不进入 FR-7 助理视图（即使有助理账号）。
4. **审计**：所有切换写 audit_log。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 权限不足 | 非 admin 切换模式 | 按钮禁用 + 提示 |
| 数据异常 | Real 数据源未就绪强切 Real | 阻断 + 提示"数据源未完成接入" |
| 并发冲突 | 切换瞬间有任务在跑 | 等待任务完成或允许"取消任务后切换" |
| 用户操作冲突 | 切到 Mock 但助理已经在执行 Real 决策 | 阻断 + 提示"有 N 条 Real 决策待执行" |
| 设备差异 | 移动端斑马条遮挡内容 | 折叠为图标 + 长按展开 |

**边界数值**:
- 模式切换冷却：30 s（防误切）
- 二次确认文字：固定 "我确认"

---

### 5.12 FR-11 三策略回测

**位置**: "回测中心"独立页

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 回测配置 | Form | 数据集（mock/影子）/ 时间窗（默认 90 天）/ 策略选择（系统/保守/激进 三选必勾系统） | - | - |
| 跑回测按钮 | Button | 可点 | 触发 job + 进度条 | 上次跑中或 <10min 内禁用 |
| 结果对比图 | Chart | 三策略的累计总收益曲线 + 缺货次数柱图 + 库存价值面积图 | hover 显示日数据 | 无结果时占位 |
| 关键指标表 | Table | 列：策略/缺货天数/库存周转/物流成本/总收益 | 排序 | - |
| 一句话结论 | Card | "系统策略相比保守策略 +X%，相比激进 +Y%" | hover 看计算口径 | 无显著差异时显示"差异不显著" |
| 历史回测对比 | Table | 列出过往回测，可选择"对比两次" | - | - |

**交互逻辑**:
1. **策略定义**：
   - 系统策略 = FR-4 引擎输出
   - 保守策略 = 维持 ≥ 60 天可卖库存，全海运
   - 激进策略 = 维持 ≥ 14 天，缺货前 5 天空运
2. **回测引擎**：模拟时间推进（天）→ 每天用当日 snapshot 跑当日策略 → 累计每日的销售/成本 → 周末汇总。
3. **统计显著性**：跑 N 次（默认 30 次 mock，影子模式 1 次）；输出均值 ± 95% CI。
4. **数据复现**：回测 job 绑定 snapshot + 参数 + 模型版本，可一键"重跑此回测"。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 历史数据 <30 天 | 拒绝跑 + 提示"数据不足" |
| 性能 | 单次回测 > 30 min | 接受超时；标 partial 结果 |
| 并发冲突 | 同时跑多个回测 | 队列化（v1 单实例顺序执行） |
| 第三方失败 | mock 生成器异常 | 中断 + 报错 |
| 设备差异 | 移动端图表过宽 | 切表格 |
| 用户操作冲突 | 删除被引用的 snapshot | 阻止 |

**边界数值**:
- 单次回测时长：< 30 min
- 历史回测保留：50 次

---

### 5.13 FR-12 周复盘报告

**位置**: 周报页内 Section + 独立"复盘"邮件

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 复盘清单 | Table | 上周所有决策；列：SKU/系统建议/实际执行/事后实际销量/正确性评分 | 排序 + 筛选（仅看错的） | - |
| 正确性评分 | Badge | 正确（绿）/ 部分正确（黄）/ 错误（红） | hover 显示评分依据 | - |
| 人工标注按钮 | Button | "我的判断"（用户可覆盖系统评分） | 弹文本框 | - |
| 一句话总结卡 | Card | "上周系统建议正确率 X%，主要误差来自 SKU XX 的销量低估" | - | - |
| 邮件订阅 | Toggle | 默认每周一 08:00 推送邮件 | 关闭即不发 | - |

**交互逻辑**:
1. **正确性评分算法**（替代"接受率 70%"）：
   - 系统建议数量 ≤ 实际需求 × 1.2 且 ≥ 实际需求 × 0.8 → 正确
   - 否则按偏差比例打分 → 部分正确 / 错误
   - 物流方式：实际未缺货 → 选海运算正确；缺货 → 必须空运
2. **数据延迟**：复盘需要 7-14 天后的"实际销量"才能算分；用户在第 N+14 天看到第 N 周完整复盘。
3. **影子模式特殊处理**：影子 SKU 的复盘单列（与 mock 隔离）。
4. **学习闭环**：用户标注的 "我的判断" 进入训练反馈池（FR-2 v1.5 增量训练用）。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 实际销量未回流 | 该行标"待回流"，不评分 |
| 网络异常 | 邮件发送失败 | 重试 3 次 + 站内信兜底 |
| 权限不足 | 助理覆盖正确性评分 | 仅 CEO 可改 |
| 并发冲突 | CEO 与系统同时标注 | 以最后时间戳为准 |
| 设备差异 | 移动端邮件查看 | 邮件模板 responsive |

**边界数值**:
- 复盘等待期：14 天
- 复盘记录保留：永久

---

### 5.14 FR-13 影子模式

**位置**: 设置页 + Dashboard 独立 Tab "影子 SKU"

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 影子 SKU 列表 | Table | 显示 shadow=true 的 SKU；列：SKU/类别（高/中/低 + 缺货事故）/纳入时间 | 添加/移除按钮 | 仅 admin 可编辑 |
| 添加 SKU Modal | Form | 选 SKU + 标类别（必填） | 保存 | - |
| 影子决策清单 | Section | 与主决策清单平行；独立颜色（紫色边框） | 用户人工录入"我的实际决策"做对照 | - |
| 对照差异表 | Table | 列：日期/SKU/系统建议/我的决策/差异原因 | - | - |
| 数据资金池配置 | Form | 影子资金池 独立 $X | 改后下次决策生效 | - |

**交互逻辑**（响应工程 R3 N3 + 商业 R3）:
1. **数据双轨**：影子 SKU 的真实数据通过手工 CSV 上传 / 简化 API 接入；与 mock 物理隔离。
2. **资金池隔离**：影子有独立 capital_pool，FR-4 求解器对 mock 与 shadow 分两次求解（不混算）。
3. **选择规则**（PRD 硬性）：必须至少 4 个 SKU = 高销量稳定 1 + 中销量波动 1 + 低销量长尾 1 + 最近 90 天有缺货事故 1。
4. **对照录入**：影子模式下用户每天在影子决策清单旁手工录"我的实际决策"；进入复盘比对池。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 手工录入数据校验失败 | 表单拦截 + 提示 |
| 权限不足 | 普通用户加影子 SKU | 403 |
| 并发冲突 | CEO 与助理同时录入实际决策 | 仅 CEO 可录 |
| 用户操作冲突 | 移除有未完成对照的 SKU | 弹"该 SKU 有 N 条未完成对照，确认移除？" |
| 设备差异 | 移动端录入界面 | 单字段卡片 |

**边界数值**:
- 影子 SKU 数：4 ~ 20
- 资金池隔离：独立预算

---

### 5.15 FR-14 批量接受 + 责任回路

**位置**: FR-6 决策清单顶部"批量接受"按钮 + 周复盘"批量决策回顾" Section

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 批量接受按钮 | Button | 隐藏；勾选 ≥2 条后出现 | 点击弹确认 Modal | 选中含"低置信度"项时禁用并提示 |
| 确认 Modal | Modal | 显示选中条目摘要 + "需输入'我确认批量接受 N 条'文字" | 确认后批量 status=accepted；记 batch_id + 操作人 + 时间 | - |
| 默认批量条件 | Setting | "置信度 ≥ 高 + 灵敏度稳定 + 数量 ≤ 安全阈值" | 可调 | - |
| 批量决策标签 | Badge | 批量接受的决策行加 "batch" 紫色徽章 | - | - |
| 周复盘批量回顾 Section | Section | 默认折叠 | 展开列出本周所有批量决策 + 正确率单算 | - |
| 助理 24h 否决权按钮 | Button | 在 FR-7 助理视图，批量决策行额外显示"批量异议→退回 CEO" | 退回时必填原因 | 超 24h 禁用 |

**交互逻辑**（响应商业 R3）:
1. **批量条件强约束**：默认仅"高置信度 + 灵敏度稳定 + 数量 ≤ 安全阈值"的决策可被批量接受；UI 上其他行的批量勾选框置灰。
2. **责任回路**：
   - 批量接受时强制确认文字，避免误点
   - 助理 24h 内可整批/单条退回 CEO（带原因）
   - 周复盘"批量决策" Section 必看：单列批量正确率、超过 2 条错误时弹提示"建议调整批量条件"
3. **批量审计**：batch_id 关联所有子决策，可追溯。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 并发冲突 | 批量接受时某条已被单独跳过 | 跳过该条，其余正常；返回执行报告 |
| 数据异常 | 批量内某条数据失效（库存数据已变） | 跳过该条，提示 "X 条因数据更新被跳过" |
| 权限不足 | 助理点批量接受 | 按钮不可见 |
| 用户操作冲突 | 批量接受与单条"调整"竞争 | 单条改优先生效；批量内其余不变 |
| 设备差异 | 移动端 Modal 文字输入 | 大键盘 + 自动聚焦 |

**边界数值**:
- 单次批量上限：50 条
- 助理否决时限：24 h
- 批量条件可配置项：3 个（置信度/灵敏度/数量阈值）

---

### 5.16 FR-15 60/90 天上游下单预警

**位置**: 预警中心独立 Tab "上游下单" + 周报内嵌

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| 长期预警列表 | Table | 列：SKU/当前库存/预计可卖天数/建议下单时间/建议数量/严重度 | 排序 + 筛选 | - |
| 时间轴视图 | Timeline | 横向时间轴显示未来 90 天各 SKU 临界日 | hover 看详情 | - |
| 严重度规则配置 | Form | 默认：60 天=warning，90 天=info | 可调 per SKU | 非 admin 只读 |
| 导出工厂下单建议 | Button | CSV 导出 | - | 列表为空时禁用 |

**交互逻辑**:
1. **算法**：当前库存 + 在途 + 已 accepted 但未到货 - 预测 t 天累计需求 < 0 时触发；t = 60 / 90。
2. **聚合**：每日凌晨一次扫描（与 FR-4 同 batch）。
3. **下单建议数量**：基于 v1.5 工厂产能（v1 暂不算），v1 仅提示"建议尽快下单 X 件"，X = 后 120 天需求预估。
4. **与 FR-8 区别**：FR-8 是"短期紧急"（21 天内），FR-15 是"长期规划"（60-90 天）。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | 在途数据缺失 | 按 0 计 + 标 warning |
| 网络异常 | 预测数据不可用 | fallback 用 30 日均值 |
| 并发冲突 | 配置与扫描同时改 | 扫描以开始时刻参数为准 |
| 权限不足 | 助理改严重度规则 | 403 |
| 设备差异 | 时间轴在小屏不可读 | 切换为列表 |

**边界数值**:
- 扫描频率：每日 1 次
- 提前预警窗口：60/90 天

---

### 5.17 FR-16 SKU 自动分类

**位置**: SKU 主数据页 + Dashboard 内嵌

**界面元素与展示规则**:

| 元素 | 类型 | 默认态 | 操作后 | 禁用条件 |
|---|---|---|---|---|
| SKU 分类徽章 | Badge | 4 类：稳定（绿）/波动（橙）/季节性（蓝）/长尾（灰） | - | - |
| 分类规则查看 | Panel | 显示当前规则（销量变异系数 / BSR 波动 / 月销量绝对值） | admin 可改 | - |
| 人工覆盖 | Button | 每 SKU 一个"我标注"按钮 | 选类别 + 备注 | - |
| 分类历史 | Timeline | 该 SKU 的分类变化历史 | - | - |
| 全量分类报告 | Table | 200 SKU 全表 + 分类 + 上次更新时间 | 导出 CSV | - |

**交互逻辑**:
1. **规则**（v1 用规则，v1.5 可上 ML）：
   - 月销量 < 5 → 长尾
   - CV (变异系数 = std/mean) < 0.3 → 稳定
   - CV ≥ 0.3 且 季节性指数（autocorr at lag 30/90） > 0.5 → 季节性
   - 否则 → 波动
2. **分类影响**：路由到不同预测模型（FR-2 §5.3 交互逻辑 1）；影响 FR-4 求解优先级（长尾跳过）。
3. **更新频率**：每周日重算。
4. **人工覆盖**：高优先级，覆盖期 90 天后失效（防永久错配）。

**异常场景**:

| 类型 | 场景 | 处理 |
|---|---|---|
| 数据异常 | SKU 历史 <30 天 | 标"待观察"，默认走"长尾"模型保守 |
| 并发冲突 | 自动分类与人工覆盖 | 人工覆盖期内自动分类不生效 |
| 权限不足 | 助理改分类 | 403 |
| 设备差异 | 全表导出在移动端 | 异步生成 + 邮件发送链接 |
| 用户操作冲突 | 用户分类与决策推断冲突 | 以用户为准 |

**边界数值**:
- 重算频率：每周
- 人工覆盖有效期：90 天

---

## §7 边界与异常场景

### 7.1 数据边界

| 维度 | 上限 | 下限 | 越界处理 |
|------|------|------|---------|
| SKU 总数 | 1000（v1 设计目标 200，预留 5× 余量） | 1 | 超上限拒绝写入 + 容量预警 |
| 单 SKU 历史数据 | 730 天 | 0 | 超上限滚动归档；0 走冷启动 |
| 单次决策窗口 | 90 天 | 7 天 | 超界 UI 校验 |
| 库存数量 | int32 max | 0 | 负数拒绝 |
| 金额（micro-USD） | int64 max | 0 | 同上 |
| 数据延迟容忍 | 24 h | - | 超 24h 顶部红条 + 阻断高敏决策 |
| 时区 | 全球任意 IANA tz | - | 未知 tz 默认 UTC + warning |
| 浮点精度 | - | 1e-6 USD | 小于精度忽略 |

### 7.2 并发与冲突

| 场景 | 策略 |
|------|------|
| 同决策被多人拍板 | 乐观锁 + version 字段；后到 409 + 显示差异 |
| 同 SKU 多预警短时触发 | 5min 窗口聚合 |
| 同数据源被多个 sync 触发 | 分布式锁（Redis）+ 去重 |
| 同求解任务被重复触发 | input_hash 去重 + 缓存复用 |
| 参数改动与决策计算 | 决策绑定参数版本快照 |
| 助理与 CEO 同时改一条决策 | 状态机约束：助理只能在 accepted→shipped 链；CEO 不能改 in_progress 之后 |
| 同一 batch 内部分被改 | 单条改优先，其他保持 |
| 跨 tab 操作 | 通过 WebSocket 广播 + 本地 toast 通知"另一端已修改" |

### 7.3 第三方依赖失败

| 依赖 | 失败模式 | 缓解 | 监控 |
|------|---------|------|------|
| FBA Reports API | 5xx / 限流 / 超时 | 指数退避 + 上次快照 fallback + P1 告警 | 成功率 / 平均延迟 |
| 求解器（SCIP/Gurobi） | OOM / 崩溃 / license 过期 | 自动重启 + 双引擎 fallback + license 7 天前预警 | 求解时长 / 失败率 |
| 推送渠道（企微/Bark/Telegram） | API 返错 / token 失效 | 多渠道 fallback + 失败队列 + token 自动 refresh | 各渠道成功率 |
| 汇率 API | 不可达 | 24h 缓存 → 30 天均值 → 标 warning | 缓存命中率 |
| 货代/海运/空运报价 | v1 无真实接入 | 用户手工录入 + 周更提醒 | 报价新鲜度（>7 天 warning） |
| 对象存储（附件） | 上传失败 | 重试 + 本地暂存 | 上传成功率 |
| WebSocket（实时推送） | 断连 | 自动重连 + 30s 轮询兜底 | 连接稳定时长 |
| 数据库 | 主库故障 | 读从库降级（只读模式 UI） + P0 告警 | 主从延迟 |

### 7.4 平台与设备差异

| 平台 | 适配策略 | 限制 |
|------|---------|------|
| 桌面 Web（Chrome/Edge ≥ 100） | 主力适配 | 全功能 |
| Safari ≥ 15 | 适配 | 部分图表降级（无 WebGL） |
| 移动 Web（iOS/Android） | 响应式：列表→卡片、宽表→关键列+横滚 | 不支持批量接受复杂操作（建议桌面） |
| PWA 安装 | v1.5 考虑 | v1 不做 |
| 邮件渲染 | responsive HTML | 不依赖 JS |
| 推送：Bark | iOS only | 需 Bark App |
| 推送：企微 | iOS/Android | 需企微账号 |
| 时区差异 | 用户设置覆盖 | 默认 Asia/Shanghai |
| 语言 | v1 仅 zh-CN | i18n key 预留 |

### 7.5 极端情况

| 情况 | 处理 |
|------|------|
| 所有 SKU 同时缺货（系统性事件） | 决策清单分批生成（每 50 SKU 一组）；不阻塞 UI |
| 求解器返回数千条建议 | 默认显示前 100，其余分页 |
| 用户长时间不操作（session 超时） | 24h 自动登出；未保存的"调整"草稿本地缓存 |
| 数据源整月不可用 | 进入"只读历史"模式，禁用新决策 |
| 模型完全错误（连续 7 天正确率 < 30%） | 自动降级到"朴素移动均值" + 顶部红条 + P0 告警 |
| 助理离职 / 账号停用 | 待办自动归还 CEO 池；不丢数据 |
| 数据存储满 | 90 天前快照自动归档冷存；触发清理告警 |
| 网络全断 | 离线模式：只读本地缓存最近 24h 数据；不允许新决策 |
| 时钟漂移 | NTP 同步检查；漂移 > 30s 报警 |
| 跨夏令时切换 | 业务日切按 PST/PDT 动态；切换日单独标记 + 测试覆盖 |

---

## §9.D 技术债

### 优先级 1（必须解决，阻塞发布或留隐患）

| ID | 技术债 | 原因 | 解决方式 |
|----|--------|------|---------|
| TD-1 | MINLP 求解器学科难度 | 工程 R3 N1：从 LP→MINLP 是质变 | **2 周技术 spike**（强制门）：20 SKU 端到端跑通；spike 不过则砍范围或转包 |
| TD-2 | 区间预测 → 点估计求解器的接口阻抗 | R3 N2 | v1 用三场景对照（p10/p50/p90 各跑一次），不做 robust optimization |
| TD-3 | 数据 Schema 按真实 FBA API 反向设计 | T7：v1.5 重构风险 | v1 阶段 1 必产出 schema doc + 反向 mock |
| TD-4 | Mock vs Shadow 物理隔离 | R3 数据双轨 | 独立 schema / 独立 capital_pool |
| TD-5 | 时区一致性（UTC 入库 + PST 业务日） | T8 | 全链路打 utc_ts + business_date_pst 两个字段 |
| TD-6 | 参数版本与决策快照绑定 | R3 复现性 | 每决策记 params_version_id |

### 优先级 2（可延后到 v1.1 / v1.5）

| ID | 技术债 | 延后原因 |
|----|--------|---------|
| TD-7 | 真实数据 API 接入 | 锚点 §1.5 明确 v1.5 |
| TD-8 | Robust optimization / Stochastic programming | v1 三场景对照已可用 |
| TD-9 | 在线增量学习（FR-2 模型每日微调） | v1 用每周全量重训也够 |
| TD-10 | 多租户 / SaaS 化 | 锚点 §1.5 明确 v1.5+ |
| TD-11 | PWA 离线模式 | v1 仅桌面主力 |
| TD-12 | i18n 英文 | v1 仅中文 |
| TD-13 | 模型可解释性（SHAP 等） | v1 用特征贡献条简化 |
| TD-14 | 求解器云原生化（k8s 弹性） | v1 单实例可承载 200 SKU |

---

## §9.E 性能瓶颈

### 已知瓶颈

| # | 瓶颈点 | 量化预期 | 触发监控 | 触发优化条件 |
|---|--------|---------|---------|------------|
| P1 | MINLP 求解器单次时长 | 200 SKU × 13 周 × 2 物流 ≈ 5200 整数变量；预期 5-30 min | metric `solver.duration_seconds` | > 30 min 持续 3 天 → 切 Gurobi / 加 warm-start |
| P2 | 灵敏度 27 场景 batch | 串行 27 × 5 min = 2h；并行 4 路 = 30 min | `sensitivity.batch_duration` | > 1h → 加并行度或减场景 |
| P3 | 每日数据同步 | 12 数据源 × 10w 行 ≈ 5-15 min | `sync.duration` | > 30 min → 分片并发 |
| P4 | 预测训练 200 SKU | LightGBM quantile × 3 ≈ 30s/SKU × 200 = 100 min；并行 8 路 = 13 min | `train.duration_per_sku` | > 30s/SKU → 减特征 |
| P5 | 决策清单 API 响应 | 200 行 + 6 列 + 置信度 → < 500 ms | `api.list_decisions.p95` | > 1s → 加索引 / 缓存 |
| P6 | preview-decision 实时重算 | 单 SKU 重算 < 200 ms | `api.preview.p95` | > 500 ms → 简化重算逻辑 |
| P7 | WebSocket 并发连接 | v1 < 5 连接（CEO + 助理 + tab） | `ws.active_connections` | > 50 → 加广播服务 |
| P8 | 数据库写入 QPS | 高峰每日 02:00 ≈ 200 QPS | `db.write_qps` | > 1000 → 分库 / 异步队列 |
| P9 | 数据快照存储 | 90 天 × 10w 行/天 ≈ 几十 GB | `storage.usage` | > 70% → 触发归档 |
| P10 | 周报 PDF 生成 | 含 chart 渲染 < 60s | `report.pdf_duration` | > 120s → 缓存 chart 图 |

### 性能预算总览

| SLO | 目标 | 测量 |
|-----|------|------|
| 每日批处理完成时间 | 凌晨 02:00 启动 → 08:00 完成（含数据同步+训练+决策+灵敏度+周报） | `batch.pipeline_duration` |
| 预警 SLA | 触发到推送 ≤ 15 min | `alert.delivery_latency` |
| Dashboard 加载 | 首屏 < 2 s | `frontend.lcp` |
| 操作响应 | 拍板/调整 < 500 ms | `api.p95` |

---

## §9.F 上线后稳定性风险

| 风险 | 缓解 | 监控 |
|------|------|------|
| 求解器内存泄漏 → OOM | 进程级隔离 + 自动重启 + max_memory_limit | `process.memory_rss` 持续 > 6GB 报警 |
| 推送渠道大面积失败 | 多渠道 fallback + 失败队列 + 站内信兜底 | 各渠道成功率 < 95% 报警 |
| 决策连续多日不准 | 7 天滚动正确率 < 50% 自动降级朴素策略 | `decision.weekly_accuracy` |
| 助理状态机卡死（如 in_progress 7 天不变） | 自动告警 + CEO 视图标"长时未更新" | 状态停留时长 monitoring |
| 数据源 schema 突变（FBA API 升级） | Schema 校验 + 失败硬阻断 + 通知 admin | schema_version_mismatch_count |
| 时区切换日异常（夏令时） | 单独测试套件 + 切换日前 24h 预演 | `business_date_consistency_check` |
| 影子模式被错当 Mock 用 | UI 顶部独立紫色标识 + 决策不进 FR-7 | `mode_misuse_attempts` |
| 用户连续 N 天不打开 | 周报邮件兜底 + 紧急 critical 必推 | `user.last_active` |
| 数据回流延迟导致复盘卡住 | 复盘"待回流"标识 + 14 天硬切 | `playback.pending_count` |
| 并发改参数导致目标函数发散 | 参数版本快照 + self-test 50 case 阻断发布 | self-test failure 报警 |
| 长尾 SKU 被错分类 → 不出建议 | FR-16 人工覆盖 + 周复盘必看 | `sku.no_recommendation_streak` > 30 天 |
| 批量接受失误（高比例错误） | 周复盘批量正确率 < 80% 自动提示调整条件 | `batch.accuracy` |
| MINLP 在某 SKU 组合上 infeasible | 软约束自动放松 + 标"约束放松" | `solver.infeasible_count` |
| 助理离职数据丢失 | 账号停用前导出待办；自动归还 CEO 池 | account_disable_audit |
| 法律/合规：商业数据走个人微信 | 默认渠道企微 / Bark / Telegram，禁用个人微信 | 渠道配置审计 |

---

## §10.A AC 自动化测试矩阵

### 总体覆盖原则
- 单元测试覆盖率：核心模块（FR-3/4/5）≥ 85%，UI ≥ 70%
- E2E 主流程：FR-6 拍板闭环、FR-7 助理状态机、FR-10 模式切换 必须 P0 自动化
- 性能基线测试：每次 release 跑（见 §10.C）

### AC 矩阵（示例 60 条，按 FR 分组）

| AC ID | 描述 | 类型 | 自动化优先级 | 测试数据要求 |
|-------|------|------|--------------|-------------|
| AC-1.1 | Mock 模式默认开启，顶部斑马条可见 | 主流程 | P0 | mock fixture |
| AC-1.2 | 切 Real 需二次确认 + 写 audit | 状态切换 | P0 | admin 用户 |
| AC-1.3 | 数据源 API 超时 3 次重试后用 last-known-good | 异常 | P0 | API stub 超时 |
| AC-1.4 | 字段缺失 > 5% 整批拒绝 | 边界值 | P0 | 缺失 6% 的 fixture |
| AC-1.5 | snapshot 不可变（修改报 409） | 异常 | P1 | 已存在 snapshot |
| AC-1.6 | 跨夏令时业务日切正确 | 边界值 | P0 | DST 切换日 fixture |
| AC-2.1 | SKU 历史 <14 天走冷启动分支 | 边界值 | P0 | 短历史 SKU |
| AC-2.2 | 输出 p10/p50/p90 三值 | 主流程 | P0 | 完整 SKU |
| AC-2.3 | 训练 30s 超时 fallback 上版本 | 异常 | P1 | 慢训练 stub |
| AC-2.4 | 全 0 历史不出预测 | 边界值 | P0 | 长尾 fixture |
| AC-3.1 | 5 项 component 计算正确（与 oracle 比对） | 主流程 | P0 | 50 预置 case |
| AC-3.2 | 缺货倍数分段（≤14 天 vs >14 天） | 边界值 | P0 | 缺货 15 天 case |
| AC-3.3 | 参数版本快照绑定决策 | 状态切换 | P0 | 多版本参数 |
| AC-3.4 | self-test 50 case 失败阻断发布 | 回归 | P0 | 故意错误 case |
| AC-4.1 | 200 SKU × 13 周求解 < 30 min | 主流程 | P0 | 全量 fixture |
| AC-4.2 | infeasible 自动放松软约束 | 异常 | P0 | 冲突约束 fixture |
| AC-4.3 | 求解器崩溃自动重启 1 次 | 异常 | P1 | 注入崩溃 |
| AC-4.4 | 相同 input_hash 24h 缓存命中 | 主流程 | P1 | 重复输入 |
| AC-4.5 | 求解超时返回 current best + 标 gap | 边界值 | P0 | 超长输入 |
| AC-5.1 | 27 场景 batch < 60 min | 主流程 | P0 | 标准输入 |
| AC-5.2 | 核心决策稳定率算式正确 | 主流程 | P0 | 已知 baseline + 扰动 |
| AC-5.3 | 单场景 infeasible 不计稳定率分母 | 边界值 | P1 | 含 infeasible 场景 |
| AC-6.1 | 决策清单按建议优先级倒序 | 主流程 | P0 | 多优先级 fixture |
| AC-6.2 | 空清单显示"今日健康" + 倒计时 | 边界值 | P0 | 健康库存 fixture |
| AC-6.3 | "调整数量"实时重算 landed cost < 200ms | 主流程 | P0 | 标准 SKU |
| AC-6.4 | "调整"调到 0 拦截 | 异常 | P1 | - |
| AC-6.5 | 决策版本乐观锁，后到 409 | 并发 | P0 | 双 tab 模拟 |
| AC-6.6 | 助理打开本页操作按钮置灰 | 权限 | P0 | assistant 角色 |
| AC-6.7 | 求解器昨晚失败显示红条 + 用前日决策 | 异常 | P0 | 注入失败 |
| AC-6.8 | 移动端切换卡片视图 | 兼容 | P1 | iPhone viewport |
| AC-6.9 | "跳过"必须有原因（提示） | 主流程 | P1 | - |
| AC-7.1 | 助理状态机：pending→in_progress→shipped 正确 | 状态切换 | P0 | 助理账号 |
| AC-7.2 | shipped 必须上传附件 | 边界值 | P0 | 无附件场景 |
| AC-7.3 | 24h 内可退回 CEO，超后禁用 | 边界值 | P0 | 24h boundary |
| AC-7.4 | WebSocket 断连自动重连 + 轮询兜底 | 异常 | P1 | 注入断连 |
| AC-7.5 | 助理只能看分配 SKU | 权限 | P0 | 多助理 fixture |
| AC-8.1 | 库存 ≤ 21 天触发 critical | 主流程 | P0 | 临界库存 |
| AC-8.2 | 5min 窗口聚合同 SKU 多预警 | 主流程 | P0 | 短时多次触发 |
| AC-8.3 | 静音规则生效 | 状态切换 | P0 | 静音 fixture |
| AC-8.4 | critical 穿透静音 | 边界值 | P1 | 静音 + critical 触发 |
| AC-8.5 | 推送到企微 < 15min | 主流程 | P0 | 企微 stub |
| AC-8.6 | 渠道失败 fallback | 异常 | P0 | 注入企微失败 |
| AC-9.1 | 周报周一 09:00 自动生成 | 主流程 | P0 | 时间 mock |
| AC-9.2 | PDF 导出 < 60s | 主流程 | P1 | 完整周数据 |
| AC-9.3 | 除 0 指标显示 "–" | 边界值 | P1 | 零数据 |
| AC-10.1 | Mock/Real 切换二次确认 | 状态切换 | P0 | admin |
| AC-10.2 | Real 数据源未就绪禁用切换 | 边界值 | P0 | 未配置 stub |
| AC-10.3 | Mock 决策不进助理视图 | 主流程 | P0 | 助理账号 + Mock |
| AC-10.4 | 切换冷却 30s | 边界值 | P1 | - |
| AC-11.1 | 三策略回测结果统计显著 | 主流程 | P0 | 30 次 mock run |
| AC-11.2 | 历史数据 <30 天拒绝跑 | 边界值 | P1 | 短历史 |
| AC-11.3 | 回测 snapshot 可复现 | 回归 | P0 | 已知 snapshot |
| AC-12.1 | 正确性评分按 ±20% 阈值算 | 主流程 | P0 | 已知销量 |
| AC-12.2 | 14 天前数据未回流标"待回流" | 边界值 | P0 | - |
| AC-13.1 | 影子 SKU 与 Mock 物理隔离 | 主流程 | P0 | 双轨 fixture |
| AC-13.2 | 必须 4 类齐全才能启用 | 边界值 | P0 | 仅 3 类 fixture |
| AC-13.3 | 影子资金池独立 | 主流程 | P0 | 双 pool 验证 |
| AC-14.1 | 批量接受需输入确认文字 | 主流程 | P0 | - |
| AC-14.2 | 低置信度行禁用批量勾选 | 边界值 | P0 | 混合置信度 |
| AC-14.3 | 助理 24h 内可整批退回 | 状态切换 | P0 | - |
| AC-14.4 | 批量正确率 < 80% 提示调整 | 主流程 | P1 | 历史批量数据 |
| AC-15.1 | 60/90 天扫描准确性 | 主流程 | P0 | 已知库存+预测 |
| AC-15.2 | 在途数据缺失按 0 计 + warning | 边界值 | P1 | - |
| AC-16.1 | CV < 0.3 分类为稳定 | 主流程 | P0 | 不同 CV 的 SKU |
| AC-16.2 | 人工覆盖 90 天后失效 | 边界值 | P1 | 时间 mock |
| AC-16.3 | 历史 <30 天默认长尾 | 边界值 | P0 | 短历史 |

### 自动化优先级图例
- **P0**: 上线必须自动化（CI/CD 阻塞）
- **P1**: 上线前必须人工通过 + 上线后 1 月内补自动化
- **P2**: 持续改进，季度内覆盖

---

## §10.B 测试数据规范

### 测试数据集分层

| 层 | 用途 | 规模 | 来源 |
|----|------|------|------|
| L1 单元测试 fixture | 函数级 | 单 SKU 几条 | 手工构造 |
| L2 集成测试 fixture | 模块级 | 5-20 SKU × 30 天 | Mock 生成器 + 手工 |
| L3 性能基线数据集 | 性能回归 | 200 SKU × 365 天 | Mock 生成器（固定 seed） |
| L4 影子模式数据集 | 真实对照 | 4 SKU × 90 天 | 用户提供 |
| L5 极端场景数据集 | 边界测试 | 各类异常 SKU | 手工构造 |

### 关键 fixture 清单

| Fixture | 用途 | 内容特征 |
|---------|------|---------|
| `fx_stable_sku` | 稳定 SKU 全链路 | CV<0.3, 365 天历史 |
| `fx_volatile_sku` | 波动 SKU | CV>0.5 |
| `fx_seasonal_sku` | 季节性 | 含 Q4 高峰 |
| `fx_longtail_sku` | 长尾 | 月销 <5 |
| `fx_new_sku` | 新品 | <14 天历史 |
| `fx_stockout_history` | 含历史缺货 | 校准 FR-12 |
| `fx_dst_boundary` | 夏令时切换 | 含 3 月 / 11 月切换日 |
| `fx_corrupt_data` | 异常值 | 含负销量/0 价格 |
| `fx_full_200_sku` | 性能基线 | 200 SKU × 365 天 |
| `fx_infeasible` | 求解 infeasible | 约束冲突 |
| `fx_high_confidence_batch` | 批量接受测试 | 全部高置信度 |
| `fx_mixed_confidence` | 批量拦截测试 | 含低置信度 |

### 数据生成与版本化
- Mock 生成器代码与 fixture 共版本（git tag）
- 性能基线数据用固定 seed，保证可复现
- 影子数据加密存储（含商业敏感信息）

### 测试环境分层

| 环境 | 数据 | 求解器 | 用途 |
|------|------|-------|------|
| dev | L1+L2 | SCIP | 日常开发 |
| ci | L1+L2+L5 | SCIP | PR 触发 |
| staging | L3 全量 | SCIP + Gurobi 二选一 | release 前 |
| perf | L3 性能基线 | 与生产一致 | 性能回归 |
| prod | 真实 | 生产配置 | - |

---

## §10.C 回归基线

### 性能基线（每次 release 必跑，对比上次）

| 指标 | 基线（v1.0） | 回归阈值 | 处理 |
|------|------------|---------|------|
| MINLP 求解（200 SKU × 13 周） | 15 min | 退化 > 50% | 阻断发布 |
| 灵敏度 27 场景 batch | 45 min | 退化 > 30% | 警告 + 必须解释 |
| 数据同步全流程 | 8 min | 退化 > 50% | 警告 |
| 模型训练 200 SKU | 12 min | 退化 > 50% | 警告 |
| 决策清单 API P95 | 300 ms | 退化 > 100% | 阻断发布 |
| 预警 SLA | 5 min | 退化 > 200%（>15min） | 阻断发布 |
| 周报 PDF 生成 | 40 s | 退化 > 100% | 警告 |

### 决策质量基线（mock 数据 30 次回测）

| 指标 | 基线（系统策略） | 回归阈值 |
|------|----------------|---------|
| 三策略总收益排序：系统 > 保守 > 激进 | 必须成立 | 不成立则阻断 |
| 系统 vs 保守总收益提升 | +X%（待 spike 后定标） | 下降 > 20% 阻断 |
| 缺货事件数 | 基线 N 次 | 增加 > 50% 阻断 |
| 灵敏度核心稳定率 | > 70% | < 60% 阻断 |

### 兼容性基线

| 维度 | 基线 |
|------|------|
| 浏览器 | Chrome 100+ / Safari 15+ / Edge 100+ 全功能通过 |
| 移动 | iOS 15+ / Android 10+ 关键流程通过（拍板/查看） |
| 邮件 | Gmail / Outlook / 企微邮箱渲染通过 |
| API 兼容 | v1 API 至少向后兼容 1 个 minor 版本 |

### 自动化回归套件

| 套件 | 频率 | 内容 |
|------|------|------|
| smoke | 每次 PR | AC-*.1（每 FR 主流程 1 条）共 16 条 < 5 min |
| nightly | 每晚 | 全部 P0（约 35 条）+ 性能基线 < 2h |
| weekly | 每周 | 全部 P0 + P1 + 决策质量基线 + 兼容性 < 8h |
| release | 每次 release | 全部 + 极端场景 + 影子模式校验 < 24h |

---

## §12 附录

### 12.1 术语表

| 术语 | 中文 | 释义 |
|------|------|------|
| FBA | Fulfillment by Amazon | 亚马逊履约服务 |
| SKU | Stock Keeping Unit | 库存单位 |
| ASIN | Amazon Standard Identification Number | 亚马逊商品编号 |
| BSR | Best Sellers Rank | 亚马逊销量排名 |
| Lead Time | 提前期 | 订单到入仓的时间 |
| Restock Limit | 补货限额 | FBA 仓位上限 |
| IPI | Inventory Performance Index | FBA 库存绩效指数 |
| Landed Cost | 落地成本 | 含商品+运费+关税的到岸成本 |
| MAPE | Mean Absolute Percentage Error | 平均绝对百分比误差 |
| CV | Coefficient of Variation | 变异系数（std/mean） |
| MINLP | Mixed-Integer Non-Linear Programming | 混合整数非线性规划 |
| LP | Linear Programming | 线性规划 |
| Gap | 求解 gap | 与最优解的相对差距 |
| Robust Optimization | 鲁棒优化 | 在不确定性下求最坏情景最优 |
| Stochastic Programming | 随机规划 | 决策变量带概率分布 |
| Warm-start | 热启动 | 用已有解作为求解起点 |
| Snapshot | 快照 | 不可变数据副本 |
| Shadow Mode | 影子模式 | 系统建议 vs 真实决策同步对照 |
| Decision Owner | 决策者 | 拍板权限角色（CEO） |
| Confidence | 置信度 | 决策稳健度评级（高/中/低） |
| Sensitivity Analysis | 灵敏度分析 | 参数扰动下决策稳定性测试 |
| Audit Log | 审计日志 | 关键操作的不可变记录 |

### 12.2 缩写与 FR 编号映射

**proposal-v1.md → 本稿 FR 编号映射**：

| proposal-v1.md | 本稿 § | 名称 |
|---|---|---|
| FR-1 | 5.2 | 数据接入 Adapter |
| FR-2 | 5.3 | 销量预测 |
| FR-3 | 5.4 | 经济目标函数 |
| FR-4 | 5.5 | 优化引擎（MINLP） |
| FR-5 | 5.6 | 灵敏度分析 |
| FR-6 | 5.7 | 决策清单 + 可解释面板 |
| FR-7 | 5.8 | 助理操作视图 + 状态回写 |
| FR-8 | 5.9 | 缺货预警 |
| FR-9 | 5.10 | 周报 Dashboard（注：proposal 原命名"收件箱"，本稿因 R3 共识"不合并预警与日报"改为周报） |
| FR-10 | 5.11 | Mock/Real 切换 |
| FR-11 | 5.12 | 三策略回测 |
| FR-12 | 5.13 | 周复盘报告 |
| FR-13（应做）| 5.14 | 影子模式（proposal 原 FR-15 提前） |
| FR-14（新增）| 5.15 | 批量接受 + 责任回路（R3 共识独立成项）|
| FR-15（应做）| 5.16 | 60/90 天上游预警（proposal 原 FR-14） |
| FR-16（应做）| 5.17 | SKU 自动分类（proposal 原 FR-13） |

**其他缩写**：

| 缩写 | 全称 |
|------|------|
| PRD | Product Requirements Document |
| AC | Acceptance Criteria |
| SLA | Service Level Agreement |
| SLO | Service Level Objective |
| OOM | Out Of Memory |
| QPS | Queries Per Second |
| P95 | 95 百分位 |
| TTL | Time To Live |
| CSV | Comma-Separated Values |
| UUID | Universally Unique Identifier |
| WebSocket / SSE | 实时通讯协议 |
| DST | Daylight Saving Time |
| ERP | Enterprise Resource Planning |

### 12.3 关联 API 文档（待补充）

| 系统 | 接口文档 | v1 状态 |
|------|---------|---------|
| Amazon Seller Central (FBA Reports / Inventory) | https://developer-docs.amazon.com/sp-api/ | v1 仅 schema 参考，不接入 |
| Amazon Ads API | https://advertising.amazon.com/API/docs/ | v1.5 接入 |
| 货代报价 API（待选 3-5 家） | TBD | v1.5 接入；v1 用手工录入 |
| 企业微信应用 API | https://developer.work.weixin.qq.com/ | v1 接入 |
| Bark Push | https://github.com/Finb/Bark | v1 接入 |
| Telegram Bot API | https://core.telegram.org/bots/api | v1 接入 |
| SCIP / PySCIPOpt | https://www.scipopt.org/ | v1 主求解器 |
| Gurobi | https://www.gurobi.com/documentation/ | v1 fallback（需 license） |
| LightGBM | https://lightgbm.readthedocs.io/ | v1 用于波动 SKU 预测 |

### 12.4 关键架构决策记录（ADR 索引，简版）

| ADR | 决策 | 替代方案 | 选择原因 |
|-----|------|---------|---------|
| ADR-01 | 求解器用 SCIP（开源） | Gurobi / CPLEX | 0 license 成本；v1 规模可承载 |
| ADR-02 | 区间预测用分位数回归 LightGBM | Prophet / DeepAR | 工程成熟 + 单 SKU < 30s |
| ADR-03 | 预警与日报不合并 | 合并收件箱 | 状态机/SLA 完全不同（响应工程 R3） |
| ADR-04 | Mock 与 Shadow 物理隔离 | 共用 DB + tenant_id | 资金池/隔离更强；避免数据污染 |
| ADR-05 | UTC 入库 + PST 业务日 | 单一时区 | 多站点扩展性 |
| ADR-06 | 周决策 + 事件触发预警 | 每日决策 | R3 共识 "200 SKU 健康业务实际每周 2-3 次发货" |
| ADR-07 | 求解输入用 input_hash 缓存 | 不缓存 | 24h 复跑可立即命中，节省 90% 算力 |
| ADR-08 | 参数版本快照绑定决策 | 当前最新值 | 复盘可复现 |

---

## ⚠️ 待 R2 跟其他主笔对齐的章节边界

| 议题 | 我的章节涉及 | 需对齐对象 | 期望确认 |
|------|------------|----------|---------|
| 1. §5.1 通用约定中"时区/货币" | 5.1 | 业务主笔 | 是否同意 UTC 入库 + PST 业务日 + Asia/Shanghai 展示 |
| 2. FR-4 MINLP 求解 v1 用 SCIP | 5.5 / 9.D | 架构主笔 | 是否同意 SCIP；是否预留 Gurobi license |
| 3. 决策频率：周节奏 vs 每日 | 5.7 / ADR-06 | 业务/产品主笔 | R3 共识改"周节奏 + 事件触发"，需业务正式确认（影响 §5.7 摘要文案与 §5.9 周报） |
| 4. 预警 SLA 取 15 min（与锚点"1 小时"不一致） | 5.9 / 9.E | 业务主笔 | 取严还是放宽 |
| 5. 助理 24h 否决权窗口 | 5.8 / 5.15 | 业务主笔 | 24h 是否合适 |
| 6. 影子模式 SKU 数下限 4 | 5.14 / 9.F | 业务/战略主笔 | 4 个是否够（战略 R3 要求 20+） |
| 7. FR-9 "周报 Dashboard" 命名 | 5.10 / 12.2 | 业务/设计主笔 | proposal 原命名"收件箱"，本稿因 ADR-03 改名，需对齐 |
| 8. 真实 FBA API schema 反向设计交付物 | 9.D TD-3 | 架构主笔 | 是否产出独立 schema 文档 |
| 9. 推送渠道默认值（企微/Bark/Telegram） | 5.9 / 9.F | 业务主笔 | 默认 + 优先级 |
| 10. 性能 SLO 表（§9.E）数值 | 9.E / 10.C | 架构/业务主笔 | 是否接受这些数值作为产品承诺 |
| 11. AC 编号体系（本稿用 AC-FRid.序号） | 10.A | 测试/QA 主笔 | 是否对齐 |
| 12. 复盘等待期 14 天 | 5.13 | 业务主笔 | 是否接受 |
| 13. 批量接受单次上限 50 条 | 5.15 | 业务主笔 | 是否合适 |
| 14. FR-14（批量+责任回路）独立成项 | 5.15 / 12.2 | 业务/产品主笔 | 是否同意从 FR-6 拆出 |
| 15. 边界 SKU 总数 1000（5× 余量） | 7.1 | 业务/架构主笔 | 是否合适 |