Admin：实现采购运行时真机规格规则与 AI 解析 #255

New Issue

2026-08-24T11:28:49+08:00

ila commented

2026-08-24 11:28:49 +08:00

基本信息

类型：需求
父级大工单：#96
所属 MVP / 版本：#253 采购运行时 AI 规格纠偏闭环
阶段：2. Admin 规则/AI 解析与幂等接口
依赖：#254；复用 #200、#201 的 AI 配置、密钥和候选匹配能力

要解决什么

Client 能观察到 PDD App 当前真实尺码，但 Admin 现有 MatchSybSpecWithAI 只读取 pdd_products.skus_json 中的候选。对于蝦皮回填规格，数据库候选与真机候选可能不同，现有 AI 即使正常运行也无法返回真机可点击的尺码。

需要让 Admin 对 Client 提交的当前颜色下真实尺码候选执行规则优先、AI 补充的白名单选择，并以幂等、可审计的结果返回 Client。

做什么 / 不做什么

做：
- 实现 #254 定义的 Client API 路由、Handler、Service 和持久化编排。
- 校验任务存在、类型为采购、当前 Client 曾领取该任务、商品 ID 和原任务规格一致、候选快照结构完整。
- 确定性规则处理繁简、大小写、空白/符号、kg/公斤/斤、正数重量区间和唯一等价候选。
- 只有规则不能唯一确定时才调用 AI；模型只能从服务端生成的候选编号中选择。
- 复用现有 AI 服务商、密钥、端点安全、超时、置信度阈值、响应格式和候选硬校验。
- 保存候选、哈希、规则/模型快照、决策、来源、置信度和原因；重复请求返回同一持久化响应。
- 对 spec_source=shopee_backfill 仅记录诊断来源，不以来源主动触发解析或直接拒绝任务。
不做：
- 不生成候选外规格，不返回点击坐标，不选择或替换 PDD 商品链接。
- 不处理颜色选择失败、候选遍历不完整、页面控件不安全、登录/验证码或价格问题。
- 不修改采购任务 payload、状态、价格上限或不可逆标记。
- 不覆盖 PDD 主规格，不自动创建采购任务、下单或付款。

怎么做

在 handler/api 注册专用 POST 路由，复用 Client 认证、统一错误和请求大小限制；Handler 只解析 DTO 和调用 Service。
Service 验证请求与任务快照，规范化候选并由服务器计算/核对候选哈希，拒绝空值、重复编号、不可用候选、超限字段和伪造商品。
规则匹配严格要求唯一等价：例如 45-55公斤 可与唯一 90-110斤 等价；与多个区间重叠时返回 uncertain。
抽取现有 AI 匹配中的通用“候选编号→模型→白名单与置信度硬校验”核心，让 SYB 批量 AI 与运行时 AI 共用；各自保留独立业务编排。
模型失败、超时、低置信度、冲突、缺失维度、伪造编号和保存前候选变化均返回不可继续结果，不降级为猜测。
在同一事务内完成解析记录决策和幂等响应保存；并发相同请求只有一个模型决策成为最终结果。
自动化测试覆盖规则边界、认证、越权、幂等并发、模型错误、候选白名单、大小限制和隐私日志。

预计修改文件：

admin/handler/api/client_api.go
admin/handler/api/client_api_test.go
admin/service/ai_specmatch.go
admin/service/ai_specmatch_client.go
新的运行时规格解析 Service 文件及测试
admin/repository/ 中 #254 建立的解析记录访问层
docs/admin/01-requirements.md
docs/admin/02-architecture.md
完成后归档 docs/task/<工单号>-admin运行时规格规则ai解析.md

验收标准

未曾领取任务的 Client、非采购任务、商品或任务规格不一致请求被拒绝且不写决策。
完全��价、繁简等价和唯一公斤/斤区间由规则匹配，不调用模型。
两个区间同时重叠、信息缺失或多个候选等价时不自动选择。
规则无法唯一确定时 AI 只能选择当前候选编号；伪造编号、低置信度和冲突不能返回 matched。
同一幂等请求重试和并发只产生一个最终解析记录和一致响应，不重复产生有效模型决策。
shopee_backfill 只作为诊断来源，不能在真机没有不匹配时主动调用 AI。
不修改 PDD 主规格、任务状态、payload、价格上限或采购安全门禁。
页面、日志、数据库和响应不包含 API Key、原始 XML或个人数据。
原 SYB 批量 AI 回归通过，人工映射优先和现有置信度门禁保持不变。
Go 1.23.0 build、test、vet 和 MySQL 8.4 _test 集成测试通过。

怎么验证

从 admin/ 执行：

$env:GOTOOLCHAIN='go1.23.0'
gofmt -l .
go build ./...
go test ./... -count=1
go vet ./...
Remove-Item Env:GOTOOLCHAIN

