docs: 归档任务 #304

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` 支持档口入库码同日安全替换