<!-- gitea-wiki-mirror:start -->
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
<!-- gitea-wiki-mirror:end -->

# 常见修改指南

## 风险分级

| 等级 | 常见修改 | 处理方式 |
|---|---|---|
| 低风险 | 文档措辞、格式化、不改变行为的测试、单文件且只恢复已有明确行为的 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](https://git.ilapage.cn/OPC/goauto/issues/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 修改

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