使用本地伪模型覆盖：唯一规则命中、45-55公斤→90-110斤、重叠区间、不确定、低置信度、超时、候选伪造和并发幂等；使用独立 MySQL 8.4 _test 库验证事务。

风险和回退

风险：重量建议并非严格尺码。只有区间唯一等价才由规则命中，重叠或近似关系交给 AI，AI 仍须通过阈值和冲突校验。
风险：模型结果错误。只允许候选白名单，保存候选快照，Client 还会再次读取并验证真机页面。
风险：重复调用产生不一致结果。请求和响应持久化并受唯一键保护。
回退：关闭专用路由或 AI 运行时入口，Client 回到规格不匹配即失败；审计记录保留。

## 基本信息 - 类型：需求 - 父级大工单：#96 - 所属 MVP / 版本：#253 采购运行时 AI 规格纠偏闭环 - 阶段：2. Admin 规则/AI 解析与幂等接口 - 依赖：#254；复用 #200、#201 的 AI 配置、密钥和候选匹配能力 ## 要解决什么 Client 能观察到 PDD App 当前真实尺码，但 Admin 现有 `MatchSybSpecWithAI` 只读取 `pdd_products.skus_json` 中的候选。对于蝦皮回填规格，数据库候选与真机候选可能不同，现有 AI 即使正常运行也无法返回真机可点击的尺码。需要让 Admin 对 Client 提交的当前颜色下真实尺码候选执行规则优先、AI 补充的白名单选择，并以幂等、可审计的结果返回 Client。 ## 做什么 / 不做什么 - 做： - 实现 #254 定义的 Client API 路由、Handler、Service 和持久化编排。 - 校验任务存在、类型为采购、当前 Client 曾领取该任务、商品 ID 和原任务规格一致、候选快照结构完整。 - 确定性规则处理繁简、大小写、空白/符号、`kg/公斤/斤`、正数重量区间和唯一等价候选。 - 只有规则不能唯一确定时才调用 AI；模型只能从服务端生成的候选编号中选择。 - 复用现有 AI 服务商、密钥、端点安全、超时、置信度阈值、响应格式和候选硬校验。 - 保存候选、哈希、规则/模型快照、决策、来源、置信度和原因；重复请求返回同一持久化响应。 - 对 `spec_source=shopee_backfill` 仅记录诊断来源，不以来源主动触发解析或直接拒绝任务。 - 不做： - 不生成候选外规格，不返回点击坐标，不选择或替换 PDD 商品链接。 - 不处理颜色选择失败、候选遍历不完整、页面控件不安全、登录/验证码或价格问题。 - 不修改采购任务 payload、状态、价格上限或不可逆标记。 - 不覆盖 PDD 主规格，不自动创建采购任务、下单或付款。 ## 怎么做 1. 在 `handler/api` 注册专用 POST 路由，复用 Client 认证、统一错误和请求大小限制；Handler 只解析 DTO 和调用 Service。 2. Service 验证请求与任务快照，规范化候选并由服务器计算/核对候选哈希，拒绝空值、重复编号、不可用候选、超限字段和伪造商品。 3. 规则匹配严格要求唯一等价：例如 `45-55公斤` 可与唯一 `90-110斤` 等价；与多个区间重叠时返回 `uncertain`。 4. 抽取现有 AI 匹配中的通用“候选编号→模型→白名单与置信度硬校验”核心，让 SYB 批量 AI 与运行时 AI 共用；各自保留独立业务编排。 5. 模型失败、超时、低置信度、冲突、缺失维度、伪造编号和保存前候选变化均返回不可继续结果，不降级为猜测。 6. 在同一事务内完成解析记录决策和幂等响应保存；并发相同请求只有一个模型决策成为最终结果。 7. 自动化测试覆盖规则边界、认证、越权、幂等并发、模型错误、候选白名单、大小限制和隐私日志。预计修改文件： - `admin/handler/api/client_api.go` - `admin/handler/api/client_api_test.go` - `admin/service/ai_specmatch.go` - `admin/service/ai_specmatch_client.go` - 新的运行时规格解析 Service 文件及测试 - `admin/repository/` 中 #254 建立的解析记录访问层 - `docs/admin/01-requirements.md` - `docs/admin/02-architecture.md` - 完成后归档 `docs/task/<工单号>-admin运行时规格规则ai解析.md` ## 验收标准 - [ ] 未曾领取任务的 Client、非采购任务、商品或任务规格不一致请求被拒绝且不写决策。 - [ ] 完全��价、繁简等价和唯一公斤/斤区间由规则匹配，不调用模型。 - [ ] 两个区间同时重叠、信息缺失或多个候选等价时不自动选择。 - [ ] 规则无法唯一确定时 AI 只能选择当前候选编号；伪造编号、低置信度和冲突不能返回 matched。 - [ ] 同一幂等请求重试和并发只产生一个最终解析记录和一致响应，不重复产生有效模型决策。 - [ ] `shopee_backfill` 只作为诊断来源，不能在真机没有不匹配时主动调用 AI。 - [ ] 不修改 PDD 主规格、任务状态、payload、价格上限或采购安全门禁。 - [ ] 页面、日志、数据库和响应不包含 API Key、原始 XML或个人数据。 - [ ] 原 SYB 批量 AI 回归通过，人工映射优先和现有置信度门禁保持不变。 - [ ] Go 1.23.0 build、test、vet 和 MySQL 8.4 `_test` 集成测试通过。 ## 怎么验证从 `admin/` 执行： ```powershell $env:GOTOOLCHAIN='go1.23.0' gofmt -l . go build ./... go test ./... -count=1 go vet ./... Remove-Item Env:GOTOOLCHAIN ``` 使用本地伪模型覆盖：唯一规则命中、`45-55公斤→90-110斤`、重叠区间、不确定、低置信度、超时、候选伪造和并发幂等；使用独立 MySQL 8.4 `_test` 库验证事务。 ## 风险和回退 - 风险：重量建议并非严格尺码。只有区间唯一等价才由规则命中，重叠或近似关系交给 AI，AI 仍须通过阈值和冲突校验。 - 风险：模型结果错误。只允许候选白名单，保存候选快照，Client 还会再次读取并验证真机页面。 - 风险：重复调用产生不一致结果。请求和响应持久化并受唯一键保护。 - 回退：关闭专用路由或 AI 运行时入口，Client 回到规格不匹配即失败；审计记录保留。

