ShiErFeng/docs/superpowers/plans/2026-10-08-meeting-flow-completion.md

# 会议物料流转缺口补齐 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 完整补齐会议纪要中现有三个业务模块的缺口，并对齐 PC、APP/PDA 与后端。

**Architecture:** 复用现有 controller/service/dao/vo/do 分层、库存状态机、作用域与事件流水。报表和 APP 接口纠偏先独立完成；日期、收货与 FIFO 在共享模型和迁移中顺序集成。

**Tech Stack:** FastAPI、SQLAlchemy、Pydantic、MySQL、Vue 3、Element Plus、uni-app、Python unittest、Node 20。

**Spec:** docs/superpowers/specs/2026-10-08-meeting-flow-completion-design.md

## Global Constraints

- 托盘号沿用发货方录入值；生产批号、托盘号和内部溯源号互不替代。
- 正式数据与测试批次隔离；权限、仓库/现场数据范围、事务锁、幂等和事件流水继续在后端执行。
- 不安装依赖、不修改运行环境、不修改无关文件、不提交既有暂存内容。
- 仅准备初始化 SQL 和增量迁移；连接真实数据库执行结构变更、补数或业务写入前另行获得明确确认。

## Task 1: 隧道报表与混批明细

**Files:** backend module_business/dao/report_dao.py、entity/vo/report_vo.py、service/report_service.py；frontend src/views/report；相关测试。

**Interfaces:** 复用现有 tunnel_id、trace_no、batch_no_snapshot；增加 camelCase 隧道筛选和名称字段；保持所有既有报表路径。

- [x] 用数据库查询生成或隔离内存数据测试证明：line_id=NULL 的使用记录仍出现，跨测试批次关联不泄漏。
- [x] 先运行新增测试确认失败，再修改产线可选关联、隧道与溯源筛选/输出、退回快照。
- [x] PC 报表改为可读隧道编号/名称，提供同隧道/同溯源关系的多批次明细，不混加使用量与退回量。
- [x] 运行 `python -B -m unittest tests.module_business.test_report_service -q` 及新增专项测试；Node 20 运行 PC 契约测试。

## Task 2: APP/PDA 隧道操作

**Files:** app src/api/business/usage.js、src/pages/business/usage/index.vue、tests 下专项测试。

**Interfaces:** GET /business/usage/tunnel-options?siteId；POST /business/usage/enter-tunnel；POST /business/usage {qrToken,tunnelId,lineId?,usedPackages,idempotencyKey}。

- [x] 用真实页面脚本/API封装的行为测试覆盖未入隧不能使用、选隧道、失败重试键不变、切换输入旧响应无效、产线可空。
- [x] 运行新增测试确认旧实现失败。
- [x] 对齐后端接口，入隧独立提交；不在前端推算最终库存；内部溯源码不占普通操作主界面。
- [x] Node 20 运行 APP 契约测试、H5 与 APP 资源构建。

## Task 3: 批次日期与完整标签

**Files:** operation_do.py、operation_vo.py、filling_service.py、各扫描响应、PC/APP filling 页面、PC shipment 标签、SQL与测试。

**Interfaces:** productionDate、expiryDate（YYYY-MM-DD）；历史读取可空，新增录入必须完整且有效期不早于生产日期。

- [x] 写日期缺失、倒置、合法日期与幂等内容变化的失败测试。
- [x] 录入并保留原生产批次，日期参与请求摘要；扫描与发货标签读同一装填记录。
- [x] 实现发货标签，不以操作日期推导历史生产日期。
- [x] 运行 filling、shipment、模型与PC/APP相关测试。

## Task 4: 接收核对闭环

**Files:** shipment controller/service/dao/model、state machine、PC/APP shipment 页面、权限 SQL、事件流水与相关测试。

**Interfaces:** 接收确认附带原单据与核对托盘集合、独立幂等键；服务端复核目标现场权限和全部物料身份。

- [x] 写发货未接收不可入隧、越权接收、漏扫/错扫、重复确认、同键不同内容的失败测试。
- [x] 增加接收动作与时间/操作人/状态留痕；接收不新增托盘、批号或重复扣减包数。
- [x] 同步PC/PDA状态显示、按钮权限及扫码核对交互。
- [x] 准备历史数据兼容迁移和回滚/备份说明，执行前停在确认门。
- [x] 运行 shipment、usage、return、状态机、权限、测试批次图与清理回归测试。

## Task 5: 印刷托盘号解析

**Files:** inventory DAO、业务扫描服务/响应、PC/APP扫码消费端与测试。

**Interfaces:** 扫描入口接受二维码固定标识或印刷托盘号，返回 canonical qrToken；写命令保持二维码身份一致。

