From a7f146e9e25f621fdca6c16f970e2228c8f6e111 Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Mon, 24 Aug 2026 16:20:13 +0800 Subject: [PATCH] docs(#76): adopt streamlined single-developer workflow --- Development-Workflow.-.md | 127 ++++++++++++++++++++++++-------------- 1 file changed, 80 insertions(+), 47 deletions(-) diff --git a/Development-Workflow.-.md b/Development-Workflow.-.md index f41d5a9..27d5fb8 100644 --- a/Development-Workflow.-.md +++ b/Development-Workflow.-.md @@ -2,55 +2,76 @@ ## 事实来源 -- Gitea Epic/MVP：长期目标、版本范围和子工单索引。 -- Gitea 单元工单：原始需求摘要、讨论、状态、方案变化、验证和验收过程。 -- Gitea Wiki：长期需求、架构、业务规则、运行方式、共享接口和任务归档。 -- Git：源码、迁移、版本绑定分析、本地原型和核心 Wiki 的只读镜像。 -- QuantUX：外部交互原型；App ID、链接和确认状态必须记录在工单。 +| 信息 | 唯一事实来源 | +|---|---| +| Epic/MVP 目标、版本范围和子工单索引 | Gitea Epic/MVP | +| 单次任务需求、变化、方案、实现、测试、提交、阻塞和验收 | Gitea 单元工单 | +| 长期需求、架构、契约、业务规则、安全边界和操作说明 | Gitea Wiki | +| 源码、迁移、测试、版本绑定分析、本地原型和核心 Wiki 镜像 | Git | +| 可编辑交互设计 | QuantUX；App ID、版本、链接和确认状态记录在工单 | -核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。页面删除、重命名、映射变化或事实来源反向切换必须另行确认。 +核心页面通过 `wiki-docs.json` 显式映射，固定执行 Wiki → `docs/` 单向同步。既有 Wiki 任务归档和 `docs/task/` 只作历史兼容；标准任务不创建或导出，只有用户明确要求专项快照时才使用 `archive` / `export`。 + +## 权威源与事实边界 + +发生冲突时按以下顺序裁决： + +1. 可执行代码与自动化测试。 +2. 状态为已批准的共享契约和决策。 +3. 当前长期 Wiki。 +4. 旧设计稿。 +5. 注释、UI 文案和历史示例。 + +“当前实现”只能描述指定 commit 上可复核的行为；“目标契约”是尚待实施或验收的目标，不能用来宣称现有能力。能力状态使用“未发现实现 / 仅设计 / 部分实现 / 已实现某一端”等带限定的表达。 + +进行基线或差距审计时，记录 source commit、核验日期、证据路径、GAP-ID、审计范围、不在范围和证据边界。轻量日常工单不强制建立完整 SRS/SAD/ADR 文档集，但接口、状态机和跨端决策必须进入对应长期契约。 ## 新项目 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`，全部成功才表示初始化完成。 +- 优先使用已配置的 Gitea MCP 查询和写入 Wiki；MCP 不可用或不支持所需操作时才回退到 Gitea API，并在初始化工单记录原因。凭据只从安全配置读取。 +- `Home` 不存在时先创建并在线回读 revision，再逐页创建或更新其他核心映射页面。 +- 每个核心页面写入后必须在线回读并取得 revision。页面缺失、回读失败或没有 revision 时停止初始化。 +- 产品编码前运行 `python dev_scripts/harness.py sync --verify`；全部成功才表示初始化完成。 ## 工单与设计证据双门禁 -正式实施前依次判断是否需要工单，以及需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。 +正式实施前先判断是否需要工单，再判断需要什么设计证据。工单不能替代原型确认，原型也不能替代技术方案、安全检查和单元工单。 ### 工单豁免 -只有纯显示文案同时满足以下全部条件时才可以免工单：不改变业务含义、流程、权限、状态、接口、数据、安全、支付、金额、单位、程序标识符、布局、截断和可访问性。有任何不确定时建立单元工单。 +直接提交必须同时满足：范围明确、容易回退、不涉及接口/数据库/状态/权限/安全/并发/重大 UI 等必须建单项，并完成受影响范围的最小验证。可包括： + +- 错别字、注释、文档措辞、格式化和导入排序； +- 单文件内部变量改名、类型标注、文档字符串或不改变产品行为的测试； +- 已确认无人使用的死代码； +- 单文件低风险且只恢复已有明确行为的缺陷； +- 不改变业务含义、流程、权限、状态、接口、数据、布局和可访问性的纯显示文案。 + +有任何不确定就建立单元工单。 ### 最低设计证据 | 修改类型 | 最低证据 | 正式实施门禁 | |---|---|---| -| 纯显示文案且满足豁免 | 无原型 | 做最小界面检查 | +| 纯显示文案且满足豁免 | 无原型 | 最小界面检查 | | 现有界面小范围样式或布局 | 标注截图、低保真图或明确复用规范 | 工单确认后实施 | -| 新组件 | 正常、空、加载、错误、禁用和权限边界说明 | 工单确认状态后实施 | +| 新组件 | 正常、空、加载、失败、禁用和权限边界 | 工单确认后实施 | | 新页面、独立功能、重大交互或导航 | QuantUX 或其他可审阅原型 | 用户确认文字需求、原型和覆盖范围后实施 | | 后端、接口、数据或定时任务 | 架构、API、数据、状态或流程设计 | 用户确认技术方案后实施 | -| 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而非改需求 | - -设计证据记录链接或路径、App ID/版本、草稿/已确认/已废弃状态、确认人、确认时间和覆盖范围。页面结构、主要流程、状态、权限、异常处理或验收结果变化时必须重新确认。 +| 恢复既有行为的 Bug | 原设计、截图、复现步骤或已有验收证据 | 确认是恢复而不是改需求 | ### 本地 HTML 审核快照 -- 完整原型形成待审核版本后，必须在用户审核前生成本地可浏览 HTML 快照，保存到 `prototypes/<工单号>/<版本>/index.html`；版本目录内资源使用相对路径。 -- 可编辑设计源仍在 QuantUX，Git 中的 HTML 是版本化审核证据，Wiki 和工单只保存索引。 -- 已确认的 HTML 快照不得原位覆盖。页面结构、流程、状态、权限、异常处理或验收结果变化时，使用新版本目录重新导出并重新确认。 -- 提交审核前检查入口、主要交互和资源完整性，并删除凭据、账号、个人信息和生产数据。 -- QuantUX 无法生成可用 HTML 时，在工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不得只保留线上链接后直接编码。 -- 纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。 +- 完整原型在用户审核前导出到 `prototypes/<工单号>/<版本>/index.html`，资源使用相对路径。 +- QuantUX 保留可编辑源，Git HTML 是版本化审核证据；工单只保存索引。 +- 已确认快照不得原位覆盖；结构、流程、状态、权限或异常处理变化时建立新版本并重新确认。 +- 提交审核前检查入口、交互和资源完整性，删除凭据、账号、个人信息和生产数据。 +- QuantUX 无法生成可用 HTML 时记录限制并停止审核；纯文案、小范围 UI、非 UI 和恢复已有行为的 Bug 不强制 HTML。 -**存量偏离（#47 确认）**：`prototypes/` 下已有的 `quantux-*.html` 平铺快照建立于本规则之前，保持原样不迁移，历史版本可在 Git 历史中查阅；工单号/版本目录结构自 #47 起对新增原型生效。 +存量 `quantux-*.html` 平铺快照建立于规则前，保持原样；新目录规则自 #47 生效。 ## 任务层级与状态 @@ -61,34 +82,44 @@ └── 单元任务 #N+1 ``` -单元任务是唯一实施单位。建立新工单不要求所有依赖已完成，但实施前必须检查真实依赖。 +单元任务是唯一正式实施单位。状态为： ```text 待确认 → 待实施 → 进行中 → 待验收 → 已完成 └→ 阻塞 ``` -前置依赖未完成且存在实施冲突时保持待实施；已经开始后出现计划外且当前无法解除的问题才标记阻塞。 +真实依赖未满足且不能并行时保持待实施；开始后遇到无法解除的问题才标记阻塞。 ## 单元任务闭环 -1. 读取工单、项目档案、业务规则、受影响目录和共享契约。 -2. 区分代码事实、用户确认规则和假设，确认目标、非目标、方案、风险、回退和验证。 -3. 检查前置工单、分支和工作区，只修改工单范围。 -4. 执行与风险相称的格式、单元、契约、集成、浏览器或真机验证。 -5. 先更新受影响的 Wiki 页面并读取确认，再导出核心 `docs/` 镜像并检查一致性；把实现、验证和未验证内容回写工单。 -6. 提交当前工单变更，创建或更新 Wiki 任务归档，工单保持待验收。 -7. 用户明确验收后更新归档状态、关闭工单，并同步 Epic/MVP 子工单索引。 +1. 只读确认当前代码事实、目标、非目标、依赖、设计证据、风险、回退、验证和长期文档影响。 +2. 需要建单时创建单元工单并记录脱敏需求摘要；实施开始时检查分支和工作区并标记进行中。 +3. 严格按工单范围实施；根因、范围、主要方案、风险或阻塞变化时先更新工单并按需重新确认。 +4. 执行与风险相称的格式、单元、契约、集成、浏览器、真机或高风险验证；记录未验证内容。 +5. 只有长期事实变化时更新 Wiki、在线回读 revision、运行一次 `sync` 和一次 `sync --check`；无长期影响时在工单说明原因并跳过。 +6. 提交并推送当前工单文件，在工单集中回写最终差异、测试、未验证内容、提交哈希和 Wiki revision，保持待验收。 +7. 用户明确验收后记录时间和结论、关闭单元工单并更新 Epic/MVP；没有新的长期事实变化时不重复同步 Wiki。 -高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。 +高风险数据库迁移、设备认证、并发租约、地址修改、创建订单、权限、删除、发布和不可逆动作必须单独建单并再次等待人工确认。任何自动支付需求直接拒绝。 + +## 标准任务节奏 + +默认只更新工单三次： + +1. **开始实施**：确认依赖、范围、工作区和设计证据。 +2. **待验收**：集中记录最终差异、测试、未验证项、提交和长期文档影响。 +3. **验收关闭**：记录用户验收结论，关闭任务并更新父工单。 + +只有根因、范围、主要方案、风险或阻塞发生重要变化时才增加过程记录。不重复抄写完整聊天、Agent 内部推理、已存在的测试证据或提交信息。 ## 需求记录与流转 - 聊天用于分析和确认，不是长期事实来源。 -- 单元工单记录来源、提出时间、必要的关键原话或脱敏摘要、目标、非目标、方案、验收和需求变化。 -- 长期稳定的需求进入[产品需求总览](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/` 仅在用户明确要求时增量或全量导出，不是完整历史。 +- 单元工单记录来源、提出时间和表达目的所需的少量关键原话或脱敏摘要，不保存凭据、个人数据或生产数据。 +- 长期稳定需求进入产品需求或对应主题 Wiki；共享接口只进入 API 契约。 +- 工单必须区分当前代码事实、目标契约和假设；不得把目标写成已有能力。 +- 标准任务不创建 Wiki 任务归档。已有任务归档不删除、不补齐；用户明确要求专项历史快照时才按需创建或导出。 ## 自然语言快捷指令 @@ -100,24 +131,26 @@ | `建工单并做` | 依次建单和执行 | 工单待验收 | | `继续工单 #N` | 从首个未完成步骤继续 | 到当前停止条件 | | `检查工单 #N` | 只读检查范围、验收、测试和证据 | 输出报告，不自动修复 | -| `同步文档` | 读取 Wiki、导出核心 `docs/` 并检查一致性，不处理任务归档 | 输出差异；不修改 Wiki、不自动提交 | -| `导出任务归档` | 按 revision 增量导出 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 | -| `导出全部任务归档` | 全量读取并导出全部 Wiki 任务归档 | 只写 `docs/task/`，不删除旧快照 | -| `#N 验收通过` | 记录验收、更新任务归档、同步必要镜像、同步父工单并关闭任务 | 工单已完成 | +| `同步文档` | 读取 Wiki，导出核心镜像并检查一致性 | 不修改 Wiki、不处理任务快照、不自动提交 | +| `导出任务归档` | 用户明确要求时按 revision 导出历史任务快照 | 只写 `docs/task/` | +| `导出全部任务归档` | 用户明确要求时全量导出历史任务快照 | 只写 `docs/task/` | +| `#N 验收通过` | 记录验收、关闭任务并同步父工单 | 无新长期事实时不再同步 Wiki | -快捷指令不能绕过方案确认、前置依赖、安全规则、工单范围、必要验证或人工验收。 +快捷指令不能绕过方案确认、依赖、安全、设计证据、工单范围、必要验证或人工验收。 ## 效率与范围控制 - 默认严格按已确认范围实施，不顺手修复相邻问题。 - 完成必要安全和前置检查后，优先执行能产生真实反馈的最小命令。 - 采用“执行 → 查看首个可行动错误 → 最小修复 → 继续”的闭环。 -- 同一任务、同一环境中已经验证的事实不重复检查；环境或关键前提变化后再验证。 +- 同一任务、同一环境已经验证的事实不重复检查；环境或关键前提变化后再验证。 - 不新增与验收无关的文档、脚本、框架、重构或扩展性设计。 -- 完成工单范围、必要验证、文档影响和证据回写后立即停止。 +- 完成工单范围、必要验证、按影响触发的文档闭环和证据回写后立即停止。 ## 文档影响 -每个单元工单至少选择一项：无长期文档影响并说明原因；更新项目档案/运行验证；更新架构；更新业务规则；更新 API 契约；更新产品需求、常见修改或故障排查。长期页面先修改 Wiki，读取确认后运行 `python dev_scripts/harness.py sync`；不得直接修改映射镜像。 +每个单元工单必须二选一：说明“无长期文档影响”的原因；或列出要更新的 Wiki 页面。 -启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新对应文档。 +启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界或日志位置变化时必须更新长期 Wiki。普通内部重构只有在入口、行为、配置和验证方式都不变时才可记为无影响。 + +Wiki 同步由长期事实变化触发，不由任务完成触发。有影响时只执行一轮：修改 Wiki → 在线回读 revision → `sync` → `sync --check` → 提交镜像；验收时内容未变化不重复执行。不得直接修改映射镜像后反向覆盖 Wiki。