cmautobuy/docs/task/294-蝦皮与PDD商品颜色匹配可视化页面.md

294 蝦皮与 PDD 商品颜色匹配可视化页面

• 类型：需求
• 父级大工单：#291
• 所属 MVP / 版本：蝦皮与 PDD 商品级颜色映射
• 状态：已完成
• 日期：2026-08-24
• Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/294

背景与目标

采购员需要从蝦皮商品上下文进入独立工作区，查看颜色来源、当前 PDD 可购买颜色、已有映射 和失效状态，并一次保存多条颜色修改，不在详情长弹窗中继续堆功能。

最终方案

• 蝦皮列表和详情都增加“颜色匹配”入口，返回时保留筛选、页码和详情打开状态。
• 新增服务端渲染页面和 GET/POST 路由，不增加顶部模块；页面沿用现有 Admin 导航、工具条、 横向滚动表格和固定状态条。
• 原生 select/optgroup 依次展示当前选择、未使用颜色、已匹配但仍可选择的颜色，支持多对一； 候选显示人民币价格区间和可购买完整规格数。
• 原生 JavaScript 只负责分组、变更计数、筛选、明确清除、未保存离开提醒和防重复提交； 只提交发生变化的行，不计算业务身份或可购买性。
• 保存失败重新渲染页面并保留输入，错误获得焦点并通过 role=alert 播报；服务端以当前登录 账号、CSRF、上下文版本和实时候选重新校验整批输入。

改了哪些

• admin/handler/web/web.go、admin/handler/web/shopee.go：增加页面和保存路由。
• admin/service/color_mapping_page.go：组装页面摘要、状态和分组候选。
• admin/templates/shopee/color_mappings.html：实现独立工作区。
• admin/templates/shopee/list.html、detail_modal.html：增加入口并保留返回状态。
• admin/static/js/color_mappings.js、static/css/app.css：增加限定于本页的交互和布局。
• admin/color_mapping_template_test.go、service/color_mapping_test.go：覆盖模板安全字段和多对一分组。
• docs/admin/05-ui-specification.md：记录正式页面规范。

验收结果

验收标准	结果
列表和详情均可进入，并携带原筛选与页码返回	通过
使用独立 SSR 页面和横向滚动表格，不增加顶部模块	通过
未使用优先、已使用项显示占用者且允许多对一	通过
只保存变化行，支持清除、防重复提交和失败回显	通过
未关联、未采集、维度不唯一、失效和过期均有文字反馈	通过
CSRF、当前账号和服务端实时重验不信任浏览器候选	通过
控件可见标签、文字状态、焦点和播报齐全	通过

测试

• 执行的命令：node --check static/js/color_mappings.js；go test ./... -count=1； go build ./...；go vet ./...；git diff --check
• 结果：通过。
• 没验证到的部分：未连接独立 MySQL 8.4 测试库启动完整 Admin，也未在真实浏览器以 1366×768 对正常、多对一、清除、过期和数据库失败状态逐项截图验收；布局按已通过的 #292 原型和现有 Admin CSS 实现。

相关提交

• 8162ae5 feat: 增加商品颜色匹配页面 (#294)
• c431982 fix: 保留颜色匹配页面返回状态 (#294)