14 KiB
14 KiB
AGENT.md — 健身房管理系统 AI 协作工作流
概述
本项目采用"需求驱动开发"（Requirement-Driven Development）工作流，通过以下四个核心命令完成从模糊需求到可运行代码的全流程。遇到复杂 Bug 时可随时调用 /systemic-debugging 进行系统化诊断。
项目技术栈与模块结构
技术栈总览
| 层 | 技术栈 | 目录 | 测试框架 |
|---|---|---|---|
| 后端 API | Java Spring Boot（Maven 多模块） | gym-manage-api/ |
JUnit + Spring Boot Test |
| 管理后台 Web | Vue.js | gym-manage-web/ |
Playwright E2E |
| 会员小程序 | UniApp | gym-manage-uniapp/ |
— |
| 端到端测试 | Playwright | e2e-tests/ |
Playwright |
后端模块映射
| 模块 | 目录 | 职责 |
|---|---|---|
| manage-app | gym-manage-api/manage-app/ |
应用启动入口、配置中心 |
| manage-gateway | gym-manage-api/manage-gateway/ |
API 网关、路由转发 |
| manage-common | gym-manage-api/manage-common/ |
公共工具、通用组件 |
| manage-db | gym-manage-api/manage-db/ |
数据库迁移（Flyway）、基础实体 |
| manage-sys | gym-manage-api/manage-sys/ |
系统管理（用户/角色/权限/菜单/字典/文件/通知/日志） |
| manage-audit | gym-manage-api/manage-audit/ |
审计日志 |
| manage-file | gym-manage-api/manage-file/ |
文件管理 |
| manage-notify | gym-manage-api/manage-notify/ |
消息通知 |
| gym-auth | gym-manage-api/gym-auth/ |
认证授权、JWT |
| gym-member | gym-manage-api/gym-member/ |
会员管理（注册/信息/会员卡） |
| gym-groupCourse | gym-manage-api/gym-groupCourse/ |
团课管理、团课预约 |
| gym-checkIn | gym-manage-api/gym-checkIn/ |
签到管理 |
| gym-dataCount | gym-manage-api/gym-dataCount/ |
数据统计 |
| gym-payment | gym-manage-api/gym-payment/ |
支付集成、支付对账 |
涉及模块的判断原则
在 /to-issues 和 /test-driven-development 阶段，根据功能需求确定涉及的模块。例如：
- "会员卡购买" →
gym-member+gym-payment+gym-manage-web+gym-manage-uniapp - "团课预约" →
gym-groupCourse+gym-member+gym-manage-uniapp - "系统管理"类功能 →
manage-sys+gym-manage-web
工作流总览
/grill-with-docs → /to-prd → /to-issues → /test-driven-development
↓ ↓ ↓ ↓
需求澄清 结构化PRD 任务拆解 TDD实现
+ 领域建模
(CONTEXT.md)
0. /domain-modeling — 领域建模（贯穿全流程）
目标：建立并维护项目的统一语言（Ubiquitous Language），确保需求、设计、代码中术语一致。
核心产出
- 项目根目录的 CONTEXT.md — 术语表，不含任何实现细节，纯粹的概念定义和关系。
执行时机
- 在
/grill-with-docs阶段：识别新术语，与用户确认定义，写入CONTEXT.md。 - 在
/to-prd阶段：引用CONTEXT.md中的术语，保持 PRD 术语一致。 - 在
/to-issues阶段：确保每个 Issue 使用的术语与CONTEXT.md对齐。 - 在
/test-driven-development阶段：代码中的类名、方法名、变量名需反映领域术语。
领域术语规则
- 挑战模糊语言：当用户使用模糊或过载的术语时，提出精确的规范术语。例如："你说的'账户'是指会员(Member)还是用户(User)？它们是不同的概念。"
- 冲突检测：当用户使用的术语与
CONTEXT.md中已定义的不同时，立即指出："你的术语表将'取消'定义为 X，但你现在似乎指 Y — 是哪个？" - 场景验证：用具体的边界场景压力测试领域关系。例如："如果会员卡已过期，预约还能取消吗？"
- 代码交叉验证：当需要确认某个术语的实际语义时，查阅现有代码实现，如有矛盾及时指出。
更新原则
- 术语一经确认，立即更新
CONTEXT.md，不要批量处理。 - 只在有实际产出时才创建或修改
CONTEXT.md。
1. /grill-with-docs — 需求澄清与领域建模
目标：通过结构化问答 + 领域建模，将模糊需求转化为清晰、文档化的共识。
触发条件
- 用户提出新功能需求但描述不完整
- 需求存在歧义或矛盾
- 需要明确验收标准
执行流程
- 收集原始需求：理解用户意图，记录关键信息。
- 启动领域建模：识别需求中涉及的领域概念，对照 CONTEXT.md 检查术语一致性，新术语与用户确认后写入。
- 识别模糊点：主动指出需求中的歧义、缺失、矛盾之处。
- 逐轮问答：每次只问 1-2 个关键问题，避免信息过载。使用
AskUserQuestion工具。 - 生成共识文档：将确认后的需求写入
docs/superpowers/plans/目录，文件名格式为{YYYY-MM-DD}-{功能名称}-grill.md，内容包括：- 功能概述
- 用户故事
- 业务流程（Mermaid 流程图）
- 验收标准
- 涉及的领域概念（引用
CONTEXT.md） - 非功能需求
- 待确认项（如有）
规则
- 不要在分歧未解决前进入下一阶段。
- 所有关键决策需用户确认。
- 文档使用中文，保持与项目已有文档风格一致。
- 新术语必须写入
CONTEXT.md后再用于文档。
2. /to-prd — 生成产品需求文档
目标：将澄清后的需求转化为结构化的 PRD。
输入
/grill-with-docs生成的共识文档（docs/superpowers/plans/{日期}-{功能名称}-grill.md）- 项目的功能清单文档（基础版功能清单.md）
- 领域术语表（CONTEXT.md）
执行流程
- 读取共识文档：理解需求全貌。
- 参考现有规范：对照 基础版功能清单.md 中的优先级定义（P0/P1/P2/P3）、技术规范和文档风格。
- 术语对齐：对照 CONTEXT.md，确保 PRD 使用的所有业务术语与术语表一致。
- 生成 PRD：将 PRD 写入
docs/superpowers/specs/目录，文件名格式为{YYYY-MM-DD}-{功能名称}-prd.md，内容结构：- 文档元信息（编号、版本、日期、状态）
- 功能概述与目标
- 用户故事（As a... I want... So that...）
- 功能详细描述（功能点、优先级、验收标准、依赖关系、预计工时）
- 涉及的后端模块（参考模块映射表）
- 业务流程（Mermaid 流程图）
- 业务规则
- 非功能需求（性能、安全、可用性）
- UI/UX 要求（如适用）
- 技术要点建议
规则
- PRD 格式严格对齐 基础版功能清单.md 的风格。
- 优先级标记使用 P0/P1/P2/P3 体系。
- 每个功能点必须有明确的验收标准。
- 必须在 PRD 中标注涉及的后端模块和前端应用。
3. /to-issues — 任务拆解
目标：将 PRD 拆解成可独立执行、可验证的具体任务（Issues）。
输入
/to-prd生成的 PRD（docs/superpowers/specs/{日期}-{功能名称}-prd.md）- 领域术语表（CONTEXT.md）
拆解原则
纵向拆分（全栈 Issue）：每个 Issue 按功能维度拆分，覆盖完整的前后端链路。
- 一个 Issue = 一个可独立交付的功能点，包含后端 API + Web 前端 + 小程序（按需）。
- TDD 顺序：后端单元测试 → 后端实现 → 前端 E2E 测试 → 前端实现。
粒度控制：
- 预计工时不超过 2 天，超过则继续拆解。
- Issue 粒度应足够小，确保一个 Issue 可以在一轮对话中实现。
优先级与排序：
- P0 任务排在 P1 之前，同一优先级下按依赖拓扑排序。
- 每个 Issue 标注依赖关系。
输出
写入 docs/superpowers/issues/ 目录（如不存在则创建），文件名格式为 ISSUES-{功能名称}.md，内容结构：
## GYM-{编号}: {标题}
- **优先级**: P0 / P1 / P2 / P3
- **预计工时**: {天数}天
- **依赖**: GYM-{编号} 或 无
- **涉及模块**: 后端模块列表 + 前端应用列表
- **领域术语**: 引用的 CONTEXT.md 术语
### 验收标准
1. 后端单元测试通过
2. E2E 测试通过
3. ...
### 技术要点
- 要点 1
- 要点 2
4. /test-driven-development — 测试驱动开发
目标：采用 TDD 方式，按 Red-Green-Refactor 循环逐个实现 Issues。
前置步骤（每个 Issue 开始前必须执行）
- 阅读 Issue 描述：理解全栈范围（涉及哪些后端模块和前端应用）。
- 阅读 CONTEXT.md：确认使用的领域术语，确保代码命名一致。
- 阅读现有测试基础设施：
- E2E 测试：
e2e-tests/helpers/（TestDataManager、TestStabilityHelper、auth.ts）、e2e-tests/pages/（Page Object 模式）、e2e-tests/fixtures/、e2e-tests/utils/（TestDataFactory、RetryHelper、api-client） - 后端测试：参考
gym-checkIn/src/test/、gym-payment/src/test/等现有模块测试用例的风格和结构 - 遵循已有的 Page Object、DataFactory、Smoke/Journey 测试分层 pattern
- E2E 测试：
执行流程
按 Issue 顺序逐个实现，每个 Issue 遵循三步循环：
Step 1: Red — 编写失败的测试
- 先写后端单元测试（JUnit），验证 API 逻辑和边界条件。
- 运行后端测试，确认测试失败（红色）。
- 写前端 E2E 测试（Playwright），覆盖用户操作链路。
- 运行 E2E 测试，确认测试失败（红色）。
Step 2: Green — 编写最小实现
- 编写后端 API 代码，刚好让单元测试通过。
- 运行后端测试，确认通过（绿色）。
- 编写前端代码，刚好让 E2E 测试通过。
- 运行 E2E 测试，确认通过（绿色）。
- 不添加任何测试未覆盖的功能。
Step 3: Refactor — 重构优化
- 在全部测试保持绿色的前提下重构代码。
- 消除重复、改善命名（对齐
CONTEXT.md术语）、优化结构。 - 运行全部测试，确认仍然通过。
规则
- 一个 Issue 完成后再开始下一个。
- 每次只改最少代码。
- 测试优先覆盖核心逻辑和边界条件。
- 代码风格严格遵循项目现有规范。
- 代码命名必须对齐 CONTEXT.md 中的领域术语。
- 所有测试通过后方可标记 Issue 为完成。
5. /systemic-debugging — 系统化调试
目标：当遇到复杂 Bug 时，通过系统化诊断流程定位根因并修复。
触发条件
- 遇到难以复现的 Bug
- 多轮尝试修复无效
- 用户明确请求调试
执行流程
- 定义问题：明确描述 Bug 的现象、触发条件和预期行为。
- 收集证据：查看相关日志、错误堆栈、数据库状态（检查 Flyway 迁移版本）、网络请求等。
- 建立假设：基于证据提出 1-3 个可能的根因假设。
- 验证假设：通过添加日志、编写最小复现用例、断点调试等方式验证或排除假设。一次只验证一个假设。
- 修复与验证：定位根因后编写修复代码，确保测试覆盖该场景。
- 回归检查：运行全部测试（后端 JUnit + 前端 E2E），确保修复未引入新问题。
规则
- 不要猜测式修复，每一步必须有证据支撑。
- 每次只验证一个假设。
- 修复后必须添加对应的回归测试。
目录结构约定
gym-manage/
├── AGENT.md # 本文件
├── CONTEXT.md # 领域术语表（统一语言）
├── 基础版功能清单.md # 项目功能清单（参考规范）
├── docs/
│ └── superpowers/ # AI 协作产出物
│ ├── plans/ # 需求澄清文档（/grill-with-docs 产出）
│ │ └── {YYYY-MM-DD}-{功能名称}-grill.md
│ ├── specs/ # PRD（/to-prd 产出）
│ │ └── {YYYY-MM-DD}-{功能名称}-prd.md
│ └── issues/ # 任务拆解（/to-issues 产出）
│ └── ISSUES-{功能名称}.md
├── gym-manage-api/ # 后端 Java Spring Boot 多模块
│ ├── manage-app/ # 应用启动入口
│ ├── manage-gateway/ # API 网关
│ ├── manage-common/ # 公共组件
│ ├── manage-db/ # 数据库迁移
│ ├── manage-sys/ # 系统管理
│ ├── manage-audit/ # 审计日志
│ ├── manage-file/ # 文件管理
│ ├── manage-notify/ # 消息通知
│ ├── gym-auth/ # 认证授权
│ ├── gym-member/ # 会员管理
│ ├── gym-groupCourse/ # 团课管理
│ ├── gym-checkIn/ # 签到管理
│ ├── gym-dataCount/ # 数据统计
│ └── gym-payment/ # 支付集成
├── gym-manage-web/ # 管理后台 Web 前端
├── gym-manage-uniapp/ # 会员小程序前端
└── e2e-tests/ # 端到端测试
├── helpers/ # TestDataManager、auth 等
├── pages/ # Page Object 模式
├── fixtures/ # 测试数据
├── utils/ # TestDataFactory、RetryHelper
├── journeys/ # 用户旅程测试
└── smoke/ # 冒烟测试
通用规则
- 语言：所有文档和代码注释使用中文，代码标识符使用英文。
- 术语对齐：所有文档和代码中的业务术语必须对齐 CONTEXT.md。
- 风格对齐：严格遵循项目现有代码风格和文档风格。
- 每一步确认：关键产出（grill 文档、PRD、Issues）完成后通知用户确认再继续。
- 最小化原则：不添加需求范围外的功能，不引入不必要的复杂度。
- 测试优先：后端单元测试和前端 E2E 测试必须在新代码之前编写。