goauto/docs/01-workflow.md

开发工作流

事实来源

• Gitea Epic/MVP：长期目标、版本范围和子工单索引。
• Gitea 单元工单：原始需求摘要、讨论、状态、方案变化、验证和验收过程。
• Gitea Wiki：长期需求、架构、业务规则、运行方式、共享接口和任务归档。
• Git：源码、迁移、版本绑定分析、本地原型和核心 Wiki 的只读镜像。
• QuantUX：外部交互原型；App ID、链接和确认状态必须记录在工单。

核心页面通过 wiki-docs.json 显式映射，固定执行 Wiki → docs/ 单向同步。页面删除、重命名、映射变化或事实来源反向切换必须另行确认。

工单与设计证据双门禁

正式实施前依次判断是否需要工单，以及需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。

工单豁免

只有纯显示文案同时满足以下全部条件时才可以免工单：不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局、截断和可访问性。有任何不确定时建立单元工单。

最低设计证据

修改类型	最低证据	正式实施门禁
纯显示文案且满足豁免	无原型	做最小界面检查
现有界面小范围样式或布局	标注截图、低保真图或明确复用规范	工单确认后实施
新组件	正常、空、加载、错误、禁用和权限边界说明	工单确认状态后实施
新页面、独立功能、重大交互或导航	QuantUX 或其他可审阅原型	用户确认文字需求、原型和覆盖范围后实施
后端、接口、数据或定时任务	架构、API、数据、状态或流程设计	用户确认技术方案后实施
恢复既有行为的 Bug	原设计、截图、复现步骤或已有验收证据	确认是恢复而非改需求

设计证据记录链接或路径、App ID/版本、草稿/已确认/已废弃状态、确认人、确认时间和覆盖范围。页面结构、主要流程、状态、权限、异常处理或验收结果变化时必须重新确认。

任务层级与状态

[Epic] 长期产品目标
└── [MVP] 一个可交付版本
    ├── 单元任务 #N
    └── 单元任务 #N+1

单元任务是唯一实施单位。建立新工单不要求所有依赖已完成，但实施前必须检查真实依赖。

待确认 → 待实施 → 进行中 → 待验收 → 已完成
                     └→ 阻塞

前置依赖未完成且存在实施冲突时保持待实施；已经开始后出现计划外且当前无法解除的问题才标记阻塞。

单元任务闭环

1. 读取工单、项目档案、业务规则、受影响目录和共享契约。
2. 区分代码事实、用户确认规则和假设，确认目标、非目标、方案、风险、回退和验证。
3. 检查前置工单、分支和工作区，只修改工单范围。
4. 执行与风险相称的格式、单元、契约、集成、浏览器或真机验证。
5. 先更新受影响的 Wiki 页面并读取确认，再导出核心 docs/ 镜像并检查一致性；把实现、验证和未验证内容回写工单。
6. 提交当前工单变更，创建或更新 Wiki 任务归档，工单保持待验收。
7. 用户明确验收后更新归档状态、关闭工单，并同步 Epic/MVP 子工单索引。

高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。

需求记录与流转

• 聊天用于分析和确认，不是长期事实来源。
• 单元工单记录来源、提出时间、必要的关键原话或脱敏摘要、目标、非目标、方案、验收和需求变化。
• 长期稳定的需求进入产品需求总览或对应主题页面；共享接口只进入API 契约。
• 工单不复制完整聊天，不保存 Agent 内部推理、凭据、个人数据或生产数据。
• 完成结果进入 Wiki 任务归档；docs/task/ 仅在用户明确要求时增量或全量导出，不是完整历史。

自然语言快捷指令

指令	执行动作	停止位置
只分析	只读检查并给出方案	等待确认，不建单、不修改
建工单	根据已确认方案创建单元任务	工单创建后停止
执行工单 #N	检查依赖，实施、测试、提交并回写证据	工单待验收
建工单并做	依次建单和执行	工单待验收
继续工单 #N	从首个未完成步骤继续	到当前停止条件
检查工单 #N	只读检查范围、验收、测试和证据	输出报告，不自动修复
同步文档	读取 Wiki、导出核心 docs/ 并检查一致性，不处理任务归档	输出差异；不修改 Wiki、不自动提交
导出任务归档	按 revision 增量导出 Wiki 任务归档	只写 docs/task/，不删除旧快照
导出全部任务归档	全量读取并导出全部 Wiki 任务归档	只写 docs/task/，不删除旧快照
#N 验收通过	记录验收、更新任务归档、同步必要镜像、同步父工单并关闭任务	工单已完成

快捷指令不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收。

效率与范围控制

• 默认严格按已确认范围实施，不顺手修复相邻问题。
• 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。
• 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。
• 同一任务、同一环境中已经验证的事实不重复检查；环境或关键前提变化后再验证。
• 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。
• 完成工单范围、必要验证、文档影响和证据回写后立即停止。

文档影响

每个单元工单至少选择一项：无长期文档影响并说明原因；更新项目档案/运行验证；更新架构；更新业务规则；更新 API 契约；更新产品需求、常见修改或故障排查。长期页面先修改 Wiki，读取确认后运行 python dev_scripts/sync_wiki_docs.py；不得直接修改映射镜像。

启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新对应文档。