3.6 KiB
会议物料流转缺口补齐设计
目标与依据
依据 10 月 4 日会议纪要及用户要求“直接修改所缺的相关功能”，在现有基础资料维护、业务管理、报表查询三个一级模块内补齐功能，不重建业务系统。
不变量
- 托盘号沿用发货方录入值；生产批号、托盘号和内部溯源号互不替代。
- 新装填固定 100 包；使用按实际包数扣减；余料退回不换托盘、不换原物料批次。
- 正式数据与测试批次隔离；权限、仓库/现场数据范围、事务锁、幂等和事件流水继续在后端执行。
- 不安装依赖、不修改运行环境、不修改无关文件、不提交既有暂存内容。
- 仅准备初始化 SQL 和增量迁移；连接真实数据库执行结构变更、补数或业务写入前另行获得明确确认。
- 在当前 codex/test-data-batch-cleanup 工作区增量修改，保留已有未提交隧道功能，不另建遗漏这些修改的工作树。
功能设计
1. 报表与混批追溯
消耗报表允许产线为空，以隧道为主要查询维度。库存、消耗、退回、托盘追溯返回隧道编号/名称与内部溯源关系；按同一溯源关系展示多托盘、多批次的使用与退回明细，避免将不同业务阶段的数量重复相加。普通操作页显示业务名称，内部码仅在查询/详情中使用。
2. APP/PDA
对齐现有后端 tunnel-options、enter-tunnel 和 usage 接口。先扫码、选择隧道、确认入隧，再提交实际使用量；产线可选。入隧与使用独立幂等键，失败重试保持原键，改动业务输入后更新键。继续支持现有扫描头与手工输入，不新增原生 SDK。
3. 批次信息与标签
装填记录增加 production_date（生产日期）和 expiry_date（有效期至），日期不得倒置。历史记录允许为空并显示“未登记”，不得用装填时间伪造生产日期。PC 与 APP 新录入一致；扫描、单据详情和相关报表读同一记录。发货标签包含原托盘号、客户/现场、品种、批号、生产日期、有效期、包数以及固定二维码。
4. 发货与接收核对
在现有发货模块内增加接收方核对确认，不新建一级菜单。发货确认与接收确认分别留痕，接收按原发货单的托盘和物料快照处理，不能新编托盘/批号；未核对接收的物料不能投入使用。接收权限必须受目标现场范围控制。历史已发货业务通过明确迁移策略保持可用，不重扣库存。
5. 无二维码录入
允许在已有扫码入口输入印刷托盘号，由服务端在当前测试批次与业务数据范围内解析。实际提交使用规范二维码标识，避免同一托盘用两种输入生成不同业务身份。若托盘号与其他二维码标识冲突，明确拒绝歧义，不能随意取第一条。
6. 先到先用
同现场、同品种、可用库存按真实接收时间排序推荐；用户已批准“允许跳过但必须记录原因”。入隧和实际使用均由后端复核，存在严格更早候选时要求最多500字的原因，随事件/使用记录保存推荐快照并参与幂等摘要。到货时间相同或当前历史时间未知时不以托盘ID强排先后，未知时间提示人工核对。保留跨托盘、跨批次混用及余料原托退回。
验收
先写回归测试再实现，覆盖无产线报表、数据隔离、混批追溯、日期边界、二维码/托盘号歧义、收货权限/状态/幂等与 FIFO。PC 和 APP 运行现有契约测试及构建。最终单独列出已验证代码、待执行迁移和待实机验收，不把它们混为完成。