OPC/goauto
2
0
Fork 0
Code Issues 200 Pull Requests Actions Packages Projects Releases Wiki Activity

功能：虾皮商品颜色与尺码映射引入 AI 建议，人工确认后保存 #172

New Issue
Open
opened 2026-08-31 15:53:50 +08:00 by ila · 0 comments
ila commented 2026-08-31 15:53:50 +08:00
Owner
Copy Link
Copy Source

Gitea MCP 未向当前会话暴露，按仓库规则回退项目根目录安全配置与 Gitea API 创建本工单；凭据未写入工单、代码或日志。

原始需求摘要

来源：用户于 2026-08-31 提出「蝦皮商品详情，颜色和尺码匹配，可以参考 D:\chengma\cmautobuy\admin 加入 AI 匹配，人工确认保存吗」，并在只读分析后确认三项选择：允许把商品标题一并发给 AI、低置信度只给理由不预填、颜色与尺码两步一起做。

目的：在虾皮商品详情的规格映射编辑界面引入 AI 建议，减少人工逐项选择颜色与尺码的工作量，同时保持「AI 只产生草稿建议、人工确认后才落库」的边界。

基线与已核实事实

代码基线：d89a027（2026-08-31）。核验日期 2026-08-31。

现有能力：

  • 尺码已有「建议 → 人工确认 → 保存」形态：PreviewAutoSizeMatches（shopeeproduct/auto_size.go:108）+ 前端「一键自动匹配」（web/src/views/goauto/shopee-products/index.vue:113）。前端只写入 pddValueDraft 草稿，不落库。
  • 但该预览只调用 aimatching.DeterministicMatch（规范化后唯一匹配），匹配不到即标记 pending 交人工，不调用任何 AI。
  • 颜色没有任何自动匹配，只有手工下拉选择（index.vue:101-107）。
  • AI 基础设施已存在：aimatching 包提供 Provider 配置、密钥存储、Resolve 与候选校验 validChoice（aimatching/service.go:281），当前只在采购期精确规格决策使用（#46）。
  • AIMatchingSetting 已有 AutoConfirmMinConfidence（models/schema.go:108，默认 0.9，约束 0～1）与 Enabled、TimeoutSeconds 等字段，无需新增配置表。
  • 映射写入路径已存在且唯一：PUT /specs/mapping、POST /specs/mapping/confirm、POST /specs/mapping/confirm-exact-matches（shopeeproduct/router.go:22-26）。
  • API Key 明文存储于 ai_matching_setting 属 #62 已确认例外，本单不改变该存储方式，也不新增任何凭据面。

参考实现核验（只读，D:\chengma\cmautobuy\admin）：

  • service/ai_color_suggestion.go（308 行）采用「短编号绑定 + 批量单次调用 + contextVersion 校验 + 置信度阈值 + 只读建议」的组合，建议不落库，正式写入仍走既有保存路径。
  • 其请求体包含 shopee_title 与 pdd_title，来源上限 100、候选上限 150。

判断边界

  • 已确认：颜色映射错误会直接导致 Agent 点错规格、买错商品，因此任何自动落库都不可接受。
  • 已确认：本单是新的数据出境场景——此前 AI 只在采购期接收规格文本（#46/#62），本单新增商品标题与颜色文本。用户已于 2026-08-31 明确同意发送商品标题。
  • 尚未确认：真实商品上 AI 颜色建议的准确率与合适的置信度阈值，需实施后按真实数据观察，本单不预设指标。

目标

  1. 虾皮商品详情的颜色匹配页签增加 AI 建议：批量为当前商品所有待匹配颜色生成建议，人工确认后保存。
  2. 尺码匹配在现有确定性匹配基础上增加 AI 兜底：确定性匹配成功的项不调用 AI，仅对 pending 项调用。
  3. 建议结果一律只写入前端草稿，人工点击保存才落库；不存在任何自动确认或自动保存路径。
  4. 引入上下文版本校验，防止基于过期候选保存建议。
  5. AI 返回的目标值必须落在服务端下发的候选集合内，模型不能产生候选之外的字符串。

