zhangxiang
015cb0dc78
W1-W3: 基线修复与测试基础设施搭建 - 修复 Jenkins JDK 21 兼容性，统一 E2E 目录，修复 storageState 冲突 - 搭建后端测试基类 BaseContractTest + Testcontainers PostgreSQL - 创建 TestDataFactory 链式构造，完善 Vitest 基座与 Playwright fixtures - 建立 docker-compose.test.yml 与测试数据隔离方案 W4-W5: 单元测试补齐（阶段 2） - 补齐 gym-member/gym-groupCourse/gym-checkIn/gym-payment 核心模块单元测试 - 补齐 gym-coach/manage-sys 模块单元测试 - 前端 utils/composables/stores 单元测试，37 文件 502 项测试 - JaCoCo 覆盖率门禁从 30% 调整至 55%，21 模块全部通过 W6-W7: 集成与契约测试（阶段 3） - Repository 集成测试：会员/团课/签到/支付关键表，Testcontainers 100% 通过 - Handler 集成测试：WebTestClient 覆盖正向/异常/权限路径 - 网关集成测试：JWT/RBAC/签名/限流/重试 - Flyway 迁移测试：验证迁移脚本可重复执行 - OpenAPI 契约测试：覆盖 ≥80% P0 接口，202 项契约测试 0 失败 - 跨模块契约测试：会员-支付-团课数据一致性 W8-W9: E2E 与用户旅程测试（阶段 4） - 管理员 Web 核心流程 E2E：用户/角色/菜单/字典/配置 - 小程序会员端核心页面 E2E：购卡/预约/签到 - 5 条 P0 用户旅程全链路自动化，60 条 journey 测试 0 失败 W10: 变异测试与质量门禁（阶段 5） - 后端 PIT 配置：pitest-maven 1.19.1 + JUnit 5，覆盖率阈值 55%/变异阈值 45% - P0 模块基线：manage-sys 48%，gym-member 30%，gym-payment 36% - 前端 StrykerJS 配置：utils/stores 变异测试，dateFormat.ts 70.83% - Jenkins 质量门禁：JaCoCo/PIT/E2E 统一检查，不达标阻断构建 W11: 持续运行与改进（阶段 6） - 测试指标收集脚本 scripts/collect-test-metrics.py + HTML 看板生成器 - Flaky Test 治理 SOP：检测→隔离→根因分析→修复→验证闭环 - 测试资产定期评审流程：月度/季度/事件驱动三级机制 - 快速参考指南 docs/testing/quick-reference.md - 累计 10 份测试文档，7 个里程碑全部达成
3.8 KiB
3.8 KiB
AGENT.md
面向 AI 代理的健身房管理系统开发工作流指南。
本文件补充
AGENTS.md的通用 Agent 行为规则，提供本项目特定的架构、命令、测试策略与服务端口信息。项目子模块：
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;"