OPC/goauto
2
0
Fork 0
Code Issues 206 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
634bd467299cc0d6e941dc4e75cb949cddd4a910
goauto/docs/04-local-development-and-verification.md
T

8.5 KiB
Raw Blame History

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: 2075bb8a28fa01dcdbbcf105f12a29afc9b2e6f3 synchronized_at: 2026-08-24T02:59:16Z

本地开发与验证

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

.\scripts\verify.ps1 -Component all

Component 也可以是 server、web 或 android。

通用检查

git status --short --branch
git diff --check

服务端验证

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、日志、工单或文档。

如需启用 AI 规格匹配，管理员在“AI 规格匹配”页面配置单一 OpenAI-compatible Provider 的 Base URL、模型、超时和 API Key；超时默认 15 秒，可设置为 3～600 秒。根据 #62 已确认的内部部署例外，API Key 明文保存在专用设置表，并只在管理员设置页面回显，不能出现在代码、日志、工单、Wiki、任务快照、采购员接口或 Android 接口。Base URL 支持公网或内网的 HTTP/HTTPS 地址，不作局域网限制；HTTP 不加密传输中的 API Key，生产环境建议 HTTPS。

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

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

.\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 默认欢迎页属于正常现象。

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

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

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

AI 规格匹配的隔离验证：

Set-Location server
go test ./app/goauto/aimatching ./app/goauto/purchase

该测试覆盖确定性标准化、歧义拒绝、Provider 回退的候选原文校验、内部 API Key 的管理员读取/采购员隔离以及 HTTP/HTTPS Base URL 校验；不会调用真实 Provider 或创建订单。

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

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 验证

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

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

Android 验证

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 台设备连接稳定性。

cmautobuy 商品导入

从 server/ 运行 #70 独立命令。两个配置文件都必须是未被 Git 跟踪的本地文件；密码不接受命令行参数。

# 默认只读预检，不写两个数据库
go run ./cmd/import-cmautobuy-products --source-config "D:\chengma\cmautobuy\admin\config.yaml" --target-config "D:\OPC\goauto\config.yaml"

# 仅在检查 dry-run 精确数量、备份目标商品表并再次人工确认后运行
go run ./cmd/import-cmautobuy-products --source-config "D:\chengma\cmautobuy\admin\config.yaml" --target-config "D:\OPC\goauto\config.yaml" --apply

也可分别用 GOAUTO_CMAUTOBUY_CONFIG 和 GOAUTO_CONFIG 指定路径。来源配置支持 disabled 或 verify_ca；相对 CA 路径按来源配置文件目录解析。导入报告不得包含 DSN、密码或原始业务响应。

MySQL 8.4 写入路径的隔离测试只允许连接名称以 _test 结尾的数据库：

$env:GOAUTO_IMPORT_MYSQL_TEST_DSN="<仅由安全环境注入的 _test DSN>"
go test ./app/goauto/cmautobuyimport -run TestRunMySQL84DryRunAndApply -count=1
Remove-Item Env:GOAUTO_IMPORT_MYSQL_TEST_DSN

Windows Supervisor 托管

本机安装的 Go Supervisor 位于 D:\supervisor。GoAuto 的版本化配置源为 scripts/supervisor/goauto.conf，运行副本为 D:\supervisor\programs\goauto.conf。两个实例都读取仓库根目录已忽略的 config.yaml，Supervisor 配置不得保存数据库密码：

  • goauto-admin-api：调用 scripts/start-server.ps1，执行迁移后启动 Admin API。
  • goauto-admin-ui：调用 scripts/start-web.ps1，先等待 ports.server 对应的 /api/v1/health 返回 200，再启动 Admin UI；脚本会解析 Node.js 并直接运行项目的 Vite CLI，避免 Supervisor 子进程缺少 Node PATH。API 在 60 秒内未就绪时，脚本明确失败并由 Supervisor 按重启策略处理。
  • 日志：D:\supervisor\logs\goauto-admin-api.log、D:\supervisor\logs\goauto-admin-ui.log。
  • Supervisor 管理界面：http://127.0.0.1:9009。

部署或修改配置后执行：

Copy-Item -LiteralPath .\scripts\supervisor\goauto.conf -Destination D:\supervisor\programs\goauto.conf
D:\supervisor\supervisord.exe /c D:\supervisor\supervisord.conf ctl reload
D:\supervisor\supervisord.exe /c D:\supervisor\supervisord.conf ctl status

单独控制实例：

D:\supervisor\supervisord.exe /c D:\supervisor\supervisord.conf ctl restart goauto-admin-api
D:\supervisor\supervisord.exe /c D:\supervisor\supervisord.conf ctl restart goauto-admin-ui

Supervisor 托管期间不要再运行 start-all.bat 或重复启动对应单端脚本，否则会因 8010/9527 被占用而失败。两个 GoAuto 实例同时重启时，Admin UI 会等待 API HTTP 就绪后再监听 Web 端口；SYB 商品页对一次短暂网络断开做单次有界重试，不对认证、权限或业务错误重试。

Reference in New Issue View Git Blame Copy Permalink