评审导航
关键决策
双记录模型补单表保存原因、操作人和试算/结算快照；
ydy_meal_order 仍是退款、报表和导出的正式订单真源。禁止使用 OrderSource=8最新
master 中 8 已经是咖啡机订单。补单复用 source=2，另用补单标识区分。七项输入部门、档口、姓名、消费时间、消费机、订单金额、补单原因。
六项结果优惠金额、服务金额、实付金额、现金支付、补贴支付、赠送支付。
服务端权威计算试算只用于展示；提交时重新计算。策略、余额或限制变化必须要求重新确认。
退款不删除退款只改变正式订单与补单状态，并追加操作日志；不得物理删除补单。
需求范围
本需求本质是资金补偿流程，不是后台手工插入订单。
| 范围内 | 不做 |
|---|---|
| 独立补单菜单、列表、详情、试算、提交、异步 XLSX、消费订单补单标识、退款和报表联动。 | 消费订单页不加新增入口；前端不计算最终金额；不伪造刷卡/刷脸；一期不录菜品明细；不物理删除。 |
时间口径
consume_time 决定策略、餐次、补贴有效期和统计账期；create_time 记录补单提交时间。餐次由后端推导，不由前端填写。
数据模型
正式消费订单
| 字段 | 用途 |
|---|---|
is_supplement | 0 正常订单，1 补单 |
supplement_id | 与补单主表一一关联；普通订单写 NULL，避免唯一键默认值冲突 |
supplement_no | 列表、详情和导出快速回显；普通订单写 NULL |
补单主表
保存补单号、幂等键、正式订单关联、人员/部门快照、档口、设备、实际消费时间、订单金额、原因、策略快照、六项结算金额、结算单 ID、状态、错误信息、门店与标准生命周期字段。
SQL 约束正式发布版本未确认前不创建猜测版本 SQL；菜单只写
db/menu.sql；新表必须包含项目规定的 is_delete/create_by/create_time/update_time 四字段。后端架构
从设备消费服务中抽取与设备协议无关的共享结算核心。设备链路保留 paycode、msgid、在线/离线、MQTT 和设备重试；PC 补单只调用领域服务，不伪造设备请求。
1 输入校验权限、人员、档口、设备、金额、原因
2 试算推导餐次，匹配策略与限制
3 再校验锁账户，比较 quote hash
4 结算落单本地钱包或一卡通适配器
5 回读追溯返回补单号和正式订单号
跨库或第三方调用不能被描述为一个普通数据库事务；失败必须保留状态、幂等键、远端交易号和补偿证据。
接口契约
| 接口 | 职责 |
|---|---|
POST /p/supplementMealOrder/list | 补单列表与组合筛选 |
POST /p/supplementMealOrder/detail | 补单、消费、结算、正式订单和操作记录 |
POST /p/supplementMealOrder/quote | 七项输入换取策略、六项金额和 quote hash，不扣款 |
POST /p/supplementMealOrder/create | 重算、幂等扣款、生成正式订单 |
POST /p/supplementMealOrder/export | 创建异步 XLSX 任务 |
POST /p/supplementMealOrder/exportLogs | 导出日志 |
消费订单 list/detail/export 同步增加补单标识、补单编号与正确的订单生成时间。响应继续使用现有 {code,message,data} 结构。
权限、安全与审计
独立菜单权限补单查询、详情、试算、创建和导出分别受控，不能借用消费订单权限创建资金记录。
对象级数据权限人员/部门、餐厅和设备归属必须全部校验；详情、导出和退款同样校验。
不信任前端策略 ID、餐次、六项金额、人员名称和部门名称都由后端解析或重算。
审计脱敏记录对象、金额、结果和错误码，不记录完整手机号、卡号、令牌或钱包敏感快照。
报表与异步导出
该列表页关联异步导出功能，需同步确认/修改异步导出逻辑。
| 范围 | 结论 |
|---|---|
| 消费订单 XLSX | 必须新增“是否补单”“补单编号”，保持流式 XLSX，不改 CSV。 |
| 人员/部门/设备 | 正式订单同表聚合，通常无需新增字段，但必须验证实际消费时间、状态和权限。 |
| 餐厅/档口 | 应按实际消费时间自动计入，必须做账期回归。 |
| 菜品销量/营养 | 一期无菜品明细，不计入；需产品接受。 |
| 充值/补贴统计 | 不改变充值和发放记录，无需同步字段。 |
一卡通边界
上线阻断一卡通开启且用户已映射时，必须走受支持的远端消费与本地镜像；不能静默改走本地钱包。第三方不支持补记历史消费时，一期应明确阻断这类补单。
回归需覆盖：关闭+访客、关闭+历史映射用户、开启+访客、开启+一卡通用户。远端成功本地失败必须进入现有补偿状态，不能删除记录掩盖。
实施与验收
| 切片 | 人工估算（未使用 AI） |
|---|---|
| 契约、SQL、枚举和模型 | 6～8h |
| 共享策略/结算核心与单测 | 12～16h |
| 接口、权限、审计和幂等 | 10～14h |
| 前端列表、试算、提交和详情 | 12～16h |
| 退款、报表和异步导出 | 8～12h |
| Apifox、回归、截图和发布证据 | 8～12h |
| 合计 | 56～78h，不含一卡通第三方等待 |
详细接口用例见 test-cases/api-contract-test-plan.md。涉及菜单、角色、路由和 UI 必须附真实页面证据；异步导出必须生成 XLSX 并通过结构校验。
上线阻断项
- 一卡通是否支持后台补记账、历史交易时间和对应冲正。
- 补单编号规则。
- 消费订单显示“后台补单”与补单页显示钱包构成的命名口径。
- 一期不录菜品明细、因此不进入菜品销量和营养统计是否接受。
- 是否支持部分退款。
- 正式发布版本号与数据库升级窗口。
本轮状态已在
codex/VWCG-1190-supplement-order-management-20260820 完成后端、前端、权限、退款和异步导出核心实现。专项测试与前端生产构建通过；代码未提交、未推送，正式版本 SQL 与真实数据库全链路仍待确认。