68 lines
3.6 KiB
Markdown
68 lines
3.6 KiB
Markdown
# 常见修改指南
|
||
|
||
## 风险分级
|
||
|
||
| 等级 | 常见修改 | 处理方式 |
|
||
|---|---|---|
|
||
| 低风险 | 文档措辞、简单查询条件、局部回归 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 修改
|
||
|
||
至少确认：解决哪个工单目标、修改入口和调用路径、行为变化、测试结果、未验证内容、文档影响、提交哈希和回退方式。只看到“测试通过”不足以验收。
|