- [x] 写二维码输入、托盘号输入、两者歧义、跨范围/跨批次的失败测试。
- [x] 服务端解析并执行原业务权限检查；客户端提交规范化标识。
- [x] 运行五类扫码服务与PC/APP组件行为测试。

## Task 6: 先到先用与界面简化

**Files:** usage service/dao/vo、PC/APP usage、相关测试。

**Interfaces:** 排序依据实际接收时间；同现场同品种。用户已批准“允许跳过但必须记录原因”。入隧与使用写命令新增可选 `fifoSkipReason`（去首尾空白，最多500字）；服务端在原锁与幂等流程内复核，仅存在严格更早的已知到货候选时要求原因。同时间不按ID强迫先后；历史到货未知时保留人工核对提示。原因及推荐快照随原事件/使用记录同事务保存。

- [x] 完成只读推荐边界测试：实际到货顺序、部分使用、同现场同品种、在途/停用/零库存排除、测试隔离、旧溯源周期排除和历史时间未知。
- [x] 实现推荐提示，保留权限与幂等；界面显示推荐托盘，不暴露长内部码。
- [x] 用户批准允许跳过但必须记录原因；完成两端输入/恢复、后端入隧及使用复核、原因与推荐快照同事务留痕和增量迁移。
- [x] 运行 usage、return 与PC/APP行为测试；退回清空本轮到货时间，新收货记录实际时间。

## Task 7: 全量覆盖审计与迁移交付

- [x] 逐条对照设计，独立复查数据闭环、权限、测试隔离、重试与历史兼容性。
- [x] 运行业务单元测试、PC与APP契约测试、构建；记录真实命令及结果。
- [x] 获得“批准开发库迁移，FIFO按推荐规则执行”授权后，完成停写、43表完整备份、隔离恢复演练、三份补丁试跑、开发库迁移与历史数据摘要核对、后端恢复。
- [x] 更新部署文档，明确实机扫码和HTTP联调尚未覆盖的部分。

## 首轮执行记录（迁移授权前，历史）

- 已确认工作分支为 codex/test-data-batch-cleanup；当前未提交隧道改动是本次基础，不回滚或复制丢失。
- 基线：后端 report_service + tunnel_flow_contract 共36项通过。
- 默认 shell Node 是16；现有 Node20 位于 /Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin，后续显式使用，不安装或修改全局环境。
- 用户已要求直接实施评估中缺口；唯一待业务选择项为FIFO执行强度。代码之外的数据库执行仍需独立确认。
- 726项后端业务回归通过；新增收货读取/权限/幂等24项包含SQLite与ASGI验证，不等于真实MySQL并发验证。
- 复查补上退回确认事件的原隧道字段；回归先复现缺失，再验证48项退回服务测试通过。
- 两端未知请求凭据落盘、离页恢复与可选产线失败降级均已有真实页面行为测试。PC静态使用断言改为执行行为套件，避免旧源码匹配要求与安全重试冲突。
- 原许可证、登录页面、缓存/日志和既有隧道改动均保留；本轮未提交、暂存、推送、执行迁移、授角色或重启服务。

## 首轮集成验证记录（2026-10-08，迁移授权前）

- 后端：`LOG_FILE_ENABLED=false PYTHONDONTWRITEBYTECODE=1 /Users/jiaolongyan/miniconda3/envs/ShiErFeng/bin/python -B -m unittest discover -s tests/module_business -q`，727项通过。
- PC、APP分别在项目目录，使用现有Node20执行 `npm run test:business`，分别208项、75项通过；PC套件含两端收货组件行为测试。
- PC `npm run build:prod -- --outDir /private/tmp/shierfeng-meeting-pc.kB6NUN` 退出0。
- APP `UNI_OUTPUT_DIR=/private/tmp/shierfeng-meeting-app.oow8jU npm run build:app` 退出0。此为APP资源构建，不是签名APK；未覆盖当前 `dist/dev/app`。
- 主线程修改涉及的收货/FIFO分层文件、库存DAO、报表DAO、装填/入库/发货/使用/退回服务及物料模型定向Ruff检查通过；限定任务路径 `git diff --check` 通过。
- 审查发现的旧溯源FIFO候选已修复：已入隧候选必须匹配当前隧道和已验证trace，未知数量统计复用同一过滤；先观察失败，再运行7项FIFO测试通过，并经只读复核关闭问题。
- 未执行真实MySQL迁移、行锁竞争验收、生产HTTP联调、角色授予、打印机和PDA实机测试。迁移和FIFO执行强度仍待用户明确选择，不能将这些状态写为已完成。
- 最终前端独立复审无Critical/Important；补验两端×账号/批次切换×恢复/人工解除的8种交错场景通过。人工解除仅清理核对后的本机待确认记录，不发业务写请求，不宣称原操作成功。

