一、交付目标
周食谱编制→自动保存 / Excel→算法推荐食谱→营养值与特殊供餐→审核发布→同步 ydy_recipes→采购反算→核对 / 交接 / 输出
生产成功的判定不是“页面可演示”，而是发布快照、原菜谱表、下游终端、采购需求和审计记录均可回读并保持一致。
来源与证据边界
| 来源 | 等级 | 采用方式 |
|---|---|---|
| 2026-09-18 用户逐项确认的生产规则 | A | 业务范围、公式、状态机、兼容红线和菜单要求的直接事实源 |
| store 当前代码与表结构 | A | 验证原菜谱表下游读取、限量字段语义及旧写入口 |
| 学校团餐产品营养功能设计 Word 与推荐弹窗截图 | A | 确认推荐食谱使用确定性专业算法，不调用 Coze 或大模型工作流 |
| 需求分析及数据库/API/测试设计 | B | 复用生产建模、接口草案和测试矩阵，并按确认规则修订 |
| 云效与交互原型 | B | 保留已确认交互；演示字段不作为生产边界 |
本方案是开发与评审合同，不代表数据库迁移、接口、权限、性能或生产验收已经通过。
二、本期范围
- 周食谱、自动保存、Excel整周原子导入。
- 学生餐标准、模板和硬约束驱动的确定性食谱推荐。
- 可复算营养值、特殊供餐核验。
- 审核通过即发布及不可变快照。
- 发布菜品投影到原
ydy_recipes。 - 采购规则、净需求、建议量、人工核对。
- 确认、取消、失效、已交接、导出打印。
- 膳食营养菜单及主数据复用入口。
三、明确不做
- Coze、大模型或其他外部工作流生成食谱。
- 真实进销存接口、库存、价格、供应商和包装规格。
- 旧菜谱采购数据补造。
- 食谱复制功能。
- 无正式标准依据的营养达标判断。
四、食谱状态
草稿 → 待审核 → 已发布 → 已归档
↑ │
└─退回──┘
- 已发布版本不可修改。
- 人数、菜品、配方或特殊供餐变化必须走新草稿。
- 发布投影失败时整体回滚，原菜单不变。
五、采购状态
待核对 → 已确认 → 已交接
│ │
└→ 已取消 └→ 已失效
- 已确认锁定，改量时旧单失效并生成新单。
- 导出、打印不代表交接。
- 新食谱发布后，未交接旧需求失效。
六、关键计算规则
净需求kg = Σ（最终每人净料克数 × 对应餐次人数）÷ 1000
有正式净料率：建议采购量 = 净需求 ÷ 净料率
无正式净料率：只展示净需求，由人工填写核对采购量
最终建议采购量：统一向上保留两位小数（kg）
按食材稳定ID汇总；人数为0不产生需求；serving_factor只用于形成最终每人净料克数，不在采购反算时重复相乘；缺食材、重量、单位或正式规则时整单不可确认。
推荐食谱算法
实现结论：推荐由服务端确定性算法完成，不调用 Coze、LLM 或 workflowRun(2)。
- 读取学段、餐次人数、模板、营养目标、季节和已授权候选菜品。
- 先执行特殊供餐、慎用/禁用食材、过敏原、模板数量和数据完整性等硬约束。
- 按《学生餐营养指南》WS/T 554及规则版本计算餐次目标；早餐、午餐、晚餐比例分别为25%～30%、35%～40%、30%～35%。
- 按营养偏差、食物多样性、荤素结构、重复频率、季节和烹调方式评分并组合优化。
- 输出平台菜品ID、分项得分、规则版本、缺项和推荐依据；人工确认后只写当前草稿。
同一输入版本、规则版本和随机种子必须可复现；失败、取消或草稿版本变化时不得覆盖原菜单。本期不使用库存作为推荐输入。
七、事实源与兼容边界
| 业务对象 | 事实源 | 约束 |
|---|---|---|
| 草稿、审核、发布历史 | 新计划/版本表 | 正式版本以 plan_version 为准 |
| 现有终端生效菜谱 | ydy_recipes | 只接受审核发布投影；旧查询保持不变 |
| 采购计算 | 不可变发布快照 | 不得从 ydy_recipes 反推人数与BOM |
| 菜品与食物成分 | 原主数据表 | 新旧菜单入口复用同一数据和权限 |
纳入新模块管理的范围，旧页面、批量导入和设备写接口不得绕过审核覆盖生效菜单。
八、数据设计
| 分组 | 核心表 | 数量 |
|---|---|---|
| 食谱与审核 | plan、plan_version、plan_meal、plan_dish、plan_ingredient、plan_log | 6 |
| 特殊供餐 | special_meal_verification | 1 |
| 推荐规则 | menu_rule_version、menu_rule_item | 2 |
| 采购规则 | purchase_rule_version、purchase_rule_item | 2 |
| 采购需求 | purchase_demand、demand_item、demand_trace、demand_log | 4 |
首期新增15张核心表，继续复用 ydy_recipes、ydy_dishes、ydy_dish、ydy_foods_composition 及学校/餐厅/档口主档。
九、垂直开发切片
| 切片 | 交付 | 关键验收 |
|---|---|---|
| S1 数据契约 | 迁移、枚举、权限、错误码、OpenAPI | 测试库结构回读和回滚通过 |
| S2 草稿与Excel | 新建、自动保存、乐观锁、整周导入 | 失败不改原草稿；并发不覆盖 |
| S3 推荐、营养与核验 | 确定性推荐算法、可复算营养值、特殊供餐记录 | 硬约束优先、结果可复现、只写草稿；缺值不补0 |
| S4 审核与投影 | 退回、审核发布、快照、原表投影 | 快照与原表一致，失败整体回滚 |
| S5 采购反算 | 净需求、规则、重叠拦截、追溯 | 金标准一致；缺项不可确认 |
| S6 状态与交接 | 调量、确认、取消、失效、交接 | 已确认不可改；状态日志可回读 |
| S7 输出与菜单 | Excel、打印、模拟转单、复用入口 | 文件与页面同源，权限不扩张 |
| S8 回归上线 | E2E、性能、安全、灰度、回滚 | P0/P1缺陷为0 |
十、菜单结构
膳食营养
├── 总览
├── 食谱管理
├── 菜品管理 → 复用原页面
├── 食物成分 → 复用原页面
├── 食材用量与采购单
└── 基础设置
原“餐厅管理”菜单不变。新入口复用同一组件、接口、数据和权限，返回及详情保持入口上下文。
十一、排期
推荐配置 后端2人、前端1人、测试1人。
建议日历周期：12～15个工作日。
仅1名后端时按18～22个工作日评估。产品、营养、供应链负责人按契约、推荐算法、采购算法、核验和UAT门禁参与。
十二、核心测试
推荐硬约束候选ID白名单稳定排序结果可复现十进制定点最终向上两位不重复乘倍数范围重叠自动保存并发Excel回滚核验失效发布幂等原表投影旧写入口门禁交接状态跨学校越权现有终端回归
必须通过的两条E2E
- 编制 → 保存/导入 → 核验 → 提交 → 退回 → 重提 → 审核发布 →
ydy_recipes回读 → 现有终端读取。 - 发布快照 → 反算 → 追溯 → 调量 → 确认 → 人工交接 → 导出/打印 → 新版本发布后的旧需求处理。
十三、上线门禁
- □ 正式净料率或无净料率处理已确认。
- □ 推荐算法的标准、硬约束、权重、阈值和金标准已确认。
- □ 菜品、食材和BOM缺项清单关闭。
- □ 迁移、备份和回滚脚本通过。
- □ 发布快照、原表和终端读取一致。
- □ 旧写入口不能绕过审核。
- □ 权限、幂等、并发和事务测试通过。
- □ 两条E2E、性能和安全测试通过。
- □ P0/P1缺陷为0，测试学校灰度通过。
十四、待联合评审
- 正式净料率、维护人、版本和金标准样例。
- 编制人与审核人的账号/角色映射。
- 推荐算法及营养评价的学段标准、餐次比例、权重、阈值和同分规则。
- 特殊供餐核验责任人及证据格式。
- 打印模板、学校抬头、签字栏和文件名。
这些事项不阻止数据表、页面骨架和发布快照链开发，但必须在对应功能进入 Ready 前关闭。
十五、人工评审结论
| 角色 | 结论 | 意见/证据 | 日期 |
|---|---|---|---|
| 产品 | 待评审 | ||
| 营养/供应链 | 待评审 | ||
| 后端 | 待评审 | ||
| 前端 | 待评审 | ||
| 测试 | 待评审 |