# 202 Admin：顺运宝列表增加批量 AI 匹配、进度与筛选

- 类型：需求
- 父级大工单：#14
- 所属 MVP / 版本：#199 / AI规格批量匹配
- 状态：已完成，待用户验收
- 日期：2026-08-14
- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/202

## 背景与目标

采购员需要在顺运宝列表批量处理已经关联并采集 PDD 数据的商品，而不是逐条打开详情。
批量操作必须持久化进度、逐条展示结果，并保持人工映射优先、上下文失效保护和“不创建采购
任务”的边界。

## 最终方案

- MySQL v22 增加批次和批次明细表，保存创建人、非敏感配置快照、进度、逐条结果和重启
  中断状态，不保存 API Key。
- 顺运宝列表增加“AI匹配”和“匹配记录”，最多提交 100 条。后台使用配置并发上限执行；
  相同蝦皮商品、顺运宝规格与 PDD 上下文只处理一次，其余明细从当前有效映射复用。
- 每条继续调用 #201 的核心服务，模型不能绕过候选白名单、硬门禁、上下文版本和人工优先。
  单条失败不会回滚其他成功条目。
- 进度弹窗轮询服务端状态，显示总数、已处理、成功、复用、待人工、失败和逐条原因；采购员
  只能查看自己的批次，管理员可以查看全部。
- 增加独立匹配来源徽标和“AI规格匹配”来源筛选。人工详情改写会把当前来源改为人工，AI
  历史决策和批次记录保留。
- Admin 启动时把遗留的等待中/运行中批次标记为中断，成功映射不回滚，未完成条目可重新
  勾选重试。

实施时补充了 `AISpecMatchResult.ConfidenceSet`，用于区分“模型明确返回 0%”和“没有置信度”，
避免批次记录把有效零值误判为空值；不改变 #201 的匹配门禁和保存结论。

## 改了哪些

- `admin/repository/mysql_db.go`、`admin/repository/ai_match_batch.go`：MySQL v22、批次持久化、
  进度统计和中断收敛。
- `admin/service/ai_match_batch.go`、`admin/service/ai_specmatch.go`、`admin/service/syb.go`：批次
  编排、上下文去重、来源筛选、来源展示和置信度零值语义。
- `admin/handler/web/ai_match.go`、`admin/handler/web/others.go`、`admin/handler/web/web.go`、
  `admin/main.go`：创建/查询路由、页面数据和启动恢复。
- `admin/templates/syb/`、`admin/static/js/app.js`、`admin/static/css/app.css`：批量确认、进度
  弹窗、轮询、来源徽标和 1366px 紧凑布局。
- `admin/service/ai_match_batch_test.go` 及既有回归测试：去重身份、结果分类、权限、中断和批次
  汇总测试。
- `docs/admin/`：同步需求、架构、数据模型、界面和安全基线。

## 验收结果

| 验收标准 | 结果 |
|---|---|
| 勾选可匹配明细创建批次，并在服务端限制空选择、重复 ID 和 100 条上限 | 通过 |
| 持久化批次/逐条状态，页面显示并自动刷新全部计数和逐条原因 | 通过 |
| 同一匹配上下文只处理一次，其余明细校验当前共享映射后复用 | 通过（专项集成用例已编写） |
| 人工映射不被覆盖，条件不足、失败和上下文变化不自动写入 | 通过 |
| 合格结果可进入采购就绪，但批量操作不创建任务、不调用 Client | 通过 |
| “AI规格匹配”筛选和列表/详情来源徽标按当前有效来源工作 | 通过 |
| 人工修改后当前来源变为人工，历史审计保留 | 通过 |
| 启动收敛未完成批次，成功结果不回滚，允许安全重试 | 通过（专项集成用例已编写） |
| 采购员只看本人批次，管理员可看全部；页面有文字反馈和可滚动明细 | 通过 |
| Go 构建、测试、vet 和 JavaScript 语法检查 | 通过；真实 MySQL 项见下方未验证说明 |

## 测试

- 执行的命令：
  - `go test ./service -run 'Test(AISpecMatchIdentity|BatchItemFromMatch|AIMatchBatch_)' -count=1 -v`
  - `go test ./... -count=1`
  - `go vet ./...`
  - `node --check static/js/app.js`
  - `git diff --check`
- 结果：纯逻辑专项测试、完整 Go 测试、vet、JavaScript 语法和差异格式检查通过。MySQL 专项
  用例能被测试套件发现，并在没有测试库开关时按项目规则明确跳过。
- **没验证到的部分**：当前环境未提供启用 `CMAUTOBUY_MYSQL_TEST=1` 的独立 MySQL 8.4
  `_test` 数据库，因此没有实际执行 v22 首建/升级/重放、真实事务并发和进程重启后的数据库
  状态检查；也未连接真实模型服务或在浏览器 1366×768 人工验收。没有使用生产数据库代替。

## 相关提交

- `d64579e` feat: 增加顺运宝批量 AI 规格匹配 (#202)