@miniidealab/openlogos 0.5.0 → 0.5.3

package/spec/workflow.md

@@ -0,0 +1,277 @@
+# 研发工作流定义
+
+> 版本：0.3.0
+>
+> 本文档定义 OpenLogos 的三层推进工作流：WHY → WHAT → HOW。这是方法论的核心骨架，所有 Skills 和工具都围绕这个工作流设计。
+
+## 核心设计：场景贯穿
+
+**场景（Scenario）是贯穿整个研发生命周期的锚。** 同一个场景在三个 Phase 中被逐层展开：
+
+```
+场景 S01: 邮箱注册
+
+Phase 1 (WHY)  → 谁需要？解决什么痛点？正常/异常预期是什么？
+Phase 2 (WHAT) → 用户看到什么页面？交互流程是什么？状态怎么变？
+Phase 3 (HOW)  → 系统调用链是什么？API 是什么？DB 怎么写？怎么测？
+```
+
+场景编号（`S01`, `S02`...）全局唯一，从 Phase 1 定义开始，一路带到 Phase 3 验收完成。不需要额外维护追溯矩阵——场景本身就是追溯链。
+
+## 总览
+
+```
+Phase 1: WHY — 为什么做
+├── 用户研究 → 痛点提炼 → 场景识别 → 优先级排序
+├── 产出：需求文档（场景驱动 + GIVEN/WHEN/THEN 验收条件）
+└── 质量门禁 → Gate 1
+
+Phase 2: WHAT — 做什么
+├── 信息架构 → 场景交互细化 → 功能规格 → HTML 原型
+├── 产出：产品设计文档 + HTML 原型（按场景组织）
+└── 质量门禁 → Gate 2
+
+Phase 3: HOW — 如何做
+├── Step 0: 技术架构概要（整体架构、技术选型、部署拓扑）
+├── Step 1: 场景 → 时序图 → API 浮现
+├── Step 2: API 细节设计 → DB 推导
+├── Step 3: 测试设计（测试先行）
+│   ├── 3a: 单元测试 + 场景测试用例设计（所有项目）
+│   └── 3b: API 编排测试设计（仅 API 项目）
+├── Step 4: AI 驱动代码生成 + 测试代码
+├── Step 5: 测试验收（openlogos verify 自动化判定）
+└── 质量门禁 → Gate 3.0 ~ Gate 3.5
+```
+
+## 场景编号规则
+
+- **格式**：`S{两位数字}`，如 `S01`、`S02`
+- **子场景**：当 Phase 2/3 中发现场景需要拆分时，使用 `S01.1`、`S01.2` 格式
+- **全局唯一**：一个场景编号在整个项目生命周期中始终对应同一件事
+- **场景 ≠ 功能**：一个功能可能涉及多个场景，一个场景可能跨多个功能
+
+## Phase 1: WHY — 需求层
+
+### 目标
+
+搞清楚要解决什么问题，识别核心业务场景，为每个场景定义业务层面的验收条件。
+
+### 工作内容
+
+1. **用户研究**：理解目标用户、痛点、使用场景
+2. **痛点提炼**：每条痛点有因果链（原因 → 痛点 → 后果）
+3. **场景识别**：将痛点和需求转化为具体的用户场景，分配场景编号
+4. **优先级排序**：按场景排列优先级（P0 / P1 / P2）
+5. **验收条件编写**：为每个核心场景编写 GIVEN/WHEN/THEN
+
+### 产出物
+
+需求文档，标准结构：
+
+- 产品背景与目标（定位、核心目标、用户画像）—— 全局
+- 用户痛点分析（因果链格式）—— 全局
+- 核心场景定义（场景表 + 每个场景的验收条件）—— **场景驱动**
+- 约束与边界（技术/资源约束 + "不做"清单）—— 全局
+
+### 场景定义格式（Phase 1 粒度）
+
+```markdown
+### S01: 场景名称
+
+- **触发条件**：谁在什么情况下进入这个场景
+- **用户价值**：解决什么痛点（追溯痛点编号）
+- **优先级**：P0
+- **主路径**：[自然语言描述正常流程]
+
+#### 验收条件
+
+##### 正常：[场景名称]
+- **GIVEN** [初始条件]
+- **WHEN** [用户操作]
+- **THEN** [期望结果]
+
+##### 异常：[异常场景名称]
+- **GIVEN** [初始条件]
+- **WHEN** [操作] + [异常触发]
+- **THEN** [错误处理行为]
+```
+
+### Gate 1 检查项
+
+- [ ] 每条痛点有因果链
+- [ ] 核心场景已识别并编号（`S01`, `S02`...）
+- [ ] 每个 P0/P1 场景有 GIVEN/WHEN/THEN 验收条件（至少 1 正常 + 1 异常）
+- [ ] 目标用户画像具体到可描述一个真实的人
+- [ ] 场景优先级已排序
+- [ ] "不做"清单明确
+
+## Phase 2: WHAT — 产品设计层
+
+### 目标
+
+设计具体的解决方案。以 Phase 1 的场景为骨架，为每个场景细化交互流程、页面设计和功能规格。
+
+### 工作内容
+
+1. **信息架构设计**：产品结构、导航层级、内容组织
+2. **场景交互细化**：为每个场景定义完整的页面流转和交互细节
+3. **功能规格撰写**：每个场景涉及的功能的详细描述 + 交互级 GIVEN/WHEN/THEN
+4. **HTML 原型设计**：使用 AI 直接生成 HTML 页面作为产品原型
+5. **设计规范制定**：全局 UI 规范
+
+### 产出物
+
+- 产品设计文档（信息架构 + 功能规格，按场景组织）
+- HTML 产品原型
+- 全局设计规范
+
+### 场景展开（Phase 2 粒度）
+
+Phase 2 在 Phase 1 场景的基础上增加交互细节：
+
+- 涉及哪些页面 / 组件
+- 页面间跳转逻辑
+- 表单字段和校验规则
+- 各种状态（加载、空、错误）的展示
+- 更精细的 GIVEN/WHEN/THEN（精确到按钮和 UI 元素级别）
+
+如果 Phase 1 的一个场景过大，此阶段可以拆分为子场景（`S01.1`, `S01.2`）。
+
+### Gate 2 检查项
+
+- [ ] 每个 P0/P1 场景有详细的交互规格 + GIVEN/WHEN/THEN 验收条件
+- [ ] 所有核心页面有 HTML 原型
+- [ ] 异常情况已考虑（错误 / 空 / 加载状态）
+- [ ] 场景编号与 Phase 1 一致（可有子场景拆分）
+
+## Phase 3: HOW — 技术实现层
+
+### Step 0: 技术架构概要
+
+在进入逐场景的技术实现之前，先建立项目的技术全局视图。这一步确保后续的时序图、API 设计和代码生成都在一致的架构约束下进行。
+
+**工作内容**：
+
+1. **系统架构图**：绘制整体架构拓扑（前端、后端、数据库、第三方服务、消息队列等），明确系统边界和交互方式
+2. **技术选型清单**：语言、框架、数据库、部署方式等核心决策，每项附选型理由
+3. **部署拓扑**：开发 / 测试 / 生产环境的部署方案
+4. **非功能性约束**：性能目标、安全要求、可扩展性、可观测性等
+5. **更新 `logos-project.yaml`**：将确定的技术栈写入 `tech_stack` 字段
+
+**产出物**：
+
+- 架构概要文档：`logos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md`
+- `logos-project.yaml` 的 `tech_stack` 字段已更新
+
+**适用策略**：
+
+- 简单项目（单体 + 单数据库）：用一段文字 + 一张简图即可，不需要长篇大论
+- 复杂项目（微服务、多数据库、消息队列）：需要详细的架构决策记录
+
+**Gate 3.0**：架构概要文档完成，技术栈已确认并写入 `logos-project.yaml`。
+
+### Step 1: 场景建模（时序图）
+
+将 Phase 1/2 的场景展开为 Mermaid 时序图。时序图中的跨系统调用箭头就是需要的 API。时序图的参与方应与 Step 0 架构图中的系统组件一致。
+
+**时序图规范**：
+- 每个箭头带 `Step N:` 编号前缀
+- 每个箭头附一行行为描述
+- 参与方明确标注系统组件
+- 文档标题保留场景编号：`S01: 邮箱注册 — 时序图`
+
+**Gate 3.1**：所有核心场景时序图完成，API 端点清晰可见。
+
+### Step 2: API 细节设计 → DB 推导
+
+基于时序图浮现的 API 端点，设计详细规格（OpenAPI 3.0 YAML）。API 的请求/响应结构确定后，DB 表结构自然推导。
+
+**Gate 3.2**：API YAML 和 DB DDL 完成，相互一致。
+
+### Step 3: 测试设计（测试先行）
+
+在写代码之前，先设计完整的测试体系。测试设计分为两个子步骤，覆盖三层测试金字塔：
+
+#### Step 3a: 单元测试 + 场景测试用例设计（所有项目）
+
+**适用范围**：所有项目类型（API 服务、CLI 工具、前端应用、库等），不可跳过。
+
+为每个场景设计两类测试用例：
+
+- **单元测试用例**：针对单个函数/方法的输入输出正确性
+  - 来源：API 字段约束（类型、格式、长度）、DB 约束（UNIQUE、CHECK、NOT NULL）、业务规则、EX 异常用例中的单点错误处理
+  - 关注：边界值、无效输入、异常返回
+
+- **场景测试用例**：针对完整场景流程在代码层面的串联
+  - 来源：时序图 Step 序列（主路径）、EX 异常用例（异常路径）、Phase 1/2 验收条件
+  - 关注：跨模块调用链的正确性、数据在 Step 间的传递、异常发生时的补偿/回滚逻辑
+
+**产出物**：测试用例规格文档（Markdown），存放在 `logos/resources/test/`，按场景分文件（如 `S01-test-cases.md`）。
+
+**Gate 3.3a**：核心场景的单元测试和场景测试用例已设计，覆盖所有 P0 场景的正常路径 + 核心 EX 异常路径。
+
+#### Step 3b: API 编排测试设计（仅 API 项目）
+
+**适用范围**：涉及 API 的项目。纯 CLI 工具、前端库等不涉及 API 的项目可跳过此步骤。
+
+为每个场景设计 API 编排测试用例：
+
+- **正常流程编排**：主路径的 API 调用链
+- **异常流程编排**：`EX-{步骤编号}.{序号}` 格式
+- **边界用例**：合法但非主路径的变体
+
+**产出物**：编排测试文件（JSON），存放在 `logos/resources/scenario/`。
+
+**Gate 3.3b**：编排覆盖所有正常流程 + 核心异常流程。
+
+### Step 4: AI 驱动代码生成 + 测试代码
+
+AI 面前已有完整上下文（原型 + 场景 + API + DB + 测试用例 + 编排），此时生成的代码质量远高于直接写代码。按场景逐个生成、逐个验证。
+
+代码生成同时包括：
+- **业务代码**：按时序图 Step 逐步实现
+- **单元测试代码**：基于 Step 3a 的单元测试用例规格实现
+- **场景测试代码**：基于 Step 3a 的场景测试用例规格实现
+
+**Gate 3.4**：代码已审核，单元测试通过，已部署测试环境。
+
+### Step 5: 测试验收
+
+运行所有测试来验证代码，使用 `openlogos verify` 自动化判定验收结果。
+
+**验收流程**：
+
+1. AI 在 Step 4 生成测试代码时，内嵌 OpenLogos reporter（见 [test-results.md](./test-results.md)）
+2. 用户运行测试（`npm test`、`pytest` 等）→ reporter 自动将每个用例的结果写入 `logos/resources/verify/test-results.jsonl`（JSONL 格式）
+3. 用户运行 `openlogos verify` → CLI 读取 JSONL + `logos/resources/test/*.md` 中的用例 ID → 自动计算验收结果
+
+**验收三层判定**：
+
+- **覆盖度**：JSONL 中出现的用例 ID / test-cases.md 中定义的全部用例 ID
+- **通过率**：status=pass 的用例数 / JSONL 中的总用例数
+- **需求追溯**（可选）：test-cases.md 中声明的覆盖范围是否覆盖 Phase 1 验收条件
+
+**验收结果**：
+
+- 全部通过 → 生成 `logos/resources/verify/acceptance-report.md`，终端输出 PASS
+- 有失败或未覆盖 → 生成报告并列出问题项，终端输出 FAIL，退出码为 1
+
+**Gate 3.5**：`openlogos verify` 输出 PASS（所有用例通过 + 覆盖度 100%）。
+
+## 场景的三级展开
+
+同一个场景在三个 Phase 中逐层细化：
+
+| Phase | 视角 | 关注点 | 验收粒度 |
+|-------|------|--------|---------|
+| Phase 1 | 业务 | 谁需要？为什么？期望什么结果？ | 业务行为级 GIVEN/WHEN/THEN |
+| Phase 2 | 交互 | 看到什么？怎么操作？状态怎么变？ | UI 元素级 GIVEN/WHEN/THEN |
+| Phase 3 | 技术 | 调用链是什么？接口返回什么？数据库写什么？ | 三层测试（单元 + 场景 + 编排）+ `openlogos verify` 自动化验收 |
+
+三层验收条件逐层细化，最终在 Phase 3 的测试中变成可自动执行的验证：单元测试覆盖函数级正确性，场景测试覆盖跨模块流程，API 编排测试覆盖端到端调用链。测试结果通过标准化的 JSONL 格式（见 [test-results.md](./test-results.md)）输出，`openlogos verify` 自动读取并生成验收报告。不需要额外的追溯矩阵——**场景编号就是追溯链，用例 ID 就是验收锚点**。
+
+## 迭代规则
+
+功能迭代**必须**按同样的分层工作流推进，使用 Delta 变更管理（详见 [change-management.md](./change-management.md)）。不允许跳过中间环节直接改代码。
+
+迭代可能导致场景变更：新增场景、修改已有场景、废弃场景。所有变更通过 `logos/changes/` 提案管理，场景编号一旦分配不复用。