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

2026-08-14 10:30:08 +08:00
parent 0201dab98c
commit d64579e9b3
26 changed files with 1289 additions and 26 deletions
@@ -144,7 +144,7 @@ syb:
 |---|---|
 | 蝦皮数据 | 导入蝦皮商品报表，填 PDD 链接，发起采集 |
 | PDD 商品 | 维护拼多多商品档案，发起采集，查看采回来的规格价格。这个页面不依赖蝦皮和顺运宝的任何数据，单独就能跑通"建商品 → 建采集任务 → 领走执行 → 提交结果 → 显示已采集"这条闭环，见 [05 界面规范](05-ui-specification.md) §5 |
-| 顺运宝数据 | 同步货运单（需要先配置 `config.yaml`，见上一节）。规格匹配和生成采购任务是后续工单的范围，本页暂不提供 |
+| 顺运宝数据 | 同步货运单、关联/采集 PDD、人工或批量 AI 规格匹配，并创建采购任务；顺运宝账号配置见上一节，AI 配置只由管理员维护 |
 | 采集采购 | 看采集和采购任务执行到哪一步了 |
 | 客户端列表 | 看哪些客户端在干活 |

@@ -407,6 +407,13 @@ Admin 本地时区，付款状态只是 Client 核单上报时的快照，Admin
 - API Key 不进入数据库、`data/`、日志或 HTTP 响应，保存后只显示固定掩码和尾四位。
 - 模型只能选择服务端提供的当前可购买候选；不确定、超时或硬校验失败时保持人工处理。
 - AI 匹配不会创建采购任务，不改变 Client 接口，也不放宽真实采购门禁。
+- 采购员在顺运宝列表勾选最多 100 条可匹配明细后创建批次；批次固定使用创建时的服务商、
+  模型和运行参数快照。相同蝦皮商品、顺运宝规格及 PDD 候选上下文在一个批次内只调用一次，
+  其余明细复用结果。
+- 页面持续显示批次总数、已处理、成功、复用、待人工、失败和逐条原因。Admin 重启时把未完成
+  批次标为中断，已经保存的映射不回滚；操作员可以重新勾选未成功条目安全重试。
+- “AI规格匹配”是当前有效映射的来源筛选，不替代“可创建采购任务”等业务阶段。人工修改后
+  当前来源立即变为人工，但历史 AI 决策和批次记录继续保留。

 ## 5. 创建采购任务的校验

@@ -268,6 +268,11 @@ AI 服务商的普通配置和非敏感审计由 `repository` 写入 MySQL。API
 唯一确定的规则结果不调用模型；有效人工映射始终优先。保存前重新计算上下文版本并检查
 当前可购买候选，防止 PDD 重采集或人工并发修改后写入过期结果。

+批量入口先在事务中创建 `ai_match_batches` 和逐条 `ai_match_batch_items`，再由 Admin 进程内
+的有界工作池执行。工作池按业务上下文哈希归并相同明细，运行中持续写入逐条状态和汇总计数；
+浏览器只轮询批次状态接口，不持有 API Key，也不承担匹配判断。Admin 启动时把遗留的
+`queued/running` 批次和未完成明细标记为 `interrupted`，成功映射保持不变。
+
 ## 10. 相关文档

 - [上手指南](00-getting-started.md)
@@ -1006,3 +1006,18 @@ CREATE UNIQUE INDEX idx_client_assignment_current
 `ai_provider_audits` 追加记录创建、修改、测试、启停以及密钥替换/清除动作，只保存字段
 名和非敏感状态。两张表都没有 API Key、Token 或 Secret 列；API Key 只存在部署指定的
 独立密钥文件。
+
+## 16. AI 规格匹配批次（MySQL v22）
+
+`ai_match_batches` 保存一次批量操作的创建人、状态、计数以及创建时的非敏感服务商配置
+快照。状态为 `queued/running/partial/succeeded/failed/interrupted`，单批最多 100 条。
+快照包含服务商名称、Base URL、模型、超时、并发、阈值和配置指纹，但绝不包含 API Key。
+
+`ai_match_batch_items` 每条对应一个顺运宝明细，保存上下文版本、同批去重身份、负责人明细、
+处理状态、结果来源、选项键、置信度和简短原因。`(batch_id, syb_id)` 唯一，保证一条明细在
+同一批次内只出现一次。相同身份只有负责人调用规则/模型，跟随项读取已保存的共享映射并记为
+复用；上下文变化时记为 `stale`，不得套用旧结果。
+
+批次记录用于进度、故障恢复和操作审计；具体模型决策证据仍只追加到
+`ai_spec_match_decisions`。Admin 重启把未完成明细改为 `interrupted` 并完成批次计数，已经
+成功写入的 `spec_mappings` 不回滚。
@@ -917,6 +917,20 @@ API Key 使用密码输入框，只允许替换或清除。已保存值显示固
 复制或下载明文的入口。修改普通配置或密钥后明确提示“需要重新测试”；测试失败保留上一
 个已启用服务商，错误消息只说明原因和恢复动作，不展示响应正文。

+### 8.5 顺运宝批量 AI 规格匹配
+
+顺运宝工具条提供“AI匹配”和“匹配记录”（无障碍名称使用完整业务名称）。只有处于规格待匹配或采购就绪、且 PDD
+已经采集的行可用于该动作；复选框可以同时支持采购与 AI 匹配，按钮按各自能力单独计数。
+确认弹窗显示本次条数、100 条上限和“不创建采购/不触发 Client”的边界。
+
+提交后打开进度弹窗，使用文字和进度条同时显示状态，并列出成功、复用、待人工、失败计数
+及逐条原因。运行中自动轮询，另提供“刷新进度”和“刷新列表”；明细表限制高度并可滚动，
+1366×768 下操作按钮仍可见。采购员只能查看自己创建的记录，管理员可以查看全部。
+
+列表增加“匹配来源”文字徽标：人工匹配、规则匹配、AI匹配。颜色只作辅助，来源必须有文字；
+映射失效时追加“已失效”。“AI规格匹配”筛选只命中当前有效、来源为 AI、且仍处于采购就绪
+阶段的明细，后续进入采购任务阶段后不再命中，但行和详情中的来源标记继续显示。
+
 ## 9. 反馈方式

 | 场景 | 怎么反馈 |
@@ -270,3 +270,9 @@ CMAutoBuyAdmin/
 - 测试失败、超时和非 2xx 响应不得记录 Authorization、完整请求或完整响应。
 - 规格匹配请求只包含商品标题、规格文本和候选短编号，不包含订单号、店铺账号、用户、地址或 Client 信息。
 - 模型返回值必须经过严格 JSON 结构、候选白名单、颜色冲突、额外维度、置信度和上下文版本校验；模型自报置信度不能替代硬门禁。
+- 批量匹配用服务端限制单批 100 条和配置的有界并发；相同业务上下文只调用一次，跟随项必须
+  复用数据库中的当前有效映射，不能只复制模型文本结果。
+- 批次和逐条状态必须持久化。Admin 异常退出或重启后，遗留 `queued/running` 状态改为
+  `interrupted`；成功映射不回滚，未完成条目允许重新勾选，且不能因为重试覆盖人工映射。
+- 批次状态接口按创建人隔离，管理员除外；响应和日志只含批次号、计数和脱敏原因，不含密钥、
+  完整模型请求/响应或订单隐私数据。