diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index a49c512..5a51ad4 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,535 +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: c021b5b8251fecaf1cfa4b96d731964f6b04ca52 -synchronized_at: 2026-09-27T02:47:22Z +wiki_revision: 37d0e42383d74fdcbf7962efbadd35f213931e6a +synchronized_at: 2026-09-27T03:35:30Z - -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: 504e1ffaa2cf1989f55048ac7067d8af50fe3bf3 -synchronized_at: 2026-09-22T02:56:22Z - -# 架构与代码地图 - -## MVP 架构 - -```text -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](https://git.ilapage.cn/OPC/goauto/issues/48)。 -- 蝦皮规格映射独立保存在 `shopee_product.specs_json`：颜色只能选择关联 PDD 当前可选颜色，允许多个蝦皮颜色共用一个 PDD 颜色。Admin 商品详情的“一键匹配颜色和尺码”在服务端统一计算两个维度：保留当前仍有效的已确认映射，将唯一确定匹配及达到阈值、具备理由且候选仍有效的 AI 匹配，在重新校验规格上下文后于同一事务直接写为 `confirmed`，无需人工确认；低置信度或无结果保持未匹配，Provider 异常或上下文变化时不写入任何本次结果。PDD 目标规格消失后页面标记失效，映射保存和采购创建均拒绝继续使用；无需新增数据库表或 Android 能力。 - -## 最小业务数据 - -| 表 | 必要内容 | -|---|---| -| `agent_device` | 唯一 `install_id`、设备信息、状态、Token 摘要、版本化能力、最后心跳 | -| `agent_app_release` / `agent_app_release_setting` | 私有 APK 的版本、SHA-256、大小、说明、创建人，以及当前版本单例指针 | -| `pdd_product` | 唯一 `goods_id`、当前 URL、标题、店铺、数字销量/评价、三态状态和通用多维 `specs_json` 最新值 | -| `collection_rule` | `id`、`name`、`content_json`、创建/更新时间、`deleted_at` | -| `purchase_rule` / `purchase_rule_setting` | 采购规则历史与当前规则单例指针；新任务复制规则快照，运行时无常量回退 | -| `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` 幂等执行记录、阶段、规则哈希、固化规格决策和结构化错误 | - -> #241 新增：`server/app/goauto/purchase/order_backfill.go` 与 `order_backfill_handler.go` 提供 `POST /api/agent/v1/purchase-tasks/order-backfill`（Device Token 鉴权，逐条事务、逐条结果）；`server/app/goauto/models/purchase_order_guard.go` 在 `PurchaseTask.BeforeSave` 上全局强制订单号唯一，以 `purchase_rule_setting` 单例行串行化订单号分配，避免新增唯一索引迁移；`purchasecontract.ParseAddressSuffix` 为 `AddressSuffix` 的反解，通过回比而非负向前瞻实现（Go RE2 不支持前瞻）。 -| `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-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`，仅管理员读取 | -| 任务领取、结果、同任务 attempt 重采与删除 | `server/app/goauto/task/`；`collection_task.attempt_number` 保存当前次数，`collection_task_attempt` 归档旧终态执行，增量迁移为 `server/cmd/migrate/migration/version-local/1787983500000_collection_task_attempt.go` | -| 管理端基线 | `web/`（go-admin-ui v3.0.0） | -| 管理端闭环页面 | `web/src/views/goauto/` | -| 备货采购服务端路径 | `purchase_task.task_type` 与迁移 `1787885300000_stock_purchase.go`；`POST /api/admin/v1/purchase-tasks/stock` 由 `server/app/goauto/purchase/service.go` 校验 PDD 当前可选规格并固化 `direct_select`，复用既有任务状态机和设备/账号互斥；重试、替换和 SYB 回填显式排除 `stock` | -| 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）；采购员菜单硬排除，仍只可通过受控 API 查看启用状态 | -| GoAuto 系统菜单与采购员权限基线 | `server/app/goauto/access/` 统一声明 12 个模块、路由元数据和 Admin API 权限矩阵；迁移 `1787885400000_goauto_menus.go` 幂等维护 `sys_menu`、`sys_menu_api_rule`、采购员默认菜单绑定和 Casbin 固定白名单。`web/src/router/index.js` 只保留公共路由，`web/src/store/modules/permission.js` 在登录时根据 `GET /api/v1/menurole` 返回结果注册业务路由与侧栏；退出、凭据异常和切换角色会清除旧动态路由，未授权深链接回退工作台。菜单可见性与 API 授权彼此独立 | -| 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 已在同一事务安全保存后，建立 5 秒任务结束冷却；不新增第二套队列轮询器。 -- 冷却到期仍由现有任务轮询按“采购优先、再采集”依次确认两个队列都为空。任何新任务、网络/服务端异常或本地未解除的不可逆采购边界都会取消返回。 -- `IdleReturnCoordinator` 只保存冷却时间、自动化前台包名与无障碍前台切换序号，不保存控件树或截图。用户切换到其他 App 后，即使又返回 PDD，也不会被强制拉回 Agent。 -- 返回请求只允许从 Agent 本次自动化停留的 PDD 或受支持浏览器页面发起，并由无障碍服务打开 `MainActivity`：现有 Activity 保持当前 Tab，重建时恢复最近一次有效 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、#155） - -- 服务端 `task/lifecycle_service.go` 的同一 Reset 事务同时服务管理端和设备端；设备端入口使用显式 Device Token 模式，不能用空 Token 退化为管理端路径。 -- Reset 复用原 `collection_task.id`：事务先归档旧终态到 `collection_task_attempt`，递增 `attempt_number`，按来源刷新最新规则快照，再清理主表当前结果/错误/租约并恢复 `pending`。归档以 task + attempt 唯一，reset requestId 也唯一，阻止并发或重放重复递增。 -- Admin 来源读取原规则当前存活内容；Agent 当前页来源读取当前手动默认规则。当前页未识别任务可以在下一 attempt 首次绑定，已识别任务仍由 `IdentifyCurrentPage` 的 goods_id 冲突保护限制为原商品。 -- `POST /api/agent/v1/collection-tasks/{taskId}/reset` 返回 `taskId`、`attemptNumber`、状态和重放标记；设备归属/在线/忙碌、规则兼容、商品冲突和采购占用在事务内检查。 -- Android `TaskHistoryFragment` 对所有失败来源显示“重新采集”；当前页来源复用无障碍、近期 PDD 前台、本地互斥和冷却检查，成功后调用 `AgentForegroundService.start`，执行仍由 `next/claim/start` 完成。Admin 详情抽屉与 Agent 详情都展示 attempt 历史摘要；Agent 接口不返回历史规则快照。 - -## 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 的辅助功能按钮时，只调用 `openAgentPreservingTab()`，以前台 `MainActivity` 打开 Agent 并保持最近一次有效 Tab；不领取、创建、重置或重试任务，不打开 PDD，也不改变 5 秒空闲返回规则。 -- 不支持或未分配系统辅助功能按钮的 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` 对 Agent 上报的白名单链接重新校验并最终裁决 goods_id，负责 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 商品活动槽；结构化结果仍写入既有任务及规格子表，不新增临时任务表。失败后通过 #155 的同任务 attempt 机制重新进入队列，不创建第二条临时任务。 -- Android 入口仍由 `TaskHistoryFragment` 承载；点击确认时先启动 `AgentForegroundService`，不先把 Agent 退到后台。服务先用 `TaskExecutionMutex` 预占本地串行槽，服务端创建成功后把预占转为真实 taskId；前台已是 PDD 时不执行返回，前台仍是 Agent 且近期见过 PDD 时只尝试一次返回，否则使用不清理任务栈、不带深链参数的 PDD 启动 Intent 恢复现有任务，并在有界等待确认 PDD 前台后才识别身份和调用既有 `PddProductDetailCollector`。 -- `CurrentPageIdentityRunner` 负责页面证据、唯一分享/复制入口和面板清理；`ClipboardRelayActivity` 使用独立、不可导出的短生命周期任务在前台读取新鲜剪贴板，完成后移除中转任务并露出原 PDD 页面。`PddShareLinkExpander` 仅在手机侧用无 Cookie、无项目凭据的移动端 GET 有界展开白名单短链，逐跳校验并最多读取 64KB 正文；Agent 不裁决 goods_id。原始剪贴板、链接与响应正文不进入日志或缓存。 -- v2 规则新增可选 `currentPageIdentity`（分享/复制别名和三个有界超时），旧 v2 规则由 Android 使用安全默认值；新设备能力为 `collector.pdd.current-page-share.v1`。 -- 该路径复用既有结果/失败接口、PDD 最新档案写回、任务结束返回和采集间隔，不调用浏览器导航，不进入任何采购、地址、创建订单或支付代码。 - - -## SYB 档口入库码（#119～#122） - -- 数据模型与迁移位于 `server/app/goauto/models/syb_inner_code.go`、`server/app/goauto/migrations/` 和 `server/cmd/migrate/migration/version-local/1786701500000_syb_inner_code.go`；Excel 业务记录、逐件入库码、匹配计划、回写批次、检查点、租约和幂等请求分表保存。 -- `server/app/goauto/sybinnercode/` 负责 Excel 解析、物理删除、异步只读匹配、回写预览、全局串行回写、逐件回读确认、结果不明确后的只读复核和启动恢复。 -- `server/app/goauto/sybclient/` 提供 SYB 读取与三个入库码写接口；匹配器只依赖只读接口，不能取得写能力。真实写入只由用户确认后的回写批次触发。 -- Admin API 注册在 `server/app/goauto/sybinnercode/router.go`，页面位于 `web/src/views/goauto/syb-inner-codes/`，菜单入口为“档口入库码”。 -- 服务启动时，未开始的 `queued` 记录释放回可回写，已经进入远端动作的 `applying` 记录转为 `needs_check`，不自动重放写请求。 - -## PDD 商品替换数据模型（#129） - -- `server/app/goauto/models/replacement.go` 定义审计主表 `pdd_product_replacement` 与分项表 `pdd_product_replacement_item`；版本迁移为 `1787885000000_pdd_product_replacement.go`，只新增表，不修改既有表和数据。 -- 主表用 `origin_type + origin_task_id` 区分失败采集任务和失败采购任务来源，以 `target_collection_task_id` 保存替代商品采集证据，以 `created_by_device_id` 保存发起设备。当前设备模型没有操作人绑定，因此该字段只能追溯到设备，不能追溯到采购员账号。 -- 主表的可空 `active_slot` 与 `source_product_id` 组成唯一索引，使同一源商品跨 SQLite、MySQL 和 PostgreSQL 同时最多存在一条 `active` 替换记录；历史记录使用 `superseded`，不软删除、不提供删除接口。 -- 分项表按 `replacement_id + shopee_product_id` 唯一保存本次实际影响集合，并独立记录 `matching / matched / manual_required`、匹配来源、置信度和持久 worker 的尝试/错误信息。某条采购任务能否续做只能读取对应虾皮商品的分项状态，不能读取主表总体进度。 -- `server/app/goauto/replacement/` 提供内部登记、幂等冲突校验、来源/采集证据校验、目标有效性、活动记录唯一性和环检测，以及只读审计查询；管理端只读路由为 `GET /api/admin/v1/pdd-product-replacements` 与 `GET /api/admin/v1/pdd-product-replacements/{replacementId}`。Agent 没有直接写入该领域的 HTTP 权限。 - - -## PDD 商品替换生效与规格匹配（#131） - -- `replacement.Service.RegisterAndActivate` 在同一数据库事务内锁定受影响采购任务与虾皮商品：虾皮商品改指替代 PDD、清除旧规格映射，待执行/待探测采购任务取消并释放租约与运行守卫；执行中和终态任务的 PDD 外键及全部快照保持原样，旧 PDD 仅置为 `disabled`。 -- `pdd_product_replacement_item` 是持久匹配工作项；`pdd_product_replacement_worker_lease` 为多实例全局租约。事务提交后异步唤醒，API 服务启动时恢复遗留 `matching`，最多有限重试，失败转 `manual_required`。 -- 匹配复用 `aimatching.Service.Resolve`。确定性 `exact_match` 可直接确认且不要求置信度；`ai_match` 只有在开关启用、置信度达到 `ai_matching_setting.auto_confirm_min_confidence`（默认 0.9）、候选/角色/原因/输入版本全部通过校验时才确认。 -- 人工维护虾皮规格映射后，同一事务同步分项状态与主表 `completed` / `completed_partial` 聚合；worker 只更新仍为 `matching` 且商品关联、规格 JSON 未变化的行，不覆盖人工结果。 -- 纠错使用 `CorrectAndActivate`：原记录转 `superseded`，新建原始失效商品到新目标的记录，只迁移原 `replacement_item` 冻结的虾皮商品集合，不影响共享中间目标的其他商品。 -- 历史采购执行身份继续以 `PDDGoodsIDSnapshot` / `PDDURLSnapshot` 为准；当前采购查询未发现按可变 `pdd_product_id` 聚合历史数据的实现，因此本工单无需改写统计 SQL。 - - -## 创建采购任务异步规格匹配（#148） - -- `purchase_spec_match_work_item` 是采购独立持久工作项；模型在 `server/app/goauto/models/purchase.go`，迁移由 `migrations.MigratedModels` 统一创建。 -- `server/app/goauto/purchase/match_worker.go` 负责原子领取、租约、30 秒/2 分钟/10 分钟退避、启动恢复、严格自动确认和输入指纹重校验；只写采购任务快照，不写虾皮长期映射。 -- `service.go` 在需要 provider 时把 `pending` 任务与工作项同事务创建并立即返回；`lifecycle.go` 在 `Next`、`Claim`、`Start` 三个入口检查工作项，防止未完成匹配的任务执行。 -- `match_admin.go`、`admin_query.go` 和 `/purchase-tasks/{taskId}/matching*` 提供状态、重新入队和人工候选选择；Admin 页面在列表和详情展示匹配状态与恢复操作。 - -## PDD 颜色图片采集与存储（#133） - -```text -PddProductDetailCollector - -> 颜色卡片子树内锁定同 content-desc ImageView bounds - -> GoAutoAccessibilityService.takeScreenshot（仅内存） - -> 按 bounds 裁剪并压缩 JPEG - -> 先 POST /tasks/{taskId}/result - -> 再逐张 POST /tasks/{taskId}/color-images - -> task.UploadColorImage 校验任务/设备/颜色/JPEG/上限 - -> pdd_product_color_image（PDD 商品 + 颜色唯一，保留最新） - -> static/uploadfile/goauto-color/*.jpg - -> product.Service.Detail 返回 colorImages - -> Admin PDD 商品详情 64×64 缩略图、无图占位与点击预览 -``` - -- 整屏 Bitmap 不进入文件系统、网络、数据库或诊断；截图回调完成后在内存中裁剪，用后回收。 -- `pdd_product_color_image` 保存图片路径、类型、字节数、宽高、来源任务与设备；来源任务继续关联其 `rule_snapshot`。同商品同颜色唯一，更新成功后删除被替换的受控目录旧文件。 -- 上传处理沿用既有 `/static/uploadfile` 静态能力，但使用独立 Agent 受控接口和 `goauto-color` 子目录，不复用公共上传入口。 -- 图片旁路独立于结构化结果状态机。Android 先安全提交结果，再上传图片；任何图片异常只写本地脱敏诊断，不触发失败提交或任务状态回滚。 - - -## Admin GoAuto 分组导航与权限（#142） - -- `server/app/goauto/access/modules.go` 是 12 个 GoAuto 页面模块及两个一级菜单组的代码事实来源；本地迁移 `1787885600000_goauto_menu_groups.go` 创建结构性父菜单，并把既有页面菜单直接迁入父组。 -- 「采集采购」依次包含：SYB 商品、SYB 同步记录、档口入库码、虾皮商品、PDD 商品、采集任务、采购管理；「采采管理」依次包含：SYB 店铺、采集规则、采购规则、设备列表、AI 规格匹配。 -- 迁移保留页面菜单 ID、路由、组件和 API 关联，移除旧的 12 个一级模块根菜单；导航固定为“分组 → 页面”两级，不增加第三级。 -- Admin 角色继续通过角色菜单查询取得全部 GoAuto 页面；采购员获得两个父组和除采购规则、AI 规格匹配外的 10 个页面，AI 页面及入口均不可见。 -- Web 继续通过 `/api/v1/menurole` 动态生成路由；直接访问组内页面时展开对应父组并高亮当前页面。 - - -## GoAuto 采购员 API 权限启动对账（#156） - -- `server/app/goauto/access/purchaser.go` 的 `AdminAPIs` 是 GoAuto 管理接口与采购员授权矩阵的唯一代码事实源；`PurchaserAPIs()` 只筛选其中明确标记为采购员可用的条目。 -- API 服务在注册路由和监听端口之前调用 `access.ReconcilePurchaserPermissions`：补齐 `sys_api` 缺失项，并在单一事务内只删除、重建 `casbin_rule` 中 `ptype=p, v0=purchaser` 的策略。其他角色、自建策略和菜单绑定不在对账范围。 -- 对账每次服务启动执行且幂等；代码新增采购员接口后无需补丁迁移，重启即可补齐；代码减权后旧采购员策略会被清除。 -- 任一数据库对账失败时，API 启动直接返回错误，不注册路由、不监听端口，避免权限矩阵未对齐时继续提供服务。既有版本化迁移保留其历史语义，但不再是运行时权限同步的唯一入口。 - -## 采购规则与 Agent 发布组件 - -- `server/app/goauto/purchaserule/` 提供管理员采购规则 CRUD、当前规则切换和运行时加载；迁移 `1787983600000_purchase_rules.go` 新增两张表、原字节播种默认规则，并把“采购规则”放入“采采管理”。 -- `server/app/goauto/purchasecontract/` 使用万分比定点值校验和计算 `priceGuard`，默认 0.2 / 1.5 与旧整数公式一致。 -- `server/app/goauto/apprelease/` 负责私有 APK 上传、Manifest 解析、哈希、当前版本和双认证下载；迁移 `1787983700000_agent_app_release.go` 仅追加版本表与单例设置表。存储根可由 `GOAUTO_AGENT_RELEASE_DIR` 指定，缺省为服务端工作目录下 `var/goauto-agent-releases`。 -- Android `update/` 组件负责启动静默检查、手动检查、私有下载、完整性校验、任务忙碌门禁、FileProvider 和系统安装确认；不参与任务轮询、心跳或前台服务生命周期。 - -## PDD 商品反向关联与订单继续采购（#161） - -- `server/app/goauto/product/related.go` 通过 `shopee_product.pdd_product_id` 与 `syb_product.shopee_product_id` 批量反查；PDD 详情只返回虾皮商品和规格映射摘要，不嵌入订单行。 -- `GET /api/admin/v1/pdd-products/{productId}/related-syb-products` 返回统一扁平分页，参数为 `page`、`pageSize`（默认 20、最大 100）、`scope=actionable|all`（默认 actionable）和可选 `shopeeProductId`。管理员和采购员可读，其他角色由 Casbin 拒绝。 -- `purchase.Service.ProcessStages` 是 SYB 页和 PDD 关联订单共用的只读阶段入口；批量加载、不调用 AI。当前采购规则缺失或无效时仍返回基础关联、采集和已有任务事实，依赖规则才能创建的行明确标记不可采购。 -- Web 的 PDD 商品详情把“创建备货采购”保留在顶部，把“关联订单继续采购”放在关联商品区块；订单行使用统一分页，并复用既有 `batch-preview` / `batch` 创建路径。 - -## 蝦皮规格自动匹配批处理（#195） - -- 服务端在 `server/app/goauto/shopeeproduct/auto_match_batch.go` 复用单商品“一键匹配颜色和尺码”原子服务，定时任务与 Admin 手动执行共用同一批处理入口。 -- `shopee_spec_auto_match_run` 保存触发来源、稳定 `requestId`、运行摘要和可空唯一 `active_slot`；活动槽与租约保证多实例、定时和手动同时触发时全局最多一个运行批次。 -- `shopee_spec_auto_match_work_item` 按蝦皮商品唯一保存输入指纹、尝试次数、下次尝试时间和逐商品租约。已完成或低置信度/无结果的相同输入不重复调用 AI；规格、关联或 AI 设置更新时间变化后才允许重新处理。 -- 迁移 `1788290000000_shopee_spec_auto_match.go` 幂等创建两张表并写入调用目标 `GoAutoShopeeSpecAutoMatch`。系统任务默认关闭，默认 Cron 为每小时第 15 分钟、每批最多 20 个商品。 -- Admin 蝦皮商品列表通过异步手动接口启动同一批次并轮询最近运行摘要；该入口仅管理员可用，不创建采购任务、订单，不调用 Android Agent，也不执行付款。 - -## SYB 异常规格 AI 定时解析（#198） - -- `server/app/goauto/sybimport/ai_parse_batch.go` 以 SYB 明细为单位执行“确定性重解析 → 封闭候选 AI 解析”，与 #195 的“蝦皮规格 → PDD 规格”任务保持独立。 -- `syb_spec_ai_parse_run` 保存全局批次、活动槽、租约与结构化计数；`syb_spec_ai_parse_work_item` 按 `syb_product_id` 唯一保存输入指纹、尝试次数、冷却和逐行租约。 -- `syb_product` 的 `ai_confirmed`、置信度、限长理由、确认时间和隐藏输入指纹记录 AI 确认事实；`parse_status` 仍只记录确定性解析器结果，`manually_confirmed` 仍只代表人工决定。 -- Provider 只接收单条 `productSpec` 和关联蝦皮商品的颜色/尺码候选；返回值必须逐字属于对应候选。采购可信门禁接受仍有效的 AI 确认，但候选消失后立即 fail-closed。 - -## 定时任务持久化执行历史（#199） - -- `server/app/jobs/execution_log.go` 为 Exec 与 HTTP 两类调度入口统一记录一次执行生命周期；`server/app/jobs/models/sys_job_execution_log.go` 对应表 `sys_job_execution_log`，保存执行标识、任务/调用目标快照、定时触发类型、开始/结束时间、耗时、`running` / `succeeded` / `failed` / `interrupted` 状态及脱敏错误码和摘要。 -- 服务启动时按当前“每个数据库一个调度器实例”的拓扑，把上次进程遗留的 `running` 记录安全收敛为 `interrupted`；任务删除后历史仍保留并可只读查询。 -- `GET /api/v1/sysjob/:id/execution-logs` 由 `server/app/jobs/service/execution_log.go`、`apis/execution_log.go` 和 `router/sys_job.go` 提供任务级分页、状态与开始时间过滤；沿用隐藏菜单 `JobLog` 的角色菜单绑定和精确 GET 权限。Web 入口为 `web/src/views/schedule/index.vue` 的单选“日志”按钮，详情页为 `web/src/views/schedule/log.vue`。 -- 执行历史明确不保存任务参数、AI Provider 地址或密钥、第三方原始响应和业务原始载荷；当前不提供删除、保留期限自动化、WebSocket 实时流或立即执行动作。 -- 追加迁移为 `server/cmd/migrate/migration/version-local/1788357000000_sys_job_execution_log.go`：创建执行历史表、登记只读 API、关联 `JobLog` 菜单，并只给迁移前已绑定该菜单的角色补充精确 Casbin 权限。 - -## 客户端密钥访问架构（#237） - -代码基线 `71f7751`（含用户确认的默认 HTTP/HTTPS 兼容），2026-09-07 完成 Server/Web 代码与隔离测试；本机迁移、管理员菜单写入与 Server/Web 启动已于 2026-09-07 授权完成，真实 HTTP 管理列表和模块目录加载通过；线上仍未部署。 - -- `server/app/goauto/clientkey` 管理独立密钥、授权及审计；`clientapi/routes.go` 的显式 Inventory 将 `/api/client/v1` 映射到既有业务处理器，绝不转发任意 Admin 路由。 -- `clientapi/gateway.go` 默认接受 HTTP 与 HTTPS，无协议开关或转发协议头门禁，按 Bearer 密钥、模块及能力顺序校验，每次请求读取数据库，无授权缓存。`common/clientprincipal` 传递独立客户端身份，不生成或伪装管理员 JWT。 -- `client_api_key` 保存名称、随机 256 位密钥的 SHA-256 摘要、前缀、授权 JSON、启用状态、版本、创建/修改人和最后使用时间；完整密钥仅创建响应一次返回。`client_api_key_audit` 保存管理变更和客户端请求元数据，不保存请求正文、查询参数、响应正文或凭据。 -- 编辑与停用采用启用状态和 version 条件更新，并与变更审计同事务提交；冲突返回 409。业务执行前先持久化请求审计意图，失败则不执行业务。完成后更新状态；更新失败或进程中断可能留下 status=0，表示结果待核对，不能据此自动重放。 -- 部分既有业务操作人字段使用该密钥最近授权管理员的 ID 兼容现有外键；实际调用方以独立审计的 key_id 为准，不能把业务字段当成人工操作证据。 -- Admin 页面 `web/src/views/goauto/client-keys/index.vue` 复用创建/编辑授权弹窗；菜单位于“采采管理”，仅管理员可见。新追加迁移 `1788798000000_client_api_key.go` 创建两表及管理员菜单，不改 Android。 - -## 采购规格面板预滑动兼容（#238） - -代码基线 `58a6c1c`，Android 0.9.60 / versionCode 73（构建完成不等同于已安装/发布）。`PurchaseRehearsalExecutor.applyPostAction` 对 `openSpecPanel.swipeAfter` 只兼容解析、不执行机械预滑动，`waitAfterMs` 保留；首趟继续原 `probeSpecs` 遍历，第二趟继续原 `selectSpec` 精确查找与容器内有界滚动。其他动作的后置滑动仍沿用既有执行语义，失败不会被统一忽略。 - -`GoAutoAccessibilityService.swipePurchase` 的失败分类由 `PurchaseSwipeFailureReason` 枚举提供；共享 `swipeNode` 仅增加可选分类回调，不改变手势目标、轨迹、1500ms 回调等待或其他调用者行为。`GoAutoPurchasePanel` 日志经 `AgentForegroundService` 关联 task、attempt、device 与规则快照哈希，新增预滑动跳过/必需滑动失败标量；不记录节点文字、坐标、原始控件树、截图或凭据。 - -Server/Web、数据库和任务快照不变；旧 APK 仍有预滑动行为，必须更新 Agent 才生效。相关验证在 `PurchaseRehearsalExecutorTest`，Android 全量测试与 APK 构建入口不变。 - -## SYB 逐页保存与部分成功（#239） - -实现绑定 c6a962d；代码已实现不代表当前线上已部署。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。 - -同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。 - -`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。 - -Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。 - -入口为 `SyncWithShopSnapshot → loadDailyList → importSyncPage`；`server/app/goauto/sybimport/sync_page.go` 封装页事务和提交后计数；`import_handler.go` 判定终态，`sync_run.go` 保存及筛选，Web 复用 `web/src/views/goauto/syb-sync-runs/index.vue`。 - -## Android 连续临时采集收尾（#250） - -当前实现绑定 `37e8b56`（Agent 0.9.72 / 85），用户确认 v5 按次数返回后切回 Agent。仅 Android，无 Admin/API/权限/数据库迁移；取代 v1～v4 首页导航。 - -- `AgentSettingsFragment` 在采集间隔后复用卡片和 SwitchMaterial；仅开启显示“返回次数”按钮，Material 单选框选择 1～5 次（默认 3），立即保存或取消。成功无常驻反馈，错误/忙碌显示原因。任务忙碌禁用，弹窗选定时再检查。 -- `AgentSettingsStore` 在私有 `goauto_agent_settings` 保存 `continuous_collection`（false）与 `continuous_collection_return_count`（3）；次数越界或读取错误回落 3，写入失败恢复旧值，无网络加载。 -- `requestCurrentPageCollection` 保留原范围判断；`executeTask` 在采集开始固定次数。`executeTaskWhileAwake` 提交结果、结束图片上传后返回 resultStatus；`ContinuousCollectionPolicy.finish` 仅对完整确认成功调用新 `PddCollectionReturnNavigator`。失败/部分成功不导航。冷却间隔不变，连续模式不启动旧 idle-return。 -- 删除 `PddCollectionHomeNavigator` 和专属首页/搜索层判据。新导航器仅使用 capture/back、当前包名、openAgentPreservingTab；1～5 次 Back，每次后 500ms，前台离开 PDD 终止剩余 Back；保留风险场景停止。最后打开 Agent 并等待 500ms 验证包名，不验证 PDD 首页。仍在原任务互斥与唤醒锁范围内完成，结束后原 finally 释放。 -- `GoAutoCollector` 日志关联 taskId、attemptNumber、deviceId、规则快照 SHA-256；记录 continuousReturn、configuredBacks、固定 reason 和 actions。原因含 count_completed、left_pdd、back_failed、unsafe_page、agent_launch_failed、agent_not_confirmed、navigation_exception、invalid_count；actions 为 Back 尝试数，不代表最终页面。无节点文字、树、截图或个人数据落盘；不扩大采购诊断存储。 -- `ContinuousCollectionTest` 覆盖范围/终态、1～5 次、无变化仍按次数、前台变化、风险、动作/启动失败、包名确认和异常；`ContinuousCollectionSettingsTest` 覆盖开关与次数持久化、默认/越界/写入失败。`:app:testDebugUnitTest :app:assembleDebug` 376 项通过。旧首页专属测试随旧行为替换，新版未安装，UI 大字体/横屏、多设备和完整采集真机链路尚未验证。 - -## SYB 存疑规格候选解析（#251） - -实现绑定 `64b4205`，仅 Server `app/goauto/sybimport`；无 API 字段、数据库迁移、权限、并发模式或 UI 变化。 - -- `parse_candidates.go: ParseWithCandidates` 先运行原 `Parse`，仅 uncertain 时解码并校验已存 SpecsJSON；复用 `closedShopeeCandidates` 提取颜色/尺码封闭候选，拒绝未知有值角色/重复角色。完整候选组合与原文归一比较唯一时确认，其他情况返回原 ParseResult。 -- `ApplyDetail` 在加载既有蝦皮商品后、写入规格前调用；`Reparse` 在保留人工/AI 确认保护后加载关联候选调用。新增 ParseResult 私有 matchedCandidates 标记，使 `mergeParsedSpec` 对已经存在的候选直接返回，避免按维度名重复合并或改变映射。 -- #198 `ProcessSpecAIParseRun → Reparse` 自然接入确定性优化，仍需 AI 的记录沿用原后续步骤，不新增异步任务/Provider 调用/接口。 -- 验证 `go test ./app/goauto/sybimport ./app/goauto/aimatching ./app/goauto/shopeeproduct ./app/goauto/purchase` 和 `go build ./...` 通过；新增候选正反/格式/组合色/单维度、歧义/空值、同步重解析一致、人工保护及无需调用 AI 测试。AI 原有置信度/失败重试测试改用仍需语义理解的合成输入，继续验证原分支。 -- 本轮只使用本地测试数据与 httptest AI，未触发真实 SYB 同步、外部 AI、采购、数据库迁移或服务重启；线上及历史数据效果尚待授权验证。 - - -## 蝦皮详情匹配等待与回读（#254） - -实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。 - -- Server `shopeeproduct.Service.DetailWithAutoMatchBudget` 为详情 GET 附加派生的整次匹配预算，不返回 Provider、Key 等配置。`AutoMatchMappings` 读取 AI 设置 T，使用 2T+10 秒的单个父 context；颜色、尺码、保存及结果回读共用剩余时间。初始配置读取也受有界 context 约束，读取耗时从后续预算扣除。 -- 批量定时匹配调用内部 `autoMatchMappings` 并继续使用原 MaxProviderTimeout=600 秒，不随本次详情入口调整；候选建议与其他 AI 功能不改。 -- Web `ShopeeProductDetailDrawer` 在提交前以普通 GET 刷新商品与预算，仅 auto-match POST 使用 (2T+20) 秒超时。准备失败/缺少预算时不发 POST；旧 Server 必须先更新，不能只发布新版 Web。 -- 加载状态同时绑定商品加载代次和操作序号。关闭/切换立即结束该页面等待状态；同商品重开读取详情，旧响应/旧 finally 不得污染新操作。匹配期间禁止在当前抽屉编辑映射，原人工草稿放弃确认保留。 -- POST 未正常返回时只回读详情及关联 PDD，不自动重发 POST；回读失败结束转圈并保留刷新入口。GET 沿用单请求10秒超时，完整结果回读最多两次串行 GET，不是无限等待。 -- 验证：Go shopeeproduct/aimatching/clientapi 测试与 go build；Web `node --test tests/unit/shopee-match-lifecycle.test.cjs`，Playwright shopee-match-lifecycle 与 shopee-pdd-picker，受影响 ESLint 与 build:prod。 - - -## SYB 行内一键关联最近采集（#253） - -实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。 - -- Web `syb-products/index.vue` 在“去关联”旁增加“一键关联＋下拉箭头”，共享 `quick-link.js` 页面级状态。`quick-link-device-preference.js` 按当前浏览器来源、API环境、用户ID保存设备ID，独立于批量采购偏好；不存密钥或商品数据。首次主动作选机继续原行，箭头选机只保存偏好。 -- Server `shopeeproduct/latest_collection.go` 复用 LinkPDD 的可选 Admin 模式。短事务核对 SYB→Shopee、未关联/规格版本、设备状态，选择并锁定最新 completed/completed_partial 的 agent_current_page 任务及其 PDD；仅完整采集、active且有可用颜色或尺码时更新，WHERE pdd_product_id IS NULL 不覆盖其他操作者的关联。响应保留该事务产生的规格版本及来源task/device/PDD，不能用后续GET替换冻结上下文再自动匹配。 -- 不新增表、迁移、路由或权限对账。原手动关联/替换请求不变；共享 Handler 明确拒绝 Client API 使用此跨模块模式，不能借 Shopee-only write grant 读取 SYB/设备上下文。来源任务原规则快照不改，taskId 可回溯既有采集证据。 -- 关联后读取现有采购准备；需要人工确认或不具备AI资格时停止自动链路并保留关联，其他情况调用原 AutoMatchMappings，沿用 #254 动态预算及原事务保存/上下文冲突保护。最后刷新实际处理阶段，不调用创建采购/订单接口。 -- 运行期间冻结行、商品、手机；前端重复主动作禁用，切换偏好仍只影响未来操作。卸载或 keep-alive deactivated 令旧操作失效，禁止旧回调继续下一步；不声称已经取消服务端在途写入。异常仅有限GET回读和刷新，不自动重发POST。 -- 验证命令：Server `go test -p 1 ./...`、`go build ./...`；Web `node --test tests/unit/syb-quick-link.test.cjs tests/unit/shopee-match-lifecycle.test.cjs`、`pnpm exec playwright test tests/e2e/syb-quick-link.spec.ts tests/e2e/shopee-match-lifecycle.spec.ts --workers=1`、受影响文件 ESLint、`pnpm build:prod`。SQLite 单连接并发测试不代替生产 MySQL 行锁验收；真实AI、生产数据、跨设备人工闭环待验证。 - -## SYB 行内一键替换（#258） - -实现绑定 `2b01974`；部署与验收见 #258 发布证据。本节补充 #253，不改变原未关联入口。 - -- `syb-products/quick-link.js` 复用分体按钮、设备偏好和匹配/回读流程；已关联且允许处理阶段时同位置显示一键替换。先只读预览，固定任务、目标商品及规格版本；不同商品一次确认，同商品不重绑。 -- `shopeeproduct/latest_collection.go` 在原 latestCollection 增加可选 replacement 模式。预览和提交均短事务锁定 SYB、Shopee、原PDD、设备、来源采集与目标PDD，核对旧关联及上下文。提交按预览 taskId 读取，不重新挑选后来采集的商品。 -- Admin 路由注入 `purchase.ValidateQuickReplacement`，在事务内复用采购准备数据集及处理阶段计算，不调用 AI。缺少校验函数拒绝替换；客户端密钥不注入且仍拒绝 latestCollection。无新路由、权限、表或迁移。 -- 关联完成后才执行现有 AI 匹配，不在数据库事务中等待 Provider；同一 SYB 正式采购创建与替换共用 SYB 行锁。历史采购快照不变。SQLite 合成测试覆盖冲突与串行并发请求，不能替代生产 MySQL 多连接锁验收。 - -## 辅助信息缺失的采集关联（#259） - -实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。 - -- completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。 -- `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。 -- 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。 -- 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。 - -## 采购单标题面板与地址就绪等待（#260、#261） - -实现绑定 #260 `3c1ffa4`（执行器回归测试 `7de4318`）、#261 `5ea07f1`，Android 0.9.74 / versionCode87，基于0.9.73。安装及真实采购验收以工单证据为准；不代表 main 的 Android 已整合这些分支。 - -- 采购仅在安全规格入口点击返回SUCCESS后，记录本次页面包名/Activity作为内存上下文；开始新执行或页面身份改变时清除。`PddScreenParser` 的新增 purchaseEntryContext 默认关闭，仅该采购执行器传入；普通解析和采集原判定保留。 -- 当前仍为同一PDD Activity、商品ID非空、没有页面风险、没有选中摘要，且唯一有标题规格滚动区、一个维度有值，同时具有关闭、数量、支付展示区域与下单操作证据时，单标题可识别为NORMAL_SCROLLABLE。只是允许进入既有精确规格探测/选择，不执行下单或付款，不全局认可UNKNOWN，不增加入口重复点击或滑动。 -- 地址入口点击原有1000ms保留；地址列表等待增加唯一修改目标要求。点击修改和保存由500ms改为1000ms，其他通用动作间隔不变，无新配置项。 -- 修改后不再只见“详细地址”文字就立即写入。最多50次、每次间隔200ms读取（不含读取耗时），检查PDD页面风险；唯一可见启用有内容的详细地址EditText，连续两次路径、边界、内容及Activity相同才继续原输入流程。始终零个/多个或不稳定时失败，不取第一个候选。 -- 输入内容生成、输入后回读、保存后退出及返回规格面板、最终复核和单次下单边界不变。新增本机脱敏诊断 addressEditorCandidates / addressEditorPolls 两个整数，与task/attempt/device/ruleHash关联；不记录地址内容、原始树或整屏截图。 -- 仅Android；无Server/Web、共享API字段、数据库迁移或权限变化。真实采购、地址写入及订单创建不作为自动安装验证，不执行付款。 - -### v2 商品入口补点与地址返回等待（#260、#261） - -2026-09-10 实现绑定 #260 `713111d`、#261 `d0a82f3`，Android 0.9.75 / versionCode88；真实采购效果以工单验收为准，非 main 合并声明。 - -- 入口恢复不再把全页面支付方式展示文案单独视为支付页。当前包名/Activity、商品标题和安全入口必须与点击前一致，入口唯一且可用；已打开面板、关闭控件、数量、选中摘要、订单操作、风险/评价页面仍拒绝恢复。支付 Activity 或明确支付、订单、地址文本继续阻止补点。仅允许既有一次重新定位后的规格入口中心手势，随后仍验证面板，不循环、不扩展到地址保存或下单。 -- 保存地址后的确认读取、必要时一次返回后的确认读取，增加最多50次、间隔200ms的有界就绪检查，页面捕获耗时另计。连续两次同一Activity满足原地址回读与确认面板条件后继续；完整信息不要求滚动区域。已明确到地址列表时保留原返回路径，不等待列表出现下单按钮；返回后增加1000ms缓冲。 -- 就绪检查不修改原地址回读和结构下单入口规则；超时后只对既有识别的面板、唯一可用滚动区域执行原有有限滚动。零/多个区域仍失败，不凭地址入口或未知底部节点授权下单。最终精确规格、数量、价格、地址与单次下单边界不变。 -- 私有采购诊断新增布尔 savedAddressMatched、savedPanelMatched；整数 savedLegacySubmitCandidates、savedAddressCards、savedAddressTargets、savedScrollCandidates、savedConfirmationPolls。只记录标量并绑定task/attempt/device/ruleHash，不保存地址、原始树或整屏图。 -- CG109 v1现场读取未达到空闲状态，不能确认原失败具体缺哪项证据；v2覆盖迟到确认节点及可观测性，不将合成测试通过冒充真机修复验收。无Server/Web/API/迁移/权限变化，不需要服务器重启。 - -## 探测到正式采购的单次面板交接（#262） - -2026-09-10 实现绑定 `2ea32fd`，Android0.9.76/code89；基于#260/#261，未声明合并main或真实采购验收通过。 - -- AgentForegroundService通过PurchaseProbeHandoff只在成功spec_probe且结束后新快照仍识别PDD规格面板时保留一次性内存交接。仅taskId/goodsId/ruleHash/deviceId、Activity、前台revision和单调时钟时间，不保留控件节点、地址或选中状态，不落盘；有效期180秒。 -- 正式阶段消费时检查同任务/商品/规则/设备、前台revision及时间，消费后即清除。失配/超时/无任务或采集任务调度/结果异常/进程重启均不能沿用；普通手动再试不会继承已消费交接。现有服务端租约、互斥和匹配等待策略不变。 -- 有交接时，执行器恢复限定的purchaseEntryContext，最多10次、间隔200ms新读取（捕获耗时另计）；连续两次相同PDD Activity且具备既有商品/面板证据才跳过openProduct。空树可有限等待，其他应用/Activity改变/页面风险立即拒绝复用。没有交接时保留原一次判断路径；不把UNKNOWN当成功，不跳过正式精确规格/数量/价格/地址或下单验证。 -- 私有诊断新增handoffPresent、productReused布尔值，reusePolls整数及reuseReason固定枚举legacy_evidence/page_problem/page_changed/handoff_ready/evidence_timeout。仍绑定task/attempt/device/ruleHash，无敏感文本。 -- 无Server/Web、共享API或数据库变化，不需重启服务器。只有合成测试验证；原CG107/108日志证实两阶段，但未记录旧版重开判断，不把上下文丢失假设宣称为唯一现场根因。 - -## 人工订单回填金额扩展（#306） - -实现绑定 8c01329（2026-09-18），分支 feat/306-order-paid-amount；待验收、未部署。复用 #241/#242 链路，不改普通采购提交和扫描器导航。 - -- Android automation/OrderBackfillPolicy.kt：BackfillDetailReader 在订单内收集唯一“实付”金额，使用 BigDecimal 精确转换为人民币分；BackfillItem 增加可选 pddOrderAmountCent。 -- Android network/OrderBackfillUpload.kt 与 persistence/TaskHistoryCache.kt：上传可选金额，读取并缓存 Server 确认金额和独立警告；不把成功警告改为任务失败。 -- Server models/purchase.go：purchase_task.pdd_order_amount_cent 为 nullable BIGINT、非负；与 actual_unit_price_cent 独立。追加迁移 1789800100000_purchase_order_amount.go 使用版本内的局部表模型，仅扩展 purchase_task；历史值 NULL，不回填猜测金额。 -- Server purchase/order_backfill.go：原有逐条事务/设备与订单号保护内补齐空金额；相同值幂等，异值保留并警告；已 order_created 同号任务也能补写。purchase/admin_query.go 输出金额。 -- Web views/goauto/purchase-tasks/index.vue：复用现有订单 state-card 显示 CNY 实付价格或“尚未获取”；列表结构不变。 -- 本次不修改 SYB 客户端或 #305，金额不进入 SYB 请求。 - -验证覆盖 Android 解析/载荷/回执缓存、Server 幂等/冲突/旧请求和局部 SQLite 迁移、Web 金额/空值展示；真机端到端、实际 MySQL 迁移和发布须另行授权，不能以本地测试替代。 - -## SYB 单号回填持久队列（#305） - -实现绑定 e89de1a（2026-09-18，未部署），仅 Server/Web；Android 复用现有普通结果与人工订单回填。 - -- purchase/lifecycle.go、purchase/order_backfill.go → ensureOrderWriteback：与订单事实同事务建立 pending，purchase_task_id 唯一；外部失败不撤销已提交的订单事实。 -- models/purchase_order_writeback.go：purchase_order_writeback 保存不可变 stock/detail/单号快照、状态、attempt_count、write_started、租约、脱敏错误和完成时间；purchase_order_writeback_command 保存 requestId/输入摘要/逐项接受结果；purchase_order_writeback_lease 保存全局单例租约。追加迁移 1789800200000，不改旧物流字段，不批量排入历史订单。 -- purchase/order_writeback.go：批量命令事务/幂等/条件校验和 Admin 状态投影；order_writeback_handler.go/router.go 暴露 Admin 补偿；access/purchaser.go 纳入原采购权限启动对账目录。 -- purchase/order_writeback_worker.go：由 cmd/api/server.go 每数据库启动一个3秒轮询 worker；数据库2分钟单例租约使跨进程及不同任务的相同SYB明细写入串行。写前核对当前任务/关联快照，持久化写入起始标记，并验证租约所有者/剩余时间；不持有数据库事务跨网络请求。失联running恢复只回读，unknown不自动调度；其他同目标未确认写入阻止新写。 -- sybclient/order_number.go：一次 POST updateDetailPurchaseCode，不跟随重定向、不使用读接口重试策略。会话仅从现有 SessionStore 恢复，不在 worker 自动登录/OCR；外部原始错误不写入任务原因。 -- Web purchase-tasks API/页面：共享勾选、按动作筛选、独立状态列/详情及逐项接受结果；付款和物流流程保持原样。 -- 验证入口：go test ./app/goauto/purchase ./app/goauto/sybclient ./app/goauto/access ./app/goauto/migrations ./cmd/migrate/migration/version-local；Web tests/e2e/purchase-order-writeback.spec.ts。测试只使用隔离SQLite和fake/httptest，不代表MySQL多实例或真实SYB验收。 - -### 会话类失败自动重试（#330） - -- purchase/order_writeback_worker.go：restoreOrderWritebackClient 在 ImportCookiesJSON 后调用 sybclient.CheckSession，UserID<=0 显式判不可用；finishSessionUnavailable 复用 lease_expires_at 作为退避到期时间（maxSessionRetryAttempts=6，sessionRetryBackoff 5/10/15/30/30m），领取条件增加 failed+SYB_SESSION_UNAVAILABLE+到期+未达上限。无迁移。 -- purchase/order_writeback.go：会话类失败的 CanSubmit 不受退避租约限制；手工重新提交 attempt_count 置 0。 -- 验证：go test ./app/goauto/purchase（含 httptest 模拟 /am/user/get 与断言 syb_session 未删除）。 - -## Chrome PDD 订单回填扩展（#316） - -- `chrome-extension/` 是独立 Manifest V3 交付单元：popup 只负责配置、启动/停止、状态轮询和逐项结果；content script 只在 `mobile.yangkeduo.com` 的隔离世界中按可见 DOM 串行读取；service worker 负责持久运行状态、聚合冲突和分批提交。 -- 列表遍历限定虚拟列表订单卡片的商品行，排除店铺头和支付、确认收货、退款、售后、取消、更多等动作区；详情只展开收货/订单信息。未看到明确列表末尾证据时必须标记未完整扫描，不得宣称全量。 -- 客户端密钥与冻结的 Admin Origin 只保存在扩展可信上下文；content script 无权读取。请求禁用 Cookie 与重定向，批次最多 50 条，稳定 UUID 可在 service worker 重启或超时后重放；已确认批次不重复计数。 -- 服务端 `POST /api/client/v1/purchase-tasks/order-backfill` 复用 Agent 回填事务校验，但使用独立 client principal，不伪造 Device Token 或 deviceId。Agent 路径仍严格保持设备归属校验及失败后按设备范围回读。 - -## 下单结果读取及应付总额链路（#325） - -分支 fix/325-order-result，2026-09-19，尚未发布及真实下单验收。PurchaseLiveAutomation.readOrderResult 采用25次支付页返回后采样、首次待付款页独立30次采样/最多4次按需滑动；原过渡60次与总90次采样上限保留有界终止。parsePayableAmount只从本次只读标签集合提取明确应付总额。 - -数据链路：PurchaseOrderEvidence.pddOrderAmountCent → PurchaseExecutionOutcome → service/PurchaseResultPayload.kt → purchase.ResultRequest → lifecycle.go 的 order_created 分支 → 既有 purchase_task.pdd_order_amount_cent。重启只读核单也沿用同一可选字段。复用已有结果Outbox、幂等哈希和订单号唯一性；不新增表、配置、任务或SYB金额字段。未修改我的订单回填、Chrome扩展和Web，不能将旧入口的实付含义描述为本次已改成应付。 - -## Admin 订单资料补全与一致回填资格（#326） - -实现3a2472d（2026-09-19），Server/Web，未合并发布；无迁移、无Android/插件改动。 - -- purchase/types.go ManualRequest 增加可选 pddOrderAmountCent；manual.go ResolveUnknown 复用既有行锁事务和模型单号保护，扩展为未知结果确认或已创建订单补缺。仅此操作启用新增重放内容校验和事务内 ensureOrderWriteback，其他人工付款/取消/授权流程不新增入队副作用。 -- order_writeback.go 的任务资格去掉 order_created 限制；validOrderWritebackTarget 统一有效 stock/detail 边界。OrderWritebackViews 一次批量读取关联而非逐行查询，RequestOrderWriteback 和 worker 执行前再次检查。队列结构、租约、外部写入协议不变。 -- web/src/views/goauto/purchase-tasks/index.vue 沿用原详情/弹窗/resolve-unknown API，新增缺字段补录入口、整数分转换、完整性展示及失败保留输入，不增加数据库状态或新的权限资源。旧未知结果请求不带金额继续兼容。 -- 回归：server go test -p 1 ./app/goauto/purchase ./app/goauto/clientapi ./app/goauto/sybclient；Web 生产构建及 tests/e2e/purchase-order-writeback.spec.ts 的6项隔离浏览器测试。真实SYB接口用fake/httptest替代，未执行付款、采购或线上写入。 - -## 规格面板识别回退与选项去重（#331/#332） - -- `automation/PddProductDetailCollector.kt`：`SpecPanelType.REQUIRED_EVIDENCE` 回退分支（地址入口/支付入口/唯一数量输入框 + 同一面板容器 + ≥1 辅助证据）；`ParsedPddScreen` 增加 `hasAddressEntry`、`hasPaymentEntry`、`hasQuantityInput`、`hasQuantityAdjustControls`、`quantityInputCount` 与 `requiredEvidenceSummary()`；`SpecPanelStabilityPolicy`（等待上限 5000ms，地址返回采样 200ms）；规格值按选项块合并（`optionBlock`）。 -- `automation/PurchaseRehearsalExecutor.kt`：`waitForSpecPanel` 对回退类型要求连续两次结构一致；`selectionFailureEvidence` 选中失败诊断。 -- `automation/PurchaseLiveAutomation.kt`：`waitForSettledPanelAfterAddressSave` 保存地址后稳定等待（不按返回键）；`finalSubmitTargets` 拒绝零尺寸文字/容器；新增构造参数 `panelDiagnostic`（仅布尔/计数）。 -- 测试：`SpecPanelRecognitionTest`、`SpecOptionDedupTest`、`SpecPanelFixtures`（脱敏构造样本）。 - -## GoAuto 售后角色与退货模块权限（#341） - -- 追加迁移 `1789801100000_after_sales_role.go` 创建固定角色 `after_sales`（显示名“售后”）。 -- 售后角色幂等复制当前采购员角色的菜单绑定与 Casbin API 策略，因此包含采购业务权限以及“yeeke 退货包裹”“yeeke 同步记录”两个退货模块；初始密码仅通过迁移时环境变量注入，不进入代码、日志或文档。 -- 迁移创建四个内部账号并绑定售后角色；已存在账号不会重置密码或静默改绑角色。 diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index d03d4f2..9a337aa 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,695 +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: 25e61fdbdfe1b3e70fec6d353620170ce14eb31f -synchronized_at: 2026-09-27T02:47:26Z +wiki_revision: e9e9ab39ccc6d8947e5b41815435be24cce43a2a +synchronized_at: 2026-09-27T03:35:33Z - -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: 7bb3997cfbe96343f63d4f6ef80201146c27c142 -synchronized_at: 2026-09-22T02:56:27Z - -# 业务规则与术语 - -## 当前范围 - -当前已实施范围包含 PDD 商品最新档案与采集闭环、虾皮商品档案、SYB 商品与后台导入、采购任务服务、Admin 采购任务与人工处理页面、Android 采购演练，以及 #36 的正式地址后缀与创建待付款订单能力。#36 尚未获得真机创建订单授权和验收；物流采集与自动回填仍由独立工单推进。 - -## PDD 商品 - -- PDD URL 由管理员人工录入。 -- 服务端必须规范化 URL 并提取 `goods_id`；提取失败时拒绝保存。 -- `goods_id` 唯一；相同 `goods_id` 再次添加时提示“商品已存在”。 -- 已存在商品允许修改当前 URL，但不自动改变已创建任务的 URL 快照。 -- 最简创建只输入 URL，新商品状态为 `pending`；人工完整保存或首次成功采集后转为 `active`，人工可设为 `disabled`。 -- 商品只保存标题、店铺、数字销量/评价和规格的最新值，不保存价格或字段变更历史。 -- `specs_json` 使用通用多维结构，角色为 `color`、`size`、`other`；只有颜色规格值保存非负整数分价格，规格值同时保存是否可选择。 -- 人工保存为完整覆盖。`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 建议）。通用 `SetMapping` 入口仍将 `exact_match` 与 `ai_match` 一律写为 `pending`，必须人工确认后才生效；#188 的 SYB 商品页批量 AI 匹配与 #194 的 Admin 蝦皮商品详情一键匹配是两个独立例外。#188 的进入条件已由 #190 放开：只要蝦皮与 PDD 关联完整、PDD 当前为 `active` 且能给出可选颜色/尺码候选、并且已解析出至少一个目标颜色或尺码，即可进入批量匹配。解析状态（含 `parse_status=uncertain` 与 `failed`）、PDD 含颜色尺码之外的可选规格、蝦皮档案中未找到目标颜色或尺码、缺少完整可售 SKU 组合证据，自 #190 起都不再阻断匹配；本项目为内部系统，由此产生的“以错误目标规格进行匹配并保存映射”的风险由人工承担。唯一确定性 `exact_match` 不调用外部 AI，可直接保存为 `confirmed`；SYB 商品页批量 `ai_match` 只要 Provider 成功返回规格结果且理由非空、返回值属于当前可选候选即可直接持久化为 `confirmed`，置信度仅记录供审计、不作为放行门槛。若当前 PDD 档案存在完整可售颜色+尺码 SKU 组合证据，结果还必须命中其中同一个组合；人工录入或外部导入导致组合证据缺失时不阻断保存或创建采购。无结果、已有组合证据中的无效组合或 Provider 异常不得改写现有映射。 -- 颜色映射只能从关联 PDD 商品当前可选颜色中选择，不允许自由输入；未使用颜色优先显示，已被其他蝦皮颜色使用的颜色仍可选择并显示占用者，因此支持多对一。 -- Admin 蝦皮商品详情只保留一个“一键匹配颜色和尺码”入口。已确认且目标仍存在的映射保留；名称标准化后的唯一确定结果直接写为 `exact_match + confirmed`；其余只有在 AI 置信度达到服务端当前阈值、理由非空、返回值仍属于当前可选候选时才写为 `ai_match + confirmed`。低置信度或无结果保持未匹配；Provider 失败、AI 未启用、关联或规格上下文变化时本次不写入。操作前有未保存的人工修改时禁用一键匹配；保存只改映射，不改蝦皮或 PDD 原始规格。 -- PDD 重新采集或更换关联后，目标规格仍存在则映射继续有效；目标规格消失时详情标记“已失效”，服务端拒绝保存不存在的目标，采购预检和创建也拒绝使用失效映射并提示重新选择。 -- 批量软删除逐条校验引用（虾皮商品被 SYB 明细或采购任务引用时不可删除）并逐条返回结果；已删除商品默认不出现在列表，可筛选查看并恢复。 - -- #257：蝦皮颜色与尺码建议/一键匹配先保留仍有效的已确认映射，再复用相同标准化比较：简体、空白、全半角与大小写统一。颜色标准化后仅命中一个当前可选 PDD 候选时，不调用 AI，建议标为 matched，一键匹配按既有流程保存 exact_match + confirmed；未命中或多个不同候选标准化后相同，仍走原 AI 与置信度/候选校验。只转换比较键，蝦皮/PDD 原规格名不改，映射目标保存 PDD 原始候选名称；不引入颜色同义词猜测、不自动重算历史映射。 - -## SYB 商品明细 - -- 一行对应 SYB 一条明确的商品/颜色/尺码/数量明细；唯一键为「蝦皮订单号 `code` + 来源明细 `id`」组合，不是全局唯一 ID（未在多货运单样本中验证过全局唯一性）。 -- `productSpec` 自由文本解析：按最后一个逗号切分为颜色/尺码 → 剥离【】备注 → 判断残留分隔符；解析状态分 `success`/`uncertain`/`failed`，永不猜测原文中不存在的颜色或尺码。 - -- 采购放行不以 uncertain 单独阻断：success 与已提取出至少一个非空颜色或尺码的 uncertain 明细，都可继续进入规格匹配和采购预检；只有 failed 或颜色、尺码均为空的异常明细才要求人工处理。uncertain 状态与解析说明继续保留供审计，不会自动猜测规格。 -- 只有 `success` 状态的解析结果会合并进虾皮商品档案的规格值（来源标记 `import`）；`uncertain`/`failed` 只停留在明细行上供人工复核，不污染共享档案。 -- 金额单位按接口分别定义：`/am/stock/detail/listByStock` 的 `productPrice` 是十进制金额，与 `/am/stock/list` 的 `amtOrder`（×100 整数）不是同一套换算，不可共用。 -- 关联虾皮商品档案：命中存活记录直接关联；命中软删除记录则复活并保留原有人工映射；均不存在时创建最小档案。命中既有档案时只补写为空的参考图与售价，不覆盖人工修改过的标题、店铺和映射。 -- 重新解析只读取已保存的原始 JSON，不请求 SYB 接口，永不改写 `RawJSON`；标记 `manuallyConfirmed` 的明细默认跳过重新解析，除非显式指定强制覆盖。 -- 人工修正的颜色/尺码视为与解析成功同等可信，同样会合并进虾皮商品档案；标记为已人工确认。 -- Admin 商品列表的订单号筛选每行一个、去空去重后精确匹配，最多 100 个且单项最长 64 字符；店铺名称使用包含匹配。店铺、订单号与解析状态之间使用 AND，不再用该筛选框搜索蝦皮商品 ID 或商品标题。 -- SYB 商品数据本身不保存 PDD 订单号、快递单号、支付或有效订单状态；Admin 的采购任务创建入口位于 SYB 商品列表，任务事实仍写入独立采购域。 - - -### SYB 商品处理阶段 - -- SYB 商品页保留“解析状态”，另按 SYB、蝦皮、PDD、采集任务和采购任务的当前事实动态派生唯一“处理阶段”；不在 `syb_product` 保存容易过期的阶段字段。 -- 对采购人员展示的阶段固定为：待人工处理、未关联 PDD、PDD 待采集、PDD 采集中、PDD 采集失败、规格待匹配、可创建采购、已创建任务、采购成功、待人工核对。 -- 主阶段优先级为：待人工核对 → 采购成功 → 已创建任务 → 待人工处理 → 未关联 PDD → PDD 待采集/采集中/采集失败 → 规格待匹配 → 可创建采购。每行只显示一个阶段和对应下一步。 -- “待人工核对”表示订单结果不明确，必须先人工核查并禁止自动重试；“采购成功”表示已取得 PDD 订单号和下单时间，不代表已经支付。 -- 一个 PDD 订单号只能属于一个采购任务，该唯一性在采购任务保存路径上全局强制（#241）。人工处理结果未知、取消及 lifecycle 保存路径撞号时返回 `PURCHASE_ORDER_NUMBER_ALREADY_USED`，提示订单号已属于哪个任务，由采购员人工核对，不静默覆盖原值。 -- 不可逆边界之后的 `order_created` 结果回传是上述规则的例外：此时 PDD 真单已创建，发现订单号已属于其他任务时不回滚、不判失败，而是把任务降级为 `order_result_unknown`，冲突订单号以「读到订单号 X，但该号已属于任务 CG-yy」保存在任务与 attempt 的 `error_message`，`pdd_order_no` 留空以维持唯一性，保留下单时间与不可逆时间，进入既有人工处理结果未知通道。首要目标是保住「真单已存在」这一事实，不制造无记录的真实订单。 -- Agent 可按收货地址后缀 `_cg<任务号>` 批量回填订单号与下单时间（#241）。 -- Agent 侧回填为**人工触发的只读扫描**（#242）：入口在采购记录页搜索按钮右侧，输入天数（默认 2）后确认启动。天数口径为滚动 N×24 小时，基准是页面读到的下单时间。采集、采购、回填三者互斥，复用既有任务互斥锁并加原子防重入，忙碌时拒绝启动而不排队、不抢占。 -- 回填扫描不假设订单列表有序：只有连续观察到至少 5 单且下单时间严格递减、期间无缺失时间时，才允许「超过指定时间即停止」；一旦出现时间回升或缺失，改为扫至内部上限并明确标记「未完整扫描」，不得把不完整结果显示为已扫完。内部上限用于限制设备占用，不作为用户可配置的门禁。 -- 回填扫描全程只读：确认收货、申请退款、催发货、去支付、立即支付、提交订单、付款、退款、取消订单、再次购买、删除订单永久排除为点击目标；点击目标必须自身可点、子树不含上述词，且不与任何含上述词的可见控件几何重叠；不得按固定坐标盲点。遇登录、验证码或风控立即停止并报告。 -- 解析不出规范后缀的订单一律跳过，其订单数据不缓存、不上传、不入日志；上传载荷只含后缀、订单号、可选下单时间，以及 #306 的可选实付金额。本地缓存只采纳服务端确认的事实，并区分页面读到的真实时间与 `irreversible_at` 回落估算值。后缀只承载任务号，请求不含地址全文或收件人信息；只允许回填该设备自己的正式采购任务；页面下单时间优先，缺失时回落该任务的 `irreversible_at` 并标记时间来源，两者皆空则该条失败。 -- 已失败、已取消或演练完成的旧采购任务不单独占用主阶段；当前数据仍满足条件时恢复显示“可创建采购”，旧任务继续在采购管理留痕和按既有规则处理。 -- 未选择处理阶段时，商品列表仍先返回，当前页阶段和采购准备继续异步批量读取且不调用 AI Provider；选择阶段筛选时，服务端必须先对完整查询结果派生并筛选阶段，再计算总数和分页，不能只过滤当前页。 - -## SYB 店铺过滤 - -- `syb_shop` 保存允许导入的 SYB 店铺；店铺名比较前统一去除首尾空白、转换全角/半角字符并忽略大小写。规范化后同名的店铺只能保留一条有效记录。 -- 版本迁移会对历史存活店铺回填 `normalized_name = Normalize(display_name)`；回填只改匹配键且可重复执行。若两个存活店铺回填后会得到同一键，迁移必须整体失败并保留原数据，管理员先人工消除歧义后再执行，不能静默合并、删除或改变店铺启用状态。 -- 店铺可以从 SYB 真实货运单列表发现，也允许管理员手工补充。只有管理员可以新增、改名、启停和软删除，采购员等其他角色只读。 -- 没有任何启用店铺时，导入必须在读取凭据、建立会话、验证码 OCR 和任意 SYB 网络请求之前失败，并给出“请先启用店铺”的可读提示。 -- 同步先预检全范围总数及上限，每页校验原始列表条数、合法 ID 和重复，再按冻结店铺快照获取明细并页事务保存；整日结束核对总数。过滤不能降低完整性校验范围，已保存不能冒充整日完整（#239，c6a962d，已于 2026-09-08 随 d403f3b 部署线上）。 -- 只有列表与明细响应的店铺名都非空且命中启用快照时才允许写入。明细店铺名为空、变化为未启用店铺或无法匹配时跳过，并计入跳过数量。 -- 停用或软删除店铺只影响后续导入，不删除历史 SYB 商品、虾皮商品或任务数据。已有错误导入数据的清理必须先给出精确 SQL 和影响行数，再由用户单独确认。 - -## SYB 后台导入记录 - -- 导入允许管理员和采购员（purchaser）创建，创建成功后立即转入后台执行；页面关闭不取消任务。其他已登录角色只能查看同步记录，不能开始导入（#236）。 -- 系统同一时刻只运行一个 SYB 导入任务。`syb_sync_run` 的唯一执行槽负责跨进程互斥，内存锁减少同一进程内的竞争；服务重启后遗留的执行中记录标记为“已中断”。 -- 导入失败或中断时保留已写入商品，记录明确的失败原因和已处理进度；重新导入相同范围按「订单号 + 明细 ID」覆盖，不产生重复商品。 -- 创建同步记录时冻结本次启用店铺的规范化匹配集合、展示名称快照及 SHA-256 哈希；后台执行必须只使用这一份快照，不得在开始后重新读取 `syb_shop`。同步详情保存并返回快照可用标记、快照店铺名称、哈希及各店铺“已导入/已跳过”数量。#212 之前的历史记录只有哈希和统计，明确标记为无完整快照。上述记录不保存账号、密码、Cookie、Token、验证码图片或 SYB 原始响应。 -- 后台任务创建前的内部失败仍向普通用户显示“服务端处理失败”，但使用稳定错误码区分阶段：店铺预检为 `SYNC_SHOP_PREFLIGHT_FAILED`，同步记录创建为 `SYNC_RUN_CREATE_FAILED`。服务端只记录阶段和经过脱敏、截断的底层原因，不记录请求体、凭据、Cookie、Token、验证码或原始响应。 - -## 采集规则 - -- 规则创建后立即可用，不存在草稿、发布、版本或停用流程。 -- 规则允许编辑；新任务读取编辑后的当前内容。 -- 创建任务时保存完整 `rule_snapshot`；规则编辑不影响正在执行的当前 attempt。人工重新采集会归档旧 attempt，并按来源刷新规则：Admin 来源读取原 `rule_id` 的当前存活内容，Agent 当前页来源读取当前手动采集默认规则；规则已删除、不可用或设备能力不兼容时拒绝重采且不修改原任务。 -- 删除采用软删除；删除后不能创建新任务，但已有任务继续执行自身快照。 -- 商品详情步骤应声明精确 `activityName`，并与包名和唯一控件共同作为页面证据；进入 PDD 登录 Activity 必须返回 `PDD_LOGIN_REQUIRED`，不能提交采集成功。 -- 唯一文字节点不可点击时，Agent 只可点击其最近的可点击父容器；不得改点兄弟节点或相似文字。 -- 商品页规格入口只接受带明确选择语义的规格摘要，或底部真实“购买/拼单”文字按钮。若“请选择”和颜色/尺码语义分散在同一可点击父容器的子节点中，也只能在该容器唯一、位于非底部动作区且同时具备两类语义时作为规格入口；规则别名只能收窄已识别的安全候选，不能按页面原始文字扩张。底部购买入口在通过全部安全过滤后仍存在多个候选时，按最右优先（`centerX` 降序，并列时可点击面积升序）确定性选出唯一入口，不再因候选不唯一直接失败；该情形记为 `bottom_purchase_rightmost`，唯一候选仍记为 `bottom_purchase`。“单独购买”与“发起拼单”打开同一规格面板，但对应不同成交形态与价格，最右优先是经人工确认的取舍。评价、评论、晒单、问答、订单、提交订单、支付和付款区域及其父容器一律排除。商品评价页与详情页共用 Activity 时，首次误触只允许安全返回并重新定位一次，重复误触明确失败；点击无变化、误入评价页和面板结构无法确认使用不同错误码。 -- v2 规则使用类型化动作和固定阶段钩子。已由 Agent 支持的选择器、别名、超时、滑动方向和有限次数可以只更新规则；新增动作类型或页面算法才需要升级 Agent。 -- v2 任务首次未进入精确商品详情页时，可以按规则显式重开同一浏览器 URL 一次；登录、验证码、风控、无效链接和详情页内采集失败不触发该恢复。 -- 假售罄恢复只使用主商品规格/购买强证据判断页面是否正常；顶部“相似商品”可以作为受控兜底证据，推荐卡片的标题、价格和销量不得冒充主商品证据。 -- 商品规格遍历必须用已识别规格节点锁定横向颜色容器和纵向面板容器；颜色按视觉行蛇形遍历，滑动完成后重新读取节点，尺码只读并允许在标题滚出后沿已锁定容器续页。 -- PDD 已选规格的订单确认形态只可由详情页、选择摘要、唯一数量控件、支付区、唯一底部提交动作和唯一主要滚动容器的组合证据确认；底部提交动作只读且永久禁止点击。Agent 只在该已确认容器内最多三次向下拖动回顶，每次重新读取节点；“参考分类”作为尺码的精确标题别名处理。 - -- PDD 完整规格选择器若无主滚动容器且尚未选择规格而没有已选摘要，仍可识别为非滚动规格面板，但必须同时出现至少两个已解析维度、至少两个可选项、唯一数量控件和唯一底部订单动作；缺少其中任一强证据时保持未识别。该订单动作仍仅作页面证据，永久禁止点击。 -- Agent 可扩展，但规则必须按任务类型授权：采集规则不能创建订单，采购规则只能使用独立审核的创建订单能力。当前项目不实现支付动作、入口或测试；支付、下单和订单相关文字可以作为只读页面证据配置，但不得成为点击目标。后续支付能力必须单独评估并至少具备显式能力位、服务端开关、单笔金额上限和人工授权。 - -- #256（Android 0.9.73，实现 43703e0）：采集执行器可识别无“已选/请选择”摘要且当前仅一个规格标题的滚动规格面板。必须匹配 PDD 包名、任务详情 Activity 与选择器，无登录/验证等异常，并同时具备唯一有界规格滚动区域、唯一标题及非空候选、关闭、唯一数量输入/增减、支付区和唯一下方提交订单只读动作；缺失任一证据仍拒绝。此分支只由采集上下文启用，不生成虚假选中摘要，采购与其他解析调用维持原条件。订单动作仍仅作只读证据，采集绝不点击。 - -## 采集任务 - -- 任务与结果共用 `collection_task` 主表，不建立独立 `collection_result` 主表。 -- 创建任务时固化 `url_snapshot`、`goods_id_snapshot` 和 `rule_snapshot`。 -- 设备默认人工指定；未指定时由在线空闲设备原子领取。 -- 一台设备同时只执行一个任务。 -- 同一 PDD 商品不能同时存在多个 `pending` 或 `running` 任务。 -- 手机离线时运行中任务失败；默认不自动重试、不自动换机。 -- 所有 `failed` 任务，无论由 Admin 还是 Agent 当前页创建，都允许采购员人工“重新采集”；必须复用原 `collection_task.id`，不得为同一次重采新建任务。Admin 来源继续允许重置 `completed`、`completed_partial`，Agent 当前页来源只允许失败后重采；`running` 禁止重置和删除。 -- `collection_task.attempt_number` 表示当前执行次数。重采事务先把旧终态执行归档到 `collection_task_attempt`，保留当次来源、设备、规则 ID/快照、终态、结构化错误、结果摘要与时间，再递增 attempt、清理主表当前错误/结果/租约并恢复为 `pending`；不保存原始控件树、截图、Token 或个人数据。 -- 重采使用最新有效规则：Admin 来源刷新原规则当前内容，Agent 当前页来源刷新当前手动采集默认规则。全部资格、规则、设备、商品冲突和幂等检查必须在事务写入前通过；相同 `requestId` 重放不得重复归档或递增。 -- Agent 当前页任务在身份识别前失败时，下一 attempt 允许首次绑定商品；已经绑定商品时必须重新识别为相同 goods_id，不同商品明确失败且不得覆盖原身份。当前页发起重采前仍要求无障碍就绪、最近 PDD 前台证据、设备在线空闲及本地冷却通过。 -- 任务自身结果仍只在任务详情查看；任务完成后会按完整/部分完成规则更新 PDD 商品最新档案，商品页不替代任务结果审计。 -- PDD 商品列表批量操作只选择当前页，最多 100 个商品；每个商品仍创建一个独立采集任务。 -- 已停用、没有可用采集规则或已有 `pending/running` 任务的商品不能勾选，并显示普通人可理解的原因。 -- 一批商品统一选择一个规则和一个可选设备；设备留空时仍由空闲设备领取。服务端提交时逐商品重新校验。 -- 批量创建按商品分别执行现有单任务事务，允许部分成功；失败项返回稳定错误码和可读原因，不回滚已成功任务。 -- 批次 `requestId` 为每个商品派生稳定的创建请求标识，同一批次重放不会重复创建任务。 -- 批量采集不创建采购任务、PDD 订单或支付动作。 - -## 采集字段 - -- PDD 标题、店铺名、销量、评价数量。 -- 通用规格维度和值，当前重点是颜色和尺码。 -- 采集时按颜色读取价格；同一颜色下不同尺码默认价格相同。 -- 逐颜色价格只在精确点击后取得目标选中、已选摘要或规格面板变化证据，并等待候选价格连续稳定后保存；其他颜色残留的选中标记不能阻塞当前颜色。点击无效果时不能沿用旧价格，相同价格允许保存；无法确认选择、找不到价格和价格不稳定只记录结构化原因并按缺失价格提交。 -- 存储时展开 SKU 组合，将颜色价格复制到该颜色各尺码 SKU。 -- SKU 不完整仍提交已有结果并标记 `completed_partial`。 - -## 采购任务契约 - -- 采购域使用独立的 `purchase_task`、`purchase_task_attempt` 和可选 `pdd_account` 引用；PDD、虾皮和 SYB 商品表不保存采购订单、支付、物流或回填字段。 -- `purchase_task.task_type` 区分 `syb_order` 与 `stock`。旧任务迁移为 `syb_order`；备货任务只引用已完成采集且处于 `active` 的 PDD 商品，颜色/尺码必须逐字命中当前可选规格，规格来源固定为 `direct_select`，SYB/虾皮身份快照为空。 -- 备货任务不占用 SYB 活动槽，同一 PDD 商品可存在多个待执行备货任务，但设备、可选账号和执行期互斥仍沿用采购安全边界。备货任务不参与商品替换、批量重试、重新采购授权或 SYB 回填；失败后由人员重新创建备货任务。 -- Admin 在处于 `active` 且具有当前可选颜色价格（有尺码维度时还须有可选尺码）的 PDD 商品详情创建备货任务；颜色、尺码只能从最新采集档案选择，不允许自由输入，颜色切换后按已采集价格更新默认上下限。采购管理列表和详情用“订单采购 / 备货采购”区分类型；备货任务的 SYB/虾皮字段显示为空、失败任务不提供重试，并明确提示“备货采购不参与库存扣减与订单关联。” -- 正式任务必须引用一条 SYB 商品明细；演练任务可以从 PDD 商品人工创建且不引用 SYB。 -- 创建时固化三个商品身份、蝦皮订单号、目标和映射规格、数量、价格区间、币种、URL、`goods_id`、规则、设备和可选账号引用。商品档案后续修改不改变任务解释。正式任务的蝦皮订单号来自 SYB 商品 `order_code`，同一订单号可以对应多条商品和多个采购任务，不作为唯一键。 -- Android 无法可靠识别登录中的 PDD 账号，因此账号引用可空；已知账号才参与账号级串行，未知账号不会阻止采购任务。 -- 同一 SYB 明细可以保留多个历史采购任务，但最多只能有一个活动任务。重新采购新建任务，旧订单不删除、不覆盖。 -- `execution_mode` 创建后不可变：`rehearsal` 只能完成商品、规格、数量和价格复核；`live` 才可能获得改地址和创建订单能力。任何模式都不支持可执行支付动作；规则中的支付相关文字只可作为只读识别信号。 -- 演练规则在服务端契约层拒绝改地址、创建订单和核单动作；正式动作还必须通过版本化能力协商。规则只包含类型化动作，禁止任意脚本。 -- 价格保护保存参考单价、最低单价、最高单价和币种，执行时以 PDD App 实际单价判断；价格越界明确失败，不考虑优惠券。 -- Admin 从 SYB 当前页选择商品，可在“创建采购”和“重新解析”两种批量用途间切换；采购模式只允许选择预检合格行，表头全选不跨页。批量预检和正式创建均最多 100 条并逐条重新校验，每条 SYB 明细只创建一个独立任务；部分失败不回滚其他成功项。 -- SYB 商品列表在列表数据返回后立即展示，采购准备状态独立异步加载；只读批量预检只执行批量数据库读取和本地确定性识别，禁止调用 AI Provider。自 #215 起，未保存或已失效的长期规格映射不再阻断创建采购；满足商品关联、PDD 状态、价格、规则、设备和订单安全门禁后即可创建任务，每个新 SYB 采购任务都在首个 attempt 以当次 PDD 页面候选重新决策。 -- SYB 商品页的 PDD 采集资格独立于采购处理阶段：只要已关联的 PDD 商品未停用、没有 `pending` / `running` 采集任务且存在可用采集规则，即可创建采集任务；因此已完成采集并进入“可创建采购”的商品也可以重新采集。相同 PDD 商品在批量创建前按商品去重，服务端创建时仍按最新状态复核。 -- 批量创建读取管理员选定的当前采购规则并重新执行契约校验，每条任务保存不可变快照；当前规则缺失或无效时明确阻断，不回退到代码常量。设备默认人工指定，也可以留空由符合能力的空闲设备领取。 -- 批量创建的价格保护来自 PDD 商品档案而不是 SYB/Shopee 的 TWD 售价：当前采购规则可用 `priceGuard.minRatio`（0.1～1.0）和 `maxRatio`（1.0～3.0）配置比例，缺省仍为 0.2 / 1.5；最低价向下取整、最高价向上取整到人民币分。已确认颜色映射时按该颜色计算，待规格探测时以全部可用颜色的最低/最高价计算，参考价取最高价；没有可用颜色价格时不能创建。 -- 地址后缀为 `_cg{purchase_task.id}`。精确规格、数量、价格和摘要核验通过后，若仍处于已识别的规格面板，Agent 只允许点击唯一、可见、启用、可点击且文案精确命中“确定/确认”别名的规格确认控件；不得点击提交订单、确认购买、付款、支付、地址修改或地址保存控件，也不使用中心手势兜底。点击后必须重新读取并确认已出现订单确认页或地址入口强证据，否则明确失败。进入订单确认页后，若收货地址被面板裁切，只允许在唯一、可见且占据主要宽度的纵向滚动容器内有限向下拉动来显示地址，禁止按页面最大滚动区域盲目滑动。Agent 只在唯一地址入口、唯一修改按钮和唯一详细地址输入框均成立时修改；脱敏手机号文字本身不可点击时，仍以该唯一文字节点的中心坐标执行一次精确手势点击，不沿用可能覆盖整个下单面板的可点击祖先。“修改”“保存”和“提交订单”等文字节点即使依赖可点击父节点，也必须保留原始文字节点作为每次重新定位的锚点，父节点只用于验证存在可点击路径。近乎完全重叠的无障碍重复节点按一个目标处理，仍有多个独立目标或页面切换超时则明确失败。按首个 `-` 或 `_` 截取地址主体后追加当前后缀，保存后必须回读完整新地址。修改或回读失败时禁止创建订单，地址全文和控件树不落库。 -- 地址编辑页可以同时存在收货人、手机号和详细地址等多个输入框；Agent 只选择与“详细地址”标签纵向重叠且位于其右侧的唯一输入框，不能用页面输入框总数或顺序猜测。 -- 点击创建订单前，Agent 必须先在本地事务保存 `order_submit_started`、不可逆时间、稳定请求 ID 和不含地址全文的最终确认快照，再用同一请求 ID通知服务端；两侧成功后才允许精确点击唯一创建订单按钮一次。 -- 进入不可逆边界后，进程重启、断网、点击结果不明或无法取得唯一订单号/下单时间时只允许只读核单并进入 `order_result_unknown`，禁止再次点击；任务与订单正式关联仍以完整 PDD 订单号为准。 -- 创建订单后出现 Android 多微信应用选择器时，Agent 只有在系统包和 `ChooserActivity` / `ResolverActivity` 白名单、已知选择器标题、微信候选三类证据同时成立时，才允许按一次返回，绝不点击微信候选。若已进入真实微信包 `com.tencent.mm`，Agent 不点击、不输入、不登录、不支付、不强制停止微信，只允许用一次无参数 PDD 启动 Intent 把既有 PDD 任务栈拉回前台；第二次仍见微信或拉起失败即保持结果未知。回到 PDD 已知支付 Activity 或明确支付动作页面后最多再返回一次，再只读读取唯一订单号和下单时间；下单成功页仅可点击唯一、精确的“查看订单”或“订单详情”入口一次，进入 PDD 订单详情后才允许有限向上手势下翻读取折叠内容。PDD 页面出现“待付款”“待支付”“订单编号”或“下单时间”等订单结果信号时，该只读信号优先于复用的支付 Activity 名称：允许在唯一主要纵向容器内有限下翻并重新读取，仍不得点击支付；没有任何订单结果信号的支付页或未知页面不得盲目滑动。入口缺失或不唯一、点击后未出现详情证据、任一页面不在白名单、恢复动作重复或结果不唯一时保持 `order_result_unknown`，禁止重下单或支付。 -- Agent 本地 SQLite/Outbox 负责断网和重启恢复，服务端以 `task_id + task_attempt_id` 幂等接收并保存最终事实。 -- 人工支付复核只记录 `paid` / `unpaid`；系统不执行或识别支付。快递单号与回填状态属于采购任务，后续物流工单实现。 -- 采购任务领取时同时占用设备租约和可选 PDD 账号租约；租约过期后才可释放并重新领取。设备还存在采集任务时不能领取采购任务。 -- 自 #215 起，每个新 SYB 采购任务无论是否存在已确认长期映射，都先由 Agent 在当次 PDD 规格面板内有界遍历颜色和尺码并回传原始候选。服务端只以任务冻结的 SYB 目标规格与当次候选先做唯一确定性匹配（繁体转简体、空格/全半角/大小写统一，以及公斤/斤换算），仍无唯一结果才调用已启用的服务端 AI。AI 必须逐字返回当次候选集中的原始标签；候选不完整、集合外返回、歧义、AI 无结果或服务不可用均明确失败，不派发第二趟、更不创建订单。 -- Agent 选择服务端下发的精确颜色或尺码时，只能在已确认打开的规格面板内有限纵向滑动、每次重新读取可选节点并按完整原始文字点击；连续没有新证据或达到上限即停止，不得点击相近规格。第一趟探测并固化规格后，第二趟仍无法精确选择而再次提交探测时，服务端必须明确失败并释放活动槽，保留第一次决策证据，禁止清空决策、循环派发或进入地址与创建订单动作。 -- 采购 Agent 在确认进入 PDD 商品页后、打开规格前，复用采集侧的假售罄识别；规格面板已打开且当前解析到的规格值全部不可选时也按售罄处理。两种情况都只允许关闭规格面板后对商品页执行一次有界恢复（默认下拉 2 次、间隔 1000 毫秒、等待 2000 毫秒），恢复动作失败或恢复后仍售罄时返回 `PDD_GOODS_SOLD_OUT`，恢复后商品页证据丢失时按页面规则不匹配失败；不得继续选择规格、修改地址或创建订单。该失败码继续进入既有替代商品资格判定。 -- 所有新 SYB 采购任务的规则都必须具有 `purchase.spec-probe.v1`；创建时任务级 `mappedColor` / `mappedSize` 为空且 `spec_source=unresolved`，长期映射和 PDD 档案候选都不能跳过首趟探测。第一趟只探测规格并释放租约，服务端固化同一 attempt 的决策后才派发第二趟；探测阶段从服务端拒绝进入 `order_submit_started`。Android 不自行匹配或猜测，只在第二趟接收并精确选择服务端固化的当次 PDD 原始标签。 -- Agent 提交的相同 attempt 最终结果只能写入一次；相同请求重放返回原事实，不同内容拒绝覆盖。`order_result_unknown` 不参与自动派发，只能人工解除。 -- 已创建订单默认禁止再次采购；管理员或采购员可以做一次性重新采购授权，新任务创建成功时在同一事务消耗授权，旧任务和旧订单保留。已标记为已支付的订单不能授权或创建重新采购任务。 -- 人工回填候选只允许从已支付订单选择；同一 SYB 明细后来选择的订单覆盖旧候选，但不删除旧订单事实。 -- Admin 采购管理只查看和处理已有任务，不提供创建入口或支付按钮；单条和批量采购任务都从 SYB 商品列表发起。订单结果未知时必须先人工核对并解除；处于该状态时页面不提供重新采购授权。 -- 采购失败任务可在采购管理当前页批量勾选重试，最多 100 条。重试不修改旧任务，而是用当前 SYB/PDD 档案、目标规格、当前价格保护和当前采购规则创建新的 `pending` 任务，并生成新任务编号与地址后缀；来源蝦皮订单号沿用失败任务的不可变快照。新任务不复用旧任务或长期档案的执行规格，仍必须先完成当次真机规格探测。 -- 只有正式采购、未进入不可逆边界、没有订单号或下单时间、且仍是同一 SYB 最新记录的 `failed` 任务可重试。原设备离线、停用、忙碌或能力不足时该项失败且不自动换机；未指定设备时仍由空闲设备领取。 -- 批量重试逐项处理并允许部分成功；同一请求幂等重放不会重复创建。失败任务不再使用一次性重新采购授权，该授权只保留给已经创建过订单且满足条件的任务。 - -## 管理端角色与权限 - -- 管理端固定支持 `admin`（管理员）和 `purchaser`（采购员）两类业务角色；用户必须绑定一个存在且启用的角色，`role_id=0` 或停用角色不能创建或保存。 -- 采购员可读取设备状态，维护 PDD/虾皮商品和规格映射，查看与修正 SYB 商品，读取 SYB 店铺及同步记录，读取采集规则，创建/重置/删除采集任务，并创建、查看、重试及人工处理采购任务。 -- 仅管理员可管理用户、角色、菜单、接口、部门和岗位；停用设备或吊销 Device Token；新增、改名、启停、删除或发现 SYB 店铺；新增、编辑或删除采集规则；保存或测试 AI Provider 配置。 -- AI 规格匹配菜单对采购员硬排除：采购员不显示该菜单，角色配置也不能为采购员选中该模块；既有 API 权限不变，仍只允许读取是否启用，不得读取 Provider 地址、模型、API Key，也不得保存或测试。 -- GoAuto 菜单由代码维护的模块定义幂等写入系统菜单和菜单/API 关联；迁移只为采购员追加首次引入且默认开放的模块，不会把采购员人工取消勾选的既有模块重新加回。 -- 采购员 Casbin API 白名单由代码权限矩阵全量重建，不从角色菜单勾选反推；减少权限时旧策略必须删除。菜单勾选只控制可见模块，不能扩大采购员 API 权限。 -- GoAuto 管理接口使用 Casbin 按 HTTP 方法和路径授权；设备凭据、规则和外部服务配置等高风险写操作另有管理员角色守卫，前端隐藏入口不能替代服务端授权。 -- 管理员继续使用 `admin` 旁路；采购员必须由明确的 `purchaser` 策略授权，不得通过赋予管理员角色临时解决登录或权限问题。 -- 任何角色都不得执行自动支付。 - -## 自动化边界 - -- 浏览器“打开拼多多APP”和系统确认框“打开”属于允许动作。 -- 登录失效、验证码、风控、人机验证和找不到唯一控件时失败并给出具体错误。 -- Android Agent 到 GoAuto 服务端默认使用 HTTPS。管理员可在明确接受 Device Token、任务内容、设备状态和执行结果被链路监听或篡改的风险后，通过服务端 `GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true` 显式允许全部 `/api/agent/v1/**` 使用 HTTP；该例外不放宽 PDD、SYB、OCR 或其他第三方服务约束。 -- Android Agent 端不使用 OCR/VLM 兜底，不保存原始控件树或截图。采集阶段不猜测缺失数据。 -- 服务端顺云宝（SYB）登录例外：允许调用配置的线上 OCR 服务识别登录验证码（见 [#48](https://git.ilapage.cn/OPC/goauto/issues/48)）。验证码图片会离开本项目发送到该服务，更换服务地址前必须重新评估。此例外只适用于 SYB 登录，不扩大到 Agent 端或任何 PDD 相关流程。 -- 采购阶段的规格匹配由服务端决策（见 [#46](https://git.ilapage.cn/OPC/goauto/issues/46)、[#62](https://git.ilapage.cn/OPC/goauto/issues/62)）：Agent 本地不得自行猜测规格或点击相近候选，只执行服务端下发的精确规格；AI Provider 只有一个 OpenAI-compatible 配置，由管理员维护。根据 #62 已确认的内部部署例外，API Key 明文保存在专用设置表，并只向管理员设置接口返回以便查看和替换；它仍不得写入代码、日志、工单、Wiki、任务快照、采购员接口或 Android 接口。Provider Base URL 不限制内网或公网，支持 HTTP/HTTPS；HTTP 不加密传输中的 API Key，生产环境建议 HTTPS。 -- 采购规则的 `openSpecPanel` 默认不写死页面文字。Agent 只在已由页面语义确认的规格入口或底部购买入口中选择；规则若提供 `textAliases`，只能进一步缩小这些安全候选，不能把任意同名页面文字变成可点击入口。 -- 采购规则的 `probeSpecs.dimensionAliases` 是只读规格维度标题的服务端下发事实源；颜色别名可由管理员增加“组合”等 PDD 页面文案，尺码别名单独维护。该字段只影响探测和 AI 匹配输入，不能改变 `selectSpec` 的精确点击目标；旧任务快照缺省时才使用 Agent 内置兼容值。 -- PDD 采集规则的 `collector.textAliases` 是规格面板、维度标题、选择摘要、评价入口、售罄主商品证据和购买入口等只读识别文案的服务端下发事实源；缺省字段只为旧快照兼容使用 Agent 内置默认值。颜色/尺码分类不得再用代码字面量扩大 `dimensionAliases`。订单和支付文字可以参与只读页面判定，但 Agent 内不可配置的创建订单/确认订单/支付/付款点击拒绝清单始终优先，规则不能放宽；修改地址和收货地址在只读及点击字段中都禁止。 -- PDD 颜色采集对首屏已识别为多行或网格的颜色区执行动态行发现：每次动作后重新解析全部可见行，单列不做无效横向滑动，并复用规则中的 `specVerticalSwipes` 与 `stableEdgeReads` 有界纵向翻页；颜色结束后规格面板归顶，再进入尺码发现。选项重排或已选项从无障碍节点消失时，不得静默跳过仍未尝试的可用颜色。 -- 正式采购规则可以调用独立审核的改地址、创建待付款订单和只读核单动作；采集规则和演练规则不能调用。真机首次安装或验证仍需独立人工授权。 -- 系统当前不提供自动支付、实时屏幕或管理端远程控制。付款、免密支付及任何等价动作不能配置为点击目标；只读识别字段可以包含支付或订单文字。后续若新增支付能力，必须由独立工单和显式控制重新评估。 - -## 设备身份与认证 - -- Android Agent 首次安装生成唯一 `install_id`；服务端收到合法设备信息即注册或更新设备，不使用硬件标识作为唯一键。 -- `install_id` 在设备表中唯一，不存在注册码、注册申请或设备审核记录。 -- Device Token 明文只返回给客户端，服务端数据库只保存不可逆摘要。 -- 设备状态只保存在线、离线或停用；是否忙碌由运行中的任务关系确定。 -- Agent 默认每 15 秒心跳一次，45 秒没有心跳即离线；离线扫描每 15 秒执行。 -- 心跳上报的 `currentTaskId` 必须与服务端该设备唯一运行任务一致；采集任务和采购任务共用这一设备级忙碌事实，异常出现跨域同时运行时按服务端一致性错误处理。 -- 设备超时离线时，运行中的采集任务和尚未提交订单的采购任务立即以 `DEVICE_OFFLINE` 失败，清除租约及运行槽且不自动重试；采购 attempt 同步结束并标为失败。 -- 采购任务已进入 `order_submit_started` 后设备离线时，任务转为 `order_result_unknown` 并释放设备/账号运行槽，必须人工核对，禁止自动重派或再次点击创建订单。 - -## 术语 - -| 术语 | 含义 | -|---|---| -| 规则快照 | 创建任务时复制到任务中的完整规则内容 | -| URL 快照 | 创建任务时复制到任务中的 PDD URL 和 goods_id | -| 空闲领取 | 未指定设备的待执行任务由在线且无活动任务的设备原子领取 | -| 部分完成 | 结果已提交，但一个或多个规格/SKU 缺失 | -| 重置任务 | 保留任务输入快照，清除原结果后重新进入待执行状态 | -| Portal/Agent | Android 端注册、保活、执行规则和提交结果的程序 | -| 虾皮 | Shopee 的中文展示名。管理端界面一律用「虾皮」，数据库表名、字段名、API 路径等程序标识符保持 `shopee_product`（单数）/ `shopee_item_id` 不变 | -| SYB | 顺云宝 ERP（ShunYunBao，域名 shunyunbaoerp.com），虾皮订单与货运单的外部来源系统。管理端界面一律用「SYB」，不再使用「货运宝」「顺云宝」等别名；数据库表名与字段保持 `syb_products` | -| 货运单 | SYB 中的一张单据（`code`，如 260728TB95MJTQ），下挂一条或多条商品明细。与系统名「SYB」区分，不可混用 | -| AI 规格匹配 | 人工映射后仍无法以确定性标准化唯一匹配时，服务端才调用单一 OpenAI-compatible Provider，把虾皮目标颜色尺码匹配到 PDD 实际可选规格；结果必须是候选原始标签，无结果、歧义或 Provider 不可用即失败 | -| 快路径 / 慢路径 | 采购执行的两种路径：Agent 能直接定位到下发的目标规格为快路径；定位不到则触发全量遍历采集并重新匹配，为慢路径 | -| 两趟执行 | 慢路径的实现方式：第一趟采集规格后结束并释放设备，服务端离线匹配，第二趟重新派发下单，复用 `task_attempt` 机制 | -| 采购探测 | 采购时对 PDD 商品页的实时规格采集，同时作为一次商品信息更新写回档案，按 `completed` / `completed_partial` 语义处理 | -| spec_source | 采购任务的规格来源标记：`manual_mapping` / `exact_match` / `ai_match`，用于事后批量追溯 | - - -## SYB 自动同步 - -- 服务端内置 go-admin 定时任务“SYB 每小时自动同步”，默认每小时第 5 分钟执行；同步日期按 Asia/Shanghai 计算，覆盖当天和前一天。 -- 定时同步与保留的手动导入 API 共用同一个导入服务和 `syb_sync_run` 记录；定时任务的操作人显示为“系统定时同步”。 -- 同一时刻只允许一个 SYB 同步任务运行。上一次仍在运行时，本次定时触发直接跳过，不排队、不并发，也不立即重试；等待下一小时再次触发。 -- 定时任务失败时明确记录失败原因，不自动重试。服务重启后由既有启动恢复逻辑处理遗留的运行中记录。 -- 单次同步内部的 SYB 只读请求（货运单总数、列表和明细）遇到暂时网络故障、5xx 或异常响应时最多执行 3 次，分别退避 1 秒、2 秒，单次 HTTP 总超时 60 秒；这不等于失败任务自动重试。明确未登录、业务失败、数据完整性错误以及任何写操作均不自动重试。 -- SYB 商品页不再提供“导入”和“同步记录”快捷按钮，也不查询、展示或轮询同步状态；后台同步成功、失败或中断均不在商品页弹出消息，商品数据由用户主动查询或刷新获取。 -- 独立“SYB 同步记录”页面是同步结果的唯一 Web 展示位置，保留运行状态、进度、数量、失败原因和店铺统计；go-admin 定时任务中的 `GoAutoSYBHourlySync` 提供“执行记录”入口。管理员和采购员可在同步记录页人工发起覆盖昨天和今天的同步，其他角色只读（#236）；人工与定时同步共用导入服务、执行记录和互斥，不排队、不并发，也不立即重试。 - - -## cmautobuy 商品导入 - -- 这是人工触发的单向离线导入，不是持续双写或双库同步；不随服务启动执行。 -- 来源只读取未软删除的 PDD、蝦皮商品及蝦皮 SKU；不导入 SYB、任务、订单、物流、设备、用户、规则和旧组合规格映射。 -- 目标已有相同 `goods_id` 或存活 `shopee_item_id` 时，按用户确认由来源商品档案覆盖；PDD 人工 `disabled` 状态保留，不能被导入自动启用。 -- PDD 销量和评价、蝦皮参考售价在来源没有对应值时覆盖为空；蝦皮币种读取 GoAuto 系统设置，缺省 TWD。 -- 同一颜色只有唯一有效价格时才保存颜色价格；出现多个价格时价格留空、PDD 商品保持 `pending` 并报告，禁止取最低价、最高价或平均价。 -- 蝦皮只聚合来源已解析的颜色和尺码，未解析内容不猜测。来源 PDD 关联不存在、已删除或无法转换时，蝦皮记录作为冲突跳过，不能静默关联其他商品。 -- 默认 dry-run 不写数据库；`--apply` 前必须查看精确影响并再次人工确认。apply 在目标单事务中执行，提交前校验 JSON、唯一键和关联完整性。 - -## Agent 当前设备历史 - -- Agent 只可查看当前 Device Token 对应设备最近 30 天的采集和采购任务，不能跨设备查看。 -- 采集历史可以查看结构化采集结果和错误；采购历史可以查看结构化采购数据和错误。采购记录不提供取消订单、修改订单或支付入口；只有服务端明确标记可重试的当前设备失败任务，才提供受控“重试采购”。 -- 历史接口遵循数据最小化：不下发 Device Token、规则快照、PDD URL、收货地址、原始控件树或截图。 -- 实际采购单价只在 Agent 确实观察到时保存；旧任务或未观察到价格时显示“未记录”，不推算、不回填。 - -## Agent 受控重新采集 - -- 当前设备可以从自身采集任务详情重新采集已完成、部分完成或失败任务。 - -## Agent 受控重试采购 - -- 当前设备只可重试自身最近 30 天内、服务端标记 `retryable=true` 的正式采购失败任务；列表和详情都只能发起单任务重试，不支持多选、批量或自动重试。 -- 普通“重试采购”调用就地 `/reset`：复用原 `purchase_task.id`，只新增 attempt；新 attempt 使用当前有效采购规则和最新版 Agent 代码，商品、目标规格、执行规格、数量、价格、地址及既有规格决策等业务快照保持不变。 -- 就地重试不恢复已经消耗的真机规格探测资格；目标规格存在但对应执行规格为空时必须拒绝，不能进入正式采购阶段。需要按替代商品或已变化业务规格重新决策时，必须走明确的新任务流程。 -- 已出现 `order_submit_started` 证据，或存在不可逆时间、订单提交请求、PDD 订单号、下单时间的任务一律拒绝重试，并提示走既有“授权重新采购”流程，防止重复下单。 -- `requestId` 按“任务 + 重置请求”幂等；相同请求重放返回同一 task ID 和 attempt，不重复递增。 -- Android 只在服务端 `retryable=true` 且状态为 `failed` 时显示普通“重试采购”。确认和成功反馈必须说明复用原任务、新增一次执行、使用当前规则但业务快照不变、可能创建待付款订单且系统不会支付。 -- `/reset` 不得把“目标规格存在但对应执行规格为空”的任务恢复到正式采购阶段；此类异常快照必须拒绝，并提示使用明确的新任务流程。 -- 替代商品匹配完成后的“继续采购”继续调用 `AgentRetry → BatchRetry → Create`，按当前档案创建不同 task ID；Admin 批量重试也保持新任务语义。取消订单、修改既有订单和支付仍禁止。真机重试可能进入创建待付款订单流程，执行前必须再次取得人工授权。 - -## Agent 状态页手动检查任务 - -- Agent 保留既有每 15 秒自动检查。状态 Tab 顶部下拉只触发一次合并到现有调度器的立即检查，不新增轮询器、不改变采购优先和单设备串行。 -- 当前任务执行中、无障碍未就绪、未配置服务端或设备身份异常时不领取新任务，并显示普通人可理解的恢复提示。 -- 检查中合并重复请求；无任务、领取采集、领取采购、设备忙和网络失败都有文字反馈。网络失败后退出手动刷新状态，既有自动检查继续运行。 -- 状态 Tab 只读显示无障碍状态；“打开无障碍设置”只保留在设置 Tab。 -- 手动检查不创建、重置或重试任务，不修改任务资格，不打开 PDD、不修改地址、不创建订单、不支付。 - -## Agent 任务记录刷新与同步 - -- 采集和采购 Tab 顶部下拉只刷新当前 Tab、当前筛选、当前编号搜索和当前页；不领取新任务，也不执行、重置、重新采集或重新采购。加载失败页必须保留可见重试入口，空列表也允许下拉。 -- 设置页记录范围支持手动输入任意 1～30 天整数，默认 7 天、最大 30 天；空值、非整数或越界时不发起同步且就近提示。同步只读取当前 Device Token 对应设备的采集与采购摘要。 -- 两类记录可以独立成功；界面必须明确显示同步完成、范围内无记录、部分完成或失败以及最近同步时间。 -- 本地仅保存列表摘要和同步时间，详情仍按需读取；不缓存 Token、完整规则快照、PDD URL、地址、控件树或截图。 -- 记录同步是服务端到 Agent 的单向只读能力，不打开 PDD、不修改地址、不创建订单、不支付。 - -## Agent 采集任务间隔 - -- Agent 设置页提供设备本地“采集任务执行间隔”，起止值均只接受 0～600 秒整数，默认 `15～15`；每次在闭区间内等概率随机一个整数秒。`0～0` 表示不等待，范围包含 0 时允许本次抽到 0。设置只影响之后结束的采集任务，已开始的间隔不随设置修改。 -- 只有采集任务已经开始且成功向服务端提交完成、部分完成或失败结果后，Agent 才按当时保存的范围随机一次并开始间隔；领取前失败、配置/认证错误或结果未安全提交不随机也不开始间隔。采购任务结束不开始采集间隔。 -- 间隔只阻止下一次采集任务的请求、领取和开始；心跳、采购任务优先领取与执行、采购 Outbox、历史刷新和同步继续运行。间隔结束只触发现有调度器一次，不新增轮询器。 -- 状态页下拉检查和采集记录“重新采集”不得绕过间隔，统一提示“采集间隔中，还需 N 秒”。 -- 本次抽中的秒数、开始时间和截止时间作为同一间隔票据持久保存在设备本地；Agent 进程或前台服务重启、设置修改都只恢复剩余时间，不重新随机。系统时间回拨时最多按该次已抽中的原始秒数截断，避免无限等待。 -- 间隔期间保持屏幕常亮；既有“任务结束 5 秒后返回 Agent”是独立机制，返回 Agent 不清除采集间隔。采购任务接管执行时不重复持有间隔亮屏锁，采购完成后若间隔尚未结束则恢复。 -- 该设置不上传服务端，不改变采集任务状态、租约、规则快照或服务端接口，不打开 PDD、不修改地址、不创建订单、不支付。 - -## Agent 当前 PDD 商品页临时采集 - -- 操作员先人工在 PDD App 打开并停留在目标商品详情页，再从 Agent 采集 Tab 点击“采集”；该入口采集当前页面，不是重置历史任务。 -- Agent 在请求服务端前取得采集/采购共用的本地互斥锁。服务端原子校验设备在线、空闲、跨域活动任务、默认规则和能力，创建固定当前设备且已进入 `running` 的标准采集任务。 -- Agent 启动当前页面采集前先保持自身在前台并启动既有前台服务。恢复时若 PDD 已在前台则不返回；若 Agent 仍在前台且近期见过 PDD，只尝试一次系统返回；仍未恢复时只使用 PDD 自身的不带参数启动 Intent 拉回现有任务，不附加清栈/重置标志。恢复后必须重新验证包名、精确 Activity 与页面强证据；不得启动浏览器、构造深链、自动搜索或自动选择相似商品。 -- 恢复详情页后先按规则唯一点击“分享”与“复制链接”，只读取本次复制后的单条、有限长度剪贴板文本。Android 优先选择含 goods_id 的白名单长链；短链只在手机侧以无 Cookie、无项目凭据、逐跳白名单校验的有限请求展开，失败时可把原短链交给服务端兜底。服务端始终重新校验链接、裁决并规范化 goods_id；Agent 不建档、不猜测商品身份。原始剪贴板、分享文案、链接、响应正文、控件树和截图都不保存。 -- goods_id 已存在时复用唯一 PDD 商品，成功或部分成功结果按既有最新档案覆盖规则更新；不存在时创建 PDD 商品。该流程不自动停用或替换旧商品，也不修改虾皮到 PDD 的关联。 -- 管理员必须配置一条存活的 PDD 商品详情 v2 规则作为 Agent 手动采集默认规则；迁移只做一次安全初选，创建任务时仍实时验证规则与设备 `collector.pdd.current-page-share.v1` 能力。 -- 当前页面任务身份确认前允许 `pdd_product_id` 为空、URL/goods_id 快照为空；普通管理端任务不放宽。身份确认后不可改成其他商品，结果 goods_id 必须与任务一致。 -- 当前页面任务不能使用“重新采集”重置；失败后重新打开目标商品并新建任务。成功提交完成、部分完成或失败结果后，继续进入设备的采集任务执行间隔。 -- 分享入口、复制链接、剪贴板、链接、页面或身份不唯一时明确失败并释放任务槽；不使用 OCR/VLM，不猜测商品身份。 -- 该能力只采集商品资料；不创建采购任务、不选择采购规格、不修改地址、不创建订单，也不执行支付动作。 - - -## SYB 档口入库码导入、匹配与回写 - -- 只接受不超过 10 MB、最多 5000 条非空数据行且包含“标签入库码映射”工作表的 Excel。一次文件只能包含一个营业日期；同日单件入库码必须唯一，同一业务键按营业日期、订单号、档口和规范化规格合并并保留 Excel 顺序。 -- 导入事务提交后自动创建并启动只读匹配任务，不提供独立“匹配”按钮。再次导入同日数据只允许整体替换仍处于等待匹配的数据；存在匹配或回写证据时拒绝覆盖。 -- 匹配必须按精确订单号取得唯一货运单，再以规格、原始 SKU 和档口证据确定唯一商品；歧义、冲突或数量不一致均不猜测。匹配阶段不能调用任何 SYB 写接口。 -- 回写前弹窗展示业务记录数、入库码总数、预计占位明细数和替换旧码数。只有 `ready` 记录可提交；所有服务实例共用数据库租约全局串行执行。 -- 每个远端写动作只发送一次，动作前重读整张货运单并校验匹配计划未漂移；每件写入后重读确认目标码唯一位于预期明细。超时、5xx、响应无法确认或服务在写入期间重启时转为 `needs_check`，禁止自动重试；“只读复核”只能读取远端状态。 -- 列表支持勾选后批量物理删除。删除必须再次确认；选中项包含 `queued`、`applying` 或 `needs_check` 时整批拒绝，不做部分删除。其余选中业务记录、逐件码、计划和终态执行证据在同一事务中物理删除；已写入 SYB 的远端值不会撤销。 - -## PDD 失效或售罄商品替换（#129） - -- 商品替换是“失效的旧 PDD 商品 → 已成功采集的替代 PDD 商品”的即时生效审计事实，可由失败采集任务或失败采购任务发起；Agent 只提交明确的来源类型、任务编号和采集结果，服务端负责最终校验和登记。 -- 替换记录不删除。同一源商品同时只允许一条生效记录；替代商品必须为 `active`，不得与源商品相同，不得形成替换环，并必须由同一发起设备的一条 `completed` 或 `completed_partial` 采集任务证明。 -- 一个 PDD 商品可能被多个虾皮商品共用，因此规格匹配按受影响的每个虾皮商品分项记录。主表只表达总体进度；Agent 展示和“继续采购”资格必须读取当前任务对应虾皮商品的分项状态。 -- 选错替代商品时，连续执行 B→C 不等于撤销 A→B，因为 B 可能还关联其他虾皮商品。正确纠错语义是把原 A→B 记录置为 `superseded`，再建立 A→C，并只处理原记录分项中冻结的影响集合。 -- 创建请求按 `create_request_id` 幂等；重放时源商品、替代商品、来源类型、来源任务、采集证据和发起设备必须一致，否则返回幂等冲突，不能静默覆盖。 -- `created_by_device_id` 只代表 Agent 设备。设备可由管理员绑定到一个采购员账号；一个采购员可拥有多台设备，一台设备最多归属一个采购员，也允许暂不归属。SYB 商品一键关联/替换按当前采购员选择的归属设备读取该设备最新临时采集，不使用其他账号或其他设备的全局最新记录。 - - -## PDD 商品替换生效与规格匹配（#131） - -- 替代商品采集成功后，服务端自动、原子生效，无人工审批。受影响虾皮商品改指替代商品并清除旧规格映射；旧 PDD 商品置为停用但不删除。 -- 原有 `pending` / `spec_probe_pending` 采购任务取消并标记 `PDD_PRODUCT_REPLACED`，释放租约与运行守卫，之后只能由既有重试流程按最新档案创建新任务；不得把新商品外键与旧 URL、goods_id、价格或规格快照拼在同一任务中。 -- `running` / `order_submit_started` 与所有终态采购任务继续保留原商品外键和全部快照，按原任务事实收敛或留作历史；`TargetColorSnapshot` / `TargetSizeSnapshot` 始终是虾皮需求，不因商品替换而清除。 -- 规格匹配按虾皮商品分项持久执行。AI 开关关闭、无结果或未通过自动确认门槛时转人工；确定性唯一 `exact_match` 可不带置信度自动确认。 -- 用户于 2026-08-28 确认放宽 #46 的 AI 口径：`ai_match` 仅在置信度存在且不低于服务端阈值（默认 0.9）、结果严格属于当前候选、颜色/尺码角色唯一完整、原因非空且写入前输入版本未变化时自动确认。否则不得猜测或选择相近候选，转 `manual_required`。 -- 自动确认必须保存来源、实际置信度和脱敏限长原因；人工确认完成后同步对应分项及主表总体状态。worker 不得覆盖已由人工改变的映射。 -- 纠错不能简单执行 B→C；必须把原 A→B 记录置为 `superseded`，建立 A→C，并只处理原记录冻结的虾皮商品影响集合。 - -## 历史：创建采购任务时的异步规格匹配（#148，#215 后仅兼容存量） - -- #215 起，新建 SYB 采购任务不再根据 PDD 档案创建 `purchase_spec_match_work_item`，也不在首次派发前调用外部 AI；规格决策统一来自首趟真机探测的当次候选。 -- 部署前已存在的匹配工作项继续保留审计、恢复、重试和人工处理能力；其 AI 封闭候选、置信度、输入指纹、退避和最长 60 秒调用边界不变，但不能成为新任务跳过当次探测的依据。 - -## SYB 采购强制当次规格探测（#215） - -- 每个新 SYB 采购任务固定执行“首趟只读探测 → 服务端确定性优先/必要时 AI → 固化任务级精确规格 → 第二趟正式采购”。首趟只打开一次浏览器商品链接；匹配期间当前设备保留给同一任务，不领取其他采购或采集任务。连续进入第二趟且当前仍有 PDD 商品页或规格面板强证据时复用当前页、不再次打开链接；手动同任务重试，或当前处于 Agent、其他应用及缺少上述强证据时，重新打开任务固化的商品 URL。复用或重开均不严格核验标题、goodsId 或页面指纹，但仍要求 PDD 包名与商品/规格/订单页面结构安全证据。已有长期映射只作商品档案事实，不直接进入任务执行规格。 -- 首趟候选与 `taskId`、`taskAttemptId`、`deviceId`、规则快照哈希和幂等结果哈希关联；第二趟失败不得回到首趟循环探测。备货 `stock/direct_select` 没有 SYB 目标规格，继续使用用户逐字选择的档案规格，不进入本规则。 -- 候选和 Provider 结果仅保存颜色、尺码原始标签及结构化决策，不保存控件树、整屏截图、账号、地址、订单或支付数据；付款仍永久禁止。 - -## Agent 手动采集替代商品（#130） - -- 采集来源不再按任务状态或错误码白名单限制“采集替代商品”：同一设备的采集任务只要仍关联 PDD 商品、该商品没有进行中的替换，且名下不存在 `running`、`order_submit_started`、`order_result_unknown` 采购任务，即可由人工判断是否替换。命中这三种采购状态时必须硬拦截并提示等待任务结束，不提供强制绕过。采购来源仍只允许失败任务且错误码逐字等于 `PDD_LINK_INVALID` 或 `PDD_GOODS_SOLD_OUT`；Android 只呈现服务端资格，不自行放宽。 -- Agent 创建当前页面采集任务时携带 `replacementOrigin.type`（`collection` / `purchase`）和来源 `taskId`。服务端再次校验设备、来源对应的资格边界、源商品、既有替换与进行中的替换流程，并把来源和激活状态持久化到采集任务，保证进程重启后仍可恢复。采集来源确认替换时必须明确提示：所有关联虾皮商品会改指新商品并清空规格映射、尚未开始的采购任务会取消、原商品会停用且暂不能自动撤销。 -- 替代商品采集结果先按普通采集事务完整保存。随后调用 #131 的原子生效流程；生效失败不得回滚或覆盖已采集商品、规格和 SKU，而是记录稳定的 `failed` 激活状态与限长错误，服务启动后可按同一幂等键仅重试生效，不重新采集。 -- 任务详情的 `replacementMappingStatus` 必须由来源任务对应的替换分项推导，不能只读取主表总体状态。状态为 `matching` 时等待自动匹配，`manual_required` 时由 Admin 人工处理，`matched` 后才进入 #132 的继续采购流程。 -- 替换采集沿用设备级单任务互斥、采集间隔、无障碍安全边界和禁止支付规则；不会增加轮询，也不会创建采购任务或订单。 - -## 替换匹配完成后继续采购（#132） - -- 只有采购来源对应的替换分项为 `matched`，且既有采购重试的任务终态、最新任务、不可逆边界、当前档案、持久化规格映射、PDD 候选、价格、设备在线/空闲与能力门禁全部通过时，Agent 详情才返回 `continuePurchaseEligible=true`。 -- 继续资格的详情查询不调用 AI，也不把当前可重新推导的确定性匹配当作已确认映射；映射被人工清空、PDD 重新采集导致候选变化或价格缺失时返回服务端原因。点击时再次执行同一前置门禁，防止详情读取后的状态漂移。 -- Agent 的“继续采购”复用既有 `AgentRetry → BatchRetry → Create`，请求仍只有来源任务号和 `requestId`；不新增采购创建接口。旧失败任务保持不可变，创建的新任务重新固化当前替代商品、规格、价格、规则和设备快照。 -- `matching` / `manual_required` 只展示匹配状态；`matched` 但资格不通过时展示服务端下发原因。Admin 批量重试行为不变。 -- 真机点击“继续采购”可能创建新的正式采购任务，必须先取得独立人工授权；永久禁止支付。 - - -## 颜色规格图片（#133） - -- 颜色图片是 PDD 商品最新档案的可选数据；缺失、截图不支持、定位、裁剪、压缩或上传失败均不得加入 `missing`，也不得改变 `completed` / `completed_partial` 或既有规格、价格结果。 -- Android Agent 仅在既有颜色遍历中，在颜色卡片子树内查找与该卡片同 `content-desc` 的 `ImageView`；禁止全局查找同名图片节点，不新增颜色点击、页面跳转或用户操作。 -- API 30 及以上设备可以在内存中取得整屏位图，并严格按图片节点边界裁剪为 JPEG（质量 85）；整屏位图用后立即回收，不落盘、不上传、不入库。低于 API 30 或截图受限时安全跳过。 -- 单张 JPEG 最大 512 KiB、最长边不超过 1024 像素；Agent 单任务最多保留 64 张、总量最多 8 MiB。结果提交成功后才逐张独立上传，上传不重试到影响任务时长。 -- 服务端只接受该任务已提交颜色维度中的 JPEG，校验 Device Token、任务归属、终态、内容、尺寸和数量；按“PDD 商品 + 颜色值”维护最新一张，记录来源 task、device，并沿任务关联不可变规则快照。 -- 只允许保存裁剪后的商品图片区域；裁剪结果不得包含账号、地址、订单、支付及其他个人数据。原始控件树、XML、整屏截图仍禁止保存。 -- 诊断阶段 `COLOR_IMAGE` 只记录成功及不支持、定位失败、裁剪失败、压缩失败、上传失败分类，不记录颜色文案、坐标或图片内容。 -- Agent 采集任务详情只返回并展示当前仍以该任务为 `source_task_id` 的颜色图片，按颜色分组提供缩略图、明确空态/加载失败占位和只读放大查看；同商品同颜色被后续任务覆盖后，旧任务详情不再显示该图。图片仍沿用既有受控商品裁剪文件，不新增整屏截图、原始控件树、下载、分享或编辑能力。 - - -## Admin 采集采购与采采管理导航（#142） - -- 「采集采购」固定顺序为：SYB 商品、SYB 同步记录、档口入库码、虾皮商品、PDD 商品、采集任务、采购管理。 -- 「采采管理」固定顺序为：SYB 店铺、采集规则、采购规则、设备列表、AI 规格匹配。 -- Admin 可见两个分组及全部 12 个页面；采购员可见两个分组和除采购规则、AI 规格匹配外的 10 个页面。父组只承担导航结构，不新增业务权限。 -- 分组迁移保留既有页面菜单 ID、URL、组件和 API 权限关联，删除旧的 12 个一级模块根菜单；菜单只保留“分组 → 页面”两级。 - -## 采购规则与 Agent 版本管理 - -- `purchase_rule` 保存管理员维护的采购规则；单例 `purchase_rule_setting` 指向当前规则。迁移以现有默认正式规则原字节播种首条记录。新建、批量预检、批量创建和安全重试读取当前规则；已有采购任务始终执行自身快照。 -- `priceGuard` 缺省或 `enabled=true` 时继续按参考价倍率保护：`minRatio` 为 0.1～1.0，`maxRatio` 为 1.0～3.0；旧规则未声明 `enabled` 时按启用处理。 -- 管理员可以设置 `priceGuard.enabled=false` 关闭参考价倍率保护，但必须同时配置整数分 `absoluteMaxUnitPriceCent`，范围 1～100000（¥0.01～¥1000.00），且不能混入倍率字段。服务端仍保留参考价用于预检和审计，并把新任务价格范围固化为 0～绝对上限；不存在无金额上限的采购模式。 -- Admin 保存关闭倍率保护的规则前必须二次确认，并在列表摘要和切换当前规则确认中显示绝对上限。规则编辑只影响新任务；既有任务继续使用自身规则和业务价格快照，安全的同任务重试也不得悄悄扩大原价格范围。 -- Android 始终以任务固化的 `minUnitPriceCent` / `maxUnitPriceCent` 为执行边界，在核价、订单摘要和创建订单前 fail-closed 校验；价格越界失败应回传实际观察单价供服务端保存和诊断。支付仍永久禁止。 -- Agent 采购历史必须分开显示任务原始目标规格与服务端最终映射的执行规格；映射缺失不等于目标规格缺失。本地历史缓存同时保存两组字段，自动化始终只消费执行规格。 -- “采购规则”是“采采管理”下与“采集规则”同级的管理员菜单，采购员角色没有菜单和 API 权限。 -- Agent APK 版本由管理员在设备页抽屉中上传、核对并显式设为当前。服务端从 APK Manifest 读取整数 `versionCode` 和 `versionName`，保存 SHA-256、大小、说明和创建人；APK 位于非公开目录，Admin 与设备下载均需认证。 -- Agent 只以整数 `versionCode` 判断更新。启动时静默检查一次，设置页可手动检查、显示下载进度并取消；下载完成必须校验大小和 SHA-256。设备有活动任务时禁止检查、下载和安装；安装始终交给 Android 系统确认，项目不绕过未知来源权限。 - -## Android 采购规格动作安全执行（#214） - -- 规格入口与精确规格选择统一按“重新定位唯一目标 → 执行一次无障碍点击 → 读取新页面验证”执行；不得复用旧无障碍节点，不选择相近规格，也不在多候选时默认点击第一个。 -- 无障碍点击后页面完全无变化时，只允许对解析器已确认的安全规格入口或服务端下发且唯一命中的精确规格执行一次中心手势兜底。目标必须可见、启用、边界有效，手势后仍须以规格面板强证据或精确选中证据确认结果。 -- 页面发生变化但规格面板强证据不足时，默认明确失败；#243 的同商品页安全入口恢复是限定例外：确认包/Activity 未变、商品标题非空且未变、入口来源与语义未变，无面板、关闭、数量、已选、支付、订单或页面异常信号时，重新定位入口并最多执行一次受控手势。整页普通动态节点变化不单独阻断该恢复；入口缺失或显式/嵌套入口歧义仍拒绝。商品标题一致是当前上下文约束，不宣称已从页面核验 goods_id。诊断只记录入口来源、点击结果/原因、恢复结果和面板数量/布尔等无敏感标量。原始控件树、节点文字集合和整屏截图仍不得保存或上传。 -- 规格已处于精确选中状态时不得重复点击。规格查找只在解析器唯一识别的规格面板容器内有限滚动，每次滚动后重新定位容器与目标；容器缺失、歧义、到边或验证失败均 fail-closed。 -- 中心手势兜底不得用于修改/保存地址、创建或提交订单、订单详情入口以及任何支付/付款目标；正式创建订单的一次性不可逆门禁与永久禁止支付规则不变。 -## PDD 商品反向关联与继续订单采购（#161） - -- 一个 PDD 商品可被多个虾皮商品共用。PDD 详情返回全部关联虾皮商品摘要；订单行由独立统一分页接口读取，不按虾皮商品伪造嵌套分页。 -- `scope=actionable` 固定包含 `purchase_ready`、`pdd_pending`、`pdd_collecting`、`pdd_collection_failed`、`color_mapping`；`scope=all` 才显示其他阶段。该集合由服务端维护，前端不复制。 -- 规格映射摘要使用 `specMappingStatus=complete|incomplete|not_required`、确认数和总数。`not_required` 只表示虾皮商品没有颜色或尺码维度；商品摘要不替代订单行采购资格。 -- “关联订单继续采购”只处理已有 SYB 订单；“创建备货采购”不关联 SYB 订单。两者入口和文案必须明确区分。继续采购复用既有批量预检和批量创建，价格、映射、并发、订单和不可逆门禁不变。 -- SYB 订单号、目标颜色/尺码、数量和当前采购任务状态只允许管理员与采购员读取；其他角色由服务端拒绝。查询路径不调用 AI Provider。 - -## 定时与手动蝦皮规格自动匹配（#195） - -- 系统只扫描存活且已关联 `active` PDD 商品、两边至少共享颜色或尺码角色、并且至少存在一个未确认或已失效映射的蝦皮商品。 -- 每个商品复用详情页“一键匹配颜色和尺码”的规则：保留当前仍有效的 `confirmed` 映射；唯一确定匹配和达到服务端阈值、理由非空、候选仍有效的 AI 结果直接保存为 `confirmed`；低置信度、无结果、Provider 异常或上下文漂移不猜测、不写入错误映射。 -- 定时与管理员手动执行共用全局活动槽和逐商品工作状态。单批默认最多 20 个商品；同一规格上下文与 AI 设置更新时间未变化时，已完成、低置信度或无结果商品不重复调用 AI。 -- Provider 临时失败最多尝试 3 次，间隔至少 60 分钟；输入变化后重新计算指纹并允许重新处理。运行记录只保存结构化计数和脱敏限长错误，不保存 API Key、Provider 原始响应、商品原始 JSON 或个人数据。 -- 系统定时任务迁移后默认关闭，须由管理员明确启用。该能力仅维护蝦皮与 PDD 颜色/尺码映射，不创建采购任务、PDD 订单，不触发 Agent，也不执行付款。 - -## SYB 异常采购规格 AI 解析（#198） - -- SYB 采购规格采用两阶段流程：先把货运单明细 `productSpec` 解析为目标颜色/尺码，再由 #195 把蝦皮规格匹配到 PDD 规格；两阶段不得混为同一匹配事实。 -- 定时任务只处理未人工确认且确定性解析为 `uncertain` / `failed` 的明细。每条先重跑确定性解析；空 `productSpec`、无关联蝦皮商品、无颜色/尺码候选或同一角色存在多个候选维度时不调用 AI，继续人工处理。 -- AI 只在关联蝦皮商品的封闭候选集合中返回原始颜色/尺码，并必须提供达到当前自动确认阈值的置信度和非空理由；集合外值、缺失角色、低置信度、歧义、无结果和输入漂移都不得确认。 -- `parse_status` 保留确定性解析器结论；AI 与人工确认分别记录，人工优先级最高。重复同步不得覆盖人工值；完全相同输入保留 AI 值，来源或关联变化会清除旧 AI 确认。 -- 同一输入的低置信度或无结果不重复调用 Provider；临时故障至少 60 分钟后重试，最多 3 次。任务不创建采集/采购任务、订单，不执行 Android 动作或付款。 - -## 设备身份恢复 - -- 管理员可在设备管理对未停用设备发起“重置设备身份”。此动作不删除设备记录、不改变设备 ID、能力或已绑定的待领取任务；它立即使旧 Token 无效，并只生成一次、有效期 10 分钟的恢复码。 -- 恢复码仅显示给发起操作的管理员一次，服务端只保存摘要；不得进入列表、日志、任务记录、Android 持久化或普通接口。手机操作员必须在同一安装实例的 Agent 设置中手动输入。 -- 服务端只接受同一 `installId`、未过期且尚未使用的恢复码完成重新注册，成功后签发新 Token 并使恢复码失效。过期、重复使用、installId 不符或停用均明确失败；不能通过清空数据、直接改库或“吊销 Token”恢复原任务归属。 - -- 自 #223 起，任务创建时把与冻结 SYB 目标对应的已确认商品规格映射保存为不可变的探测指导快照，但仍不得跳过首趟真机探测。探测完成后，每个角色先验证快照映射能否按既有规范化规则唯一对应当次候选，能对应时固化当次候选原文；不能对应时只对该未解决角色执行确定性匹配，仍无结果才调用 AI。已解决角色不重复交给 AI，任一最终值仍必须逐字属于当次候选；历史映射失效、规范化后歧义或角色不符时不得复用。候选完整但无法决策时提示“已采集到当前规格，但未能确定颜色或尺码映射”，不再误报候选不存在。 - -## 采购商品深链入口（#232） - -- Android 采购新任务（含探测与人工重试）打开商品时，优先使用指定 PDD 包名的 ACTION_VIEW，并设置 NEW_TASK 与 CLEAR_TASK，以清理旧任务栈后交付该任务链接。清理的是 Activity 返回历史，不是清除应用数据或强制停止进程。 -- 直接启动失败（包括无可处理 Activity）时回退既有浏览器入口；启动请求被接受后仍由执行器验证稳定商品页面，停留首页不会仅因启动成功而判定完成。 -- 清栈不用于改地址后返回、下单后回到 PDD、订单核查；采集入口继续使用既有浏览器流程，避免绕过规则中的浏览器步骤。 -- 当前通用商品页面结构验证不能独立证明页面 goods_id；解析结果携带的任务 goodsId 不是页面回读证据。首次直接深链上线仍需以实际目标商品真机核对，ADB 实验不替代 Agent 上下文验证。 -## SYB 批量采购设备偏好（#233） - -- SYB 商品页“批量创建采购任务”按当前登录用户 ID、当前浏览器来源与 API 环境记住最近一次设备选择；主动清空也记忆为不指定设备。只保存设备 ID，不保存 Token、账号凭据或订单信息。 -- 弹窗打开后先按现有在线/可选/采购能力条件加载设备，再恢复选择并以相同设备预检。记忆设备当前不可用时保留偏好并提示用户重新选择或明确清空，不静默切换设备或自动领取。 -- 预检加载中、失败或记忆设备不可用时不能提交；过期预检结果不覆盖新的设备选择。服务端原有设备及采购资格校验不变。 -- 偏好只作用于此入口，不影响采集、其他创建入口和采购重试。浏览器存储失败时仍允许手动操作；刷新或关闭再打开浏览器可恢复，清理浏览器数据或沿用现有退出登录清理存储行为后需重新选择。 - -## 客户端密钥与可编辑模块授权（#237） - -以下为提交 `71f7751` 已实现的规则；2026-09-07 本机已迁移并验证管理页面可用，2026-09-08 已随 d403f3b 完成线上迁移与部署，真实客户端密钥执行闭环尚未验证。 - -- 仅管理员创建、查看、编辑授权或停用密钥。首版不提供密钥改名、到期、轮换、恢复启用、删除或任意接口授权。 -- 模块选择复用“采集采购/采采管理”现有 12 个业务模块；分组勾选只影响当前子模块，新菜单不会自动获得授权。客户端密钥管理、系统账号权限及支付不在可授权模块中。 -- 勾选模块默认只读，至少保留一个模块。读写仅开放清单中的普通写操作；同步、采集、采购、删除、导入、重解析、匹配、回写及切换当前采购规则分别独立授权，默认关闭。没有普通写接口的模块不允许勾选读写。 -- 编辑既有密钥不会更换密钥，名称和前缀只读；移除模块同时移除其动作。取消保留原授权；失败保留输入；版本冲突要求刷新重开。停用不可编辑或恢复。 -- 保存后新请求按最新授权校验，已经通过校验的在途请求可能完成，不追溯回滚。模块授权不是行级、店铺级或租户隔离，授予读取即允许读取该模块明确接口可返回的业务范围。 -- 用户于 2026-09-07 明确接受明文风险：密钥管理及客户端接口默认兼容 HTTP/HTTPS，无需开关。HTTP 会明文传输密钥与业务数据，建议优先使用 HTTPS；兼容不改变管理员身份与模块授权边界。 -- 客户端与 Admin 登录 JWT、Agent Device Token 独立。响应排除凭据及原始载荷字段；AI 设置只返回 enabled，不开放 Provider 配置读写或连接测试。设备仅开放列表，不开放身份重置、令牌或解锁接口。 -- 执行动作复用既有业务门禁、幂等参数及状态机；客户端采购 batch-retry 沿用 Admin 原有语义，不等同于 Agent 就地 reset。授权重采购、支付复核、取消订单等未列入接口不开放；永久禁止付款。 -- 创建响应丢失时不可找回完整密钥，应核对列表并停用可能已创建的记录，再明确创建新密钥，不能盲目自动重试。完整密钥只在创建结果弹窗内存中显示，关闭或离开页面清空，不写浏览器持久存储。 - -## 打开采购规格面板后按需滚动（#238） - -- Android 0.9.60 / versionCode 73，代码 `58a6c1c` 起，规则 `openSpecPanel.swipeAfter` 保留格式校验与旧快照兼容，但不执行打开面板后的固定次数预滑动；不以“必须滑两次成功”作为进入规格探测/选择的条件。动作后的 `waitAfterMs` 仍生效。 -- 首趟规格探测和第二趟精确选择仍使用各自既有的按需横向/纵向、有界与稳定终止策略。取消预滑动不等于不探测隐藏规格，也不等于只看首屏。目标不存在、歧义、页面证据不足或必要的有界查找失败时仍明确失败。 -- 此调整覆盖所有已经安全识别打开的面板，不再仅特判 NON_SCROLLABLE_CONFIRMATION；不弱化面板验证、精确选中、地址、价格、任务租约、创建订单边界或禁止支付规则。 -- 其他动作的后置滑动沿用原行为，必需滑动失败仍返回 RULE_ACTION_FAILED。旧规则 JSON 不回写、不迁移；原任务 ID、历史 attempt、商品与规格快照不变。旧 APK 行为不变，需升级 Agent；本单未改线上规则或执行 CG68 真机采购。 - -## SYB 逐页保存与部分成功（#239） - -实现绑定 c6a962d；2026-09-08 已随 d403f3b 部署线上，未手动触发真实同步验收；#240 上游尾页超时尚未修复。每页完整明细在外部请求结束后按页事务保存；页回滚不累计明细/新增/覆盖数，已提交页保留。日期局部读取失败继续下一日期，全局数据库/进度/会话/取消故障停止。当天漂移不在一次运行内重扫；后续运行重新扫描并幂等补齐。 - -同步状态增加 `partial_success`（部分成功，15 字符，复用现有 varchar(16)，无需迁移）。有错误且 created+updated>0 为部分成功；有错误无已提交明细为 failed；完整且无错误为 succeeded（包括无符合店铺的数据）。中断仍为 interrupted，不把中断追认为成功。所有终态沿用活动槽释放规则。 - -`orderCount` 是已验证页的原始列表读取数量；`detailCount`、`created`、`updated` 为已提交明细及其新增/覆盖数量；`daysProcessed` 是完整通过的日期数，不是已尝试日期数。失败日期/页码/阶段写入现有脱敏限长 errorMessage。部分成功不刷新店铺的完整同步统计。 - -Web 唯一展示位置为“采集采购 → SYB 同步记录”：列表状态、状态筛选及详情支持部分成功，详情保留已保存数量、错误原因与重新同步补齐提示。定时任务日志只表示异步任务受理，不等于最终业务同步成功。 - - -## 商品页动态变化下的采购入口恢复（#243） - -实现 ec8b14a，Android 0.9.61/versionCode 74；已构建、未安装或真机验收。规格探测和正式采购共用入口函数，面板已打开时不新增点击；仍在同一商品上下文且安全入口存在时，一次重新定位手势恢复不再依赖整页完全静止。手势后仍未打开则报告入口无效果，不循环点击。恢复不能用于地址、创建订单、支付或未知面板，不修改面板分类器及正式下单边界。CG82/CG85 原首次点击未生效的底层原因尚待新日志和授权真机验证。 - - -## 同一颜色卡片重复选中节点（#244） - -实现 93aab6a，Android 0.9.62/versionCode 75；已构建并授权覆盖安装，真实采购效果待验收。仅在颜色维度完整精确目标已选中、但存在非目标已选候选时，识别同一卡片重复表达：卡片必须是滚动容器直接子级的可点击非滚动 android.view.ViewGroup，节点父链明确、可见启用且边界包含；其他冲突节点仅可为该卡片自身或其中的 ImageView。另一文字选项、另一张卡片、多个精确目标、目标未选中、父链/边界不明均不适用例外。额外核对内存源节点以拒绝被解析器按同名去重隐藏的跨卡片目标；不保存原始树。 - -不删除规格数字、不模糊匹配、不改变通用解析器、尺码确认、摘要兜底、入口/滚动/地址/价格/创建订单。没有非目标选中冲突时继续原判断；仅把同卡片容器/图片的重复选中表达从冲突中排除，不新增点击。 - - -## 精确规格不可用与入口恢复诊断（#245） - -实现 ca815c3，Android 0.9.63/versionCode 76；已通过单元测试并构建，未安装、未进行真实采购验收。入口恢复沿用 #243 条件，拒绝时通过 entryRecovery=rejected;reason=<固定原因码> 区分页面身份、商品上下文、面板/支付区域、数量/摘要、标题、入口来源/文案、歧义、规则别名及可用性；不放宽条件，不新增点击。 - -在规格面板识别出唯一完整精确候选且 available=false 时，立即返回既有 PURCHASE_SPEC_SAFE_TARGET_MISSING，提示目标颜色/尺码已售罄或当前不可选，未创建订单；已选中目标同样不能绕过不可用检查。只记录 dimension 和 exact_target_unavailable 固定结构证据，不记录规格原文或原始树。原有纵向与横向定位在此条件下本就停止，不能将本改动描述为修复“已识别售罄仍继续搜索”。未识别精确候选时继续既有有界搜索，不推断售罄，不替换规格；解析器、匹配规则、滚动预算、地址与下单流程不变。 - -## 改地址返回后的动态提交按钮（#248） - -实现绑定 `c80c746`，Android 0.9.66 / versionCode 79；已通过 353 项 Android 单元测试并构建，尚未安装或进行真实采购验收。 - -- 地址回读与最终提交按钮定位分开判断。旧“提交订单”“现在买，仅”“确认购买”识别继续优先；存在旧文案候选但歧义时不使用结构补充选择其中一个。地址确实缺失时保留既有有限恢复；地址及采购面板上下文已确认后，不因底部按钮文字变化而滚动规格列表。按钮缺失或不唯一使用 `PURCHASE_SUBMIT_TARGET_AMBIGUOUS` 提示按钮问题，不误报地址保存超时。 -- 结构补充只属于当前执行器中已完成地址修改后的返回流程，不能由其他页面或旧执行的地址证明启用。当前须为 PDD、地址后缀按既有规则回读唯一、地址入口唯一，并存在唯一数量输入或已选摘要；通过地址入口与该证据的最近共同祖先确定整个采购弹层，不把颜色/尺码滚动区域当成弹层。排除全屏大祖先、地址编辑、已知支付 Activity 及订单结果/支付页面，后续定位要求 Activity 与地址返回时一致。 -- 旧文案无候选时，只接受弹层底部固定区域内一个独立、可见启用、非滚动的可点击容器；不在规格滚动区内选择按钮，不取控件树末项，不使用固定屏幕点击坐标。文字与人民币金额子节点合并为一个按钮；支持如“复购价，”及非支付展示文字变化，但单独价格、多个操作按钮或支付/付款/地址/返回等非提交动作均不放行。 -- 地址返回检查、最终复核和提交共用目标定位。结构路径保留原文字节点为重新定位锚点，由已有无障碍点击重新查找其可点击父级；不新增下单手势兜底。最终复核成功后才允许该结构路径提交；提交前再次检查路径、类别、文字与边界，发生变化即停止；复核失败清除本地结构提交锚点。 -- 既有规格、数量、价格和地址复核，任务租约、服务端/本地不可逆边界及单次提交规则不变。结构识别不支持支付，不增加采购员操作、配置或审批；不改变 Admin、接口、数据库、规则 JSON、通用解析器及滑动执行器。原始控件树、整屏截图、地址全文和凭据不得落盘或上传。 - -## 临时采集连续模式（#250） - -当前实现绑定 `37e8b56`，Agent 0.9.72 / versionCode 85。2026-09-09 用户批准 v5：按配置次数返回后切回 Agent，替代此前“识别并停留 PDD 首页”的方案；不保证 PDD 最终停在首页。代码、376 项 Android 单测及 Debug 构建通过，新版设置与完整真机闭环待验收。 - -- 连续采集默认关闭，本机即时保存，失败恢复原值；开启后显示返回次数选择，1～5 次、默认 3，取消不改，写入失败恢复旧值。任务忙碌时开关和次数均禁用，选择提交时再次检查；无新增权限。只用于本次人工新建普通临时采集（source=agent_current_page、attemptNumber=1、无替换来源），Admin 下发、重试、替代与采购不参与。 -- 单任务执行开始固定返回次数。完整 completed、服务端提交确认且既有图片上传流程结束后，执行有限 Back，每次后等待 500ms；不要求识别商品/搜索/相机/首页，也不要求画面发生变化。图片上传仍沿用既有非致命行为，不因收尾更改结果。 -- 每次 Back 前检查前台仍为 PDD，读取页面后再次检查；离开 PDD 则停止余下 Back。次数完成、离开 PDD 或 Back 动作失败后，尝试打开 Agent 保持原 Tab，等待 500ms 并验证前台包名。动作失败不重试，不把请求启动成功直接当作切回成功。 -- 沿用风险页安全边界：登录/验证码/风控、地址编辑、订单详情或支付等证据时保留现场，不发送 Back 或强行切回；Activity 缺失、读取异常明确停止。以上例外不引入首页门禁。 -- 导航在原任务互斥和唤醒锁内完成，不变更租约/调度。返回失败只显示人工处理提示，不把成功采集改为失败或自动重采。 -- 失败、部分成功、提交未确认保留现场，不运行返回步骤，也不触发旧空闲返回倒计时。关闭开关保持原流程，采集间隔不变。 -- 不自动拍照、搜索或创建下一任务，不涉及采购/订单/付款；不使用深链、浏览器、OCR/VLM 或坐标兜底。 - -## SYB 存疑规格候选核对（#251） - -实现绑定 `64b4205`，基线 main `fdd26af`；2026-09-09 代码与本地测试/构建通过，未部署、未重跑生产历史数据。 - -- 原 Parse 的成功与失败行为不变，仅 uncertain 明细增加既有蝦皮规格候选核对。比较完整原文，沿用【备注】清理，允许全角逗号、逗号两侧空白及连续空白归一；颜色尺码可正序或倒序，使用逗号或空白分隔，只有唯一完整组合才改为 success。返回既有候选标签，不改写标签，不删除加号、不截断体重说明、不做近似匹配。 -- 单规格只有在候选确实仅包含该角色时通过；有两个角色时不能用单值补猜另一个角色。空/损坏候选、校验不通过、同角色多维、未知有值维度、多种组合或归一化碰撞，均保留原结果。候选必须已存在，不能用本次待确认输入生成候选再自我证明。 -- 同步入库 ApplyDetail、手动 Reparse 共用；成功核对不再次合并规格，因此不新增重复维度、不覆盖已有映射。人工确认仍优先，默认 Reparse 跳过人工与 AI 已确认值；原文保留。 -- #198 批处理原本先 Reparse，所以可直接复用本优化：能确定的不用调用 AI；仍不确定的按原 AI 流程处理。没有新增调度、调用额度或同步等待，不自动开启已有任务。 -- 不取消 uncertain/failed 状态，不改变采购可信度/可采购规则，不实现一键关联 PDD。部署后新同步或显式重新解析会使用新逻辑；本次没有执行生产批量更新。 - - -## 蝦皮详情匹配等待与回读（#254） - -实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。 - -- AI 设置中的 timeoutSeconds=T 仍是单次 Provider 请求的上限。详情一键匹配的整次预算为 2T+10 秒，浏览器 POST 等待上限为 2T+20 秒；例如 T=60 时130/140秒，T=180时370/380秒。只保留现有一个 AI 设置入口，不新增时间配置框，也不自动改变管理员已保存的 T。 -- 超时上限不是固定等待。颜色/尺码串行执行且共用整次预算；正常部分匹配仍按原事务保存合格结果，AI异常在保存前返回时不提交本轮新映射。既有置信度、候选、人工确认映射保护和采购资格不变。 -- 前端超时、关闭或切换详情不代表后端已取消、未保存或已回滚；必须以回读结果为准，无法回读显示结果未确认，不自动重复匹配、不自动创建采购。 -- 单商品详情的成功/失败/超时/关闭重开都必须结束失效的等待状态；旧请求不得覆盖新商品或新操作。匹配进行期间本抽屉不能人工改映射，已有未保存草稿仍按原确认流程处理。 -- UI匹配提示的等待上限仅指POST，不含提交前GET及结果核对GET；结果核对也有限时，不能让失败提示再次陷入无限转圈。 - - -## SYB 行内一键关联最近采集（#253） - -实现绑定 `b1594dc`，2026-09-10；分支 feat/253-one-click-link，包含 #254 依赖。已完成合成数据测试及构建，未合并 main、未部署，不代表当前线上已具备此能力。 - -- 未关联 PDD 且既有处理阶段提供“去关联”的 SYB 行可用一键关联；原人工入口不删除。首次点击选择采集手机后继续当前行，后续使用记忆手机；小箭头查看/切换手机，保存只修改全行共用偏好。取消不改变偏好、不执行关联。与批量采购设备选择互不影响。 -- 以所选手机的临时采集 source=agent_current_page 为范围，从 completed、completed_partial 中按 finished_at DESC、id DESC 取最新一条；失败/待执行/执行中不参与。最新为部分成功或商品停用、无可用规格时明确停止，不回退更旧商品，不切换其他手机。离线手机允许使用已有成功结果，停用或已删除手机需要重新选择。 -- 主动作开始冻结行、蝦皮商品和设备；服务端关联事务固定来源采集任务、PDD商品与规格版本。仅未关联时自动写入，已有或被其他操作改变的关联不覆盖。关联作用于蝦皮商品，因此共用该蝦皮档案的其他 SYB 明细也受影响；切换手机不会重绑已有商品，也不会改变在途操作。 -- 先保存关联，再复用现有颜色/尺码自动匹配及保存。有效已确认映射保留；普通部分匹配保存合格结果，AI故障不提交本轮新映射，但已保存关联保留。后续可从“去匹配”或详情人工继续。failed 且无人工/AI确认时不能自动跳过人工解析；uncertain 不统一拦截，仍以原采购准备规则为准。 -- 操作完成不保证立即可采购，必须刷新现有处理阶段；缺规格、缺映射、解析需确认或其他原资格不满足时继续显示真实待处理阶段。不自动创建采购任务、不下单、不支付。 -- 请求超时/网络中断只做有限回读，不重复提交；读回失败明确结果未确认，避免无限转圈。离开页面不代表后端停止或回滚。普通用户沿用现有采购员权限，无新管理员专属开关。 - -## SYB 已关联商品的一键替换（#258） - -实现绑定 `2b01974`；部署与验收见 #258 发布证据。 - -- 复用一键关联及小箭头的位置，保留原查看 PDD 商品。PDD 待采集、采集失败、停用或缺价格的对应处理阶段可替换；采集中、已创建/运行采购、成功或结果未知不开放。服务端提交时再次检查，不能只相信按钮。 -- 复用每用户/浏览器/API环境的手机偏好；首次选择继续当前行，小箭头仅切换偏好。预览仅选所选手机最新 completed/completed_partial 临时采集，部分成功或不可用不回退旧商品。确认后固定来源任务和目标，不改用新采集；来源状态、设备、目标规格或旧关联改变时拒绝。 -- 不同商品显示一次确认，包含旧/新商品、手机和共享蝦皮档案影响；取消不写入。同商品不弹替换确认且不重写关联，只继续匹配。共享该蝦皮档案的 SYB 明细使用新关联，历史采购任务快照不改。 -- 沿用既有更换关联和有效映射检查，再复用自动匹配保存。部分匹配、AI失败或解析需人工处理时保留已保存关联，显示真实处理阶段，不保证立即可采购、不自动创建采购。 -- 网络异常只有限回读，区分目标商品、仍为原商品和其他关联，不把“已有某个关联”误报为本次替换成功；不自动重发写请求。没有新增后台作业、订单或付款操作。 - -## 辅助信息缺失的采集关联（#259） - -实现绑定 `e467706`，仅 Server；部署/验收见 #259。替代 #253/#258 中“部分完成一律拒绝”的限制，不改变 completed 原有路径。 - -- completed_partial 的 missing 必须是非空合法列表且仅包含 salesText、shopName、reviewCount，才进入辅助信息兼容检查；title、规格/价格缺失、遍历截断、SKU数量上限及未知原因仍拒绝。 -- `shopeeproduct/partial_collection.go` 核对本次 task 的维度和值、可售SKU的完整标记/规格引用/非负价格、本次颜色价格，以及当前档案可选值由本次有效SKU覆盖，不能借旧档案合并残留的规格或价格通过。真实单维度允许，不虚构另一维度；本次明确报告缺少规格仍拒绝。 -- 一键关联、替换预览及确认提交共用验证。失败沿用409 LATEST_COLLECTION_UNAVAILABLE及现有提示，不回退更早采集、不换手机。状态 completed_partial 和 missing 原样保留；辅助字段缺失仍可在任务详情查看。 -- 无接口字段、数据库迁移、Android/Web或权限变更；普通人工关联与采购/AI资格不变。不将“允许关联”视为“已匹配或已采购”。 - -## 采购单标题面板与地址就绪等待（#260、#261） - -实现绑定 #260 `3c1ffa4`（执行器回归测试 `7de4318`）、#261 `5ea07f1`，Android 0.9.74 / versionCode87，基于0.9.73。安装及真实采购验收以工单证据为准；不代表 main 的 Android 已整合这些分支。 - -- 采购仅在安全规格入口点击返回SUCCESS后，记录本次页面包名/Activity作为内存上下文；开始新执行或页面身份改变时清除。`PddScreenParser` 的新增 purchaseEntryContext 默认关闭，仅该采购执行器传入；普通解析和采集原判定保留。 -- 当前仍为同一PDD Activity、商品ID非空、没有页面风险、没有选中摘要，且唯一有标题规格滚动区、一个维度有值，同时具有关闭、数量、支付展示区域与下单操作证据时，单标题可识别为NORMAL_SCROLLABLE。只是允许进入既有精确规格探测/选择，不执行下单或付款，不全局认可UNKNOWN，不增加入口重复点击或滑动。 -- 地址入口点击原有1000ms保留；地址列表等待增加唯一修改目标要求。点击修改和保存由500ms改为1000ms，其他通用动作间隔不变，无新配置项。 -- 修改后不再只见“详细地址”文字就立即写入。最多50次、每次间隔200ms读取（不含读取耗时），检查PDD页面风险；唯一可见启用有内容的详细地址EditText，连续两次路径、边界、内容及Activity相同才继续原输入流程。始终零个/多个或不稳定时失败，不取第一个候选。 -- 输入内容生成、输入后回读、保存后退出及返回规格面板、最终复核和单次下单边界不变。新增本机脱敏诊断 addressEditorCandidates / addressEditorPolls 两个整数，与task/attempt/device/ruleHash关联；不记录地址内容、原始树或整屏截图。 -- 仅Android；无Server/Web、共享API字段、数据库迁移或权限变化。真实采购、地址写入及订单创建不作为自动安装验证，不执行付款。 - -### v2 商品入口补点与地址返回等待（#260、#261） - -2026-09-10 实现绑定 #260 `713111d`、#261 `d0a82f3`，Android 0.9.75 / versionCode88；真实采购效果以工单验收为准，非 main 合并声明。 - -- 入口恢复不再把全页面支付方式展示文案单独视为支付页。当前包名/Activity、商品标题和安全入口必须与点击前一致，入口唯一且可用；已打开面板、关闭控件、数量、选中摘要、订单操作、风险/评价页面仍拒绝恢复。支付 Activity 或明确支付、订单、地址文本继续阻止补点。仅允许既有一次重新定位后的规格入口中心手势，随后仍验证面板，不循环、不扩展到地址保存或下单。 -- 保存地址后的确认读取、必要时一次返回后的确认读取，增加最多50次、间隔200ms的有界就绪检查，页面捕获耗时另计。连续两次同一Activity满足原地址回读与确认面板条件后继续；完整信息不要求滚动区域。已明确到地址列表时保留原返回路径，不等待列表出现下单按钮；返回后增加1000ms缓冲。 -- 就绪检查不修改原地址回读和结构下单入口规则；超时后只对既有识别的面板、唯一可用滚动区域执行原有有限滚动。零/多个区域仍失败，不凭地址入口或未知底部节点授权下单。最终精确规格、数量、价格、地址与单次下单边界不变。 -- 私有采购诊断新增布尔 savedAddressMatched、savedPanelMatched；整数 savedLegacySubmitCandidates、savedAddressCards、savedAddressTargets、savedScrollCandidates、savedConfirmationPolls。只记录标量并绑定task/attempt/device/ruleHash，不保存地址、原始树或整屏图。 -- CG109 v1现场读取未达到空闲状态，不能确认原失败具体缺哪项证据；v2覆盖迟到确认节点及可观测性，不将合成测试通过冒充真机修复验收。无Server/Web/API/迁移/权限变化，不需要服务器重启。 - -## 探测到正式采购的单次面板交接（#262） - -2026-09-10 实现绑定 `2ea32fd`，Android0.9.76/code89；基于#260/#261，未声明合并main或真实采购验收通过。 - -- AgentForegroundService通过PurchaseProbeHandoff只在成功spec_probe且结束后新快照仍识别PDD规格面板时保留一次性内存交接。仅taskId/goodsId/ruleHash/deviceId、Activity、前台revision和单调时钟时间，不保留控件节点、地址或选中状态，不落盘；有效期180秒。 -- 正式阶段消费时检查同任务/商品/规则/设备、前台revision及时间，消费后即清除。失配/超时/无任务或采集任务调度/结果异常/进程重启均不能沿用；普通手动再试不会继承已消费交接。现有服务端租约、互斥和匹配等待策略不变。 -- 有交接时，执行器恢复限定的purchaseEntryContext，最多10次、间隔200ms新读取（捕获耗时另计）；连续两次相同PDD Activity且具备既有商品/面板证据才跳过openProduct。空树可有限等待，其他应用/Activity改变/页面风险立即拒绝复用。没有交接时保留原一次判断路径；不把UNKNOWN当成功，不跳过正式精确规格/数量/价格/地址或下单验证。 -- 私有诊断新增handoffPresent、productReused布尔值，reusePolls整数及reuseReason固定枚举legacy_evidence/page_problem/page_changed/handoff_ready/evidence_timeout。仍绑定task/attempt/device/ruleHash，无敏感文本。 -- 无Server/Web、共享API或数据库变化，不需重启服务器。只有合成测试验证；原CG107/108日志证实两阶段，但未记录旧版重开判断，不把上下文丢失假设宣称为唯一现场根因。 - -## PDD 订单实付价格（#306） - -实现绑定 8c01329（2026-09-18），待验收，尚未部署。人工“我的订单”回填除订单号和下单时间外，可提交唯一、合法的“实付”价格。它是订单展示总额，人民币分，独立存为 purchase_task.pdd_order_amount_cent；actual_unit_price_cent 仍是下单前观察的商品单价，二者不互相推算。 - -不判断是否付款，不改变人工支付复核状态。没看到实付、格式异常或多个不同实付值时，仅跳过金额，订单号和时间照常按原规则回填。采购员可稍后再点既有“回填”，为空金额补写；已有相同值幂等，不同值保留旧值并返回金额冲突提示，不撤销正确订单事实。只允许当前设备自己的、原有允许状态的任务；不新增 attempt 或采购动作。 - -金额仅保存 Admin；#305 订单号回写 SYB 的数据流不得使用该字段或将其映射为 cost，金额缺失/冲突不得成为订单号回写的前置条件。本单不代表 #305 已实现。Admin 现有订单详情卡片增加“实付价格”，缺失显示“尚未获取”，不新增列表列、入口或支付动作。安全点击集合及不保存原始控件树/个人信息的规则不变。 - -## PDD 订单号自动回填 SYB（#305） - -实现绑定 e89de1a（2026-09-18），代码与隔离测试已完成，真实迁移/发布/SYB写入尚未验证。以下补充 #306 的单号后续流程，不改变其金额规则。 - -正式 SYB 订单采购取得 PDD 单号（普通结果或人工遍历回填）后，在订单事实的同一个数据库事务中保存独立回填记录，后台异步写入对应 stock_id + detail_id。已人工回填相同单号也幂等确保记录存在；不重新采购，不等待支付复核。备货、演练、未取得单号或关联失效不回填；不自动扫描历史单据，历史补偿由采购管理勾选发起。 - -写前精确回读唯一目标明细：同单号且 purchasePlatform=pdd 直接成功；非空不同单号/不兼容平台标记 conflict，不覆盖。远端为空才允许一次写请求，写后回读确认才成功。未知结果不得自动重复写；重启恢复的 running 只回读，不能因租约过期盲重发。失败/unknown 可人工补偿，仍先回读，且在途租约未到期时不能再发起。 - -订单回填状态独立于采购成功、支付复核及物流 writeback_status。实付金额只存 Admin，SYB cost=0 为接口固定参数，不以金额推断付款。SYB 接口会同时更新采购状态/平台/时间，不能视作纯展示修改。 - -采购管理增加独立状态列、批量回填和详情补偿；复用既有访问权限，不增支付确认或审批。批量受理与最终成功分开展示；重试采购和回填分别筛选勾选项。远端无原子CAS，对系统外人工并发修改/超长延迟请求不能承诺绝对互斥；有冲突应人工核对，禁止强制覆盖。 -### SYB 会话类失败的有界自动重试（#330） - -实现 01510a8/08b7095（2026-09-21，已合并 main，未部署、未生产验证）。回填 worker 从缓存会话恢复客户端后调用 SYB 会话校验；会话缺失/过期、串号失效、校验网络错误等均记为 `SYB_SESSION_UNAVAILABLE`，error_message 只记录类别和“将自动重试；如持续失败请恢复登录后重试”，不含原始错误。该类失败发生在任何写入之前，最多自动重试 6 次，退避 5/10/15/30/30 分钟（约 90 分钟，大于一个整点同步周期），达上限保持 failed 等人工。会话仍只由每小时 SYB 同步刷新；回填不登录、不 OCR、不删除或写入会话。其他失败码仍不自动重试。退避期内可手工重新回填，手工提交重置尝试次数。历史失败记录不会被自动领取。 - -## Agent 回填订单入口兼容（#307） - -- 打开我的订单后最多采样8次，每次间隔1秒，连续两次订单导航结构一致才继续；登录/风控仍立即停止，超时给出明确原因。 -- 保留全部标签selected=true的原路径。PDD不提供selected属性时，要求订单标题、唯一全部标签以及同排至少两个订单状态标签；仅该安全导航标签允许一次中心手势，不扩大到订单卡片、地址、支付或其他操作。 -- 本轮主动点击全部后复核订单导航结构；本轮上下文不能跨扫描复用，出现其他已选中订单状态时停止。卡片识别与支付禁令保持不变。 -- 回填结束/失败通过现有通知与Toast显示脱敏原因；详细结果仍在Agent采购页。本变更不调整服务端回填接口、采集或采购流程。 - -## 下单后待付款核单与应付金额（#325） - -实现分支 fix/325-order-result，2026-09-19；未部署、未真机验收。下单点击及不可逆边界不改。已知 PayActivity 允许一次原有 Back，随后从3次放宽为25次200ms采样（约5秒等待，不含页面捕获耗时），持续无证据仍为 PURCHASE_ORDER_PAYMENT_REPEATED。微信恢复、系统选择器、空窗口和陌生应用的既有边界保留。 - -过渡阶段最多60次采样。首次识别到待付款证据后单独分配30次采样预算，不被之前绕路消耗，不因文字反复出现重置；核单总采样上限90次。缺少唯一订单号或时间时立即向上滑动读取下方内容，最多4次、手势400ms、每次后等500ms；读全立即停止，已有完整字段不滑动。该待付款读取分支不点击任何控件，也不点击付款。纯支付页不使用该滑动分支；出现可读待付款证据优先于复用的 Activity 名称。按采样间隔约18秒加有限手势/额外等待，实际耗时还含capture等调用；未改变2分钟任务租约或5分钟唤醒锁，也不宣称新增了执行器总体墙钟超时机制。 - -应付金额从同一订单的可见标签集合中读取，兼容“应付:,13元”等标点；不跨无关联节点拼接，不读拼单价、优惠或实付。父子重复同金额去重，多值/缺失/无效/溢出省略，不因金额失败丢弃订单号与时间。仅存Admin，不推断支付、不改SYB金额、不修改地址行为。历史回填及界面语义未在本单统一，详见API契约#325补充。 - -## 采购订单资料完整性及简化单号回填（#326） - -用户2026-09-19确认内部系统简化流程，原型v1通过。实现3a2472d，尚未发布或真实SYB验收。 - -采购任务保存 PDD 订单号、下单时间和订单金额即为资料完整，不检查是否已付款；金额0元有效。复用 pddOrderNo/orderSubmittedAt/pddOrderAmountCent，金额以人民币分存储。order_created 不改义，仍是已创建订单事实；缺金额展示“订单信息待补全”，不能当作采购失败再次下单。页面统一称“订单金额”，其来源可能是#325应付或既有回填实付，不能将历史值统一称已付金额。 - -Admin 复用未知结果处理弹窗增加金额输入，并为 live 已创建且缺资料任务提供“补全订单信息”；已有字段只读、缺项可填。保存中禁用提交，失败保留输入；沿用既有权限，不增加审批。非执行中的未知结果人工确认与已有订单资料补全都会事务内保证单号回填记录，不修改支付复核或触发设备操作。 - -SYB 回填与资料完整性独立：正式SYB任务已有单号且仍关联有效明细即可入队，不要求 order_created 状态、时间、金额、付款确认或地址后缀。只有订单号上传SYB；沿用同号成功、异号冲突不覆盖及既有在途防重复规则，不倒扫历史任务。历史补偿仍手动勾选，已成功或在途任务不可重复发起。 - -自动下单读取和Admin补录是后续目标来源；本单尚未删除插件或Agent我的订单回填，不能宣称上游地址后缀已取消或历史错误归属已修复。金额缺失不得自动采购，订单号唯一归属保护和永久不付款规则不变。 - -## 采购管理已回填 SYB 筛选（#327） - -实现368f2c2，2026-09-19，尚未发布。采购管理现有“状态”下拉框增加“已回填 SYB”，用户选择后点击原查询按钮，按PDD单号回填队列成功记录筛选；不是新的采购任务状态，也不表示物流回填成功或已付款。 - -筛选后仍展示原采购状态与独立SYB单号回填状态，已成功任务不因查询而允许重复回填。清空或重置恢复原列表，查询回到第一页，其他条件继续叠加。沿用既有下拉框、空/加载/失败状态及权限，不新增页面、审批、数据字段或外部动作。 - -## 规格面板识别与选项去重（#331/#332） - -实现 `0edc78a`（#332）、`d8382e6`（#331），2026-09-22 已合并 main 并发布 Server（Android 0.9.60 仅安装到设备 8）；真机采购效果未验证。 - -- 规格面板识别在原有判定之后新增回退类型 `REQUIRED_EVIDENCE`：**必须**同时存在收货地址入口（打码手机号所在可点击行）、支付方式修改入口（支付别名所在可点击行）和唯一可用的数量输入框，三者须位于同一规格面板容器内；另需至少一项辅助证据（规格选项、已选/请选择摘要、关闭、加减数量、提交订单）。加减按钮不再是必备条件。原有已识别的面板分类不变。 -- 地址入口只判断存在与否，不读取、不记录、不上传地址内容；诊断只输出布尔值与计数。 -- 点击规格入口后、保存地址返回后，若面板仅靠回退类型识别，须连续两次采样结构一致才继续，上限 5 秒；等待期间不按返回键，超时明确失败。稳定且明显不是采购面板的页面（如地址列表）沿用原返回路径。 -- 提交订单点击保持严格并进一步收紧：必须唯一、可点击、文字匹配，且文字节点及其可点击容器尺寸非零。 -- 规格选项解析：同一选项块（外层可点击块与其内部文字）只计一个值，文字优先取外层块；不做“零差评/快要抢光”等标签清洗。选中确认失败时诊断列出该维度解析值（截断）、选中状态和目标值。 -- 缺少必备证据时，失败信息附带可读提示，例如“未找到支付入口：请确认 PDD 默认支付方式为微信支付”“未找到收货地址入口：请确认 PDD 已设置默认收货地址”“未找到购买数量输入框”。 - -### 采购手机环境前提 -执行采购的 Android 手机必须：PDD App 已登录、微信已登录、PDD 已设置默认收货地址、PDD 默认支付方式为微信支付。规格面板的地址与支付证据依赖该前提；不为支付宝等其他支付方式补充识别别名（有意决定）。条件不满足时 Agent 明确失败，不自动登录、不切换支付方式、不填写地址。 - -## 管理端售后角色（#341） - -- 管理端固定增加 `after_sales`（显示名“售后”）业务角色。售后账号拥有采购员当前权限，并额外可访问“yeeke 退货包裹”和“yeeke 同步记录”两个模块及其接口。 -- 售后角色与账号由版本化迁移幂等维护；创建初始账号时由部署环境临时提供密码，迁移不输出或持久化明文密码。已存在账号若绑定其他角色则迁移失败并要求人工处理。 -- 本角色不获得管理员专属的用户、角色、设备凭据、规则配置或 AI Provider 管理权限，也不新增支付能力。 diff --git a/docs/13-deployment-and-operations.md b/docs/13-deployment-and-operations.md index 16457c1..1e4c7f7 100644 --- a/docs/13-deployment-and-operations.md +++ b/docs/13-deployment-and-operations.md @@ -2,168 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.- -wiki_revision: 1195a0fab799c064c7e279443dd57977da63c94b -synchronized_at: 2026-09-27T02:47:34Z +wiki_revision: e007549478c6a45a540bff7ef13bf3990cfa7e29 +synchronized_at: 2026-09-27T03:35:42Z - -generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) -wiki_page: Deployment-and-Operations -wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-and-Operations.- -wiki_revision: cc642ebfa65f429100779e40560a59174ab877a0 -synchronized_at: 2026-09-22T02:56:36Z - -# 部署与运维 - -## 当前线上拓扑 - -- 外部入口：`http://185.216.248.75:9527`，Nginx 同时承载 Admin 静态资源并反向代理 GoAuto API。 -- GoAuto 服务监听：`127.0.0.1:8010`。 -- 常驻服务：systemd `goauto.service`。 -- 工作目录：`/home/goauto/current`，指向 `/home/goauto/releases/<发布标识>`。 -- 服务配置：`/home/goauto/current/config/settings.yml`；敏感环境变量由 `/etc/goauto/goauto.env` 提供，不写入 Git、Wiki、工单或日志。 -- Agent APK 私有目录：相对工作目录的 `var/goauto-agent-releases`；下载必须通过已认证接口。 - -## Agent HTTP 例外 - -服务端生产模式默认要求 Agent 使用 HTTPS。当前线上入口只有 HTTP，因此经 #181 用户明确确认，在 `/etc/goauto/goauto.env` 设置： - -```text -GOAUTO_ALLOW_INSECURE_AGENT_HTTP=true -``` - -该开关只放宽全部 `/api/agent/v1/**`，包括注册、心跳、采集、采购、Agent 版本检查与下载；不放宽 Admin、PDD、SYB、OCR 或其他第三方地址的安全约束。HTTP 会明文传输 Device Token、任务内容、设备状态和执行结果。后续启用 HTTPS 后应删除该变量或设为 `false`。 - -`GOAUTO_TRUST_FORWARDED_PROTO=true` 只表示信任受控反向代理传入的 `X-Forwarded-Proto: https`，不能把实际 HTTP 请求视为加密链路，也不能替代上述显式 HTTP 开关。 - -## 发布与验证 - -1. 在本地完成服务端测试/构建和 Android 单测/APK 构建，记录提交、versionCode、SHA-256 与大小。 -2. 创建新的 `/home/goauto/releases/<发布标识>`，复制服务端二进制、Web 静态资源和非敏感配置；保留旧发布目录用于回滚。 -3. 原子切换 `/home/goauto/current` 后重启 `goauto.service`，确认 `systemctl is-active goauto.service` 为 `active`，并从外部入口验证 API。 -4. 上传 APK 到 Admin Agent 版本并按需设为当前；服务端解析 Manifest，校验 versionCode 唯一性并保存 SHA-256。 -5. 真机安装前确认设备没有运行中的任务。Android 系统安装确认仍由人工完成，Agent 不静默安装。 - -发布、重启、设置当前 Agent 版本和真机安装都属于高风险操作，必须有对应工单和人工确认。不得在部署过程中执行付款、创建订单或清理生产数据。 - -### API 长请求超时约束 - -Admin 蝦皮规格 AI 匹配会同步等待外部 Provider：Provider 配置允许 3～600 秒，旧版详情复合一键匹配共享600秒总预算，旧Admin客户端等待610秒；#254未部署前仍适用，部署后详情入口改用下节动态预算。因此服务端 `settings.application.writetimeout` 必须至少为 620 秒，受版本管理的标准配置固定为 `620`；启动时低于该值必须明确失败，禁止以 2 秒等短写超时运行，否则连接会在领域错误返回前被截断并表现为代理 502。反向代理的读/发送超时也必须大于服务端窗口。 - -Provider 故障日志只允许记录调用关联 ID、操作类型、耗时、上游 HTTP 状态码或网络错误分类；不得记录 API Key、Authorization、Provider URL、模型输入、候选规格、商品原始内容或响应正文。Provider 失败时接口返回 HTTP 503 与 `AI_MATCHING_UNAVAILABLE`，供 Admin 显示安全中文提示。 - -## 回滚 - -服务异常时把 `/home/goauto/current` 切回上一已验证发布目录并重启 `goauto.service`，随后复核服务状态和 Agent 接口。不要删除当前或历史 APK/发布目录来代替回滚；数据库变化如需回退必须单独评估。 - -## 蝦皮规格自动匹配任务运维（#195） - -- 迁移 `1788290000000_shopee_spec_auto_match.go` 创建运行与工作状态表，并幂等写入 `sys_job.invoke_target=GoAutoShopeeSpecAutoMatch`。首次部署状态为关闭，迁移重跑不会覆盖管理员后来修改的 Cron、参数或启停状态。 -- 默认 Cron 为 `0 15 * * * *`（每小时第 15 分钟），默认 `batchLimit` 为 20，合法范围 1～100。上线后先保持关闭，在 Admin 蝦皮商品列表手动执行小批次并核对运行摘要和映射，再由管理员在定时任务页明确启用。 -- 定时和手动触发共享数据库唯一活动槽。看到“已有自动匹配正在运行”属于正常互斥结果；运行租约超过 30 分钟会在下次触发时安全释放并把旧运行标记失败。处理每个商品前会续租。 -- Provider 临时失败的商品至少 60 分钟后重试，最多 3 次；低置信度或无结果在输入指纹不变时不会重复调用。排错优先查看 `shopee_spec_auto_match_run` 的结构化计数与脱敏错误，以及 `shopee_spec_auto_match_work_item` 的状态、尝试次数、下次尝试时间和租约；不得输出或复制 API Key、Provider 原始响应、商品原始 JSON 或个人数据。 -- 紧急回退只需关闭系统任务并停止使用 Admin 手动入口；保留运行记录和既有已确认映射用于审计，不删除数据，也不回滚 #194。 - -## SYB 异常规格 AI 定时任务（#198） - -- 追加迁移 `1788354164329_syb_spec_ai_parse.go` 创建 AI 确认字段、`syb_spec_ai_parse_run`、`syb_spec_ai_parse_work_item`，并幂等写入 `sys_job.invoke_target=GoAutoSYBSpecAIParse`。 -- 系统任务默认关闭，默认 Cron 为每小时第 5 分钟、参数 `{"batchLimit":20}`；迁移重跑不得覆盖管理员后续修改的 Cron、参数或启停状态。建议先运行该任务，再由默认第 15 分钟的 #195 完成蝦皮到 PDD 的规格匹配。 -- 多实例通过可空唯一活动槽和租约保证全局单批运行；逐行工作项按输入指纹去重。Provider 临时失败至少 60 分钟后重试且最多 3 次，低置信度/无结果在输入不变时不重复调用。 -- 上线顺序为：备份数据库、执行追加迁移、发布服务并保持任务关闭、核验表/字段/任务种子，再由管理员决定是否启用。排错只查看运行计数、工作状态和脱敏错误，不输出 API Key、Provider 原始响应、完整 RawJSON 或订单数据。 - -## 定时任务执行历史运维（#199） - -- 发布 #199 时先备份数据库，再执行追加迁移 `1788357000000_sys_job_execution_log.go`，随后发布服务与 Web。迁移创建 `sys_job_execution_log`、登记 `GET /api/v1/sysjob/:id/execution-logs`，并只为原本绑定隐藏菜单 `JobLog` 的角色写入精确读取权限；菜单缺失时迁移明确失败，不扩大角色授权。 -- 服务启动会将上次进程遗留的 `running` 执行记录标记为 `interrupted`。该恢复依赖当前线上每个数据库只运行一个调度器实例；扩展为多调度器前必须另建工单引入实例租约，不能直接复用此判断。 -- 排错从 Admin 定时任务页单选任务后进入“日志”，按状态和开始时间查询。记录只含稳定错误码和脱敏摘要；需要定位细节时查看受控服务日志，不得把任务参数、Provider 配置/响应、密钥或业务原始数据复制进执行历史。 -- 当前没有执行历史删除接口和自动保留策略；删除定时任务不删除历史。数据库容量治理需要另建工单评估。#198 的 `GoAutoSYBSpecAIParse` 在 #199 发布和迁移后仍保持关闭，启用必须由管理员另行确认。 - -## 客户端密钥部署与验证（#237） - -实现基线 `71f7751`；2026-09-07 已按用户授权完成本机 MySQL 迁移、管理员菜单写入和 Server/Web 构建重启；管理页面 HTTP 列表与模块加载已验证。2026-09-08 经用户授权，线上已发布 Server/Web 基线 `d403f3b`，执行迁移 `1788798000000` 并重启 GoAuto/Nginx；迁移记录、两张密钥表、仅管理员菜单关联已回读。HTTP 页面与健康检查通过；未登录管理请求 HTTP 200、业务码 401。真实密钥创建及客户端业务读写闭环尚未验证。 - -- 发布前须单独授权追加迁移 `server/cmd/migrate/migration/version-local/1788798000000_client_api_key.go`，按既有迁移流程创建 client_api_key、client_api_key_audit 和“采采管理/客户端密钥”管理员菜单。前置父菜单必须存在；不应以赋予普通用户管理员角色代替迁移或权限核验。 -- 用户于 2026-09-07 明确确认默认兼容 HTTP/HTTPS、不设开关并接受明文风险；部署本版本并执行迁移后，现有 `http://185.216.248.75:9527` 可以使用客户端密钥管理及客户端 API。2026-09-08 线上部署及未登录拒绝检查已通过，真实密钥读写验收仍待进行。HTTP 会明文传输密钥和业务数据，仍建议使用 HTTPS。 -- 客户端密钥功能不依赖 GOAUTO_TRUST_FORWARDED_PROTO、X-Forwarded-Proto 或 Agent HTTP 例外。既有其他路由的协议和代理配置保持不变；不伪造协议头，不新增明文放行开关。 -- 代理、APM、应用日志均不得记录 Authorization、创建响应 secret 或原始业务载荷。应用对两类客户端密钥路由跳过旧请求/响应正文日志，使用专用元数据审计；实际代理日志脱敏仍须部署验收。 -- 请求审计 status=0 可能表示在途、进程中断或结果审计更新失败；先按请求关联号核对业务结果，不自动重试采购、采集、同步等操作。停用阻止后续认证，不保证取消已开始的业务操作。 -- 隔离验证：Server `go test ./app/goauto/clientkey ./app/goauto/clientapi ./cmd/migrate/migration/version-local`；Web `pnpm exec jest tests/unit/client-keys.spec.js --runInBand` 与 `pnpm run build:prod`。浏览器模拟入口 `/tests/fixtures/client-keys.html` 仅由本地 Vite 开发服务承载，使用内存模拟请求和无效示例密钥，不连接真实数据库，不证明线上鉴权已验收。 -- 真实部署验收须另行验证实际 HTTP/HTTPS 入口、管理员创建/编辑/停用、普通用户拒绝、读写/独立动作隔离、停用后的后续请求拒绝及日志无密钥；任何真实业务执行继续按独立授权范围进行。 - - -## Windows 本机运行目录与 #237 迁移验证（2026-09-07） - -- Supervisor 实际配置 `D:/supervisor/programs/goauto.conf`；程序仅 `goauto-admin-api` 和 `goauto-admin-ui`。从已有干净工作区 `D:/OPC/goauto-worktrees/main-runtime` 的 main 分支运行；源码运行基线 `ac3c63e`，版本化启动模板更新提交 `9a10d82`。 -- 原目录 `D:/OPC/goauto` 的用户改动保持原样；本机敏感配置继续读取 `D:/OPC/goauto/config.yaml`，不复制凭据到运行工作区或版本库。数据库 `127.0.0.1:3307/goauto`，API `http://127.0.0.1:8010`，Web `http://127.0.0.1:9527`。 -- API 命令：`pwsh.exe -NoLogo -NoProfile -File "D:/OPC/goauto-worktrees/main-runtime/scripts/start-server.ps1" -ConfigPath "D:/OPC/goauto/config.yaml" -SkipMigration`；Web 同目录 `scripts/start-web.ps1` 与相同 ConfigPath。已验证无需 ExecutionPolicy Bypass。 -- 真实迁移必须单独授权并先确认唯一待执行版本；常驻 API 加 `-SkipMigration`，日常重启不自动执行未来待审核迁移。#237 迁移 `1788798000000_client_api_key.go` 已执行，sys_migration 记录 `1788798000000`、两张密钥表及管理员菜单已回读；其他角色未新增菜单关联。任务启停状态未改。 -- 范围明确的服务控制：`D:/supervisor/supervisord.exe -c D:/supervisor/supervisord.conf ctl status goauto-admin-api goauto-admin-ui`，启动/停止/重启将 status 分别替换为 start/stop/restart。不得为了 GoAuto 重启整个 Supervisor 或其他项目。配置内容变化后需重新读取配置；本次调用 `supervisor.reloadConfig`，再对上述两个程序定向 start，已通过进程命令行核对新目录。 -- 日志：`D:/supervisor/logs/goauto-admin-api.log`、`D:/supervisor/logs/goauto-admin-ui.log`；对外分享只能保留脱敏结构摘要。迁移输出不得暴露凭据或业务原文。 -- 管理员刷新页面后可进入 `http://127.0.0.1:9527/#/client-keys/index`；菜单缓存未更新时重新登录。已验证列表空态、创建弹窗加载 12 模块及 HTTP 风险提示；未实际创建密钥，真实客户端读写及停用闭环仍待范围明确的验证。本节为 2026-09-07 本机验证记录；线上已于 2026-09-08 另行授权发布，见上节。 - - -## 蝦皮详情匹配等待与回读（#254） - -实现绑定 `9088e6b`（2026-09-10，分支 fix/254-match-loading）；已通过合成数据测试，尚未合并 main 或发布线上。 - -- 本次只完成代码构建与合成测试，未改线上配置、AI设置、常驻服务或Nginx；部署与重启需另行授权。 -- 详情匹配新窗口是后端 2T+10 秒、Web POST 2T+20 秒。当前默认API最低写超时校验仍为620秒，这是历史最低值，不保证容纳所有动态预算；发布前读取实际 AI timeoutSeconds、application.writetimeout 和生效代理配置核对。 -- 建议API写超时至少为 2T+30 秒，且仍满足原最低620秒；代理读/发送超时需留足对应窗口。T=60/180时原620秒足够容纳应用预算；T=600时至少需要1230秒API写超时及适当更长的代理窗口。不得仅设置较大的AI超时却忽略传输层更早截断。 -- 上述是发布核对要求，不是本单已修改/验证线上代理的结论。超大T带来长连接占用，不能用关闭超时来代替正确预算。新增失败回读不代表必须延长任何线上请求。 -- 必须配套发布 Server/Web；仅上新版Web连接旧Server时，因缺失派生预算会提示等待时间不可用并停止匹配。原Android不需升级。 - -## 本地 Supervisor 与局域网访问 - -本机开发/联调环境由 `D:\supervisor\programs\goauto.conf` 分别启动 GoAuto API 与 Admin Web；实例配置只负责调用项目脚本，端口读取 `D:\OPC\goauto\config.yaml`。 - -- API 由 `scripts/start-server.ps1` 启动并监听所有网卡的 `ports.server`。 -- Admin Web 由 `scripts/start-web.ps1` 启动，监听 `0.0.0.0` 的 `ports.web`，因此同一局域网设备可通过 `http://<本机局域网IP>:/` 访问。 -- 浏览器使用同源相对 API；Vite 将 `/api` 与 `/static` 代理到本机 `127.0.0.1:`，避免局域网客户端错误访问自身的 `127.0.0.1`。 -- 修改脚本或配置后，只需重启 Supervisor 的 `goauto-admin-ui`；API 未变化时无需重启 `goauto-admin-api`。若局域网仍无法连接，检查 Windows 防火墙是否允许 `ports.web` 的 TCP 入站。 - -## SYB 订单号回填 worker 部署与排错（#305） - -代码绑定 e89de1a（2026-09-18），基于 #306 的07a3817；本节是部署要求，不表示已发布或业务库已迁移。 - -1. 另行取得明确目标环境的数据库迁移、权限对账和发布授权。核对 #306 的1789800100000金额列前置；本单追加1789800200000_purchase_order_writeback.go，建立purchase_order_writeback、purchase_order_writeback_command、purchase_order_writeback_lease三表和单例行，不改任务/付款事实，不排入历史回填、不修改定时任务开关。 -2. 配套构建并发布Server/Web，沿用现有启动权限对账为管理员/采购员登记POST /api/admin/v1/purchase-tasks/syb-order-writeback。不新增角色、菜单或支付门槛。旧常驻实例使用SkipMigration时，仅重启并不能替代授权迁移。 -3. API启动后每数据库恢复一个3秒轮询的持久队列worker，独立于Admin定时任务列表；只处理已排入pending及租约过期running。正式采购结果、人工订单回填成功/同号回放会排队；历史补偿仅用户勾选发起。部署重启后已有pending会执行真实SYB写入，必须包含在发布授权范围内。 -4. 全局租约2分钟；会话恢复预算25秒，每次外部读/写20秒（只读客户端重试亦受该context限制），写前再次核验租约。崩溃恢复只回读，不盲目重写；unknown不自动重试，等租约到期再人工核对/补偿。同目标其他未确认写入先解决，不能删除记录规避保护。 -5. 排错先看采购管理的“SYB 单号回填”状态、脱敏原因、完成时间；需要结构诊断时查询记录的taskId/status/attempt_count/error_code/lease_expires_at，不输出单号、Cookie或完整原始响应。SYB会话失败应先恢复既有登录，再勾选失败任务补偿；按钮受理不等于SYB成功。conflict只核对，不强制覆盖。 -6. 不执行真实支付；实付金额只存Admin，SYB请求cost固定0。停止新版API可停止新轮询，但不保证已发送远端请求取消；回滚保留追加表和未知状态，不删除记录、不回退采购事实。迁移/多实例MySQL/真实SYB端到端仍需授权验收。 - -### #305/#306 线上发布验证（2026-09-18） - -用户授权合并main、迁移并发布线上；main已快进至7e257ca（包含#306及#305），Server/Web从该提交重新构建。此前线上RELEASE记录60c7526；新发布目录为/home/goauto/releases/20260918-7e257ca-305，current已原子切换，goauto.service重启、Nginx校验及reload成功。先前各节“未部署”是对应提交阶段记录，本节为后续发布事实。 - -- 迁移前51个版本已应用，唯一缺失为1789800100000和1789800200000；服务器内受限备份/home/goauto/backups/20260918-305/database.sql（目录0700、文件0600），不下载生产数据。执行后53版本齐全，purchase_task.pdd_order_amount_cent为nullable BIGINT，独立三表和单例租约行已建立，历史回填队列0条。 -- 启动对账已登记新POST接口及purchaser权限，管理员沿用原授权；已登录采购列表返回orderWriteback，空批次请求返回422且不入队。未执行真实订单回填或付款，不将空队列健康验证宣称为SYB端到端验收。 -- 保持sys_job原启停值不变（任务1/2为1，3/4/5为2），没有更改Cron或主动触发同步。发布前采集/采购运行数均0。 -- 原20260916目录的static/var与20260914目录互相循环，不能继续通过旧current间接链接。新release分别直接引用已确认真实存在的/home/goauto/releases/20260907-29ba16e-236/static和/home/goauto/releases/20260903-2d6d244-r1/var；不删除或改写历史资源，不修改其他站点Nginx配置。后续清理旧release前必须检查这些被引用的数据目录。 -- 公网入口http://185.216.248.75:9527首页和10项JS/CSS资源HTTP200，/api/v1/health HTTP200；未认证采购接口业务码401。二进制SHA256=4833d779843f0613455ea2b56cadff6efd88d2b96c13e00cb4423cac02e72cb7；发布后结构日志检查无panic/fatal/1146/1054。 -- 回滚代码目标保留/home/goauto/releases/20260916-03647dd，追加数据库表/列保留；该旧目录原有static/var循环是已知问题，回退不能宣称资源链自动恢复。不要删除新队列记录或恢复旧数据覆盖后续业务；停止服务亦不保证已发送远端请求取消。 - -## Chrome 订单回填扩展交付与运行（#316） - -- 扩展以 `chrome-extension/manifest.json` 为入口，不随 Server 自动部署。解压安装、授予 Admin Origin、创建或修改客户端密钥授权、真实 PDD 遍历及订单回填都必须按目标环境另行授权；发布 Server 不等于安装或启用扩展。 -- 管理员为密钥显式勾选“采购管理 → 回填（writeback）”。建议 HTTPS；若使用项目既有客户端密钥 HTTP 例外，密钥和订单事实会明文传输，风险边界不扩大到 Cookie、JWT 或 Device Token。 -- popup 关闭不停止运行；重新打开可查看持久状态。设置在运行时只读。停止会保留已确认批次并阻止后续请求；重启或超时仅以原批次 UUID 重放未确认批次。 -- 排错只查看阶段、已读、可提交、已写入、冲突、未完整扫描原因、脱敏错误码和批次状态；不得记录客户端密钥、地址全文、订单号、Cookie、原始 HTML 或真实订单载荷。没有明确列表末尾证据时只能报告未完整扫描。 - -## 采购手机准备清单（#331） - -采购员配置或更换采购用 Android 手机时逐项确认： -1. 拼多多 App 已登录； -2. 微信已登录； -3. 拼多多已设置默认收货地址； -4. 拼多多默认支付方式为微信支付； -5. GoAuto Agent 已启动，无障碍服务已开启，Admin 设备列表显示在线并已归属对应采购员账号。 - -任一项不满足时采购会明确失败并提示缺失项（如“未找到支付入口：请确认 PDD 默认支付方式为微信支付”）；Agent 不代为登录、切换支付方式或填写地址。安装新版 Agent 后需手动启动一次 App，心跳恢复后设备才显示在线。 - -## #341 售后角色与账号迁移 - -- 发布前需单独授权执行 `server/cmd/migrate/migration/version-local/1789801100000_after_sales_role.go`。迁移会创建/维护 `after_sales` 角色、复制采购员当前菜单/API 授权，并创建四个售后账号；不会重置已存在账号密码。 -- 首次创建账号时仅在当前迁移进程设置 `GOAUTO_AFTER_SALES_INITIAL_PASSWORD`，执行完成后立即清除；不得把密码写入仓库、日志、工单或 Wiki。 -- 本地和线上均执行迁移后回读角色、四个账号的角色绑定、退货接口策略及幂等结果，再按常规流程重启 GoAuto API。 diff --git a/server/app/goauto/returnmatch/handler_access_test.go b/server/app/goauto/returnmatch/handler_access_test.go new file mode 100644 index 0000000..59d1d26 --- /dev/null +++ b/server/app/goauto/returnmatch/handler_access_test.go @@ -0,0 +1,26 @@ +package returnmatch + +import ( + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" + jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth" +) + +func TestReturnMatchWriteRoles(t *testing.T) { + for _, role := range []string{"admin", "purchaser", "after_sales", "other", ""} { + t.Run(role, func(t *testing.T) { + w := httptest.NewRecorder() + c, _ := gin.CreateTestContext(w) + c.Set("JWT_PAYLOAD", jwt.MapClaims{"rolekey": role}) + want := role == "admin" || role == "purchaser" || role == "after_sales" + if got := requireCanPurchase(c); got != want { + t.Fatalf("role %q allowed=%v want %v", role, got, want) + } + if !want && w.Code != 403 { + t.Fatalf("denied role status=%d", w.Code) + } + }) + } +} diff --git a/server/cmd/migrate/migration/version-local/1789801200000_after_sales_return_match_test.go b/server/cmd/migrate/migration/version-local/1789801200000_after_sales_return_match_test.go new file mode 100644 index 0000000..a26af29 --- /dev/null +++ b/server/cmd/migrate/migration/version-local/1789801200000_after_sales_return_match_test.go @@ -0,0 +1,63 @@ +package version_local + +import ( + "testing" + + "go-admin/app/goauto/access" + migrationmodels "go-admin/cmd/migrate/migration/models" + common "go-admin/common/models" + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +func TestAfterSalesReturnMatchCatalogAndGrants(t *testing.T) { + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + if err != nil { + t.Fatal(err) + } + if err = db.AutoMigrate(&migrationmodels.SysRole{}, &afterSalesReturnMatchAPI{}, &afterSalesReturnMatchPolicy{}, &common.Migration{}); err != nil { + t.Fatal(err) + } + if err = db.Create(&migrationmodels.SysRole{RoleKey: access.RoleAfterSales}).Error; err != nil { + t.Fatal(err) + } + for _, version := range []string{"test-first", "test-repeat"} { + if err = migrateAfterSalesReturnMatch(db, version); err != nil { + t.Fatal(err) + } + } + var apis []afterSalesReturnMatchAPI + if err = db.Find(&apis).Error; err != nil { + t.Fatal(err) + } + if len(apis) != 8 { + t.Fatalf("API count=%d", len(apis)) + } + for _, api := range apis { + if api.Path == "" || api.Action == "" { + t.Fatalf("empty API path/action: id=%d", api.ID) + } + } + var count int64 + if err = db.Model(&afterSalesReturnMatchPolicy{}).Where("v0 = ?", access.RoleAfterSales).Count(&count).Error; err != nil { + t.Fatal(err) + } + if count != 8 { + t.Fatalf("policy count=%d", count) + } + // Simulate the original deployed catalogue bug, then repair and repeat. + if err = db.Model(&afterSalesReturnMatchAPI{}).Where("id > 0").Updates(map[string]any{"path": "", "action": ""}).Error; err != nil { + t.Fatal(err) + } + for _, version := range []string{"repair-first", "repair-repeat"} { + if err = migrateFixReturnMatchAPICatalog(db, version); err != nil { + t.Fatal(err) + } + } + if err = db.Model(&afterSalesReturnMatchAPI{}).Where("path = '' OR action = ''").Count(&count).Error; err != nil { + t.Fatal(err) + } + if count != 0 { + t.Fatalf("unrepaired API rows=%d", count) + } +}