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

Admin 蝦皮商品详情一键匹配并自动确认颜色尺码 #194

New Issue
Open
opened 2026-09-01 21:46:17 +08:00 by ila · 2 comments
ila commented 2026-09-01 21:46:17 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：无
  • 所属 MVP / 版本：采购规格匹配
  • 阶段：待实施

依赖与并行

  • 前置工单：#46、#62、#188、#190
  • 是否允许与前置工单并行：否
  • 原因：复用现有 AI Provider、自动确认门槛和 #190 已放宽的规格候选规则。

子项目影响

  • 交付单元：server、web、shared-docs
  • 是否跨子项目：是
  • 是否修改共享接口或契约：是；新增 Admin 蝦皮商品详情一键匹配接口，更新 Wiki API 契约。
  • 验证：Go 服务测试、Web 单元/E2E、前后端构建和仓库严格检查。

原始需求

  • 来源：用户对话
  • 提出时间：2026-09-01
  • 脱敏摘要：Admin 蝦皮商品详情的 AI 匹配改为一次匹配颜色和尺码，匹配成功后无需人工再次确认即可使用。

要解决什么

  • 当前代码事实：详情页颜色和尺码各有一个“AI 匹配”按钮；接口只返回未保存建议。前端还需逐项保存，通用 SetMapping 会把 exact_match / ai_match 写为 pending，AI 映射需要再次人工确认。
  • 目标契约：详情页提供一个“一键匹配颜色和尺码”动作；成功匹配项由服务端直接保存为 confirmed，刷新详情后立即可用于采购预检。
  • 假设：仅“成功且通过既有安全门槛”的结果自动确认；低置信度、无结果、候选无效、Provider 失败或输入漂移不保存、不猜测。

做什么 / 不做什么

  • 做：
    • 新增详情级一键匹配接口，一次处理颜色和尺码。
    • 保留仍有效的 confirmed 映射。
    • 唯一确定性匹配直接 confirmed。
    • AI 结果仅在置信度达到 autoConfirmMinConfidence、理由非空、结果属于当前 PDD 可选候选且写入前规格上下文未变化时 confirmed。
    • Provider 调用完成后在事务内重新校验 specContextVersion，颜色和尺码结果一次提交，避免部分写入。
    • 页面改为单个“一键匹配颜色和尺码”按钮，展示已匹配、未匹配和失败数量；成功后刷新详情。
    • 保留人工选择和保存，供自动匹配未覆盖的规格使用。
  • 不做：
    • 不降低置信度阈值，不保存低置信度建议。
    • 不改变 PDD/SYB 原始规格，不猜测候选，不修改采购创建和 Agent。
    • 不执行创建订单、发布或数据清理。

已确认方案

  • 服务端新增 POST /api/admin/v1/shopee-products/{productId}/specs/mapping/auto-match，请求包含 requestId 与 specContextVersion。
  • 响应返回颜色/尺码及合计的 confirmed、preserved、unmatched 数量和逐项脱敏结果。
  • 外部 AI 调用不持有数据库事务；生成全部决策后开启事务，重读蝦皮/PDD 商品并复核输入版本与候选，再一次写入 SpecsJSON。
  • requestId 提供幂等保护；上下文漂移返回 SPEC_CONTEXT_VERSION_STALE 且不写入。
  • 现有通用 SetMapping 的 pending 语义保持不变；自动确认只走本工单专用接口。

预计修改文件：

  • server/app/goauto/shopeeproduct/auto_match.go 及测试
  • server/app/goauto/shopeeproduct/handler.go、router.go
  • server/app/goauto/access/purchaser.go 及测试
  • web/src/api/goauto/shopee-products.js
  • web/src/views/goauto/shopee-products/ShopeeProductDetailDrawer.vue
  • 对应 Web 测试
  • Wiki：Business-Rules-and-Glossary、Android-Agent-API-Contract、Architecture-and-Code-Map 及同步镜像

需求变化记录

