frontend/component-development

# 前端组件开发方法论

## 组件设计原则

### 单一职责原则
- 每个组件只负责一个功能模块
- 复杂组件拆分为多个子组件
- 容器组件（逻辑）与展示组件（UI）分离

### 可复用性设计
- 通过 Props/属性实现组件配置化
- 避免硬编码业务逻辑
- 提供合理的默认值
- 支持插槽/children 扩展

### 组件命名规范
- 使用 PascalCase 命名组件
- 名称应清晰描述组件功能
- 避免过于通用的名称（如 Item、Component）
- 文件名与组件名保持一致

## 状态管理策略

### 状态分类
| 状态类型 | 管理方式 | 适用场景 |
|----------|----------|----------|
| 本地状态 | useState/ref | 组件内部状态（表单输入、展开/收起） |
| 共享状态 | Context/Store | 跨组件共享（用户信息、主题） |
| 服务端状态 | Query库/SWR | API 数据缓存和同步 |
| URL 状态 | Router | 页面参数、筛选条件 |

### 状态提升原则
- 状态放在最近的公共父组件
- 避免过度提升导致不必要的重渲染
- 使用 Context 避免 Props 层层传递

### 副作用管理
- 使用框架的副作用 Hook（useEffect/onMounted）
- 清理订阅和定时器
- 依赖数组准确声明
- 避免在渲染函数中执行副作用

## 样式实现规范

### UI 规范优先级
```
ui-design.json > ui-spec.md > 项目现有样式 > 框架默认值
```

### ui-design.json 集成
当 `.boss/<feature>/ui-design.json` 存在时：
1. **读取 tokens**：映射为 CSS 变量或主题对象
   ```typescript
   // 示例：从 tokens 生成 CSS 变量
   const colors = uiDesign.tokens.colors;
   // --color-primary: #007AFF
   ```

2. **解析 pages 和 frames**：推导页面结构和布局
   - 从 `pages[].frames[]` 提取页面组件层级
   - 从 `frames[].layout` 获取布局约束（宽度、间距、对齐）

3. **实现 prototype.links**：推导导航和交互
   - 按钮点击跳转
   - 表单提交流程
   - 模态框打开/关闭

4. **复用 components**：提取可复用组件
   - 从 `components[]` 识别通用组件（Button、Input、Card）
   - 实现为独立组件文件

### 样式编写原则
- 使用项目约定的样式方案（CSS Modules/Tailwind/CSS-in-JS）
- 响应式设计：移动端优先或桌面端优先（按项目约定）
- 使用设计系统的间距、颜色、字体变量
- 避免魔法数字，使用语义化变量

### 无障碍实现
- 添加正确的 ARIA 属性（role、aria-label、aria-describedby）
- 确保键盘导航可用（tabindex、focus 样式）
- 表单元素关联 label
- 图片添加 alt 文本

## 性能优化技巧

### 渲染优化
- 使用 Memo/shouldComponentUpdate 避免不必要的重渲染
- 列表渲染使用稳定的 key
- 虚拟滚动处理长列表
- 避免在渲染函数中创建新对象/函数

### 代码分割
- 路由级别的懒加载
- 大型组件按需加载
- 第三方库按需引入

### 资源优化
- 图片懒加载和响应式图片
- 使用 WebP 等现代图片格式
- SVG 图标内联或雪碧图

## API 契约管理

### 契约来源
实现前端 API 调用前，必须阅读：
1. **architecture.md §5（API 设计）**：获取端点列表、请求/响应格式
2. **后端共享类型**（如有）：复用类型定义

### API 调用层设计
```typescript
// services/api/users.ts
export const userApi = {
  async getUser(id: string): Promise<User> {
    const response = await fetch(`/api/users/${id}`);
    return response.json();
  },
  
  async createUser(data: CreateUserRequest): Promise<User> {
    const response = await fetch('/api/users', {
      method: 'POST',
      body: JSON.stringify(data),
    });
    return response.json();
  },
};
```

### 错误处理
- 统一错误处理：按 architecture.md 定义的错误格式
- 用户友好的错误提示
- 网络错误重试机制
- 加载和错误状态展示

### Mock 策略
后端未就绪时，基于 architecture.md §5 创建 Mock：
```typescript
// services/api/users.mock.ts
export const mockUserApi = {
  async getUser(id: string): Promise<User> {
    return { id, name: 'Mock User', email: 'mock@example.com' };
  },
};
```

## 组件测试策略

### 测试金字塔
| 测试类型 | 占比 | 工具示例 |
|----------|------|----------|
| 单元测试 | 70% | Jest + Testing Library |
| 集成测试 | 20% | Testing Library |
| E2E 测试 | 10% | Playwright/Cypress |

### 单元测试覆盖
- 组件渲染：关键元素是否存在
- Props 变化：不同 Props 下的渲染结果
- 用户交互：点击、输入、表单提交
- Hooks 逻辑：自定义 Hook 的状态变化

### 集成测试覆盖
- 组件间交互：父子组件通信
- 状态管理：全局状态变化对组件的影响
- 路由导航：页面跳转和参数传递

### E2E 测试覆盖（必须）
- 创建流程：填写表单 → 提交 → 验证结果
- 编辑流程：打开编辑 → 修改 → 保存 → 验证
- 删除流程：点击删除 → 确认 → 验证消失
- 列表展示：加载列表 → 筛选 → 分页
- 核心业务流程：完整用户路径

## 实现检查清单

实现组件前：
- [ ] 阅读 ui-design.json（如有）和 ui-spec.md
- [ ] 阅读 architecture.md §5 API 设计
- [ ] 探索项目现有组件模式和样式方案
- [ ] 确认状态管理方案（本地/共享/服务端）

实现组件后：
- [ ] 组件符合单一职责原则
- [ ] 添加必要的 Props 类型定义
- [ ] 实现响应式布局
- [ ] 添加无障碍属性
- [ ] 编写单元测试（70%）
- [ ] 编写集成测试（20%）
- [ ] 编写 E2E 测试（10%，必须）
- [ ] 测试覆盖率达标
- [ ] 代码通过 Lint 检查