188-template-179/mini-starter @ d351c2ab9511e10ed88c4fdb8b317381e36de65d

开发环境说明

多八多云端开发容器环境
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 了解更多日志管理说明
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 工具执行工作流

正确的使用方式

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

为什么这样设计？

Token 管理: 工作流包含大量上下文加载，在子代理中执行不消耗主对话 token
隔离执行: 子代理在独立上下文中执行，不干扰主对话的连续性
状态管理: 完整的工作流状态管理和错误恢复
并行执行: 多个工作流可以在不同子代理中并行执行

常用 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 测试之间不会冲突
- 方便并行运行多个测试

示例：

// 使用 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 子代理

CLAUDE.md 8.3 KB 履歴 Raw

开发环境说明

Claude Code

🚨 BMM 工作流指令 - 必读！

⚠️ 调用链（重要！）

正确的使用方式

为什么这样设计？

常用 BMM 工作流

示例：开发 Story 10.11

工作流状态文件位置

⚠️ API 并发错误处理

其他开发说明

工具调用最佳实践

Playwright E2E 测试

其他工具

CLAUDE.md 8.3 KB

履歴 Raw