日期 变化内容 原因 用户确认
2026-09-01 颜色与尺码合并为一次操作；成功匹配直接 confirmed 用户要求减少人工二次确认 是

设计与原型门禁

  • 修改类型：现有页面小范围交互调整
  • 所需设计证据：明确复用现有规格匹配区、Element Plus 主按钮和反馈消息
  • 低保真：
    • 规格匹配　　　　X/Y 已匹配　[一键匹配颜色和尺码]
    • 提示：成功匹配会直接保存并可用于采购；未通过门槛的项目保持未匹配。
    • 下方继续保留“颜色匹配 / 尺码匹配”两个表格页签和人工选择控件。
  • 状态：已确认
  • 确认人/时间/范围：用户，2026-09-01；按钮、结果反馈、自动保存语义
  • 本地 HTML 导出：未要求
  • 无需完整原型原因：不新增页面、组件或导航，只合并现有按钮并改变既有匹配提交语义。

文档影响

  • 不影响长期文档
  • 更新架构与代码地图 Wiki
  • 更新业务规则与术语 Wiki
  • 更新 API 契约 Wiki

交付文档影响

  • 更新已有交付文档：管理员规格匹配规则和 API
  • 新增交付文档
  • 需要目标岗位或客户代表验证：否；由用户在待验收阶段检查详情页。

任务记录与可选快照

  • 单次任务事实来源：当前 Gitea 工单正文与评论
  • 默认不创建任务快照

验收标准

  • 详情页只显示一个“一键匹配颜色和尺码”按钮。
  • 单次点击同时处理存在的颜色和尺码；缺少某一维度时仍处理另一维度。
  • 确定性唯一匹配和达到阈值的合法 AI 匹配直接保存为 confirmed，刷新后计入“可采购”。
  • 已确认且仍有效的映射保持不变。
  • 低置信度、无结果、非法候选、Provider 失败或上下文漂移不产生部分/错误写入。
  • 人工选择与保存继续可用。
  • 接口、权限、服务端/Web 测试和构建通过。
  • 长期 Wiki 在线更新、回读 revision、sync 与 sync --check 完成。

验证方式

  • cd server && go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access
  • Web 受影响单元/E2E
  • .\scripts\verify.ps1 -Component server
  • .\scripts\verify.ps1 -Component web
  • python dev_scripts/harness.py check --strict
  • 人工检查详情页按钮、成功/部分成功/失败反馈和刷新后的 confirmed 状态。

风险和回退

  • 风险：AI 结果直接影响采购规格。通过服务端候选白名单、阈值、理由、上下文版本、事务写入及 fail-closed 控制。
  • 回退：回退专用接口和单按钮 UI；通用人工映射及 pending/confirm 流程不变，无数据库迁移。