非目标

  • 不做自动确认、自动保存、高置信度直接落库。
  • 不修改现有映射写入接口的语义、幂等与校验规则。
  • 不修改 #46 采购期 AI 决策路径、其提示词与置信度语义。
  • 不新增 AI Provider 配置表、不改变 API Key 存储方式、不新增凭据接口。
  • 不移植参考实现的目录结构、错误体系与数据库访问方式，只借鉴设计思路。
  • 不做模糊、子串、编辑距离匹配来提高命中率；证据不足即留给人工。
  • 不发送账号、地址、订单、支付、价格与个人数据给 AI。

前置依赖与并行性

  • 依赖既有 aimatching Provider 配置可用（Enabled=true 且连通性测试通过）。
  • 与修改 shopeeproduct 规格映射接口或 shopee-products/index.vue 映射区域的任务不可并行；#168 只改 PDD 选择弹窗与 PDD 商品列表页，区域不重叠，可并行但需注意同文件冲突。
  • 与 #164 的采购期规格决策无代码重叠，可并行。

固定实施方案

1. 上下文版本（正确性前置）

  • 详情接口返回 specContextVersion：由虾皮商品 id、关联 PDD 商品 id、PDD 规格快照与虾皮规格值集合派生的稳定摘要。
  • 生成建议与保存映射时都必须携带该版本；与服务端当前值不一致时拒绝，提示「商品关联或规格已变化，请刷新后重试」。
  • 该校验对手工保存同样生效，不只保护 AI 路径。

2. 服务端建议接口

新增两个只读接口（不写库）：

  • POST /api/admin/v1/shopee-products/:productId/specs/mapping/suggest-colors
  • POST /api/admin/v1/shopee-products/:productId/specs/mapping/suggest-sizes

共同约定：

  • 请求体只含 specContextVersion。
  • 一次性处理当前商品全部待匹配项，批量单次调用模型，禁止逐项调用。
  • 待匹配来源上限 100、PDD 候选上限 150，超出时拒绝并提示人工先缩小范围。
  • 已确认（confirmed）且目标仍在候选内的项跳过，不重新建议。
  • 尺码接口先跑 DeterministicMatch，只把 pending 项交给 AI。
  • 返回每项：来源值、建议的 PDD 值（可为空）、结论、置信度、理由、apply 标志。

3. 短编号绑定与严格校验

  • 发送给模型的来源与候选各自使用本次请求内的短编号（如 s1、c1），模型只允许返回编号。
  • 返回值翻译回真实字符串时必须校验编号存在于本次候选集合；出现未知编号、重复编号或候选外字符串，该项判为无建议并记录原因，不做任何猜测替换。
  • 复用 aimatching 既有的候选校验思路，不放宽相等语义。

4. 置信度与预填

  • 复用 AIMatchingSetting.AutoConfirmMinConfidence 作为预填阈值。
  • 命名歧义须在代码注释中写明：本单不做任何自动确认，该字段在本路径仅决定是否预填草稿；其在 #46 采购路径的既有语义不变。
  • 置信度 ≥ 阈值：apply=true，前端预填草稿并标为「AI 建议」。
  • 置信度 < 阈值：apply=false，只展示建议值与理由，不预填草稿，由人工自行选择。
  • 无建议项照常显示「待人工选择」。

5. 发送数据范围（安全边界）

发送给 AI 的字段仅限：

  • 虾皮商品标题、PDD 商品标题（用户已确认允许）；
  • 待匹配的虾皮颜色/尺码文本；
  • PDD 可选颜色/尺码候选文本。

禁止发送：账号、地址、订单、支付、价格、设备信息、任务信息与任何个人数据。API Key 只从既有配置读取，不出现在日志、错误消息与工单中；错误消息回传前必须做密钥脱敏。

6. 前端交互

  • 颜色页签增加「AI 匹配」按钮，交互形态与尺码现有「一键自动匹配」保持一致。
  • 尺码页签保留现有按钮，行为改为「确定性匹配优先、pending 项走 AI」，按钮文案相应调整。
  • 结果以行内标签区分来源：「格式统一匹配」「AI 建议」「AI 建议（置信度低，未预填）」「待人工选择」。
  • 保存动作、保存按钮与既有确认流程不变；未保存前刷新页面草稿丢失，与现有行为一致。
  • AI 未启用、未配置或调用失败时按钮可用但给出明确错误提示，不影响手工映射。

