feat: batch AI match SYB purchase specs (#188)
This commit is contained in:
QiuSW
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Business-Rules-and-Glossary
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary.-
|
||||
wiki_revision: 36d7285beb3f0c8441e38b4e9e81e5cf7256b603
|
||||
synchronized_at: 2026-09-01T01:50:05Z
|
||||
wiki_revision: 084dae8190b765758cc77a59732215bd8a9ca6fe
|
||||
synchronized_at: 2026-09-01T04:05:25Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -31,7 +31,7 @@ synchronized_at: 2026-09-01T01:50:05Z
|
||||
- 关联 PDD 商品时校验目标存在且非 `disabled`；不提供手工输入商品 ID 的入口，只能通过搜索选择。
|
||||
- 参考售价 `sale_price_cent` 为整数分，`currency` 为 ISO 4217 代码；币种取系统配置默认值，不逐商品选择，缺省回退为 `TWD`。
|
||||
- 规格值来源分 `import`（SYB 导入，不可人工删除，只能清除映射）与 `manual`（人工添加，可删除）；导入与人工值按「维度 + 名称」合并，不重复创建。
|
||||
- 映射来源分 `manual`（人工，允许创建时即为已确认）、`exact_match`（名称完全相等自动预填）、`ai_match`（AI 建议）；`exact_match` 与 `ai_match` 一律以 `pending` 状态写入，必须人工确认后才生效。
|
||||
- 映射来源分 `manual`（人工，允许创建时即为已确认）、`exact_match`（名称完全相等自动预填）、`ai_match`（AI 建议）。通用 `SetMapping` 入口仍将 `exact_match` 与 `ai_match` 一律写为 `pending`，必须人工确认后才生效；#188 的 SYB 商品页批量 AI 匹配是独立例外：只有 `ai_match` 置信度存在且达到服务端阈值、候选与原因完整时才可直接持久化为 `confirmed`，低置信度或异常不得改写现有映射。
|
||||
- 颜色映射只能从关联 PDD 商品当前可选颜色中选择，不允许自由输入；未使用颜色优先显示，已被其他蝦皮颜色使用的颜色仍可选择并显示占用者，因此支持多对一。
|
||||
- 尺码“一键自动匹配”只生成可审阅草稿：繁简体、首尾/重复空格、大小写和全半角统一后只有唯一结果才预填；没有唯一结果时保持待人工选择。保存只改映射，不改蝦皮或 PDD 原始规格。
|
||||
- PDD 重新采集或更换关联后，目标规格仍存在则映射继续有效；目标规格消失时详情标记“已失效”，服务端拒绝保存不存在的目标，采购预检和创建也拒绝使用失效映射并提示重新选择。
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Android-Agent-API-Contract
|
||||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract.-
|
||||
wiki_revision: 0f448673dbec00a351c397d30926f0c5090a1141
|
||||
synchronized_at: 2026-09-01T01:50:29Z
|
||||
wiki_revision: 44f936706dfd36b0281215a239b790bbe50aaf77
|
||||
synchronized_at: 2026-09-01T04:09:50Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# MVP 共享 API 契约
|
||||
@@ -54,7 +54,7 @@ POST /api/admin/v1/shopee-products/batch-delete
|
||||
|
||||
创建与关联/映射相关写操作均提交 `requestId` 做幂等重放；重放请求返回相同结果并标记 `replayed`。创建请求提交 `shopeeItemId`、`title`、`shopName`，可选 `pddProductId` 和 `specs`；`shopeeItemId` 重复时返回 `SHOPEE_ITEM_ID_EXISTS` 和已存在商品 ID。`link-pdd` 校验 PDD 商品存在且非 `disabled`，否则分别返回 `PDD_PRODUCT_NOT_FOUND` 或 `PDD_PRODUCT_DISABLED`；关联成功后返回值包含 `sharedByPddCount`，表示当前共用同一 PDD 商品的虾皮商品数。
|
||||
|
||||
`specs` 结构同 PDD 商品的维度/规格值形状，但规格值额外携带 `source`（`import` / `manual`）与可选的 `mapping`（`pddValue`、`source`、`status`、`confidence`、`reason`）。新增规格值固定为 `manual` 来源；删除规格值仅允许 `manual` 来源，`import` 来源返回 `SPEC_VALUE_NOT_MANUAL`。设置映射时，`exact_match` 与 `ai_match` 来源一律写入 `pending` 状态，与请求体中的 `status` 无关；只有 `manual` 来源可以直接写入 `confirmed`。`confirm-exact-matches` 仅确认 `source=exact_match` 且状态为 `pending` 的映射，不影响 `ai_match`。
|
||||
`specs` 结构同 PDD 商品的维度/规格值形状，但规格值额外携带 `source`（`import` / `manual`）与可选的 `mapping`（`pddValue`、`source`、`status`、`confidence`、`reason`）。新增规格值固定为 `manual` 来源；删除规格值仅允许 `manual` 来源，`import` 来源返回 `SPEC_VALUE_NOT_MANUAL`。设置映射时，`exact_match` 与 `ai_match` 来源一律写入 `pending` 状态，与请求体中的 `status` 无关；只有 `manual` 来源可以直接写入 `confirmed`。`confirm-exact-matches` 仅确认 `source=exact_match` 且状态为 `pending` 的映射，不影响 `ai_match`。该通用入口不因 #188 改变；#188 仅通过下述采购批量规格匹配接口的独立写入路径，在高置信度门槛通过时写入 `confirmed`。
|
||||
|
||||
`preview-auto-size` 是只读计算接口（使用 `POST` 触发计算，不写数据库），无需 `requestId`。它读取当前蝦皮尺码与关联 PDD 的可选尺码，只返回格式统一后唯一确定的匹配；响应含 `items[]`（`valueName`、可选 `pddValue`、`status=preserved|matched|pending`、`reason`）、`pddValues`、`matchedCount` 和 `pendingCount`。已确认且目标仍存在的映射标为 `preserved`；无唯一结果标为 `pending`。Admin 的显式“保存修改”仍通过既有设置/确认接口落库。
|
||||
|
||||
@@ -502,6 +502,7 @@ POST /api/agent/v1/tasks/{taskId}/fail
|
||||
| `POST` | `/api/admin/v1/purchase-tasks` | `requestId`；单条创建 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/stock` | 创建备货采购；`requestId`、`executionMode`、`pddProductId`、可选 `deviceId` / `pddAccountId`、`color`、可选 `size`、`quantity`、`minUnitPriceCent`、`maxUnitPriceCent`。服务端使用内置规则并从所选颜色归档派生参考价；相同 `requestId` 幂等返回原任务 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch-preview` | `sybProductIds`（1～100）和可选 `deviceId`；逐条返回采购是否可创建、价格区间、原因和下一步，并独立返回 PDD 采集资格 `collectionEligible` 与可选禁用原因 `collectionDisabledReason`，不创建任务 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch-spec-match` | `sybProductIds`（1～100）；仅处理当前为 `color_mapping` 的明细，逐条返回 `auto_confirmed` / `pending` / `failed` / `skipped`。只有 `ai_match` 置信度达到 `autoConfirmMinConfidence` 且理由非空时，才通过独立路径把该明细所需映射写为 `confirmed`；低置信度和 Provider 异常不改写现有映射 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/batch` | 批次 `requestId`、`sybProductIds`（1～100）和可选 `deviceId`；每条派生稳定幂等键并独立创建，部分失败不回滚成功项 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/{taskId}/authorize-repurchase` | 一次性授权；创建新任务后自动消耗 |
|
||||
| `POST` | `/api/admin/v1/purchase-tasks/{taskId}/payment-review` | `paid` 或 `unpaid`，管理员和采购员可操作 |
|
||||
|
||||
Reference in New Issue
Block a user