OPC/goauto
2
0
Fork 0
Code Issues 192 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ea970c755e434af54ca565434e7943d2229dd23e
goauto/docs/02-architecture-and-code-map.md
T

24 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: 7a1281d8873cc6afaf121c13c0562a3caf1d3eb7 synchronized_at: 2026-08-27T06:25:11Z

架构与代码地图

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 本地 SQLite 事务中先保存不可逆状态、稳定服务端请求 ID 和脱敏最终确认快照，再通知服务端并只允许一次创建订单点击；重启后只重放服务端标记、只读核单或上报，不再次点击。
  • 原始控件树和截图不持久化；Android Agent 端第一期不使用 OCR/VLM。服务端 SYB 登录验证码识别是唯一例外，见 #48。
  • 蝦皮规格映射独立保存在 shopee_product.specs_json：颜色只能选择关联 PDD 当前可选颜色，允许多个蝦皮颜色共用一个 PDD 颜色；尺码自动匹配只预览格式统一后的唯一确定结果。PDD 目标规格消失后页面标记失效，映射保存和采购创建均拒绝继续使用；无需新增数据库表或 Android 能力。

最小业务数据

表 必要内容
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 与规格值的多对多关联
pdd_account 可选的账号调度引用，只保存名称和状态，不保存凭据
purchase_task 商品外键和不可变快照、执行模式、状态/租约 guard、价格边界、订单、人工支付复核、物流与回填事实
purchase_task_attempt task_id + attempt_id 幂等执行记录、阶段、规则哈希、固化规格决策和结构化错误
ai_matching_setting 唯一单例的启用状态、OpenAI-compatible Base URL、模型、超时、内部部署明文 API Key 和更新人；仅管理员设置接口可以读取该字段

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 列还有数据库检查约束，必须在同一条状态变更语句中更新。

采购表使用同一 guard 思路：purchase_task.active_slot 保证同一 SYB 明细最多一个活动任务，device_run_slot 保证设备串行，account_run_slot 在账号已知时保证账号串行。账号未知是合法状态。正式任务必须引用 SYB 的规则由模型钩子和后续创建服务双重校验；MySQL 8.4 不允许 syb_product_id 同时参与带参照动作的外键和跨字段 CHECK，因此不在该列添加数据库 CHECK。

配置分层

配置分三层，下层覆盖上层：

层 文件 是否进 Git 放什么
1 默认值 server/config/settings.yml 是 应用配置和非机密运维参数（extend.syb 的 baseurl / pagesize / maxmatches / ocrurl）
2 部署本地值 config.yaml（仓库根） 否（.gitignore） 数据库、端口、顺云宝凭据
3 覆盖值 GOAUTO_* 环境变量 — 服务、容器和 CI 用；优先级最高

[必须] 凭据只允许出现在第 2、3 层。 settings.yml 被 Git 跟踪，任何时候都不能往里写账号密码。

服务端自己读第 2 层（config/local.go 的 ApplyLocalConfig），查找顺序为 GOAUTO_CONFIG 指定的路径 → 当前目录 ./config.yaml → 可执行文件同级目录。找不到不是错误：容器场景只用环境变量，本来就没有这个文件。回调注册在 ApplyEnvironment 之前，环境变量因此始终有最后决定权。

[必须] 第 2 层的标量按 YAML 原始类型读取后统一转字符串。纯数字密码不加引号会被 YAML 读成整数，这里不能因此启动失败——但仍应加引号，否则前导零会丢。

开发启动脚本把 config.yaml 的路径通过 GOAUTO_CONFIG 传给服务端，不在 PowerShell 里重复解析 YAML。

前端伺服

web/.env.production 的 VUE_APP_BASE_API 为空，即生产构建发的是相对请求，前端与接口必须同源。服务端在 dist/index.html 存在时伺服构建产物并为 history 路由回退到 index.html（app/admin/router/spa.go）。

[必须] 回退只对非接口路径的 GET 生效。给写错的接口路径回 200 + HTML，客户端看到的会是 JSON 解析错误而不是 404。

[必须] dist 不存在时不注册 NoRoute。开发环境前端跑在 vite 独立端口上，装了回退会把每个真 404 变成一张 HTML 页。

已建立的工程入口