设计证据

在现有「颜色匹配 / 尺码匹配」页签内增加按钮与状态标签，属现有界面的小范围调整，复用当前映射表格与尺码预览的既有规范，不新增页面与组件，不需要完整原型。实施前提供标注截图交用户确认，覆盖：AI 建议成功（含高/低置信度两种行）、无建议、AI 未启用、AI 调用失败、上下文过期五个状态。

验收标准

  • 颜色页签可一次性为全部待匹配颜色生成 AI 建议，人工确认保存后映射正确落库。
  • 尺码页签确定性匹配成功的项不调用 AI；仅 pending 项进入 AI。
  • 置信度 ≥ 阈值预填草稿；置信度 < 阈值只显示建议与理由且不预填。
  • 任何路径下 AI 结果都不会自动落库；不保存直接刷新页面则建议全部丢失。
  • AI 返回候选集合之外的值、未知编号或重复编号时，该项判为无建议，不发生错误替换。
  • 生成建议后修改商品关联或重新采集 PDD 规格，再保存时被上下文版本校验拒绝并提示刷新。
  • 手工保存路径同样受上下文版本校验保护。
  • 单次请求只调用一次模型；超过来源 100 或候选 150 时明确拒绝。
  • 发送内容仅含双方商品标题与规格文本；日志、错误消息与接口响应中不含 API Key、账号、地址、订单、支付与个人数据。
  • AI 未启用、未配置、超时、返回非法 JSON 时均有明确提示，不影响手工映射与保存。
  • 已确认映射不被 AI 建议覆盖。
  • #46 采购期 AI 决策路径行为未改变，其既有测试通过。
  • Server 单元测试与构建通过；Web 单元测试与既有 e2e 测试通过。

必测场景

  • 颜色：全部可建议、部分可建议、全部无建议。
  • 高置信度预填与低置信度不预填两条路径。
  • 模型返回未知编号、重复编号、候选外字符串、非法 JSON、超时。
  • 尺码：确定性匹配全中（不调用 AI）、部分 pending（只对 pending 调用）、全部 pending。
  • 已确认映射存在时被跳过，不被重新建议或覆盖。
  • 生成建议后更换关联 PDD 商品或重新采集规格，保存被拒绝。
  • 来源 100 / 候选 150 边界与超限拒绝。
  • AI 未启用、未配置 Provider、连通性失败。
  • 密钥脱敏：构造包含密钥的错误消息，验证回传内容已脱敏。

风险与安全门禁

  • 新的数据出境场景：本单新增向外部 AI 服务发送商品标题与颜色/尺码文本。用户已于 2026-08-31 明确同意发送商品标题。更换 Provider 地址前必须重新评估，本单不扩大到 Agent 端与任何 PDD 页面数据。
  • 错误映射直达采购：颜色/尺码映射决定 Agent 点击哪个规格，错误映射会导致买错商品。因此本单严禁自动落库，低置信度不得预填，候选校验不得放宽。
  • 不通过放宽相等判断或引入模糊匹配提高命中率；证据不足必须留给人工。
  • 涉及外部服务调用与采购前置数据，实施前需用户确认本方案。
  • 不修改地址、不创建订单、不支付。

文档影响

有长期文档影响。 新增两个 admin 接口、新增 specContextVersion 字段与其校验语义，并扩大 AI 服务的数据发送范围。须更新 Wiki 中的架构/接口页面与业务规则页面（记录「AI 只产生草稿建议、人工确认后落库」与新的数据出境范围）；在线回读 revision 后执行一次 python dev_scripts/harness.py sync 和一次 sync --check，revision 回写本工单。docs/08-agent-api-contract.md 为 Agent 契约，本单不涉及。

相邻问题（不在本单范围）

  • AI 建议的准确率评估与阈值调优需在真实数据上观察，必要时另建工单。
  • 参考实现中的繁简、别名归一化不在本单范围。

状态

待确认（2026-08-31 创建，等待用户确认方案与界面截图后方可实施）。

