### 开发环境说明
- 多八多云端开发容器环境
- Node.js 20.19.2
- PostgresSQL 17 (默认数据库: postgres)
- Redis 7
- MinIO(默认存储桶: d8dai)
- 所有服务使用默认参数连接，正式环境参数相同
- 默认开放8080端口供外网访问
- 开发服务器在8080端口默认开机自动启动，无需手动启动
- **日志记录**: `pnpm run dev` 会自动记录日志到 `logs/dev-logs/`
  - `logs/dev-logs/dev-current.log` 是当前日志文件（追加模式）
  - AI 代理排查问题时可以先查看日志：`cat logs/dev-logs/dev-current.log`
  - 参考 `logs/README.md` 了解更多日志管理说明
- **小程序测试账号**:
  - 企业小程序: http://localhost:8080/mini-enterprise/
    - 账号: `13800138002`
    - 密码: `123123`
  - 人才小程序: http://localhost:8080/mini-talent/
    - 账号: `13800138003`
    - 密码: `123123`

- ### Claude Code
- use pnpm
- 数据库在同一容器组的另一个容器中，需要运行 psql -h 127.0.0.1 -U postgres 来访问
- vitest中，只有console.debug会显示，其他的都屏蔽了
- vitest中，用import 来配合 vi.mocked，而不是require
- **E2E测试**:
  - **工作流程**: 编写 E2E 测试前，先使用子代理运行 Playwright MCP 手动走一遍测试流程
    - 使用 Playwright MCP 工具（如 `browser_navigate`、`browser_click`、`browser_snapshot` 等）探索页面结构
    - 验证测试流程的可行性，熟悉页面交互
    - 将验证过的流程转化为自动化测试代码
    - 这样可以减少测试编写时的反复调试，提高效率
  - **测试策略要点**:
    - **即时验证**: 在 Story 开发过程中立即使用 Playwright MCP 进行测试验证
    - **模块化验证**: 每完成一个功能模块立即验证，不等到专门的 E2E 测试 Story
    - **减少返工**: 早期发现问题可以减少后期返工成本
    - **示例流程**: Page Object 开发 → Playwright MCP 探索验证 → 代码修复 → 提交
  - **SSR 超时排查**: 当使用 Playwright MCP 发现页面 SSR 超时时，需检查页面控制台日志（这是页面运行时错误，非后端 API 问题）
    - 使用 `browser_console_messages` 工具获取控制台日志
    - 检查 error 级别的日志
    - 常见问题：模块导入失败（如 `Failed to resolve import`）、组件渲染错误、TypeScript/JavaScript 运行时错误
    - 示例场景：SSR 渲染超时（`渲染超时，终止请求`）、页面 `#root` 元素为空、模块脚本加载失败
  - **图片 MCP 配合使用**: Playwright MCP 与图片 MCP（如 zai-mcp-server）配合使用可以更高效地进行测试验证
    - **工作流程**:
      1. 使用 Playwright MCP 导航到页面并截图：`browser_take_screenshot`
      2. 使用图片 MCP 查看截图内容，分析页面状态
      3. 根据分析结果进行调试或修复问题
      4. 在代码审查时使用图片 MCP 验证测试截图的正确性
    - **优点**:
      - 可以直观看到页面实际渲染效果
      - AI 可以识别页面元素和布局问题
      - 验证测试数据是否正确显示（如脱敏、格式等）
      - 快速定位 UI 问题而不需要手动查看截图
    - **示例提示词**: "使用 Playwright MCP 截图后，用图片 MCP 分析截图中的页面元素和测试结果"
  - **推荐使用子代理运行**: 运行 Playwright E2E 测试时，使用 Task 工具的 Bash 子代理方式运行，速度更快且多个 Playwright 进程不会冲突
    - 示例提示词: "在 web 目录下运行 `pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\"`"
  - 运行所有E2E测试: `pnpm test:e2e:chromium`
  - 运行单个测试文件: `pnpm test:e2e:chromium <测试文件名>` (如: `pnpm test:e2e:chromium disability-person-complete`)
  - **快速失败模式** (推荐调试时使用): 使用 Linux `timeout` 命令限制总运行时间
    - `timeout 30 pnpm test:e2e:chromium` (所有测试，30秒后中断)
    - `timeout 60 pnpm test:e2e:chromium disability-person-complete` (单文件测试，60秒后中断)
  - E2E测试失败时先查看页面结构 `test-results/**/error-context.md`
  - E2E测试在 web 目录下运行: `cd web && pnpm test:e2e:chromium`
  - **配置文件超时**: `playwright.config.ts` 中已设置 `timeout: 60000` (60秒，单个测试的默认超时)