## 数据库只读预检补充（2026-10-08）

- 继续轮完成了新证据核对，不是重复报告状态：实际开发目标为 `127.0.0.1:3306/shierfeng-fastapi`，MySQL 8.0.36，已有测试批次和隧道结构。
- 两个日期列、发货单5个收货列、库存实际收货时间列尚未落库；收货菜单1119和同名权限均未占用，也无1119孤立角色授权。
- 查询采用只读事务，仅结构元数据和菜单冲突检查，未做备份、DDL、业务写入、授权或重启。后端9099仍有监听，不能在未获准停写时执行补丁。
- 余下目标仍依赖用户确认两份增量迁移的维护窗口，以及FIFO跳过策略；未将自动目标续跑当作数据库写入授权。

## 迁移授权后实施与最终验证（2026-10-08）

本节是用户明确“批准开发库迁移，FIFO按推荐规则执行”后的当前状态；上文待授权、未迁移等描述保留为历史，不代表仍需重复审批。

- 已对本机 `127.0.0.1:3306/shierfeng-fastapi` 完成停写、43表完整备份、隔离库恢复及逐行摘要比对、三份补丁试跑、开发库迁移、原数据摘要核对和9099服务恢复。依次执行日期、收货、FIFO补丁；没有重跑初始化、清空业务表或自动授予普通角色。备份路径及SHA-256见 `docs/pallet-workflow-deployment.md`。
- FIFO已实现为“允许跳过严格更早到货的可用托盘，但必须填写最多500字原因”。入隧、使用两个写入口强制校验；原因及推荐快照同事务保存，参与幂等摘要；同时间和历史未知时间不伪造顺序。PC、APP均接入。
- 真实MySQL发现的提交/回滚后ORM过期属性读取已修复；返回值和ID在事务结束前取值。FIFO候选改为 `FOR UPDATE NOWAIT`，只对3572/1213/1205最多三次整事务原键重试，避免反向锁等待且不跳过早到候选。
- 前端审查发现的3项问题已补回归并修复：APP无业务code的HTTP5xx及不完整结果误清凭据、PC跨页面旧成功删除新待确认记录、PC恢复FIFO拒绝后推荐失败丢失已知必填要求。
- 主线程在最终代码运行后端 `LOG_FILE_ENABLED=false PYTHONDONTWRITEBYTECODE=1 /Users/jiaolongyan/miniconda3/envs/ShiErFeng/bin/python -B -m unittest discover -s tests/module_business -q`：741项，0失败，其中2项需显式隔离库而跳过。出现一条asyncio慢任务警告，不影响测试结果。
- 随后在已恢复的本机隔离库，设置 `SHIERFENG_MYSQL_FLOW_TEST_DATABASE=shierfeng_rehearsal_20261008_6ce_sy6c`，使用同一Python、`LOG_FILE_ENABLED=false DB_ECHO=false PYTHONDONTWRITEBYTECODE=1` 执行 `-m unittest discover -s tests/module_business -p test_material_flow_mysql.py -v`：2项均通过。覆盖完整物料流程、四类报表、三连接同键不重复扣减，以及正式scope两托交错入隧/使用的真实锁冲突回滚重试。未写实际开发库业务数据。
- 两端分别使用 `PATH=/Users/jiaolongyan/.nvm/versions/node/v20.20.2/bin:$PATH npm run test:business`：PC 243/243、APP 144/144通过，无跳过。
- PC `npm run build:prod -- --outDir /private/tmp/shierfeng-fifo-final-pc.kMm0to` 退出0；APP `UNI_OUTPUT_DIR=/private/tmp/shierfeng-fifo-final-app.BepwcI npm run build:app` 退出0，均使用上述Node20。构建到独立临时目录，未覆盖用户当前 `dist/dev/app`；APP产物为资源包，不是签名APK。
- 最终FIFO生产文件定向Ruff通过，限定任务路径 `git diff --check` 通过。`GET /docs` 返回HTTP200；未登录收货列表返回业务401，验证运行态及访问保护正常。
- 独立复审已关闭后端候选锁顺序及部署清单2项、前端F1/F2/F3三项问题，限定范围内无剩余阻断项；复审另行实跑后端11项及3组补充检查、PC 12项、APP 42项定向回归。没有用审查报告替代上述主线程最终全套验证。
- 普通角色配置、真实登录账号的HTTP写入联调、打印机及东集PDA实机仍未验收；未新增依赖、未改生产环境、未暂存/提交/推送，原有许可证、登录页、日志、缓存等改动均保留。