## 基本信息 - 类型：需求 - 所属 Epic：无 - 所属 MVP / 版本：采购规格匹配 - 阶段：待实施 ## 依赖与并行 - 前置工单：#46、#62、#188、#190 - 是否允许与前置工单并行：否 - 原因：复用现有 AI Provider、自动确认门槛和 #190 已放宽的规格候选规则。 ## 子项目影响 - 交付单元：server、web、shared-docs - 是否跨子项目：是 - 是否修改共享接口或契约：是；新增 Admin 蝦皮商品详情一键匹配接口，更新 Wiki API 契约。 - 验证：Go 服务测试、Web 单元/E2E、前后端构建和仓库严格检查。 ## 原始需求 - 来源：用户对话 - 提出时间：2026-09-01 - 脱敏摘要：Admin 蝦皮商品详情的 AI 匹配改为一次匹配颜色和尺码，匹配成功后无需人工再次确认即可使用。 ## 要解决什么 - 当前代码事实：详情页颜色和尺码各有一个“AI 匹配”按钮；接口只返回未保存建议。前端还需逐项保存，通用 SetMapping 会把 exact_match / ai_match 写为 pending，AI 映射需要再次人工确认。 - 目标契约：详情页提供一个“一键匹配颜色和尺码”动作；成功匹配项由服务端直接保存为 confirmed，刷新详情后立即可用于采购预检。 - 假设：仅“成功且通过既有安全门槛”的结果自动确认；低置信度、无结果、候选无效、Provider 失败或输入漂移不保存、不猜测。 ## 做什么 / 不做什么 - 做： - 新增详情级一键匹配接口，一次处理颜色和尺码。 - 保留仍有效的 confirmed 映射。 - 唯一确定性匹配直接 confirmed。 - AI 结果仅在置信度达到 autoConfirmMinConfidence、理由非空、结果属于当前 PDD 可选候选且写入前规格上下文未变化时 confirmed。 - Provider 调用完成后在事务内重新校验 specContextVersion，颜色和尺码结果一次提交，避免部分写入。 - 页面改为单个“一键匹配颜色和尺码”按钮，展示已匹配、未匹配和失败数量；成功后刷新详情。 - 保留人工选择和保存，供自动匹配未覆盖的规格使用。 - 不做： - 不降低置信度阈值，不保存低置信度建议。 - 不改变 PDD/SYB 原始规格，不猜测候选，不修改采购创建和 Agent。 - 不执行创建订单、发布或数据清理。 ## 已确认方案 - 服务端新增 POST /api/admin/v1/shopee-products/{productId}/specs/mapping/auto-match，请求包含 requestId 与 specContextVersion。 - 响应返回颜色/尺码及合计的 confirmed、preserved、unmatched 数量和逐项脱敏结果。 - 外部 AI 调用不持有数据库事务；生成全部决策后开启事务，重读蝦皮/PDD 商品并复核输入版本与候选，再一次写入 SpecsJSON。 - requestId 提供幂等保护；上下文漂移返回 SPEC_CONTEXT_VERSION_STALE 且不写入。 - 现有通用 SetMapping 的 pending 语义保持不变；自动确认只走本工单专用接口。 预计修改文件： - server/app/goauto/shopeeproduct/auto_match.go 及测试 - server/app/goauto/shopeeproduct/handler.go、router.go - server/app/goauto/access/purchaser.go 及测试 - web/src/api/goauto/shopee-products.js - web/src/views/goauto/shopee-products/ShopeeProductDetailDrawer.vue - 对应 Web 测试 - Wiki：Business-Rules-and-Glossary、Android-Agent-API-Contract、Architecture-and-Code-Map 及同步镜像 ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-09-01 | 颜色与尺码合并为一次操作；成功匹配直接 confirmed | 用户要求减少人工二次确认 | 是 | ## 设计与原型门禁 - 修改类型：现有页面小范围交互调整 - 所需设计证据：明确复用现有规格匹配区、Element Plus 主按钮和反馈消息 - 低保真： - 规格匹配　　　　X/Y 已匹配　[一键匹配颜色和尺码] - 提示：成功匹配会直接保存并可用于采购；未通过门槛的项目保持未匹配。 - 下方继续保留“颜色匹配 / 尺码匹配”两个表格页签和人工选择控件。 - 状态：已确认 - 确认人/时间/范围：用户，2026-09-01；按钮、结果反馈、自动保存语义 - 本地 HTML 导出：未要求 - 无需完整原型原因：不新增页面、组件或导航，只合并现有按钮并改变既有匹配提交语义。 ## 文档影响 - [ ] 不影响长期文档 - [x] 更新架构与代码地图 Wiki - [x] 更新业务规则与术语 Wiki - [x] 更新 API 契约 Wiki ## 交付文档影响 - [x] 更新已有交付文档：管理员规格匹配规则和 API - [ ] 新增交付文档 - [ ] 需要目标岗位或客户代表验证：否；由用户在待验收阶段检查详情页。 ## 任务记录与可选快照 - 单次任务事实来源：当前 Gitea 工单正文与评论 - [x] 默认不创建任务快照 ## 验收标准 - [ ] 详情页只显示一个“一键匹配颜色和尺码”按钮。 - [ ] 单次点击同时处理存在的颜色和尺码；缺少某一维度时仍处理另一维度。 - [ ] 确定性唯一匹配和达到阈值的合法 AI 匹配直接保存为 confirmed，刷新后计入“可采购”。 - [ ] 已确认且仍有效的映射保持不变。 - [ ] 低置信度、无结果、非法候选、Provider 失败或上下文漂移不产生部分/错误写入。 - [ ] 人工选择与保存继续可用。 - [ ] 接口、权限、服务端/Web 测试和构建通过。 - [ ] 长期 Wiki 在线更新、回读 revision、sync 与 sync --check 完成。 ## 验证方式 - cd server && go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access - Web 受影响单元/E2E - .\scripts\verify.ps1 -Component server - .\scripts\verify.ps1 -Component web - python dev_scripts/harness.py check --strict - 人工检查详情页按钮、成功/部分成功/失败反馈和刷新后的 confirmed 状态。 ## 风险和回退 - 风险：AI 结果直接影响采购规格。通过服务端候选白名单、阈值、理由、上下文版本、事务写入及 fail-closed 控制。 - 回退：回退专用接口和单按钮 UI；通用人工映射及 pending/confirm 流程不变，无数据库迁移。
ila commented 2026-09-01 22:23:41 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，待验收