- 前端是 hono/client  hc  rpc 的，不是直接fetch

---

## 🚨 BMM 工作流指令 - 必读！

### ⚠️ 调用链（重要！）
**主对话 → Task 工具启动子代理 → 子代理内部调用 Skill 工具执行工作流**

### 正确的使用方式
```typescript
// 主对话中的操作
Task({
  subagent_type: "general-purpose",
  prompt: "调用 Skill 工具执行 bmad:bmm:workflows:dev-story，参数为 10.11"
})
```

### 为什么这样设计？
1. **Token 管理**: 工作流包含大量上下文加载，在子代理中执行不消耗主对话 token
2. **隔离执行**: 子代理在独立上下文中执行，不干扰主对话的连续性
3. **状态管理**: 完整的工作流状态管理和错误恢复
4. **并行执行**: 多个工作流可以在不同子代理中并行执行

### 常用 BMM 工作流
| 工作流 | Skill 名称 | 说明 |
|--------|-----------|------|
| 开发 Story | `bmad:bmm:workflows:dev-story` | 实现 Story 的任务和子任务 |
| 创建 Story | `bmad:bmm:workflows:create-story` | 从 Epic 创建下一个 Story |
| 代码审查 | `bmad:bmm:workflows:code-review` | AI 代码审查 |
| Sprint 状态 | `bmad:bmm:workflows:sprint-status` | 查询当前 Sprint 状态 |
| Sprint 规划 | `bmad:bmm:workflows:sprint-planning` | Sprint 规划 |

### 示例：开发 Story 10.11
```
用户: "开发 Story 10.11"

主对话响应:
Task({
  subagent_type: "general-purpose",
  prompt: "调用 Skill 工具执行 bmad:bmm:workflows:dev-story，参数为 10.11"
})

→ 子代理启动，内部执行 Skill 工具调用 BMM 工作流
→ 工作流在子代理中完成，不消耗主对话 token
```

### 工作流状态文件位置
- Sprint 状态: `_bmad-output/implementation-artifacts/sprint-status.yaml`
- Story 文件: `_bmad-output/implementation-artifacts/*.md`
- Epic 文件: `_bmad-output/planning-artifacts/epics.md`

### ⚠️ API 并发错误处理
当子代理在运行时遇到 API 并发报错（如 "您当前使用该API的并发数过高"）时：
- **不要停止工作**，只需要等待 1-2 秒后继续重试即可
- 这是因为同时启动了多个子代理导致的暂时性限制
- 系统会自动恢复，重试通常能够成功

---

## 其他开发说明

- **project-context.md 路径**: `_bmad-output/project-context.md`
- 必须用中文回答
- **git提交**: 当遇到git锁文件冲突时，使用单条命令：`rm -f /mnt/code/184-172-template-6/.git/index.lock && git add <文件> && git commit -m "提交信息"`
- **测试调试**: 使用 `pnpm test --testNamePattern "测试名称"` 来运行特定测试查看详细信息 (mini使用Jest，其他包使用Vitest)
  - **Vitest**: 支持 `-t` 或 `--testNamePattern`
  - **Jest**: 只支持 `--testNamePattern`，mini是Jest
  - **Mini测试**: 需要先进入mini目录再运行 `pnpm test --testNamePattern "测试名称"`
- **表单调试**: 表单提交失败时，在表单form onsubmit=form.handleSubmit的第二个参数中加console.debug来看表单验证错误，例如：`form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))`
- 类型检查 可以用 pnpm typecheck 加 grep来过滤要检查的 指定文件
- **长文档分段生成**: 如果文档（如 story 文档）太长一次生成不完，应该分段生成：
  1. 先使用 Write 工具创建文件的基础部分（header、requirements）
  2. 使用 Edit 工具逐步添加其他部分（dev notes、references、dev agent record 等）
  3. 每次添加一个主要部分，确保不会超过单次生成的长度限制

---

## 工具调用最佳实践

### Playwright E2E 测试
- **推荐方式**：使用 Task 工具调用 `Bash` 子代理运行 E2E 测试
- **优点**：
  - 速度快，在独立上下文中执行
  - 多个 Playwright 测试之间不会冲突
  - 方便并行运行多个测试
- **示例**：
  ```typescript
  // 使用 Task 工具 + Bash 子代理
  Task({
    subagent_type: "Bash",
    prompt: "在 web 目录下运行 pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\""
  })
  ```

### 其他工具
- 对于其他长时间运行的任务（如构建、测试套件），建议使用 Task 工具的 Bash 子代理
- 对于复杂的多步骤任务，可以使用 Task 工具的 general-purpose 子代理