gym-manage/AGENT.md

AGENT.md

面向 AI 代理的健身房管理系统开发工作流指南。

项目子模块：gym-manage-api（Java 多模块后端）、gym-manage-web（Vue3 管理后台）、gym-manage-uniapp（会员端小程序）、gym-manage-coach-uniapp（教练端小程序）

---

服务工作端口

服务	端口	说明
Gateway	8080	API 网关，路由 /api/** → localhost:8084
App	8084	主应用服务，Swagger: http://localhost:8084/swagger-ui.html
Frontend Dev	3002	Vite 开发服务器 (pnpm dev)
PostgreSQL	55432	数据库，manage_system / novalon / novalon123
Redis	6379	缓存

---

工作流

1. /grill-with-docs — 需求梳理

启动需求澄清流程，通过迭代问答将模糊需求转化为清晰、文档化的共识。

• 识别需求中的模糊点与歧义，以问答形式逐一澄清
• 澄清过程中产生的新领域术语 / 修正定义，即时同步到 gym-manage-api/CONTEXT.md
• 重要架构决策（满足：难以逆转 + 不记录会令人困惑 + 存在真实权衡）写入 gym-manage-api/docs/adr/
• 输出：需求共识 spec 文档，存放于 docs/superpowers/specs/，格式沿用现有 spec 模板（文档版本/日期/作者/状态 → 项目概况 → 设计方案）

2. /to-prd — 生成 PRD

将 /grill-with-docs 澄清后的需求转化为结构化产品需求文档。

• 沿袭 docs/superpowers/specs/ 现有文档格式
• 输出存放于 docs/superpowers/specs/

3. /to-issues — 任务拆解

将 PRD 拆解成可执行的具体任务。

• 按端到端功能拆解（每个 issue 覆盖完整功能链路：API + Web + UniApp）
• 格式沿袭 docs/superpowers/plans/ 现有模板（含 AI 代理指令头、阶段化任务清单、文件结构）
• 输出存放于 docs/superpowers/plans/

4. /test-driven-development — 测试驱动开发

TDD 全栈覆盖，按 issue 逐个实现。每个 TDD 循环完成后 git commit。

循环：Red（写失败测试）→ Green（最小实现）→ Refactor（重构优化）

测试层次与命令：

层	子项目	框架	命令
后端单元/集成	gym-manage-api	JUnit 5	cd gym-manage-api && mvn test
Web 前端单元	gym-manage-web	vitest	cd gym-manage-web && pnpm test
Web E2E	gym-manage-web	Playwright	cd gym-manage-web && pnpm test:e2e
UniApp 单元	gym-manage-uniapp / gym-manage-coach-uniapp	vitest	首次涉及时先搭建测试基础设施，再正常 TDD

首次涉及 UniApp 端时：先为该子项目配置 vitest + @vue/test-utils，搭建完成后进入 Red-Green-Refactor。

5. /systemic-debugging — 系统化诊断

遇到棘手 Bug 时进行系统化诊断：收集日志 → 提出假设 → 插桩验证 → 定位根因 → 修复 → 回归验证。

诊断入口速查：

问题类型	排查入口
后端 API 错误	Gateway 控制台日志、App 控制台日志（日志级别 DEBUG，输出至 stdout）
数据库问题	psql -U novalon -d manage_system -p 55432
Web 前端错误	浏览器 DevTools Console + Network 标签
E2E 测试失败	Playwright HTML Report，查看失败截图与 trace
UniApp 小程序错误	微信开发者工具控制台（urlCheck: false 已关闭 URL 校验）
Docker 环境	docker-compose logs -f backend / frontend / postgres

直接数据库查询：

psql -U novalon -d manage_system -p 55432 -c "SELECT * FROM table_name LIMIT 10;"