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

docs(#40): sync architecture, business rules and API contract for shopee product

Browse Source 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
QiuSW
2026-08-19 13:45:35 +08:00
co-authored by Claude Opus 5
parent 658ffd5d15
commit 03f44a0dd2
5 changed files with 49 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-architecture-and-code-map.md
+4 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map.-
wiki_revision: a5c60ff2d9d64c824be176bb1630d884379f6c7c
synchronized_at: 2026-08-17T08:56:32Z
wiki_revision: 8612c845ddfe84dfe18e3aca695eab3d9339465d
synchronized_at: 2026-08-19T05:44:11Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -79,6 +79,8 @@ Android Portal/Agent
| 设备注册、认证、停用与吊销 | `server/app/goauto/device/` |
| PDD 商品与规则 | `server/app/goauto/product/`、`server/app/goauto/rule/` |
| PDD 商品档案增量迁移 | `server/cmd/migrate/migration/version-local/1786700500000_pdd_product_archive.go` |
| 虾皮商品档案与规格映射 | `server/app/goauto/shopeeproduct/`（服务端 API 已实现；Admin 页面待实现） |
| 虾皮商品档案增量迁移 | `server/cmd/migrate/migration/version-local/1786700600000_shopee_product_archive.go` |
| 任务领取、结果、重置与删除 | `server/app/goauto/task/` |
| 管理端基线 | `web/`（go-admin-ui v3.0.0） |
| 管理端闭环页面 | `web/src/views/goauto/` |
docs/03-business-rules-and-glossary.md
+13 -3
View File
@@ -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: 652236933e8dc996af2f8ab43a20cedead62ee5d
synchronized_at: 2026-08-18T09:43:32Z
wiki_revision: 5717e1e7561d8663abfebf34c99ae11a23a8e62d
synchronized_at: 2026-08-19T05:44:15Z
<!-- gitea-wiki-mirror:end -->
# 业务规则与术语
@@ -24,6 +24,16 @@ synchronized_at: 2026-08-18T09:43:32Z
- 人工保存为完整覆盖。`completed` 采集结果全量覆盖；`completed_partial` 只合并明确采集到的字段和规格，不删除原有缺失部分；`failed` 不修改商品。
- 人工停用的商品不会被后续采集结果自动重新启用；假售罄、临时售罄和采集失败也不会自动停用商品。
## 虾皮商品
- `shopee_item_id` 全局唯一，仅在存活记录之间生效；软删除的记录不占用该唯一性，重新创建或 #41 重新导入均可成功。
- `pdd_product_id` 可为空，且不加唯一约束：一个虾皮商品最多关联一个 PDD 商品，但多个虾皮商品可以共用同一个 PDD 商品。
- 关联 PDD 商品时校验目标存在且非 `disabled`；不提供手工输入商品 ID 的入口，只能通过搜索选择。
- 参考售价 `sale_price_cent` 为整数分，`currency` 为 ISO 4217 代码；币种取系统配置默认值，不逐商品选择，缺省回退为 `TWD`。
- 规格值来源分 `import`（SYB 导入，不可人工删除，只能清除映射）与 `manual`（人工添加，可删除）；导入与人工值按「维度 + 名称」合并，不重复创建。
- 映射来源分 `manual`（人工，允许创建时即为已确认）、`exact_match`（名称完全相等自动预填）、`ai_match`（AI 建议）；`exact_match` 与 `ai_match` 一律以 `pending` 状态写入，必须人工确认后才生效。
- 批量软删除逐条校验引用（虾皮商品被 SYB 明细或采购任务引用时不可删除）并逐条返回结果；已删除商品默认不出现在列表，可筛选查看并恢复。
## 采集规则
- 规则创建后立即可用，不存在草稿、发布、版本或停用流程。
@@ -94,7 +104,7 @@ synchronized_at: 2026-08-18T09:43:32Z
| 部分完成 | 结果已提交，但一个或多个规格/SKU 缺失 |
| 重置任务 | 保留任务输入快照，清除原结果后重新进入待执行状态 |
| Portal/Agent | Android 端注册、保活、执行规则和提交结果的程序 |
| 虾皮 | Shopee 的中文展示名。管理端界面一律用「虾皮」，数据库表名、字段名、API 路径等程序标识符保持 `shopee_products` / `shopee_item_id` 不变 |
| 虾皮 | Shopee 的中文展示名。管理端界面一律用「虾皮」，数据库表名、字段名、API 路径等程序标识符保持 `shopee_product`（单数）/ `shopee_item_id` 不变 |
| SYB | 顺云宝 ERP（ShunYunBao，域名 shunyunbaoerp.com），虾皮订单与货运单的外部来源系统。管理端界面一律用「SYB」，不再使用「货运宝」「顺云宝」等别名；数据库表名与字段保持 `syb_products` |
| 货运单 | SYB 中的一张单据（`code`，如 260728TB95MJTQ），下挂一条或多条商品明细。与系统名「SYB」区分，不可混用 |
| AI 规格匹配 | 人工映射缺失、PDD 商品无规格数据或目标规格定位不到时，由服务端 AI 接口把虾皮目标颜色尺码匹配到 PDD 实际规格；候选集限定为实时可选规格，无结果即失败 |
docs/07-mvp-requirements.md
+3 -3
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Product-Requirements-Overview
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Product-Requirements-Overview.-
wiki_revision: 3d6652ff3ac221c6f3829f3473e34646c3e8066b
synchronized_at: 2026-08-19T00:52:59Z
wiki_revision: b323b48023d1a00a223a1a04570be7c20ee782aa
synchronized_at: 2026-08-19T05:44:23Z
<!-- gitea-wiki-mirror:end -->
# 产品需求总览与当前 MVP
@@ -29,7 +29,7 @@ synchronized_at: 2026-08-19T00:52:59Z
|---|---|---|---|---|
| PDD 商品采集闭环 | 管理员维护商品、规则和设备，由 Android 采集结构化结果 | 已交付；T23～T28 增强项部分待验收 | [Epic #1](https://git.ilapage.cn/OPC/goauto/issues/1)、[MVP #2](https://git.ilapage.cn/OPC/goauto/issues/2)、[#3～#30 索引](https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues) | [真机验收](https://git.ilapage.cn/OPC/goauto/wiki/OnePlus-Real-Device-Acceptance) |
| PDD 正式商品档案 | 采购人员长期复用商品资料，可由采集或人工覆盖维护 | 原型草稿，待用户确认 | [#31](https://git.ilapage.cn/OPC/goauto/issues/31) | [QuantUX App `6a81db5d191a826306a7edd6`](http://124.222.27.183:8082/#/apps/6a81db5d191a826306a7edd6.html) |
| Shopee、SYB 与 PDD 商品关系 | 从 SYB 明细提取 Shopee 商品，人工关联 PDD 商品和规格 | #40、#41 原型 2026-08-19 均已确认，Stage B 代码待实施 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40)、[#41](https://git.ilapage.cn/OPC/goauto/issues/41) | [#40 QuantUX App `6a83b708191a826306a7eeb1`](http://124.222.27.183:8082/#/apps/6a83b708191a826306a7eeb1.html)；[#41 QuantUX App `6a83d7b4191a826306a7eebd`](http://124.222.27.183:8082/#/apps/6a83d7b4191a826306a7eebd.html) |
| Shopee、SYB 与 PDD 商品关系 | 从 SYB 明细提取 Shopee 商品，人工关联 PDD 商品和规格 | #40 Stage B 服务端（迁移、API）已完成，Admin 页面与文档同步待实施；#41 Stage B 待实施 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40)、[#41](https://git.ilapage.cn/OPC/goauto/issues/41) | [#40 QuantUX App `6a83b708191a826306a7eeb1`](http://124.222.27.183:8082/#/apps/6a83b708191a826306a7eeb1.html)；[#41 QuantUX App `6a83d7b4191a826306a7eebd`](http://124.222.27.183:8082/#/apps/6a83d7b4191a826306a7eebd.html) |
| PDD 采购闭环 | 采购人员派发任务，Agent 选规格、改地址并创建待付款订单，人工支付后回填物流 | 总体原型 2026-08-18 已确认；代码未实施 | [#32](https://git.ilapage.cn/OPC/goauto/issues/32)、[#33～#39](https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues)、[#42](https://git.ilapage.cn/OPC/goauto/issues/42) | [QuantUX App `6a827440191a826306a7eddd`](http://124.222.27.183:8082/#/apps/6a827440191a826306a7eddd.html) |
| 开发治理与需求追溯 | 负责人和 Agent 需要可复现模板基线、双门禁和需求索引 | 本次文档升级待验收 | [#43](https://git.ilapage.cn/OPC/goauto/issues/43) | 无 UI 原型；DevHarness 目标提交见项目档案 |
docs/08-agent-api-contract.md
+26 -2
View File
@@ -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: d5b5407a09e3bcdc0bc34be2eb244e781c557420
synchronized_at: 2026-08-17T09:16:09Z
wiki_revision: 59c87171d19d73903f38f8747a7cf14b0258f70e
synchronized_at: 2026-08-19T05:44:30Z
<!-- gitea-wiki-mirror:end -->
# MVP 共享 API 契约
@@ -33,6 +33,30 @@ GET /api/admin/v1/pdd-products/{productId}
Android 提交结果的契约不增加字段：服务端在保存任务结果的同一事务更新 PDD 商品最新档案。`completed` 全量覆盖，`completed_partial` 合并明确获得的数据，`failed` 不更新；人工 `disabled` 状态不会被采集自动改回 `active`。
## 管理端：虾皮商品
```http
GET /api/admin/v1/shopee-products
POST /api/admin/v1/shopee-products
GET /api/admin/v1/shopee-products/{productId}
PATCH /api/admin/v1/shopee-products/{productId}
POST /api/admin/v1/shopee-products/{productId}/link-pdd
POST /api/admin/v1/shopee-products/{productId}/restore
POST /api/admin/v1/shopee-products/{productId}/specs/values
DELETE /api/admin/v1/shopee-products/{productId}/specs/values
PUT /api/admin/v1/shopee-products/{productId}/specs/mapping
DELETE /api/admin/v1/shopee-products/{productId}/specs/mapping
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm
POST /api/admin/v1/shopee-products/{productId}/specs/mapping/confirm-exact-matches
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`。
`batch-delete` 提交 `requestId` 和 `ids`（1～500 个），逐条校验引用后返回每条的 `status`（`deleted` / `skipped`）与 `reason`；引用检查覆盖 SYB 明细（#41）与采购任务（#33/#34），两张表落地前恒不阻塞删除。`restore` 恢复一条已软删除商品，恢复后原有 PDD 关联与规格映射保持不变。列表接口 `status=deleted` 筛选已删除商品，默认只返回存活商品。
## 管理端：采集规则
```http
docs/09-delivery-issues.md
+3 -3
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Delivery-Issues
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues.-
wiki_revision: 6ec228c6f14c73f510065fc52c28158bc42c0aea
synchronized_at: 2026-08-19T00:53:06Z
wiki_revision: 9a3d11db5e715f463cdb4fbd78d0a581e4c0807c
synchronized_at: 2026-08-19T05:44:33Z
<!-- gitea-wiki-mirror:end -->
# 当前 MVP 交付工单索引
@@ -60,7 +60,7 @@ synchronized_at: 2026-08-19T00:53:06Z
| T35 | [#37](https://git.ilapage.cn/OPC/goauto/issues/37) | 服务端物流调度与货运宝自动回填 | 采购任务与有效订单能力 |
| T36 | [#38](https://git.ilapage.cn/OPC/goauto/issues/38) | Android PDD 订单物流采集规则 | 采购订单关联契约 |
| T37 | [#39](https://git.ilapage.cn/OPC/goauto/issues/39) | 采购闭环真机端到端验收 | #33～#38、#42 |
| T38 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40) | 虾皮商品档案、PDD 关联与规格映射 | #31；商品域独立于采购任务；Stage A 原型 2026-08-19 已通过，Stage B 待实施 |
| T38 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40) | 虾皮商品档案、PDD 关联与规格映射 | #31；商品域独立于采购任务；Stage B 服务端（迁移、API）已完成，Admin 页面待实施 |
| T39 | [#41](https://git.ilapage.cn/OPC/goauto/issues/41) | SYB 货运单商品导入与虾皮信息提取 | #40；源数据域独立于采购任务；Stage A 原型 2026-08-19 已通过，Stage B 待实施 |
| T40 | [#42](https://git.ilapage.cn/OPC/goauto/issues/42) | Android 采购演练规则与持久执行基线 | #33、#34；只演练，不改地址、不创建订单 |
| T43 | [#45](https://git.ilapage.cn/OPC/goauto/issues/45) | Admin PDD 商品列表多选与批量采集任务创建（2026-08-18 已验收） | 已完成 |