实现

  • 分支：feat/194-one-click-spec-match
  • 提交：041cd8d03fd53f84065b9c513f635e3b87729e75
  • Admin 蝦皮商品详情将原颜色/尺码两个“AI 匹配”入口合并为一个“一键匹配颜色和尺码”。
  • 单次请求同时处理已有颜色与尺码；保留有效 confirmed 映射，唯一确定匹配和达到当前阈值、理由非空、候选仍有效的 AI 匹配直接保存为 confirmed，无需人工二次确认。
  • 低置信度或无结果保持未匹配；Provider 异常、AI 未启用或规格上下文漂移时 fail-closed，不写入本次结果。
  • 新增专用接口 POST /api/admin/v1/shopee-products/{productId}/specs/mapping/auto-match，包含 UUID 幂等、specContextVersion 复核、事务内候选/设置复核和原子写入；通用 SetMapping 的 pending 语义不变。
  • 人工选择、清除、保存及旧 pending 确认能力继续保留。

验证

  • go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access：通过。
  • .\scripts\verify.ps1 -Component server：通过（全量 Go 测试与构建）。
  • 目标 ESLint：通过。
  • pnpm exec playwright test tests/e2e/shopee-pdd-picker.spec.ts：2 项通过。
  • pnpm build:prod：通过。
  • python dev_scripts/harness.py check --strict：通过。
  • Web 全量 verify 的 lint 被基线文件 web/src/views/goauto/purchase-tasks/index.vue 的 24 个既有缩进错误阻断；#194 未修改该文件，目标 lint、E2E 与生产构建均已通过，未混入相邻修复。

Wiki 与文档

  • 已更新 Architecture-and-Code-Map、Business-Rules-and-Glossary、Android-Agent-API-Contract。
  • 线上 Wiki revision：b94fd07dfdebe418257a675a779f83b782896543；3 页在线回读均命中新规则。
  • harness.py sync 与 sync --check：通过；目标镜像已提交。
  • Gitea MCP 不可用且当前 API Token 无效；浏览器编辑大页连续超时后，按用户已确认的写入范围回退到 Gitea 原生 Wiki Git 仓库，随后完成线上回读。

待人工验收

  • 在 Admin 蝦皮商品详情使用真实 AI Provider 验证成功、部分未匹配和失败反馈。
  • 工单保持开启，不关闭。