ila referenced this issue

2026-08-24 11:42:35 +08:00

Admin：定义采购运行时规格解析接口与审计模型 #254

ila commented

2026-08-24 11:42:36 +08:00

开始实施。范围严格按 #255：实现 #254 的 Admin 路由/Handler/Service、规则优先与 AI 白名单决策、持久化和幂等编排，并补充契约/并发/回归测试及需求/架构文档。不会修改任务状态、payload、PDD 主规格、价格门禁，也不实现 Client 真机采集或继续点击。当前工作区已有的 Client 与本机文件将保持不动。

ila commented

2026-08-24 11:42:37 +08:00

#255 ?????,?????:????

????:de36cfd

???:

?? POST /api/v1/client/tasks/{task_id}/spec-resolution,?? 64 KiB ???????????/??/??/????/???????
?????????????????????/????????;????????????? uncertain,??????
?? SYB ??????? AI ?????????????/????????????;??????????
?? pending ???? + ?????/AI + ????????????;??????????????????????????
shopee_backfill ??????????,?????????
????????payload??????PDD ??????????;??????????? API Key?XML?????????

??:

GOTOOLCHAIN=go1.23.0 go test ./... -count=1:???
go vet ./...:???
go build ./...:???
go test -race ./service -run 'Test(MatchPurchaseSpec|ParsePurchaseSpec|ResolvePurchaseSpec)' -count=1:???
?????????????? SQLite ??,???? CMAUTOBUY_MYSQL_TEST=1 ????? MySQL 8 _test ??

???:?? MySQL 8.4 ?????????????,??? CMAUTOBUY_MYSQL_TEST=1 ? #255 ??????;v26 MySQL ???/Repository ??????? #254 ?????????????????

#255 ?????,?????:???? ????:`de36cfd` ???: - ?? `POST /api/v1/client/tasks/{task_id}/spec-resolution`,?? 64 KiB ???????????/??/??/????/??????? - ?????????????????????/????????;????????????? uncertain,?????? - ?? SYB ??????? AI ?????????????/????????????;?????????? - ?? pending ???? + ?????/AI + ????????????;?????????????????????????? - `shopee_backfill` ??????????,????????? - ????????payload??????PDD ??????????;??????????? API Key?XML????????? ??: - `GOTOOLCHAIN=go1.23.0 go test ./... -count=1`:??? - `go vet ./...`:??? - `go build ./...`:??? - `go test -race ./service -run 'Test(MatchPurchaseSpec|ParsePurchaseSpec|ResolvePurchaseSpec)' -count=1`:??? - ?????????????? SQLite ??,???? `CMAUTOBUY_MYSQL_TEST=1` ????? MySQL 8 `_test` ?? ???:?? MySQL 8.4 ?????????????,??? `CMAUTOBUY_MYSQL_TEST=1` ? #255 ??????;v26 MySQL ???/Repository ??????? #254 ?????????????????

ila commented

2026-08-24 11:42:38 +08:00