@jahanxu/trellis 0.4.1 → 0.5.0

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

@@ -1,321 +0,0 @@
-# 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)