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

定时及手动批量匹配未匹配蝦皮商品颜色尺码 #195

New Issue
Open
opened 2026-09-01 22:54:14 +08:00 by ila · 1 comment
ila commented 2026-09-01 22:54:14 +08:00
Owner
Copy Link
Copy Source

阶段

待实施。涉及数据库迁移、定时调度和多实例并发，实施前必须再次取得用户明确确认。

原始需求摘要

  • 来源：用户，2026-09-01。
  • 目标：系统定时处理已关联 PDD、蝦皮与 PDD 至少存在一个对应颜色或尺码维度、且仍有未确认映射的蝦皮商品；同时允许管理员手动执行一次。
  • 补充确认：手动入口放在 Admin 蝦皮商品列表；手动与定时执行必须复用同一规则和并发门禁。

前置依赖

  • 依赖 #194 的一键匹配专用服务、候选校验、置信度门槛、上下文版本和原子 confirmed 写入。
  • #194 当前实现提交：041cd8d03fd53f84065b9c513f635e3b87729e75，尚待用户验收。
  • 不允许脱离 #194 重新实现第二套匹配规则；#194 未验收/未进入目标集成基线前，本工单保持待实施。
  • 是否可并行：否；只能在 #194 确认基线上实施。

当前代码事实

  • 服务端已有 sys_job + robfig/cron 调度框架，并已有 SYB 定时同步任务示例。
  • sys_job.concurrent 当前没有形成跨进程互斥，不能单独作为本任务的并发保证。
  • 现有 /api/v1/job/start/:id 只是把任务注册进 Cron，不是“立即执行一次”，因此不能冒充本需求的手动入口。
  • #194 已提供单商品颜色+尺码统一匹配服务；合法成功结果可直接 confirmed，Provider 或上下文失败时 fail-closed。

目标范围

  1. 定时扫描并批量处理符合资格的蝦皮商品。
  2. Admin 蝦皮商品列表提供“执行规格自动匹配”按钮，异步启动同一批处理逻辑。
  3. 定时与手动执行共用全局单次运行门禁、商品工作状态、重试、冷却、结果统计和 #194 匹配服务。
  4. 默认每小时第 15 分钟调度，每次全局最多处理 20 个商品；系统任务由现有任务管理页维护 Cron 和启停。
  5. 新增任务默认关闭，部署后由管理员明确启用，避免升级后立即批量调用 AI 和改写映射。

非目标

  • 不创建采购任务、PDD 订单，不执行付款或任何 Agent 动作。
  • 不覆盖仍有效的 confirmed 映射，不修改蝦皮或 PDD 原始规格。
  • 不新增独立管理页面，不把通用系统任务“启动”接口改造成立即执行。
  • 不处理未关联 PDD、PDD 已停用、双方没有对应颜色/尺码维度或没有可选候选的商品。

资格与匹配规则

  • 蝦皮商品为存活记录且已关联 PDD；PDD 存在、非 disabled，并能给出当前可选颜色或尺码候选。
  • 双方至少有一个相同角色维度：颜色对颜色或尺码对尺码。
  • 至少一个目标规格没有仍有效的 confirmed 映射；有效 confirmed 映射始终保留。
  • 复用 #194：先处理确定性结果，剩余项才调用 AI；只接受达到当前服务端阈值、理由非空且仍属于当前候选的 AI 结果。
  • 低置信度或无结果保留为未匹配；同一商品规格上下文和 AI 设置版本都未变化时，不重复消耗 AI。
  • 规格关联、候选、人工映射或 AI 设置变化后，输入指纹变化，允许重新处理。

数据与并发方案

运行记录

新增 shopee_spec_auto_match_run：保存触发来源（scheduled/manual）、状态、稳定 requestId、请求人、批量参数、扫描/符合/处理/confirmed/未匹配/失败数量、安全错误摘要和开始/结束时间；使用唯一可空 active_slot 与过期租约保证定时、手动及多实例全局只运行一个批次。

商品工作状态

