gym-manage/AGENT.md

# 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](./CONTEXT.md) — 术语表，不含任何实现细节，纯粹的概念定义和关系。

### 执行时机
- **在 `/grill-with-docs` 阶段**：识别新术语，与用户确认定义，写入 `CONTEXT.md`。
- **在 `/to-prd` 阶段**：引用 `CONTEXT.md` 中的术语，保持 PRD 术语一致。
- **在 `/to-issues` 阶段**：确保每个 Issue 使用的术语与 `CONTEXT.md` 对齐。
- **在 `/test-driven-development` 阶段**：代码中的类名、方法名、变量名需反映领域术语。

### 领域术语规则
1. **挑战模糊语言**：当用户使用模糊或过载的术语时，提出精确的规范术语。例如："你说的'账户'是指会员(Member)还是用户(User)？它们是不同的概念。"
2. **冲突检测**：当用户使用的术语与 `CONTEXT.md` 中已定义的不同时，立即指出："你的术语表将'取消'定义为 X，但你现在似乎指 Y — 是哪个？"
3. **场景验证**：用具体的边界场景压力测试领域关系。例如："如果会员卡已过期，预约还能取消吗？"
4. **代码交叉验证**：当需要确认某个术语的实际语义时，查阅现有代码实现，如有矛盾及时指出。

### 更新原则
- 术语一经确认，立即更新 `CONTEXT.md`，不要批量处理。
- 只在有实际产出时才创建或修改 `CONTEXT.md`。

---

## 1. /grill-with-docs — 需求澄清与领域建模

**目标**：通过结构化问答 + 领域建模，将模糊需求转化为清晰、文档化的共识。

### 触发条件
- 用户提出新功能需求但描述不完整
- 需求存在歧义或矛盾
- 需要明确验收标准

### 执行流程

1. **收集原始需求**：理解用户意图，记录关键信息。
2. **启动领域建模**：识别需求中涉及的领域概念，对照 [CONTEXT.md](./CONTEXT.md) 检查术语一致性，新术语与用户确认后写入。
3. **识别模糊点**：主动指出需求中的歧义、缺失、矛盾之处。
4. **逐轮问答**：每次只问 1-2 个关键问题，避免信息过载。使用 `AskUserQuestion` 工具。
5. **生成共识文档**：将确认后的需求写入 `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](./基础版功能清单.md)）
- 领域术语表（[CONTEXT.md](./CONTEXT.md)）

### 执行流程

1. **读取共识文档**：理解需求全貌。
2. **参考现有规范**：对照 [基础版功能清单.md](./基础版功能清单.md) 中的优先级定义（P0/P1/P2/P3）、技术规范和文档风格。
3. **术语对齐**：对照 [CONTEXT.md](./CONTEXT.md)，确保 PRD 使用的所有业务术语与术语表一致。
4. **生成 PRD**：将 PRD 写入 `docs/superpowers/specs/` 目录，文件名格式为 `{YYYY-MM-DD}-{功能名称}-prd.md`，内容结构：
   - 文档元信息（编号、版本、日期、状态）
   - 功能概述与目标
   - 用户故事（As a... I want... So that...）
   - 功能详细描述（功能点、优先级、验收标准、依赖关系、预计工时）
   - 涉及的后端模块（参考模块映射表）
   - 业务流程（Mermaid 流程图）
   - 业务规则
   - 非功能需求（性能、安全、可用性）
   - UI/UX 要求（如适用）
   - 技术要点建议

### 规则
- PRD 格式严格对齐 [基础版功能清单.md](./基础版功能清单.md) 的风格。
- 优先级标记使用 P0/P1/P2/P3 体系。
- 每个功能点必须有明确的验收标准。
- 必须在 PRD 中标注涉及的后端模块和前端应用。

---

## 3. /to-issues — 任务拆解

**目标**：将 PRD 拆解成可独立执行、可验证的具体任务（Issues）。

### 输入
- `/to-prd` 生成的 PRD（`docs/superpowers/specs/{日期}-{功能名称}-prd.md`）
- 领域术语表（[CONTEXT.md](./CONTEXT.md)）

### 拆解原则

**纵向拆分（全栈 Issue）**：每个 Issue 按功能维度拆分，覆盖完整的前后端链路。
- 一个 Issue = 一个可独立交付的功能点，包含后端 API + Web 前端 + 小程序（按需）。
- TDD 顺序：后端单元测试 → 后端实现 → 前端 E2E 测试 → 前端实现。

**粒度控制**：
- 预计工时不超过 2 天，超过则继续拆解。
- Issue 粒度应足够小，确保一个 Issue 可以在一轮对话中实现。

**优先级与排序**：
- P0 任务排在 P1 之前，同一优先级下按依赖拓扑排序。
- 每个 Issue 标注依赖关系。

### 输出

写入 `docs/superpowers/issues/` 目录（如不存在则创建），文件名格式为 `ISSUES-{功能名称}.md`，内容结构：

```markdown
## GYM-{编号}: {标题}

