diff --git a/docs/task/306-档口入库码自动替换安全旧快照.md b/docs/task/306-档口入库码自动替换安全旧快照.md new file mode 100644 index 0000000..3b3d139 --- /dev/null +++ b/docs/task/306-档口入库码自动替换安全旧快照.md @@ -0,0 +1,69 @@ +# 306 Admin:档口入库码导入自动替换安全旧快照 + +- 类型:需求 / 交互优化 +- 父级大工单:#14 +- 所属 MVP / 版本:#224 / 档口入库码回写 MVP +- 状态:已完成 +- 日期:2026-08-26 +- Gitea 工单:https://git.ilapage.cn/OPC/cmautobuy/issues/306 + +## 背景与目标 + +#304 增加了“替换当日已删除旧数据”复选框和专门确认框。业务规则进一步确认后,采购员 +上传的文件就是当前要采用的完整数据,不需要再手工选择替换模式。本次移除该控件,由后端 +自动判断同日旧快照能否安全替换,并保留全部数据保护。 + +## 最终方案 + +- 每次 Excel 解析成功后,事务先锁定同一业务日期的完整旧快照。 +- 只有旧快照非空,且每条记录都已软删除、状态精确为 `pending`、没有匹配、采购、规划、 + 批次、远端结果或应用审计字段时,才自动物理删除整日旧快照并导入当前文件。 +- 没有旧快照,或任一旧记录未删除、已处理或存在处理痕迹时,不物理删除,继续原有同日 + 组成码归属检查和幂等 upsert。原有冲突、恢复和文件校验语义保持不变。 +- 删除影响行数变化会返回自动替换并发冲突;删除和后续写入仍在同一事务中,失败整体回滚。 +- Handler 不再读取浏览器替换选项;只有实际替换数量大于 0 时,成功反馈追加“自动替换 + 旧数据 N 条”。 +- 页面移除复选框、专门确认文案和专用样式,只保留选择文件、文件名和“导入”按钮。 + UI/UX 评审要求的“导入中…”禁用反馈、成功统计和可恢复错误提示继续保留。 +- 没有修改数据库结构、Client 接口或顺运宝远端数据。 + +## 改了哪些 + +- `admin/service/inner_code_import.go`:统一导入入口,增加非空整日旧快照自动安全判定。 +- `admin/handler/web/inner_code.go`:移除表单选项解析,按实际替换数量显示结果。 +- `admin/templates/inner_code/list.html`:移除复选框和专门确认属性。 +- `admin/static/js/app.js`、`admin/static/css/app.css`:移除替换确认逻辑和专用样式,保留上传反馈。 +- `admin/service/inner_code_import_test.go`:覆盖空、安全、未删除、已处理和逐字段处理证据。 +- `admin/handler/web/inner_code_test.go`、`admin/inner_code_template_test.go`:确认浏览器不再控制替换, + 且加载反馈仍存在。 +- `docs/admin/03-data-model.md`、`docs/admin/05-ui-specification.md`:固化自动判定规则。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 页面不再显示或提交手工替换字段和专门确认框 | 通过 | +| 上传仍显示“导入中…”并阻止重复提交 | 通过 | +| 空快照走普通导入,不计为自动替换 | 通过 | +| 非空且全部安全的整日旧快照自动替换 | 通过 | +| 未删除、非 `pending` 或任一处理证据都会退回普通导入 | 通过 | +| 自动替换成功反馈显示实际替换数量 | 通过 | +| 普通导入的组成码冲突、幂等恢复和文件校验保持不变 | 通过 | +| 删除数量变化或后续写入失败时事务回滚 | 通过 | +| 最新样本仍解析为 123 个源行、122 条业务记录、合并 1 行 | 通过 | +| 不新增 schema、不改 Client 接口、不提交源 Excel | 通过 | + +## 测试 + +- 执行的命令: + - `$env:GOTOOLCHAIN='go1.23.0'; go build ./...; go test ./... -count=1; go vet ./...` + - `node --check static/js/app.js` + - 使用正式解析器只读检查 `Shopee_mapping_20260826 (3).xlsx` +- 结果:Go 1.23.0 全量编译、测试、vet 和 JavaScript 语法检查通过;样本业务日期为 + 2026-08-26,读取 123 行、合并 1 行、最终 122 条。 +- **没验证到的部分**:未连接隔离 MySQL 8 测试库执行真实并发行锁测试;未部署生产; + 未使用生产文件执行自动替换;未做登录后的浏览器人工视觉验收。 + +## 相关提交 + +- `429ecf3` fix: 自动替换档口入库码安全旧快照 (#306)