新增 shopee_spec_auto_match_work_item：每个蝦皮商品唯一，保存输入指纹、状态、尝试次数、下次尝试时间、租约所有者/到期时间、最后运行、结果计数和脱敏错误。领取使用带旧状态、指纹、尝试次数和租约条件的原子更新，防止同一商品被重复处理。

  • Provider 临时失败：最多 3 次，间隔至少 60 分钟。
  • 低置信度/无结果：同一输入指纹下结束，不自动反复调用；上下文或 AI 设置变化后重置。
  • 进程中断：租约到期后可恢复，不把运行中状态永久卡死。
  • 日志和记录不得保存 API Key、Provider 原始响应、商品原始 JSON 或个人数据。

调度与手动接口

  • 新增 ExecJob 调用目标，例如 GoAutoShopeeSpecAutoMatch，注册到现有任务表。
  • 迁移幂等写入一条默认关闭的系统任务；重复迁移不得覆盖管理员后来修改的 Cron、参数或启停状态。
  • 新增管理员专用接口：
    • POST /api/admin/v1/shopee-spec-auto-match/runs：提交 UUID requestId，异步启动一次手动批次；相同请求幂等重放。
    • GET /api/admin/v1/shopee-spec-auto-match/runs/latest：读取最近一次执行摘要，供列表页反馈。
  • 已有活动运行时返回当前运行摘要，不启动第二个批次。

低保真与设计证据

复用 Admin 蝦皮商品列表现有工具栏和 Element Plus 交互：

[添加] [删除] [执行规格自动匹配] 最近一次：完成，处理 12，确认 9，未匹配 3

点击后确认框：

将在后台处理最多 20 个符合条件的商品，并可能调用 AI。不会创建采购任务或订单。是否继续？

状态覆盖：

  • 正常：管理员可点击。
  • 加载：提交中按钮 loading，禁止重复点击。
  • 运行中：按钮禁用并显示“自动匹配进行中”。
  • 成功受理：提示“已开始后台匹配”，刷新最近摘要。
  • 空结果：显示“本次没有符合条件的商品”。
  • 失败：显示安全错误信息，不展示 Provider 原始响应。
  • 权限：仅管理员显示和调用；采购员仍可使用 #194 单商品匹配，但不能启动全局批次。

设计状态：已确认。确认人/时间：用户，2026-09-01；确认范围为增加手动执行、列表入口、后台批次与定时任务共用门禁。无需完整原型或本地 HTML：现有页面小范围按钮、确认框和摘要反馈。

预计影响

  • server/app/goauto/shopeeproduct/：扫描、工作状态、批次执行及复用 #194 服务。
  • server/app/jobs/examples.go：注册调用目标。
  • server/cmd/migrate/migration/version-local/：两张状态表及系统任务种子迁移与测试。
  • server/app/goauto/access/、路由/处理器：管理员接口和权限。
  • web/src/views/goauto/shopee-products/、对应 API 与测试：手动按钮和最近摘要。
  • Wiki：Architecture-and-Code-Map、Business-Rules-and-Glossary、Android-Agent-API-Contract、Deployment-and-Operations 及同步镜像。

验收标准

  • 定时任务只筛选符合资格且仍有未确认映射的商品。
  • 单批全局最多处理配置数量，默认 20。
  • 手动按钮可异步启动同一批次，显示运行中和最近摘要。
  • 定时与手动并发、多实例同时触发时最多一个活动批次；同一商品不会被重复领取。
  • 有效 confirmed 映射不被覆盖；成功结果复用 #194 直接 confirmed。
  • 低置信度/无结果同一输入不重复调用；Provider 临时失败按规则重试，达到上限后停止。
  • 输入或 AI 设置变化后可重新处理；上下文漂移不写入旧结果。
  • 迁移幂等且不覆盖管理员修改过的系统任务配置。
  • 手动接口仅管理员可用，稳定 requestId 幂等。
  • 不创建采购任务、订单或付款动作。
  • 服务端、Web、迁移、并发和构建测试通过。
  • 长期 Wiki 在线更新、回读 revision、sync 与 sync --check 完成。