## 实施完成，待验收 ### 实现 - 分支：`feat/194-one-click-spec-match` - 提交：`041cd8d03fd53f84065b9c513f635e3b87729e75` - Admin 蝦皮商品详情将原颜色/尺码两个“AI 匹配”入口合并为一个“一键匹配颜色和尺码”。 - 单次请求同时处理已有颜色与尺码；保留有效 confirmed 映射，唯一确定匹配和达到当前阈值、理由非空、候选仍有效的 AI 匹配直接保存为 confirmed，无需人工二次确认。 - 低置信度或无结果保持未匹配；Provider 异常、AI 未启用或规格上下文漂移时 fail-closed，不写入本次结果。 - 新增专用接口 `POST /api/admin/v1/shopee-products/{productId}/specs/mapping/auto-match`，包含 UUID 幂等、`specContextVersion` 复核、事务内候选/设置复核和原子写入；通用 SetMapping 的 pending 语义不变。 - 人工选择、清除、保存及旧 pending 确认能力继续保留。 ### 验证 - `go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access`：通过。 - `.\scripts\verify.ps1 -Component server`：通过（全量 Go 测试与构建）。 - 目标 ESLint：通过。 - `pnpm exec playwright test tests/e2e/shopee-pdd-picker.spec.ts`：2 项通过。 - `pnpm build:prod`：通过。 - `python dev_scripts/harness.py check --strict`：通过。 - Web 全量 verify 的 lint 被基线文件 `web/src/views/goauto/purchase-tasks/index.vue` 的 24 个既有缩进错误阻断；#194 未修改该文件，目标 lint、E2E 与生产构建均已通过，未混入相邻修复。 ### Wiki 与文档 - 已更新 Architecture-and-Code-Map、Business-Rules-and-Glossary、Android-Agent-API-Contract。 - 线上 Wiki revision：`b94fd07dfdebe418257a675a779f83b782896543`；3 页在线回读均命中新规则。 - `harness.py sync` 与 `sync --check`：通过；目标镜像已提交。 - Gitea MCP 不可用且当前 API Token 无效；浏览器编辑大页连续超时后，按用户已确认的写入范围回退到 Gitea 原生 Wiki Git 仓库，随后完成线上回读。 ### 待人工验收 - 在 Admin 蝦皮商品详情使用真实 AI Provider 验证成功、部分未匹配和失败反馈。 - 工单保持开启，不关闭。
ila commented 2026-09-03 15:08:43 +08:00
Author
Owner
Copy Link
Copy Source

集成完成，待验收。已将 #194 已验证实现合入当前发布分支并推送：58e058f feat: 一键匹配并确认蝦皮颜色尺码 (#194)。此前本地服务所在分支遗漏了该提交，故“去匹配”只显示旧的颜色/尺码独立匹配。现详情页改为单个“一键匹配颜色和尺码”入口，并包含专用原子写入接口；不会自动执行 AI 匹配、创建采购或订单。验证通过：go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access；pnpm exec playwright test tests/e2e/shopee-pdd-picker.spec.ts（2/2）；pnpm run build:prod；python dev_scripts/harness.py check --strict。Wiki 在线内容此前已由 #194 更新；本次 sync --check 发现 docs/02 本地镜像滞后，标准 sync 被已有无关未提交修改 docs/12-syb-erp-interface.md 保护性阻止，未覆盖该文件。需在本地重启 Admin API 后，页面才会加载新增后端接口。

集成完成，待验收。已将 #194 已验证实现合入当前发布分支并推送：58e058f feat: 一键匹配并确认蝦皮颜色尺码 (#194)。此前本地服务所在分支遗漏了该提交，故“去匹配”只显示旧的颜色/尺码独立匹配。现详情页改为单个“一键匹配颜色和尺码”入口，并包含专用原子写入接口；不会自动执行 AI 匹配、创建采购或订单。验证通过：go test ./app/goauto/shopeeproduct ./app/goauto/aimatching ./app/goauto/access；pnpm exec playwright test tests/e2e/shopee-pdd-picker.spec.ts（2/2）；pnpm run build:prod；python dev_scripts/harness.py check --strict。Wiki 在线内容此前已由 #194 更新；本次 sync --check 发现 docs/02 本地镜像滞后，标准 sync 被已有无关未提交修改 docs/12-syb-erp-interface.md 保护性阻止，未覆盖该文件。需在本地重启 Admin API 后，页面才会加载新增后端接口。
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#194