功能 当前目录
服务端基线 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/、web/src/views/goauto/shopee-products/；Admin 按确认原型提供颜色下拉人工映射、确定性尺码批量预览、失效提示和单一保存入口，SYB 快捷入口可突出目标颜色；不修改两端原始规格
虾皮商品档案增量迁移 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
SYB 店铺准入、发现与过滤 server/app/goauto/sybshop/、server/app/goauto/sybimport/；迁移 server/cmd/migrate/migration/version-local/1786700900000_syb_shop.go
SYB 后台导入任务、进度、单任务互斥与启动恢复 server/app/goauto/sybimport/sync_run.go、sync_run_handler.go；表 syb_sync_run，迁移 server/cmd/migrate/migration/version-local/1786701000000_syb_sync_run.go
SYB 每小时自动同步 server/app/goauto/sybimport/import_handler.go 提供手动/定时共用的 StartImport 服务；scheduled_job.go 通过 go-admin 定时任务调度，固定按 Asia/Shanghai 取今天和昨天；任务注册迁移为 server/cmd/migrate/migration/version-local/1786701600000_syb_hourly_sync_job.go
采购任务数据与类型化规则契约 server/app/goauto/models/purchase.go、server/app/goauto/purchasecontract/；迁移 server/cmd/migrate/migration/version-local/1786701100000_purchase_contract.go
采购任务单条/批量预检与创建、租约、attempt 幂等、Admin 只读查询和人工处置状态机 server/app/goauto/purchase/；batch-preview 通过批量预加载 SYB、蝦皮、PDD 与最新任务执行快速只读预检，不访问 AI；batch-create 仍按最新数据逐项完整复核并可在必要时调用 AI；既有追加迁移为 server/cmd/migrate/migration/version-local/1786701200000_purchase_state_machine.go
采购规格标准化匹配与 AI Provider 设置 server/app/goauto/aimatching/；服务端先做繁简、空白/全半角/大小写和公斤/斤的唯一确定性匹配，再按需调用单一 OpenAI-compatible Provider；1786701300000_ai_matching_setting.go 创建设置表，1786701400000_ai_matching_setting_plain_api_key.go 将原加密列迁移为内部明文 api_key，仅管理员读取
任务领取、结果、重置与删除 server/app/goauto/task/
管理端基线 web/（go-admin-ui v3.0.0）
管理端闭环页面 web/src/views/goauto/
Admin 采购任务列表、详情与人工处理 web/src/views/goauto/purchase-tasks/、web/src/api/goauto/purchase-tasks.js；创建入口不在本模块
Admin AI 规格匹配设置 web/src/views/goauto/ai-matching-settings/、web/src/api/goauto/ai-matching-settings.js；管理员可查看、维护和测试 Provider（包括内部明文 API Key），采购员只可查看启用状态
Admin 失败采购任务批量重试 POST /api/admin/v1/purchase-tasks/batch-retry；服务端 server/app/goauto/purchase/retry.go 负责资格判定、逐项幂等创建与部分成功结果，Admin 页面只允许选择服务端标记可重试的行；不修改 Android Agent
SYB 店铺管理页面与接口封装 web/src/views/goauto/syb-shops/、web/src/api/goauto/syb-shops.js；确认原型快照 prototypes/49/v1/index.html
SYB 异步导入、商品筛选、当前页采购选择/确认/逐条结果与同步记录页面 web/src/views/goauto/syb-products/、web/src/views/goauto/syb-sync-runs/、web/src/api/goauto/syb-products.js、web/src/api/goauto/purchase-tasks.js；商品列表按店铺名称包含匹配，并支持最多 100 个多行订单号精确筛选；确认原型见 #44 设计证据，导入原型快照为 prototypes/50/v2/index.html
Android Agent 基线 android/app/src/main/java/cn/ilapage/goauto/agent/
Android 无障碍规则执行 android/app/src/main/java/cn/ilapage/goauto/agent/automation/
PDD 安全规格入口与评论页误触恢复 automation/PddProductDetailCollector.kt：明确选择语义、底部购买文字、评论上下文排除、一次返回重试和结构化错误；不保存控件树或截图
Android 采购规则解释器与正式地址/订单动作 android/app/src/main/java/cn/ilapage/goauto/agent/automation/PurchaseRuleContract.kt、PurchaseRehearsalExecutor.kt、PurchaseLiveAutomation.kt
Android 采购任务、attempt 与 Outbox 持久化 android/app/src/main/java/cn/ilapage/goauto/agent/persistence/；调度入口 service/AgentForegroundService.kt
三端统一验证 scripts/verify.ps1

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

cmautobuy 商品离线导入

server/cmd/import-cmautobuy-products/ 是 #70 的独立单向导入入口，转换逻辑位于 server/app/goauto/cmautobuyimport/。它不注册 HTTP 路由、不参与服务启动，也不是数据库 schema migration。

导入器从 cmautobuy MySQL 只读一致性快照读取有效 pdd_products、shopee_products 和 shopee_skus，再写入 GoAuto 的 pdd_product、shopee_product。旧 PDD 组合 SKU 聚合为 GoAuto 通用维度；同一颜色出现多个不同价格时不猜测价格。旧组合 spec_mappings、SYB、任务、订单和其他域数据不进入导入范围。