验证方式

  • Go：筛选、指纹、租约竞争、重复调度、手动/定时互斥、崩溃恢复、重试、幂等和迁移测试。
  • Web：权限、确认框、重复点击、运行中、空结果、成功/失败反馈和最近摘要测试。
  • .\scripts\verify.ps1 -Component server
  • .\scripts\verify.ps1 -Component web
  • python dev_scripts/harness.py check --strict
  • 人工验收：先保持定时任务关闭，手动执行小批次；确认结果后再由管理员启用 Cron。

风险与回退

  • 风险：批量 AI 成本、错误映射、多实例重复执行、服务重启遗留租约。
  • 控制：默认关闭、批量上限、单次运行槽、逐商品租约、输入指纹、阈值/候选复核、有限重试和安全日志。
  • 回退：关闭系统任务并隐藏/停用手动入口；工作记录可保留审计，不删除既有 confirmed 映射，不回滚 #194。

文档影响

  • 更新架构与代码地图 Wiki。
  • 更新业务规则与术语 Wiki。
  • 更新共享 API 契约 Wiki。
  • 更新部署与运维 Wiki（任务启停、Cron、默认关闭、排错）。
  • 默认不创建任务快照或 Wiki 任务归档。
## 阶段 待实施。涉及数据库迁移、定时调度和多实例并发，实施前必须再次取得用户明确确认。 ## 原始需求摘要 - 来源：用户，2026-09-01。 - 目标：系统定时处理已关联 PDD、蝦皮与 PDD 至少存在一个对应颜色或尺码维度、且仍有未确认映射的蝦皮商品；同时允许管理员手动执行一次。 - 补充确认：手动入口放在 Admin 蝦皮商品列表；手动与定时执行必须复用同一规则和并发门禁。 ## 前置依赖 - 依赖 #194 的一键匹配专用服务、候选校验、置信度门槛、上下文版本和原子 confirmed 写入。 - #194 当前实现提交：`041cd8d03fd53f84065b9c513f635e3b87729e75`，尚待用户验收。 - 不允许脱离 #194 重新实现第二套匹配规则；#194 未验收/未进入目标集成基线前，本工单保持待实施。 - 是否可并行：否；只能在 #194 确认基线上实施。 ## 当前代码事实 - 服务端已有 `sys_job + robfig/cron` 调度框架，并已有 SYB 定时同步任务示例。 - `sys_job.concurrent` 当前没有形成跨进程互斥，不能单独作为本任务的并发保证。 - 现有 `/api/v1/job/start/:id` 只是把任务注册进 Cron，不是“立即执行一次”，因此不能冒充本需求的手动入口。 - #194 已提供单商品颜色+尺码统一匹配服务；合法成功结果可直接 confirmed，Provider 或上下文失败时 fail-closed。 ## 目标范围 1. 定时扫描并批量处理符合资格的蝦皮商品。 2. Admin 蝦皮商品列表提供“执行规格自动匹配”按钮，异步启动同一批处理逻辑。 3. 定时与手动执行共用全局单次运行门禁、商品工作状态、重试、冷却、结果统计和 #194 匹配服务。 4. 默认每小时第 15 分钟调度，每次全局最多处理 20 个商品；系统任务由现有任务管理页维护 Cron 和启停。 5. 新增任务默认关闭，部署后由管理员明确启用，避免升级后立即批量调用 AI 和改写映射。 ## 非目标 - 不创建采购任务、PDD 订单，不执行付款或任何 Agent 动作。 - 不覆盖仍有效的 confirmed 映射，不修改蝦皮或 PDD 原始规格。 - 不新增独立管理页面，不把通用系统任务“启动”接口改造成立即执行。 - 不处理未关联 PDD、PDD 已停用、双方没有对应颜色/尺码维度或没有可选候选的商品。 ## 资格与匹配规则 - 蝦皮商品为存活记录且已关联 PDD；PDD 存在、非 `disabled`，并能给出当前可选颜色或尺码候选。 - 双方至少有一个相同角色维度：颜色对颜色或尺码对尺码。 - 至少一个目标规格没有仍有效的 confirmed 映射；有效 confirmed 映射始终保留。 - 复用 #194：先处理确定性结果，剩余项才调用 AI；只接受达到当前服务端阈值、理由非空且仍属于当前候选的 AI 结果。 - 低置信度或无结果保留为未匹配；同一商品规格上下文和 AI 设置版本都未变化时，不重复消耗 AI。 - 规格关联、候选、人工映射或 AI 设置变化后，输入指纹变化，允许重新处理。 ## 数据与并发方案 ### 运行记录 新增 `shopee_spec_auto_match_run`：保存触发来源（scheduled/manual）、状态、稳定 requestId、请求人、批量参数、扫描/符合/处理/confirmed/未匹配/失败数量、安全错误摘要和开始/结束时间；使用唯一可空 `active_slot` 与过期租约保证定时、手动及多实例全局只运行一个批次。 ### 商品工作状态 新增 `shopee_spec_auto_match_work_item`：每个蝦皮商品唯一，保存输入指纹、状态、尝试次数、下次尝试时间、租约所有者/到期时间、最后运行、结果计数和脱敏错误。领取使用带旧状态、指纹、尝试次数和租约条件的原子更新，防止同一商品被重复处理。 - Provider 临时失败：最多 3 次，间隔至少 60 分钟。 - 低置信度/无结果：同一输入指纹下结束，不自动反复调用；上下文或 AI 设置变化后重置。 - 进程中断：租约到期后可恢复，不把运行中状态永久卡死。 - 日志和记录不得保存 API Key、Provider 原始响应、商品原始 JSON 或个人数据。 ## 调度与手动接口 - 新增 ExecJob 调用目标，例如 `GoAutoShopeeSpecAutoMatch`，注册到现有任务表。 - 迁移幂等写入一条默认关闭的系统任务；重复迁移不得覆盖管理员后来修改的 Cron、参数或启停状态。 - 新增管理员专用接口： - `POST /api/admin/v1/shopee-spec-auto-match/runs`：提交 UUID `requestId`，异步启动一次手动批次；相同请求幂等重放。 - `GET /api/admin/v1/shopee-spec-auto-match/runs/latest`：读取最近一次执行摘要，供列表页反馈。 - 已有活动运行时返回当前运行摘要，不启动第二个批次。 ## 低保真与设计证据 复用 Admin 蝦皮商品列表现有工具栏和 Element Plus 交互： `[添加] [删除] [执行规格自动匹配] 最近一次：完成，处理 12，确认 9，未匹配 3` 点击后确认框： > 将在后台处理最多 20 个符合条件的商品，并可能调用 AI。不会创建采购任务或订单。是否继续？ 状态覆盖： - 正常：管理员可点击。 - 加载：提交中按钮 loading，禁止重复点击。 - 运行中：按钮禁用并显示“自动匹配进行中”。 - 成功受理：提示“已开始后台匹配”，刷新最近摘要。 - 空结果：显示“本次没有符合条件的商品”。 - 失败：显示安全错误信息，不展示 Provider 原始响应。 - 权限：仅管理员显示和调用；采购员仍可使用 #194 单商品匹配，但不能启动全局批次。 设计状态：已确认。确认人/时间：用户，2026-09-01；确认范围为增加手动执行、列表入口、后台批次与定时任务共用门禁。无需完整原型或本地 HTML：现有页面小范围按钮、确认框和摘要反馈。 ## 预计影响 - `server/app/goauto/shopeeproduct/`：扫描、工作状态、批次执行及复用 #194 服务。 - `server/app/jobs/examples.go`：注册调用目标。 - `server/cmd/migrate/migration/version-local/`：两张状态表及系统任务种子迁移与测试。 - `server/app/goauto/access/`、路由/处理器：管理员接口和权限。 - `web/src/views/goauto/shopee-products/`、对应 API 与测试：手动按钮和最近摘要。 - Wiki：Architecture-and-Code-Map、Business-Rules-and-Glossary、Android-Agent-API-Contract、Deployment-and-Operations 及同步镜像。 ## 验收标准 - [ ] 定时任务只筛选符合资格且仍有未确认映射的商品。 - [ ] 单批全局最多处理配置数量，默认 20。 - [ ] 手动按钮可异步启动同一批次，显示运行中和最近摘要。 - [ ] 定时与手动并发、多实例同时触发时最多一个活动批次；同一商品不会被重复领取。 - [ ] 有效 confirmed 映射不被覆盖；成功结果复用 #194 直接 confirmed。 - [ ] 低置信度/无结果同一输入不重复调用；Provider 临时失败按规则重试，达到上限后停止。 - [ ] 输入或 AI 设置变化后可重新处理；上下文漂移不写入旧结果。 - [ ] 迁移幂等且不覆盖管理员修改过的系统任务配置。 - [ ] 手动接口仅管理员可用，稳定 requestId 幂等。 - [ ] 不创建采购任务、订单或付款动作。 - [ ] 服务端、Web、迁移、并发和构建测试通过。 - [ ] 长期 Wiki 在线更新、回读 revision、sync 与 sync --check 完成。 ## 验证方式 - Go：筛选、指纹、租约竞争、重复调度、手动/定时互斥、崩溃恢复、重试、幂等和迁移测试。 - Web：权限、确认框、重复点击、运行中、空结果、成功/失败反馈和最近摘要测试。 - `.\scripts\verify.ps1 -Component server` - `.\scripts\verify.ps1 -Component web` - `python dev_scripts/harness.py check --strict` - 人工验收：先保持定时任务关闭，手动执行小批次；确认结果后再由管理员启用 Cron。 ## 风险与回退 - 风险：批量 AI 成本、错误映射、多实例重复执行、服务重启遗留租约。 - 控制：默认关闭、批量上限、单次运行槽、逐商品租约、输入指纹、阈值/候选复核、有限重试和安全日志。 - 回退：关闭系统任务并隐藏/停用手动入口；工作记录可保留审计，不删除既有 confirmed 映射，不回滚 #194。 ## 文档影响 - [x] 更新架构与代码地图 Wiki。 - [x] 更新业务规则与术语 Wiki。 - [x] 更新共享 API 契约 Wiki。 - [x] 更新部署与运维 Wiki（任务启停、Cron、默认关闭、排错）。 - [x] 默认不创建任务快照或 Wiki 任务归档。
ila commented 2026-09-01 23:43:03 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，待验收

