diff --git a/Android-Agent-API-Contract.-.md b/Android-Agent-API-Contract.-.md index fa57dfc..23bd89a 100644 --- a/Android-Agent-API-Contract.-.md +++ b/Android-Agent-API-Contract.-.md @@ -16,9 +16,14 @@ POST /api/admin/v1/pdd-products PATCH /api/admin/v1/pdd-products/{productId} GET /api/admin/v1/pdd-products +GET /api/admin/v1/pdd-products/{productId} ``` -新增请求只提交 `url`。服务端展开并规范化 URL、提取 `goods_id`；无法提取时返回 `PDD_GOODS_ID_INVALID`，已存在时返回 `PDD_PRODUCT_EXISTS` 和现有商品 ID。编辑 URL 不改变已有任务快照。 +新增请求只提交 `requestId` 和 `url`。服务端规范化 URL、提取 `goods_id`；无法提取时返回 `PDD_GOODS_ID_INVALID`，已存在时返回 `PDD_PRODUCT_EXISTS` 和现有商品 ID。编辑请求完整提交 URL、标题、店铺、数字销量/评价、状态和 `specs`；人工保存覆盖当前值，但不改变已有任务快照。 + +`specs` 是维度数组。维度包含非空 `name`、`role`（`color` / `size` / `other`）和非空 `values`；规格值包含 `name`、`selectable`，只有颜色值允许包含非负整数分 `priceCent`。列表支持 `keyword` 搜索 goods_id、标题或店铺，并支持 `status` 筛选。商品状态为 `pending`、`active`、`disabled`。 + +Android 提交结果的契约不增加字段：服务端在保存任务结果的同一事务更新 PDD 商品最新档案。`completed` 全量覆盖，`completed_partial` 合并明确获得的数据，`failed` 不更新；人工 `disabled` 状态不会被采集自动改回 `active`。 ## 管理端：采集规则 diff --git a/Architecture-and-Code-Map.-.md b/Architecture-and-Code-Map.-.md index de1465e..c09be48 100644 --- a/Architecture-and-Code-Map.-.md +++ b/Architecture-and-Code-Map.-.md @@ -25,7 +25,8 @@ Android Portal/Agent 3. 管理员从一个 PDD 商品创建任务，可指定设备，也可留空等待空闲设备领取。 4. 任务固化 URL、goods_id 和完整规则快照。 5. Android 串行执行并把结果写回同一条任务；规格与 SKU 写入任务结果子表。 -6. 管理员只在任务详情查看结果，并可对终态任务执行重置。 +6. 同一事务把 `completed` 结果全量覆盖到 PDD 商品最新档案，把 `completed_partial` 明确采集到的字段和规格安全合并；`failed` 不修改商品。 +7. 管理员在任务详情查看原始结构化结果，也可在 PDD 商品页面查看和人工覆盖最新商品资料。 ## 关键设计 @@ -44,7 +45,7 @@ Android Portal/Agent | 表 | 必要内容 | |---|---| | `agent_device` | 唯一 `install_id`、设备信息、状态、Token 摘要、版本化能力、最后心跳 | -| `pdd_product` | `id`、唯一 `goods_id`、当前 `url`、创建/更新时间 | +| `pdd_product` | 唯一 `goods_id`、当前 URL、标题、店铺、数字销量/评价、三态状态和通用多维 `specs_json` 最新值 | | `collection_rule` | `id`、`name`、`content_json`、创建/更新时间、`deleted_at` | | `collection_task` | 商品/设备外键、五态状态、URL/goods_id/规则快照、租约、结果摘要、错误和时间 | | `collection_dimension` | 任务、维度键、名称、排序 | @@ -69,6 +70,7 @@ Android Portal/Agent | go-admin 迁移注册 | `server/cmd/migrate/migration/version-local/1786700000000_goauto_schema.go` | | 设备注册、认证、停用与吊销 | `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/task/` | | 管理端基线 | `web/`（go-admin-ui v3.0.0） | | 管理端闭环页面 | `web/src/views/goauto/` | diff --git a/Business-Rules-and-Glossary.-.md b/Business-Rules-and-Glossary.-.md index bac56aa..41874af 100644 --- a/Business-Rules-and-Glossary.-.md +++ b/Business-Rules-and-Glossary.-.md @@ -2,7 +2,7 @@ ## 当前范围 -当前 MVP 只有四个业务动作：添加 PDD 商品、创建规则、创建采集任务、在任务详情查看 Android 回传结果。顺云宝、Shopee、采购、批量任务、规则发布流程、全局停机和实时屏幕不在范围内。 +当前已实施范围包含 PDD 商品最新档案、规则、采集任务、Android 执行和结构化结果。顺云宝、Shopee、采购、批量任务、规则发布流程、全局停机和实时屏幕仍由独立工单推进。 ## PDD 商品 @@ -10,6 +10,11 @@ - 服务端必须规范化 URL 并提取 `goods_id`；提取失败时拒绝保存。 - `goods_id` 唯一；相同 `goods_id` 再次添加时提示“商品已存在”。 - 已存在商品允许修改当前 URL，但不自动改变已创建任务的 URL 快照。 +- 最简创建只输入 URL，新商品状态为 `pending`；人工完整保存或首次成功采集后转为 `active`，人工可设为 `disabled`。 +- 商品只保存标题、店铺、数字销量/评价和规格的最新值，不保存价格或字段变更历史。 +- `specs_json` 使用通用多维结构，角色为 `color`、`size`、`other`；只有颜色规格值保存非负整数分价格，规格值同时保存是否可选择。 +- 人工保存为完整覆盖。`completed` 采集结果全量覆盖；`completed_partial` 只合并明确采集到的字段和规格，不删除原有缺失部分；`failed` 不修改商品。 +- 人工停用的商品不会被后续采集结果自动重新启用；假售罄、临时售罄和采集失败也不会自动停用商品。 ## 采集规则 @@ -36,7 +41,7 @@ - 失败后允许人工重置或删除后重新创建。 - `completed`、`completed_partial`、`failed` 可以重置；`running` 禁止重置和删除。 - 重置保留原 URL、goods_id、规则和设备快照，在一个事务中删除旧规格/SKU、清空结果和错误，并恢复为 `pending`。 -- 任务结果只在任务详情查看，不回填到 PDD 商品列表或独立结果页面。 +- 任务自身结果仍只在任务详情查看；任务完成后会按完整/部分完成规则更新 PDD 商品最新档案，商品页不替代任务结果审计。 ## 采集字段 diff --git a/Delivery-Issues.-.md b/Delivery-Issues.-.md index d9f5d3a..43536d2 100644 --- a/Delivery-Issues.-.md +++ b/Delivery-Issues.-.md @@ -39,11 +39,11 @@ ## 后续商品与采购设计工单 -以下工单不属于当前采集 MVP。#31 和 #32 的 QuantUX 原型仍是草稿；用户明确审核通过前，不得把后续采购能力混入生产代码。 +以下工单保持商品域与采购域解耦。#31 PDD 商品原型已确认并进入代码待验收；#32 采购原型及采购实施继续遵守各自门禁，不得把采购能力混入 #31。 | 顺序 | 工单 | 交付项 | 主要依赖 / 门禁 | |---|---|---|---| -| T29 | [#31](https://git.ilapage.cn/OPC/goauto/issues/31) | PDD 商品采购档案与规格 JSON 管理 | 先行 #31 QuantUX 原型审核 | +| T29 | [#31](https://git.ilapage.cn/OPC/goauto/issues/31) | PDD 商品采购档案与规格 JSON 管理 | 原型已确认；代码待用户验收 | | T30 | [#32](https://git.ilapage.cn/OPC/goauto/issues/32) | 采购闭环数据关系与交互原型 | #31；#32 原型是全部采购代码门禁 | | T31 | [#33](https://git.ilapage.cn/OPC/goauto/issues/33) | 采购任务数据模型与共享 API 契约 | #31、#40、#41、#32 原型通过 | | T32 | [#34](https://git.ilapage.cn/OPC/goauto/issues/34) | 服务端采购任务、租约、幂等与状态机 | #33 | @@ -55,6 +55,7 @@ | T38 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40) | Shopee 商品档案、PDD 关联与规格映射 | #31；商品域独立于采购任务 | | T39 | [#41](https://git.ilapage.cn/OPC/goauto/issues/41) | SYB 货运单商品导入与 Shopee 信息提取 | #40；源数据域独立于采购任务 | | 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 商品列表多选与批量采集任务创建 | #31 原型已确认；独立于商品档案实施 | 推荐依赖顺序：#31、#40、#41 完成商品域 → #33、#34 建立采购契约和服务端状态机 → #42 完成不下单演练 → #35 管理端人工处理 → #36 高风险真实订单动作 → #37、#38 物流闭环 → #39 真机总验收。 diff --git a/Project-Profile.-.md b/Project-Profile.-.md index 787396f..9bc2ac5 100644 --- a/Project-Profile.-.md +++ b/Project-Profile.-.md @@ -9,8 +9,8 @@ | 主要使用者 | 管理员、采购人员、开发维护者 | | Gitea 仓库 | `OPC/goauto` | | 默认分支 | `main` | -| 当前已实施范围 | PDD 商品 URL、采集规则、采集任务、Android 执行、任务详情结果 | -| 后续设计范围 | PDD 正式商品档案、Shopee/SYB 商品关系、采购演练、创建待付款订单和物流回填 | +| 当前已实施范围 | PDD 正式商品档案、采集规则、采集任务、Android 执行、任务详情结果 | +| 后续设计范围 | Shopee/SYB 商品关系、采购演练、创建待付款订单和物流回填 | | 预计规模 | 20 台 Android；每天约 100 个采集任务、200 个采购任务 | ## 建设基线 @@ -58,4 +58,4 @@ 当前采集 MVP 的 T01～T22 已完成实现并由用户验收；T08 只读实时屏幕已延期。T23～T28 的一加真机增强、规格遍历、假售罄恢复、浏览器重开恢复和端口配置已经实现，其中部分工单仍等待用户验收。 -后续采购方向仍处于设计与工单阶段：#31 PDD 商品档案原型和 #32 采购闭环原型均为草稿、等待用户明确审核；#33～#42 不得在 #32 原型通过前进入采购业务代码实施。采购永不支付，真实地址修改和创建订单属于必须再次人工确认的高风险范围。 +#31 PDD 商品档案原型已由用户确认，数据库、API 和 Admin 商品档案页面已进入待验收；#45 继续独立承担 PDD 商品列表批量创建采集任务，未混入商品档案实现。#32 采购闭环原型及后续采购工单仍按各自门禁推进。采购永不支付，真实地址修改和创建订单属于必须再次人工确认的高风险范围。