# 90 Admin：规格匹配建议（规则层排序，人工确认）

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#15
- 状态：已完成（待验收）
- 日期：2026-08-10
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/90

## 背景与目标

#88 已把顺运宝原始规格作为主链路，但采购员仍需在全部 PDD SKU 中逐项查找。
本任务增加可解释的规则建议和稳定排序，减少人工查找，同时坚持由采购员最终确认，
不把规则建议直接保存为映射，也不触发采购或下单。

## 最终方案

- 新增 `rules_v1` 规则层：统一常用繁简颜色、尺码别名、公斤/斤单位和体重区间，
  将候选分为 A、B、C 和冲突四级，并在同级中保持原始顺序。
- 只有唯一 A 级候选且不存在额外规格维度歧义时才默认选中；多个 A 级、缺少信息或
  存在颜色、尺码、体重冲突时只排序和说明原因，不自动选择。
- 页面展示“建议”标识、文字原因和核对提示，不展示数值分数；保存动作仍要求采购员提交。
- 保存时由服务端重新计算建议结果，不采用浏览器提交的建议等级或采纳状态。
- 对货运单、商品、规格、PDD SKU 和规则版本计算上下文版本；页面打开后数据发生变化时，
  拒绝过期保存并要求重新查看。
- MySQL 追加 v4 `spec_mapping_decisions` 表；映射保存与决策审计使用同一事务，记录规则版本、
  建议项、最终选择和是否采纳。审计写入失败时映射一并回滚。
- 与原工单方案一致，没有增加自动保存、自动采购、统计页面或机器学习评分。
- 生产发布预检发现 `autobuy` 已于 2026-08-10 12:31:48（北京时间）记录 v4，审计表为空且
  结构正确；因此发布时没有重复执行迁移，而是先停服备份，再将线上 Admin 从 `f0715ee`
  原子切换到包含本任务的 `5a77bde`，使运行代码与数据库版本一致。

## 改了哪些

- `admin/service/specmatch.go`、`specmatch_test.go`：建议规则、候选排序、歧义判断和样例测试。
- `admin/service/purchase_workflow.go`、`purchase_workflow_test.go`：上下文校验、服务端复算、
  映射与审计事务及回滚测试。
- `admin/model/model.go`、`admin/repository/`：候选展示字段、决策审计模型与 MySQL v4 迁移自检。
- `admin/handler/web/others.go`、`admin/templates/syb/detail_modal.html`：传递上下文版本，显示建议、
  理由和人工核对提示。
- `docs/admin/01-requirements.md`、`03-data-model.md`、`05-ui-specification.md`：同步业务规则、
  审计结构、统计查询和界面约束。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 候选按 A/B/C/冲突稳定排序，只有唯一无歧义 A 级默认选中 | 通过 |
| 繁简颜色、尺码别名、公斤/斤、体重区间和多维规格均有测试 | 通过 |
| 页面仅给出可解释建议，不显示分数、不自动保存或采购 | 通过 |
| 最终保存以服务端复算为准，选择非建议项时正确记录未采纳 | 通过 |
| 上下文变化后拒绝过期页面保存 | 通过 |
| 映射与决策审计同事务写入，审计失败时完整回滚 | 通过 |
| MySQL v3→v4、迁移重放和错误表结构自检 | 通过 |
| 管理员与采购员页面权限回归 | 通过 |
| 生产库 v4 唯一版本记录、审计表结构、约束、服务健康和关键数据计数 | 通过 |

## 测试

- 执行的命令：
  - `cd D:\chengma\cmautobuy\admin; $env:GOTOOLCHAIN='go1.23.0'; go vet ./...; gofmt -l .; go test ./... -count=1`
  - 设置隔离 `_test` 库环境变量后执行 `go test ./repository -run 'TestMySQLMigrate_' -count=1 -v`
  - 设置相同环境后执行规格建议、决策审计、过期上下文、事务回滚和主页面定向测试
  - 生产发布时停止 `cmautobuy-admin`，执行单事务逻辑备份、压缩包完整性检查、二进制
    SHA-256 校验、原子切换和自动失败回退脚本，再检查 systemd、监听地址、数据库结构、
    关键表计数、近期日志及公网 HTTP 状态。
- 结果：静态检查、格式检查、普通全量测试通过；真实 MySQL 8 隔离库的 v4 迁移、事务和页面回归通过；
  生产 `schema_migrations` 为 v4 且仅一条，`spec_mapping_decisions` 为 InnoDB、10 列并包含
  `accepted` 约束；服务 active，近期无 warning/error，公网登录页返回 200。
- **没验证到的部分**：未在真实浏览器中人工核对包含 48 个以上候选的弹窗滚动、建议展示和选择体验。

## 相关提交

- `5a77bde` `feat: 增加规格匹配建议与决策审计 (#90)`
- `d470209` `docs: 归档任务 #90`