已按确认方案完成并推送。

实现

  • 新增 shopee_spec_auto_match_run 与 shopee_spec_auto_match_work_item，以唯一活动槽、运行租约和逐商品租约保证定时/手动/多实例全局串行。
  • 复用 #194 单商品原子匹配服务；只扫描已关联 active PDD、双方共享颜色或尺码且仍有未确认/失效映射的存活蝦皮商品。
  • 保留有效 confirmed；相同输入下 completed/unmatched 不重复调用 AI；Provider 临时失败至少 60 分钟后重试，最多 3 次；输入或 AI 设置更新时间变化后允许重新处理。
  • 新增调用目标 GoAutoShopeeSpecAutoMatch。迁移幂等播种默认关闭任务：Cron 0 15 * * * *，默认每批 20。
  • 新增管理员接口 POST /api/admin/v1/shopee-spec-auto-match/runs 与 GET /api/admin/v1/shopee-spec-auto-match/runs/latest；手动执行异步、requestId 幂等，已有活动批次时不重复启动。
  • Admin 蝦皮商品列表增加“执行规格自动匹配”、确认框、运行中状态和最近摘要；采购员不显示且服务端拒绝。
  • 不创建采购任务、订单，不触发 Android Agent，不执行付款。

验证

  • go test ./...：通过。
  • go vet ./app/goauto/shopeeproduct ./app/jobs ./cmd/migrate/migration/version-local：通过。
  • 迁移幂等、默认关闭、保留管理员 Cron/参数/状态测试：通过。
  • 批次 requestId 幂等、全局互斥、确定性匹配、输入指纹冷却测试：通过。
  • 本工单 Web 文件 ESLint：通过。
  • pnpm build:prod：通过（只有仓库既有 CSS/大 chunk 警告）。
  • Playwright shopee-spec-auto-match-run.spec.ts：1 passed。
  • python dev_scripts/harness.py check --strict：通过。
  • Wiki sync 与 sync --check：通过。
  • 全量 verify.ps1 -Component web：被未修改的基线文件 web/src/views/goauto/purchase-tasks/index.vue 既有空格/Tab lint 错误阻断；本工单文件 lint、构建及新增浏览器用例均已单独通过，未越界修复。

