sdd-skills 1.0.2 → 1.1.1

package/docs/workflow-guide.md

@@ -36,17 +36,23 @@ Pre-Execution Review (多角色讨论)
     ↓
 SAE (需求分析 + 架构设计)
     ↓
-Backend/Frontend Engineer (OpenSpec + 代码实现 + 验证)
-    ↓
-Tester (测试验证)
-    ↓
-Code Reviewer (代码审查)
-    ↓
-Git Engineer (预检测 + 提交 + MR)
-    ↓
-完成 (等待 MR 批准)
+    ├─→ Backend Engineer (OpenSpec + 代码实现 + 验证) ─┐
+    │                                                │
+    └─→ Frontend Engineer (OpenSpec + 代码实现 + 验证)─┘
+                    ↓
+              (前后端并行开发)
+                    ↓
+            Tester (测试验证)
+                    ↓
+         Code Reviewer (代码审查)
+                    ↓
+     Git Engineer (预检测 + 提交 + MR)
+                    ↓
+            完成 (等待 MR 批准)
 ```
 
+**注意**: Backend 和 Frontend Engineer 可以并行开发，通过 API 契约协作，无需等待对方完成。
+
 ---
 
 ## 角色说明
@@ -217,6 +223,10 @@ Git Engineer (预检测 + 提交 + MR)
 - 数据模型
 - 验收标准
 
+### 阶段 2-3: 前后端并行实现
+
+**重要**: Backend 和 Frontend Engineer 可以并行开发，通过 SAE 定义的 API 契约协作。前端可以使用 Mock 数据进行开发，后端提供符合契约的 API 实现。
+
 ### 阶段 2: 后端实现 (Backend Engineer)
 
 **输入**: 需求规格文档

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-skills",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Spec-Driven Development Skills for Claude Code - SAE/ADE workflow automation",
   "type": "module",
   "main": "install.js",

package/references/backend-review-guide.md

@@ -0,0 +1,363 @@
+# Backend Engineer OpenSpec 评审指南
+
+## 何时需要评审
+
+**仅在以下情况下加载此评审指南**：
+- Backend OpenSpec 已生成，需要评审验证
+- 用户明确要求对后端 OpenSpec 进行评审
+- 代码实现完成，需要对照 OpenSpec 进行符合性评审
+
+## 评审目标
+
+确保后端 OpenSpec 的完整性、正确性、可实施性，验证代码实现符合 OpenSpec 要求。
+
+## 评审检查清单
+
+### 1. API 设计评审
+
+- [ ] **RESTful 规范**: API 设计是否遵循 RESTful 最佳实践？
+- [ ] **HTTP 方法**: GET/POST/PUT/DELETE 使用是否正确？
+- [ ] **URL 设计**: 路径是否清晰？资源命名是否合理？
+- [ ] **版本管理**: 是否有 API 版本控制（如 /api/v1/）？
+- [ ] **幂等性**: PUT/DELETE 操作是否幂等？
+
+**示例检查**:
+```go
+// ❌ 不符合 RESTful
+POST /api/getUserById
+
+// ✅ 符合 RESTful
+GET /api/v1/users/:id
+```
+
+### 2. 请求/响应设计评审
+
+- [ ] **请求参数**: 必需参数和可选参数是否明确？
+- [ ] **参数验证**: 是否定义了参数类型、格式、取值范围？
+- [ ] **响应格式**: 是否统一？包含 code, message, data？
+- [ ] **错误码**: 是否定义了完整的错误码体系？
+- [ ] **分页**: 列表接口是否支持分页？
+
+**响应格式检查**:
+```go
+// ✅ 统一的响应格式
+type Response struct {
+    Code    int         `json:"code"`
+    Message string      `json:"message"`
+    Data    interface{} `json:"data,omitempty"`
+}
+```
+
+### 3. 数据模型评审
+
+- [ ] **表设计**: 表结构是否合理？字段类型是否正确？
+- [ ] **索引设计**: 是否为常用查询字段添加索引？
+- [ ] **外键约束**: 关系是否正确定义？
+- [ ] **软删除**: 是否需要软删除？deleted_at 字段是否添加？
+- [ ] **时间戳**: created_at, updated_at 是否添加？
+
+**模型定义检查**:
+```go
+type User struct {
+    ID        uint      `gorm:"primaryKey"`
+    Email     string    `gorm:"uniqueIndex;not null"`
+    Password  string    `gorm:"not null"`
+    Name      string    `gorm:"index"`
+    CreatedAt time.Time
+    UpdatedAt time.Time
+    DeletedAt gorm.DeletedAt `gorm:"index"`
+}
+```
+
+### 4. 业务逻辑评审
+
+- [ ] **Service 层**: 业务逻辑是否正确实现？
+- [ ] **事务处理**: 是否正确使用数据库事务？
+- [ ] **并发安全**: 是否考虑并发访问场景？需要锁吗？
+- [ ] **幂等性**: 重复请求是否会产生副作用？
+- [ ] **状态机**: 状态流转是否正确？
+
+### 5. 安全性评审
+
+- [ ] **认证授权**: JWT/Session 实现是否正确？
+- [ ] **密码安全**: 是否使用 bcrypt 等安全算法加密？
+- [ ] **SQL 注入**: 是否使用参数化查询？
+- [ ] **XSS 防护**: 输出是否转义？
+- [ ] **CSRF 防护**: 是否有 CSRF token 验证？
+- [ ] **敏感信息**: 日志中是否泄露密码、token 等？
+
+**安全检查示例**:
+```go
+// ✅ 正确：参数化查询
+db.Where("email = ?", email).First(&user)
+
+// ❌ 危险：SQL 拼接
+query := "SELECT * FROM users WHERE email = '" + email + "'"
+
+// ✅ 正确：密码加密
+hashedPassword, _ := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+
+// ❌ 危险：明文存储
+user.Password = password
+```
+
+### 6. 性能评审
+
+- [ ] **N+1 查询**: 是否使用 Preload 避免 N+1 查询？
+- [ ] **索引使用**: 查询是否命中索引？
+- [ ] **分页查询**: 大数据量是否使用分页？
+- [ ] **缓存策略**: 热点数据是否使用缓存（Redis）？
+- [ ] **批量操作**: 是否使用批量插入/更新？
+
+**性能优化示例**:
+```go
+// ❌ N+1 查询
+for _, user := range users {
+    db.Model(&user).Association("Orders").Find(&user.Orders)
+}
+
+// ✅ 预加载
+db.Preload("Orders").Find(&users)
+```
+
+### 7. 错误处理评审
+
+- [ ] **错误不忽略**: 是否检查所有 error 返回值？
+- [ ] **错误包装**: 是否使用 fmt.Errorf("%w") 包装错误？
+- [ ] **错误日志**: 是否记录错误日志？
+- [ ] **用户友好**: 错误消息是否用户可读？
+- [ ] **错误分类**: 是否区分系统错误和业务错误？
+
+```go
+// ✅ 正确的错误处理
+if err := db.Create(&user).Error; err != nil {
+    log.Error("Failed to create user", zap.Error(err))
+    return nil, fmt.Errorf("create user failed: %w", err)
+}
+
+// ❌ 忽略错误
+db.Create(&user)
+```
+
+### 8. 测试覆盖评审
+
+- [ ] **单元测试**: 覆盖率是否 >= 90%？
+- [ ] **测试用例**: 是否覆盖正常和异常流程？
+- [ ] **表驱动测试**: 是否使用表驱动测试模式？
+- [ ] **Mock 依赖**: 是否正确 mock 外部依赖？
+- [ ] **集成测试**: 是否有 API 集成测试？
+
+## 评审标准
+
+### ✅ 评审通过标准
+
+1. **API 设计规范**: 遵循 RESTful 规范，URL 设计合理
+2. **数据模型完整**: 表结构、索引、约束定义完整
+3. **安全性达标**: 无 SQL 注入、XSS 等安全漏洞
+4. **性能可接受**: 无 N+1 查询，使用索引和缓存
+5. **错误处理完善**: 所有错误都正确处理和记录
+6. **测试覆盖充分**: >= 90% 单元测试覆盖率
+
+### ❌ 评审不通过场景
+
+1. **安全漏洞**: 存在 SQL 注入、密码明文存储等安全问题
+2. **性能问题**: N+1 查询、缺少索引、未分页
+3. **错误处理缺失**: 忽略 error 返回值
+4. **测试不足**: 覆盖率 < 90%，缺少关键测试用例
+5. **API 设计不规范**: 不符合 RESTful 规范
+
+## 评审流程
+
+### 1. OpenSpec 评审
+
+**检查 OpenSpec 文档**:
+```markdown
+□ API 端点定义完整（方法、路径、参数、响应）
+□ 数据模型定义清晰（字段、类型、约束）
+□ 错误码定义完整
+□ 性能要求明确（响应时间、并发量）
+□ 安全要求明确（认证、授权、加密）
+```
+
+### 2. 代码实现评审
+
+**对照 OpenSpec 检查代码**:
+```markdown
+□ Handler 层实现所有 API 端点
+□ Service 层实现所有业务逻辑
+□ Repository 层实现所有数据访问
+□ Model 定义与 OpenSpec 一致
+□ 测试用例覆盖所有场景
+```
+
+### 3. 安全和性能审查
+
+使用自动化工具:
+```bash
+# 安全扫描
+gosec ./...
+
+# 性能分析
+go test -bench=. -benchmem
+
+# 竞态检测
+go test -race ./...
+```
+
+### 4. 测试覆盖率检查
+
+```bash
+go test ./... -coverprofile=coverage.out
+go tool cover -func=coverage.out | grep total
+
+# 要求: >= 90%
+```
+
+## 评审记录模板
+
+```markdown
+## Backend OpenSpec 评审记录
+
+**评审日期**: YYYY-MM-DD
+**评审人**: [Backend Engineer 姓名]
+**OpenSpec 版本**: v1.0
+
+### API 设计评审
+
+- [ ] RESTful 规范: ✅ 通过 / ❌ 不通过
+- [ ] 请求/响应格式: ✅ 通过 / ❌ 不通过
+- [ ] 错误码定义: ✅ 通过 / ❌ 不通过
+
+**问题列表**:
+1. [问题描述] - [修复建议]
+
+### 安全性评审
+
+- [ ] SQL 注入防护: ✅ 通过 / ❌ 不通过
+- [ ] 密码加密: ✅ 通过 / ❌ 不通过
+- [ ] 认证授权: ✅ 通过 / ❌ 不通过
+
+**问题列表**:
+1. [问题描述] - [修复建议]
+
+### 性能评审
+
+- [ ] N+1 查询: ✅ 无问题 / ❌ 发现问题
+- [ ] 索引使用: ✅ 合理 / ❌ 需优化
+- [ ] 缓存策略: ✅ 合理 / ❌ 需优化
+
+**问题列表**:
+1. [问题描述] - [修复建议]
+
+### 测试评审
+
+- 单元测试覆盖率: [X]%
+- 测试用例数量: [N] 个
+- 集成测试: ✅ 完成 / ❌ 缺失
+
+### 评审结论
+
+- [ ] ✅ 通过，可以进入测试阶段
+- [ ] ⚠️ 有条件通过，修复以下问题后可进入测试
+- [ ] ❌ 不通过，需要重大修订
+
+### 待修复问题
+
+1. [严重] [问题描述] - [修复建议]
+2. [中等] [问题描述] - [修复建议]
+```
+
+## 常见问题和解决方案
+
+### Q1: OpenSpec 与实际实现不一致怎么办？
+
+**解决方案**:
+- 如果 OpenSpec 错误，更新 OpenSpec 并重新评审
+- 如果代码实现错误，修复代码使其符合 OpenSpec
+- 记录变更原因和决策
+
+### Q2: 测试覆盖率达不到 90% 怎么办？
+
+**解决方案**:
+- 使用 `go tool cover -html=coverage.out` 查看未覆盖代码
+- 补充测试用例覆盖关键分支和边界情况
+- 对于不可测试的代码（如初始化代码），可适当豁免
+
+### Q3: 发现性能瓶颈怎么办？
+
+**解决方案**:
+- 使用 `go test -bench` 进行基准测试
+- 使用 `pprof` 分析 CPU 和内存使用
+- 优化数据库查询（索引、预加载、缓存）
+- 考虑异步处理或消息队列
+
+### Q4: 如何评审并发安全性？
+
+**解决方案**:
+- 运行 `go test -race` 检测数据竞争
+- 检查共享状态是否使用 mutex 保护
+- 验证 goroutine 是否正确管理（避免泄漏）
+- 使用 channel 进行安全通信
+
+## 质量标准
+
+### 优秀的 Backend 实现特征
+
+1. **代码规范**: 遵循 Go 代码规范，通过 golangci-lint
+2. **安全可靠**: 无安全漏洞，错误处理完善
+3. **性能优秀**: 响应时间 < 200ms (P95)，无 N+1 查询
+4. **测试充分**: >= 90% 覆盖率，测试用例全面
+5. **可维护**: 代码结构清晰，注释完整
+
+### 需要改进的实现特征
+
+1. **安全问题**: SQL 注入、密码明文、未认证
+2. **性能问题**: N+1 查询、缺少索引、未分页
+3. **错误处理**: 忽略 error，未记录日志
+4. **测试不足**: 覆盖率 < 90%，缺少边界测试
+5. **代码混乱**: 逻辑复杂，缺少注释
+
+## 工具推荐
+
+### 静态分析工具
+
+```bash
+# 代码规范检查
+golangci-lint run
+
+# 安全漏洞扫描
+gosec ./...
+
+# 依赖安全检查
+go list -json -m all | nancy sleuth
+```
+
+### 性能分析工具
+
+```bash
+# 基准测试
+go test -bench=. -benchmem
+
+# CPU profiling
+go test -cpuprofile=cpu.prof
+go tool pprof cpu.prof
+
+# 内存 profiling
+go test -memprofile=mem.prof
+go tool pprof mem.prof
+```
+
+### 测试工具
+
+```bash
+# 覆盖率报告
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out
+
+# 竞态检测
+go test -race ./...
+```
+
+---
+
+**记住**: 高质量的后端代码是系统稳定性的基石。严格的评审能及早发现问题，降低生产环境风险。