<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Common-Changes
wiki_url: https://git.ilapage.cn/chengma/cmsp/wiki/Common-Changes.-
wiki_revision: a852c6f6430902be970468b30802282617c09f93
synchronized_at: 2026-09-02T03:57:24Z
<!-- gitea-wiki-mirror:end -->

# 常见修改

本页说明典型改动要改哪里、验证什么、属于什么风险。产品代码尚未建立，涉及 Go 与前端的条目标注为「计划」，骨架建立后按实际路径回填。

## 风险分级

风险按影响范围判断，不按代码行数判断。

| 风险 | 本项目的例子 | 处理方式 |
|---|---|---|
| 低 | 界面文案、标签、列标题、提示语；表格列宽与排序；日志措辞；文档措辞 | 可直接实施。改完自测受影响界面，报告结果 |
| 中 | 参数设置项增减；SQLite 查询条件；任务进度事件字段；下载目录与命名规则；错误码新增 | 建工单。由 Agent 实现，维护者检查差异并执行验证 |
| 高 | 淘宝登录判定、签名生成、MTOP 请求构造；货憨憨写操作（上传素材、批量修改商品、删除素材）；SQLite 表结构与迁移；并发数与风控等待；断点与全局停止门逻辑；凭据存取方式 | 停止修改，先分析并等待人工确认 |

轻量模式下低风险项可直接实施；出现下列任何一项立即按高风险处理：涉及凭据、真实店铺数据、批量写入、删除、迁移、并发，或无法判断影响范围。

## 修改界面文案（计划）

1. 在 `frontend/src/views/` 找到对应页面的文案。
2. 只改显示文本，不改绑定的字段名和事件名。
3. `wails dev` 启动后确认两个标签页显示正常。
4. 属于低风险，可直接实施。

错误提示要注意：前端不得依赖中文错误文本做判断。程序逻辑一律按 Go 侧返回的错误码分支，中文只用于显示。改文案不能改错误码。

## 增加一个参数设置项（计划）

1. `internal/config/` 增加字段、默认值与校验范围。
2. `frontend/src/views/SettingsView` 增加对应表单项。
3. 在使用该参数的模块读取，不要在多处各自读一份。
4. 验证：填非法值时被拒绝并给出原因；重启程序后配置仍然生效。
5. 属于中风险，建工单。

如果新参数是路径或凭据，先确认它属于哪一类：路径写入配置文件；凭据不得写入仓库，也不得进入日志。

## 修改 Wiki 文案

长期文档的唯一编辑入口是 Gitea Wiki，`docs/` 是只读镜像。

```powershell
# 1. 在 Gitea Wiki 页面上修改并保存
# 2. 在线读取确认内容正确
# 3. 导出镜像
python dev_scripts/harness.py sync
# 4. 检查差异
git diff --stat docs
# 5. 单独提交镜像，不与实现代码混在一起
```

注意事项：

- 不要先改 `docs/` 再反向覆盖 Wiki，同步工具没有反向能力。
- 不要改动固定章节标题，`check --strict` 依赖它们。
- 镜像有未提交改动时同步会停止；先确认改动来源再处理，不要直接覆盖。
- 页面删除或重命名不会自动传播，必须先在工单确认映射变化。

## 调整 Harness 检查

`dev_scripts/` 属于 DevHarness 自身工具，本项目默认不修改。

- 需要新增一个长期文档页面时：先在 Gitea Wiki 建页，再在 `wiki-docs.json` 增加映射，然后 `sync` 导出，最后 `check --strict` 验证。这不属于修改 Harness。
- 确实需要改 `harness.py` 或 `wiki_docs.py` 时，先确认该需求是否应该回到上游 `OPC/dev_harness` 解决。在本项目就地改会让后续升级产生冲突，必须建工单并在[项目档案](00-project-profile.md)的「项目适配说明」登记。
- 升级 DevHarness 时整体替换 `dev_scripts/`，并把[项目档案](00-project-profile.md)中的基线提交更新为实际采用的完整哈希。未完成或已回退的升级不得更新基线。
- 业务用的通用脚本放独立目录，不得混入 `dev_scripts/`。

## 看懂 Agent 的修改

审查 Agent 提交时按这个顺序看，比逐行读代码有效：

1. **范围**：`git diff --stat` 的文件是否都属于本次任务。出现无关文件说明范围失控。
2. **边界**：是否触碰了[架构与代码地图](02-architecture-and-code-map.md)的「不可破坏的边界」。尤其看有没有把 Cookie、token 写进日志或文件。
3. **规则**：是否改变了[业务规则与术语](03-business-rules-and-glossary.md)里的稳定规则。改了就必须有对应工单和重新确认记录。
4. **证据**：工单里的测试结果是真实运行的，还是只写了「已实现」。未验证的部分有没有明确写出来。
5. **文档**：命令、入口、配置、错误码、业务规则有变化时，Wiki 是否同步更新。
6. **提交**：提交是否只包含本次任务文件，有工单时是否带工单号。

看不懂的地方直接要求 Agent 解释这段代码在什么情况下会走到、失败时会发生什么。不要因为测试通过就默认边界没被破坏。