sdd-skills 1.0.1 → 1.1.0

package/references/frontend-review-guide.md

@@ -0,0 +1,504 @@
+# Frontend Engineer OpenSpec 评审指南
+
+## 何时需要评审
+
+**仅在以下情况下加载此评审指南**：
+- Frontend OpenSpec 已生成，需要评审验证
+- 用户明确要求对前端 OpenSpec 进行评审
+- 代码实现完成，需要对照 OpenSpec 进行符合性评审
+
+## 评审目标
+
+确保前端 OpenSpec 的完整性、正确性、可实施性，验证代码实现符合 OpenSpec 要求和用户体验标准。
+
+## 评审检查清单
+
+### 1. 组件设计评审
+
+- [ ] **组件划分**: 组件粒度是否合理？职责是否单一？
+- [ ] **可复用性**: 组件是否可复用？是否过度抽象？
+- [ ] **Props 设计**: Props 是否有完整的类型定义？
+- [ ] **Emits 定义**: 事件是否明确定义？
+- [ ] **组件命名**: 是否使用 PascalCase？命名是否语义化？
+
+**Vue 组件检查**:
+```vue
+<!-- ✅ 正确：完整的类型定义 -->
+<script setup lang="ts">
+interface Props {
+  userId: number
+  name: string
+  email?: string
+}
+
+interface Emits {
+  (e: 'update', user: User): void
+  (e: 'delete', id: number): void
+}
+
+const props = defineProps<Props>()
+const emit = defineEmits<Emits>()
+</script>
+```
+
+**React 组件检查**:
+```typescript
+// ✅ 正确：完整的类型定义
+interface UserCardProps {
+  userId: number
+  name: string
+  email?: string
+  onUpdate: (user: User) => void
+  onDelete: (id: number) => void
+}
+
+const UserCard: React.FC<UserCardProps> = ({ userId, name, email, onUpdate, onDelete }) => {
+  // ...
+}
+```
+
+### 2. 状态管理评审
+
+**Vue (Pinia) 检查**:
+- [ ] **Store 设计**: Store 划分是否合理？是否按模块组织？
+- [ ] **State 定义**: 状态是否有完整类型？
+- [ ] **Actions**: 异步操作是否在 actions 中？
+- [ ] **Getters**: 是否使用 computed 而非重复计算？
+- [ ] **持久化**: 是否需要状态持久化（localStorage）？
+
+```typescript
+// ✅ 正确的 Pinia Store
+export const useUserStore = defineStore('user', () => {
+  // State
+  const users = ref<User[]>([])
+  const currentUser = ref<User | null>(null)
+
+  // Getters
+  const activeUsers = computed(() => users.value.filter(u => u.active))
+
+  // Actions
+  async function fetchUsers() {
+    const { data } = await api.get<User[]>('/users')
+    users.value = data
+  }
+
+  return { users, currentUser, activeUsers, fetchUsers }
+})
+```
+
+**React (Redux Toolkit / Zustand) 检查**:
+- [ ] **Slice 设计**: Redux slice 划分是否合理？
+- [ ] **Immutability**: 是否保持状态不可变？
+- [ ] **Selectors**: 是否使用 reselect 避免重复计算？
+- [ ] **Async Thunks**: 异步操作是否正确处理？
+
+```typescript
+// ✅ 正确的 Redux Slice
+const userSlice = createSlice({
+  name: 'user',
+  initialState: { users: [], loading: false },
+  reducers: {
+    setUsers: (state, action) => {
+      state.users = action.payload
+    }
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUsers.pending, (state) => {
+        state.loading = true
+      })
+      .addCase(fetchUsers.fulfilled, (state, action) => {
+        state.users = action.payload
+        state.loading = false
+      })
+  }
+})
+```
+
+### 3. 路由设计评审
+
+- [ ] **路由结构**: 路由层级是否清晰？嵌套是否合理？
+- [ ] **路由守卫**: 是否有认证守卫？权限控制是否完善？
+- [ ] **懒加载**: 是否使用路由级代码分割？
+- [ ] **元信息**: 是否定义页面标题、面包屑等元信息？
+- [ ] **404 处理**: 是否有 404 页面？
+
+**Vue Router 检查**:
+```typescript
+// ✅ 正确的路由配置
+const routes = [
+  {
+    path: '/dashboard',
+    component: () => import('@/views/Dashboard.vue'), // 懒加载
+    meta: { requiresAuth: true, title: 'Dashboard' }
+  },
+  {
+    path: '/:pathMatch(.*)*',
+    component: () => import('@/views/NotFound.vue')
+  }
+]
+```
+
+### 4. UI/UX 评审
+
+- [ ] **响应式设计**: 是否适配移动端和桌面端？
+- [ ] **加载状态**: 是否有 loading 指示器？
+- [ ] **错误提示**: 是否有友好的错误提示？
+- [ ] **空状态**: 列表为空时是否有提示？
+- [ ] **交互反馈**: 按钮点击、表单提交是否有反馈？
+- [ ] **可访问性**: 是否考虑了 a11y（键盘导航、ARIA 属性）？
+
+**交互反馈示例**:
+```vue
+<template>
+  <button @click="handleSubmit" :disabled="loading">
+    <span v-if="loading">提交中...</span>
+    <span v-else>提交</span>
+  </button>
+
+  <div v-if="users.length === 0" class="empty-state">
+    <p>暂无数据</p>
+  </div>
+</template>
+```
+
+### 5. 性能评审
+
+- [ ] **组件懒加载**: 是否使用 `defineAsyncComponent` / `React.lazy`？
+- [ ] **列表优化**: 大列表是否使用虚拟滚动？
+- [ ] **图片优化**: 是否使用懒加载？是否压缩？
+- [ ] **防抖节流**: 搜索、滚动是否使用防抖节流？
+- [ ] **Memo 优化**: 是否使用 `computed` / `useMemo` 避免重复计算？
+
+**性能优化示例**:
+```vue
+<!-- Vue: 异步组件 -->
+<script setup>
+const HeavyComponent = defineAsyncComponent(() =>
+  import('./HeavyComponent.vue')
+)
+</script>
+
+<!-- 虚拟滚动 -->
+<script setup>
+import { useVirtualList } from '@vueuse/core'
+
+const { list, containerProps, wrapperProps } = useVirtualList(
+  largeList,
+  { itemHeight: 50 }
+)
+</script>
+```
+
+```typescript
+// React: useMemo
+const expensiveValue = useMemo(() => {
+  return computeExpensiveValue(a, b)
+}, [a, b])
+
+// React.memo 避免不必要的渲染
+const MemoizedComponent = React.memo(MyComponent)
+```
+
+### 6. 安全性评审
+
+- [ ] **XSS 防护**: 是否避免使用 `v-html` / `dangerouslySetInnerHTML`？
+- [ ] **输入验证**: 表单输入是否有前端验证？
+- [ ] **Token 管理**: JWT token 是否安全存储？
+- [ ] **HTTPS**: API 调用是否使用 HTTPS？
+- [ ] **敏感信息**: 是否避免在前端存储敏感信息？
+
+**安全检查示例**:
+```vue
+<!-- ❌ 危险：XSS 风险 -->
+<div v-html="userInput"></div>
+
+<!-- ✅ 安全：自动转义 -->
+<div>{{ userInput }}</div>
+
+<!-- ✅ 如必须使用 HTML，先消毒 -->
+<script setup>
+import DOMPurify from 'dompurify'
+const sanitizedHTML = computed(() => DOMPurify.sanitize(userInput.value))
+</script>
+<div v-html="sanitizedHTML"></div>
+```
+
+### 7. TypeScript 类型安全评审
+
+- [ ] **类型定义**: 组件 Props、State、API 响应是否有类型？
+- [ ] **避免 any**: 是否避免使用 `any` 类型？
+- [ ] **类型推导**: 是否充分利用类型推导？
+- [ ] **接口定义**: 是否定义清晰的接口和类型？
+
+```typescript
+// ✅ 正确：完整的类型定义
+interface User {
+  id: number
+  name: string
+  email: string
+  role: 'admin' | 'user'
+}
+
+interface ApiResponse<T> {
+  code: number
+  message: string
+  data: T
+}
+
+async function fetchUsers(): Promise<ApiResponse<User[]>> {
+  const response = await api.get<ApiResponse<User[]>>('/users')
+  return response.data
+}
+```
+
+### 8. 测试覆盖评审
+
+- [ ] **组件测试**: 覆盖率是否 >= 90%？
+- [ ] **测试用例**: 是否覆盖正常和异常流程？
+- [ ] **用户交互**: 是否测试按钮点击、表单提交等交互？
+- [ ] **Store 测试**: 是否测试状态管理逻辑？
+- [ ] **E2E 测试**: 是否有关键流程的端到端测试？
+
+**Vue 测试示例**:
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/vue'
+
+describe('LoginForm', () => {
+  it('submits form with valid data', async () => {
+    const { emitted } = render(LoginForm)
+
+    await fireEvent.update(screen.getByLabelText('Email'), 'test@example.com')
+    await fireEvent.update(screen.getByLabelText('Password'), 'password123')
+    await fireEvent.click(screen.getByRole('button', { name: /login/i }))
+
+    expect(emitted()).toHaveProperty('submit')
+  })
+})
+```
+
+## 评审标准
+
+### ✅ 评审通过标准
+
+1. **组件设计合理**: 职责单一，可复用性强
+2. **类型安全**: 完整的 TypeScript 类型定义
+3. **用户体验良好**: 响应式设计，交互反馈及时
+4. **性能优秀**: 组件懒加载，大列表优化
+5. **安全可靠**: 无 XSS 风险，输入验证完善
+6. **测试充分**: >= 90% 覆盖率
+
+### ❌ 评审不通过场景
+
+1. **类型缺失**: 缺少 TypeScript 类型定义，大量使用 `any`
+2. **XSS 风险**: 不当使用 `v-html` / `dangerouslySetInnerHTML`
+3. **性能问题**: 未使用懒加载，大列表未优化
+4. **用户体验差**: 无 loading 状态，无错误提示
+5. **测试不足**: 覆盖率 < 90%，缺少关键测试
+
+## 评审流程
+
+### 1. OpenSpec 评审
+
+**检查 OpenSpec 文档**:
+```markdown
+□ 页面组件列表完整
+□ 可复用组件定义清晰
+□ 状态管理设计合理
+□ 路由配置完整
+□ API 调用层定义明确
+□ 测试策略清晰（覆盖率 >= 90%）
+```
+
+### 2. 代码实现评审
+
+**对照 OpenSpec 检查代码**:
+```markdown
+□ 所有页面组件已实现
+□ 可复用组件符合设计
+□ Pinia/Redux Store 实现正确
+□ 路由配置与 OpenSpec 一致
+□ API 调用层封装合理
+□ 测试用例覆盖所有场景
+```
+
+### 3. 自动化检查
+
+```bash
+# TypeScript 类型检查
+npm run type-check
+
+# ESLint 检查
+npm run lint
+
+# 测试覆盖率
+npm run test:coverage
+
+# 构建检查
+npm run build
+```
+
+### 4. 手动测试
+
+```markdown
+□ 在不同浏览器测试（Chrome, Firefox, Safari）
+□ 在不同屏幕尺寸测试（桌面、平板、手机）
+□ 测试键盘导航
+□ 测试错误场景（网络失败、无效输入）
+□ 测试性能（Lighthouse 分数 >= 90）
+```
+
+## 评审记录模板
+
+```markdown
+## Frontend OpenSpec 评审记录
+
+**评审日期**: YYYY-MM-DD
+**评审人**: [Frontend Engineer 姓名]
+**OpenSpec 版本**: v1.0
+**框架**: Vue 3 / React 18
+
+### 组件设计评审
+
+- [ ] 组件划分: ✅ 合理 / ❌ 需调整
+- [ ] TypeScript 类型: ✅ 完整 / ❌ 缺失
+- [ ] Props/Emits: ✅ 定义清晰 / ❌ 需补充
+
+**问题列表**:
+1. [问题描述] - [修复建议]
+
+### 状态管理评审
+
+- [ ] Store 设计: ✅ 合理 / ❌ 需调整
+- [ ] 类型定义: ✅ 完整 / ❌ 缺失
+- [ ] 异步处理: ✅ 正确 / ❌ 有问题
+
+**问题列表**:
+1. [问题描述] - [修复建议]
+
+### UI/UX 评审
+
+- [ ] 响应式设计: ✅ 良好 / ❌ 需优化
+- [ ] 加载状态: ✅ 完整 / ❌ 缺失
+- [ ] 错误提示: ✅ 友好 / ❌ 需改进
+- [ ] 可访问性: ✅ 良好 / ❌ 需改进
+
+### 性能评审
+
+- [ ] 组件懒加载: ✅ 已使用 / ❌ 未使用
+- [ ] 大列表优化: ✅ 已优化 / ❌ 需优化
+- [ ] Lighthouse 分数: [分数] (>= 90)
+
+### 安全性评审
+
+- [ ] XSS 防护: ✅ 安全 / ❌ 有风险
+- [ ] 输入验证: ✅ 完善 / ❌ 不足
+- [ ] Token 管理: ✅ 安全 / ❌ 有风险
+
+### 测试评审
+
+- 单元测试覆盖率: [X]%
+- 组件测试数量: [N] 个
+- E2E 测试: ✅ 完成 / ❌ 缺失
+
+### 评审结论
+
+- [ ] ✅ 通过，可以进入测试阶段
+- [ ] ⚠️ 有条件通过，修复以下问题后可进入测试
+- [ ] ❌ 不通过，需要重大修订
+
+### 待修复问题
+
+1. [严重] [问题描述] - [修复建议]
+2. [中等] [问题描述] - [修复建议]
+```
+
+## 常见问题和解决方案
+
+### Q1: 组件拆分粒度如何把握？
+
+**解决方案**:
+- 单一职责：一个组件只做一件事
+- 可复用性：被多次使用的逻辑抽取为组件
+- 避免过度：不要为了复用而复用
+
+### Q2: 如何优化大列表性能？
+
+**解决方案**:
+- 使用虚拟滚动（vue-virtual-scroller, react-window）
+- 分页加载
+- 使用 `v-memo` / `React.memo` 避免不必要渲染
+
+### Q3: 如何处理全局状态和局部状态？
+
+**解决方案**:
+- 全局状态：用户信息、主题设置 → Pinia/Redux
+- 局部状态：表单输入、弹窗显示 → 组件内 `ref`/`useState`
+
+### Q4: 如何确保类型安全？
+
+**解决方案**:
+- 所有 API 响应定义类型
+- 组件 Props 使用接口定义
+- 避免使用 `any`，使用 `unknown` 或泛型
+- 开启 `strict` 模式
+
+## 质量标准
+
+### 优秀的 Frontend 实现特征
+
+1. **类型安全**: 完整的 TypeScript 类型定义
+2. **组件设计**: 职责单一，可复用性强
+3. **用户体验**: 响应式、加载状态、错误提示完善
+4. **性能优秀**: Lighthouse 分数 >= 90
+5. **测试充分**: >= 90% 覆盖率
+
+### 需要改进的实现特征
+
+1. **类型缺失**: 大量使用 `any`
+2. **组件混乱**: 职责不清，难以复用
+3. **体验不佳**: 无 loading，错误提示不友好
+4. **性能差**: 未懒加载，大列表未优化
+5. **测试不足**: 覆盖率 < 90%
+
+## 工具推荐
+
+### 开发工具
+
+- **Vue**: Vite, Vue Devtools, Volar
+- **React**: Vite/CRA, React DevTools, React Developer Tools
+- **状态管理**: Pinia Devtools, Redux DevTools
+
+### 测试工具
+
+```bash
+# 单元测试
+npm run test:unit
+
+# 覆盖率
+npm run test:coverage
+
+# E2E 测试
+npm run test:e2e
+
+# 性能测试
+npx lighthouse http://localhost:3000
+```
+
+### 代码质量工具
+
+```bash
+# ESLint
+npm run lint
+
+# TypeScript 检查
+npm run type-check
+
+# 格式化
+npm run format
+```
+
+---
+
+**记住**: 优秀的前端代码不仅功能完整，还要提供良好的用户体验和可维护性。

package/references/sae-review-guide.md

@@ -0,0 +1,213 @@
+# SAE 需求规格评审指南
+
+## 何时需要评审
+
+**仅在以下情况下加载此评审指南**：
+- 需求规格文档已完成，需要评审验证
+- 用户明确要求对需求规格进行评审
+- OpenSpec proposal 完成，需要技术方案评审
+
+## 评审目标
+
+确保需求规格文档的完整性、准确性、可实施性，为后续开发提供清晰的指导。
+
+## 评审检查清单
+
+### 1. 需求完整性检查
+
+- [ ] **业务背景**：是否清晰说明了为什么需要这个功能？
+- [ ] **目标用户**：是否明确了使用该功能的用户角色？
+- [ ] **核心价值**：是否阐述了功能解决的问题和带来的价值？
+- [ ] **功能列表**：是否列出了所有必需的功能点？
+- [ ] **非功能需求**：是否考虑了性能、安全、可维护性等？
+
+### 2. 需求清晰度检查
+
+- [ ] **功能描述**：每个功能点是否有明确、无歧义的描述？
+- [ ] **用户故事**：是否使用"作为...我希望...以便..."的格式？
+- [ ] **边界清晰**：功能范围和边界是否明确？不在范围内的也要说明
+- [ ] **术语统一**：关键术语是否定义清晰且全文一致？
+
+### 3. 技术方案可行性检查
+
+- [ ] **架构设计**：系统架构是否合理？模块划分是否清晰？
+- [ ] **技术选型**：所选技术栈是否成熟可靠？团队是否熟悉？
+- [ ] **接口定义**：前后端 API 契约是否完整？包含请求/响应格式、错误码等
+- [ ] **数据模型**：数据库设计是否合理？表结构、字段类型、索引是否明确？
+- [ ] **依赖风险**：是否识别了外部依赖和第三方服务？
+
+### 4. 性能和安全检查
+
+- [ ] **性能指标**：是否定义了性能要求？（响应时间、并发量、吞吐量）
+- [ ] **安全考虑**：是否考虑了认证、授权、数据加密、输入验证？
+- [ ] **错误处理**：是否定义了异常情况的处理策略？
+- [ ] **日志审计**：是否规划了日志记录和审计追踪？
+
+### 5. 验收标准检查
+
+- [ ] **可测试性**：验收标准是否可测试？有明确的预期结果？
+- [ ] **覆盖完整**：验收标准是否覆盖了所有关键功能？
+- [ ] **场景完整**：是否包含正常流程和异常流程？
+- [ ] **量化指标**：是否有可量化的成功标准？
+
+### 6. 测试策略检查
+
+- [ ] **单元测试**：是否明确了覆盖率要求？（后端 90%, 前端 90%）
+- [ ] **集成测试**：是否规划了 API 集成测试？
+- [ ] **E2E 测试**：是否定义了关键用户流程的端到端测试？
+- [ ] **性能测试**：是否需要性能测试？如需要，是否定义了测试场景？
+
+## 评审标准
+
+### ✅ 评审通过标准
+
+1. **完整性**: 所有必需章节都已填写，无遗漏
+2. **清晰性**: 描述清晰明确，无歧义，技术人员可直接实施
+3. **可行性**: 技术方案成熟可靠，团队有能力实现
+4. **可测试**: 验收标准清晰，可测试验证
+5. **风险可控**: 已识别主要风险，有缓解措施
+
+### ❌ 评审不通过场景
+
+1. **需求不清**：功能描述模糊，存在多种理解
+2. **技术风险高**：使用不成熟技术，团队不熟悉，无备选方案
+3. **接口不完整**：前后端 API 定义缺失关键信息
+4. **缺少验收标准**：无法判断功能是否完成
+5. **性能/安全考虑不足**：未考虑性能瓶颈或安全漏洞
+
+## 评审流程
+
+### 1. 自检阶段
+
+在提交评审前，SAE 应自行检查：
+```markdown
+□ 阅读整个文档，确保逻辑连贯
+□ 使用评审检查清单逐项核对
+□ 模拟 Backend/Frontend Engineer 视角，是否能直接开发
+□ 模拟 Tester 视角，是否能设计测试用例
+```
+
+### 2. 同行评审阶段
+
+邀请其他技术角色评审：
+- **Backend Engineer**: 评审后端技术方案、API 设计、数据模型
+- **Frontend Engineer**: 评审前端交互设计、组件规划、状态管理
+- **Tester**: 评审测试策略、验收标准的可测试性
+
+### 3. 修订阶段
+
+根据评审反馈修订：
+```markdown
+1. 记录所有评审意见
+2. 对每条意见进行分类：接受/拒绝/需讨论
+3. 更新需求规格文档
+4. 回复评审意见，说明修订内容
+```
+
+### 4. 最终确认
+
+所有关键问题解决后：
+- 标记文档状态为"已评审"
+- 通知 Backend/Frontend Engineer 开始实施
+- 将文档纳入版本管理
+
+## 评审记录模板
+
+```markdown
+## 评审记录
+
+**评审日期**: YYYY-MM-DD
+**评审人**: [SAE姓名] + [其他角色]
+**文档版本**: v1.0
+
+### 评审意见
+
+#### 意见 1
+- **类型**: 重大问题 / 中等问题 / 建议
+- **描述**: [具体问题描述]
+- **建议**: [修复建议]
+- **状态**: 已修复 / 待修复 / 不修复（说明原因）
+
+#### 意见 2
+...
+
+### 评审结论
+
+- [ ] 通过，可以进入开发阶段
+- [ ] 有条件通过，修复以下问题后可进入开发
+- [ ] 不通过，需要重大修订后重新评审
+
+### 后续行动
+
+1. [行动项 1]
+2. [行动项 2]
+```
+
+## 常见问题和解决方案
+
+### Q1: 需求描述过于技术化，业务人员看不懂怎么办？
+
+**解决方案**:
+- 增加"业务背景"章节，用业务语言描述
+- 技术实现细节放在"技术方案"章节
+- 使用流程图、时序图等可视化方式辅助说明
+
+### Q2: 前后端接口设计分歧怎么办？
+
+**解决方案**:
+- 召集 Backend/Frontend Engineer 进行设计评审会议
+- 讨论各方案的优劣，达成一致
+- 在需求规格中明确记录最终决策和理由
+
+### Q3: 性能要求无法量化怎么办？
+
+**解决方案**:
+- 参考行业标准（如响应时间 < 200ms P95）
+- 基于用户体验设定指标（如页面加载 < 3秒）
+- 与产品/业务方确认可接受的性能水平
+
+### Q4: 技术方案存在多个可行选项怎么办？
+
+**解决方案**:
+- 使用决策矩阵对比各方案（成熟度、性能、成本、团队熟悉度）
+- 在需求规格中记录对比结果和选择理由
+- 保留备选方案作为风险缓解措施
+
+## 评审质量标准
+
+### 优秀的需求规格特征
+
+1. **完整详尽**: 涵盖所有功能和非功能需求
+2. **清晰无歧义**: 技术人员读完即可开始设计
+3. **可实施**: 技术方案成熟，团队有能力实现
+4. **可验证**: 验收标准清晰，可测试
+5. **前瞻性**: 考虑了扩展性和未来演进
+
+### 需要改进的需求规格特征
+
+1. **描述模糊**: 使用"可能"、"大概"等不确定词汇
+2. **技术方案缺失**: 没有说明如何实现
+3. **接口不完整**: API 定义缺少关键字段或错误码
+4. **缺少边界**: 没有明确功能范围
+5. **验收标准不可测**: 无法判断是否完成
+
+## 工具和技巧
+
+### 推荐工具
+
+- **流程图**: Mermaid, draw.io
+- **API 文档**: Swagger/OpenAPI, Apifox
+- **数据库设计**: dbdiagram.io, DrawSQL
+- **协作评审**: GitLab Comments, Google Docs
+
+### 评审技巧
+
+1. **换位思考**: 从开发者、测试者角度阅读
+2. **提出问题**: "如果...怎么办？" "为什么...？"
+3. **检查一致性**: 术语、命名、格式是否统一
+4. **验证可测**: 能否根据文档编写测试用例
+5. **风险识别**: 主动寻找潜在问题和边界情况
+
+---
+
+**记住**: 好的需求规格是成功开发的基础。花时间做好评审，能避免后期返工，节约整体时间。