- **优先级**: P0 / P1 / P2 / P3
- **预计工时**: {天数}天
- **依赖**: GYM-{编号} 或 无
- **涉及模块**: 后端模块列表 + 前端应用列表
- **领域术语**: 引用的 CONTEXT.md 术语

### 验收标准
1. 后端单元测试通过
2. E2E 测试通过
3. ...

### 技术要点
- 要点 1
- 要点 2
```

---

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

**目标**：采用 TDD 方式，按 Red-Green-Refactor 循环逐个实现 Issues。

### 前置步骤（每个 Issue 开始前必须执行）

1. **阅读 Issue 描述**：理解全栈范围（涉及哪些后端模块和前端应用）。
2. **阅读 [CONTEXT.md](./CONTEXT.md)**：确认使用的领域术语，确保代码命名一致。
3. **阅读现有测试基础设施**：
   - 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

### 执行流程

按 Issue 顺序逐个实现，每个 Issue 遵循三步循环：

#### Step 1: Red — 编写失败的测试
1. 先写后端单元测试（JUnit），验证 API 逻辑和边界条件。
2. 运行后端测试，确认测试失败（红色）。
3. 写前端 E2E 测试（Playwright），覆盖用户操作链路。
4. 运行 E2E 测试，确认测试失败（红色）。

#### Step 2: Green — 编写最小实现
1. 编写后端 API 代码，刚好让单元测试通过。
2. 运行后端测试，确认通过（绿色）。
3. 编写前端代码，刚好让 E2E 测试通过。
4. 运行 E2E 测试，确认通过（绿色）。
5. 不添加任何测试未覆盖的功能。

#### Step 3: Refactor — 重构优化
1. 在全部测试保持绿色的前提下重构代码。
2. 消除重复、改善命名（对齐 `CONTEXT.md` 术语）、优化结构。
3. 运行全部测试，确认仍然通过。

### 规则
- 一个 Issue 完成后再开始下一个。
- 每次只改最少代码。
- 测试优先覆盖核心逻辑和边界条件。
- 代码风格严格遵循项目现有规范。
- 代码命名必须对齐 [CONTEXT.md](./CONTEXT.md) 中的领域术语。
- 所有测试通过后方可标记 Issue 为完成。

---

## 5. /systemic-debugging — 系统化调试

**目标**：当遇到复杂 Bug 时，通过系统化诊断流程定位根因并修复。

### 触发条件
- 遇到难以复现的 Bug
- 多轮尝试修复无效
- 用户明确请求调试

### 执行流程

1. **定义问题**：明确描述 Bug 的现象、触发条件和预期行为。
2. **收集证据**：查看相关日志、错误堆栈、数据库状态（检查 Flyway 迁移版本）、网络请求等。
3. **建立假设**：基于证据提出 1-3 个可能的根因假设。
4. **验证假设**：通过添加日志、编写最小复现用例、断点调试等方式验证或排除假设。一次只验证一个假设。
5. **修复与验证**：定位根因后编写修复代码，确保测试覆盖该场景。
6. **回归检查**：运行全部测试（后端 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](./CONTEXT.md)。
- **风格对齐**：严格遵循项目现有代码风格和文档风格。
- **每一步确认**：关键产出（grill 文档、PRD、Issues）完成后通知用户确认再继续。
- **最小化原则**：不添加需求范围外的功能，不引入不必要的复杂度。
- **测试优先**：后端单元测试和前端 E2E 测试必须在新代码之前编写。