Wiki revisions

  • Architecture-and-Code-Map: 2864a22f9e0f
  • Business-Rules-and-Glossary: 0e1df62c48ae
  • Android-Agent-API-Contract: 87219820eec3
  • Deployment-and-Operations: 88422ddd1bd2

提交

  • 分支：feat/195-scheduled-spec-auto-match
  • 提交：d792461
  • 基线：#194 041cd8d

本会话未提供 Gitea MCP 与 codebase-memory 图工具，已按项目规则回退到已登录 Gitea 页面和 rg，未创建任务归档。工单保持开启，等待用户验收。

## 实施完成，待验收 已按确认方案完成并推送。 ### 实现 - 新增 `shopee_spec_auto_match_run` 与 `shopee_spec_auto_match_work_item`，以唯一活动槽、运行租约和逐商品租约保证定时/手动/多实例全局串行。 - 复用 #194 单商品原子匹配服务；只扫描已关联 active PDD、双方共享颜色或尺码且仍有未确认/失效映射的存活蝦皮商品。 - 保留有效 confirmed；相同输入下 completed/unmatched 不重复调用 AI；Provider 临时失败至少 60 分钟后重试，最多 3 次；输入或 AI 设置更新时间变化后允许重新处理。 - 新增调用目标 `GoAutoShopeeSpecAutoMatch`。迁移幂等播种默认关闭任务：Cron `0 15 * * * *`，默认每批 20。 - 新增管理员接口 `POST /api/admin/v1/shopee-spec-auto-match/runs` 与 `GET /api/admin/v1/shopee-spec-auto-match/runs/latest`；手动执行异步、requestId 幂等，已有活动批次时不重复启动。 - Admin 蝦皮商品列表增加“执行规格自动匹配”、确认框、运行中状态和最近摘要；采购员不显示且服务端拒绝。 - 不创建采购任务、订单，不触发 Android Agent，不执行付款。 ### 验证 - `go test ./...`：通过。 - `go vet ./app/goauto/shopeeproduct ./app/jobs ./cmd/migrate/migration/version-local`：通过。 - 迁移幂等、默认关闭、保留管理员 Cron/参数/状态测试：通过。 - 批次 requestId 幂等、全局互斥、确定性匹配、输入指纹冷却测试：通过。 - 本工单 Web 文件 ESLint：通过。 - `pnpm build:prod`：通过（只有仓库既有 CSS/大 chunk 警告）。 - Playwright `shopee-spec-auto-match-run.spec.ts`：1 passed。 - `python dev_scripts/harness.py check --strict`：通过。 - Wiki `sync` 与 `sync --check`：通过。 - 全量 `verify.ps1 -Component web`：被未修改的基线文件 `web/src/views/goauto/purchase-tasks/index.vue` 既有空格/Tab lint 错误阻断；本工单文件 lint、构建及新增浏览器用例均已单独通过，未越界修复。 ### Wiki revisions - Architecture-and-Code-Map: `2864a22f9e0f` - Business-Rules-and-Glossary: `0e1df62c48ae` - Android-Agent-API-Contract: `87219820eec3` - Deployment-and-Operations: `88422ddd1bd2` ### 提交 - 分支：`feat/195-scheduled-spec-auto-match` - 提交：`d792461` - 基线：#194 `041cd8d` 本会话未提供 Gitea MCP 与 codebase-memory 图工具，已按项目规则回退到已登录 Gitea 页面和 `rg`，未创建任务归档。工单保持开启，等待用户验收。
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#195