默认模式是 dry-run；显式 --apply 才会在目标 MySQL 单事务覆盖同业务键商品。来源与目标配置都来自未跟踪 YAML，连接串和密码不输出。来源蝦皮的字符串 pdd_goods_id 必须通过目标 PDD goods_id 换算为数字 pdd_product_id，提交前重新校验 JSON、唯一键和关联完整性。

Android Agent 0.3 设备端外壳（#88）

  • Android 入口仍为单 Activity，但从动态单页升级为 AndroidX Fragment + Material BottomNavigationView 的四 Tab 外壳：状态、采集、采购、设置；默认进入状态页并保存当前 Tab。
  • android/app/src/main/java/cn/ilapage/goauto/agent/ui/ 保存状态页、设置页、任务占位页、无障碍真实就绪检测和共享 UI 组件；采集/采购历史列表与详情由 #90 接入。
  • 状态页同时读取系统启用的 AccessibilityService 组件和 GoAutoAccessibilityService.instance 绑定事实，区分“未开启”“已开启等待连接”“已开启并就绪”，并显示服务连接、当前任务和最近心跳。
  • 设置页维护服务器地址和设备名称，测试连接只访问 GET /api/v1/health；保存后沿用当前 installId / Device Token 重新连接。执行任务或测试连接期间表单与按钮禁用。
  • 设置页只显示 Token 是否配置，不返回或显示明文；不包含 PDD 账号、采购写操作或支付入口。
  • AgentStateStore 保存界面所需的当前任务类型/编号摘要；任务结束后由执行服务清除。它不保存控件树、截图、完整规则或凭据。

Android Agent 任务结束冷却与返回（#89）

  • AgentForegroundService 在采集结果已提交，或采购结果与 Outbox 已在同一事务安全保存后，建立 15 秒任务结束冷却；不新增第二套队列轮询器。
  • 冷却到期仍由现有任务轮询按“采购优先、再采集”依次确认两个队列都为空。任何新任务、网络/服务端异常或本地未解除的不可逆采购边界都会取消返回。
  • IdleReturnCoordinator 只保存冷却时间、自动化前台包名与无障碍前台切换序号，不保存控件树或截图。用户切换到其他 App 后，即使又返回 PDD，也不会被强制拉回 Agent。
  • 返回请求只允许从 Agent 本次自动化停留的 PDD 或受支持浏览器页面发起，并由无障碍服务打开 MainActivity 状态 Tab；Android 后台 Activity 启动限制导致失败时只提示手动打开，不重复强拉。
  • 任务执行和冷却分别使用带超时的亮屏锁；MainActivity 仅在运行态标记要求时设置 FLAG_KEEP_SCREEN_ON。任务、新任务接管、取消、返回或服务销毁后统一释放，不绕过设备 PIN、图案或密码。

Agent 任务历史（#90）

  • Android 的采集任务与采购任务 Tab 由 TaskHistoryFragment 承载，复用搜索、状态筛选、分页、加载/空/失败状态和只读详情能力。
  • AgentApiClient 调用服务端当前设备历史接口；任务编号规范化由客户端先处理，服务端再次校验。
  • 服务端采集与采购模块各自使用 agent_history.go 负责 Device Token 设备隔离、最近 30 天过滤、分页和最小化 DTO。
  • purchase_task.actual_unit_price_cent 是可空字段，只记录 Agent 实际观察到的采购单价；旧任务不回填。

Agent 受控重新采集（#91）

  • 服务端 task/lifecycle_service.go 的同一 Reset 事务同时服务管理端和设备端；设备端入口使用显式 Device Token 模式，不能用空 Token 退化为管理端路径。
  • POST /api/agent/v1/collection-tasks/{taskId}/reset 只返回最小状态，设备归属、忙碌和商品冲突在事务内检查。
  • Android TaskHistoryFragment 只在采集终态详情显示“重新采集”，确认成功后调用 AgentForegroundService.start 唤醒现有轮询，任务执行仍由 next/claim/start 完成。

Agent 受控采购重试（#95）

  • 服务端 server/app/goauto/purchase/retry.go 的 AgentRetry 使用 Device Token 校验任务归属，并复用 Admin BatchRetry 的当前档案、不可逆边界、设备能力/忙碌和幂等创建逻辑；旧失败任务不修改，新任务固定原设备。
  • GET /api/agent/v1/purchase-tasks 与详情通过 retryable / retryDisabledReason 返回服务端资格结论；POST /api/agent/v1/purchase-tasks/{taskId}/retry 只接受 requestId，不接受客户端指定设备、规格或规则。
  • Android TaskHistoryFragment 在采购失败列表和详情按服务端资格显示单任务“重试采购”，二次确认后调用新接口；成功后唤醒既有 AgentForegroundService 队列，实际执行仍只走 next → claim → start。Agent 不实现批量重试、取消订单、修改既有订单或支付。

