@jahanxu/trellis 0.4.1

package/dist/templates/trellis/spec/roles/frontend-impl/index.md

@@ -0,0 +1,321 @@
+# Frontend (前端开发工程师) 工作规范
+
+> 前端开发工程师在三角色协作中的职责、标准和工作流程
+
+---
+
+## 角色定位
+
+**前端开发工程师（Frontend）** 是三角色协作流水线的**第三环**：
+- 从 `prototypes` 池选择原型
+- 基于原型代码补充真实API调用和业务逻辑
+- 产出物进入 `production` 池，准备上线
+
+---
+
+## 工作流程
+
+### 1. 选择原型
+```bash
+# 查看可用原型
+python3 .trellis/scripts/pool.py list prototypes
+
+# 选择原型并创建任务
+/trellis:pick-task prototypes <task-id>
+```
+
+系统会自动：
+- 创建任务目录
+- 设置 `source.json` 引用上游原型
+- 注入原型代码和HANDOFF文档
+
+### 2. 补充真实逻辑
+
+参考 `HANDOFF.md` 中的"需要Frontend补充的逻辑"章节：
+1. 替换Mock API为真实API调用
+2. 添加错误处理
+3. 接入全局状态管理
+4. 补充边缘场景逻辑
+
+### 3. 完成并交接
+```bash
+/trellis:handoff
+```
+
+产出自动进入 `deliverables/production/{task-id}/`
+
+---
+
+## 开发标准
+
+### API集成规范
+
+#### 1. 识别Mock位置
+```typescript
+// Designer留下的TODO注释
+const handleLogin = async (email: string, password: string) => {
+  // TODO: [Frontend] 替换为真实API调用 /api/auth/login
+  return new Promise(resolve => {
+    setTimeout(() => resolve(mockUser), 1000);
+  });
+};
+```
+
+#### 2. 替换为真实API
+```typescript
+// ✅ 使用项目API客户端
+import { apiClient } from '@/lib/api';
+
+const handleLogin = async (email: string, password: string) => {
+  try {
+    const response = await apiClient.post('/api/auth/login', {
+      email,
+      password
+    });
+    return response.data;
+  } catch (error) {
+    throw new ApiError('登录失败', error);
+  }
+};
+```
+
+#### 3. 保留类型定义
+```typescript
+// 继续使用Designer定义的类型
+import type { User } from '@/types/user';
+
+// 确保API返回与类型匹配
+const user: User = response.data.user;
+```
+
+### 错误处理规范
+
+**必须处理的错误场景**：
+1. **网络错误** - 超时、断网
+2. **业务错误** - 登录失败、权限不足
+3. **表单验证错误** - 格式错误、必填项缺失
+
+**示例**：
+```typescript
+const handleLogin = async (email: string, password: string) => {
+  try {
+    setLoading(true);
+    setError(null);
+
+    const response = await apiClient.post('/api/auth/login', { email, password });
+
+    // 成功处理
+    setUser(response.data.user);
+    navigate('/dashboard');
+
+  } catch (error) {
+    // 错误处理
+    if (error instanceof NetworkError) {
+      setError('网络连接失败，请检查网络设置');
+    } else if (error.response?.status === 401) {
+      setError('邮箱或密码错误');
+    } else {
+      setError('登录失败，请稍后重试');
+    }
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+### 状态管理规范
+
+**根据复杂度选择方案**：
+
+| 场景 | 推荐方案 | 示例 |
+|------|---------|------|
+| 简单页面状态 | React useState | 表单输入、UI切换 |
+| 跨组件状态 | React Context | 用户信息、主题 |
+| 复杂全局状态 | Zustand/Redux | 购物车、消息通知 |
+
+**示例**：
+```typescript
+// 接入全局用户状态
+import { useAuthStore } from '@/stores/auth';
+
+const LoginPage = () => {
+  const { login, user } = useAuthStore();
+
+  const handleLogin = async (email: string, password: string) => {
+    await login(email, password);  // 调用全局store
+  };
+};
+```
+
+### 代码质量要求
+
+**必须通过**：
+- [ ] TypeScript类型检查无错误
+- [ ] ESLint检查无错误
+- [ ] 单元测试覆盖率 > 70%（核心逻辑）
+- [ ] 手动测试通过所有验收标准
+
+**推荐优化**：
+- [ ] 性能优化（lazy loading、缓存）
+- [ ] 无障碍支持（ARIA标签）
+- [ ] 响应式优化（移动端适配）
+
+---
+
+## HANDOFF文档要点
+
+AI生成的 `HANDOFF.md` 应包含：
+
+### 实现总结
+- 主要功能实现说明
+- API集成情况
+- 状态管理方案
+
+### 产出文件
+```
+修改的文件：
+- LoginPage.tsx - 添加真实API调用
+- useAuth.ts - 新增全局登录状态hook
+- api/auth.ts - 新增登录API封装
+```
+
+### API集成清单
+
+| 端点 | 方法 | 用途 | 位置 |
+|------|------|------|------|
+| /api/auth/login | POST | 用户登录 | LoginPage.tsx:67 |
+| /api/auth/logout | POST | 用户登出 | Header.tsx:34 |
+
+### 测试说明
+```
+已添加的测试：
+- LoginForm.test.tsx - 表单验证测试
+- useAuth.test.ts - Hook逻辑测试
+
+测试覆盖率：78%
+```
+
+### 已知问题
+如有遗留问题，明确说明：
+1. 问题描述
+2. 影响范围
+3. 计划修复时间
+
+### 部署注意事项
+
+**环境变量**：
+```bash
+VITE_API_BASE_URL=https://api.example.com
+VITE_AUTH_REDIRECT_URI=https://app.example.com/callback
+```
+
+**依赖项**：
+- 新增：`axios@1.6.0`, `zustand@4.5.0`
+
+---
+
+## 质量检查清单
+
+在执行 `/trellis:handoff` 前，确保：
+
+### 功能性
+- [ ] 所有PRD要求的功能已实现
+- [ ] Mock API已全部替换为真实API
+- [ ] 错误处理完善（网络错误、业务错误）
+- [ ] 边缘场景已处理
+
+### 代码质量
+- [ ] TypeScript编译无错误
+- [ ] ESLint检查通过
+- [ ] 单元测试覆盖核心逻辑
+- [ ] 代码已Code Review
+
+### 用户体验
+- [ ] 加载状态友好
+- [ ] 错误提示清晰
+- [ ] 交互流畅
+- [ ] 响应式适配（如需要）
+
+### 文档
+- [ ] HANDOFF文档完整
+- [ ] API集成清单准确
+- [ ] 环境变量已文档化
+- [ ] 已知问题已记录
+
+---
+
+## 从原型到生产的改造要点
+
+### 1. API集成
+```typescript
+// Before (Designer's mock)
+const mockLogin = () => Promise.resolve(mockUser);
+
+// After (Real API)
+const login = (email, password) => apiClient.post('/api/auth/login', { email, password });
+```
+
+### 2. 错误处理
+```typescript
+// Before (无错误处理)
+const handleSubmit = async () => {
+  const user = await mockLogin();
+  setUser(user);
+};
+
+// After (完善错误处理)
+const handleSubmit = async () => {
+  try {
+    setLoading(true);
+    const user = await login(email, password);
+    setUser(user);
+  } catch (error) {
+    handleError(error);
+  } finally {
+    setLoading(false);
+  }
+};
+```
+
+### 3. 状态管理
+```typescript
+// Before (本地state)
+const [user, setUser] = useState(null);
+
+// After (全局store)
+const { user, login, logout } = useAuthStore();
+```
+
+### 4. 性能优化
+```typescript
+// Before (直接import)
+import HeavyComponent from './HeavyComponent';
+
+// After (lazy loading)
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+```
+
+---
+
+## 常见问题
+
+### Q: 可以重构Designer的代码吗？
+A: 可以，但需要在HANDOFF中说明重构理由。保持组件结构相似，便于Designer理解。
+
+### Q: Mock数据可以删除吗？
+A: 保留Mock数据用于测试。在 `__tests__/mocks/` 目录下集中管理。
+
+### Q: 需要实现哪些测试？
+A: 最低要求：核心业务逻辑的单元测试。推荐：集成测试、E2E测试。
+
+### Q: 如何处理原型中没有的功能？
+A: 参考PRD，如果是必需功能但原型缺失，补充实现并在HANDOFF中说明。
+
+---
+
+## 参考资料
+
+- [API集成指南](./api-integration.md)
+- [状态管理最佳实践](./state-management.md)
+- [错误处理规范](./error-handling.md)
+- [测试指南](./testing-guide.md)