188-template-179/mini-starter @ e88dab6262e965eafdbb8f5bc66ce5e535e2b11f

开发环境说明

多八多云端开发容器环境
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
- 代码目录: /mini
- 账号: 13800138005
- 密码: 123123
- 人才小程序: http://localhost:8080/talent-mini
- 代码目录: /mini-talent
- 个人信息页: /talent-mini/#/talent-mini/pages/personal-info/index
- 账号: 13800138004
- 密码: 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

🚨 BMAD 工作流指令 - 必读！

⚠️ 调用方式（重要！）

直接使用斜杠命令 /bmad-xxx 调用工作流

常用 BMAD 工作流命令

工作流	命令	说明
Party Mode	`/bmad-party-mode`	多代理群组讨论
开发 Story	`/bmad-bmm-dev-story`	实现 Story 的任务和子任务
创建 Story	`/bmad-bmm-create-story`	从 Epic 创建下一个 Story
代码审查	`/bmad-bmm-code-review`	AI 代码审查
Sprint 状态	`/bmad-bmm-sprint-status`	查询当前 Sprint 状态
Sprint 规划	`/bmad-bmm-sprint-planning`	Sprint 规划
回顾	`/bmad-bmm-retrospective`	Sprint 回顾
纠正方向	`/bmad-bmm-correct-course`	纠正开发方向
快速开发	`/bmad-bmm-quick-dev`	快速流程开发
帮助	`/bmad-help`	获取帮助信息

示例：开发 Story 10.11

用户: "开发 Story 10.11"

直接输入: /bmad-bmm-dev-story

完整命令列表

所有可用命令位于 .claude/commands/ 目录，命令格式为 /bmad-xxx：

代理类: /bmad-agent-bmm-dev, /bmad-agent-bmm-pm, /bmad-agent-bmm-architect 等
工作流: /bmad-bmm-dev-story, /bmad-bmm-create-story, /bmad-bmm-code-review 等
快速流: /bmad-bmm-quick-dev, /bmad-bmm-quick-spec
图表工具: /bmad-bmm-create-excalidraw-* (流程图、数据流图、线框图等)
其他: /bmad-brainstorming, /bmad-party-mode, /bmad-help

工作流状态文件位置

Sprint 状态: _bmad-output/implementation-artifacts/sprint-status.yaml
Story 文件: _bmad-output/implementation-artifacts/*.md
Epic 文件: _bmad-output/planning-artifacts/epics.md

其他开发说明

project-context.md 路径: _bmad-output/project-context.md
必须用中文回答
git提交: 当遇到git锁文件冲突时，使用单条命令：rm -f /mnt/code/188-179-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 Histórico Em bruto

开发环境说明

Claude Code

🚨 BMAD 工作流指令 - 必读！

⚠️ 调用方式（重要！）

常用 BMAD 工作流命令

示例：开发 Story 10.11

完整命令列表

工作流状态文件位置

其他开发说明

工具调用最佳实践

Playwright E2E 测试

其他工具

CLAUDE.md 8.3 KB

Histórico Em bruto