sdd-skills 1.0.0

package/docs/workflow-guide.md

@@ -0,0 +1,836 @@
+# SDD 工作流指南
+
+本文档详细介绍 SDD (Spec-Driven Development) 工作流的完整流程。
+
+## 目录
+
+- [工作流概述](#工作流概述)
+- [角色说明](#角色说明)
+- [完整流程](#完整流程)
+- [Pre-Execution Review](#pre-execution-review)
+- [实施阶段](#实施阶段)
+- [质量保障](#质量保障)
+- [钉钉通知](#钉钉通知)
+- [最佳实践](#最佳实践)
+- [常见问题](#常见问题)
+
+---
+
+## 工作流概述
+
+SDD 工作流是一个规格书驱动的开发流程，通过多个专业角色协作完成软件开发全生命周期。
+
+### 核心理念
+
+1. **规格先行**: 先定义详细的技术规格，再开始编码
+2. **角色分工**: 每个角色专注于特定领域的工作
+3. **质量内建**: 在开发过程中持续验证质量
+4. **反馈及时**: 失败时立即通知，快速修复
+
+### 工作流阶段
+
+```
+用户需求
+    ↓
+Pre-Execution Review (多角色讨论)
+    ↓
+SAE (需求分析 + 架构设计)
+    ↓
+Backend/Frontend Engineer (OpenSpec + 代码实现 + 验证)
+    ↓
+Tester (测试验证)
+    ↓
+Code Reviewer (代码审查)
+    ↓
+Git Engineer (预检测 + 提交 + MR)
+    ↓
+完成 (等待 MR 批准)
+```
+
+---
+
+## 角色说明
+
+### 1. SAE (Software Architecture Engineer)
+
+**职责**: 需求分析、架构设计、技术方案
+
+**输出**:
+- 需求规格文档 (`specs/requirements/[feature-name].md`)
+- 技术方案设计
+- 前后端接口契约
+- 验收标准
+
+**关键能力**:
+- 5W1H 需求分析
+- 系统架构设计
+- 技术选型评估
+- 风险识别
+
+### 2. Backend Engineer
+
+**职责**: 后端 API 设计与实现 (Golang)
+
+**输出**:
+- 后端 OpenSpec
+- API 接口实现
+- 数据库设计
+- 单元测试 (覆盖率 >= 90%)
+
+**技术栈**:
+- Go 1.21+, Gin 框架
+- PostgreSQL/MySQL, Redis
+- GORM, testify
+
+### 3. Frontend Engineer
+
+**职责**: 前端组件与交互实现 (Vue)
+
+**输出**:
+- 前端 OpenSpec
+- 页面和组件实现
+- 状态管理 (Pinia)
+- 单元测试 (覆盖率 >= 70%)
+
+**技术栈**:
+- Vue 3, Composition API
+- Pinia, Vue Router
+- Vite, Vitest, Playwright
+
+### 4. Tester
+
+**职责**: 测试验证和质量保障
+
+**输出**:
+- 测试报告
+- 覆盖率报告
+- E2E 测试结果
+- 验收标准检查
+
+**验证内容**:
+- 后端单元测试 + 覆盖率
+- 前端单元测试 + 覆盖率
+- E2E 测试
+- 性能测试 (可选)
+
+### 5. Code Reviewer
+
+**职责**: 代码质量、安全审查
+
+**输出**:
+- 代码审查报告
+- 问题清单 (严重/中等/轻微)
+- 修复建议
+
+**审查内容**:
+- 代码质量 (规范、可维护性)
+- 安全性 (SQL 注入、XSS、认证授权)
+- 性能 (N+1 查询、缓存策略)
+- 最佳实践
+
+### 6. Git Engineer
+
+**职责**: 代码提交、版本管理、MR 创建
+
+**输出**:
+- 规范化的 Git 提交
+- GitLab Merge Request
+- CI/CD 流水线验证
+
+**工作内容**:
+- 预检测 (lint, build, test)
+- Conventional Commits 提交规范
+- MR 创建和审查人指定
+
+### 7. Notifier
+
+**职责**: 钉钉通知发送
+
+**输出**:
+- 失败告警通知
+- 成功事件通知 (可选)
+
+**触发场景**:
+- 测试失败
+- 代码审查不通过
+- 预检测失败
+- MR 创建成功
+
+---
+
+## 完整流程
+
+### 阶段 0: Pre-Execution Review
+
+**目的**: 在开始实施前，多角色讨论需求的可行性、复杂度和风险。
+
+**参与角色**: 所有角色
+
+**讨论内容**:
+- SAE: 需求清晰度、架构复杂度
+- Backend Engineer: 技术可行性、性能评估
+- Frontend Engineer: UI/UX 复杂度、组件设计
+- Tester: 测试策略、环境需求
+- Code Reviewer: 潜在风险、安全关注
+- Git Engineer: CI/CD 兼容性
+
+**输出**: 汇总反馈 + 用户决策
+
+**示例**:
+```
+🗣️ SAE 角度：
+- 需求清晰度：⭐⭐⭐⭐ (需澄清：第三方登录)
+- 架构复杂度：中等
+
+🗣️ Backend Engineer 角度：
+- 技术可行性：高
+- 性能评估：响应时间 < 100ms
+- 依赖风险：需要 Redis
+
+🗣️ Frontend Engineer 角度：
+- UI/UX 复杂度：中等
+- 组件设计：可复用登录表单
+
+...
+
+📋 汇总反馈：整体可行，需澄清 3 个问题...
+```
+
+### 阶段 1: 需求分析 (SAE)
+
+**输入**: 用户原始需求
+
+**工作流程**:
+1. 读取用户需求
+2. 使用 5W1H 分析需求
+3. 使用 AskUserQuestion 澄清模糊点
+4. 探索现有代码库 (Grep/Glob)
+5. 编写需求规格文档
+
+**输出**: `specs/requirements/[feature-name].md`
+
+**关键内容**:
+- 需求概述
+- 功能需求
+- 技术方案
+- 接口设计 (前后端契约)
+- 数据模型
+- 验收标准
+
+### 阶段 2: 后端实现 (Backend Engineer)
+
+**输入**: 需求规格文档
+
+**工作流程**:
+1. 读取需求规格
+2. 调用 `/openspec:proposal` 生成后端 OpenSpec
+3. 等待用户批准 OpenSpec
+4. 调用 `/openspec:apply` 实现代码
+5. **验证检查** (必须通过):
+   - 语法检查 (`go vet`)
+   - 编译检查 (`go build`)
+   - Lint 检查 (`golangci-lint`)
+   - 单元测试 (`go test`)
+   - 覆盖率 >= 90%
+6. 提交代码到特性分支
+
+**输出**:
+- 后端 OpenSpec
+- API 接口代码
+- 单元测试
+- 数据库迁移 (如需要)
+
+### 阶段 3: 前端实现 (Frontend Engineer)
+
+**输入**: 需求规格文档
+
+**工作流程**:
+1. 读取需求规格
+2. 调用 `/openspec:proposal` 生成前端 OpenSpec
+3. 等待用户批准 OpenSpec
+4. 调用 `/openspec:apply` 实现代码
+5. **验证检查** (必须通过):
+   - 类型检查 (`npm run type-check`)
+   - 编译检查 (`npm run build`)
+   - Lint 检查 (`npm run lint`)
+   - 单元测试 (`npm run test:unit`)
+   - 覆盖率 >= 70%
+6. 提交代码到特性分支
+
+**输出**:
+- 前端 OpenSpec
+- 页面和组件代码
+- Pinia stores
+- 单元测试
+
+### 阶段 4: 测试验证 (Tester)
+
+**输入**: 后端和前端代码实现
+
+**工作流程**:
+1. 读取需求规格和 OpenSpec
+2. 执行后端测试:
+   - 单元测试
+   - 集成测试
+   - 覆盖率检查 (>= 90%)
+3. 执行前端测试:
+   - 单元测试
+   - E2E 测试 (Playwright)
+   - 覆盖率检查 (>= 70%)
+4. 验收标准检查
+5. 生成测试报告
+
+**成功**: 交给 Code Reviewer
+**失败**: 返回对应 Engineer + 发送钉钉通知
+
+**输出**:
+- 测试报告
+- 覆盖率报告
+
+### 阶段 5: 代码审查 (Code Reviewer)
+
+**输入**: 通过测试的代码
+
+**工作流程**:
+1. 读取需求规格和 OpenSpec
+2. 获取变更文件列表 (`git diff`)
+3. 执行自动化检查:
+   - 后端: `golangci-lint`, `gosec`
+   - 前端: `npm run lint`, `npm audit`
+4. 人工审查:
+   - 代码质量
+   - 安全性 (OWASP Top 10)
+   - 性能
+   - 可维护性
+5. 生成审查报告
+
+**成功**: 交给 Git Engineer
+**失败**: 返回对应 Engineer + 发送钉钉通知
+
+**输出**:
+- 代码审查报告
+- 问题清单 (如有)
+
+### 阶段 6: 提交和 MR (Git Engineer)
+
+**输入**: 通过审查的代码
+
+**工作流程**:
+1. 执行预检测:
+   - 后端: lint, build, test, coverage
+   - 前端: lint, build, test, coverage
+2. 提交代码 (Conventional Commits 规范)
+3. 推送到远程分支
+4. 创建 GitLab Merge Request (使用 `glab`)
+5. 指定审查人和标签
+
+**成功**: 工作流完成 + 发送钉钉通知 (可选)
+**失败**: 返回对应 Engineer + 发送钉钉通知
+
+**输出**:
+- Git 提交
+- GitLab MR
+
+---
+
+## Pre-Execution Review
+
+### 为什么需要 Pre-Execution Review?
+
+1. **早期发现问题**: 在编码前识别技术风险
+2. **多角度评估**: 不同角色提供专业视角
+3. **降低返工**: 减少后期修改成本
+4. **统一理解**: 确保所有角色对需求理解一致
+
+### Review 流程
+
+1. **SAE 首先发言**:
+   - 评估需求清晰度
+   - 识别需要澄清的问题
+   - 评估架构复杂度
+
+2. **Backend Engineer**:
+   - 技术可行性
+   - 性能预估
+   - 依赖风险
+
+3. **Frontend Engineer**:
+   - UI/UX 复杂度
+   - 组件可复用性
+   - 状态管理策略
+
+4. **Tester**:
+   - 测试策略
+   - 是否需要特殊测试环境
+   - E2E 测试场景完整性
+
+5. **Code Reviewer**:
+   - 潜在安全风险
+   - 性能瓶颈预判
+   - 可维护性挑战
+
+6. **Git Engineer**:
+   - CI/CD 兼容性
+   - 分支策略
+   - MR 审查流程
+
+7. **汇总反馈**:
+   - 整合所有角色的反馈
+   - 提出澄清问题
+   - 给出整体可行性评估
+
+8. **用户决策**:
+   - 回答澄清问题
+   - 决定是否继续
+
+### Review 模板
+
+```markdown
+📍 Pre-Execution Review
+
+## 需求概述
+[简要描述需求]
+
+---
+
+🗣️ SAE 角度：
+- 需求清晰度：⭐⭐⭐⭐ (1-5星)
+- 需要澄清：[问题列表]
+- 架构复杂度：[低/中/高]
+
+🗣️ Backend Engineer 角度：
+- 技术可行性：[高/中/低]
+- 性能评估：[预估指标]
+- 依赖风险：[新依赖？版本兼容？]
+
+🗣️ Frontend Engineer 角度：
+- UI/UX 复杂度：[低/中/高]
+- 组件设计：[可复用性评估]
+- 状态管理：[策略建议]
+
+🗣️ Tester 角度：
+- 测试复杂度：[低/中/高]
+- 环境需求：[特殊环境？]
+- E2E 场景：[场景完整性]
+
+🗣️ Code Reviewer 角度：
+- 潜在风险：[安全、性能等]
+- 技术债务：[可能引入的债务]
+
+🗣️ Git Engineer 角度：
+- CI/CD 兼容性：[是否需要调整？]
+- 分支策略：[建议]
+
+---
+
+📋 汇总反馈：
+- 整体可行性：[高/中/低]
+- 需澄清问题：[列表]
+- 主要风险：[列表]
+- 建议操作：[继续/暂缓/调整方案]
+```
+
+---
+
+## 实施阶段
+
+### OpenSpec 工作流
+
+每个 Engineer 角色都使用 OpenSpec 来管理设计和实现：
+
+1. **Proposal (规划)**:
+   ```bash
+   /openspec:proposal
+   ```
+   - 生成详细的实现规格
+   - 包含接口定义、数据模型、测试用例
+   - 等待用户批准
+
+2. **Apply (实施)**:
+   ```bash
+   /openspec:apply
+   ```
+   - 基于批准的 OpenSpec 实现代码
+   - 确保实现符合规格
+   - 包含测试代码
+
+3. **Archive (归档)**:
+   ```bash
+   /openspec:archive
+   ```
+   - 功能上线后归档 OpenSpec
+   - 更新项目文档
+
+### 验证检查清单
+
+#### Backend Engineer
+```bash
+cd backend
+
+# 1. 语法检查
+go vet ./...
+
+# 2. 编译检查
+go build ./...
+
+# 3. Lint 检查
+golangci-lint run
+
+# 4. 单元测试
+go test ./... -v
+
+# 5. 覆盖率 (>= 90%)
+go test ./... -coverprofile=coverage.out
+go tool cover -func=coverage.out | grep total
+```
+
+#### Frontend Engineer
+```bash
+cd frontend
+
+# 1. 类型检查
+npm run type-check
+
+# 2. 编译检查
+npm run build
+
+# 3. Lint 检查
+npm run lint
+
+# 4. 单元测试
+npm run test:unit
+
+# 5. 覆盖率 (>= 70%)
+npm run test:coverage
+```
+
+---
+
+## 质量保障
+
+### 测试策略
+
+#### 1. 单元测试
+
+**后端** (Go):
+```go
+func TestUserService_CreateUser(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   CreateUserRequest
+        wantErr bool
+    }{
+        {"valid user", CreateUserRequest{Email: "test@example.com"}, false},
+        {"invalid email", CreateUserRequest{Email: "invalid"}, true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := service.CreateUser(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("error = %v, wantErr %v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**前端** (Vue + Vitest):
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/vue'
+import LoginForm from '@/components/LoginForm.vue'
+
+describe('LoginForm', () => {
+  it('renders login form', () => {
+    render(LoginForm)
+    expect(screen.getByLabelText('Email')).toBeInTheDocument()
+  })
+})
+```
+
+#### 2. 集成测试
+
+**后端 API 测试**:
+```go
+func TestAuthAPI_Login(t *testing.T) {
+    router := setupRouter()
+    w := httptest.NewRecorder()
+
+    body := `{"email":"test@example.com","password":"password123"}`
+    req, _ := http.NewRequest("POST", "/api/v1/auth/login", strings.NewReader(body))
+    req.Header.Set("Content-Type", "application/json")
+
+    router.ServeHTTP(w, req)
+
+    assert.Equal(t, 200, w.Code)
+}
+```
+
+#### 3. E2E 测试
+
+**前端 E2E (Playwright)**:
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user login flow', async ({ page }) => {
+  await page.goto('/login')
+  await page.fill('input[name="email"]', 'test@example.com')
+  await page.fill('input[name="password"]', 'password123')
+  await page.click('button[type="submit"]')
+
+  await expect(page).toHaveURL('/dashboard')
+})
+```
+
+### 代码审查清单
+
+#### 安全检查 (OWASP Top 10)
+- [ ] SQL 注入防护 (参数化查询)
+- [ ] XSS 防护 (输出转义)
+- [ ] 密码加密存储 (bcrypt)
+- [ ] 认证授权机制
+- [ ] CORS 配置正确
+- [ ] 敏感信息不泄露
+
+#### 性能检查
+- [ ] 无 N+1 查询
+- [ ] 数据库索引合理
+- [ ] 大数据量分页
+- [ ] 热点数据缓存
+- [ ] 前端组件懒加载
+
+#### 可维护性检查
+- [ ] 代码结构清晰
+- [ ] 函数职责单一
+- [ ] 无魔法数字
+- [ ] 无重复代码
+- [ ] 测试覆盖率达标
+
+---
+
+## 钉钉通知
+
+### 配置钉钉 Webhook
+
+1. **创建钉钉机器人**:
+   - 在钉钉群中添加"自定义机器人"
+   - 安全设置选择"自定义关键词"
+   - 添加关键词：**SDD**
+   - 复制 Webhook URL
+
+2. **配置文件**:
+   - 全局: `~/.claude/dingtalk-config.json`
+   - 项目: `<project>/.claude/dingtalk-config.json`
+
+3. **配置内容**:
+   ```json
+   {
+     "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN",
+     "notify_on": ["failure", "success"],
+     "enabled": true
+   }
+   ```
+
+### 通知场景
+
+#### 失败通知 (自动发送)
+- Tester 测试失败
+- Code Reviewer 审查不通过
+- Git Engineer 预检测失败
+- Backend/Frontend Engineer 验证失败
+
+#### 成功通知 (可选)
+- Git Engineer MR 创建成功
+- 整个工作流完成
+
+### 通知示例
+
+**测试失败**:
+```
+❌ SDD 工作流失败
+
+- 工作流: user-login
+- 失败阶段: Tester
+- 失败详情:
+  - 后端测试失败：2/12
+  - 覆盖率不达标：85% (要求 >= 90%)
+- 建议操作: 返回 Backend Engineer 修复
+
+🕐 时间: 2026-01-06 14:30:00
+```
+
+**代码审查不通过**:
+```
+❌ SDD 代码审查不通过
+
+- 工作流: user-login
+- 失败阶段: Code Reviewer
+- 问题统计:
+  - 严重问题：2 个
+  - 中等问题：1 个
+- 主要问题:
+  - 密码明文存储（严重）
+  - N+1 查询问题（严重）
+- 建议操作: 返回 Backend Engineer 修复
+
+🕐 时间: 2026-01-06 15:00:00
+```
+
+**MR 创建成功**:
+```
+✅ SDD MR 已创建
+
+- 工作流: user-login
+- MR 标题: feat(auth): Add user login functionality
+- MR 链接: https://git.in.chaitin.net/project/-/merge_requests/1
+- 审查人: @reviewer1
+
+🕐 时间: 2026-01-06 16:30:00
+```
+
+---
+
+## 最佳实践
+
+### 1. 需求分析
+
+- ✅ 使用 5W1H 方法全面分析需求
+- ✅ 主动澄清模糊点，不要猜测
+- ✅ 明确前后端职责边界
+- ✅ 定义清晰的验收标准
+
+### 2. 代码实现
+
+- ✅ 先通过验证检查再流转下一阶段
+- ✅ 遵循语言和框架的最佳实践
+- ✅ 编写有意义的测试用例
+- ✅ 达到覆盖率要求 (后端 90%, 前端 70%)
+
+### 3. 测试验证
+
+- ✅ 对照验收标准逐项检查
+- ✅ 运行所有自动化测试
+- ✅ 验证性能指标 (响应时间 < 200ms)
+- ✅ 检查安全性 (SQL 注入、XSS 等)
+
+### 4. 代码审查
+
+- ✅ 使用自动化工具辅助审查
+- ✅ 重点关注安全和性能问题
+- ✅ 提供具体的修复建议
+- ✅ 严重问题必须修复后才能通过
+
+### 5. 提交规范
+
+- ✅ 遵循 Conventional Commits 规范
+- ✅ 提交消息清晰描述变更内容
+- ✅ MR 描述包含功能概述、测试结果、验收标准
+- ✅ 指定合适的审查人
+
+---
+
+## 常见问题
+
+### Q1: 如果验证检查失败怎么办？
+
+**答**:
+1. 查看失败详情 (语法错误、测试失败、覆盖率不达标等)
+2. 修复所有问题
+3. 重新运行验证检查
+4. 通过后才能进入下一阶段
+
+### Q2: 测试覆盖率不达标怎么办？
+
+**答**:
+1. 使用覆盖率报告查看未覆盖的代码
+2. 补充测试用例覆盖未测试的分支
+3. 重新运行测试并检查覆盖率
+4. 后端要求 >= 90%, 前端要求 >= 70%
+
+### Q3: 代码审查不通过怎么办？
+
+**答**:
+1. 仔细阅读审查报告中的问题清单
+2. 根据修复建议修改代码
+3. 严重问题必须修复，中等问题建议修复
+4. 修复后重新提交给 Code Reviewer
+
+### Q4: 如何处理 N+1 查询问题？
+
+**答** (后端 Go + GORM):
+```go
+// ❌ N+1 查询
+for _, user := range users {
+    db.Model(&user).Association("Orders").Find(&user.Orders)
+}
+
+// ✅ 使用 Preload
+db.Preload("Orders").Find(&users)
+```
+
+### Q5: 如何避免 SQL 注入？
+
+**答**:
+```go
+// ❌ 危险：SQL 拼接
+query := "SELECT * FROM users WHERE email = '" + email + "'"
+
+// ✅ 安全：参数化查询
+db.Where("email = ?", email).First(&user)
+```
+
+### Q6: 如何避免 XSS 攻击？
+
+**答** (前端 Vue):
+```vue
+<!-- ❌ 危险：v-html -->
+<div v-html="userInput"></div>
+
+<!-- ✅ 安全：自动转义 -->
+<div>{{ userInput }}</div>
+```
+
+### Q7: 钉钉通知发送失败怎么办？
+
+**答**:
+1. 检查 Webhook URL 是否正确
+2. 确认消息包含 "SDD" 关键字
+3. 检查发送频率 (避免过于频繁)
+4. 运行测试脚本验证配置
+
+### Q8: 如何跳过某个阶段？
+
+**答**: 不建议跳过阶段。每个阶段都有其重要的质量保障作用。如果确实需要调整流程，建议与团队讨论后修改工作流定义。
+
+### Q9: 多个功能并行开发怎么办？
+
+**答**:
+1. 为每个功能创建独立的特性分支
+2. 每个功能独立走完整的 SDD 流程
+3. 避免分支间的代码冲突
+4. 合并时按优先级顺序进行
+
+### Q10: 如何查看工作流状态？
+
+**答**:
+1. 查看钉钉通知了解失败阶段
+2. 查看 Git 分支了解代码提交状态
+3. 查看 GitLab MR 了解审查进度
+4. 查看 OpenSpec 变更了解实施计划
+
+---
+
+## 总结
+
+SDD 工作流通过多角色协作、质量内建和及时反馈，确保软件开发的高质量和高效率。
+
+关键要素：
+- ✅ Pre-Execution Review 提前识别风险
+- ✅ OpenSpec 驱动实施
+- ✅ 验证检查确保质量
+- ✅ 自动化测试保障功能
+- ✅ 代码审查提升质量
+- ✅ 钉钉通知及时反馈
+
+遵循 SDD 工作流，享受高效、高质量的开发体验！