132 lines
9.0 KiB
Markdown
132 lines
9.0 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Development-Workflow
|
||
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Development-Workflow.-
|
||
wiki_revision: ae87ca1d39dc196bccf2640d6fb868723cdd3e1d
|
||
synchronized_at: 2026-08-19T01:19:47Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 开发工作流
|
||
|
||
## 事实来源
|
||
|
||
- Gitea Epic/MVP：长期目标、版本范围和子工单索引。
|
||
- Gitea 单元工单：原始需求摘要、讨论、状态、方案变化、验证和验收过程。
|
||
- Gitea Wiki：长期需求、架构、业务规则、运行方式、共享接口和任务归档。
|
||
- Git：源码、迁移、版本绑定分析、本地原型和核心 Wiki 的只读镜像。
|
||
- QuantUX：外部交互原型；App ID、链接和确认状态必须记录在工单。
|
||
|
||
核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。页面删除、重命名、映射变化或事实来源反向切换必须另行确认。
|
||
|
||
## 新项目 Wiki 初始化门禁
|
||
|
||
本项目 Wiki 已于 2026-08-17 初始化并启用 Wiki-first，本节适用于从本仓库派生新项目的场景。
|
||
|
||
- 先创建 Gitea 远端仓库并启用工单和 Wiki，再配置 `wiki-docs.json`；不得把本地 `docs/` 当作线上 Wiki 已初始化的证据。
|
||
- 优先使用已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需写操作时才使用 Gitea API，并在初始化工单记录回退原因。凭据只从环境或 MCP 安全配置读取。
|
||
- 先查询线上页面列表；`Home` 不存在时必须先创建 `Home`，在线回读正文并记录 revision，再逐页创建或更新其他核心映射页面。
|
||
- 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化，不得开始产品代码。
|
||
- 产品编码前必须运行 `python dev_scripts/harness.py sync --verify`，全部成功才表示初始化完成。
|
||
|
||
## 工单与设计证据双门禁
|
||
|
||
正式实施前依次判断是否需要工单，以及需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。
|
||
|
||
### 工单豁免
|
||
|
||
只有纯显示文案同时满足以下全部条件时才可以免工单：不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局、截断和可访问性。有任何不确定时建立单元工单。
|
||
|
||
### 最低设计证据
|
||
|
||
| 修改类型 | 最低证据 | 正式实施门禁 |
|
||
|---|---|---|
|
||
| 纯显示文案且满足豁免 | 无原型 | 做最小界面检查 |
|
||
| 现有界面小范围样式或布局 | 标注截图、低保真图或明确复用规范 | 工单确认后实施 |
|
||
| 新组件 | 正常、空、加载、错误、禁用和权限边界说明 | 工单确认状态后实施 |
|
||
| 新页面、独立功能、重大交互或导航 | QuantUX 或其他可审阅原型 | 用户确认文字需求、原型和覆盖范围后实施 |
|
||
| 后端、接口、数据或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后实施 |
|
||
| 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而非改需求 |
|
||
|
||
设计证据记录链接或路径、App ID/版本、草稿/已确认/已废弃状态、确认人、确认时间和覆盖范围。页面结构、主要流程、状态、权限、异常处理或验收结果变化时必须重新确认。
|
||
|
||
### 本地 HTML 审核快照
|
||
|
||
- 完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。
|
||
- 可编辑设计源仍在 QuantUX，Git 中的 HTML 是版本化审核证据，Wiki 和工单只保存索引。
|
||
- 已确认的 HTML 快照不得原位覆盖。页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。
|
||
- 提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。
|
||
- QuantUX 无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留线上链接后直接编码。
|
||
- 纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。
|
||
|
||
**存量偏离（#47 确认）**：`prototypes/` 下已有的 `quantux-*.html` 平铺快照建立于本规则之前，保持原样不迁移，历史版本可在 Git 历史中查阅；工单号/版本目录结构自 #47 起对新增原型生效。
|
||
|
||
## 任务层级与状态
|
||
|
||
```text
|
||
[Epic] 长期产品目标
|
||
└── [MVP] 一个可交付版本
|
||
├── 单元任务 #N
|
||
└── 单元任务 #N+1
|
||
```
|
||
|
||
单元任务是唯一实施单位。建立新工单不要求所有依赖已完成，但实施前必须检查真实依赖。
|
||
|
||
```text
|
||
待确认 → 待实施 → 进行中 → 待验收 → 已完成
|
||
└→ 阻塞
|
||
```
|
||
|
||
前置依赖未完成且存在实施冲突时保持待实施；已经开始后出现计划外且当前无法解除的问题才标记阻塞。
|
||
|
||
## 单元任务闭环
|
||
|
||
1. 读取工单、项目档案、业务规则、受影响目录和共享契约。
|
||
2. 区分代码事实、用户确认规则和假设，确认目标、非目标、方案、风险、回退和验证。
|
||
3. 检查前置工单、分支和工作区，只修改工单范围。
|
||
4. 执行与风险相称的格式、单元、契约、集成、浏览器或真机验证。
|
||
5. 先更新受影响的 Wiki 页面并读取确认，再导出核心 `docs/` 镜像并检查一致性；把实现、验证和未验证内容回写工单。
|
||
6. 提交当前工单变更，创建或更新 Wiki 任务归档，工单保持待验收。
|
||
7. 用户明确验收后更新归档状态、关闭工单，并同步 Epic/MVP 子工单索引。
|
||
|
||
高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。
|
||
|
||
## 需求记录与流转
|
||
|
||
- 聊天用于分析和确认，不是长期事实来源。
|
||
- 单元工单记录来源、提出时间、必要的关键原话或脱敏摘要、目标、非目标、方案、验收和需求变化。
|
||
- 长期稳定的需求进入[产品需求总览](https://git.ilapage.cn/OPC/goauto/wiki/Product-Requirements-Overview)或对应主题页面；共享接口只进入[API 契约](https://git.ilapage.cn/OPC/goauto/wiki/Android-Agent-API-Contract)。
|
||
- 工单不复制完整聊天，不保存 Agent 内部推理、凭据、个人数据或生产数据。
|
||
- 完成结果进入 Wiki 任务归档；`docs/task/` 仅在用户明确要求时增量或全量导出，不是完整历史。
|
||
|
||
## 自然语言快捷指令
|
||
|
||
| 指令 | 执行动作 | 停止位置 |
|
||
|---|---|---|
|
||
| `只分析` | 只读检查并给出方案 | 等待确认，不建单、不修改 |
|
||
| `建工单` | 根据已确认方案创建单元任务 | 工单创建后停止 |
|
||
| `执行工单 #N` | 检查依赖，实施、测试、提交并回写证据 | 工单待验收 |
|
||
| `建工单并做` | 依次建单和执行 | 工单待验收 |
|
||
| `继续工单 #N` | 从首个未完成步骤继续 | 到当前停止条件 |
|
||
| `检查工单 #N` | 只读检查范围、验收、测试和证据 | 输出报告，不自动修复 |
|
||
| `同步文档` | 读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档 | 输出差异；不修改 Wiki、不自动提交 |
|
||
| `导出任务归档` | 按 revision 增量导出 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 |
|
||
| `导出全部任务归档` | 全量读取并导出全部 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 |
|
||
| `#N 验收通过` | 记录验收、更新任务归档、同步必要镜像、同步父工单并关闭任务 | 工单已完成 |
|
||
|
||
快捷指令不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收。
|
||
|
||
## 效率与范围控制
|
||
|
||
- 默认严格按已确认范围实施，不顺手修复相邻问题。
|
||
- 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。
|
||
- 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。
|
||
- 同一任务、同一环境中已经验证的事实不重复检查；环境或关键前提变化后再验证。
|
||
- 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。
|
||
- 完成工单范围、必要验证、文档影响和证据回写后立即停止。
|
||
|
||
## 文档影响
|
||
|
||
每个单元工单至少选择一项：无长期文档影响并说明原因；更新项目档案/运行验证；更新架构；更新业务规则；更新 API 契约；更新产品需求、常见修改或故障排查。长期页面先修改 Wiki，读取确认后运行 `python dev_scripts/harness.py sync`；不得直接修改映射镜像。
|
||
|
||
启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新对应文档。
|