goauto/docs/05-common-changes.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Common-Changes wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Common-Changes.- wiki_revision: 03ea269058b50fea2be7842b9c284018987c82d9 synchronized_at: 2026-09-21T08:14:50Z

常见修改指南

风险分级

等级	常见修改	处理方式
低风险	文档措辞、格式化、不改变行为的测试、单文件且只恢复已有明确行为的 Bug	范围明确、容易回退且不触及强制建单项时可直接提交；有疑问就建单
中风险	API、配置、依赖、跨模块逻辑、数据结构、新组件	由 Agent 实现，维护者检查差异并执行验证
高风险	权限、安全、并发、迁移、地址修改、创建订单、支付、删除数据、不可逆操作	停止修改，由 Agent 分析并等待人工确认

风险由影响范围决定，不按代码行数判断。新页面、重大交互和导航变化还必须先通过设计与原型门禁。

增加设备字段

先检查设备表、注册响应、心跳、管理端列表和 API 文档。跨三端字段必须在同一工单修改，并运行服务端、Web、Android 和契约验证。

停止条件：字段涉及设备身份、Token、吊销、在线判定或任务互斥。

修改采集字段

依次检查规则输出、Android 结果 DTO、服务端校验、结果表和管理端详情。不能只改数据库或前端；长期字段同步更新业务规则和 API 契约。

停止条件：无法确定完整与部分结果的合并语义，或会删除已有结果。

新增或修改规则

规则创建后立即可用。编辑或删除规则不修改已有任务的 rule_snapshot；规则软删除后不能创建新任务，已有任务仍可执行。已支持选择器、别名、等待和有限滑动优先放规则；新增通用动作或复杂算法才升级 Agent。

停止条件：规则需要创建订单、支付、任意脚本、OCR/VLM 或点击不唯一候选。

新增数据库模型或字段

[必须] 两步都要做，缺一不可：

1. 把模型加进 server/app/goauto/models/schema.go，并登记到 migrations.MigratedModels()；
2. 在 server/cmd/migrate/migration/version-local/ 下新建一个版本文件（时间戳递增，照抄同目录已有文件的写法）。

只做第 1 步对全新数据库有效，对已有数据库无效：旧版本号已经记在 sys_migration 里，Migrate() 不会再次执行，表就是不会出现。而单元测试每次都用全新数据库，所以照样全绿——这个缺口只会在真实环境里暴露成一句 Error 1146: Table ... doesn't exist（见 #48）。

[必须] 模型必须显式声明 TableName() 返回单数表名。漏写时 gorm 会静默使用复数，迁移照样成功。

迁移命令跑完会调用 migrations.VerifyTables 核对所有表是否都在，缺表时直接以非零码退出并报出表名。

停止条件：修改或删除已有列、需要数据回填、涉及唯一键语义变化。

增加错误码

错误码必须包含稳定代码、用户可读消息、是否可重试和建议处理。同步更新 Android、服务端、管理端和 docs/08-agent-api-contract.md。

修改任务状态

任务状态影响数据库、领取租约、Android 本地状态和 UI 筛选，属于跨端高风险修改，必须有迁移、并发和重复提交测试。

修改任务重置

重置只允许用于终态任务，并在一个事务中删除旧规格/SKU、清空结果与错误、恢复为 pending。URL、goods_id、规则和设备快照保持不变。

修改界面

1. 先判断是否只是纯显示文案；不确定时建单。
2. 小范围布局使用标注截图或低保真图。
3. 新组件记录正常、空、加载、错误、禁用和权限状态。
4. 新页面或重大流程使用 QuantUX 或其他可审阅原型，记录可访问链接、App ID、版本/revision 或确认日期、审核版本识别方式、草稿/确认状态和覆盖范围。
5. 完整原型默认在线审核；只有用户明确要求或项目规则要求时才导出版本化本地 HTML，且不得覆盖已确认快照。
6. 用户确认原型后才实施生产页面，并用浏览器验证主流程和异常状态。

停止条件：原型未确认，或界面文字涉及支付、安全、权限、金额和不可逆操作。

更新文档

GoAuto 的长期文档采用 Wiki-first，但同步由长期事实变化触发，不由任务完成触发。无长期影响时只在工单说明原因并跳过本节；有影响时只执行一轮：

1. 在单元工单列出受影响页面。
2. 修改对应 Gitea Wiki 页面，不写入密码、Token、个人数据或生产数据。
3. 通过 API 或页面回读确认正文和 revision。
4. 运行 python dev_scripts/harness.py sync 导出核心镜像。
5. 运行 python dev_scripts/harness.py sync --check 和 git diff --check，再审查差异。

完成第 5 步后，本任务的文档闭环结束；验收时内容未变化不重复同步。标准任务不创建 Wiki 任务归档；既有 archive / export 只在用户明确要求专项历史快照时使用。

部署命令或常驻服务运维方式变化时，更新项目自己的 Deployment-and-Operations Wiki 页面；可从 Deployment-Template 复制章节结构，但必须按已验证的 GoAuto 环境改写，不得保留占位生产参数。当前真实部署拓扑未确认时，在工单记录限制，不创建虚假的部署说明。

停止条件：需要删除/重命名 Wiki 页面、修改映射、改变事实来源边界，或映射镜像存在未提交修改；这些必须在工单中单独确认，不得强制覆盖。

验收 Agent 修改

至少确认：解决哪个工单目标、修改入口和调用路径、行为变化、测试结果、未验证内容、文档影响、提交哈希和回退方式。只看到“测试通过”不足以验收。