cmroubao/README.md

# 采购自动化验证系统

本项目面向采购管理人员和采购执行人员，目标是将后台采集的商品标题、描述、图片、
数量和预算转成 Android 端可执行的采购任务，并验证 AI 辅助拼多多检索和候选商品
判断是否可靠。

第一版只验证：

```text
后台创建任务
  -> Android App 手动领取
  -> App 本地 VLM 解析图片与文字
  -> 拼多多搜索和候选比较
  -> 停在人工确认位置
  -> 回传结果、截图和失败原因
```

管理后端只负责任务控制和结果审计，不保存或代理 VLM；App 使用有限离线授权和本地
加密 outbox。MVP 不自动提交订单、不支付、不绕过验证码或平台风控。

## 目标结构

```text
cmroubao/
├── android-buyer/       # Roubao main 固定 commit 的 Android 基线
├── backend-api/         # Go-Gin API、SQLite、迁移和后续管理页面
├── docs/                # Harness Coding 项目事实和执行约束
├── AGENTS.md            # AI coding agent 权威入口
├── init.ps1             # Windows 标准构建/真机启动入口
└── init.sh              # Unix 等价构建/真机启动入口
```

管理人员使用 Web 管理端，采购人员使用 Android App；二者共享同一后端、任务数据
和权限体系。验证版已实现 ADMIN 服务端会话、BUYER 账号和预授权设备联合身份，
完整 RBAC 放到验证通过后。

后端采用 Go 1.23.0 + Gin 1.11.0，以 Go Blueprint v0.10.11 为一次性骨架参考，
已收敛出 SQLite、Goose 迁移、健康检查和可关闭的 HTTP Server；业务 API 按 Phase 2
任务逐步加入。

Android 端已核实的 Roubao 上游环境为 Kotlin 1.9.20、JDK 17、Gradle 8.2、
AGP 8.2.0、Android SDK 34，以及 Jetpack Compose Compiler 1.5.5。最低支持
Android 8.0（API 26），目标为 Android 14（API 34）。具体版本和本机环境状态见
[`docs/03-tech-stack.md`](docs/03-tech-stack.md) 与
[`docs/current-state.md`](docs/current-state.md)。

## 私有样本导入

```powershell
Set-Location android-buyer
.\gradlew.bat :tools:shopee-importer:run `
  --args="--input ../private-fixtures/shopee --output ../.local/probe-import"
.\gradlew.bat :app:assembleDebug `
  '-PprobeFixturesDir=../.local/probe-import'
```

普通 `.\init.ps1` 或不带 `-PprobeFixturesDir` 的 Debug 构建会清除先前注入的私有
fixture，默认 APK 不携带真实订单资料。

## 后端运行

在项目根目录可直接使用 Windows 启动脚本。首次运行或更新代码后有 pending migration 时，
显式传入 `--migrate`；脚本不会隐式改动数据库。

```powershell
.\start-backend.bat --migrate
```

后续启动：

```powershell
.\start-backend.bat
```

等价的手工命令如下：

```powershell
Set-Location backend-api
$env:GOTOOLCHAIN = "local"
go run ./cmd/migrate up
$env:CMROUBAO_AUTH_PASSWORD = "至少 5 个 UTF-8 字节"
go run ./cmd/authctl create-user ADMIN admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
$env:CMROUBAO_AUTH_PASSWORD = "采购员独立强密码，至少 5 个 UTF-8 字节"
go run ./cmd/authctl create-user BUYER buyer01
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
$env:CMROUBAO_AUTH_PASSWORD = "管理员新密码，至少 5 个 UTF-8 字节"
go run ./cmd/authctl reset-password admin
Remove-Item Env:CMROUBAO_AUTH_PASSWORD
go run ./cmd/authctl create-device buyer-phone-01
go run ./cmd/api
```

默认监听 `127.0.0.1:8080`，SQLite 位于被忽略的 `backend-api/var/`。另一个终端可
访问 `http://127.0.0.1:8080/healthz`。可配置项和独立验证命令见
[`backend-api/README.md`](backend-api/README.md)。

Debug App 通过 USB 连接本机后先执行
`adb reverse tcp:8080 tcp:8080`，再在“任务”页使用
`http://127.0.0.1:8080`、BUYER 账号、设备 ID 和只显示一次的设备密钥登录。
正式版后台地址只接受 HTTPS。App 每次由采购员点击“获取任务”，不会自动领单。

局域网 Debug 联调先生成本机 CA 和服务端证书，再启动服务：

```powershell
.\generate-local-tls.ps1 -IPAddress 192.168.0.224
.\start-backend.bat --migrate
adb push .\.local\cmroubao-tls\ca.crt /sdcard/Download/cmroubao-local-ca.crt
```

在手机系统设置中从下载目录安装 `cmroubao-local-ca.crt` 为 CA 证书；Debug APK 才会
信任该用户安装的 CA。App 后端地址填写 `https://192.168.0.224:8080`。证书与私钥均
位于被忽略的 `.local/`，不可提交或共享；Windows 防火墙还必须允许入站 TCP 8080。

## 文档入口

- [AI 开发入口](docs/00-ai-start-here.md)
- [项目愿景](docs/01-vision.md)
- [需求与 MVP 验收](docs/02-requirements.md)
- [技术栈](docs/03-tech-stack.md)
- [架构设计](docs/04-architecture.md)
- [API 合约](docs/api.md)
- [任务路线图](docs/06-tasks.md)
- [当前实现状态](docs/current-state.md)
- [完整文档导航](docs/README.md)

Android Phase 0/1、后端 T-201 至 T-205 和 App 接入 T-206 已完成。真实状态以
[`docs/current-state.md`](docs/current-state.md) 为准。