docs(wiki): add Octopus↔Gitea 工作流状态映射说明

2026-06-24 09:25:14 +08:00
commit b31c801f12
1 changed files with 254 additions and 0 deletions
@@ -0,0 +1,254 @@
+# Octopus 工作流状态映射至 Gitea
+
+本文档详细说明 Octopus SDLC（软件开发生命周期）工作流的各个状态、阶段与产物，是如何精确映射到 Gitea 仓库的各个实体（项目看板、里程碑、Issue、Wiki、标签、PR、Release）上的。该映射由 Octopus 的 `gitea-sync` 能力驱动，支持两种触发模式。
+
+---
+
+## 1. 核心映射原则
+
+Octopus 将"软件开发流程"抽象为一组**概念实体**：Roadmap（路线图）、Chunk（分块）、Work Item（工作项）、Phase/Stage（阶段）、Iteration（迭代）、Document（文档）、Review（评审）、Release（发布）。这些概念并不直接存储在 Gitea 中，而是通过一套**确定性映射规则**投影到 Gitea 原生能力上：
+
+- **Gitea 是投影面，不是真相源**：Octopus 的 `.artifacts/{slug}/` 目录才是产物的唯一真相源；Gitea 上的内容是同步过来的可读副本，供人在 Web UI 中审阅。
+- **同步时机**：同步始终发生在**评审收敛之后**、**征求用户批准之前**。用户在 TUI 与 Gitea 两侧都能看到同一份产物。
+- **幂等性**：每次同步前先检查目标实体是否已存在，已存在则用 `update` 覆盖，避免产生重复。
+
+---
+
+## 2. 实体映射总表
+
+| Octopus 概念 | Gitea 实体 | 使用的 MCP 工具 | 同步触发时机 |
+|---|---|---|---|
+| Roadmap（路线图） | 项目看板 + Wiki 页面 | `project__create`、`wiki__create_page` | roadmap 阶段之后 |
+| Chunk（分块） | 里程碑（Milestone） | `milestone__create` | roadmap 中定义分块时 |
+| Chunk 依赖关系 | 里程碑描述（自由文本） | `milestone__update` | 定义依赖时 |
+| Work Item（工作项） | Issue（正文中含验收标准清单） | `issue__create` | 创建工作项时 |
+| 工作项依赖 | Issue 的 blocked-by（Gitea 原生） | `issue__create` + 依赖 API | 设置依赖时 |
+| Phase / 阶段 | 看板列的位置 | `column__move_issue` | 阶段流转时 |
+| 状态（blocked 等） | 标签 | `issue_label__add` | 状态变更时 |
+| 类型（feature/bugfix/refactor） | 标签 | `issue_label__add` | 创建 Issue 时 |
+| 优先级 | 标签 | `issue_label__add` | 创建 Issue 时 |
+| 迭代 | 标签 | `issue_label__add` | 分配迭代时 |
+| 需求文档 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | requirements 阶段之后 |
+| 设计文档 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | design 阶段之后 |
+| 迭代计划 | Wiki 页面 | `wiki__create_page` / `wiki__update_page` | plan 阶段之后 |
+| 评审结论 | Issue 评论 | `issue_comment__create` | 各评审阶段之后 |
+| 代码分支与合并 | Pull Request | `pull__create`、`pull__merge` | 代码合并时 |
+| Release（发布） | Gitea Release + Tag | `release__create` | 切版发布时 |
+
+---
+
+## 3. 一次性前置设置（Prerequisites）
+
+首次同步前，目标 Gitea 仓库需要预先创建**标签体系、项目看板、看板列**。这是一次性的、每仓库仅需执行一次的初始化。
+
+### 3.1 标签体系（Label Taxonomy）
+
+| 标签名 | 颜色 | 说明 |
+|---|---|---|
+| `type/feature` | `#84b6eb` | 新功能开发 |
+| `type/bugfix` | `#e11d48` | 缺陷修复 |
+| `type/refactor` | `#5cb85c` | 代码重构 |
+| `status/blocked` | `#e11d48` | 被依赖阻塞 |
+| `status/needs-attention` | `#fbca04` | 需要人工决策 |
+| `priority/high` | `#e11d48` | 高优先级 |
+| `priority/medium` | `#fbca04` | 中优先级 |
+| `priority/low` | `#cccccc` | 低优先级 |
+
+> 迭代标签（`iteration/iter-1`、`iteration/iter-2`……）随迭代定义**动态创建**，颜色统一用 `#fbca04`。技术标识符（`chunk/`、`iteration/`、`type/` 前缀）保持英文，其余内容可中文化。
+
+### 3.2 项目看板
+
+创建一个名为 `{项目名} SDLC Board` 的项目看板，作为整个工作流的视觉总览。
+
+### 3.3 看板列（对应 SDLC 阶段）
+
+Gitea 默认会创建若干列，需重命名或重建为以下布局。创建后须**记录每列的 column_id**，后续 `column__move_issue` 全程依赖它们。
+
+| 顺序 | 列标题 | 对应的 Octopus 阶段 |
+|---|---|---|
+| 1 | Backlog | 未启动 |
+| 2 | Requirements | requirements-elicitation（需求收集） |
+| 3 | Design | design（架构设计） |
+| 4 | Plan | plan-iterations（迭代规划） |
+| 5 | Implement | implement（代码实现） |
+| 6 | Review | review-code（代码评审） |
+| 7 | Verify | verify（验证） |
+| 8 | Done | 已完成 |
+
+---
+
+## 4. 文档 → Wiki 页面映射
+
+Wiki 页面采用扁平命名空间，以 `/` 作为分隔符。Wiki 内容是产物文件的**完整 Markdown 源码**（MCP 工具透明处理 base64 编解码，直接传入原始 Markdown 即可）。
+
+| 文档 | Wiki 页面标题 | 来源文件 |
+|---|---|---|
+| 路线图 | `Roadmap` | `.artifacts/{slug}/roadmap/roadmap.md` |
+| 需求（按分块） | `Requirements/{chunk-id}` | `.artifacts/{slug}/index.md` |
+| 设计（按分块） | `Design/{chunk-id}` | `.artifacts/{slug}/design/design.md` |
+| 迭代计划 | `Plan/{chunk-id}` | `.artifacts/{slug}/plan/plan.md` |
+| 可行性报告 | `Feasibility-Report` | `docs/.../*.md` |
+
+> **page_name 注意事项**：Gitea 会把 Wiki 标题转换成 URL 安全的 `sub_url`（例如 `Plan/chunk-foo` → `Plan/chunk-foo.-`）。在调用 `wiki__get_page` / `wiki__update_page` 前，应先 `wiki__list_pages` 并使用返回的 `sub_url` 作为 `page_name`。
+
+---
+
+## 5. 两种触发模式
+
+### 模式一：流水线集成（推荐）
+
+当用户说 **"启用 Gitea 同步"** 后，流水线中每个评审门在收敛后会自动把评审通过的产物同步到 Gitea，**再**提交给用户批准。用户可在 Gitea 的 Web UI（Wiki 页面、Issue、项目看板）中直接审阅产物，而非只能在 TUI 里看。会话内记住该同步状态直至用户说 **"停止 Gitea 同步"**。
+
+#### 流水线同步点
+
+| 评审门完成 | 同步到 Gitea | 用户在何处审阅 |
+|---|---|---|
+| `review-roadmap` | Wiki 页面"Roadmap" + 里程碑（分块）+ 项目看板 | Gitea wiki + 项目看板 |
+| `review-design-space` | Wiki 页面"Requirements/{chunk}" + "Design/{chunk}" + Issue（工作项）+ 看板列 | Gitea wiki + Issue + 看板 |
+| `review-iteration-plan` | Wiki 页面"Plan/{chunk}" + 给 Issue 打迭代标签 + 把 Issue 移到"Plan"列 | Gitea wiki + Issue 标签 |
+| `review-code` | PR（若有代码）+ 评审结论作为 Issue 评论 + Issue 移到"Review"列 | Gitea PR + Issue 评论 |
+| `verify` | 验证结果作为 Issue 评论 + 关闭 Issue + 移到"Done"列 | Gitea Issue（已关闭） |
+
+> **关键原则**：同步发生在评审收敛*之后*、`question` 工具征求批准*之前*。
+
+#### 编排器在每个同步点执行的动作
+
+1. 检查 Gitea 同步是否已启用（由"启用"命令记住）。
+2. 查上表确定要同步的内容。
+3. 调用对应的 Gitea MCP 工具推送产物。
+4. 报告一行摘要："✓ Synced to Gitea: {创建了/更新了什么}"。
+5. 继续进入 `question` 征求用户批准。
+
+### 模式二：手动触发（始终可用）
+
+用户随时可显式请求同步：
+
+| 用户指令 | 同步内容 |
+|---|---|
+| "同步到 Gitea" | 当前流水线迄今产生的全部产物 |
+| "同步 roadmap 到 Gitea" | 仅路线图（看板 + 里程碑） |
+| "同步这个 chunk 到 Gitea" | 单个分块的工作项 + 文档 |
+| "同步 PR 到 Gitea" | 创建镜像代码分支的 Gitea PR |
+| "同步 release 到 Gitea" | 创建 Gitea Release + Tag |
+
+---
+
+## 6. 生命周期操作详解（分阶段）
+
+以下过程在两种模式下通用。在**流水线模式**中，由编排器在每个同步点调用对应小节；在**手动模式**中，由用户指令决定执行哪些小节。所有操作均遵循幂等规则，可安全在每个评审门迭代时反复调用。
+
+### A. 同步 Roadmap（roadmap 阶段后）
+
+1. 确保看板 + 列已存在（见第 3 节）。
+2. 为路线图中每个 chunk 创建里程碑：
+   - 标题 `chunk-{chunk-id}`，描述包含"分块说明 + 依赖列表"。
+3. 把路线图文档同步到 Wiki 页面 `Roadmap`。
+
+### B. 同步 Requirements（review-design-space 收敛后 · 需求部分）
+
+1. 把需求文档同步到 Wiki 页面 `Requirements/{chunk-id}`。
+2. 为每个工作项创建 Issue：
+   - 标题 `[{chunk-id}] {工作项标题}`；正文含"## 验收标准"清单 + 描述；关联里程碑；打上类型与优先级标签。
+3. 设置工作项依赖：在 Issue 正文记录"Blocked by #N"，或通过依赖 API（`POST /repos/{owner}/{repo}/issues/{blocker}/blocks`）设置。
+
+### C. 同步 Design（review-design-space 收敛后 · 设计部分）
+
+1. 把设计文档同步到 Wiki 页面 `Design/{chunk-id}`。
+2. 把该 chunk 的所有 Issue 移到"Design"列（`column__move_issue` 的参数是 `issue_index`，即 Issue 编号）。
+3. 给被依赖阻塞的 Issue 打上 `status/blocked` 标签。
+
+### D. 同步迭代计划（review-iteration-plan 收敛后）
+
+1. 把计划文档同步到 Wiki 页面 `Plan/{chunk-id}`。
+2. 若迭代标签不存在则创建 `iteration/iter-{N}`。
+3. 给 Issue 打上对应迭代标签。
+4. 把 Issue 移到"Plan"列。
+
+### E. 同步实现（review-code 门 · 代码就绪时）
+
+1. 把 Issue 移到"Implement"列。
+2. 创建分支、代码就绪后创建 PR：标题 `[{chunk-id}][{iteration}] {描述}`，body 含"Closes #{issue_index}"。
+3. 按需添加评审人。
+
+### F. 同步代码评审（review-code 收敛后）
+
+1. 把评审摘要作为 Issue 评论发出（含 PASS / NEEDS-FIX 状态）。
+2. 把已评审的 Issue 移到"Review"列。
+
+### G. 同步验证（verify 收敛后）
+
+1. 把验证结果（DoD 矩阵摘要）作为 Issue 评论发出（含 PASS / FAIL 状态）。
+2. 把已验证的 Issue 移到"Done"列。
+3. 关闭 Issue（`issue__update` 设 state="closed"）。
+4. 若该迭代所有工作项均通过验证，则合并 PR（`pull__merge`）。
+
+### H. 同步发布
+
+1. 收集上次发布以来所有已关闭的 Issue。
+2. 收集上次发布以来所有已合并的 PR。
+3. 创建 Release：tag `v{version}`，target `main`，note 含"## What's New"与"## Changelog"。
+
+---
+
+## 7. 幂等规则（避免重复同步）
+
+每次创建前先检查：
+
+1. **里程碑**：`milestone__list` → 标题已存在则跳过。
+2. **Issue**：带标签过滤的 `issue__list` → 标题已匹配则跳过。
+3. **标签**：`label__list` → 名称已存在则跳过。
+4. **Wiki 页面**：`wiki__list_pages` → 页面已存在则改用 `wiki__update_page`。
+5. **Release**：`release__list` → tag 已存在则跳过。
+6. **项目看板**：`project__list` → 同名看板已存在则跳过。
+
+重新同步（产物变更后）使用更新工具：`issue__update`、`milestone__update`、`wiki__update_page`、`issue_label__replace`。
+
+---
+
+## 8. 阶段流转一图速览
+
+```
+roadmap ──┐
+          ▼
+[里程碑创建 · 看板创建 · Wiki "Roadmap"]
+          │
+requirements-elicitation ──▶ review-design-space ──▶ design
+          ▼                                              ▼
+[Wiki "Requirements/{chunk}" · Issue 创建]      [Wiki "Design/{chunk}" · Issue→Design 列]
+          │
+          ▼
+plan-iterations ──▶ review-iteration-plan
+          ▼
+[Wiki "Plan/{chunk}" · 迭代标签 · Issue→Plan 列]
+          │
+          ▼
+implement ──▶ review-code
+          ▼                      ▼
+[Issue→Implement 列 · PR 创建]  [Issue 评论评审结论 · Issue→Review 列]
+          │
+          ▼
+verify
+          ▼
+[Issue 评论验证结论 · Issue→Done 列 · Issue 关闭 · PR 合并]
+          │
+          ▼
+release
+          ▼
+[Gitea Release + Tag]
+```
+
+---
+
+## 9. 语言约定
+
+所有生成内容（Issue 标题/正文、Wiki 页面、标签描述、PR 描述、发布说明）采用用户指定的语言：
+
+- 用户说"用中文同步" → 全部中文。
+- 用户说"sync in English" → 全部英文。
+- 用户未指定 → 沿用源产物的语言。
+
+技术标识符（`chunk/`、`iteration/`、`type/` 前缀等）除非另有说明，保持英文。
+
+---
+
+*本页面由 Octopus `gitea-sync` 能力生成并维护。真相源始终是 `.artifacts/{slug}/` 目录下的原始产物文件。*