sanguo_moziplus_v3/docs/05-example-workflows.md

# 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: "<main|backend|frontend>",
  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-<role>
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)