docs: prepare Wiki-first migration (#43)

2026-08-17 11:27:09 +08:00
parent cde2a84211
commit a4ac398ca0
17 changed files with 1457 additions and 103 deletions
@@ -4,23 +4,46 @@

 | 项目 | 内容 |
 |---|---|
-| 项目名称 | GoAuto 移动采集管理平台 |
-| 一句话目标 | 管理 Android 手机并从 PDD App 采集商品与规格数据 |
-| 主要使用者 | 管理员、开发维护者 |
+| 项目名称 | GoAuto 移动采集与采购管理平台 |
+| 一句话目标 | 管理 Android 手机，采集 PDD 商品资料，并在独立高风险阶段支持创建待付款采购订单 |
+| 主要使用者 | 管理员、采购人员、开发维护者 |
 | Gitea 仓库 | `OPC/goauto` |
 | 默认分支 | `main` |
-| 当前 MVP | PDD 商品、规则、任务、Android 执行、任务详情结果 |
-| 预计规模 | 20 台 Android；每天约 100 个采集任务 |
+| 当前已实施范围 | PDD 商品 URL、采集规则、采集任务、Android 执行、任务详情结果 |
+| 后续设计范围 | PDD 正式商品档案、Shopee/SYB 商品关系、采购演练、创建待付款订单和物流回填 |
+| 预计规模 | 20 台 Android；每天约 100 个采集任务、200 个采购任务 |
+
+## 建设基线
+
+| 基线 | 来源与版本 | 许可证 / 使用方式 | GoAuto 适配 |
+|---|---|---|---|
+| DevHarness | `D:\OPC\dev_harness`，目标提交 `b1f500128d6eb100985792d4a715db8b6b5ae203` | 开发流程与文档模板 | 2026-08-17 增量升级；保留 GoAuto 专用规则并启用 Wiki-first |
+| 服务端 | `go-admin` v2.3.0 | 上游开源管理端基线；升级时复核许可证和安全公告 | 保留认证、菜单、配置和管理端基础能力，新增 GoAuto 业务模块 |
+| 管理端 | `go-admin-ui` v3.0.0，`web/package.json` 标注 MIT | Vue 管理界面基线 | 保留应用外壳与通用组件，新增 GoAuto 页面 |
+| Android | 原生 Kotlin Agent | 自研业务客户端 | 通过 HTTPS 直连服务端，不保留 Windows 桌面 Client/ADB 作为生产拓扑 |
+
+当前仓库没有记录最初采用的 DevHarness 完整提交，因此不能声称一个未经验证的旧基线。本次以现有 GoAuto 文档为旧事实，以以上目标提交为可复现的新基线。以后升级必须比较当前记录的目标提交与新的明确提交，不能笼统复制“最新版”。

 ## 交付单元

 | 目录 | 职责 | 技术栈 | 独立验证 |
 |---|---|---|---|
-| `server/` | go-admin API、任务调度、规则、设备连接、结果持久化 | Go 1.26.5、go-admin v2.3.0、关系数据库 | Go 单元与构建验证 |
+| `server/` | go-admin API、任务调度、规则、设备连接、结果持久化 | Go 1.26.5、go-admin v2.3.0、MySQL 8.4 | Go 单元与构建验证 |
 | `web/` | go-admin-ui 管理端 | Vue、go-admin-ui v3.0.0、pnpm | lint、生产构建、浏览器验收 |
 | `android/` | Portal/Agent、注册保活、任务执行和结果提交 | Kotlin 1.9.22、Android SDK 34 | Android 单元测试、APK 构建与真机验收 |
-| `prototypes/` | 服务端和 Android 交互原型 | HTML/CSS/JavaScript | 静态检查、浏览器人工验收 |
-| `docs/` | Harness Coding 和共享契约 | Markdown | 链接与结构检查 |
+| `prototypes/` | 与代码版本绑定的服务端和 Android HTML 原型 | HTML/CSS/JavaScript | 静态检查、浏览器人工验收 |
+| `docs/` | 核心 Wiki 的本地只读镜像、版本绑定分析和规则文件 | Markdown、JSON | Wiki 镜像一致性、链接、结构和差异检查 |
+
+跨端共享契约以 [Android Agent API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract) 为唯一事实来源。各交付单元可以独立构建和验证，但共享字段、状态或能力变化必须在同一工单中验证所有受影响端。
+
+## 文档事实来源
+
+- Gitea 工单保存任务过程、确认、状态、验证和验收。
+- Gitea Wiki 保存长期产品需求、架构、业务规则、开发规范、共享契约和任务归档。
+- Git `docs/` 保存核心 Wiki 的只读镜像，以及与代码版本绑定且未映射到 Wiki 的分析和规则文件。
+- QuantUX 保存外部交互原型；工单必须记录 App ID、链接和草稿/确认状态。
+- Gitea Wiki 已于 2026-08-17 完成核心页面迁移、显式映射和单向同步验证，长期文档采用 Wiki-first。
+- 固定更新顺序是修改 Wiki、读取确认、导出本地镜像、检查一致性并提交；不得直接编辑镜像后反向覆盖 Wiki。

 ## 环境与凭据

@@ -28,8 +51,11 @@
 - 每台设备使用独立 Device Token；Token 只存安全配置，不进入仓库。
 - PDD 账号密码、Cookie、验证码和用户个人数据不得进入日志。
 - 根目录 `gitea.env` 是本机工单访问配置，已被 Git 忽略。
+- 根目录 `config.yaml` 是本机数据库和端口配置，已被 Git 忽略；示例见 `config.example.yaml`。
 - `demo/` 是旧 PoC 的本地归档，已被 Git 忽略，不是新产品代码入口。

 ## 当前阶段

-当前 MVP 的 T01～T07、T09～T22 均已完成实现、验证并由用户验收。T08（只读实时屏幕）已延期且未实施，不属于当前 MVP。T17 已在一加/ColorOS 真机完成指定设备领取、空闲领取、PDD 商品详情页到达和部分结果提交验证，不包含华为兼容。T23 已完成 v2 一加真机实施验证，正在等待用户验收。T24 已完成规格面板锚定滚动、逐行蛇形颜色遍历和尺码续页实现，并以商品 `236231603269` 验证 14 色、8 尺码和 112 个 SKU，正在等待用户验收。T25 已实现商品页假售罄的一次性下拉恢复，T26 已实现未进入商品详情页时的一次性浏览器重开恢复。T27 已修复“相似商品”推荐区域污染假售罄判定和 Agent 未声明手势能力的问题，并以商品 `731370706977` 的任务 32 在一加真机验证两次下拉恢复及完整任务完成，正在等待用户验收。T28 已实现由本地 `config.yaml` 统一配置 API 与管理端启动端口，并完成非默认端口联合验证，正在等待用户验收。当前实施范围仍是采集闭环；Agent 架构允许未来增加独立采购规则的创建订单能力，但付款能力禁止进入项目。
+当前采集 MVP 的 T01～T22 已完成实现并由用户验收；T08 只读实时屏幕已延期。T23～T28 的一加真机增强、规格遍历、假售罄恢复、浏览器重开恢复和端口配置已经实现，其中部分工单仍等待用户验收。
+
+后续采购方向仍处于设计与工单阶段：#31 PDD 商品档案原型和 #32 采购闭环原型均为草稿、等待用户明确审核；#33～#42 不得在 #32 原型通过前进入采购业务代码实施。采购永不支付，真实地址修改和创建订单属于必须再次人工确认的高风险范围。
@@ -2,41 +2,101 @@

 ## 事实来源

- Gitea Epic/MVP：目标、阶段与子工单索引。
- Gitea 单元工单：需求、讨论、状态、验证和验收过程。
- `docs/`：当前架构、业务规则、运行方式和共享接口。
- Git：源码、迁移、版本绑定文档和原型。
+- Gitea Epic/MVP：长期目标、版本范围和子工单索引。
+- Gitea 单元工单：原始需求摘要、讨论、状态、方案变化、验证和验收过程。
+- Gitea Wiki：长期需求、架构、业务规则、运行方式、共享接口和任务归档。
+- Git：源码、迁移、版本绑定分析、本地原型和核心 Wiki 的只读镜像。
+- QuantUX：外部交互原型；App ID、链接和确认状态必须记录在工单。

-## 任务层级
+核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。页面删除、重命名、映射变化或事实来源反向切换必须另行确认。
+
+## 工单与设计证据双门禁
+
+正式实施前依次判断是否需要工单，以及需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。
+
+### 工单豁免
+
+只有纯显示文案同时满足以下全部条件时才可以免工单：不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局、截断和可访问性。有任何不确定时建立单元工单。
+
+### 最低设计证据
+
+| 修改类型 | 最低证据 | 正式实施门禁 |
+|---|---|---|
+| 纯显示文案且满足豁免 | 无原型 | 做最小界面检查 |
+| 现有界面小范围样式或布局 | 标注截图、低保真图或明确复用规范 | 工单确认后实施 |
+| 新组件 | 正常、空、加载、错误、禁用和权限边界说明 | 工单确认状态后实施 |
+| 新页面、独立功能、重大交互或导航 | QuantUX 或其他可审阅原型 | 用户确认文字需求、原型和覆盖范围后实施 |
+| 后端、接口、数据或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后实施 |
+| 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而非改需求 |
+
+设计证据记录链接或路径、App ID/版本、草稿/已确认/已废弃状态、确认人、确认时间和覆盖范围。页面结构、主要流程、状态、权限、异常处理或验收结果变化时必须重新确认。
+
+## 任务层级与状态

 ```text
-[Epic] Android PDD 商品采集平台
-└── [MVP] 第一阶段最小采集闭环
-    ├── 单元任务：项目骨架
-    ├── 单元任务：设备连接
-    ├── 单元任务：规则管理
-    └── 单元任务：采集任务与结果
+[Epic] 长期产品目标
+└── [MVP] 一个可交付版本
+    ├── 单元任务 #N
+    └── 单元任务 #N+1
 ```

-单元任务是唯一实施单位。创建工单不代表立即实施；前置依赖满足后才能进入进行中。
-
-## 状态
+单元任务是唯一实施单位。建立新工单不要求所有依赖已完成，但实施前必须检查真实依赖。

 ```text
 待确认 → 待实施 → 进行中 → 待验收 → 已完成
                     └→ 阻塞
 ```

+前置依赖未完成且存在实施冲突时保持待实施；已经开始后出现计划外且当前无法解除的问题才标记阻塞。
+
 ## 单元任务闭环

-1. 读取工单、项目档案、业务规则和受影响契约。
-2. 检查前置工单、分支和工作区。
-3. 严格按范围实现，不混入相邻需求。
-4. 执行对应单元测试、契约测试和必要真机验证。
-5. 更新受影响文档并把结果回写工单。
-6. 提交代码，工单保持待验收。
-7. 用户明确验收后关闭，并同步父工单。
+1. 读取工单、项目档案、业务规则、受影响目录和共享契约。
+2. 区分代码事实、用户确认规则和假设，确认目标、非目标、方案、风险、回退和验证。
+3. 检查前置工单、分支和工作区，只修改工单范围。
+4. 执行与风险相称的格式、单元、契约、集成、浏览器或真机验证。
+5. 先更新受影响的 Wiki 页面并读取确认，再导出核心 `docs/` 镜像并检查一致性；把实现、验证和未验证内容回写工单。
+6. 提交当前工单变更，创建或更新 Wiki 任务归档，工单保持待验收。
+7. 用户明确验收后更新归档状态、关闭工单，并同步 Epic/MVP 子工单索引。

-## 高风险门禁
+高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。

-数据库迁移、设备认证、并发租约、自动提交订单、权限和不可逆动作必须单独建单并等待确认。任何自动支付需求直接拒绝实施。
+## 需求记录与流转
+
+- 聊天用于分析和确认，不是长期事实来源。
+- 单元工单记录来源、提出时间、必要的关键原话或脱敏摘要、目标、非目标、方案、验收和需求变化。
+- 长期稳定的需求进入[产品需求总览](https://git.ilapage.cn/OPC/goauto/wiki/Product-Requirements-Overview)或对应主题页面；共享接口只进入[API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract)。
+- 工单不复制完整聊天，不保存 Agent 内部推理、凭据、个人数据或生产数据。
+- 完成结果进入 Wiki 任务归档；`docs/task/` 仅在用户明确要求时增量或全量导出，不是完整历史。
+
+## 自然语言快捷指令
+
+| 指令 | 执行动作 | 停止位置 |
+|---|---|---|
+| `只分析` | 只读检查并给出方案 | 等待确认，不建单、不修改 |
+| `建工单` | 根据已确认方案创建单元任务 | 工单创建后停止 |
+| `执行工单 #N` | 检查依赖，实施、测试、提交并回写证据 | 工单待验收 |
+| `建工单并做` | 依次建单和执行 | 工单待验收 |
+| `继续工单 #N` | 从首个未完成步骤继续 | 到当前停止条件 |
+| `检查工单 #N` | 只读检查范围、验收、测试和证据 | 输出报告，不自动修复 |
+| `同步文档` | 读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档 | 输出差异；不修改 Wiki、不自动提交 |
+| `导出任务归档` | 按 revision 增量导出 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 |
+| `导出全部任务归档` | 全量读取并导出全部 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 |
+| `#N 验收通过` | 记录验收、更新任务归档、同步必要镜像、同步父工单并关闭任务 | 工单已完成 |
+
+快捷指令不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收。
+
+## 效率与范围控制
+
+- 默认严格按已确认范围实施，不顺手修复相邻问题。
+- 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。
+- 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。
+- 同一任务、同一环境中已经验证的事实不重复检查；环境或关键前提变化后再验证。
+- 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。
+- 完成工单范围、必要验证、文档影响和证据回写后立即停止。
+
+## 文档影响
+
+每个单元工单至少选择一项：无长期文档影响并说明原因；更新项目档案/运行验证；更新架构；更新业务规则；更新 API 契约；更新产品需求、常见修改或故障排查。长期页面先修改 Wiki，读取确认后运行 `python dev_scripts/sync_wiki_docs.py`；不得直接修改映射镜像。
+
+启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新对应文档。
@@ -1,16 +1,32 @@
-# 常见修改
+# 常见修改指南
+
+## 风险分级
+
+| 等级 | 常见修改 | 处理方式 |
+|---|---|---|
+| 低风险 | 文档措辞、简单查询条件、局部回归 Bug | 初级维护者可在 Agent 协助下修改和验证 |
+| 中风险 | API、配置、依赖、跨模块逻辑、数据结构、新组件 | 由 Agent 实现，维护者检查差异并执行验证 |
+| 高风险 | 权限、安全、并发、迁移、地址修改、创建订单、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
+
+风险由影响范围决定，不按代码行数判断。新页面、重大交互和导航变化还必须先通过设计与原型门禁。

 ## 增加设备字段

-先检查设备表、注册响应、心跳、管理端列表和 API 文档。跨三端字段必须在同一工单修改并做契约测试。
+先检查设备表、注册响应、心跳、管理端列表和 API 文档。跨三端字段必须在同一工单修改，并运行服务端、Web、Android 和契约验证。
+
+停止条件：字段涉及设备身份、Token、吊销、在线判定或任务互斥。

 ## 修改采集字段

-依次检查规则输出、Android 结果 DTO、服务端校验、结果表和管理端详情。不能只改数据库或前端。
+依次检查规则输出、Android 结果 DTO、服务端校验、结果表和管理端详情。不能只改数据库或前端；长期字段同步更新业务规则和 API 契约。
+
+停止条件：无法确定完整与部分结果的合并语义，或会删除已有结果。

 ## 新增或修改规则

-规则创建后立即可用。编辑或删除规则不修改已有任务的 `rule_snapshot`；规则软删除后不能创建新任务，已有任务仍可执行。
+规则创建后立即可用。编辑或删除规则不修改已有任务的 `rule_snapshot`；规则软删除后不能创建新任务，已有任务仍可执行。已支持选择器、别名、等待和有限滑动优先放规则；新增通用动作或复杂算法才升级 Agent。
+
+停止条件：规则需要创建订单、支付、任意脚本、OCR/VLM 或点击不唯一候选。

 ## 增加错误码

@@ -18,8 +34,34 @@

 ## 修改任务状态

-任务状态影响数据库、领取租约、Android 本地状态和 UI 筛选，属于跨端高风险修改，必须有迁移与并发测试。
+任务状态影响数据库、领取租约、Android 本地状态和 UI 筛选，属于跨端高风险修改，必须有迁移、并发和重复提交测试。

 ## 修改任务重置

 重置只允许用于终态任务，并在一个事务中删除旧规格/SKU、清空结果与错误、恢复为 `pending`。URL、goods_id、规则和设备快照保持不变。
+
+## 修改界面
+
+1. 先判断是否只是纯显示文案；不确定时建单。
+2. 小范围布局使用标注截图或低保真图。
+3. 新组件记录正常、空、加载、错误、禁用和权限状态。
+4. 新页面或重大流程使用 QuantUX 原型，记录 App ID、草稿/确认状态和覆盖范围。
+5. 用户确认原型后才实施生产页面，并用浏览器验证主流程和异常状态。
+
+停止条件：原型未确认，或界面文字涉及支付、安全、权限、金额和不可逆操作。
+
+## 更新文档
+
+GoAuto 的长期文档采用 Wiki-first：
+
+1. 在单元工单列出受影响页面。
+2. 修改对应 Gitea Wiki 页面，不写入密码、Token、个人数据或生产数据。
+3. 通过 API 或页面回读确认正文和 revision。
+4. 运行 `python dev_scripts/sync_wiki_docs.py` 导出核心镜像。
+5. 运行 `python dev_scripts/sync_wiki_docs.py --check` 和 `git diff --check`，再审查差异。
+
+停止条件：需要删除/重命名 Wiki 页面、修改映射、改变事实来源边界，或映射镜像存在未提交修改；这些必须在工单中单独确认，不得强制覆盖。
+
+## 验收 Agent 修改
+
+至少确认：解决哪个工单目标、修改入口和调用路径、行为变化、测试结果、未验证内容、文档影响、提交哈希和回退方式。只看到“测试通过”不足以验收。
@@ -1,6 +1,33 @@
-# 第一阶段最小采集闭环
+# 产品需求总览与当前 MVP

-## 用户闭环
+## 本页用途
+
+本页统一导航 GoAuto 的长期需求、状态、工单、原型和验收入口，同时保留当前采集 MVP 的稳定范围。它不复制完整工单、原型内容或聊天记录。
+
+## 事实来源边界
+
+| 信息 | 唯一事实来源 |
+|---|---|
+| 项目目标、用户、规模和建设基线 | [项目档案](https://git.ilapage.cn/OPC/goauto/wiki/Project-Profile) |
+| 长期业务规则和安全边界 | [业务规则与术语](https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary) |
+| 单次实现范围、变化和验收 | Gitea 单元工单 |
+| Android 与服务端共享接口 | [Agent API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract) |
+| 外部原型 | QuantUX 应用和对应工单评论 |
+| 真机验证结果 | [一加真机验收](https://git.ilapage.cn/OPC/goauto/wiki/OnePlus-Real-Device-Acceptance)和对应工单 |
+
+## 长期需求索引
+
+| 需求领域 | 用户与场景 | 状态 | 工单 | 原型 / 验收入口 |
+|---|---|---|---|---|
+| PDD 商品采集闭环 | 管理员维护商品、规则和设备，由 Android 采集结构化结果 | 已交付；T23～T28 增强项部分待验收 | [Epic #1](https://git.ilapage.cn/OPC/goauto/issues/1)、[MVP #2](https://git.ilapage.cn/OPC/goauto/issues/2)、[#3～#30 索引](https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues) | [真机验收](https://git.ilapage.cn/OPC/goauto/wiki/OnePlus-Real-Device-Acceptance) |
+| PDD 正式商品档案 | 采购人员长期复用商品资料，可由采集或人工覆盖维护 | 原型草稿，待用户确认 | [#31](https://git.ilapage.cn/OPC/goauto/issues/31) | [QuantUX App `6a81db5d191a826306a7edd6`](http://124.222.27.183:8082/#/apps/6a81db5d191a826306a7edd6.html) |
+| Shopee、SYB 与 PDD 商品关系 | 从 SYB 明细提取 Shopee 商品，人工关联 PDD 商品和规格 | 待实施；受采购总体原型门禁约束 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40)、[#41](https://git.ilapage.cn/OPC/goauto/issues/41) | #32 总体流程原型；独立管理页原型待对应工单补充 |
+| PDD 采购闭环 | 采购人员派发任务，Agent 选规格、改地址并创建待付款订单，人工支付后回填物流 | 总体原型草稿，待用户确认；代码未实施 | [#32](https://git.ilapage.cn/OPC/goauto/issues/32)、[#33～#39](https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues)、[#42](https://git.ilapage.cn/OPC/goauto/issues/42) | [QuantUX App `6a827440191a826306a7eddd`](http://124.222.27.183:8082/#/apps/6a827440191a826306a7eddd.html) |
+| 开发治理与需求追溯 | 负责人和 Agent 需要可复现模板基线、双门禁和需求索引 | 本次文档升级待验收 | [#43](https://git.ilapage.cn/OPC/goauto/issues/43) | 无 UI 原型；DevHarness 目标提交见项目档案 |
+
+原型状态只有“草稿、已确认、已废弃”。#31 和 #32 当前均为草稿；用户明确回复对应原型通过后才能作为实现依据。
+
+## 当前采集 MVP 用户闭环

 1. 管理员添加一个 PDD URL。
 2. 服务端提取 `goods_id`；重复时提示商品已存在。
@@ -11,10 +38,9 @@
 7. Android 把完整、部分或失败结果写回该任务。
 8. 管理员在任务详情查看结果，必要时重置终态任务重新采集。

-## MVP 包含
+## 当前采集 MVP 包含

- PDD 商品新增、列表和 URL 编辑。
- URL 规范化、`goods_id` 提取和唯一性校验。
+- PDD 商品新增、列表和 URL 编辑；URL 规范化、`goods_id` 提取和唯一性校验。
 - 规则新增、编辑、列表和软删除；创建即生效。
 - 单商品创建任务，可指定设备或留空。
 - 设备注册、令牌、心跳、在线状态与单设备串行。
@@ -25,34 +51,37 @@
 - 终态任务重置、失败任务删除和任务详情。
 - 登录失效、验证码、风控、人机验证、控件缺失和离线错误。

-## MVP 不包含
+## 当前采集 MVP 不包含

- 顺云宝、货运单和 Shopee 商品。
- 采购、下单和支付。
+- SYB、货运单和 Shopee 商品。
+- 采购、修改地址、创建订单和支付。
 - PDD 与其他平台商品关联。
- 批量创建任务。
- 规则草稿、发布、版本历史和全局停机。
- 独立采集结果主表或独立结果页面。
- 自动重试、自动换机和离线续跑。
- 实时屏幕和管理端远程控制。
+- 批量创建任务、规则草稿/发布/版本历史、全局停机和实时屏幕。
+- 独立采集结果主表、自动重试、自动换机和离线续跑。
 - OCR/VLM、原始控件树、截图和价格历史。

+后续工单存在不代表以上能力已经进入当前采集 MVP。采购能力必须使用独立任务类型、规则权限和高风险门禁，任何阶段都不允许自动支付。
+
 ## 数据约束

 - `pdd_product.goods_id` 唯一。
- 同一 `pdd_product_id` 最多一个 `pending` 或 `running` 任务。
+- 同一 `pdd_product_id` 最多一个 `pending` 或 `running` 采集任务。
 - 一台设备最多一个 `running` 任务。
- 规则软删除后不能创建新任务，但已有任务不受影响。
+- 规则软删除后不能创建新任务，但已有任务继续使用自身快照。
 - 终态任务提交后结果冻结，除非管理员执行重置。
- 重置事务保留所有输入快照，删除全部旧结果子记录并清空结果字段。
+- 重置事务保留输入快照，删除旧结果子记录并清空结果字段。

-## 验收
+## 当前 MVP 验收

 - 一加/ColorOS 完成真实商品闭环；当前 MVP 不包含华为兼容。
 - 重复 goods_id 显示明确冲突，不产生第二条商品。
- 规则创建后可以直接选用；删除后不能创建新任务，旧任务仍可执行。
- 指定设备和未指定设备两种领取方式均正确且没有双领。
+- 规则创建后可直接选用；删除后不能创建新任务，旧任务仍可执行。
+- 指定设备和未指定设备两种领取方式正确且没有双领。
 - 同一商品不能创建第二个未完成任务。
 - 每个颜色价格正确展开到该颜色的尺码 SKU；部分结果正常展示。
 - 重置后原结果彻底清除，快照保持不变，并可重新采集。
 - 离线和各类安全页面返回明确错误且不自动重试。
+
+## 更新时机
+
+新的长期需求、状态变化、主要工单、原型或验收入口变化时更新本页。普通内部重构、小缺陷和不改变长期能力的任务只保留在工单。
@@ -37,6 +37,27 @@
 | T27 | [#29](https://git.ilapage.cn/OPC/goauto/issues/29) | 修复相似商品区域导致假售罄恢复不触发 | T25、T26 |
 | T28 | [#30](https://git.ilapage.cn/OPC/goauto/issues/30) | 启动端口统一由 config.yaml 配置 | T18 |

+## 后续商品与采购设计工单
+
+以下工单不属于当前采集 MVP。#31 和 #32 的 QuantUX 原型仍是草稿；用户明确审核通过前，不得把后续采购能力混入生产代码。
+
+| 顺序 | 工单 | 交付项 | 主要依赖 / 门禁 |
+|---|---|---|---|
+| T29 | [#31](https://git.ilapage.cn/OPC/goauto/issues/31) | PDD 商品采购档案与规格 JSON 管理 | 先行 #31 QuantUX 原型审核 |
+| T30 | [#32](https://git.ilapage.cn/OPC/goauto/issues/32) | 采购闭环数据关系与交互原型 | #31；#32 原型是全部采购代码门禁 |
+| T31 | [#33](https://git.ilapage.cn/OPC/goauto/issues/33) | 采购任务数据模型与共享 API 契约 | #31、#40、#41、#32 原型通过 |
+| T32 | [#34](https://git.ilapage.cn/OPC/goauto/issues/34) | 服务端采购任务、租约、幂等与状态机 | #33 |
+| T33 | [#35](https://git.ilapage.cn/OPC/goauto/issues/35) | Admin 采购任务与人工处理页面 | #33、#34 |
+| T34 | [#36](https://git.ilapage.cn/OPC/goauto/issues/36) | Android 地址后缀、不可逆门禁与创建订单 | #33、#34、#42；真机前再次人工确认 |
+| T35 | [#37](https://git.ilapage.cn/OPC/goauto/issues/37) | 服务端物流调度与货运宝自动回填 | 采购任务与有效订单能力 |
+| T36 | [#38](https://git.ilapage.cn/OPC/goauto/issues/38) | Android PDD 订单物流采集规则 | 采购订单关联契约 |
+| T37 | [#39](https://git.ilapage.cn/OPC/goauto/issues/39) | 采购闭环真机端到端验收 | #33～#38、#42 |
+| T38 | [#40](https://git.ilapage.cn/OPC/goauto/issues/40) | Shopee 商品档案、PDD 关联与规格映射 | #31；商品域独立于采购任务 |
+| T39 | [#41](https://git.ilapage.cn/OPC/goauto/issues/41) | SYB 货运单商品导入与 Shopee 信息提取 | #40；源数据域独立于采购任务 |
+| T40 | [#42](https://git.ilapage.cn/OPC/goauto/issues/42) | Android 采购演练规则与持久执行基线 | #33、#34；只演练，不改地址、不创建订单 |
+
+推荐依赖顺序：#31、#40、#41 完成商品域 → #33、#34 建立采购契约和服务端状态机 → #42 完成不下单演练 → #35 管理端人工处理 → #36 高风险真实订单动作 → #37、#38 物流闭环 → #39 真机总验收。
+
 ## 延期

 - [#10：只读实时屏幕](https://git.ilapage.cn/OPC/goauto/issues/10) 已关闭，未实施，不属于当前 MVP。
@@ -1,19 +1,63 @@
-# Harness Coding 文档中心
+# GoAuto 文档中心

-本文档集面向项目负责人、开发 Agent 和接手维护的程序员。建议按编号顺序阅读。
+GoAuto 使用 Gitea 工单记录任务过程，使用 Gitea Wiki 维护长期开发文档，使用 Git 保存源码、版本绑定资料和 Wiki 的本地镜像。

-| 文档 | 回答的问题 |
+## 建议阅读顺序
+
+1. [项目档案](https://git.ilapage.cn/OPC/goauto/wiki/Project-Profile)：项目目标、建设基线、交付单元和当前阶段。
+2. [产品需求总览](https://git.ilapage.cn/OPC/goauto/wiki/Product-Requirements-Overview)：长期需求状态、工单、原型和当前采集闭环。
+3. [架构与代码地图](https://git.ilapage.cn/OPC/goauto/wiki/Architecture-and-Code-Map)：请求怎样跨服务端、Web 和 Android 流动。
+4. [业务规则与术语](https://git.ilapage.cn/OPC/goauto/wiki/Business-Rules-and-Glossary)：重要状态和不能破坏的规则。
+5. [本地开发与验证](https://git.ilapage.cn/OPC/goauto/wiki/Local-Development-and-Verification)：怎样启动、测试和真机验证。
+6. [常见修改指南](https://git.ilapage.cn/OPC/goauto/wiki/Common-Changes)：常见修改入口、风险和停止条件。
+7. [故障排查](https://git.ilapage.cn/OPC/goauto/wiki/Troubleshooting)：出现错误时按什么顺序检查。
+8. [开发工作流](https://git.ilapage.cn/OPC/goauto/wiki/Development-Workflow)：完整建单、设计门禁、实施和验收流程。
+
+专题资料：
+
+- [Android Agent API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract)
+- [工单与依赖索引](https://git.ilapage.cn/OPC/goauto/wiki/Delivery-Issues)
+- [一加真机验收](https://git.ilapage.cn/OPC/goauto/wiki/OnePlus-Real-Device-Acceptance)
+- [PDD 商品详情规则迁移分析](https://git.ilapage.cn/OPC/goauto/wiki/PDD-Detail-Rule-Migration-Analysis)
+
+## 事实来源
+
+| 信息 | 唯一事实来源 |
 |---|---|
-| `00-project-profile.md` | 项目是什么、包含哪些交付单元 |
-| `01-workflow.md` | 如何从需求、工单走到验收 |
-| `02-architecture-and-code-map.md` | 请求如何跨服务端、Web 和 Android 流动 |
-| `03-business-rules-and-glossary.md` | 哪些业务与安全规则不能破坏 |
-| `04-local-development-and-verification.md` | 如何运行与验证 |
-| `05-common-changes.md` | 常见修改从哪里开始 |
-| `06-troubleshooting.md` | 失败时按什么顺序排查 |
-| `07-mvp-requirements.md` | 第一阶段必须交付什么 |
-| `08-agent-api-contract.md` | Android 与服务端的共享接口 |
-| `09-delivery-issues.md` | 一期 Epic、MVP、Task 及依赖索引 |
-| `10-real-device-acceptance.md` | 一加/ColorOS 真机闭环验收证据与待测项 |
+| 任务状态、讨论、阻塞、需求变化和验收过程 | Gitea 单元工单 |
+| 长期产品需求、架构、业务规则、开发规范、操作说明和任务归档 | Gitea Wiki |
+| 跨服务端与 Android 的共享接口 | Wiki 的 Android-Agent-API-Contract 页面 |
+| 源码、迁移、版本绑定分析、本地 HTML 原型和规则 JSON | Git 仓库 |
+| 核心长期文档的离线副本 | Git 仓库 `docs/` 中的 Wiki 只读镜像 |
+| 外部交互原型 | QuantUX 链接、App ID 和对应工单记录 |

-当前 `docs/` 由 Git 直接维护。后续启用 Gitea Wiki 镜像时，必须通过独立工单迁移，不能形成两个互相冲突的事实来源。
+本地映射 Markdown 不是编辑入口。长期文档固定顺序是：修改 Wiki → 读取确认 → 导出核心 `docs/` → 检查一致性 → 提交镜像。任务归档默认只保存在 Wiki，只有用户明确要求时才导出到 `docs/task/`。
+
+## 五分钟检查
+
+```powershell
+git status --short --branch
+python dev_scripts/sync_wiki_docs.py --check
+python -m unittest discover -s tests -v
+.\scripts\verify.ps1 -Component all
+```
+
+预期结果是工作区范围明确、所有 Wiki 映射一致、Wiki 工具单元测试通过，并且受影响的三端验证通过。具体环境、分组件命令和真机范围见[本地开发与验证](https://git.ilapage.cn/OPC/goauto/wiki/Local-Development-and-Verification)。
+
+## 同步与归档
+
+```powershell
+# 从 Wiki 单向导出核心文档
+python dev_scripts/sync_wiki_docs.py
+
+# 只检查一致性
+python dev_scripts/sync_wiki_docs.py --check
+
+# 创建 Wiki 任务归档草稿，不自动导出本地
+python dev_scripts/new_task_archive.py 43 "升级 DevHarness 文档基线"
+
+# 仅在用户明确要求时导出任务归档
+python dev_scripts/export_task_archives.py
+```
+
+凭据只通过 `GITEA_TOKEN` 环境变量提供，不写入配置、日志、工单、Wiki 或文档。
@@ -0,0 +1,42 @@
+# <工单号> <标题>
+
+- 类型：需求 / 缺陷 / 重构
+- 所属 Epic：#
+- 所属 MVP / 版本：#
+- 状态：待验收 / 已完成
+- 日期：YYYY-MM-DD
+- Gitea 工单：<链接>
+- Wiki 页面：<页面名>
+- Wiki revision：见本地镜像头
+
+## 背景与目标
+
+<!-- 原来有什么问题，这次达到什么结果。 -->
+
+## 最终方案
+
+<!-- 说明实际实现。与建单方案不同之处必须写清原因。 -->
+
+## 修改文件
+
+- `<文件>`：<改动说明>
+
+## 验收结果
+
+| 验收标准 | 结果 |
+|---|---|
+|  | 通过 / 未通过 |
+
+## 测试
+
+- 执行命令：`<命令>`
+- 结果：
+- **未验证部分**：<!-- 必填；没有就写“无”。 -->
+
+## 遗留问题
+
+<!-- 没有就删除本节。 -->
+
+## 相关提交
+
+- `<提交哈希>` <提交说明>