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: 7d96409a13ef19d91df7cd74af24d8cdab473f32 synchronized_at: 2026-08-17T03:28:08Z

常见修改指南

风险分级

等级	常见修改	处理方式
低风险	文档措辞、简单查询条件、局部回归 Bug	初级维护者可在 Agent 协助下修改和验证
中风险	API、配置、依赖、跨模块逻辑、数据结构、新组件	由 Agent 实现，维护者检查差异并执行验证
高风险	权限、安全、并发、迁移、地址修改、创建订单、支付、删除数据、不可逆操作	停止修改，由 Agent 分析并等待人工确认

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

增加设备字段

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

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

修改采集字段

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

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

新增或修改规则

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

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

增加错误码

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

修改任务状态

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

修改任务重置

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

修改界面

1. 先判断是否只是纯显示文案；不确定时建单。
2. 小范围布局使用标注截图或低保真图。
3. 新组件记录正常、空、加载、错误、禁用和权限状态。
4. 新页面或重大流程使用 QuantUX 原型，记录 App ID、草稿/确认状态和覆盖范围。
5. 用户确认原型后才实施生产页面，并用浏览器验证主流程和异常状态。

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

更新文档

GoAuto 的长期文档采用 Wiki-first：

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

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

验收 Agent 修改

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