147 lines
6.0 KiB
Markdown
147 lines
6.0 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Development-Workflow
|
||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
|
||
wiki_revision: af4c1cbdd73cf9f6df971415487e2664e227ebc9
|
||
synchronized_at: 2026-08-08T00:58:03Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 开发工作流
|
||
|
||
## 事实来源边界
|
||
|
||
- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
|
||
- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
|
||
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
|
||
- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
|
||
|
||
## 一次任务怎样完成
|
||
|
||
### 1. 讨论
|
||
|
||
用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。
|
||
|
||
### 2. 建单
|
||
|
||
方案确认后，使用 `.gitea/issue_template/task.md` 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。
|
||
|
||
新产品或较大版本先建立 Epic，再建立 MVP：
|
||
|
||
```text
|
||
[Epic] 产品或长期目标
|
||
└── [MVP] 第一个可交付版本
|
||
├── #101 单元任务
|
||
├── #102 单元任务
|
||
└── #103 单元任务
|
||
```
|
||
|
||
每个单元任务都应目标单一，能够独立测试、提交和回退。
|
||
|
||
### 3. 实施
|
||
|
||
Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。
|
||
|
||
重要进度及时写回工单：
|
||
|
||
- 已确认的根因；
|
||
- 方案或范围变化；
|
||
- 测试结果；
|
||
- 阻塞和未验证内容；
|
||
- Git 提交哈希；
|
||
- 相关 Wiki 页面及 revision。
|
||
|
||
长期文档遵循唯一顺序：
|
||
|
||
```text
|
||
修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
|
||
```
|
||
|
||
不得先编辑 `docs/` 再反向覆盖 Wiki。
|
||
|
||
### 4. 待验收
|
||
|
||
实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
|
||
|
||
### 5. 归档和关闭
|
||
|
||
使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像：
|
||
|
||
```powershell
|
||
python scripts/new_task_archive.py 123 "修复登录超时"
|
||
```
|
||
|
||
归档内容以 Wiki 页面为主源；本地 `docs/task/<编号>-<短标题>.md` 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
|
||
|
||
## 文档同步规则
|
||
|
||
- 映射保存在 `wiki-docs.json`，每个 Wiki 页面对应唯一仓库路径。
|
||
- 同步脚本只实现 Wiki → `docs/`，不提供反向同步。
|
||
- 镜像头必须记录页面名、页面地址、revision 和同步时间。
|
||
- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
|
||
- `--check` 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。
|
||
- 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
|
||
- Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
|
||
- 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。
|
||
|
||
## 面向初级维护者的修改边界
|
||
|
||
| 风险 | 示例 | 处理方式 |
|
||
|---|---|---|
|
||
| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 |
|
||
| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 |
|
||
| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
|
||
|
||
风险由影响范围决定，不按代码行数判断。
|
||
|
||
## 每个任务的文档影响
|
||
|
||
单元任务必须明确选择：
|
||
|
||
- 不影响长期文档，并说明原因；
|
||
- 更新项目档案或运行验证；
|
||
- 更新架构与代码地图；
|
||
- 更新业务规则与术语；
|
||
- 更新常见修改或故障排查；
|
||
- 新增或调整其他 Wiki 页面。
|
||
|
||
以下变化必须更新相关 Wiki：
|
||
|
||
- 启动、测试、部署或排错命令变化；
|
||
- 模块入口、目录职责或主要调用路径变化；
|
||
- 配置项、API、数据结构或状态变化；
|
||
- 业务规则、安全边界或权限变化；
|
||
- 日志位置、错误定位或常见处理方式变化。
|
||
|
||
普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。
|
||
|
||
## 稳定文档与任务归档
|
||
|
||
- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
|
||
- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。
|
||
- 新人先读稳定主题页，只有追查历史原因时才读任务归档。
|
||
- 任务产生的长期结论必须合并到主题页，不能只留在归档。
|
||
|
||
## 什么时候重新确认方案
|
||
|
||
以下变化必须先更新工单，再由用户确认：
|
||
|
||
- 交付结果或用户操作发生变化；
|
||
- 增加或删除接口、数据库字段或迁移；
|
||
- 安全边界、权限或不可逆操作发生变化；
|
||
- 原方案不可行，需要更换主要技术路线；
|
||
- 任务范围明显扩大；
|
||
- Wiki 页面删除、重命名或事实源边界改变。
|
||
|
||
普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。
|
||
|
||
## 工单、Wiki 与 Git 分别写什么
|
||
|
||
| 信息 | Gitea 工单 | Gitea Wiki | Git / `docs` 镜像 |
|
||
|---|---:|---:|---:|
|
||
| 讨论过程和临时方案 | 是 | 否 | 否 |
|
||
| 实施进度和阻塞 | 是 | 否 | 否 |
|
||
| 长期有效的最终方案 | 链接 | 是 | 镜像 |
|
||
| 测试结果与未验证内容 | 是 | 任务归档 | 镜像 |
|
||
| 提交哈希 | 是 | 任务归档 | 镜像 |
|
||
| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
|