docs: 归档任务 #225

docs/task/225-Admin档口入库码独立Tab交互原型.md

@@ -0,0 +1,55 @@
+# 225 Admin：设计档口入库码独立 Tab 交互原型
+
+- 类型：需求
+- 父级大工单：#14
+- 所属 MVP / 版本：#224 / 档口入库码回写 MVP
+- 状态：已完成，待用户确认原型
+- 日期：2026-08-14
+- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/225
+
+## 背景与目标
+
+线下档口入库码需要迁入 Admin，但用户明确要求该能力不能放在顺运宝模块中，
+应新增独立一级 Tab，并放在“客户端列表”之后。正式开发数据库、接口和回写逻辑前，
+先通过交互原型确认采购员的操作路径和异常处理方式。
+
+## 最终方案
+
+- 新增一个不依赖网络资源的单文件 HTML 原型，不修改 Admin 生产代码。
+- 主导航中把“档口入库码”放在“客户端列表”之后，作为独立模块展示。
+- 页面只使用一张列表表达最小闭环：导入 Excel、确定性匹配、选择可回写记录、
+  二次确认、逐条回写以及结果查看。
+- 原型使用虚构数据演示唯一匹配、歧义跳过、已有采购信息跳过、远端值已存在、
+  回写失败和“需核对”等情况。
+- “需核对”操作只演示重新读取远端并确认结果，不会再次执行写入，避免未知结果下重复回写。
+- 原型明确提示不会读取 Excel、调用 Admin 或连接顺运宝。
+
+## 改了哪些
+
+- `docs/prototypes/admin-inner-code.html`：增加独立“档口入库码”Tab 的静态交互原型，
+  内含模拟导入、匹配、筛选、勾选回写、确认和重新核对交互。
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+| 顶部导航展示独立“档口入库码”，且紧跟“客户端列表” | 通过 |
+| 可演示 Excel 导入和按业务日期生成单表记录 | 通过 |
+| 可演示唯一匹配进入可回写、歧义或条件不符显示原因 | 通过 |
+| 只有可回写记录可勾选，确认框展示记录数和旧值处理数 | 通过 |
+| 可演示回写进度、成功、失败、需核对和重新核对 | 通过 |
+| 1366×768 下关键操作、表格滚动、焦点和状态反馈可用 | 通过 |
+| 没有真实接口调用，也没有修改 Admin 生产代码、路由和数据库 | 通过 |
+
+## 测试
+
+- 执行的命令：
+  - `python -c "from html.parser import HTMLParser; HTMLParser().feed(open(r'docs/prototypes/admin-inner-code.html', encoding='utf-8').read()); print('HTML parse OK')"`
+  - `node -e "const fs=require('fs'),h=fs.readFileSync('docs/prototypes/admin-inner-code.html','utf8'),m=h.match(/<script>([\s\S]*?)<\/script>/); new Function(m[1]); console.log('JS syntax OK')"`
+  - 使用 Playwright 在 1366×768 视口依次验证匹配、全选、回写确认、完成状态和重新核对。
+- 结果：HTML 解析和 JavaScript 语法通过；匹配得到 2 条可回写记录，确认框显示 2 条回写、1 条旧值处理；完成后 2 条进入已回写；需核对记录重新读取后进入已回写；新页面加载后的浏览器控制台无脚本错误。
+- **没验证到的部分**：尚未由用户确认视觉布局和业务操作习惯；真实 Excel 解析、数据库迁移、Admin 接口和顺运宝远端回写不属于本原型工单，均未执行。
+
+## 相关提交
+
+- `b82ea77` docs: 增加档口入库码交互原型 (#225)