cmvr-wms/docs/purchase-project-refactor.md

采购与项目经费改造说明

目标

本次改造将采购从独立申请单升级为项目经费闭环：

项目分科目预算 -> 采购申请占用 -> 分批到货验收 -> 实际支出 -> 项目来源库存批次 -> 项目领用

采购主线边界

• 项目：项目基本信息、负责人、成员及访问范围。
• 经费：经费科目、项目分科目预算、占用金额、支出金额和不可变流水。
• 采购申请：项目、经费科目、预计含税单价、预计金额及采购状态。
• 采购导入：普通 Excel、带下拉选项的模板、表格粘贴和智能识别结果均须补齐项目、科目和预计单价。
• 到货验收：支持分批到货、实际含税单价、实际金额、拒收和未入库前撤销验收。
• 入库：验收通过生成待入库单；确认入库后生成带来源项目、经费科目和实际成本的库存批次。
• 出库：按库存批次扣减，记录来源项目与使用项目；跨项目使用须有权限和原因。

AI 指令审计、批量导入性能、移动端和仪表盘调整与采购主线共享同一未提交工作区，但不属于采购闭环的最小发布范围，提交时应单独审查。

经费规则

• 新增采购申请：按 需求数量 * 预计含税单价 增加占用金额。
• 修改有效申请：按新旧预计金额差额调整占用；更换项目或科目时先释放原占用，再占用新预算。
• 取消或删除申请：释放尚未结算的预计占用。
• 验收通过：按本批数量对应的预计金额释放占用，并按实际金额增加支出。
• 撤销已通过验收：仅允许在对应入库单尚未确认时执行，同时恢复占用并冲回实际支出。

数据库升级

1. 备份目标数据库。
2. 执行 select database();，确认连接的是预期数据库。
3. 执行 sql/wms_optimization_20260916.sql。
4. 执行 sql/wms_project_management_20260922.sql。
5. 再次执行第 3、4 步，确认脚本可安全重放。
6. 检查 project_info、expense_category、project_budget、project_fund_ledger、stock_lot 和 out_record_lot。

最小回归清单

1. 创建进行中的项目，将测试用户加入项目并配置一个经费科目预算。
2. 新建采购申请，确认预计金额和项目预算占用同步增加。
3. 修改数量或预计单价，确认只产生差额占用流水。
4. 登记部分到货并验收通过，确认采购状态为部分到货、占用减少、实际支出增加，并生成待入库单。
5. 确认入库，检查库存汇总和 stock_lot 的来源项目、科目、采购申请、到货记录及单位成本。
6. 对第二批到货验收，确认采购状态变为已到齐。
7. 对尚未确认入库的验收执行撤销，确认待入库单删除、经费恢复且采购状态回退。
8. 验证预算不足、超量到货、非项目成员、已归档项目和重复提交均被拒绝。

当前验证状态

• 2026-09-28 在 wms-test（MySQL 8.0.36）执行升级前 50 张基础表的数据与结构快照，备份库为 wms_test_backup_20260928_103302。
• wms_optimization_20260916.sql 和 wms_project_management_20260922.sql 均连续执行两遍成功，重放后业务表行数保持不变。
• 真实 Spring 服务与测试库事务回归通过，测试数据已全部回滚。覆盖：项目预算、采购占用、预计金额调整、部分到货、验收结算、撤销验收、再次验收、确认入库、库存批次成本和采购到齐。
• 回归发现并修复了“撤销后再次验收复用旧幂等键，导致经费不重新结算”的问题；验收流水幂等键现按验收周期生成。
• 后端 mvn clean test：通过，但仓库暂时没有常驻自动化测试源文件。
• 前端 npm run build:prod：通过，存在包体积告警。
• 2026-09-28 发布前已备份 wms-dev，备份库为 wms_dev_backup_20260928_105015；升级脚本连续执行两遍成功，基础表由 42 张增至 50 张，原业务表行数保持不变。
• wms-dev 真实 Spring 服务事务回归通过并完成回滚校验，未保留测试项目、采购、到货、入库或库存批次数据。