Android 系统辅助功能按钮（#97）

  • Android 8.0 及以上的 GoAutoAccessibilityService 请求系统 flagRequestAccessibilityButton，服务连接后向 AccessibilityButtonController 注册单一回调，销毁时注销；服务重连不会叠加回调。
  • 单击由系统分配给 GoAuto 的辅助功能按钮时，只调用既有 openAgentStatus()，以前台 MainActivity 打开“状态”Tab；不领取、创建、重置或重试任务，不打开 PDD，也不改变 15 秒空闲返回规则。
  • 不支持或未分配系统辅助功能按钮的 ROM 保持安全降级；项目不创建自定义悬浮窗。

Android Agent 状态页手动检查（#98）

  • AgentStatusFragment 使用 Android 原生下拉刷新容器；只有状态页顶部下拉会请求一次立即检查，采集/采购历史页的下拉只刷新记录，两者语义不同。
  • AgentForegroundService.checkNow 只向既有单线程同步与调度入口提交一个可合并请求；不建立第二套轮询器，也不改变 15 秒自动轮询、采购优先、设备互斥或服务端租约。
  • 手动请求在已有同步运行时保留一个待处理标记，当前同步结束后再执行一次；重复手势不会并发请求。
  • 结果通过仅限当前应用包的广播返回状态页，区分无任务、采集任务、采购任务、设备忙、配置/认证和网络错误。状态页无障碍信息只读，唯一系统设置入口保留在设置 Tab。
  • 手动检查不创建、重置或重试任务，不绕过无障碍与身份校验，不打开 PDD，不修改地址、不创建订单、不支付。

Agent 任务记录刷新与摘要缓存（#99）

  • Android 的采集/采购历史页使用单个 SwipeRefreshLayout 包裹既有滚动页，只在列表顶部下拉刷新当前查询；请求中合并重复手势，加载失败页仍保留可见重试入口。
  • 设置页保存 1/3/7/15/30 天记录范围（默认 7 天），用当前 Device Token 分页读取采集与采购摘要。两类读取独立结算，支持完整、空、部分和失败反馈。
  • TaskHistoryCache 使用独立 SharedPreferences 保存当前同步范围的列表摘要，网络读取失败时可显示最近同步摘要；Token 继续只保存在 Android Keystore 保护的设备身份存储中，任务详情不离线镜像。
  • 服务端两个 Agent 历史列表查询增加 days=1..30，并继续在数据库查询中强制设备隔离、分页上限和 30 天最大窗口；详情读取仍保持原 30 天边界。
  • 该链路只读，不接入任务领取、执行、重置、重试、PDD 导航、地址修改、创建订单或支付。

Agent 当前页面临时采集（#101）

  • 服务端入口位于 server/app/goauto/task/current_page.go：CreateCurrentPage 原子完成设备校验、任务创建、规则快照和租约；IdentifyCurrentPage 负责白名单短链解析、PDD 商品复用/创建和任务身份绑定。路由为 /api/agent/v1/current-page-collection-tasks 及其 /{taskId}/identify。
  • 默认规则设置位于 server/app/goauto/rule/agent_manual_setting.go，使用单行表 agent_manual_collection_setting。迁移 1787790000000_agent_current_page_collection.go 增加任务来源、识别幂等字段、可空 PDD 外键和默认规则表，并对旧任务回填 admin。
  • collection_task.source 目前只允许 admin / agent_current_page。当前页面任务创建时由设备运行槽防并发，识别商品后再参与 PDD 商品活动槽；结构化结果仍写入既有任务及规格子表，不新增临时任务表。
  • Android 入口仍由 TaskHistoryFragment 承载；点击确认时先启动 AgentForegroundService，不先把 Agent 退到后台。服务先用 TaskExecutionMutex 预占本地串行槽，服务端创建成功后把预占转为真实 taskId；前台已是 PDD 时不执行返回，前台仍是 Agent 且近期见过 PDD 时只尝试一次返回，否则使用不清理任务栈、不带深链参数的 PDD 启动 Intent 恢复现有任务，并在有界等待确认 PDD 前台后才识别身份和调用既有 PddProductDetailCollector。
  • CurrentPageIdentityRunner 负责页面证据、唯一分享/复制入口和面板清理；ClipboardRelayActivity 使用独立、不可导出的短生命周期任务在前台读取新鲜剪贴板，完成后移除中转任务并露出原 PDD 页面。原始剪贴板不进入日志、缓存或网络请求。
  • v2 规则新增可选 currentPageIdentity（分享/复制别名和三个有界超时），旧 v2 规则由 Android 使用安全默认值；新设备能力为 collector.pdd.current-page-share.v1。
  • 该路径复用既有结果/失败接口、PDD 最新档案写回、任务结束返回和采集间隔，不调用浏览器导航，不进入任何采购、地址、创建订单或支付代码。
Reference in New Issue View Git Blame Copy Permalink