diff --git a/docs/05-example-workflows.md b/docs/05-example-workflows.md new file mode 100644 index 0000000..8cbb97b --- /dev/null +++ b/docs/05-example-workflows.md @@ -0,0 +1,460 @@ +# sanguo_moziplus_v3 v0.4 示例工作流 + +本文档展示如何使用三实例环境完成典型开发任务。 + +## 工作流 1: 实现用户认证功能 + +### 场景 + +实现一个完整的用户认证系统,包括后端 API 和前端页面。 + +### 步骤 + +#### 1. 架构师 (pane 0) 接收需求 + +``` +用户: "实现用户认证功能" +``` + +#### 2. 架构师分析和规划 + +``` +架构师: +- 分析需求: 用户登录、注册、密码找回 +- 规划技术方案: + * 后端: JWT 认证、/auth/login、/auth/register、/auth/refresh + * 前端: 登录页面、注册页面、表单验证 +- 拆分任务 +``` + +#### 3. 架构师指派任务 + +```javascript +// pane 0 +SendMessage({ + to: "backend", + summary: "实现用户认证 API", + message: ` +需要实现 JWT 认证系统: +1. POST /auth/login - 用户登录 +2. POST /auth/register - 用户注册 +3. POST /auth/refresh - 刷新 token +4. POST /auth/logout - 用户登出 +5. 中间件: JWT 验证 + +技术要求: +- 使用 bcrypt 密码哈希 +- JWT 有效期 1 小时 +- 返回标准 HTTP 状态码 +- 编写单元测试 + +验收标准: +- 所有端点正常工作 +- 测试覆盖率 > 80% +- API 文档完整 + ` +}) + +SendMessage({ + to: "frontend", + summary: "实现认证页面", + message: ` +需要实现用户认证页面: +1. 登录页面 +2. 注册页面 +3. 表单验证 +4. API 调用集成 +5. 错误提示 + +技术要求: +- 使用 shadcn/ui 组件 +- 响应式设计 +- 表单验证 +- Loading 状态 + +验收标准: +- UI 符合设计规范 +- 表单验证完整 +- 浏览器兼容性测试通过 + ` +}) +``` + +#### 4. 后端 (pane 1) 执行 + +``` +后端收到任务: +1. 加载 backend-dev skill +2. 设计 API 端点 +3. 实现 JWT 逻辑 +4. 编写测试 +5. 自测验证 +6. 返回结果 +``` + +```javascript +// pane 1 - 后端完成 +SendMessage({ + to: "main", + summary: "后端认证 API 完成", + message: ` +已完成用户认证 API: + +文件: +- src/api/auth.ts (认证端点) +- src/middleware/auth.ts (JWT 中间件) +- src/utils/jwt.ts (JWT 工具) +- src/tests/auth.test.ts (测试) + +端点: +✅ POST /auth/login - 登录成功返回 JWT +✅ POST /auth/register - 注册成功返回用户信息 +✅ POST /auth/refresh - 刷新 token +✅ POST /auth/logout - 清除 token + +测试结果: 12/12 通过 + +API 文档: docs/api-auth.md + ` +}) +``` + +#### 5. 前端 (pane 2) 执行 + +``` +前端收到任务: +1. 加载 frontend-dev skill +2. 设计页面组件 +3. 实现表单 +4. 调用后端 API +5. 浏览器测试 +6. 返回结果 +``` + +```javascript +// pane 2 - 前端完成 +SendMessage({ + to: "main", + summary: "前端认证页面完成", + message: ` +已完成认证页面: + +文件: +- src/pages/LoginPage.tsx (登录页面) +- src/pages/RegisterPage.tsx (注册页面) +- src/components/AuthForm.tsx (表单组件) +- src/hooks/useAuth.ts (认证 Hook) + +功能: +✅ 登录表单 (邮箱/密码) +✅ 注册表单 (邮箱/密码/确认) +✅ 表单验证 +✅ API 调用 +✅ 错误提示 +✅ Loading 状态 + +浏览器测试: Chrome, Safari, Firefox 通过 + +预览: 截图已保存到 docs/screenshots/auth-pages.png + ` +}) +``` + +#### 6. 架构师审查和整合 + +```javascript +// pane 0 - 架构师 +// 加载 CODE-REVIEW skill 进行审查 +// 加载 test-engineer skill 验证测试 +// 整合前后端代码 +// 提交 Git +``` + +## 工作流 2: 代码审查 + +### 场景 + +后端提交了一个 PR,架构师需要审查代码。 + +### 步骤 + +#### 1. 架构师接收 PR + +```javascript +// pane 0 +SendMessage({ + to: "backend", + summary: "请提供 PR 信息", + message: ` +你提交的 PR #123 需要审查。 + +请提供: +1. 改动的文件列表 +2. 实现的功能说明 +3. 测试结果 +4. 已知问题 + ` +}) +``` + +#### 2. 后端返回信息 + +```javascript +// pane 1 +SendMessage({ + to: "main", + summary: "PR #123 信息", + message: ` +改动的文件: +- src/api/users.ts (新增用户查询 API) +- src/tests/users.test.ts (新增测试) + +实现功能: +- GET /api/users/:id - 获取用户信息 +- 支持查询参数过滤 + +测试结果: 8/8 通过 + +已知问题: 无 + ` +}) +``` + +#### 3. 架构师审查 + +``` +架构师: +1. 加载 CODE-REVIEW skill +2. 审查代码质量 +3. 检查测试覆盖 +4. 验证 API 设计 +5. 提供反馈 +``` + +## 工作流 3: Bug 修复 + +### 场景 + +前端发现了一个 bug,需要定位和修复。 + +### 步骤 + +#### 1. 前端报告问题 + +```javascript +// pane 2 +SendMessage({ + to: "main", + summary: "报告 bug", + message: ` +发现登录页面 bug: + +现象: 登录成功后页面没有跳转 + +重现步骤: +1. 输入正确的邮箱和密码 +2. 点击登录按钮 +3. Loading 显示 +4. Loading 消失后仍在登录页 + +环境: Chrome 126, macOS + +日志显示 API 调用成功,但 redirect 没有执行 + ` +}) +``` + +#### 2. 架构师分析 + +``` +架构师: +1. 分析问题描述 +2. 确定是前端问题 +3. 指派前端修复 +``` + +```javascript +// pane 0 +SendMessage({ + to: "frontend", + summary: "修复登录跳转 bug", + message: ` +Bug: 登录成功后页面没有跳转 + +日志显示 API 调用成功,检查: +1. useAuth Hook 的逻辑 +2. 跳转代码是否执行 +3. react-router 配置 + +优先级: 高 + ` +}) +``` + +#### 3. 前端修复 + +```javascript +// pane 2 +SendMessage({ + to: "main", + summary: "Bug 已修复", + message: ` +问题原因: useAuth Hook 中 redirect 逻辑在 useEffect 之外 + +修复方案: +- 将 redirect 逻辑移到 useEffect 中 +- 添加 loading 状态检查 + +测试: 登录成功后正确跳转到首页 + +文件: src/hooks/useAuth.ts + ` +}) +``` + +## 工作流 4: 性能优化 + +### 场景 + +后端 API 响应慢,需要优化。 + +### 步骤 + +#### 1. 架构师分析性能问题 + +``` +架构师: +1. 分析性能数据 +2. 确定瓶颈 +3. 规划优化方案 +``` + +#### 2. 架构师指派优化任务 + +```javascript +// pane 0 +SendMessage({ + to: "backend", + summary: "优化用户查询 API", + message: ` +性能问题: GET /api/users 响应时间 2.5秒 + +目标: 优化到 < 500ms + +分析: +- 数据库查询慢 (N+1 问题) +- 缺少索引 + +优化方案: +1. 添加数据库索引 +2. 优化查询逻辑 (使用 JOIN) +3. 添加缓存层 (Redis) + +请先实现索引和查询优化,缓存后续再做。 + ` +}) +``` + +#### 3. 后端实施优化 + +```javascript +// pane 1 +SendMessage({ + to: "main", + summary: "优化完成", + message: ` +优化措施: +1. 添加 email 索引 +2. 优化查询: 使用 JOIN 替代 N+1 +3. 添加查询缓存 + +结果: +- 优化前: 2.5s +- 优化后: 180ms ✅ + +文件: +- migrations/add_indexes.sql +- src/api/users.ts (优化查询) +- src/cache/userCache.ts (缓存层) + ` +}) +``` + +## SendMessage 最佳实践 + +### 发送消息格式 + +```javascript +SendMessage({ + to: "", + summary: "<简短摘要 5-10 词>", + message: `<详细描述,包括: +- 任务/问题说明 +- 技术要求 +- 验收标准 +- 其他上下文` +}) +``` + +### 接收消息处理 + +``` +1. 读取消息内容 +2. 理解任务要求 +3. 加载相应的 skill +4. 执行任务 +5. 返回结果 +``` + +### 错误处理 + +如果收到不相关的任务: + +```javascript +SendMessage({ + to: "main", + summary: "拒绝任务", + message: "这不是 [后端/前端] 任务,请转给 [frontend/backend] agent" +}) +``` + +## 常用命令 + +### tmux 操作 + +```bash +# 切换 pane +Ctrl+B 0/1/2 + +# 在 pane 间循环 +Ctrl+B o + +# 分离会话 +Ctrl+B d + +# 重新附加 +tmux attach-session -t sanguo_dev +``` + +### 启动 Claude Code + +```bash +# 在各 pane 中 +cd ~/.claude/projects/sanguo- +claude +``` + +### Web 访问 + +```bash +# 启动 Web 终端 +ttyd -p 8088 tmux attach -t sanguo_dev + +# 访问 +http://YOUR_LAN_IP:8088 +``` + +## 相关文档 + +- [快速参考](./04-quick-reference.md) +- [完整设计](./design/04-design-v0.4.md)