<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Local-Development-and-Verification.-
wiki_revision: 9fa21612e642c3d1b3edaa235b6127c876299e4e
synchronized_at: 2026-08-17T03:28:04Z
<!-- gitea-wiki-mirror:end -->

# 本地开发与验证

T01 已建立可执行的三端骨架。建议从仓库根目录运行统一脚本：

```powershell
.\scripts\verify.ps1 -Component all
```

`Component` 也可以是 `server`、`web` 或 `android`。

## 通用检查

```powershell
git status --short --branch
git diff --check
```

## 服务端验证

```powershell
Set-Location server
go test ./...
go build ./...
```

服务端固定为 go-admin v2.3.0，模块要求 Go 1.26.5；本机可由 `GOTOOLCHAIN=auto` 获取匹配工具链。对象存储用例带有 `integration` 标签，默认验证不会访问云端凭据。

默认运行目标是 MySQL。开发者在仓库根目录的 `config.yaml` 中维护本机连接参数和启动端口；该文件已被 Git 忽略，不得提交。可从不含凭据的 `config.example.yaml` 复制。启动脚本读取配置后，仅通过当前进程环境注入数据库连接、服务端端口和前端 API 地址，不把账号密码写回 `server/config/settings.yml`、日志、工单或文档。

已经执行过旧版 GoAuto 表结构的数据库，会由 `1786700300000_collection_execution.go` 增量补齐任务幂等、结果、软删除和颜色价格字段；不要通过修改已执行迁移的版本号强制重跑。

Windows 本地 MySQL 8.4 可以从仓库根目录双击或执行：

```powershell
.\start-server.bat
```

首次使用先编辑根目录 `config.yaml`：`database` 节点配置 `host`、`port`、`user`、`password` 和 `name`，`ports.server` 与 `ports.web` 配置 API 和管理端开发服务器端口。两个启动端口必须位于 1～65535 且不能相同。随后脚本直接读取该文件，创建数据库、执行迁移并启动服务，不再交互询问密码。迁移已经执行过时，可使用 `.\start-server.bat -SkipMigration`；只验证服务端配置可使用 `.\start-server.bat -ValidateConfigOnly`，只验证前端端口配置可使用 `.\start-web.bat -ValidateConfigOnly`。

管理端前端可单独双击 `start-web.bat`；也可双击 `start-all.bat` 同时打开服务端和前端两个窗口。访问地址分别为 `http://127.0.0.1:<ports.web>` 和 `http://127.0.0.1:<ports.server>`，默认仍是 9527 和 8000。前端开发 API 地址会自动跟随 `ports.server`。修改服务端端口后，还需同步修改 Android Agent 保存的服务地址。API 根路径显示 go-admin 默认欢迎页属于正常现象。

只验证最小闭环迁移和数据库约束：

```powershell
Set-Location server
go test ./app/goauto/...
```

该命令同时覆盖设备注册的首次签发、requestId 重放、错误 Token、防接管、停用/吊销、HTTPS、限流、心跳任务一致性和超时离线失败测试。

如需用临时 SQLite 做隔离联调，服务端命令必须显式带上 SQLite 构建标签：

```powershell
Set-Location server
go run -tags sqlite3 . migrate -c config/settings.sqlite.yml
go run -tags sqlite3 . server -c config/settings.sqlite.yml
```

SQLite 只用于测试；正式运行和最终迁移目标仍为 MySQL 8.4。真实 MySQL 连接串继续通过 `GOAUTO_DB_DSN` 注入。

## Web 验证

```powershell
Set-Location web
pnpm install --frozen-lockfile
pnpm run lint
pnpm run build:prod
```

上游现存 lint 警告和构建体积提示不会阻断验证，但新增代码不得增加错误。

## Android 验证

```powershell
Set-Location android
.\gradlew.bat test
.\gradlew.bat assembleDebug
```

Android 骨架使用 Kotlin 1.9.22、AGP 8.2.0、Java 17 和 SDK 34。

局域网真机联调可在构建时设置 `GOAUTO_SERVER_URL`。只有 Debug 清单允许明文 HTTP；Release 的 URL 校验和 Android 网络安全策略都保持 HTTPS 约束。

## 原型验证

- 直接打开 `prototypes/server-admin.html` 和 `prototypes/android-agent.html`。
- 检查 375、768、1024、1440 像素宽度。
- 用键盘完成导航，检查明显焦点、表单标签和删除/重置确认。
- 开启 `prefers-reduced-motion` 后不应依赖动画表达状态。

## 必须真机验证的范围

- 一加/ColorOS 的无障碍绑定、后台运行和安装保护。
- 任务执行期间 Agent 只持有最长 5 分钟的屏幕唤醒锁，并在任务结束时释放；不解锁安全锁屏，也不常驻保持屏幕。
- 浏览器打开 PDD、两层确认、商品详情识别和规格遍历。
- 网络断开、登录失效、验证码、风控和规则删除后的快照执行。
- 一台设备串行任务和 20 台设备连接稳定性。