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

225 Admin：设计档口入库码独立 Tab 交互原型

• 类型：需求
• 父级大工单：#14
• 所属 MVP / 版本：#224 / 档口入库码回写 MVP
• 状态：已完成，待用户确认原型
• 日期：2026-08-14
• Gitea 工单：#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)