From 80a2167e4c4aabecf082f6982303be03f15e96f0 Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 26 Aug 2026 12:11:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E4=BB=BB=E5=8A=A1=20?= =?UTF-8?q?#304?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...档口入库码同日新版安全替换.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/task/304-档口入库码同日新版安全替换.md diff --git a/docs/task/304-档口入库码同日新版安全替换.md b/docs/task/304-档口入库码同日新版安全替换.md new file mode 100644 index 0000000..2ffce8b --- /dev/null +++ b/docs/task/304-档口入库码同日新版安全替换.md @@ -0,0 +1,70 @@ +# 304 Admin：支持同日最新版档口入库码快照安全替换 + +- 类型：缺陷 / 需求 +- 父级大工单：#14 +- 所属 MVP / 版本：#224 / 档口入库码回写 MVP +- 状态：已完成 +- 日期：2026-08-26 +- Gitea 工单：https://git.ilapage.cn/OPC/cmautobuy/issues/304 + +## 背景与目标 + +同一业务日期的 Excel 重新生成后，商品增删或排序变化会重新分配档口入库码。原有导入 +会继续把软删除记录视为入库码拥有者，因此最新文件会与旧快照发生归属冲突。 + +本次保留普通导入的唯一性和幂等规则，只增加一个由操作员明确选择的安全替换入口：仅当 +同日旧数据全部已软删除、仍为 `pending` 且从未匹配、排队或回写时，才用最新文件原子 +替换整日旧快照。 + +## 最终方案 + +- 原有 `ImportInnerCodeExcel` 保持默认行为，通过无选项包装兼容已有调用。 +- 新增导入选项。替换模式先解析并校验完整 Excel，再在 MySQL 事务中锁定同日全部旧记录。 +- service 逐条检查软删除标记、精确 `pending` 状态，以及匹配、规划、批次、远端结果和 + 应用审计字段；任意处理痕迹都会阻止整批替换。 +- 安全检查通过后，repository 按业务日期物理删除已锁定旧快照并核对影响行数，再写入 + 最新记录。删除、插入或提交任一步失败都会回滚。 +- 页面增加默认不勾选的“替换当日已删除旧数据”复选项。勾选提交时先显示包含后端门禁 + 条件的二次确认；失败明确提示本次没有删除或导入任何数据，成功显示替换数量。 +- UI 按数据密集型内部管理页面处理：危险选项使用可见文字和边框，不只依赖颜色，并保留 + 键盘焦点样式与导入中的禁用反馈。 +- 没有新增数据库表或字段，没有修改 Client 接口，也没有连接生产库执行替换。 + +## 改了哪些 + +- `admin/repository/inner_code.go`：增加同日完整快照锁定和带数量核对的事务删除。 +- `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/*_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` + - `$env:GOTOOLCHAIN='go1.23.0'; go vet ./...` + - `node --check static/js/app.js` + - 使用项目正式 Excel 解析器只读检查 `Shopee_mapping_20260826 (3).xlsx` +- 结果：Go 1.23.0 全量编译、测试、vet 和 JavaScript 语法检查通过；样本统计为 + 业务日期 2026-08-26、读取 123 行、合并 1 行、最终 122 条。 +- **没验证到的部分**：未连接隔离 MySQL 8 测试库执行真实行锁并发测试；未部署生产，也未 + 对生产 2026-08-26 数据执行替换；浏览器人工视觉验收留给用户验收阶段。 + +## 相关提交 + +- `ee3049b` 支持档口入库码同日安全替换