OPC/goauto
2
0
Fork 0
Code Issues 195 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7edb4e7b9f7c188c22fd34aa652a90bb0bdebaab
goauto/docs/02-architecture-and-code-map.md
T
QiuSWandClaude Opus 5 7edb4e7b9f feat(#48): add SYB sync orchestration, import endpoint and page entry 
Stage 2. Completes the path from the SYB API to the archive.

sybimport.Sync pages a date range day by day and folds each detail line
through the existing idempotent ApplyDetail. The paging loop is driven by
listTotal, never by the list response's own total, which live data
confirmed is the page's row count rather than the filtered total. A day
whose completeness cannot be proven — a short page, a total that drifted
while paging, a detail response missing an order — stops the run instead
of reporting a partial import as a whole one. Rows already written stay:
they are idempotent on (order_code, detail_id), so a re-run overwrites.

sybimport.Connect reuses the cached session and only discards it when SYB
explicitly says it is invalid. Caching the numeric user id alongside the
cookies is required, not incidental: session validation calls
/am/user/get?id=, and a wrong id comes back as a business error rather
than a logout, so cookies alone can never be revalidated.

The import endpoint is single-flight and detached from the request
context, so closing the tab cannot abandon a half-finished range. It
reads only; no SYB write endpoint is reachable from GoAuto.

The page swaps its "no import entry" warning for a date-range dialog that
warns when the span is wide — a single week held over 7000 orders — and
reports partial progress when a run fails midway.

Verified: go build, go vet, go test ./... all pass. The drift check was
mutation-tested. Not verified: the MySQL migration for syb_session, and
any browser walkthrough.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-19 16:56:00 +08:00

6.2 KiB
Raw Blame History

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: a94218dc2c7cbf1c5d56af808a02bf65aaa19964 synchronized_at: 2026-08-19T08:53:52Z

架构与代码地图

MVP 架构

go-admin-ui
  │ REST：PDD商品、规则、任务、任务详情
  ▼
go-admin Server ───────── 数据库
  │                         ├─ pdd_product
  │ REST：注册/心跳/任务     ├─ collection_rule
  │                         ├─ collection_task（任务+结果）
  ▼                         └─ dimension/value/color_price/sku 子表
Android Portal/Agent
  ├─ 注册、心跳与设备串行锁
  ├─ 领取指定任务或空闲领取未指定任务
  ├─ 执行任务内的 URL 与规则快照
  └─ 提交结构化结果或明确错误

最小闭环

  1. 管理员添加 PDD URL，服务端规范化 URL 并提取唯一 goods_id。
  2. 管理员创建规则；规则创建后立即可用于创建任务。
  3. 管理员从一个 PDD 商品创建任务，可指定设备，也可留空等待空闲设备领取。
  4. 任务固化 URL、goods_id 和完整规则快照。
  5. Android 串行执行并把结果写回同一条任务；规格与 SKU 写入任务结果子表。
  6. 同一事务把 completed 结果全量覆盖到 PDD 商品最新档案，把 completed_partial 明确采集到的字段和规格安全合并；failed 不修改商品。
  7. 管理员在任务详情查看原始结构化结果，也可在 PDD 商品页面查看和人工覆盖最新商品资料。

关键设计

  • pdd_product.goods_id 唯一；重复时提示商品已存在，不重复新增。
  • 规则没有草稿、发布和版本流程；软删除只阻止创建新任务。
  • 已有任务不依赖规则当前状态，始终执行自身 rule_snapshot。
  • collection_task 同时保存任务生命周期和结果摘要，不建立 collection_result 主表。
  • 同一 PDD 商品最多存在一个 pending 或 running 任务。
  • 指定设备只能由该设备领取；未指定任务由在线空闲设备原子领取。
  • 重置在事务中清空原结果，保留 URL、goods_id、规则和设备快照，状态恢复为 pending。
  • Android 本地互斥与服务端原子领取共同保证单设备串行。
  • 原始控件树和截图不持久化；Android Agent 端第一期不使用 OCR/VLM。服务端 SYB 登录验证码识别是唯一例外，见 #48。

最小业务数据

表 必要内容
agent_device 唯一 install_id、设备信息、状态、Token 摘要、版本化能力、最后心跳
pdd_product 唯一 goods_id、当前 URL、标题、店铺、数字销量/评价、三态状态和通用多维 specs_json 最新值
collection_rule id、name、content_json、创建/更新时间、deleted_at
collection_task 商品/设备外键、五态状态、URL/goods_id/规则快照、租约、结果摘要、错误和时间
collection_dimension 任务、维度键、名称、排序
collection_dimension_value 维度、值、排序
collection_color_price 任务、颜色、该颜色统一使用的整数分价格
collection_sku 任务、整数分价格、可用性、完整性
collection_sku_value SKU 与规格值的多对多关联

collection_task 的状态仅为 pending、running、completed、completed_partial、failed。设备身份和心跳表属于 Agent 领取任务的必要基础，不承载 PDD 业务数据。

设备以 JSON 数组保存最后一次注册或心跳上报的版本化能力。v1 任务兼容未上报能力的旧 Agent；v2 任务在创建指定设备任务、获取下一任务、领取和开始四个边界重复校验能力，避免旧 APK 执行未知规则。

数据库使用两个可空 guard 列表达跨数据库唯一约束：活动任务的 active_slot=1，运行中设备的 device_run_slot=1；终态记录对应列为 NULL。复合唯一索引据此保证同商品最多一个活动任务、同设备最多一个运行中任务，同时允许保留任意数量的终态历史任务。状态与 guard 列还有数据库检查约束，必须在同一条状态变更语句中更新。

已建立的工程入口

功能 当前目录
服务端基线 server/（go-admin v2.3.0）
最小闭环数据模型 server/app/goauto/models/
数据迁移与约束测试 server/app/goauto/migrations/
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/shopeeproduct/（服务端 API 已实现；Admin 页面待实现）
虾皮商品档案增量迁移 server/cmd/migrate/migration/version-local/1786700600000_shopee_product_archive.go
SYB 商品明细导入、解析与虾皮档案合并 server/app/goauto/sybimport/（解析、幂等落库、同步编排、导入端点、管理端 API 和 Admin 页面均已实现）
顺云宝（SYB）ERP HTTP 客户端与登录会话 server/app/goauto/sybclient/（登录、OCR 验证码、会话缓存、列表与明细读取；见 SYB-ERP-Interface-Contract）
SYB 商品明细增量迁移 server/cmd/migrate/migration/version-local/1786700700000_syb_product_import.go
任务领取、结果、重置与删除 server/app/goauto/task/
管理端基线 web/（go-admin-ui v3.0.0）
管理端闭环页面 web/src/views/goauto/
Android Agent 基线 android/app/src/main/java/cn/ilapage/goauto/agent/
Android 无障碍规则执行 android/app/src/main/java/cn/ilapage/goauto/agent/automation/
三端统一验证 scripts/verify.ps1

以上入口均已落地；新增 API、表或执行动作时必须同步更新本代码地图与共享契约。

Reference in New Issue View Git Blame Copy Permalink