> Gitea MCP 未向当前会话暴露，按仓库规则回退项目根目录安全配置与 Gitea API 创建本工单；凭据未写入工单、代码或日志。 ## 原始需求摘要 来源：用户于 2026-08-31 提出「蝦皮商品详情，颜色和尺码匹配，可以参考 `D:\chengma\cmautobuy\admin` 加入 AI 匹配，人工确认保存吗」，并在只读分析后确认三项选择：**允许把商品标题一并发给 AI**、**低置信度只给理由不预填**、**颜色与尺码两步一起做**。 目的：在虾皮商品详情的规格映射编辑界面引入 AI 建议，减少人工逐项选择颜色与尺码的工作量，同时保持「AI 只产生草稿建议、人工确认后才落库」的边界。 ## 基线与已核实事实 代码基线：`d89a027`（2026-08-31）。核验日期 2026-08-31。 现有能力： - 尺码已有「建议 → 人工确认 → 保存」形态：`PreviewAutoSizeMatches`（`shopeeproduct/auto_size.go:108`）+ 前端「一键自动匹配」（`web/src/views/goauto/shopee-products/index.vue:113`）。前端只写入 `pddValueDraft` 草稿，不落库。 - 但该预览只调用 `aimatching.DeterministicMatch`（规范化后唯一匹配），匹配不到即标记 `pending` 交人工，**不调用任何 AI**。 - 颜色**没有任何自动匹配**，只有手工下拉选择（`index.vue:101-107`）。 - AI 基础设施已存在：`aimatching` 包提供 Provider 配置、密钥存储、`Resolve` 与候选校验 `validChoice`（`aimatching/service.go:281`），当前只在采购期精确规格决策使用（#46）。 - `AIMatchingSetting` 已有 `AutoConfirmMinConfidence`（`models/schema.go:108`，默认 0.9，约束 0～1）与 `Enabled`、`TimeoutSeconds` 等字段，无需新增配置表。 - 映射写入路径已存在且唯一：`PUT /specs/mapping`、`POST /specs/mapping/confirm`、`POST /specs/mapping/confirm-exact-matches`（`shopeeproduct/router.go:22-26`）。 - API Key 明文存储于 `ai_matching_setting` 属 #62 已确认例外，本单不改变该存储方式，也不新增任何凭据面。 参考实现核验（只读，`D:\chengma\cmautobuy\admin`）： - `service/ai_color_suggestion.go`（308 行）采用「短编号绑定 + 批量单次调用 + contextVersion 校验 + 置信度阈值 + 只读建议」的组合，建议不落库，正式写入仍走既有保存路径。 - 其请求体包含 `shopee_title` 与 `pdd_title`，来源上限 100、候选上限 150。 ## 判断边界 - 已确认：颜色映射错误会直接导致 Agent 点错规格、买错商品，因此任何自动落库都不可接受。 - 已确认：本单是**新的数据出境场景**——此前 AI 只在采购期接收规格文本（#46/#62），本单新增商品标题与颜色文本。用户已于 2026-08-31 明确同意发送商品标题。 - 尚未确认：真实商品上 AI 颜色建议的准确率与合适的置信度阈值，需实施后按真实数据观察，本单不预设指标。 ## 目标 1. 虾皮商品详情的颜色匹配页签增加 AI 建议：批量为当前商品所有待匹配颜色生成建议，人工确认后保存。 2. 尺码匹配在现有确定性匹配基础上增加 AI 兜底：确定性匹配成功的项不调用 AI，仅对 `pending` 项调用。 3. 建议结果一律只写入前端草稿，人工点击保存才落库；不存在任何自动确认或自动保存路径。 4. 引入上下文版本校验，防止基于过期候选保存建议。 5. AI 返回的目标值必须落在服务端下发的候选集合内，模型不能产生候选之外的字符串。 ## 非目标 - 不做自动确认、自动保存、高置信度直接落库。 - 不修改现有映射写入接口的语义、幂等与校验规则。 - 不修改 #46 采购期 AI 决策路径、其提示词与置信度语义。 - 不新增 AI Provider 配置表、不改变 API Key 存储方式、不新增凭据接口。 - 不移植参考实现的目录结构、错误体系与数据库访问方式，只借鉴设计思路。 - 不做模糊、子串、编辑距离匹配来提高命中率；证据不足即留给人工。 - 不发送账号、地址、订单、支付、价格与个人数据给 AI。 ## 前置依赖与并行性 - 依赖既有 `aimatching` Provider 配置可用（`Enabled=true` 且连通性测试通过）。 - 与修改 `shopeeproduct` 规格映射接口或 `shopee-products/index.vue` 映射区域的任务不可并行；#168 只改 PDD 选择弹窗与 PDD 商品列表页，区域不重叠，可并行但需注意同文件冲突。 - 与 #164 的采购期规格决策无代码重叠，可并行。 ## 固定实施方案 ### 1. 上下文版本（正确性前置） - 详情接口返回 `specContextVersion`：由虾皮商品 id、关联 PDD 商品 id、PDD 规格快照与虾皮规格值集合派生的稳定摘要。 - 生成建议与保存映射时都必须携带该版本；与服务端当前值不一致时拒绝，提示「商品关联或规格已变化，请刷新后重试」。 - 该校验对手工保存同样生效，不只保护 AI 路径。 ### 2. 服务端建议接口 新增两个只读接口（不写库）： - `POST /api/admin/v1/shopee-products/:productId/specs/mapping/suggest-colors` - `POST /api/admin/v1/shopee-products/:productId/specs/mapping/suggest-sizes` 共同约定： - 请求体只含 `specContextVersion`。 - 一次性处理当前商品全部待匹配项，**批量单次调用模型**，禁止逐项调用。 - 待匹配来源上限 100、PDD 候选上限 150，超出时拒绝并提示人工先缩小范围。 - 已确认（`confirmed`）且目标仍在候选内的项跳过，不重新建议。 - 尺码接口先跑 `DeterministicMatch`，只把 `pending` 项交给 AI。 - 返回每项：来源值、建议的 PDD 值（可为空）、结论、置信度、理由、`apply` 标志。 ### 3. 短编号绑定与严格校验 - 发送给模型的来源与候选各自使用本次请求内的短编号（如 `s1`、`c1`），模型只允许返回编号。 - 返回值翻译回真实字符串时必须校验编号存在于本次候选集合；出现未知编号、重复编号或候选外字符串，该项判为无建议并记录原因，不做任何猜测替换。 - 复用 `aimatching` 既有的候选校验思路，不放宽相等语义。 ### 4. 置信度与预填 - 复用 `AIMatchingSetting.AutoConfirmMinConfidence` 作为**预填阈值**。 - **命名歧义须在代码注释中写明**：本单不做任何自动确认，该字段在本路径仅决定是否预填草稿；其在 #46 采购路径的既有语义不变。 - 置信度 ≥ 阈值：`apply=true`，前端预填草稿并标为「AI 建议」。 - 置信度 < 阈值：`apply=false`，**只展示建议值与理由，不预填草稿**，由人工自行选择。 - 无建议项照常显示「待人工选择」。 ### 5. 发送数据范围（安全边界） 发送给 AI 的字段**仅限**： - 虾皮商品标题、PDD 商品标题（用户已确认允许）； - 待匹配的虾皮颜色/尺码文本； - PDD 可选颜色/尺码候选文本。 **禁止发送**：账号、地址、订单、支付、价格、设备信息、任务信息与任何个人数据。API Key 只从既有配置读取，不出现在日志、错误消息与工单中；错误消息回传前必须做密钥脱敏。 ### 6. 前端交互 - 颜色页签增加「AI 匹配」按钮，交互形态与尺码现有「一键自动匹配」保持一致。 - 尺码页签保留现有按钮，行为改为「确定性匹配优先、pending 项走 AI」，按钮文案相应调整。 - 结果以行内标签区分来源：「格式统一匹配」「AI 建议」「AI 建议（置信度低，未预填）」「待人工选择」。 - 保存动作、保存按钮与既有确认流程不变；未保存前刷新页面草稿丢失，与现有行为一致。 - AI 未启用、未配置或调用失败时按钮可用但给出明确错误提示，不影响手工映射。 ## 设计证据 在现有「颜色匹配 / 尺码匹配」页签内增加按钮与状态标签，属现有界面的小范围调整，复用当前映射表格与尺码预览的既有规范，不新增页面与组件，不需要完整原型。实施前提供标注截图交用户确认，覆盖：AI 建议成功（含高/低置信度两种行）、无建议、AI 未启用、AI 调用失败、上下文过期五个状态。 ## 验收标准 - [ ] 颜色页签可一次性为全部待匹配颜色生成 AI 建议，人工确认保存后映射正确落库。 - [ ] 尺码页签确定性匹配成功的项不调用 AI；仅 `pending` 项进入 AI。 - [ ] 置信度 ≥ 阈值预填草稿；置信度 < 阈值只显示建议与理由且**不预填**。 - [ ] 任何路径下 AI 结果都不会自动落库；不保存直接刷新页面则建议全部丢失。 - [ ] AI 返回候选集合之外的值、未知编号或重复编号时，该项判为无建议，不发生错误替换。 - [ ] 生成建议后修改商品关联或重新采集 PDD 规格，再保存时被上下文版本校验拒绝并提示刷新。 - [ ] 手工保存路径同样受上下文版本校验保护。 - [ ] 单次请求只调用一次模型；超过来源 100 或候选 150 时明确拒绝。 - [ ] 发送内容仅含双方商品标题与规格文本；日志、错误消息与接口响应中不含 API Key、账号、地址、订单、支付与个人数据。 - [ ] AI 未启用、未配置、超时、返回非法 JSON 时均有明确提示，不影响手工映射与保存。 - [ ] 已确认映射不被 AI 建议覆盖。 - [ ] #46 采购期 AI 决策路径行为未改变，其既有测试通过。 - [ ] Server 单元测试与构建通过；Web 单元测试与既有 e2e 测试通过。 ## 必测场景 - 颜色：全部可建议、部分可建议、全部无建议。 - 高置信度预填与低置信度不预填两条路径。 - 模型返回未知编号、重复编号、候选外字符串、非法 JSON、超时。 - 尺码：确定性匹配全中（不调用 AI）、部分 pending（只对 pending 调用）、全部 pending。 - 已确认映射存在时被跳过，不被重新建议或覆盖。 - 生成建议后更换关联 PDD 商品或重新采集规格，保存被拒绝。 - 来源 100 / 候选 150 边界与超限拒绝。 - AI 未启用、未配置 Provider、连通性失败。 - 密钥脱敏：构造包含密钥的错误消息，验证回传内容已脱敏。 ## 风险与安全门禁 - **新的数据出境场景**：本单新增向外部 AI 服务发送商品标题与颜色/尺码文本。用户已于 2026-08-31 明确同意发送商品标题。更换 Provider 地址前必须重新评估，本单不扩大到 Agent 端与任何 PDD 页面数据。 - **错误映射直达采购**：颜色/尺码映射决定 Agent 点击哪个规格，错误映射会导致买错商品。因此本单严禁自动落库，低置信度不得预填，候选校验不得放宽。 - 不通过放宽相等判断或引入模糊匹配提高命中率；证据不足必须留给人工。 - 涉及外部服务调用与采购前置数据，实施前需用户确认本方案。 - 不修改地址、不创建订单、不支付。 ## 文档影响 **有长期文档影响。** 新增两个 admin 接口、新增 `specContextVersion` 字段与其校验语义，并扩大 AI 服务的数据发送范围。须更新 Wiki 中的架构/接口页面与业务规则页面（记录「AI 只产生草稿建议、人工确认后落库」与新的数据出境范围）；在线回读 revision 后执行一次 `python dev_scripts/harness.py sync` 和一次 `sync --check`，revision 回写本工单。`docs/08-agent-api-contract.md` 为 Agent 契约，本单不涉及。 ## 相邻问题（不在本单范围） - AI 建议的准确率评估与阈值调优需在真实数据上观察，必要时另建工单。 - 参考实现中的繁简、别名归一化不在本单范围。 ## 状态 待确认（2026-08-31 创建，等待用户确认方案与界面截图后方可实施）。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/goauto#172