# 项目档案

## 基本信息

| 项目 | 内容 |
|---|---|
| 项目名称 | GoAuto 移动采集与采购管理平台 |
| 一句话目标 | 管理 Android 手机，采集 PDD 商品资料，并在独立高风险阶段支持创建待付款采购订单 |
| 主要使用者 | 管理员、采购人员、开发维护者 |
| Gitea 仓库 | `OPC/goauto` |
| 默认分支 | `main` |
| 当前已实施范围 | 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、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 原型 | 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。

## 环境与凭据

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

## 当前阶段

当前采集 MVP 的 T01～T22 已完成实现并由用户验收；T08 只读实时屏幕已延期。T23～T28 的一加真机增强、规格遍历、假售罄恢复、浏览器重开恢复和端口配置已经实现，其中部分工单仍等待用户验收。

后续采购方向仍处于设计与工单阶段：#31 PDD 商品档案原型和 #32 采购闭环原型均为草稿、等待用户明确审核；#33～#42 不得在 #32 原型通过前进入采购业务代码实施。采购永不支付，真实地址修改和创建订单属于必须再次人工确认的高风险范围。