diff --git a/Local-Development-and-Verification.-.md b/Local-Development-and-Verification.-.md new file mode 100644 index 0000000..69e473d --- /dev/null +++ b/Local-Development-and-Verification.-.md @@ -0,0 +1,97 @@ +# 本地开发与验证 + +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:` 和 `http://127.0.0.1:`,默认仍是 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 台设备连接稳定性。