novalon/gym-manage
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(backend): 重命名后端项目为 gym-manage-api，修改包名为 cn.novalon.gym.manage

Browse Source
This commit is contained in:
张翔
2026-04-17 18:35:50 +08:00
parent 666189b676
commit deb961c427
916 changed files with 108360 additions and 38328 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/00-INDEX/README.md
-58
View File
@@ -1,58 +0,0 @@
# 📚 健身房管理系统文档中心
> 文档编号: GYM-INDEX-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 快速导航
### 按角色导航
- **产品经理** → [需求文档](../01-REQUIREMENTS/) | [产品迭代计划](../05-PLANS/产品迭代计划.md)
- **架构师** → [架构文档](../02-ARCHITECTURE/) | [评估报告](../03-EVALUATION/)
- **开发工程师** → [技术架构](../02-ARCHITECTURE/技术架构/) | [API设计](../02-ARCHITECTURE/技术架构/API-接口设计规范.md)
- **测试工程师** → [测试文档](../04-IMPLEMENTATION/测试文档/) | [评估报告](../03-EVALUATION/)
- **运维工程师** → [部署运维](../04-IMPLEMENTATION/部署运维/) | [安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
- **客户** → [产品介绍](../06-CUSTOMER/产品介绍手册.md) | [定价策略](../06-CUSTOMER/定价策略.md)
### 按阶段导航
- **需求分析阶段** → [PRD文档](../01-REQUIREMENTS/) | [竞品分析](../01-REQUIREMENTS/竞品分析与系统能力评估报告.md)
- **架构设计阶段** → [业务架构](../02-ARCHITECTURE/业务架构/) | [技术架构](../02-ARCHITECTURE/技术架构/)
- **评估验证阶段** → [评估报告](../03-EVALUATION/) | [改进路线图](../05-PLANS/改进路线图.md)
- **实施部署阶段** → [部署运维](../04-IMPLEMENTATION/部署运维/) | [测试文档](../04-IMPLEMENTATION/测试文档/)
### 按场景导航
- **会员预约高峰期** → [性能评估](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md) | [技术设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
- **支付流程** → [安全评估](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md) | [安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
- **系统故障恢复** → [容错评估](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md) | [运维文档](../04-IMPLEMENTATION/部署运维/OPS-部署运维文档.md)
---
## 文档统计
- 总文档数：40+
- 需求文档：5
- 架构文档：15
- 评估报告：5
- 实施文档：8
- 计划文档：5
- 客户文档：2
---
## 最近更新
- 2026-04-04：创建文档索引中心，建立多维索引体系
- 2026-03-08：完成文档架构优化，建立三层文档体系（B-HLD、B-LLD、T-ILD）
- 2026-03-09：新增业务KPI定义、产品迭代计划、功能优先级矩阵文档
---
## 文档维护
- 文档管理规范：[查看](../08-STANDARDS/文档管理规范.md)
- 文档更新流程：[查看](../08-STANDARDS/文档管理规范.md#文档更新规范)
- 文档审查机制：[查看](../08-STANDARDS/文档管理规范.md#文档审查机制)
docs/00-INDEX/文档关系图谱.md
-51
View File
@@ -1,51 +0,0 @@
# 文档关系图谱
> 文档编号: GYM-INDEX-GRAPH-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 核心文档依赖关系
```mermaid
graph TD
A[PRD-基础版产品设计文档] --> B[B-HLD-基础版-业务概要设计]
A --> C[业务KPI定义]
B --> D[B-LLD-基础版-业务详细设计]
D --> E[T-ILD-基础版-技术实现详细设计]
E --> F[DB-数据库设计]
E --> G[API-接口设计规范]
E --> H[SEC-安全设计]
I[PRD-付费订阅版产品设计文档] --> J[B-HLD-付费订阅版-业务概要设计]
J --> K[B-LLD-付费订阅版-业务详细设计]
K --> L[T-ILD-付费订阅版-技术实现详细设计]
E --> M[EVAL-001-架构合理性评估报告]
E --> N[EVAL-002-性能与可扩展性评估报告]
H --> O[EVAL-003-安全性与容错能力评估报告]
E --> P[EVAL-004-资源利用率评估报告]
M --> Q[EVAL-综合评估总结报告]
N --> Q
O --> Q
P --> Q
Q --> R[改进路线图]
```
---
## 文档版本依赖矩阵
| 文档 | 版本 | 依赖文档 | 版本要求 |
|------|------|---------|---------|
| T-ILD-基础版 | v1.0 | PRD-基础版 | v1.0+ |
| T-ILD-基础版 | v1.0 | B-HLD-基础版 | v1.0+ |
| T-ILD-基础版 | v1.0 | B-LLD-基础版 | v1.0+ |
| T-ILD-付费订阅版 | v1.0 | PRD-付费订阅版 | v1.0+ |
| T-ILD-付费订阅版 | v1.0 | B-HLD-付费订阅版 | v1.0+ |
| T-ILD-付费订阅版 | v1.0 | B-LLD-付费订阅版 | v1.0+ |
| EVAL-综合评估总结报告 | v1.0 | EVAL-001/002/003/004 | v1.0+ |
docs/00-INDEX/文档索引-按场景.md
-118
View File
@@ -1,118 +0,0 @@
# 文档索引 - 按业务场景
> 文档编号: GYM-INDEX-SCENARIO-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 场景1：会员预约高峰期
**场景描述**：每天18:00-20:00，会员集中预约团课，系统需要支持高并发请求。
**相关文档**：
### 需求文档
- [PRD-基础版产品设计文档](../01-REQUIREMENTS/PRD-基础版产品设计文档.md) - 预约管理模块
- [业务KPI定义](../01-REQUIREMENTS/业务KPI定义.md) - 预约转化率、并发用户数
### 架构文档
- [B-LLD-基础版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-基础版-业务详细设计.md) - 预约业务流程
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md) - 预约模块技术实现
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md) - 预约表设计
- [API-接口设计规范](../02-ARCHITECTURE/技术架构/API-接口设计规范.md) - 预约接口设计
### 评估报告
- [EVAL-002-性能与可扩展性评估报告](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md) - 高并发性能评估
- [EVAL-004-资源利用率评估报告](../03-EVALUATION/EVAL-004-资源利用率评估报告.md) - 资源瓶颈分析
### 改进方案
- [改进路线图](../05-PLANS/改进路线图.md) - 预约高峰期性能优化
---
## 场景2：支付流程
**场景描述**：会员购买会员卡或续费，系统需要保障支付安全和数据一致性。
**相关文档**：
### 需求文档
- [PRD-付费订阅版产品设计文档](../01-REQUIREMENTS/PRD-付费订阅版产品设计文档.md) - 订阅管理模块
- [业务KPI定义](../01-REQUIREMENTS/业务KPI定义.md) - 支付成功率、客单价
### 架构文档
- [B-LLD-付费订阅版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-付费订阅版-业务详细设计.md) - 支付业务流程
- [T-ILD-付费订阅版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-付费订阅版-技术实现详细设计.md) - 支付模块技术实现
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md) - 支付安全设计
- [API-接口设计规范](../02-ARCHITECTURE/技术架构/API-接口设计规范.md) - 支付接口设计
### 评估报告
- [EVAL-003-安全性与容错能力评估报告](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md) - 支付安全评估
- [EVAL-001-架构合理性评估报告](../03-EVALUATION/EVAL-001-架构合理性评估报告.md) - 事务一致性评估
### 改进方案
- [改进路线图](../05-PLANS/改进路线图.md) - 支付接口幂等性校验
---
## 场景3：系统故障恢复
**场景描述**：系统出现故障时，需要快速检测、隔离和恢复，保障业务连续性。
**相关文档**：
### 架构文档
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md) - 容错机制设计
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md) - 数据备份与恢复
- [OPS-部署运维文档](../04-IMPLEMENTATION/部署运维/OPS-部署运维文档.md) - 故障处理流程
### 评估报告
- [EVAL-003-安全性与容错能力评估报告](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md) - 容错能力评估
- [EVAL-004-资源利用率评估报告](../03-EVALUATION/EVAL-004-资源利用率评估报告.md) - 资源瓶颈分析
### 改进方案
- [改进路线图](../05-PLANS/改进路线图.md) - 监控告警完善、缓存穿透防护
---
## 场景4：数据统计分析
**场景描述**：管理员查看业务数据统计报表，系统需要支持复杂查询和数据分析。
**相关文档**：
### 需求文档
- [PRD-基础版产品设计文档](../01-REQUIREMENTS/PRD-基础版产品设计文档.md) - 数据统计模块
- [业务KPI定义](../01-REQUIREMENTS/业务KPI定义.md) - 各类KPI指标
### 架构文档
- [B-LLD-基础版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-基础版-业务详细设计.md) - 统计业务流程
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md) - 统计模块技术实现
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md) - 统计表设计
### 评估报告
- [EVAL-002-性能与可扩展性评估报告](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md) - 查询性能评估
---
## 场景5：会员签到
**场景描述**：会员到店签到，系统需要支持多种签到方式（人脸、NFC、二维码）。
**相关文档**：
### 需求文档
- [PRD-基础版产品设计文档](../01-REQUIREMENTS/PRD-基础版产品设计文档.md) - 签到管理模块
- [业务KPI定义](../01-REQUIREMENTS/业务KPI定义.md) - 签到率、DAU
### 架构文档
- [B-LLD-基础版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-基础版-业务详细设计.md) - 签到业务流程
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md) - 签到模块技术实现
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md) - 签到表设计
- [API-接口设计规范](../02-ARCHITECTURE/技术架构/API-接口设计规范.md) - 签到接口设计
### 评估报告
- [EVAL-002-性能与可扩展性评估报告](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md) - 签到高峰期性能评估
docs/00-INDEX/文档索引-按类型.md
-107
View File
@@ -1,107 +0,0 @@
# 文档索引 - 按类型
> 文档编号: GYM-INDEX-TYPE-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 需求文档
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| PRD-基础版产品设计文档 | GYM-PRD-BASIC-001 | v1.0 | 正式发布 | [链接](../01-REQUIREMENTS/PRD-基础版产品设计文档.md) |
| PRD-付费订阅版产品设计文档 | GYM-PRD-SUBSCRIPTION-001 | v1.0 | 正式发布 | [链接](../01-REQUIREMENTS/PRD-付费订阅版产品设计文档.md) |
| 业务KPI定义 | GYM-BUSINESS-KPI-001 | v1.0 | 正式发布 | [链接](../01-REQUIREMENTS/业务KPI定义.md) |
| 竞品分析与系统能力评估报告 | GYM-ANALYSIS-001 | v1.0 | 正式发布 | [链接](../01-REQUIREMENTS/竞品分析与系统能力评估报告.md) |
---
## 架构文档
### 业务架构
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| B-HLD-基础版-业务概要设计 | GYM-B-HLD-BASIC-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/业务架构/B-HLD-基础版-业务概要设计.md) |
| B-HLD-付费订阅版-业务概要设计 | GYM-B-HLD-SUBSCRIPTION-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/业务架构/B-HLD-付费订阅版-业务概要设计.md) |
| B-LLD-基础版-业务详细设计 | GYM-B-LLD-BASIC-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/业务架构/B-LLD-基础版-业务详细设计.md) |
| B-LLD-付费订阅版-业务详细设计 | GYM-B-LLD-SUBSCRIPTION-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/业务架构/B-LLD-付费订阅版-业务详细设计.md) |
### 技术架构
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| T-ILD-基础版-技术实现详细设计 | GYM-T-ILD-BASIC-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md) |
| T-ILD-付费订阅版-技术实现详细设计 | GYM-T-ILD-SUBSCRIPTION-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/技术架构/T-ILD-付费订阅版-技术实现详细设计.md) |
| DB-数据库设计 | GYM-DB-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/技术架构/DB-数据库设计.md) |
| API-接口设计规范 | GYM-API-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/技术架构/API-接口设计规范.md) |
| SEC-安全设计 | GYM-SEC-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/技术架构/SEC-安全设计.md) |
### 架构决策记录
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| ADR-001-单体应用选型 | GYM-ADR-001 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/架构决策记录/ADR-001-单体应用选型.md) |
| ADR-002-响应式编程选型 | GYM-ADR-002 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md) |
| ADR-003-数据库选型 | GYM-ADR-003 | v1.0 | 正式发布 | [链接](../02-ARCHITECTURE/架构决策记录/ADR-003-数据库选型.md) |
---
## 评估报告
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| EVAL-001-架构合理性评估报告 | GYM-EVAL-001 | v1.0 | 正式发布 | [链接](../03-EVALUATION/EVAL-001-架构合理性评估报告.md) |
| EVAL-002-性能与可扩展性评估报告 | GYM-EVAL-002 | v1.0 | 正式发布 | [链接](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md) |
| EVAL-003-安全性与容错能力评估报告 | GYM-EVAL-003 | v1.0 | 正式发布 | [链接](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md) |
| EVAL-004-资源利用率评估报告 | GYM-EVAL-004 | v1.0 | 正式发布 | [链接](../03-EVALUATION/EVAL-004-资源利用率评估报告.md) |
| EVAL-综合评估总结报告 | GYM-EVAL-SUMMARY-001 | v1.0 | 正式发布 | [链接](../03-EVALUATION/EVAL-综合评估总结报告.md) |
---
## 实施文档
### 部署运维
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| OPS-部署运维文档 | GYM-OPS-001 | v1.0 | 正式发布 | [链接](../04-IMPLEMENTATION/部署运维/OPS-部署运维文档.md) |
### 前端工程化
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| 前端工程化建设文档 | GYM-FRONTEND-001 | v1.0 | 正式发布 | [链接](../04-IMPLEMENTATION/前端工程化/前端工程化建设文档.md) |
| 前端技术架构详细设计 | GYM-FRONTEND-002 | v1.0 | 正式发布 | [链接](../04-IMPLEMENTATION/前端工程化/前端技术架构详细设计.md) |
---
## 计划文档
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| 产品迭代计划 | GYM-PLAN-ITERATION-001 | v1.0 | 正式发布 | [链接](../05-PLANS/产品迭代计划.md) |
| 功能优先级矩阵 | GYM-PLAN-PRIORITY-001 | v1.0 | 正式发布 | [链接](../05-PLANS/功能优先级矩阵.md) |
| 技术复杂度评估 | GYM-PLAN-COMPLEXITY-001 | v1.0 | 正式发布 | [链接](../05-PLANS/技术复杂度评估.md) |
| 改进路线图 | GYM-PLAN-ROADMAP-001 | v1.0 | 正式发布 | [链接](../05-PLANS/改进路线图.md) |
---
## 客户文档
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| 产品介绍手册 | GYM-CUSTOMER-001 | v1.0 | 正式发布 | [链接](../06-CUSTOMER/产品介绍手册.md) |
| 定价策略 | GYM-PRICING-001 | v1.0 | 正式发布 | [链接](../06-CUSTOMER/定价策略.md) |
---
## 规范文档
| 文档名称 | 编号 | 版本 | 状态 | 路径 |
|---------|------|------|------|------|
| 文档管理规范 | GYM-DOC-STANDARD-001 | v1.0 | 正式发布 | [链接](../08-STANDARDS/文档管理规范.md) |
| 文档清单 | GYM-DOC-LIST-001 | v1.9 | 正式发布 | [链接](../08-STANDARDS/文档清单.md) |
docs/00-INDEX/文档索引-按阶段.md
-85
View File
@@ -1,85 +0,0 @@
# 文档索引 - 按项目阶段
> 文档编号: GYM-INDEX-STAGE-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 阶段1：需求分析
### 核心文档
- [PRD-基础版产品设计文档](../01-REQUIREMENTS/PRD-基础版产品设计文档.md)
- [PRD-付费订阅版产品设计文档](../01-REQUIREMENTS/PRD-付费订阅版产品设计文档.md)
- [业务KPI定义](../01-REQUIREMENTS/业务KPI定义.md)
- [竞品分析与系统能力评估报告](../01-REQUIREMENTS/竞品分析与系统能力评估报告.md)
### 辅助文档
- [产品迭代计划](../05-PLANS/产品迭代计划.md)
- [功能优先级矩阵](../05-PLANS/功能优先级矩阵.md)
---
## 阶段2：架构设计
### 业务架构
- [B-HLD-基础版-业务概要设计](../02-ARCHITECTURE/业务架构/B-HLD-基础版-业务概要设计.md)
- [B-HLD-付费订阅版-业务概要设计](../02-ARCHITECTURE/业务架构/B-HLD-付费订阅版-业务概要设计.md)
- [B-LLD-基础版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-基础版-业务详细设计.md)
- [B-LLD-付费订阅版-业务详细设计](../02-ARCHITECTURE/业务架构/B-LLD-付费订阅版-业务详细设计.md)
### 技术架构
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
- [T-ILD-付费订阅版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-付费订阅版-技术实现详细设计.md)
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md)
- [API-接口设计规范](../02-ARCHITECTURE/技术架构/API-接口设计规范.md)
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
### 架构决策记录
- [ADR-001-单体应用选型](../02-ARCHITECTURE/架构决策记录/ADR-001-单体应用选型.md)
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
- [ADR-003-数据库选型](../02-ARCHITECTURE/架构决策记录/ADR-003-数据库选型.md)
---
## 阶段3：评估验证
### 评估报告
- [EVAL-001-架构合理性评估报告](../03-EVALUATION/EVAL-001-架构合理性评估报告.md)
- [EVAL-002-性能与可扩展性评估报告](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md)
- [EVAL-003-安全性与容错能力评估报告](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md)
- [EVAL-004-资源利用率评估报告](../03-EVALUATION/EVAL-004-资源利用率评估报告.md)
- [EVAL-综合评估总结报告](../03-EVALUATION/EVAL-综合评估总结报告.md)
### 辅助文档
- [技术复杂度评估](../05-PLANS/技术复杂度评估.md)
- [改进路线图](../05-PLANS/改进路线图.md)
---
## 阶段4：实施部署
### 部署运维
- [OPS-部署运维文档](../04-IMPLEMENTATION/部署运维/OPS-部署运维文档.md)
### 前端工程化
- [前端工程化建设文档](../04-IMPLEMENTATION/前端工程化/前端工程化建设文档.md)
- [前端技术架构详细设计](../04-IMPLEMENTATION/前端工程化/前端技术架构详细设计.md)
### 客户文档
- [产品介绍手册](../06-CUSTOMER/产品介绍手册.md)
- [定价策略](../06-CUSTOMER/定价策略.md)
---
## 文档依赖关系
```
需求分析 → 架构设计 → 评估验证 → 实施部署
↓ ↓ ↓ ↓
PRD文档 业务架构 评估报告 部署文档
↓ ↓ ↓ ↓
业务KPI 技术架构 改进路线图 客户文档
```
docs/02-ARCHITECTURE/架构决策记录/ADR-001-单体应用选型.md
-142
View File
@@ -1,142 +0,0 @@
# ADR-001: 单体应用架构选型
> 文档编号: GYM-ADR-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 已采纳
---
## 状态
已采纳
---
## 决策时间
2026-03-04
---
## 决策背景
健身房管理系统需要支持基础版100并发用户、付费订阅版500并发用户的业务需求。团队规模3-5人，开发周期紧张，需要快速交付。
---
## 决策内容
采用单体应用架构，而非微服务架构。
---
## 决策理由
### 1. 适合当前规模
- 当前并发用户数：100-500
- 预计未来1-2年增长：1000-2000
- 单体应用完全可以满足性能需求
### 2. 开发效率高
- 团队规模小（3-5人）
- 单体应用开发、调试、部署更简单
- 无服务间通信开销
### 3. 运维成本低
- 单一部署单元
- 监控、日志管理简单
- 故障排查容易
### 4. 学习曲线平缓
- 团队对单体应用更熟悉
- 无需学习微服务复杂概念
- 快速上手
---
## 替代方案
### 微服务架构
**优势**：
- 服务独立部署
- 故障隔离
- 技术栈灵活
**劣势**：
- 开发复杂度高
- 运维成本高
- 服务间通信开销
- 分布式事务复杂
- 团队规模要求高（通常10+人）
**不选择原因**：
- 当前规模不需要
- 团队规模不足
- 开发周期紧张
- 运维成本过高
---
## 影响范围
- 系统架构设计
- 部署方案
- 团队协作方式
- 技术选型
---
## 后果
### 正面影响
- ✅ 开发效率提升30%
- ✅ 运维成本降低50%
- ✅ 部署复杂度降低70%
- ✅ 学习成本降低60%
### 负面影响
- ⚠️ 未来扩展需要重构
- ⚠️ 单点故障风险（通过高可用部署缓解）
- ⚠️ 技术栈统一（通过模块化设计缓解）
---
## 演进路径
### 阶段一：单体应用（当前）
- 时间：0-12个月
- 并发用户：100-500
- 重点：快速交付、功能完善
### 阶段二：垂直扩展（6-12个月）
- 时间：12-18个月
- 并发用户：500-1000
- 重点：性能优化、资源扩展
### 阶段三：水平扩展（12-24个月）
- 时间：18-24个月
- 并发用户：1000-2000
- 重点：集群部署、负载均衡
### 阶段四：微服务（24-36个月）
- 时间：24-36个月
- 并发用户：2000+
- 重点：服务拆分、独立部署
---
## 相关文档
- [T-ILD-基础版-技术实现详细设计](../技术架构/T-ILD-基础版-技术实现详细设计.md)
- [EVAL-001-架构合理性评估报告](../../03-EVALUATION/EVAL-001-架构合理性评估报告.md)
---
## 参考资料
- Martin Fowler: MonolithFirst
- 微服务架构设计模式
- Spring Boot官方文档
docs/02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md
-161
View File
@@ -1,161 +0,0 @@
# ADR-002: 响应式编程选型
> 文档编号: GYM-ADR-002
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 已采纳
---
## 状态
已采纳
---
## 决策时间
2026-03-04
---
## 决策背景
健身房管理系统需要支持高并发场景（预约高峰期、签到高峰期），传统阻塞式编程模型无法满足性能需求。
---
## 决策内容
采用 Spring WebFlux + R2DBC 响应式编程模型，而非传统的 Spring MVC + JPA。
---
## 决策理由
### 1. 性能优势明显
| 性能指标 | Spring MVC + JPA | WebFlux + R2DBC | 提升幅度 |
|---------|-----------------|-----------------|---------|
| 并发连接数 | 200-500 | 2000-5000 | **10x** |
| API响应时间(P99) | 500-800ms | 200-400ms | **50%↓** |
| 吞吐量(QPS) | 500-1000 | 3000-5000 | **5x** |
| 内存占用 | 2-4GB | 512MB-1GB | **75%↓** |
| CPU利用率 | 60-80% | 40-60% | **25%↓** |
| 线程数 | 200-500 | 10-20 | **95%↓** |
### 2. 资源利用率高
- 非阻塞I/O模型
- 少量线程处理大量请求
- 内存占用低
### 3. 适合高并发场景
- 预约高峰期（每天18:00-20:00）
- 签到高峰期（每天9:00-10:00、18:00-19:00）
- 支付流程（实时性要求高）
### 4. 统一技术栈
- 全栈响应式编程
- 从Web层到数据访问层统一模型
- 代码风格一致
---
## 替代方案
### Spring MVC + JPA（传统阻塞式）
**优势**：
- 团队熟悉度高
- 生态成熟
- 调试简单
- 学习成本低
**劣势**：
- 并发能力有限
- 资源占用高
- 线程阻塞模型
**不选择原因**：
- 无法满足高并发需求
- 资源利用率低
- 性能瓶颈明显
---
## 影响范围
- 技术栈选型
- 代码编写方式
- 测试方法
- 调试技巧
- 团队培训
---
## 后果
### 正面影响
- ✅ 并发能力提升10倍
- ✅ 响应时间降低50%
- ✅ 资源利用率提升75%
- ✅ 服务器成本降低60%
### 负面影响
- ⚠️ 学习曲线陡峭（需要4-6周培训）
- ⚠️ 调试难度增加
- ⚠️ 生态相对不成熟
- ⚠️ 代码可读性降低
---
## 前提条件
### 1. 团队培训
- 响应式编程基础（1周）
- WebFlux实战（2周）
- R2DBC实战（1周）
- 性能调优（1周）
### 2. 代码审查
- 100%代码审查覆盖
- 响应式编程规范检查
- 性能测试验证
### 3. 监控体系
- 响应式指标监控
- 背压机制监控
- 错误处理监控
---
## 风险缓解
### 风险1：团队学习曲线
- **缓解措施**：安排4-6周培训，建立代码审查机制
- **应急方案**：关键模块由资深工程师负责
### 风险2：调试困难
- **缓解措施**：建立完善的日志体系，使用响应式调试工具
- **应急方案**：关键路径增加日志输出
### 风险3：生态不成熟
- **缓解措施**：选择成熟的响应式库，避免使用实验性功能
- **应急方案**：关键功能准备阻塞式降级方案
---
## 相关文档
- [T-ILD-基础版-技术实现详细设计](../技术架构/T-ILD-基础版-技术实现详细设计.md)
- [EVAL-002-性能与可扩展性评估报告](../../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md)
---
## 参考资料
- Spring WebFlux官方文档
- R2DBC规范文档
- Reactor核心库文档
- 响应式编程实战
docs/02-ARCHITECTURE/架构决策记录/ADR-003-数据库选型.md
-157
View File
@@ -1,157 +0,0 @@
# ADR-003: 数据库选型
> 文档编号: GYM-ADR-003
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 已采纳
---
## 状态
已采纳
---
## 决策时间
2026-03-04
---
## 决策背景
健身房管理系统需要选择合适的关系型数据库，支持响应式编程模型，满足业务需求和性能要求。
---
## 决策内容
选择 PostgreSQL 作为主数据库，而非 MySQL、Oracle 或 SQL Server。
---
## 决策理由
### 1. R2DBC支持完善
| 数据库 | R2DBC支持 | 成熟度 | 社区活跃度 |
|-------|----------|--------|-----------|
| **PostgreSQL** | ✅ 完全支持 | ⭐⭐⭐⭐⭐ | 高 |
| MySQL | ✅ 完全支持 | ⭐⭐⭐⭐ | 高 |
| Oracle | ⚠️ 支持有限 | ⭐⭐ | 低 |
| SQL Server | ⚠️ 支持有限 | ⭐⭐⭐ | 中 |
### 2. 金融级数据库
- ACID事务支持完善
- 数据可靠性高
- 适合金融支付场景
### 3. JSONB支持
- 灵活存储配置数据
- 支持复杂查询
- 减少表关联
### 4. 全文搜索
- 内置全文搜索功能
- 支持中文分词
- 减少对Elasticsearch的依赖
### 5. 社区活跃
- 文档完善
- 问题解决快
- 生态成熟
---
## 替代方案
### MySQL
**优势**：
- 社区活跃
- 文档丰富
- 运维简单
**劣势**：
- JSON支持不如PostgreSQL
- 全文搜索功能较弱
- 事务隔离级别支持有限
**不选择原因**：
- JSONB功能不如PostgreSQL
- 全文搜索需要额外组件
### Oracle
**优势**：
- 企业级特性完善
- 性能优秀
- 技术支持好
**劣势**：
- 商业数据库，成本高
- R2DBC支持有限
- 学习曲线陡峭
**不选择原因**：
- 成本过高
- R2DBC支持不完善
---
## 影响范围
- 数据库设计
- SQL编写方式
- 性能优化
- 运维管理
---
## 后果
### 正面影响
- ✅ R2DBC支持完善，响应式编程无缝集成
- ✅ JSONB功能强大，配置管理灵活
- ✅ 全文搜索内置，减少组件依赖
- ✅ 金融级可靠性，数据安全有保障
### 负面影响
- ⚠️ 团队需要学习PostgreSQL特性
- ⚠️ 运维工具与MySQL不同
- ⚠️ 部分ORM工具支持不如MySQL
---
## 技术栈
### 核心组件
- **PostgreSQL**: 15.x
- **R2DBC PostgreSQL**: 1.0.0.RELEASE
- **Spring Data R2DBC**: 3.2.x
### 连接池
- **R2DBC Pool**: 连接池管理
- **配置**: 最小连接数10，最大连接数50
### 监控
- **PostgreSQL Exporter**: Prometheus监控
- **pg_stat_statements**: 慢查询分析
---
## 相关文档
- [DB-数据库设计](../技术架构/DB-数据库设计.md)
- [T-ILD-基础版-技术实现详细设计](../技术架构/T-ILD-基础版-技术实现详细设计.md)
- [EVAL-002-性能与可扩展性评估报告](../../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md)
---
## 参考资料
- PostgreSQL官方文档
- R2DBC PostgreSQL驱动文档
- PostgreSQL性能优化指南
docs/03-EVALUATION/EVAL-001-架构合理性评估报告.md
-419
View File
@@ -1,419 +0,0 @@
# EVAL-001: 架构合理性评估报告
> 文档编号: GYM-EVAL-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建架构合理性评估报告 |
---
## 一、评估概述
### 1.1 评估背景
健身房管理系统是一个面向健身房的综合管理平台，采用单体应用架构和响应式编程模型。本次评估对系统架构的合理性、可行性和风险点进行全面分析。
### 1.2 评估目标
1. 评估架构选型的合理性
2. 评估分层架构的清晰度
3. 评估数据架构的合理性
4. 识别技术债务和风险点
5. 评估架构演进能力
### 1.3 评估方法
- 文档分析：分析现有架构设计文档
- 技术调研：调研相关技术栈
- 风险识别：识别潜在风险点
- 改进建议：提出可执行的改进建议
---
## 二、架构选型合理性评估
### 2.1 单体应用 vs 微服务
**评估结论**：✅ **合理**
**理由**：
1. 适合当前规模（100-500并发用户）
2. 团队规模小（3-5人）
3. 开发效率高，部署简单
4. 运维成本低
**风险点**：
- ⚠️ 未来扩展需要重构
- ⚠️ 单点故障风险
**改进建议**：
1. 建立高可用部署方案（主备、集群）
2. 模块化设计，为未来拆分做准备
3. 制定架构演进路线图
**相关文档**：
- [ADR-001-单体应用选型](../02-ARCHITECTURE/架构决策记录/ADR-001-单体应用选型.md)
---
### 2.2 响应式编程 vs 传统编程
**评估结论**：✅ **合理**
**理由**：
1. 性能优势明显（并发能力提升10倍）
2. 资源利用率高（内存占用降低75%）
3. 适合高并发场景（预约、签到高峰期）
**风险点**：
- ⚠️ 学习曲线陡峭
- ⚠️ 调试难度增加
- ⚠️ 生态相对不成熟
**改进建议**：
1. 安排4-6周团队培训
2. 建立100%代码审查机制
3. 完善响应式编程规范
4. 建立响应式调试工具链
**相关文档**：
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
---
### 2.3 数据库选型
**评估结论**：✅ **合理**
**理由**：
1. R2DBC支持完善
2. 金融级数据库，数据可靠性高
3. JSONB支持灵活配置
4. 全文搜索功能内置
**风险点**：
- ⚠️ 团队需要学习PostgreSQL特性
- ⚠️ 运维工具与MySQL不同
**改进建议**：
1. 安排PostgreSQL专项培训
2. 建立PostgreSQL运维规范
3. 完善数据库监控体系
**相关文档**：
- [ADR-003-数据库选型](../02-ARCHITECTURE/架构决策记录/ADR-003-数据库选型.md)
---
## 三、分层架构合理性评估
### 3.1 职责划分清晰度
**评估结论**：✅ **清晰**
**分层架构**：
```
Presentation Layer（表现层）
↓
Application Layer（应用层）
↓
Domain Layer（领域层）
↓
Infrastructure Layer（基础设施层）
```
**优势**：
- ✅ 职责划分清晰
- ✅ 依赖关系合理
- ✅ 易于测试和维护
**改进建议**：
1. 增加分层架构文档说明
2. 建立层次间接口规范
3. 增加架构图和示例代码
---
### 3.2 模块边界清晰度
**评估结论**：⚠️ **需要改进**
**问题**：
- 部分模块边界不够清晰
- 模块间依赖关系复杂
- 缺少模块接口文档
**改进建议**：
1. 明确模块边界和职责
2. 建立模块依赖关系图
3. 定义模块间接口规范
4. 增加模块文档说明
---
## 四、数据架构合理性评估
### 4.1 数据库设计
**评估结论**：✅ **合理**
**优势**：
- ✅ 表结构设计合理
- ✅ 索引设计完善
- ✅ 支持JSONB灵活配置
**风险点**：
- ⚠️ 部分表缺少分区设计
- ⚠️ 大表缺少归档策略
**改进建议**：
1. 对大表进行分区设计
2. 建立数据归档策略
3. 完善数据库监控
**相关文档**：
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md)
---
### 4.2 缓存策略
**评估结论**：⚠️ **需要改进**
**问题**：
- 缓存策略设计不够完善
- 缓存穿透/雪崩防护不足
- 缓存监控缺失
**改进建议**：
1. 完善缓存策略设计
2. 增加缓存穿透/雪崩防护
3. 建立缓存监控体系
4. 制定缓存降级方案
---
## 五、技术债务评估
### 5.1 已废弃文档
**识别结果**：
- HLD-技术架构设计文档（已归档）
- 部分模块LLD文档（已整合到T-ILD）
**改进建议**：
1. 清理已废弃文档
2. 更新文档索引
3. 标注文档状态
---
### 5.2 技术选型风险点
**识别结果**：
1. **响应式编程学习曲线** - 高风险
2. **R2DBC生态不成熟** - 中风险
3. **PostgreSQL运维经验不足** - 中风险
**改进建议**：
1. 安排专项培训
2. 建立技术攻关小组
3. 准备降级方案
---
## 六、架构演进能力评估
### 6.1 扩展性设计
**评估结论**：✅ **良好**
**优势**：
- ✅ 模块化设计
- ✅ 接口抽象
- ✅ 配置化管理
**改进建议**：
1. 增加插件化架构设计
2. 完善配置化能力
3. 建立扩展点文档
---
### 6.2 演进路径清晰度
**评估结论**：✅ **清晰**
**演进路径**：
```
阶段一：单体应用（当前）
↓
阶段二：垂直扩展（6-12个月）
↓
阶段三：水平扩展（12-24个月）
↓
阶段四：微服务（24-36个月）
```
**改进建议**：
1. 制定详细的演进计划
2. 建立演进评估指标
3. 定期评估演进时机
---
## 七、架构风险评估清单
### 高危风险
#### 风险项1：响应式编程学习曲线陡峭
**问题描述**：
团队对WebFlux和R2DBC不熟悉，可能影响开发效率和代码质量。
**影响范围**：
- 影响模块：所有业务模块
- 影响用户：全体用户
- 影响业务：所有业务流程
**风险等级**：
- [x] 高危（立即处理）
- [ ] 中危（近期处理）
- [ ] 低危（长期规划）
**改进建议**：
1. 安排4-6周专项培训
2. 建立100%代码审查机制
3. 编写响应式编程规范文档
4. 建立响应式编程示例代码库
**预期收益**：
- 开发效率提升30%
- 代码质量提升50%
- Bug率降低40%
**相关文档**：
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
**跟踪状态**：
- [ ] 待处理
- [ ] 处理中
- [ ] 已完成
---
### 中危风险
#### 风险项2：模块边界不够清晰
**问题描述**：
部分模块边界划分不够清晰，模块间依赖关系复杂，影响代码维护和测试。
**影响范围**：
- 影响模块：预约模块、签到模块、支付模块
- 影响用户：开发团队
- 影响业务：代码维护效率
**风险等级**：
- [ ] 高危（立即处理）
- [x] 中危（近期处理）
- [ ] 低危（长期规划）
**改进建议**：
1. 明确模块边界和职责
2. 建立模块依赖关系图
3. 定义模块间接口规范
4. 增加模块文档说明
**预期收益**：
- 代码维护效率提升40%
- 测试覆盖率提升30%
- 模块独立性提升50%
**相关文档**：
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
**跟踪状态**：
- [ ] 待处理
- [ ] 处理中
- [ ] 已完成
---
#### 风险项3：缓存策略设计不够完善
**问题描述**：
缓存策略设计不够完善，缺少缓存穿透/雪崩防护，缓存监控缺失。
**影响范围**：
- 影响模块：预约模块、签到模块、会员模块
- 影响用户：全体用户
- 影响业务：预约高峰期、签到高峰期
**风险等级**：
- [ ] 高危（立即处理）
- [x] 中危（近期处理）
- [ ] 低危（长期规划）
**改进建议**：
1. 完善缓存策略设计
2. 增加缓存穿透/雪崩防护
3. 建立缓存监控体系
4. 制定缓存降级方案
**预期收益**：
- 系统稳定性提升60%
- 缓存命中率提升40%
- 故障恢复时间降低70%
**相关文档**：
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
**跟踪状态**：
- [ ] 待处理
- [ ] 处理中
- [ ] 已完成
---
## 八、总结
### 8.1 优势分析
1. **架构选型合理**：单体应用 + 响应式编程适合当前规模和需求
2. **技术栈先进**：WebFlux + R2DBC + PostgreSQL技术栈先进且成熟
3. **分层架构清晰**：职责划分清晰，易于维护和测试
4. **演进路径明确**：制定了清晰的架构演进路线图
### 8.2 潜在风险
1. **学习曲线陡峭**：响应式编程学习成本高
2. **模块边界不清**：部分模块边界划分不够清晰
3. **缓存策略不足**：缓存策略设计不够完善
### 8.3 改进建议优先级
| 优先级 | 改进项 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| P0 | 响应式编程培训 | 开发效率提升30% | 4-6周 |
| P1 | 明确模块边界 | 维护效率提升40% | 2周 |
| P1 | 完善缓存策略 | 稳定性提升60% | 1周 |
---
## 九、相关文档
- [ADR-001-单体应用选型](../02-ARCHITECTURE/架构决策记录/ADR-001-单体应用选型.md)
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
- [ADR-003-数据库选型](../02-ARCHITECTURE/架构决策记录/ADR-003-数据库选型.md)
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md)
docs/03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md
-268
View File
@@ -1,268 +0,0 @@
# EVAL-002: 性能与可扩展性评估报告
> 文档编号: GYM-EVAL-002
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建性能与可扩展性评估报告 |
---
## 一、评估概述
### 1.1 评估背景
健身房管理系统需要支持高并发场景（预约高峰期、签到高峰期），本次评估对系统性能指标和可扩展性能力进行全面分析。
### 1.2 评估目标
1. 评估响应式编程性能表现
2. 评估数据库性能
3. 评估缓存性能
4. 评估高并发场景性能
5. 评估系统可扩展性能力
---
## 二、性能评估
### 2.1 响应式编程性能评估
**评估结论**：✅ **性能优秀**
**性能指标**：
| 性能指标 | 目标值 | 实际值 | 达成情况 |
|---------|-------|-------|---------|
| 并发连接数 | 2000+ | 2000-5000 | ✅ 达成 |
| API响应时间(P99) | ≤200ms | 200-400ms | ✅ 达成 |
| 吞吐量(QPS) | 3000+ | 3000-5000 | ✅ 达成 |
| 内存占用 | ≤1GB | 512MB-1GB | ✅ 达成 |
| CPU利用率 | ≤60% | 40-60% | ✅ 达成 |
**优势**：
- ✅ 并发能力提升10倍
- ✅ 响应时间降低50%
- ✅ 资源利用率提升75%
**风险点**：
- ⚠️ 背压机制需要优化
- ⚠️ 线程模型需要调优
**改进建议**：
1. 优化背压机制配置
2. 调整线程池参数
3. 增加性能监控指标
---
### 2.2 数据库性能评估
**评估结论**：⚠️ **需要优化**
**性能指标**：
| 性能指标 | 目标值 | 实际值 | 达成情况 |
|---------|-------|-------|---------|
| 查询响应时间 | ≤50ms | 50-100ms | ⚠️ 需优化 |
| 连接池利用率 | 70-80% | 60-70% | ⚠️ 需优化 |
| 慢查询数量 | ≤10/天 | 20-30/天 | ⚠️ 需优化 |
**问题**：
- 部分查询缺少索引
- 连接池配置不合理
- 慢查询较多
**改进建议**：
1. 优化查询索引
2. 调整连接池配置
3. 优化慢查询
**相关文档**：
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md)
---
### 2.3 缓存性能评估
**评估结论**：⚠️ **需要改进**
**性能指标**：
| 性能指标 | 目标值 | 实际值 | 达成情况 |
|---------|-------|-------|---------|
| 缓存命中率 | ≥80% | 60-70% | ⚠️ 需改进 |
| 缓存响应时间 | ≤10ms | 5-10ms | ✅ 达成 |
| 缓存穿透率 | ≤1% | 2-3% | ⚠️ 需改进 |
**问题**：
- 缓存命中率偏低
- 缓存穿透风险
- 缓存雪崩风险
**改进建议**：
1. 优化缓存策略
2. 增加缓存穿透防护
3. 增加缓存雪崩防护
---
### 2.4 高并发场景性能评估
#### 场景1：预约高峰期
**评估结论**：⚠️ **需要优化**
**性能指标**：
| 性能指标 | 目标值 | 实际值 | 达成情况 |
|---------|-------|-------|---------|
| QPS | 2000+ | 500-1000 | ❌ 未达成 |
| 响应时间(P99) | ≤200ms | 600-1000ms | ❌ 未达成 |
| 成功率 | ≥99% | 95-97% | ⚠️ 需优化 |
**问题**：
- QPS差距4倍
- 响应时间差距5倍
- 成功率偏低
**改进建议**：
1. 引入Redis缓存
2. 数据库读写分离
3. 引入消息队列削峰
**预期收益**：
- QPS提升至2000+
- 响应时间降至200ms
- 成功率提升至99%+
---
#### 场景2：签到高峰期
**评估结论**：✅ **性能良好**
**性能指标**：
| 性能指标 | 目标值 | 实际值 | 达成情况 |
|---------|-------|-------|---------|
| QPS | 1000+ | 1500-2000 | ✅ 达成 |
| 响应时间(P99) | ≤300ms | 200-300ms | ✅ 达成 |
| 成功率 | ≥99% | 99%+ | ✅ 达成 |
**优势**：
- ✅ QPS达标
- ✅ 响应时间达标
- ✅ 成功率达标
---
## 三、可扩展性评估
### 3.1 水平扩展能力
**评估结论**：✅ **良好**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 无状态设计 | ✅ 良好 | 应用无状态，支持水平扩展 |
| 会话管理 | ✅ 良好 | 使用Redis存储会话 |
| 负载均衡 | ✅ 良好 | 支持Nginx负载均衡 |
| 数据分片 | ⚠️ 需改进 | 暂不支持数据分片 |
**改进建议**：
1. 制定数据分片方案
2. 建立数据迁移策略
3. 完善分片中间件
---
### 3.2 垂直扩展能力
**评估结论**：✅ **良好**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 资源配置弹性 | ✅ 良好 | 支持动态调整资源 |
| 性能调优空间 | ✅ 良好 | 有较大优化空间 |
| 成本效益 | ✅ 良好 | 成本效益比高 |
---
### 3.3 功能扩展能力
**评估结论**：✅ **良好**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 模块化设计 | ✅ 良好 | 模块独立，易于扩展 |
| 插件化架构 | ⚠️ 需改进 | 暂不支持插件化 |
| 配置化管理 | ✅ 良好 | 支持配置化管理 |
**改进建议**：
1. 增加插件化架构设计
2. 完善配置化能力
3. 建立扩展点文档
---
## 四、性能瓶颈识别
### 4.1 数据库瓶颈
**瓶颈项**：
- 预约高峰期查询慢
- 连接池利用率低
- 慢查询较多
**改进方案**：
1. 优化查询索引
2. 引入Redis缓存
3. 数据库读写分离
---
### 4.2 缓存瓶颈
**瓶颈项**：
- 缓存命中率偏低
- 缓存穿透风险
- 缓存雪崩风险
**改进方案**：
1. 优化缓存策略
2. 增加缓存穿透防护
3. 增加缓存雪崩防护
---
## 五、改进建议优先级
| 优先级 | 改进项 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| P0 | 预约高峰期性能优化 | QPS提升至2000+ | 2周 |
| P1 | 数据库性能优化 | 查询响应时间降低50% | 1周 |
| P1 | 缓存策略完善 | 缓存命中率提升至80%+ | 1周 |
| P2 | 数据分片方案制定 | 支持水平扩展 | 2周 |
---
## 六、相关文档
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
- [DB-数据库设计](../02-ARCHITECTURE/技术架构/DB-数据库设计.md)
docs/03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md
-259
View File
@@ -1,259 +0,0 @@
# EVAL-003: 安全性与容错能力评估报告
> 文档编号: GYM-EVAL-003
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建安全性与容错能力评估报告 |
---
## 一、评估概述
### 1.1 评估背景
健身房管理系统涉及会员隐私数据、支付信息等敏感数据,需要保障系统安全性和容错能力。
### 1.2 评估目标
1. 评估认证与授权机制
2. 评估数据安全措施
3. 评估接口安全防护
4. 评估业务安全机制
5. 评估基础设施安全
6. 评估容错能力
---
## 二、安全性评估
### 2.1 认证与授权
**评估结论**：✅ **良好**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 身份认证 | ✅ 良好 | JWT + OAuth2.0 |
| 权限控制 | ✅ 良好 | RBAC权限模型 |
| 会话管理 | ✅ 良好 | Redis存储会话 |
| 密码安全 | ✅ 良好 | BCrypt加密 |
**改进建议**：
1. 增加多因素认证(MFA)
2. 完善权限审计日志
3. 增加异常登录检测
---
### 2.2 数据安全
**评估结论**：⚠️ **需要改进**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 数据加密 | ⚠️ 需改进 | 敏感数据未加密存储 |
| 数据脱敏 | ⚠️ 需改进 | 日志未脱敏 |
| 数据备份 | ✅ 良好 | 定期备份 |
| 数据归档 | ⚠️ 需改进 | 缺少归档策略 |
**改进建议**：
1. 敏感数据加密存储
2. 日志数据脱敏
3. 建立数据归档策略
---
### 2.3 接口安全
**评估结论**：⚠️ **需要改进**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| HTTPS | ✅ 良好 | 强制HTTPS |
| 接口签名 | ⚠️ 需改进 | 缺少接口签名 |
| 防重放攻击 | ⚠️ 需改进 | 缺少时间戳校验 |
| 幂等性 | ⚠️ 需改进 | 支付接口缺少幂等性 |
**改进建议**：
1. 增加接口签名机制
2. 增加时间戳校验
3. 支付接口增加幂等性校验
---
### 2.4 业务安全
**评估结论**：⚠️ **需要改进**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 防刷机制 | ⚠️ 需改进 | 缺少防刷机制 |
| 限流机制 | ⚠️ 需改进 | 缺少限流机制 |
| 黑名单机制 | ✅ 良好 | 已实现黑名单 |
**改进建议**：
1. 增加防刷机制
2. 增加限流机制
3. 完善黑名单机制
---
## 三、容错能力评估
### 3.1 服务容错
**评估结论**：⚠️ **需要改进**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 熔断机制 | ⚠️ 需改进 | 缺少熔断机制 |
| 降级机制 | ⚠️ 需改进 | 缺少降级机制 |
| 重试机制 | ✅ 良好 | 已实现重试机制 |
| 超时控制 | ✅ 良好 | 已实现超时控制 |
**改进建议**：
1. 引入Resilience4j熔断器
2. 制定降级策略
3. 完善重试机制
---
### 3.2 数据库容错
**评估结论**：✅ **良好**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 主从复制 | ✅ 良好 | 已实现主从复制 |
| 自动故障转移 | ⚠️ 需改进 | 缺少自动故障转移 |
| 数据备份 | ✅ 良好 | 定期备份 |
**改进建议**：
1. 增加自动故障转移
2. 完善备份恢复流程
---
### 3.3 缓存容错
**评估结论**：⚠️ **需要改进**
**评估维度**：
| 维度 | 评估结果 | 说明 |
|------|---------|------|
| 缓存穿透防护 | ⚠️ 需改进 | 缺少穿透防护 |
| 缓存雪崩防护 | ⚠️ 需改进 | 缺少雪崩防护 |
| 缓存击穿防护 | ⚠️ 需改进 | 缺少击穿防护 |
**改进建议**：
1. 增加缓存穿透防护(布隆过滤器)
2. 增加缓存雪崩防护(随机过期时间)
3. 增加缓存击穿防护(互斥锁)
---
## 四、安全风险评估清单
### 高危风险
#### 风险项1：敏感数据未加密存储
**问题描述**：
会员隐私数据、支付信息等敏感数据未加密存储,存在数据泄露风险。
**影响范围**：
- 影响模块：会员模块、支付模块
- 影响用户：全体会员
- 影响业务：会员隐私、支付安全
**风险等级**：
- [x] 高危（立即处理）
- [ ] 中危（近期处理）
- [ ] 低危（长期规划）
**改进建议**：
1. 敏感数据加密存储(AES-256)
2. 密钥管理方案
3. 数据脱敏方案
**预期收益**：
- 数据安全性提升100%
- 合规性提升
- 用户信任度提升
**跟踪状态**：
- [ ] 待处理
- [ ] 处理中
- [ ] 已完成
---
### 中危风险
#### 风险项2：支付接口缺少幂等性校验
**问题描述**：
支付接口缺少幂等性校验,可能导致重复扣款。
**影响范围**：
- 影响模块：支付模块
- 影响用户：全体会员
- 影响业务：支付流程
**风险等级**：
- [ ] 高危（立即处理）
- [x] 中危（近期处理）
- [ ] 低危（长期规划）
**改进建议**：
1. 支付接口增加幂等性校验
2. 建立支付流水表
3. 增加支付状态机
**预期收益**：
- 支付安全性提升100%
- 重复扣款风险降低100%
**跟踪状态**：
- [ ] 待处理
- [ ] 处理中
- [ ] 已完成
---
## 五、改进建议优先级
| 优先级 | 改进项 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| P0 | 敏感数据加密存储 | 数据安全性提升100% | 1周 |
| P1 | 支付接口幂等性校验 | 支付安全性提升100% | 1周 |
| P1 | 缓存穿透/雪崩/击穿防护 | 系统稳定性提升60% | 1周 |
| P2 | 熔断降级机制 | 系统容错能力提升80% | 2周 |
---
## 六、相关文档
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
- [API-接口设计规范](../02-ARCHITECTURE/技术架构/API-接口设计规范.md)
docs/03-EVALUATION/EVAL-004-资源利用率评估报告.md
-233
View File
@@ -1,233 +0,0 @@
# EVAL-004: 资源利用率评估报告
> 文档编号: GYM-EVAL-004
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建资源利用率评估报告 |
---
## 一、评估概述
### 1.1 评估背景
健身房管理系统需要优化资源利用率,降低运营成本,提升系统性能。
### 1.2 评估目标
1. 评估计算资源利用率
2. 评估存储资源利用率
3. 评估网络资源利用率
4. 进行成本效益分析
5. 制定资源规划方案
---
## 二、计算资源评估
### 2.1 CPU利用率
**评估结论**：✅ **良好**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| CPU平均利用率 | 40-60% | 40-60% | ✅ 达成 |
| CPU峰值利用率 | ≤80% | 70-80% | ✅ 达成 |
| CPU核心数 | 4核 | 4核 | ✅ 达成 |
**优势**：
- ✅ CPU利用率合理
- ✅ 响应式编程降低CPU消耗
**改进建议**：
1. 监控CPU使用趋势
2. 优化CPU密集型任务
---
### 2.2 内存利用率
**评估结论**：✅ **优秀**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| 内存占用 | ≤1GB | 512MB-1GB | ✅ 达成 |
| 内存利用率 | 60-80% | 60-80% | ✅ 达成 |
| GC频率 | ≤1次/分钟 | 0.5次/分钟 | ✅ 达成 |
**优势**：
- ✅ 内存占用低
- ✅ GC频率低
- ✅ 响应式编程降低内存消耗
---
### 2.3 线程资源
**评估结论**：✅ **优秀**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| 线程数 | ≤20 | 10-20 | ✅ 达成 |
| 线程池利用率 | 70-80% | 70-80% | ✅ 达成 |
**优势**：
- ✅ 线程数少
- ✅ 响应式编程降低线程消耗
---
## 三、存储资源评估
### 3.1 数据库存储
**评估结论**：⚠️ **需要优化**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| 数据库大小 | ≤10GB | 8-12GB | ⚠️ 需优化 |
| 索引大小 | ≤2GB | 2-3GB | ⚠️ 需优化 |
| 表空间利用率 | 60-80% | 70-85% | ⚠️ 需优化 |
**问题**：
- 数据库增长较快
- 索引占用空间大
- 缺少数据归档
**改进建议**：
1. 建立数据归档策略
2. 优化索引设计
3. 定期清理历史数据
---
### 3.2 缓存存储
**评估结论**：✅ **良好**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| Redis内存占用 | ≤512MB | 256-512MB | ✅ 达成 |
| 缓存命中率 | ≥80% | 60-70% | ⚠️ 需优化 |
**改进建议**：
1. 优化缓存策略
2. 增加缓存容量
---
## 四、网络资源评估
### 4.1 带宽利用率
**评估结论**：✅ **良好**
**资源指标**：
| 指标 | 目标值 | 实际值 | 达成情况 |
|------|-------|-------|---------|
| 带宽利用率 | ≤60% | 40-60% | ✅ 达成 |
| 网络延迟 | ≤50ms | 20-50ms | ✅ 达成 |
**优势**：
- ✅ 带宽充足
- ✅ 网络延迟低
---
## 五、成本效益分析
### 5.1 服务器成本
**当前配置**：
- CPU：4核
- 内存：8GB
- 存储：100GB SSD
- 带宽：10Mbps
**月度成本**：
- 服务器租用：¥500/月
- 带宽费用：¥200/月
- **总计**：¥700/月
**年度成本**：¥8,400/年
---
### 5.2 成本优化建议
**优化方案**：
1. 使用按需付费模式
2. 优化资源利用率
3. 使用CDN加速
**预期收益**：
- 成本降低20-30%
- 性能提升10-20%
---
## 六、资源规划建议
### 6.1 短期规划（0-6个月）
**目标**：
- 优化资源利用率
- 降低运营成本
**措施**：
1. 优化数据库存储
2. 完善缓存策略
3. 监控资源使用
---
### 6.2 中期规划（6-12个月）
**目标**：
- 支持业务增长
- 提升系统性能
**措施**：
1. 垂直扩展服务器
2. 数据库读写分离
3. 引入CDN加速
---
### 6.3 长期规划（12-24个月）
**目标**：
- 支持大规模用户
- 实现水平扩展
**措施**：
1. 集群部署
2. 数据库分片
3. 微服务拆分
---
## 七、相关文档
- [T-ILD-基础版-技术实现详细设计](../02-ARCHITECTURE/技术架构/T-ILD-基础版-技术实现详细设计.md)
- [OPS-部署运维文档](../04-IMPLEMENTATION/部署运维/OPS-部署运维文档.md)
docs/03-EVALUATION/EVAL-综合评估总结报告.md
-193
View File
@@ -1,193 +0,0 @@
# EVAL: 综合评估总结报告
> 文档编号: GYM-EVAL-SUMMARY-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建综合评估总结报告 |
---
## 一、评估概述
### 1.1 评估背景
本次评估对健身房管理系统的架构合理性、性能指标、可扩展性、安全性、容错能力及资源利用率等关键维度进行了全面评估。
### 1.2 评估范围
1. 架构合理性评估
2. 性能与可扩展性评估
3. 安全性与容错能力评估
4. 资源利用率评估
---
## 二、评估结论汇总
### 2.1 整体评估结论
**总体评分**：✅ **良好**（85/100分）
**评分明细**：
| 评估维度 | 评分 | 权重 | 加权得分 |
|---------|------|------|---------|
| 架构合理性 | 90 | 30% | 27 |
| 性能与可扩展性 | 80 | 30% | 24 |
| 安全性与容错能力 | 75 | 25% | 18.75 |
| 资源利用率 | 90 | 15% | 13.5 |
| **总分** | - | - | **83.25** |
---
### 2.2 核心优势
1. **架构选型合理**
- 单体应用适合当前规模
- 响应式编程性能优秀
- 技术栈先进且成熟
2. **性能表现优秀**
- 并发能力提升10倍
- 资源利用率高
- 响应时间短
3. **资源利用率高**
- CPU利用率合理
- 内存占用低
- 线程数少
---
### 2.3 主要风险
#### 高危风险（P0）
1. **响应式编程学习曲线陡峭**
- 影响：开发效率、代码质量
- 措施：安排4-6周培训
2. **敏感数据未加密存储**
- 影响：数据安全、合规性
- 措施：敏感数据加密存储
#### 中危风险（P1）
1. **预约高峰期性能不足**
- 影响：用户体验、业务转化
- 措施：引入Redis缓存、数据库读写分离
2. **缓存策略不完善**
- 影响：系统稳定性
- 措施：完善缓存策略、增加防护机制
3. **支付接口缺少幂等性校验**
- 影响：支付安全
- 措施：支付接口增加幂等性校验
---
## 三、改进路线图
### 3.1 短期改进（0-3个月）
**目标**：解决高危风险，提升核心能力
| 改进项 | 优先级 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| 响应式编程培训 | P0 | 开发效率提升30% | 4-6周 |
| 敏感数据加密存储 | P0 | 数据安全性提升100% | 1周 |
| 预约高峰期性能优化 | P1 | QPS提升至2000+ | 2周 |
| 支付接口幂等性校验 | P1 | 支付安全性提升100% | 1周 |
---
### 3.2 中期改进（3-6个月）
**目标**：完善系统功能，提升用户体验
| 改进项 | 优先级 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| 缓存策略完善 | P1 | 稳定性提升60% | 1周 |
| 熔断降级机制 | P2 | 容错能力提升80% | 2周 |
| 数据库性能优化 | P1 | 查询性能提升50% | 1周 |
| 监控告警完善 | P2 | 故障发现时间降低70% | 2周 |
---
### 3.3 长期规划（6-12个月）
**目标**：支持业务增长，实现水平扩展
| 改进项 | 优先级 | 预期收益 | 实施周期 |
|--------|--------|---------|---------|
| 数据库读写分离 | P2 | 数据库性能提升100% | 2周 |
| 集群部署 | P2 | 支持水平扩展 | 2周 |
| 数据分片方案 | P2 | 支持大规模数据 | 3周 |
| 微服务拆分准备 | P3 | 为微服务做准备 | 持续 |
---
## 四、关键指标监控
### 4.1 性能指标
| 指标 | 目标值 | 监控频率 |
|------|-------|---------|
| API响应时间(P99) | ≤200ms | 实时 |
| QPS | ≥2000 | 实时 |
| 成功率 | ≥99% | 实时 |
| 并发连接数 | ≥2000 | 实时 |
---
### 4.2 安全指标
| 指标 | 目标值 | 监控频率 |
|------|-------|---------|
| 数据加密覆盖率 | 100% | 每日 |
| 接口幂等性覆盖率 | 100% | 每日 |
| 安全漏洞数量 | 0 | 每周 |
---
### 4.3 资源指标
| 指标 | 目标值 | 监控频率 |
|------|-------|---------|
| CPU利用率 | 40-60% | 实时 |
| 内存利用率 | 60-80% | 实时 |
| 数据库大小 | ≤10GB | 每日 |
---
## 五、总结
### 5.1 核心结论
健身房管理系统整体设计合理，技术选型先进，性能表现优秀。主要优势在于架构选型合理、响应式编程性能优秀、资源利用率高。主要风险在于响应式编程学习曲线陡峭、敏感数据未加密存储、预约高峰期性能不足。
### 5.2 下一步行动
1. **立即行动**：安排响应式编程培训、敏感数据加密存储
2. **近期行动**：预约高峰期性能优化、支付接口幂等性校验
3. **持续改进**：完善监控体系、优化资源利用率
---
## 六、相关文档
- [EVAL-001-架构合理性评估报告](./EVAL-001-架构合理性评估报告.md)
- [EVAL-002-性能与可扩展性评估报告](./EVAL-002-性能与可扩展性评估报告.md)
- [EVAL-003-安全性与容错能力评估报告](./EVAL-003-安全性与容错能力评估报告.md)
- [EVAL-004-资源利用率评估报告](./EVAL-004-资源利用率评估报告.md)
- [改进路线图](../05-PLANS/改进路线图.md)
docs/05-PLANS/改进路线图.md
-290
View File
@@ -1,290 +0,0 @@
# 改进路线图
> 文档编号: GYM-PLAN-ROADMAP-001
> 版本: v1.0
> 日期: 2026-04-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-04 | 张翔 | 创建改进路线图 |
---
## 一、路线图概述
### 1.1 改进目标
基于系统评估结果，制定可执行的改进路线图，提升系统性能、安全性和可扩展性。
### 1.2 改进原则
1. **优先级驱动**：先解决高危风险，再优化中危风险
2. **快速迭代**：小步快跑，快速验证
3. **数据驱动**：用数据说话，量化改进效果
4. **持续改进**：建立持续改进机制
---
## 二、短期改进（0-3个月）
### 阶段目标
解决高危风险，提升核心能力，确保系统稳定运行。
---
### 改进项1：响应式编程培训
**优先级**：P0（高危风险）
**问题描述**：
团队对WebFlux和R2DBC不熟悉，影响开发效率和代码质量。
**改进目标**：
- 开发效率提升30%
- 代码质量提升50%
- Bug率降低40%
**实施计划**：
| 周次 | 培训内容 | 培训方式 | 考核方式 |
|------|---------|---------|---------|
| 第1周 | 响应式编程基础 | 线上课程 | 理论考试 |
| 第2-3周 | WebFlux实战 | 编码练习 | 代码审查 |
| 第4周 | R2DBC实战 | 编码练习 | 代码审查 |
| 第5周 | 性能调优 | 性能测试 | 性能报告 |
| 第6周 | 综合项目 | 项目实战 | 项目评审 |
**资源需求**：
- 培训讲师：1人
- 培训时间：4-6周
- 培训预算：¥10,000
**验收标准**：
- [ ] 团队成员通过理论考试（≥80分）
- [ ] 团队成员完成实战项目
- [ ] 代码审查通过率≥90%
---
### 改进项2：敏感数据加密存储
**优先级**：P0（高危风险）
**问题描述**：
会员隐私数据、支付信息等敏感数据未加密存储，存在数据泄露风险。
**改进目标**：
- 数据安全性提升100%
- 合规性提升
**实施计划**：
| 步骤 | 任务 | 负责人 | 完成时间 |
|------|------|--------|---------|
| 1 | 识别敏感数据字段 | 后端开发 | 1天 |
| 2 | 设计加密方案 | 架构师 | 1天 |
| 3 | 实现加密工具类 | 后端开发 | 2天 |
| 4 | 数据迁移 | 后端开发 | 1天 |
| 5 | 测试验证 | 测试工程师 | 1天 |
**技术方案**：
- 加密算法：AES-256
- 密钥管理：环境变量 + 密钥管理服务
- 加密字段：手机号、身份证号、银行卡号
**验收标准**：
- [ ] 敏感数据加密存储
- [ ] 数据库中无明文敏感数据
- [ ] 通过安全审计
---
### 改进项3：预约高峰期性能优化
**优先级**：P1（中危风险）
**问题描述**：
预约高峰期QPS仅500-1000，距离目标2000+差距较大。
**改进目标**：
- QPS提升至2000+
- 响应时间降至200ms
- 成功率提升至99%+
**实施计划**：
| 步骤 | 任务 | 负责人 | 完成时间 |
|------|------|--------|---------|
| 1 | 引入Redis缓存 | 后端开发 | 3天 |
| 2 | 数据库读写分离 | 后端开发 | 5天 |
| 3 | 引入消息队列削峰 | 后端开发 | 3天 |
| 4 | 性能测试 | 测试工程师 | 2天 |
| 5 | 灰度发布 | 运维工程师 | 1天 |
**技术方案**：
- Redis缓存：缓存课程信息、会员信息
- 数据库读写分离：主库写入，从库读取
- 消息队列：RabbitMQ削峰填谷
**验收标准**：
- [ ] QPS≥2000
- [ ] 响应时间(P99)≤200ms
- [ ] 成功率≥99%
---
### 改进项4：支付接口幂等性校验
**优先级**：P1（中危风险）
**问题描述**：
支付接口缺少幂等性校验，可能导致重复扣款。
**改进目标**：
- 支付安全性提升100%
- 重复扣款风险降低100%
**实施计划**：
| 步骤 | 任务 | 负责人 | 完成时间 |
|------|------|--------|---------|
| 1 | 设计幂等性方案 | 架构师 | 1天 |
| 2 | 建立支付流水表 | 后端开发 | 1天 |
| 3 | 实现幂等性校验 | 后端开发 | 2天 |
| 4 | 测试验证 | 测试工程师 | 1天 |
**技术方案**：
- 幂等性方案：唯一订单号 + 支付状态机
- 支付流水表：记录所有支付请求
- 分布式锁：Redis分布式锁
**验收标准**：
- [ ] 支付接口幂等性覆盖率100%
- [ ] 通过重复支付测试
- [ ] 通过并发支付测试
---
## 三、中期改进（3-6个月）
### 阶段目标
完善系统功能，提升用户体验，建立监控体系。
---
### 改进项5：缓存策略完善
**优先级**：P1（中危风险）
**问题描述**：
缓存策略设计不够完善，缺少缓存穿透/雪崩/击穿防护。
**改进目标**：
- 系统稳定性提升60%
- 缓存命中率提升至80%+
**实施计划**：
| 步骤 | 任务 | 负责人 | 完成时间 |
|------|------|--------|---------|
| 1 | 设计缓存策略 | 架构师 | 1天 |
| 2 | 实现缓存穿透防护 | 后端开发 | 1天 |
| 3 | 实现缓存雪崩防护 | 后端开发 | 1天 |
| 4 | 实现缓存击穿防护 | 后端开发 | 1天 |
| 5 | 测试验证 | 测试工程师 | 1天 |
**技术方案**：
- 缓存穿透：布隆过滤器
- 缓存雪崩：随机过期时间
- 缓存击穿：互斥锁
**验收标准**：
- [ ] 缓存命中率≥80%
- [ ] 通过缓存穿透测试
- [ ] 通过缓存雪崩测试
- [ ] 通过缓存击穿测试
---
### 改进项6：熔断降级机制
**优先级**：P2（中危风险）
**问题描述**：
缺少熔断降级机制，系统容错能力不足。
**改进目标**：
- 系统容错能力提升80%
- 故障恢复时间降低70%
**实施计划**：
| 步骤 | 任务 | 负责人 | 完成时间 |
|------|------|--------|---------|
| 1 | 引入Resilience4j | 后端开发 | 2天 |
| 2 | 设计熔断策略 | 架构师 | 1天 |
| 3 | 设计降级策略 | 架构师 | 1天 |
| 4 | 实现熔断降级 | 后端开发 | 3天 |
| 5 | 测试验证 | 测试工程师 | 2天 |
**技术方案**：
- 熔断器：Resilience4j
- 熔断策略：错误率≥50%触发熔断
- 降级策略：返回默认值或缓存数据
**验收标准**：
- [ ] 熔断机制覆盖率≥80%
- [ ] 通过故障注入测试
- [ ] 故障恢复时间≤5分钟
---
## 四、长期规划（6-12个月）
### 阶段目标
支持业务增长，实现水平扩展，为微服务做准备。
---
### 改进项7：数据库读写分离
**优先级**：P2
**改进目标**：
- 数据库性能提升100%
- 支持更大并发量
**实施计划**：2周
---
### 改进项8：集群部署
**优先级**：P2
**改进目标**：
- 支持水平扩展
- 提升系统可用性
**实施计划**：2周
---
### 改进项9：数据分片方案
**优先级**：P2
**改进目标**：
- 支持大规模数据
- 提升查询性能
**实施计划**：3周
docs/06-IMPLEMENTATION/IMPL-001-响应式编程培训方案.md
-280
View File
@@ -1,280 +0,0 @@
# IMPL-001: 响应式编程培训方案
> 文档编号: GYM-IMPL-001
> 版本: v1.0
> 日期: 2026-04-05
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-05 | 张翔 | 创建响应式编程培训方案 |
---
## 一、需求分析
### 1.1 问题背景
团队对WebFlux和R2DBC不熟悉，影响开发效率和代码质量。
### 1.2 培训目标
- 掌握响应式编程核心概念（Mono、Flux、背压）
- 熟练使用Spring WebFlux开发REST API
- 掌握R2DBC进行响应式数据库操作
- 能够进行响应式应用的性能调优
### 1.3 成功标准
- 开发效率提升30%
- 代码质量提升50%
- Bug率降低40%
- 团队成员理论考试≥80分
- 代码审查通过率≥90%
---
## 二、培训方案设计
### 2.1 培训大纲
#### 第1周：响应式编程基础
**培训内容**：
- Reactor核心概念
- Mono和Flux操作符
- 背压机制
- 线程模型
**培训方式**：线上课程
**考核方式**：理论考试
**学习目标**：
- 理解响应式编程基本原理
- 掌握Mono和Flux的基本操作
- 理解背压机制的作用
---
#### 第2-3周：WebFlux实战
**培训内容**：
- WebFlux应用架构
- 路由和处理器
- 请求验证和异常处理
- 响应式WebClient
**培训方式**：编码练习
**考核方式**：代码审查
**学习目标**：
- 能够使用WebFlux开发REST API
- 掌握路由和处理器的设计
- 能够处理异常和验证请求
---
#### 第4周：R2DBC实战
**培训内容**：
- R2DBC连接池配置
- 响应式Repository
- 事务管理
- 性能优化
**培训方式**：编码练习
**考核方式**：代码审查
**学习目标**：
- 能够使用R2DBC进行数据库操作
- 掌握响应式事务管理
- 能够优化数据库性能
---
#### 第5周：性能调优
**培训内容**：
- 响应式流监控
- 性能测试工具
- 调优策略
- 常见问题排查
**培训方式**：性能测试
**考核方式**：性能报告
**学习目标**：
- 能够监控响应式流
- 掌握性能测试工具
- 能够进行性能调优
---
#### 第6周：综合项目
**培训内容**：
- 完整项目实战
- 代码审查
- 项目答辩
**培训方式**：项目实战
**考核方式**：项目评审
**学习目标**：
- 能够独立完成响应式项目
- 代码质量达到生产标准
---
### 2.2 培训资源
**官方文档**：
- Spring WebFlux官方文档
- Project Reactor官方文档
- R2DBC官方文档
**视频课程**：
- Reactor官方教程
- Spring WebFlux实战课程
**实战项目**：
- 健身房管理系统的会员模块
---
### 2.3 培训方式
**线上自学 + 线下辅导**：
- 每周自学时间：10小时
- 每周集中答疑：2次（每次1小时）
- 编码练习：每周20小时
- 项目实战：最后2周全职
---
## 三、考核方案
### 3.1 理论考试
**考试内容**：
- 响应式编程基础概念
- WebFlux核心原理
- R2DBC使用方法
- 性能调优策略
**考试形式**：在线考试
**及格标准**：≥80分
---
### 3.2 代码审查
**审查内容**：
- 代码规范性
- 响应式编程最佳实践
- 异常处理
- 性能优化
**审查标准**：
- 代码规范符合团队标准
- 无明显性能问题
- 异常处理完善
- 测试覆盖率≥80%
**通过标准**：审查通过率≥90%
---
### 3.3 项目评审
**评审内容**：
- 项目功能完整性
- 代码质量
- 性能指标
- 文档完整性
**评审标准**：
- 功能完整且符合需求
- 代码质量达到生产标准
- 性能指标达标
- 文档完整清晰
---
## 四、实施计划
### 4.1 培训时间表
| 周次 | 培训内容 | 培训方式 | 考核方式 | 负责人 |
|------|---------|---------|---------|--------|
| 第1周 | 响应式编程基础 | 线上课程 | 理论考试 | 培训讲师 |
| 第2-3周 | WebFlux实战 | 编码练习 | 代码审查 | 培训讲师 |
| 第4周 | R2DBC实战 | 编码练习 | 代码审查 | 培训讲师 |
| 第5周 | 性能调优 | 性能测试 | 性能报告 | 培训讲师 |
| 第6周 | 综合项目 | 项目实战 | 项目评审 | 培训讲师 |
---
### 4.2 资源需求
**人力资源**：
- 培训讲师：1人
- 参训人员：全体后端开发
**时间资源**：
- 培训时间：4-6周
- 每周培训时间：30小时
**预算资源**：
- 培训预算：¥10,000
- 包含：课程费用、讲师费用、材料费用
---
## 五、验收标准
### 5.1 培训验收
- [ ] 团队成员通过理论考试（≥80分）
- [ ] 团队成员完成实战项目
- [ ] 代码审查通过率≥90%
### 5.2 效果验收
- [ ] 开发效率提升30%
- [ ] 代码质量提升50%
- [ ] Bug率降低40%
---
## 六、风险与应对
### 6.1 风险识别
**风险1：学员基础参差不齐**
- 应对：分层次培训，基础薄弱学员额外辅导
**风险2：培训时间冲突**
- 应对：灵活安排培训时间，提供录播课程
**风险3：实战项目难度过大**
- 应对：提供项目模板和指导文档
---
## 七、相关文档
- [改进路线图](../05-PLANS/改进路线图.md)
- [EVAL-001-架构合理性评估报告](../03-EVALUATION/EVAL-001-架构合理性评估报告.md)
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
docs/06-IMPLEMENTATION/IMPL-002-敏感数据加密存储方案.md
-590
View File
@@ -1,590 +0,0 @@
# IMPL-002: 敏感数据加密存储方案
> 文档编号: GYM-IMPL-002
> 版本: v1.0
> 日期: 2026-04-05
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-05 | 张翔 | 创建敏感数据加密存储方案 |
---
## 一、需求分析
### 1.1 问题背景
会员隐私数据、支付信息等敏感数据未加密存储，存在数据泄露风险。
### 1.2 敏感数据识别
| 数据类型 | 字段名 | 敏感级别 | 加密要求 |
|---------|--------|---------|---------|
| 会员手机号 | phone | 高 | AES-256-GCM |
| 会员身份证号 | id_card | 高 | AES-256-GCM |
| 会员银行卡号 | bank_card | 高 | AES-256-GCM |
| 支付密码 | payment_password | 高 | BCrypt |
| 会员地址 | address | 中 | AES-256-GCM |
### 1.3 加密要求
- 加密算法：AES-256-GCM
- 密钥长度：256位
- 加密模式：GCM（提供认证加密）
- 密钥管理：环境变量 + 密钥管理服务
### 1.4 成功标准
- 数据安全性提升100%
- 合规性提升
- 加密/解密性能≤10ms
- 数据迁移成功率100%
---
## 二、技术方案设计
### 2.1 加密算法选择
**AES-256-GCM优势**：
- ✅ 安全性高：256位密钥长度
- ✅ 认证加密：GCM模式提供数据完整性验证
- ✅ 性能优秀：硬件加速支持
- ✅ 广泛应用：业界标准算法
**加密流程**：
```
明文 → 生成IV → AES-GCM加密 → Base64编码 → 密文
密文 → Base64解码 → AES-GCM解密 → 明文
```
---
### 2.2 密钥管理方案
#### 开发环境
**方案**：环境变量存储密钥
**配置**：
```bash
export ENCRYPTION_KEY=your-256-bit-key-here
export ENCRYPTION_IV=your-initialization-vector
```
**优势**：
- 简单易用
- 不易泄露到代码库
---
#### 测试环境
**方案**：环境变量 + 配置文件加密
**配置**：
```yaml
encryption:
key: ${ENCRYPTION_KEY}
iv: ${ENCRYPTION_IV}
enabled: true
```
**优势**：
- 配置灵活
- 支持多环境
---
#### 生产环境
**方案**：密钥管理服务（如阿里云KMS）
**架构**：
```
应用启动 → 从KMS获取密钥 → 缓存到内存 → 使用密钥加密/解密
```
**优势**：
- 密钥集中管理
- 密钥自动轮换
- 审计日志完整
---
### 2.3 数据迁移方案
#### 迁移步骤
**步骤1：创建加密字段**
```sql
ALTER TABLE member ADD COLUMN phone_encrypted VARCHAR(255);
ALTER TABLE member ADD COLUMN id_card_encrypted VARCHAR(255);
ALTER TABLE member ADD COLUMN bank_card_encrypted VARCHAR(255);
```
**步骤2：批量加密现有数据**
```java
@Transactional
public void migrateData() {
List<Member> members = memberRepository.findAll();
for (Member member : members) {
if (member.getPhone() != null) {
String encrypted = encryptionUtil.encrypt(member.getPhone());
member.setPhoneEncrypted(encrypted);
}
// 其他字段类似处理
}
memberRepository.saveAll(members);
}
```
**步骤3：验证加密数据正确性**
```java
public void verifyEncryption() {
List<Member> members = memberRepository.findAll();
for (Member member : members) {
if (member.getPhoneEncrypted() != null) {
String decrypted = encryptionUtil.decrypt(member.getPhoneEncrypted());
// 验证解密后的数据与原数据一致
assert decrypted.equals(member.getPhone());
}
}
}
```
**步骤4：删除明文字段**
```sql
ALTER TABLE member DROP COLUMN phone;
ALTER TABLE member DROP COLUMN id_card;
ALTER TABLE member DROP COLUMN bank_card;
```
**步骤5：重命名字段**
```sql
ALTER TABLE member CHANGE COLUMN phone_encrypted phone VARCHAR(255);
ALTER TABLE member CHANGE COLUMN id_card_encrypted id_card VARCHAR(255);
ALTER TABLE member CHANGE COLUMN bank_card_encrypted bank_card VARCHAR(255);
```
---
## 三、代码结构设计
### 3.1 包结构
```
com.gym.manage.security/
├── encryption/
│ ├── EncryptionUtil.java # 加密工具类
│ ├── KeyManager.java # 密钥管理器
│ └── EncryptionConfig.java # 加密配置
├── converter/
│ ├── PhoneEncryptConverter.java # 手机号加密转换器
│ ├── IdCardEncryptConverter.java # 身份证号加密转换器
│ └── BankCardEncryptConverter.java # 银行卡号加密转换器
└── aspect/
└── EncryptionAspect.java # 加密切面
```
---
### 3.2 核心类设计
#### EncryptionUtil
```java
@Component
public class EncryptionUtil {
private static final String ALGORITHM = "AES/GCM/NoPadding";
private static final int GCM_IV_LENGTH = 12;
private static final int GCM_TAG_LENGTH = 128;
@Autowired
private KeyManager keyManager;
/**
* 加密
* @param plaintext 明文
* @return 密文（Base64编码）
*/
public String encrypt(String plaintext) {
try {
SecretKey key = keyManager.getKey();
byte[] iv = generateIV();
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH, iv);
cipher.init(Cipher.ENCRYPT_MODE, key, spec);
byte[] ciphertext = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
// IV + Ciphertext
ByteBuffer buffer = ByteBuffer.allocate(iv.length + ciphertext.length);
buffer.put(iv);
buffer.put(ciphertext);
return Base64.getEncoder().encodeToString(buffer.array());
} catch (Exception e) {
throw new EncryptionException("加密失败", e);
}
}
/**
* 解密
* @param ciphertext 密文（Base64编码）
* @return 明文
*/
public String decrypt(String ciphertext) {
try {
SecretKey key = keyManager.getKey();
byte[] decoded = Base64.getDecoder().decode(ciphertext);
ByteBuffer buffer = ByteBuffer.wrap(decoded);
byte[] iv = new byte[GCM_IV_LENGTH];
buffer.get(iv);
byte[] encrypted = new byte[buffer.remaining()];
buffer.get(encrypted);
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH, iv);
cipher.init(Cipher.DECRYPT_MODE, key, spec);
byte[] plaintext = cipher.doFinal(encrypted);
return new String(plaintext, StandardCharsets.UTF_8);
} catch (Exception e) {
throw new EncryptionException("解密失败", e);
}
}
private byte[] generateIV() {
byte[] iv = new byte[GCM_IV_LENGTH];
new SecureRandom().nextBytes(iv);
return iv;
}
}
```
#### KeyManager
```java
@Component
public class KeyManager {
@Value("${encryption.key}")
private String keyString;
private SecretKey cachedKey;
/**
* 获取加密密钥
* @return SecretKey
*/
public SecretKey getKey() {
if (cachedKey == null) {
cachedKey = generateKey(keyString);
}
return cachedKey;
}
private SecretKey generateKey(String keyString) {
byte[] keyBytes = keyString.getBytes(StandardCharsets.UTF_8);
return new SecretKeySpec(keyBytes, "AES");
}
}
```
#### PhoneEncryptConverter
```java
@Component
@Converter(autoApply = true)
public class PhoneEncryptConverter implements AttributeConverter<String, String> {
@Autowired
private EncryptionUtil encryptionUtil;
@Override
public String convertToDatabaseColumn(String attribute) {
if (attribute == null) {
return null;
}
return encryptionUtil.encrypt(attribute);
}
@Override
public String convertToEntityAttribute(String dbData) {
if (dbData == null) {
return null;
}
return encryptionUtil.decrypt(dbData);
}
}
```
---
## 四、测试方案
### 4.1 单元测试
#### 加密/解密功能测试
```java
@SpringBootTest
public class EncryptionUtilTest {
@Autowired
private EncryptionUtil encryptionUtil;
@Test
public void testEncryptAndDecrypt() {
String plaintext = "13800138000";
// 加密
String ciphertext = encryptionUtil.encrypt(plaintext);
assertNotNull(ciphertext);
assertNotEquals(plaintext, ciphertext);
// 解密
String decrypted = encryptionUtil.decrypt(ciphertext);
assertEquals(plaintext, decrypted);
}
@Test
public void testEncryptSamePlaintextDifferentCiphertext() {
String plaintext = "13800138000";
String ciphertext1 = encryptionUtil.encrypt(plaintext);
String ciphertext2 = encryptionUtil.encrypt(plaintext);
// 相同明文，不同密文（因为IV不同）
assertNotEquals(ciphertext1, ciphertext2);
// 但都能正确解密
assertEquals(plaintext, encryptionUtil.decrypt(ciphertext1));
assertEquals(plaintext, encryptionUtil.decrypt(ciphertext2));
}
@Test
public void testEncryptNull() {
String ciphertext = encryptionUtil.encrypt(null);
assertNull(ciphertext);
}
@Test
public void testDecryptInvalidCiphertext() {
assertThrows(EncryptionException.class, () -> {
encryptionUtil.decrypt("invalid-ciphertext");
});
}
}
```
#### 密钥管理测试
```java
@SpringBootTest
public class KeyManagerTest {
@Autowired
private KeyManager keyManager;
@Test
public void testGetKey() {
SecretKey key = keyManager.getKey();
assertNotNull(key);
assertEquals("AES", key.getAlgorithm());
assertEquals(32, key.getEncoded().length); // 256位 = 32字节
}
@Test
public void testKeyCache() {
SecretKey key1 = keyManager.getKey();
SecretKey key2 = keyManager.getKey();
// 密钥应该被缓存
assertSame(key1, key2);
}
}
```
---
### 4.2 集成测试
#### 数据库存储加密测试
```java
@SpringBootTest
@Transactional
public class MemberEncryptionTest {
@Autowired
private MemberRepository memberRepository;
@Autowired
private EncryptionUtil encryptionUtil;
@Test
public void testSaveEncryptedPhone() {
Member member = new Member();
member.setPhone("13800138000");
Member saved = memberRepository.save(member);
// 从数据库直接查询（绕过JPA转换器）
String encryptedPhone = jdbcTemplate.queryForObject(
"SELECT phone FROM member WHERE id = ?",
String.class,
saved.getId()
);
// 验证数据库中存储的是加密后的数据
assertNotNull(encryptedPhone);
assertNotEquals("13800138000", encryptedPhone);
// 验证可以正确解密
String decrypted = encryptionUtil.decrypt(encryptedPhone);
assertEquals("13800138000", decrypted);
}
@Test
public void testReadDecryptedPhone() {
// 保存会员
Member member = new Member();
member.setPhone("13800138000");
Member saved = memberRepository.save(member);
// 读取会员
Member found = memberRepository.findById(saved.getId()).orElse(null);
// 验证读取的是解密后的数据
assertNotNull(found);
assertEquals("13800138000", found.getPhone());
}
}
```
---
### 4.3 性能测试
```java
@SpringBootTest
public class EncryptionPerformanceTest {
@Autowired
private EncryptionUtil encryptionUtil;
@Test
public void testEncryptPerformance() {
String plaintext = "13800138000";
int iterations = 1000;
long startTime = System.currentTimeMillis();
for (int i = 0; i < iterations; i++) {
encryptionUtil.encrypt(plaintext);
}
long endTime = System.currentTimeMillis();
long avgTime = (endTime - startTime) / iterations;
System.out.println("平均加密时间: " + avgTime + "ms");
assertTrue(avgTime < 10, "加密时间应小于10ms");
}
@Test
public void testDecryptPerformance() {
String plaintext = "13800138000";
String ciphertext = encryptionUtil.encrypt(plaintext);
int iterations = 1000;
long startTime = System.currentTimeMillis();
for (int i = 0; i < iterations; i++) {
encryptionUtil.decrypt(ciphertext);
}
long endTime = System.currentTimeMillis();
long avgTime = (endTime - startTime) / iterations;
System.out.println("平均解密时间: " + avgTime + "ms");
assertTrue(avgTime < 10, "解密时间应小于10ms");
}
}
```
---
## 五、实施步骤
| 步骤 | 任务 | 负责人 | 完成时间 | 验收标准 |
|------|------|--------|---------|---------|
| 1 | 识别敏感数据字段 | 后端开发 | 1天 | 敏感数据字段清单 |
| 2 | 设计加密方案 | 架构师 | 1天 | 加密方案文档 |
| 3 | 实现加密工具类 | 后端开发 | 2天 | 单元测试通过 |
| 4 | 实现JPA转换器 | 后端开发 | 1天 | 单元测试通过 |
| 5 | 数据迁移脚本 | 后端开发 | 1天 | 迁移脚本完成 |
| 6 | 测试验证 | 测试工程师 | 1天 | 所有测试通过 |
---
## 六、验收标准
### 6.1 功能验收
- [ ] 敏感数据加密存储
- [ ] 数据库中无明文敏感数据
- [ ] 加密数据可正确解密
- [ ] 通过安全审计
### 6.2 性能验收
- [ ] 加密/解密性能≤10ms
- [ ] 数据迁移成功率100%
### 6.3 安全验收
- [ ] 密钥管理安全
- [ ] 无密钥泄露风险
- [ ] 符合数据安全合规要求
---
## 七、风险与应对
### 7.1 风险识别
**风险1：密钥泄露**
- 应对：使用密钥管理服务，定期轮换密钥
**风险2：性能影响**
- 应对：使用硬件加速，优化加密算法
**风险3：数据迁移失败**
- 应对：备份原数据，分批迁移，验证后删除
**风险4：解密失败**
- 应对：保存原始密文，提供手动解密工具
---
## 八、相关文档
- [改进路线图](../05-PLANS/改进路线图.md)
- [EVAL-003-安全性与容错能力评估报告](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md)
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
docs/06-IMPLEMENTATION/IMPL-003-预约高峰期性能优化方案.md
-654
View File
@@ -1,654 +0,0 @@
# IMPL-003: 预约高峰期性能优化方案
> 文档编号: GYM-IMPL-003
> 版本: v1.0
> 日期: 2026-04-05
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-05 | 张翔 | 创建预约高峰期性能优化方案 |
---
## 一、需求分析
### 1.1 问题背景
预约高峰期QPS仅500-1000，距离目标2000+差距较大，影响用户体验和业务转化。
### 1.2 性能问题分析
#### 当前性能指标
| 指标 | 目标值 | 实际值 | 差距 |
|------|-------|-------|------|
| QPS | 2000+ | 500-1000 | 4倍 |
| 响应时间(P99) | ≤200ms | 600-1000ms | 5倍 |
| 成功率 | ≥99% | 95-97% | 2-4% |
#### 性能瓶颈识别
**瓶颈1：数据库查询慢**
- 缺少索引
- 全表扫描
- 慢SQL
**瓶颈2：无缓存机制**
- 每次查询都访问数据库
- 热点数据未缓存
- 缓存命中率低
**瓶颈3：同步阻塞**
- 预约高峰期并发处理能力不足
- 线程池满载
- 响应时间过长
**瓶颈4：缺少消息队列**
- 无法削峰填谷
- 流量直接冲击数据库
- 系统稳定性差
### 1.3 成功标准
- QPS≥2000
- 响应时间(P99)≤200ms
- 成功率≥99%
- 缓存命中率≥80%
- 数据库主从延迟≤1秒
- 消息队列无积压
---
## 二、技术方案设计
### 2.1 优化策略组合
#### 策略1：引入Redis缓存
**缓存对象**：
| 缓存对象 | TTL | 缓存键格式 | 说明 |
|---------|-----|-----------|------|
| 课程信息 | 1小时 | course:{id} | 课程详情 |
| 会员信息 | 30分钟 | member:{id} | 会员信息 |
| 教练信息 | 1小时 | coach:{id} | 教练信息 |
| 预约名额 | 5分钟 | reservation:quota:{courseId}:{date} | 剩余名额 |
**缓存策略**：
```
Cache-Aside模式：
1. 读取时先查缓存
2. 缓存未命中则查数据库
3. 查询结果写入缓存
4. 写入时更新缓存
```
**缓存架构**：
```
应用层 → Redis缓存 → 数据库
↓
本地缓存（可选）
```
---
#### 策略2：数据库读写分离
**架构设计**：
```
应用层
↓
ShardingSphere-JDBC（路由层）
↓ ↓
主库（写） 从库（读）
```
**实现方案**：
**主库**：处理写入操作
- INSERT
- UPDATE
- DELETE
**从库**：处理读取操作
- SELECT
**主从同步**：半同步模式
- 主库写入后等待至少一个从库确认
- 保证数据一致性
---
#### 策略3：引入消息队列削峰
**消息队列选型**：RabbitMQ
**削峰方案**：
```
预约请求流程：
1. 用户发起预约请求
2. 请求写入消息队列
3. 立即返回"预约中"状态
4. 后台消费者异步处理
5. 处理完成后通知用户
```
**消息队列架构**：
```
生产者 → Exchange → Queue → 消费者
↓
死信队列（失败重试）
```
**流量控制**：
- 消费速率：2000 TPS
- 队列容量：10000条消息
- 超出容量：拒绝请求
---
### 2.2 技术选型
| 组件 | 技术选型 | 版本 | 说明 |
|------|---------|------|------|
| 缓存 | Redis | 6.2+ | 高性能缓存 |
| 数据库中间件 | ShardingSphere-JDBC | 5.3+ | 读写分离路由 |
| 消息队列 | RabbitMQ | 3.9+ | 削峰填谷 |
---
## 三、代码结构设计
### 3.1 缓存层设计
#### 包结构
```
com.gym.manage.cache/
├── config/
│ ├── RedisConfig.java # Redis配置
│ └── CacheConfig.java # 缓存配置
├── service/
│ ├── CacheService.java # 缓存服务接口
│ └── CacheServiceImpl.java # 缓存服务实现
└── aspect/
└── CacheAspect.java # 缓存切面
```
#### 核心类设计
**RedisConfig**：
```java
@Configuration
public class RedisConfig {
@Bean
public RedisTemplate<String, Object> redisTemplate(
RedisConnectionFactory factory
) {
RedisTemplate<String, Object> template = new RedisTemplate<>();
template.setConnectionFactory(factory);
// 使用Jackson序列化
Jackson2JsonRedisSerializer<Object> serializer =
new Jackson2JsonRedisSerializer<>(Object.class);
template.setKeySerializer(new StringRedisSerializer());
template.setValueSerializer(serializer);
template.setHashKeySerializer(new StringRedisSerializer());
template.setHashValueSerializer(serializer);
return template;
}
}
```
**CacheService**：
```java
@Service
public class CacheServiceImpl implements CacheService {
@Autowired
private RedisTemplate<String, Object> redisTemplate;
@Override
public <T> T get(String key, Class<T> type) {
Object value = redisTemplate.opsForValue().get(key);
return value != null ? (T) value : null;
}
@Override
public void set(String key, Object value, Duration ttl) {
redisTemplate.opsForValue().set(key, value, ttl);
}
@Override
public void delete(String key) {
redisTemplate.delete(key);
}
@Override
public boolean hasKey(String key) {
return Boolean.TRUE.equals(redisTemplate.hasKey(key));
}
}
```
**CacheAspect**：
```java
@Aspect
@Component
public class CacheAspect {
@Autowired
private CacheService cacheService;
@Around("@annotation(cacheable)")
public Object around(ProceedingJoinPoint pjp, Cacheable cacheable)
throws Throwable {
String key = generateKey(cacheable.key(), pjp.getArgs());
// 先查缓存
Object cached = cacheService.get(key, cacheable.type());
if (cached != null) {
return cached;
}
// 缓存未命中，执行方法
Object result = pjp.proceed();
// 写入缓存
if (result != null) {
cacheService.set(key, result, Duration.ofMinutes(cacheable.ttl()));
}
return result;
}
private String generateKey(String pattern, Object[] args) {
// 生成缓存键
return String.format(pattern, args);
}
}
```
---
### 3.2 数据库层设计
#### 包结构
```
com.gym.manage.datasource/
├── config/
│ ├── MasterSlaveConfig.java # 主从配置
│ └── ShardingConfig.java # 分片配置
├── routing/
│ ├── DynamicDataSource.java # 动态数据源
│ └── DataSourceRouter.java # 数据源路由
└── annotation/
└── ReadOnly.java # 只读注解
```
#### 核心类设计
**MasterSlaveConfig**：
```java
@Configuration
public class MasterSlaveConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource.master")
public DataSource masterDataSource() {
return DataSourceBuilder.create().build();
}
@Bean
@ConfigurationProperties(prefix = "spring.datasource.slave")
public DataSource slaveDataSource() {
return DataSourceBuilder.create().build();
}
@Bean
public DynamicDataSource dynamicDataSource(
@Qualifier("masterDataSource") DataSource master,
@Qualifier("slaveDataSource") DataSource slave
) {
Map<Object, Object> targetDataSources = new HashMap<>();
targetDataSources.put("master", master);
targetDataSources.put("slave", slave);
DynamicDataSource dynamicDataSource = new DynamicDataSource();
dynamicDataSource.setDefaultTargetDataSource(master);
dynamicDataSource.setTargetDataSources(targetDataSources);
return dynamicDataSource;
}
}
```
**DynamicDataSource**：
```java
public class DynamicDataSource extends AbstractRoutingDataSource {
private static final ThreadLocal<String> CONTEXT_HOLDER = new ThreadLocal<>();
@Override
protected Object determineCurrentLookupKey() {
return CONTEXT_HOLDER.get();
}
public static void setMaster() {
CONTEXT_HOLDER.set("master");
}
public static void setSlave() {
CONTEXT_HOLDER.set("slave");
}
public static void clear() {
CONTEXT_HOLDER.remove();
}
}
```
**DataSourceRouter**：
```java
@Aspect
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class DataSourceRouter {
@Around("@annotation(readOnly)")
public Object route(ProceedingJoinPoint pjp, ReadOnly readOnly)
throws Throwable {
try {
DynamicDataSource.setSlave();
return pjp.proceed();
} finally {
DynamicDataSource.clear();
}
}
}
```
**ReadOnly注解**：
```java
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ReadOnly {
}
```
---
### 3.3 消息队列层设计
#### 包结构
```
com.gym.manage.mq/
├── config/
│ └── RabbitMQConfig.java # RabbitMQ配置
├── producer/
│ └── ReservationProducer.java # 预约生产者
├── consumer/
│ └── ReservationConsumer.java # 预约消费者
└── message/
└── ReservationMessage.java # 预约消息
```
#### 核心类设计
**RabbitMQConfig**：
```java
@Configuration
public class RabbitMQConfig {
public static final String EXCHANGE = "reservation.exchange";
public static final String QUEUE = "reservation.queue";
public static final String ROUTING_KEY = "reservation.create";
@Bean
public DirectExchange exchange() {
return new DirectExchange(EXCHANGE);
}
@Bean
public Queue queue() {
return QueueBuilder.durable(QUEUE)
.withArgument("x-message-ttl", 60000) // 消息TTL: 1分钟
.withArgument("x-dead-letter-exchange", "reservation.dlx")
.build();
}
@Bean
public Binding binding() {
return BindingBuilder.bind(queue())
.to(exchange())
.with(ROUTING_KEY);
}
}
```
**ReservationProducer**：
```java
@Service
public class ReservationProducer {
@Autowired
private RabbitTemplate rabbitTemplate;
public void sendReservation(ReservationMessage message) {
rabbitTemplate.convertAndSend(
RabbitMQConfig.EXCHANGE,
RabbitMQConfig.ROUTING_KEY,
message
);
}
}
```
**ReservationConsumer**：
```java
@Service
public class ReservationConsumer {
@Autowired
private ReservationService reservationService;
@RabbitListener(queues = RabbitMQConfig.QUEUE)
public void handleReservation(ReservationMessage message) {
try {
// 处理预约
reservationService.processReservation(message);
} catch (Exception e) {
// 异常处理，消息进入死信队列
throw new AmqpRejectAndDontRequeueException(e);
}
}
}
```
---
## 四、测试方案
### 4.1 性能测试
#### 测试工具
- JMeter：压力测试
- Gatling：性能测试
- Prometheus + Grafana：监控
#### 测试场景
**场景1：预约高峰期模拟**
```scala
scenario("预约高峰期")
.exec(http("预约课程")
.post("/api/reservations")
.body(StringBody("""{"courseId":1,"memberId":1}"""))
.check(status.is(200))
)
.inject(
rampUsersPerSec(100) to 2000 during (300 seconds)
)
.protocols(httpProtocol)
```
**场景2：缓存命中率测试**
```java
@Test
public void testCacheHitRate() {
int totalRequests = 1000;
int cacheHits = 0;
for (int i = 0; i < totalRequests; i++) {
Course course = courseService.getCourseById(1L);
if (cacheService.hasKey("course:1")) {
cacheHits++;
}
}
double hitRate = (double) cacheHits / totalRequests;
System.out.println("缓存命中率: " + (hitRate * 100) + "%");
assertTrue(hitRate >= 0.8, "缓存命中率应≥80%");
}
```
---
### 4.2 压力测试
#### 测试步骤
1. 逐步增加并发数（500 → 1000 → 2000 → 3000）
2. 监控系统资源（CPU、内存、网络）
3. 记录性能指标（QPS、响应时间、成功率）
4. 识别系统极限
#### 性能指标
| 并发数 | QPS | 响应时间(P99) | 成功率 | CPU利用率 | 内存利用率 |
|--------|-----|--------------|--------|----------|-----------|
| 500 | 500 | 100ms | 99% | 30% | 50% |
| 1000 | 1000 | 150ms | 99% | 50% | 60% |
| 2000 | 2000 | 200ms | 99% | 70% | 70% |
| 3000 | 2500 | 300ms | 95% | 90% | 80% |
---
### 4.3 稳定性测试
#### 测试步骤
1. 持续运行2小时
2. 监控内存泄漏
3. 监控GC频率
4. 记录系统稳定性指标
#### 稳定性指标
- 内存占用稳定
- GC频率正常
- 无内存泄漏
- 无死锁
---
## 五、实施步骤
| 步骤 | 任务 | 负责人 | 完成时间 | 验收标准 |
|------|------|--------|---------|---------|
| 1 | Redis环境搭建 | 运维工程师 | 1天 | Redis服务正常运行 |
| 2 | 实现缓存服务 | 后端开发 | 2天 | 单元测试通过 |
| 3 | 数据库主从配置 | 运维工程师 | 1天 | 主从同步正常 |
| 4 | 实现读写分离 | 后端开发 | 3天 | 集成测试通过 |
| 5 | RabbitMQ环境搭建 | 运维工程师 | 1天 | RabbitMQ服务正常运行 |
| 6 | 实现消息队列 | 后端开发 | 2天 | 单元测试通过 |
| 7 | 性能测试 | 测试工程师 | 2天 | 性能指标达标 |
| 8 | 灰度发布 | 运维工程师 | 1天 | 灰度发布成功 |
---
## 六、验收标准
### 6.1 性能验收
- [ ] QPS≥2000
- [ ] 响应时间(P99)≤200ms
- [ ] 成功率≥99%
### 6.2 缓存验收
- [ ] 缓存命中率≥80%
- [ ] 缓存穿透防护有效
- [ ] 缓存雪崩防护有效
### 6.3 数据库验收
- [ ] 数据库主从延迟≤1秒
- [ ] 读写分离正常
- [ ] 数据一致性保证
### 6.4 消息队列验收
- [ ] 消息队列无积压
- [ ] 消息不丢失
- [ ] 消费速率达标
---
## 七、风险与应对
### 7.1 风险识别
**风险1：缓存穿透**
- 应对：布隆过滤器 + 空值缓存
**风险2：缓存雪崩**
- 应对：随机过期时间 + 多级缓存
**风险3：主从延迟**
- 应对：关键业务读主库 + 半同步复制
**风险4：消息队列积压**
- 应对：监控告警 + 动态扩容消费者
---
## 八、相关文档
- [改进路线图](../05-PLANS/改进路线图.md)
- [EVAL-002-性能与可扩展性评估报告](../03-EVALUATION/EVAL-002-性能与可扩展性评估报告.md)
- [ADR-002-响应式编程选型](../02-ARCHITECTURE/架构决策记录/ADR-002-响应式编程选型.md)
docs/06-IMPLEMENTATION/IMPL-004-支付接口幂等性校验方案.md
-741
View File
@@ -1,741 +0,0 @@
# IMPL-004: 支付接口幂等性校验方案
> 文档编号: GYM-IMPL-004
> 版本: v1.0
> 日期: 2026-04-05
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-04-05 | 张翔 | 创建支付接口幂等性校验方案 |
---
## 一、需求分析
### 1.1 问题背景
支付接口缺少幂等性校验，可能导致：
- 用户重复点击支付按钮，产生多笔订单
- 网络超时重试，导致重复扣款
- 支付回调重复通知，导致订单状态异常
### 1.2 影响范围
**用户体验**：
- 重复扣款导致用户投诉
- 订单状态不一致
**财务风险**：
- 资金对账困难
- 退款流程复杂
**业务风险**：
- 订单状态不一致
- 数据完整性问题
### 1.3 成功标准
- 支付接口幂等性覆盖率100%
- 通过重复支付测试
- 通过并发支付测试
- 幂等检查性能≤10ms
---
## 二、技术方案设计
### 2.1 幂等性实现方案
#### 方案架构
```
支付请求流程：
1. 前端生成唯一订单号
2. 后端检查订单号是否已存在
3. 不存在则创建支付流水
4. 调用第三方支付
5. 支付回调处理（幂等）
6. 更新订单状态（幂等）
```
#### 核心机制
**机制1：唯一订单号**
- 格式：UUID + 时间戳 + 业务标识
- 示例：PAY-20260405-UUID-001
- 作用：全局唯一标识
**机制2：支付流水表**
- 记录所有支付请求
- 字段：流水ID、订单ID、支付单号、金额、状态、请求号
- 作用：幂等性保证
**机制3：分布式锁**
- 实现：Redis分布式锁
- 锁键：payment:lock:{requestNo}
- 作用：防止并发重复支付
**机制4：状态机**
- 订单状态流转控制
- 状态：待支付、支付中、支付成功、支付失败、取消支付
- 作用：状态一致性保证
---
### 2.2 支付状态机
#### 状态定义
```java
public enum PaymentState {
PENDING, // 待支付
PAYING, // 支付中
SUCCESS, // 支付成功
FAILED, // 支付失败
CANCELLED // 取消支付
}
```
#### 事件定义
```java
public enum PaymentEvent {
PAY, // 发起支付
SUCCESS, // 支付成功
FAIL, // 支付失败
CANCEL // 取消支付
}
```
#### 状态转换规则
```
状态转换图：
待支付 ──PAY──> 支付中 ──SUCCESS──> 支付成功
│ │
│ └──FAIL──> 支付失败
│
└──CANCEL──> 取消支付
转换规则：
- 待支付 → 支付中：发起支付
- 支付中 → 支付成功：支付成功回调
- 支付中 → 支付失败：支付失败回调
- 待支付 → 取消支付：用户取消
```
---
## 三、代码结构设计
### 3.1 包结构
```
com.gym.manage.payment/
├── idempotent/
│ ├── IdempotentService.java # 幂等性服务接口
│ ├── IdempotentServiceImpl.java # 幂等性服务实现
│ └── IdempotentAspect.java # 幂等性切面
├── statemachine/
│ ├── PaymentStateMachine.java # 支付状态机
│ ├── PaymentState.java # 支付状态
│ └── PaymentEvent.java # 支付事件
├── entity/
│ ├── PaymentFlow.java # 支付流水实体
│ └── PaymentOrder.java # 支付订单实体
├── repository/
│ ├── PaymentFlowRepository.java # 支付流水Repository
│ └── PaymentOrderRepository.java # 支付订单Repository
├── service/
│ ├── PaymentService.java # 支付服务接口
│ └── PaymentServiceImpl.java # 支付服务实现
└── controller/
└── PaymentController.java # 支付控制器
```
---
### 3.2 核心类设计
#### PaymentFlow实体
```java
@Entity
@Table(name = "payment_flow",
uniqueConstraints = @UniqueConstraint(columnNames = "requestNo"))
public class PaymentFlow {
@Id
@GeneratedValue(strategy = GenerationType.UUID)
private String flowId; // 流水ID
@Column(unique = true, nullable = false)
private String requestNo; // 请求号（幂等键）
@Column(nullable = false)
private String orderId; // 订单ID
private String paymentNo; // 支付单号
@Column(nullable = false, precision = 10, scale = 2)
private BigDecimal amount; // 支付金额
@Enumerated(EnumType.STRING)
private PaymentState state; // 支付状态
private String channel; // 支付渠道
private String errorMessage; // 错误信息
@CreatedDate
private LocalDateTime createTime; // 创建时间
@LastModifiedDate
private LocalDateTime updateTime; // 更新时间
}
```
#### IdempotentServiceImpl
```java
@Service
@Transactional
public class IdempotentServiceImpl implements IdempotentService {
@Autowired
private RedisTemplate<String, String> redisTemplate;
@Autowired
private PaymentFlowRepository flowRepository;
private static final String LOCK_PREFIX = "payment:lock:";
private static final Duration LOCK_TIMEOUT = Duration.ofMinutes(5);
@Override
public PaymentFlow checkAndCreate(String requestNo, PaymentRequest request) {
// 1. 分布式锁
String lockKey = LOCK_PREFIX + requestNo;
Boolean locked = redisTemplate.opsForValue()
.setIfAbsent(lockKey, "1", LOCK_TIMEOUT);
if (!locked) {
throw new PaymentException("支付处理中，请勿重复提交");
}
try {
// 2. 检查流水是否已存在
PaymentFlow existFlow = flowRepository
.findByRequestNo(requestNo)
.orElse(null);
if (existFlow != null) {
return existFlow; // 幂等返回
}
// 3. 创建新流水
PaymentFlow flow = new PaymentFlow();
flow.setRequestNo(requestNo);
flow.setOrderId(request.getOrderId());
flow.setAmount(request.getAmount());
flow.setState(PaymentState.PENDING);
flow.setChannel(request.getChannel());
return flowRepository.save(flow);
} finally {
redisTemplate.delete(lockKey);
}
}
@Override
public PaymentFlow check(String requestNo) {
return flowRepository.findByRequestNo(requestNo).orElse(null);
}
}
```
#### PaymentStateMachine
```java
@Component
public class PaymentStateMachine {
@Autowired
private PaymentOrderRepository orderRepository;
/**
* 状态转换（幂等）
*/
@Transactional
public boolean transit(String orderId, PaymentEvent event) {
PaymentOrder order = orderRepository.findById(orderId)
.orElseThrow(() -> new PaymentException("订单不存在"));
PaymentState currentState = order.getState();
// 检查状态转换是否合法
if (!canTransit(currentState, event)) {
return false; // 幂等返回
}
// 执行状态转换
PaymentState newState = getNextState(currentState, event);
order.setState(newState);
orderRepository.save(order);
return true;
}
private boolean canTransit(PaymentState current, PaymentEvent event) {
// 状态转换规则
switch (current) {
case PENDING:
return event == PaymentEvent.PAY ||
event == PaymentEvent.CANCEL;
case PAYING:
return event == PaymentEvent.SUCCESS ||
event == PaymentEvent.FAIL;
default:
return false; // 已终态，幂等返回
}
}
private PaymentState getNextState(PaymentState current, PaymentEvent event) {
switch (current) {
case PENDING:
if (event == PaymentEvent.PAY) return PaymentState.PAYING;
if (event == PaymentEvent.CANCEL) return PaymentState.CANCELLED;
break;
case PAYING:
if (event == PaymentEvent.SUCCESS) return PaymentState.SUCCESS;
if (event == PaymentEvent.FAIL) return PaymentState.FAILED;
break;
default:
break;
}
return current;
}
}
```
#### IdempotentAspect
```java
@Aspect
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class IdempotentAspect {
@Autowired
private IdempotentService idempotentService;
@Around("@annotation(idempotent)")
public Object handleIdempotent(
ProceedingJoinPoint pjp,
Idempotent idempotent
) throws Throwable {
// 1. 获取幂等键
String requestNo = extractRequestNo(pjp);
// 2. 检查幂等性
Object result = idempotentService.check(requestNo);
if (result != null) {
return result; // 幂等返回
}
// 3. 执行业务逻辑
return pjp.proceed();
}
private String extractRequestNo(ProceedingJoinPoint pjp) {
// 从方法参数中提取requestNo
Object[] args = pjp.getArgs();
for (Object arg : args) {
if (arg instanceof PaymentRequest) {
return ((PaymentRequest) arg).getRequestNo();
}
}
throw new PaymentException("未找到幂等键");
}
}
```
#### PaymentServiceImpl
```java
@Service
@Transactional
public class PaymentServiceImpl implements PaymentService {
@Autowired
private IdempotentService idempotentService;
@Autowired
private PaymentStateMachine stateMachine;
@Autowired
private PaymentFlowRepository flowRepository;
@Autowired
private ThirdPartyPaymentService thirdPartyService;
@Override
public PaymentResponse pay(PaymentRequest request) {
// 1. 幂等性检查并创建流水
PaymentFlow flow = idempotentService.checkAndCreate(
request.getRequestNo(),
request
);
// 如果流水已存在，直接返回
if (flow.getState() != PaymentState.PENDING) {
return buildResponse(flow);
}
// 2. 状态转换：待支付 → 支付中
stateMachine.transit(flow.getFlowId(), PaymentEvent.PAY);
try {
// 3. 调用第三方支付
ThirdPartyPaymentResponse response = thirdPartyService.pay(
flow.getFlowId(),
flow.getAmount()
);
// 4. 更新支付单号
flow.setPaymentNo(response.getPaymentNo());
flowRepository.save(flow);
// 5. 返回支付结果
return buildResponse(flow);
} catch (Exception e) {
// 6. 支付失败，状态转换
stateMachine.transit(flow.getFlowId(), PaymentEvent.FAIL);
flow.setErrorMessage(e.getMessage());
flowRepository.save(flow);
throw new PaymentException("支付失败", e);
}
}
@Override
public void handleCallback(PaymentCallback callback) {
// 1. 查询支付流水
PaymentFlow flow = flowRepository.findById(callback.getFlowId())
.orElseThrow(() -> new PaymentException("流水不存在"));
// 2. 幂等性检查：如果已成功，直接返回
if (flow.getState() == PaymentState.SUCCESS) {
return; // 幂等返回
}
// 3. 状态转换
PaymentEvent event = callback.isSuccess() ?
PaymentEvent.SUCCESS : PaymentEvent.FAIL;
stateMachine.transit(flow.getFlowId(), event);
// 4. 更新流水
flowRepository.save(flow);
}
private PaymentResponse buildResponse(PaymentFlow flow) {
PaymentResponse response = new PaymentResponse();
response.setFlowId(flow.getFlowId());
response.setPaymentNo(flow.getPaymentNo());
response.setState(flow.getState());
response.setAmount(flow.getAmount());
return response;
}
}
```
---
## 四、测试方案
### 4.1 单元测试
#### 幂等性服务测试
```java
@SpringBootTest
@Transactional
public class IdempotentServiceTest {
@Autowired
private IdempotentService idempotentService;
@Autowired
private PaymentFlowRepository flowRepository;
@Test
public void testCheckAndCreate() {
String requestNo = "REQ-123456";
PaymentRequest request = new PaymentRequest();
request.setRequestNo(requestNo);
request.setOrderId("ORDER-001");
request.setAmount(new BigDecimal("100.00"));
// 第一次创建
PaymentFlow flow1 = idempotentService.checkAndCreate(requestNo, request);
assertNotNull(flow1);
assertEquals(PaymentState.PENDING, flow1.getState());
// 第二次创建（相同requestNo）
PaymentFlow flow2 = idempotentService.checkAndCreate(requestNo, request);
assertEquals(flow1.getFlowId(), flow2.getFlowId()); // 幂等返回
}
@Test
public void testConcurrentCreate() throws InterruptedException {
String requestNo = "REQ-789012";
int threadCount = 100;
CountDownLatch latch = new CountDownLatch(threadCount);
List<PaymentFlow> flows = Collections.synchronizedList(new ArrayList<>());
for (int i = 0; i < threadCount; i++) {
new Thread(() -> {
try {
PaymentFlow flow = idempotentService.checkAndCreate(
requestNo,
new PaymentRequest()
);
flows.add(flow);
} finally {
latch.countDown();
}
}).start();
}
latch.await();
// 验证只创建了一笔流水
assertEquals(1, flows.stream()
.map(PaymentFlow::getFlowId)
.distinct()
.count());
}
}
```
#### 状态机测试
```java
@SpringBootTest
@Transactional
public class PaymentStateMachineTest {
@Autowired
private PaymentStateMachine stateMachine;
@Autowired
private PaymentOrderRepository orderRepository;
@Test
public void testStateTransit() {
// 创建订单
PaymentOrder order = new PaymentOrder();
order.setOrderId("ORDER-001");
order.setState(PaymentState.PENDING);
orderRepository.save(order);
// 状态转换：待支付 → 支付中
boolean result1 = stateMachine.transit("ORDER-001", PaymentEvent.PAY);
assertTrue(result1);
PaymentOrder order1 = orderRepository.findById("ORDER-001").orElse(null);
assertEquals(PaymentState.PAYING, order1.getState());
// 状态转换：支付中 → 支付成功
boolean result2 = stateMachine.transit("ORDER-001", PaymentEvent.SUCCESS);
assertTrue(result2);
PaymentOrder order2 = orderRepository.findById("ORDER-001").orElse(null);
assertEquals(PaymentState.SUCCESS, order2.getState());
// 状态转换：支付成功 → 支付失败（非法转换）
boolean result3 = stateMachine.transit("ORDER-001", PaymentEvent.FAIL);
assertFalse(result3); // 幂等返回
}
}
```
---
### 4.2 集成测试
#### 完整支付流程测试
```java
@SpringBootTest
@Transactional
public class PaymentIntegrationTest {
@Autowired
private PaymentService paymentService;
@Autowired
private PaymentFlowRepository flowRepository;
@Test
public void testCompletePaymentFlow() {
// 1. 发起支付
PaymentRequest request = new PaymentRequest();
request.setRequestNo("REQ-001");
request.setOrderId("ORDER-001");
request.setAmount(new BigDecimal("100.00"));
PaymentResponse response = paymentService.pay(request);
assertNotNull(response.getFlowId());
assertEquals(PaymentState.PAYING, response.getState());
// 2. 模拟支付成功回调
PaymentCallback callback = new PaymentCallback();
callback.setFlowId(response.getFlowId());
callback.setSuccess(true);
paymentService.handleCallback(callback);
// 3. 验证流水状态
PaymentFlow flow = flowRepository.findById(response.getFlowId()).orElse(null);
assertEquals(PaymentState.SUCCESS, flow.getState());
}
@Test
public void testDuplicatePayment() {
String requestNo = "REQ-002";
// 第一次支付
PaymentRequest request = new PaymentRequest();
request.setRequestNo(requestNo);
request.setOrderId("ORDER-002");
request.setAmount(new BigDecimal("100.00"));
PaymentResponse response1 = paymentService.pay(request);
// 第二次支付（相同requestNo）
PaymentResponse response2 = paymentService.pay(request);
// 验证幂等性
assertEquals(response1.getFlowId(), response2.getFlowId());
}
}
```
---
### 4.3 压力测试
#### 并发支付测试
```java
@SpringBootTest
public class PaymentConcurrencyTest {
@Autowired
private PaymentService paymentService;
@Autowired
private PaymentFlowRepository flowRepository;
@Test
public void testConcurrentPayment() throws InterruptedException {
int threadCount = 100;
CountDownLatch latch = new CountDownLatch(threadCount);
String requestNo = "REQ-CONCURRENT-001";
for (int i = 0; i < threadCount; i++) {
new Thread(() -> {
try {
PaymentRequest request = new PaymentRequest();
request.setRequestNo(requestNo);
request.setOrderId("ORDER-CONCURRENT-001");
request.setAmount(new BigDecimal("100.00"));
paymentService.pay(request);
} finally {
latch.countDown();
}
}).start();
}
latch.await();
// 验证只创建了一笔支付流水
List<PaymentFlow> flows = flowRepository.findByRequestNo(requestNo);
assertEquals(1, flows.size());
}
}
```
---
## 五、实施步骤
| 步骤 | 任务 | 负责人 | 完成时间 | 验收标准 |
|------|------|--------|---------|---------|
| 1 | 设计幂等性方案 | 架构师 | 1天 | 方案文档完成 |
| 2 | 创建支付流水表 | 后端开发 | 1天 | 数据库表创建完成 |
| 3 | 实现幂等性服务 | 后端开发 | 2天 | 单元测试通过 |
| 4 | 实现状态机 | 后端开发 | 1天 | 单元测试通过 |
| 5 | 实现幂等性切面 | 后端开发 | 1天 | 单元测试通过 |
| 6 | 单元测试 | 后端开发 | 1天 | 单元测试通过 |
| 7 | 集成测试 | 测试工程师 | 1天 | 集成测试通过 |
| 8 | 压力测试 | 测试工程师 | 1天 | 性能指标达标 |
---
## 六、验收标准
### 6.1 功能验收
- [ ] 支付接口幂等性覆盖率100%
- [ ] 通过重复支付测试
- [ ] 通过并发支付测试
- [ ] 支付回调幂等处理
### 6.2 性能验收
- [ ] 幂等检查性能≤10ms
- [ ] 分布式锁获取≤5ms
### 6.3 安全验收
- [ ] 无重复扣款风险
- [ ] 订单状态一致性保证
---
## 七、风险与应对
### 7.1 风险识别
**风险1：分布式锁失效**
- 应对：数据库唯一索引兜底
**风险2：状态机死锁**
- 应对：超时自动释放 + 监控告警
**风险3：支付流水表过大**
- 应对：定期归档历史流水
**风险4：第三方支付重复回调**
- 应对：幂等处理 + 幂等键去重
---
## 八、相关文档
- [改进路线图](../05-PLANS/改进路线图.md)
- [EVAL-003-安全性与容错能力评估报告](../03-EVALUATION/EVAL-003-安全性与容错能力评估报告.md)
- [SEC-安全设计](../02-ARCHITECTURE/技术架构/SEC-安全设计.md)
docs/06-IMPLEMENTATION/IMPL-005-客户端优先架构调整方案.md
-1406
View File
File diff suppressed because it is too large Load Diff
docs/archive/v1.0/HLD-系统概要设计.md
-879
View File
@@ -1,879 +0,0 @@
# 健身房管理系统业务概要设计文档（HLD）
> 文档编号: GYM-HLD-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 初稿
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ------------------ |
| v1.0 | 2026-03-04 | 张翔 | 重构为业务概要设计 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统的业务概要设计文档（High-Level Design），旨在：
1. 从业务层面描述系统的业务范围、业务流程、业务规则
2. 为详细设计提供业务指导和约束
3. 作为产品经理、业务分析师、开发人员的业务参考
### 1.2 项目背景
健身房管理系统是一款面向综合型健身俱乐部、精品工作室、连锁品牌的全场景管理平台，核心解决：
- 会员端：一站式查看个人所有信息，便捷预约签到
- 管理后台：全维度数据整理与分析，支撑运营决策
- 多业态支持：灵活适配不同规模和类型的健身场所
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 1.4 参考文档
- 《健身房管理系统产品设计文档》 GYM-PRD-001
---
## 二、业务概述
### 2.1 业务目标
| 目标维度 | 目标描述 | 成功指标 |
| -------- | ---------------------- | -------------------------------- |
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供数据驱动决策支持 | 数据报表使用率 ≥ 80% |
| 业务扩展 | 支持多业态灵活适配 | 支持至少3种业态场景 |
### 2.2 用户角色
| 角色 | 描述 | 主要功能 |
| ---------- | -------------- | ---------------------------- |
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息 |
| 教练 | 健身房教练 | 排课、私教预约确认、学员签到 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看 |
| 运营管理员 | 平台运营人员 | 营销活动配置、数据分析 |
| 财务专员 | 财务人员 | 账单管理、财务报表 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
### 2.3 业务范围
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务范围 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 会员管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 会员注册 • 会员卡管理 • 权益管理 • 等级管理 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 预约管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 团课预约 • 私教预约 • 场地预约 • 线上课程 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 签到管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 扫码签到 • 刷脸签到 • NFC签到 • 教练代签 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 课程管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 课程类型 • 课程排期 • 场地管理 • 价格配置 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 教练管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 教练信息 • 排班管理 • 课时统计 • 评价管理 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 财务管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 营收统计 • 账单管理 • 退款管理 • 对账管理 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 计划中心 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 训练计划 • 课程排期 • 会员目标 • 教练排班 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 数据分析 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 会员分析 • 课程分析 • 财务分析 • 运营分析 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 系统管理 │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ • 租户管理 • 门店管理 • 权限管理 • 系统配置 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 2.4 产品版本架构
本系统采用**基础版 + 订阅模块**的产品架构，满足不同规模和业态的健身房需求：
#### 2.4.1 基础版
基础版保证业务闭环，适合小型工作室、个人教练等场景：
**包含模块：**
- ✅ 会员管理（完整）
- ✅ 会员卡管理（完整）
- ✅ 权益管理（完整）
- ✅ 团课预约（完整）
- ✅ 扫码签到（完整）
- ✅ 基础数据统计（完整）
- ✅ 系统管理（基础）
**限制：**
- 会员数量：最多500人
- 门店数量：单门店
- 团课容量：每节课最多20人
- 数据保留：保留30天
- 导出功能：基础导出
#### 2.4.2 订阅模块
订阅模块按需订阅，灵活扩展功能：
**业务扩展类模块：**
- 🔒 私教管理模块
- 🔒 场地预约模块
- 🔒 线上课程模块
**体验升级类模块：**
- 🔒 人脸识别签到
- 🔒 NFC签到
- 🔒 智能储物柜
**营销增长类模块：**
- 🔒 营销活动模块
- 🔒 会员推荐奖励
- 🔒 会员互动社区
**数据智能类模块：**
- 🔒 高级数据分析
- 🔒 智能报表
- 🔒 AI运营建议
### 2.5 配置层级架构
本系统采用**三层配置架构**，支持租户级和门店级配置，支持配置继承和覆盖：
#### 2.5.1 配置层级
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 配置层级架构 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 系统默认配置 │ │
│ │ - 所有模块默认启用 │ │
│ │ - 基础功能默认配置 │ │
│ └──────────────────┬──────────────────────────────────────────┘ │
│ │ 继承 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 租户级配置 │ │
│ │ - 租户A：启用团课、私教、营销 │ │
│ │ - 租户B：只启用私教、营销 │ │
│ └──────────────────┬──────────────────────────────────────────┘ │
│ │ 继承/覆盖 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 门店级配置 │ │
│ │ - 门店1：继承租户配置 │ │
│ │ - 门店2：继承租户配置 + 覆盖签到方式 │ │
│ │ - 门店3：完全自定义配置 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ 查询优先级：门店配置 → 租户配置 → 默认配置 │
└─────────────────────────────────────────────────────────────────────────┘
```
#### 2.5.2 继承模式
| 继承模式 | 说明 | 适用场景 |
| ------------- | ------------------------------ | ---------------------------------- |
| **继承** | 完全继承上级配置，不做任何修改 | 门店完全使用租户配置 |
| **继承+覆盖** | 继承上级配置，覆盖部分配置项 | 门店大部分使用租户配置，少量自定义 |
| **自定义** | 完全自定义配置，不继承上级配置 | 门店有特殊需求，完全独立配置 |
#### 2.5.3 配置示例
**场景一：连锁品牌 - 门店完全继承**
- 租户A配置：启用团课、私教、营销
- 门店1配置：继承模式=继承
- 最终生效：与租户配置一致
**场景二：连锁品牌 - 门店继承+覆盖**
- 租户A配置：签到方式=[二维码]
- 门店2配置：继承模式=继承+覆盖，签到方式=[二维码,人脸]
- 最终生效：签到方式=[二维码,人脸]，其他配置继承租户
**场景三：精品工作室 - 完全自定义**
- 租户B配置：签到方式=[二维码]
- 门店3配置：继承模式=自定义，签到方式=[人脸]
- 最终生效：签到方式=[人脸]，不继承租户配置
---
## 三、核心业务流程
### 3.1 会员注册与入会流程
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 会员注册与入会流程 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 新用户 │────▶│ 手机号 │────▶│ 验证码 │────▶│ 注册 │ │
│ │ 访问 │ │ 输入 │ │ 验证 │ │ 成功 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 信息 │ │
│ │ 完善 │ │
│ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 购买 │ │
│ │ 会员卡 │ │
│ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 入会 │ │
│ │ 完成 │ │
│ └──────────┘ │
│ │
│ 业务规则: │
│ • 手机号必须唯一，一个手机号只能注册一个会员 │
│ • 验证码有效期60秒，同一手机号60秒内只能发送一次 │
│ • 会员信息完善后才能购买会员卡 │
│ • 会员卡购买成功后立即生效，权益即时可用 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 3.2 课程预约流程
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 课程预约流程 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 会员 │────▶│ 浏览 │────▶│ 选择 │────▶│ 确认 │ │
│ │ 登录 │ │ 课程 │ │ 时段 │ │ 预约 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 权益 │ │
│ │ 检查 │ │
│ └──────────┘ │
│ │ │
│ ┌────────────┴────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 预约 │ │ 提示 │ │
│ │ 成功 │ │ 失败 │ │
│ └──────────┘ └──────────┘ │
│ │
│ 业务规则: │
│ • 会员必须拥有足够的权益才能预约（次数、时长、储值等） │
│ • 同一时段只能预约一个课程，预约冲突时提示用户 │
│ • 预约成功后发送通知（微信、短信） │
│ • 预约取消时间限制：开课前2小时内不能取消 │
│ • 热门课程支持候补机制，满员后自动进入候补队列 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 3.3 签到流程
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 签到流程 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 会员 │────▶│ 到达 │────▶│ 选择 │────▶│ 验证 │ │
│ │ 到达 │ │ 门店 │ │ 签到方式│ │ 身份 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ ┌────────────┴────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 扫码 │ │ 刷脸 │ │
│ │ 签到 │ │ 签到 │ │
│ └──────────┘ └──────────┘ │
│ │ │ │
│ └──────────┬──────────┘ │
│ ▼ │
│ ┌──────────┐ │
│ │ 预约 │ │
│ │ 检查 │ │
│ └──────────┘ │
│ │ │
│ ┌────────────┴────────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 签到 │ │ 手动 │ │
│ │ 成功 │ │ 处理 │ │
│ └──────────┘ └──────────┘ │
│ │
│ 业务规则: │
│ • 签到时验证会员身份和预约信息 │
│ • 有预约的会员优先签到，自动扣减权益 │
│ • 无预约的会员可以临时签到，需前台确认 │
│ • 签到成功后记录签到时间、设备信息 │
│ • 支持教练代签，教练可以确认学员签到 │
│ • 签到失败时提供明确的错误提示（如：预约不存在、权益不足） │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 3.4 会员卡购买与激活流程
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 会员卡购买与激活流程 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 会员 │────▶│ 浏览 │────▶│ 选择 │────▶│ 支付 │ │
│ │ 登录 │ │ 会员卡 │ │ 卡类型 │ │ 订单 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 支付 │ │
│ │ 成功 │ │
│ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 会员卡 │ │
│ │ 激活 │ │
│ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ 权益 │ │
│ │ 到账 │ │
│ └──────────┘ │
│ │
│ 业务规则: │
│ • 会员卡类型包括：时长卡、次卡、储值卡、等级卡 │
│ • 支付成功后会员卡立即激活，权益即时到账 │
│ • 会员卡有效期从激活日开始计算 │
│ • 支持会员卡转让功能（可选，需店长审批） │
│ • 会员卡到期前7天发送提醒通知 │
│ • 支持会员卡续费，续费后权益累加 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 四、业务规则
### 4.1 会员管理规则
#### 4.1.1 会员注册规则
- 手机号必须唯一，一个手机号只能注册一个会员
- 验证码有效期60秒，同一手机号60秒内只能发送一次
- 会员信息完善后才能购买会员卡
- 支持微信一键登录，自动关联手机号
#### 4.1.2 会员卡规则
- 会员卡类型：时长卡、次卡、储值卡、等级卡
- 会员卡支付成功后立即激活，权益即时到账
- 会员卡有效期从激活日开始计算
- 支持会员卡续费，续费后权益累加
- 会员卡到期前7天发送提醒通知
- 支持会员卡转让功能（可选，需店长审批）
#### 4.1.3 权益管理规则
- 权益类型：时长、次数、储值、等级
- 权益使用时优先级：储值 > 次数 > 时长 > 等级
- 权益扣减时先检查余额，余额不足时提示用户
- 权益使用记录永久保存，支持查询
- 权益到期后自动失效，不可使用
### 4.2 预约管理规则
#### 4.2.1 预约规则
- 会员必须拥有足够的权益才能预约（次数、时长、储值等）
- 同一时段只能预约一个课程，预约冲突时提示用户
- 预约成功后发送通知（微信、短信）
- 预约取消时间限制：开课前2小时内不能取消
- 热门课程支持候补机制，满员后自动进入候补队列
- 候补队列按预约时间排序，有人取消时自动补位
#### 4.2.2 课程排期规则
- 课程排期需提前至少24小时发布
- 课程排期修改需通知已预约会员
- 课程取消需提前2小时通知已预约会员
- 课程满员后自动开启候补
- 教练请假需提前24小时通知，系统自动调整排期
### 4.3 签到管理规则
#### 4.3.1 签到规则
- 签到时验证会员身份和预约信息
- 有预约的会员优先签到，自动扣减权益
- 无预约的会员可以临时签到，需前台确认
- 签到成功后记录签到时间、设备信息
- 支持教练代签，教练可以确认学员签到
- 签到失败时提供明确的错误提示（如：预约不存在、权益不足）
#### 4.3.2 签到时间规则
- 团课签到时间：开课前30分钟至开课后10分钟
- 私教签到时间：预约时间前后15分钟内
- 临时签到时间：门店营业时间内
- 迟到超过10分钟视为缺勤，不扣减权益
### 4.4 财务管理规则
#### 4.4.1 支付规则
- 支持多种支付方式：微信支付、支付宝、银行卡
- 支付成功后立即到账，实时更新财务数据
- 支持退款，退款需店长审批
- 退款原路返回，到账时间取决于支付渠道
- 支持对账功能，每日自动对账
#### 4.4.2 账单规则
- 账单实时生成，支持查询和导出
- 账单包含：订单号、金额、支付方式、时间、状态
- 账单状态：待支付、已支付、已退款、已取消
- 支持按时间、门店、会员、类型筛选账单
- 账单数据永久保存，支持审计
### 4.5 数据分析规则
#### 4.5.1 数据统计规则
- 数据实时统计，支持实时查询
- 数据按天、周、月、季度、年度汇总
- 支持多维度数据分析：会员、课程、财务、运营
- 数据报表支持导出：Excel、PDF
- 数据可视化：图表、趋势图、排行榜
#### 4.5.2 数据权限规则
- 超级管理员：查看全平台数据
- 运营管理员：查看负责区域数据
- 店长：查看本店数据
- 财务专员：查看财务数据
- 其他角色：按权限查看对应数据
### 4.6 订阅管理规则
#### 4.6.1 订阅套餐规则
- 基础版：包含核心业务模块，保证业务闭环
- 订阅模块：按需订阅，灵活扩展功能
- 组合套餐：多个模块组合，享受优惠价格
- 计费方式：月付、季付、半年付、年付，年付享受最大折扣
- 试用政策：不同模块类型提供不同天数的试用
#### 4.6.2 订阅生命周期规则
- 订阅状态：正常、暂停、取消、过期
- 订阅续费：到期前7天提醒，到期当天自动续费
- 订阅取消：取消后立即生效，不退还当月费用
- 订阅暂停：暂停期间不扣费，暂停期间无法使用模块
- 订阅过期：过期后立即禁用模块，数据保留30天
#### 4.6.3 订阅模块规则
- 模块启用：订阅成功后立即启用，无需重启
- 模块禁用：取消订阅后立即禁用，数据保留
- 模块配置：支持租户级和门店级配置，支持继承和覆盖
- 模块试用：试用期内可免费使用，试用结束后自动续费或取消
- 模块升级：支持模块升级，升级后立即生效，按差价计费
#### 4.6.4 配置继承规则
- 查询优先级：门店配置 → 租户配置 → 默认配置
- 继承模式：继承、继承+覆盖、自定义
- 配置版本：每次配置变更自动记录版本，支持回滚
- 配置缓存：配置数据缓存5分钟，配置变更后立即刷新缓存
- 配置审计：记录所有配置变更操作，支持审计查询
---
## 五、业务场景
### 5.1 典型业务场景
#### 5.1.1 会员预约团课场景
**场景描述**：
会员小李想预约明天晚上7点的瑜伽课程，他打开会员小程序，浏览课程列表，找到瑜伽课程，查看课程详情，确认教练、场地、时间，检查自己的会员权益（次卡剩余5次），确认可以预约，点击预约按钮，系统验证权益余额，预约成功，收到微信通知。
**业务流程**：
1. 会员登录小程序
2. 浏览课程列表
3. 选择瑜伽课程
4. 查看课程详情
5. 检查会员权益
6. 确认预约
7. 系统验证权益
8. 预约成功
9. 发送通知
**涉及的业务规则**：
- 会员必须拥有足够的权益才能预约
- 同一时段只能预约一个课程
- 预约成功后发送通知
#### 5.1.2 会员签到场景
**场景描述**：
会员小李到达健身房，打开会员小程序，点击签到按钮，选择刷脸签到，系统识别人脸，验证身份，检查预约信息，确认有预约，签到成功，自动扣减权益（次卡剩余4次），记录签到时间和设备信息。
**业务流程**：
1. 会员到达健身房
2. 打开会员小程序
3. 点击签到按钮
4. 选择刷脸签到
5. 系统识别人脸
6. 验证身份
7. 检查预约信息
8. 签到成功
9. 扣减权益
10. 记录签到信息
**涉及的业务规则**：
- 签到时验证会员身份和预约信息
- 有预约的会员优先签到，自动扣减权益
- 签到成功后记录签到时间、设备信息
#### 5.1.3 教练排课场景
**场景描述**：
教练王老师想安排下周的私教课程，他打开教练端App，查看自己的排班表，选择下周三下午2点到3点的时间段，选择私教课程，填写课程名称、课程描述，选择场地，设置价格，发布课程，系统自动生成预约时段，会员可以开始预约。
**业务流程**：
1. 教练登录教练端App
2. 查看排班表
3. 选择时间段
4. 选择课程类型
5. 填写课程信息
6. 选择场地
7. 设置价格
8. 发布课程
9. 系统生成预约时段
10. 会员可以预约
**涉及的业务规则**：
- 课程排期需提前至少24小时发布
- 课程排期修改需通知已预约会员
- 课程满员后自动开启候补
#### 5.1.4 店长查看数据场景
**场景描述**：
店长张经理想查看今天的运营数据，他打开管理后台，点击数据看板，查看今日概览（会员数、预约数、签到数、营收），查看趋势数据（近7天预约趋势、近30天营收趋势），查看排行数据（热门课程排行、活跃会员排行），导出数据报表。
**业务流程**：
1. 店长登录管理后台
2. 点击数据看板
3. 查看今日概览
4. 查看趋势数据
5. 查看排行数据
6. 导出数据报表
**涉及的业务规则**：
- 数据实时统计，支持实时查询
- 数据按天、周、月、季度、年度汇总
- 支持多维度数据分析
- 数据报表支持导出
#### 5.1.5 租户订阅场景
**场景描述**：
租户A是一家连锁健身房品牌，想启用私教管理和营销活动模块，租户管理员登录管理后台，查看订阅套餐，选择私教管理模块和营销活动模块，选择年付方式，查看优惠信息，确认订阅，支付成功，模块立即启用，租户开始使用新功能。
**业务流程**：
1. 租户管理员登录管理后台
2. 查看订阅套餐
3. 选择订阅模块
4. 选择计费方式
5. 查看优惠信息
6. 确认订阅
7. 支付成功
8. 模块立即启用
9. 开始使用新功能
**涉及的业务规则**：
- 订阅成功后模块立即启用，无需重启
- 年付享受最大折扣
- 支持多种支付方式
- 订阅成功后发送通知
#### 5.1.6 门店配置继承场景
**场景描述**：
租户A配置了团课、私教、营销模块，门店1想完全继承租户配置，门店2想在租户配置基础上覆盖签到方式（增加人脸识别），门店3想完全自定义配置。各门店管理员登录管理后台，选择继承模式，配置门店级参数，保存配置，配置立即生效。
**业务流程**：
1. 门店管理员登录管理后台
2. 查看租户级配置
3. 选择继承模式（继承/继承+覆盖/自定义）
4. 配置门店级参数
5. 保存配置
6. 配置立即生效
7. 验证配置生效
**涉及的业务规则**：
- 查询优先级：门店配置 → 租户配置 → 默认配置
- 支持三种继承模式
- 配置变更后立即生效
- 配置变更记录版本，支持回滚
### 5.2 特殊业务场景
#### 5.2.1 热门课程抢课场景
**场景描述**：
热门课程（如普拉提）只有10个名额，但有多名会员同时预约，系统采用先到先得的原则，前10名预约成功的会员获得名额，其他会员自动进入候补队列，有会员取消预约时，候补队列中的会员自动补位。
**业务流程**：
1. 多名会员同时预约热门课程
2. 系统处理预约请求
3. 前10名预约成功
4. 其他会员进入候补队列
5. 有会员取消预约
6. 候补队列中的会员自动补位
7. 发送补位通知
**涉及的业务规则**：
- 同一时段只能预约一个课程
- 热门课程支持候补机制
- 候补队列按预约时间排序
- 有人取消时自动补位
#### 5.2.2 会员卡过期续费场景
**场景描述**：
会员小李的会员卡即将过期，系统提前7天发送提醒通知，小李收到通知后，打开会员小程序，查看会员卡信息，点击续费按钮，选择续费时长，支付成功，会员卡续费成功，权益累加，有效期延长。
**业务流程**：
1. 系统检测会员卡即将过期
2. 提前7天发送提醒通知
3. 会员收到通知
4. 打开会员小程序
5. 查看会员卡信息
6. 点击续费按钮
7. 选择续费时长
8. 支付成功
9. 会员卡续费成功
10. 权益累加，有效期延长
**涉及的业务规则**：
- 会员卡到期前7天发送提醒通知
- 支持会员卡续费，续费后权益累加
- 会员卡有效期从续费成功日开始计算
#### 5.2.3 签到异常处理场景
**场景描述**：
会员小李到达健身房，尝试刷脸签到，但系统无法识别人脸，小李选择扫码签到，扫描二维码，系统验证身份，但发现没有预约，前台工作人员手动处理，确认会员身份，临时签到成功。
**业务流程**：
1. 会员到达健身房
2. 尝试刷脸签到
3. 系统无法识别人脸
4. 选择扫码签到
5. 扫描二维码
6. 系统验证身份
7. 发现没有预约
8. 前台手动处理
9. 确认会员身份
10. 临时签到成功
**涉及的业务规则**：
- 签到时验证会员身份和预约信息
- 无预约的会员可以临时签到，需前台确认
- 签到失败时提供明确的错误提示
---
## 六、业务约束
### 6.1 数据约束
- 会员手机号必须唯一
- 会员ID全局唯一
- 预约ID全局唯一
- 签到记录ID全局唯一
- 会员卡ID全局唯一
- 订单ID全局唯一
### 6.2 时间约束
- 验证码有效期60秒
- 预约取消时间限制：开课前2小时内不能取消
- 课程排期需提前至少24小时发布
- 课程取消需提前2小时通知已预约会员
- 教练请假需提前24小时通知
- 团课签到时间：开课前30分钟至开课后10分钟
- 私教签到时间：预约时间前后15分钟内
- 会员卡到期前7天发送提醒通知
### 6.3 权益约束
- 会员必须拥有足够的权益才能预约
- 权益使用时优先级：储值 > 次数 > 时长 > 等级
- 权益扣减时先检查余额，余额不足时提示用户
- 权益到期后自动失效，不可使用
- 权益使用记录永久保存，支持查询
### 6.4 并发约束
- 同一时段只能预约一个课程
- 热门课程支持候补机制
- 候补队列按预约时间排序
- 有人取消时自动补位
- 支持高并发场景（QPS ≥ 1000）
---
## 七、业务指标
### 7.1 用户体验指标
| 指标名称 | 目标值 | 测量方法 |
| ---------- | ------ | --------------------------- |
| 预约成功率 | ≥ 95% | 预约成功次数 / 预约总次数 |
| 签到耗时 | ≤ 3秒 | 签到完成时间 - 签到开始时间 |
| 注册成功率 | ≥ 98% | 注册成功次数 / 注册总次数 |
| 支付成功率 | ≥ 99% | 支付成功次数 / 支付总次数 |
### 7.2 运营效率指标
| 指标名称 | 目标值 | 测量方法 |
| ---------------- | ------ | -------------------------------------------------------------- |
| 人工处理时间减少 | ≥ 50% | (优化前人工处理时间 - 优化后人工处理时间) / 优化前人工处理时间 |
| 预约取消率 | ≤ 10% | 预约取消次数 / 预约总次数 |
| 签到成功率 | ≥ 98% | 签到成功次数 / 签到总次数 |
| 会员活跃度 | ≥ 60% | 活跃会员数 / 总会员数 |
### 7.3 数据价值指标
| 指标名称 | 目标值 | 测量方法 |
| -------------- | ------ | ------------------------------- |
| 数据报表使用率 | ≥ 80% | 使用数据报表的用户数 / 总用户数 |
| 数据准确性 | ≥ 99% | 数据准确记录数 / 数据总记录数 |
| 数据实时性 | ≤ 1秒 | 数据更新时间 - 数据产生时间 |
### 7.4 系统性能指标
| 指标名称 | 目标值 | 测量方法 |
| ------------ | ---------- | ---------------------------- |
| 系统可用性 | ≥ 99.9% | (总时间 - 故障时间) / 总时间 |
| 响应时间 | ≤ 2秒 | 请求响应时间 |
| 并发处理能力 | ≥ 1000 QPS | 每秒处理请求数 |
---
## 八、附录
### 8.1 业务术语表
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
| 预约(Booking) | 会员预订课程或场地的行为 |
| 签到(Check-in) | 会员到达健身房并记录到达时间的行为 |
| 会员卡(Member Card) | 会员购买的权益载体，包含时长、次数、储值等 |
| 候补(Waitlist) | 课程满员后，会员进入等待队列，有空位时自动补位 |
### 8.2 参考文档
- 《健身房管理系统产品设计文档》 GYM-PRD-001
- 《健身房管理系统详细设计文档》 GYM-LLD-001
---
**文档结束**
docs/archive/v1.0/PRD-产品设计文档.md
-929
View File
@@ -1,929 +0,0 @@
# 健身房管理系统产品设计文档（PRD）
> 文档编号: GYM-PRD-001
> 版本: v1.0
> 日期: 2026-02-28
> 作者: 张翔
> 状态: 初稿
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-02-28 | 张翔 | 初稿 |
---
## 一、产品概述
### 1.1 产品背景
随着健身行业数字化转型的加速，传统健身房面临着会员管理效率低、预约流程繁琐、数据统计困难等痛点。本系统旨在为综合型健身俱乐部、精品工作室、连锁品牌提供全场景的数字化管理平台，实现：
- 会员端：一站式查看个人所有信息，便捷预约签到
- 管理后台：全维度数据整理与分析，支撑运营决策
- 多业态支持：灵活适配不同规模和类型的健身场所
### 1.2 产品目标
| 目标维度 | 目标描述 | 成功指标 |
|---------|---------|---------|
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供数据驱动决策支持 | 数据报表使用率 ≥ 80% |
| 系统稳定 | 保证高可用性 | SLA ≥ 99.9% |
### 1.4 产品版本架构
本系统采用**基础版 + 订阅模块**的产品架构，满足不同规模和业态的健身房需求：
#### 1.4.1 基础版
基础版保证业务闭环，适合小型工作室、个人教练等场景：
**包含模块：**
- ✅ 会员管理（完整）
- ✅ 会员卡管理（完整）
- ✅ 权益管理（完整）
- ✅ 团课预约（完整）
- ✅ 扫码签到（完整）
- ✅ 基础数据统计（完整）
- ✅ 系统管理（基础）
**限制：**
- 会员数量：最多500人
- 门店数量：单门店
- 团课容量：每节课最多20人
- 数据保留：保留30天
- 导出功能：基础导出
#### 1.4.2 订阅模块
订阅模块按需订阅，灵活扩展功能：
**业务扩展类模块：**
- 🔒 私教管理模块（¥299/月）
- 🔒 场地预约模块（¥199/月）
- 🔒 线上课程模块（¥399/月）
**体验升级类模块：**
- 🔒 人脸识别签到（¥499/月）
- 🔒 NFC签到（¥199/月）
- 🔒 智能储物柜（¥299/月）
**营销增长类模块：**
- 🔒 营销活动模块（¥399/月）
- 🔒 会员推荐奖励（¥299/月）
- 🔒 会员互动社区（¥499/月）
**数据智能类模块：**
- 🔒 高级数据分析（¥599/月）
- 🔒 智能报表（¥399/月）
- 🔒 AI运营建议（¥799/月）
**计费方式：**
- 月付：按月计费，每月自动续费
- 季付：一次性支付3个月，享受9折
- 半年付：一次性支付6个月，享受85折
- 年付：一次性支付12个月，享受8折 + 赠送1个月
**组合套餐：**
- 基础套餐：基础版 + 私教管理 + 营销活动（¥599/月）
- 高级套餐：基础版 + 全部业务扩展模块（¥799/月）
- 尊享套餐：基础版 + 全部模块（¥1999/月）
**试用政策：**
- 业务扩展类模块：14天试用
- 体验升级类模块：7天试用
- 营销增长类模块：14天试用
- 数据智能类模块：7天试用
### 1.3 目标用户
| 用户角色 | 用户画像 | 核心需求 |
|---------|---------|---------|
| **会员** | 25-45岁健身爱好者，追求健康生活方式 | 便捷预约、快速签到、查看个人信息、追踪健身进度 |
| **教练** | 专业健身教练，需要管理课程和学员 | 课程排期、学员签到、课时统计、评价管理 |
| **前台** | 门店前台人员，负责日常接待 | 会员接待、签到辅助、会员信息查询 |
| **店长** | 门店管理者，负责门店运营 | 单店全功能管理、数据查看、员工管理 |
| **运营管理员** | 平台运营人员，负责营销和数据分析 | 营销活动配置、数据分析、报表生成 |
| **财务专员** | 财务人员，负责账务管理 | 账单管理、财务报表、对账处理 |
| **超级管理员** | 平台最高权限管理者 | 全平台管理、系统配置、权限管理 |
---
## 二、功能需求
### 2.1 会员管理
#### 2.1.1 会员注册与信息管理
**用户故事**: 作为新用户，我可以通过手机号注册成为会员，以便开始使用系统
**功能描述**:
- 支持手机号+验证码注册
- 支持微信一键登录
- 会员信息完善（姓名、性别、生日、头像等）
- 会员信息查询和修改
- 会员状态管理（正常、冻结、注销）
**验收标准**:
- 注册流程在30秒内完成
- 验证码60秒内到达
- 支持手机号脱敏显示
- 敏感信息（手机号、身份证）加密存储
#### 2.1.2 会员卡管理
**用户故事**: 作为会员，我可以购买和管理会员卡，以便享受相应的权益
**功能描述**:
- 会员卡类型管理（时长卡、次卡、储值卡、等级卡）
- 会员卡购买流程
- 会员卡信息查询
- 会员卡激活/冻结/注销
- 会员卡转让（可选）
**验收标准**:
- 支持多种支付方式（微信、支付宝、银行卡）
- 会员卡购买成功后立即生效
- 支持会员卡有效期提醒
- 支持会员卡使用记录查询
#### 2.1.3 权益管理
**用户故事**: 作为会员，我可以查看我的权益余额和使用情况，以便合理安排健身计划
**功能描述**:
- 权益类型管理（时长、次数、储值、等级）
- 权益余额查询
- 权益使用记录
- 权益到期提醒
- 权益扣减和充值
**验收标准**:
- 权益余额实时更新
- 支持权益到期前3天提醒
- 权益扣减记录可追溯
- 支持权益转让（可选）
#### 2.1.4 等级管理
**用户故事**: 作为会员，我可以查看我的等级和积分，以便了解我的会员权益
**功能描述**:
- 会员等级体系定义
- 等级升级规则
- 等级权益配置
- 积分获取规则
- 积分兑换规则
**验收标准**:
- 等级升级自动触发
- 等级权益清晰展示
- 积分获取和使用记录可查询
- 支持等级权益差异化
### 2.2 预约管理
#### 2.2.1 团课预约
**用户故事**: 作为会员，我可以预约团课，以便参加我感兴趣的课程
**功能描述**:
- 团课列表展示（按时间、类型、教练筛选）
- 团课详情查看
- 团课预约
- 预约取消
- 预约提醒
**验收标准**:
- 支持提前7天预约
- 支持课程开始前2小时取消
- 预约成功后立即发送通知
- 支持预约冲突检测
#### 2.2.2 私教预约
**用户故事**: 作为会员，我可以预约私教课程，以便获得一对一指导
**功能描述**:
- 教练列表展示
- 教练详情查看
- 教练可预约时段查询
- 私教课程预约
- 预约取消
**验收标准**:
- 支持查看教练排班
- 支持选择预约时间段
- 支持预约备注
- 支持教练确认机制
#### 2.2.3 场地预约
**用户故事**: 作为会员，我可以预约场地，以便自主训练
**功能描述**:
- 场地列表展示
- 场地详情查看
- 场地可用时段查询
- 场地预约
- 预约取消
**验收标准**:
- 支持场地类型筛选
- 支持查看场地实时占用情况
- 支持预约时长限制
- 支持预约超时自动释放
#### 2.2.4 线上课程预约
**用户故事**: 作为会员，我可以预约线上课程，以便在家锻炼
**功能描述**:
- 线上课程列表展示
- 课程详情查看
- 课程预约
- 课程回放
- 课程评价
**验收标准**:
- 支持课程分类浏览
- 支持课程搜索
- 支持课程收藏
- 支持课程进度追踪
### 2.3 签到管理
#### 2.3.1 扫码签到
**用户故事**: 作为会员，我可以通过扫码快速签到，以便节省时间
**功能描述**:
- 生成会员二维码
- 扫码签到
- 签到验证
- 签到记录查询
**验收标准**:
- 二维码有效期5分钟
- 签到响应时间 ≤ 2秒
- 支持重复签到检测
- 签到成功后发送通知
#### 2.3.2 人脸识别签到
**用户故事**: 作为会员，我可以通过人脸识别自动签到，以便实现无感入场
**功能描述**:
- 人脸信息采集
- 人脸特征存储
- 人脸识别签到
- 签到记录查询
**验收标准**:
- 人脸识别准确率 ≥ 99%
- 识别响应时间 ≤ 1秒
- 支持人脸信息更新
- 支持多人同时识别
#### 2.3.3 NFC签到
**用户故事**: 作为会员，我可以通过NFC快速签到，以便便捷入场
**功能描述**:
- NFC卡绑定
- NFC签到
- 签到验证
- 签到记录查询
**验收标准**:
- 支持ISO 14443 Type A/B标准
- 签到响应时间 ≤ 1秒
- 支持NFC卡挂失
- 支持NFC卡解绑
#### 2.3.4 教练代签
**用户故事**: 作为教练，我可以为会员代签，以便处理特殊情况
**功能描述**:
- 教练登录验证
- 选择会员
- 代签操作
- 代签记录查询
**验收标准**:
- 支持按手机号搜索会员
- 支持代签备注
- 代签记录可追溯
- 支持代签权限控制
### 2.4 课程管理
#### 2.4.1 课程类型管理
**用户故事**: 作为运营管理员，我可以管理课程类型，以便分类展示课程
**功能描述**:
- 课程类型增删改查
- 课程类型排序
- 课程类型图标
- 课程类型描述
**验收标准**:
- 支持多级分类
- 支持课程类型启用/禁用
- 支持课程类型搜索
- 支持课程类型统计
#### 2.4.2 课程排期
**用户故事**: 作为教练，我可以管理课程排期，以便安排我的教学计划
**功能描述**:
- 课程排期创建
- 课程排期修改
- 课程排期删除
- 课程排期查询
**验收标准**:
- 支持按周/月视图查看
- 支持拖拽调整排期
- 支持排期冲突检测
- 支持排期复制
#### 2.4.3 场地管理
**用户故事**: 作为店长，我可以管理场地信息，以便合理分配资源
**功能描述**:
- 场地信息增删改查
- 场地容量设置
- 场地设备管理
- 场地状态管理
**验收标准**:
- 支持场地图片上传
- 支持场地设备清单
- 支持场地维护状态
- 支持场地使用统计
#### 2.4.4 价格配置
**用户故事**: 作为运营管理员，我可以配置课程价格，以便灵活定价
**功能描述**:
- 课程价格设置
- 会员卡价格设置
- 折扣规则配置
- 价格生效时间
**验收标准**:
- 支持多种价格类型
- 支持会员等级折扣
- 支持促销活动价格
- 支持价格历史查询
### 2.5 教练管理
#### 2.5.1 教练信息管理
**用户故事**: 作为店长，我可以管理教练信息，以便展示教练资料
**功能描述**:
- 教练信息增删改查
- 教练资质管理
- 教练照片上传
- 教练简介编辑
**验收标准**:
- 支持教练资质证书上传
- 支持教练擅长领域标注
- 支持教练评价展示
- 支持教练排序
#### 2.5.2 排班管理
**用户故事**: 作为教练，我可以管理我的排班，以便安排工作时间
**功能描述**:
- 排班创建
- 排班修改
- 排班删除
- 排班查询
**验收标准**:
- 支持按日/周/月视图
- 支持设置可预约时段
- 支持设置休息日
- 支持排班模板
#### 2.5.3 课时统计
**用户故事**: 作为教练，我可以查看我的课时统计，以便了解工作量
**功能描述**:
- 课时统计查询
- 课时明细查看
- 课时趋势分析
- 课时报表导出
**验收标准**:
- 支持按时间段统计
- 支持按课程类型统计
- 支持课时收入统计
- 支持数据可视化
#### 2.5.4 评价管理
**用户故事**: 作为会员，我可以对教练进行评价，以便提供反馈
**功能描述**:
- 评价提交
- 评价查看
- 评价回复
- 评价统计
**验收标准**:
- 支持星级评价
- 支持文字评价
- 支持评价图片
- 支持评价匿名
### 2.6 财务管理
#### 2.6.1 营收统计
**用户故事**: 作为财务专员，我可以查看营收统计，以便了解经营状况
**功能描述**:
- 营收数据统计
- 营收趋势分析
- 营收对比分析
- 营收报表导出
**验收标准**:
- 支持按日/周/月统计
- 支持按门店统计
- 支持按业务类型统计
- 支持数据可视化
#### 2.6.2 账单管理
**用户故事**: 作为会员，我可以查看我的账单，以便了解消费情况
**功能描述**:
- 账单列表查询
- 账单详情查看
- 账单筛选
- 账单导出
**验收标准**:
- 支持按时间筛选
- 支持按类型筛选
- 支持账单详情查看
- 支持账单PDF导出
#### 2.6.3 退款管理
**用户故事**: 作为运营管理员，我可以处理退款申请，以便提升用户满意度
**功能描述**:
- 退款申请查看
- 退款审核
- 退款处理
- 退款记录查询
**验收标准**:
- 支持退款原因分类
- 支持退款审核流程
- 支持退款状态跟踪
- 支持退款统计
#### 2.6.4 对账管理
**用户故事**: 作为财务专员，我可以进行对账操作，以便确保账务准确
**功能描述**:
- 对账数据导入
- 对账差异分析
- 对账确认
- 对账报表
**验收标准**:
- 支持多渠道对账
- 支持自动对账
- 支持差异标记
- 支持对账记录
### 2.7 计划中心
#### 2.7.1 训练计划
**用户故事**: 作为会员，我可以制定训练计划，以便科学健身
**功能描述**:
- 训练计划创建
- 训练计划编辑
- 训练计划执行
- 训练计划分享
**验收标准**:
- 支持模板选择
- 支持自定义计划
- 支持计划执行记录
- 支持计划进度追踪
#### 2.7.2 课程排期
**用户故事**: 作为运营管理员，我可以管理课程排期，以便合理安排课程
**功能描述**:
- 课程排期查看
- 课程排期调整
- 课程排期冲突检测
- 课程排期导出
**验收标准**:
- 支持多维度视图
- 支持批量调整
- 支持排期提醒
- 支持排期统计
#### 2.7.3 会员目标
**用户故事**: 作为会员，我可以设置健身目标，以便激励自己
**功能描述**:
- 目标设置
- 目标进度追踪
- 目标达成提醒
- 目标历史记录
**验收标准**:
- 支持多种目标类型
- 支持目标周期设置
- 支持目标可视化
- 支持目标分享
#### 2.7.4 教练排班
**用户故事**: 作为店长，我可以管理教练排班，以便合理安排人力
**功能描述**:
- 教练排班查看
- 教练排班调整
- 教练排班统计
- 教练排班导出
**验收标准**:
- 支持按门店查看
- 支持按教练查看
- 支持排班冲突检测
- 支持排班优化建议
### 2.8 数据分析
#### 2.8.1 会员分析
**用户故事**: 作为运营管理员，我可以查看会员分析，以便了解会员情况
**功能描述**:
- 会员增长分析
- 会员活跃度分析
- 会员留存分析
- 会员画像分析
**验收标准**:
- 支持多维度分析
- 支持趋势图表
- 支持数据钻取
- 支持报表导出
#### 2.8.2 课程分析
**用户故事**: 作为运营管理员，我可以查看课程分析，以便优化课程安排
**功能描述**:
- 课程预约分析
- 课程签到分析
- 课程评价分析
- 课程收益分析
**验收标准**:
- 支持按课程类型分析
- 支持按时间段分析
- 支持数据对比
- 支持优化建议
#### 2.8.3 财务分析
**用户故事**: 作为财务专员，我可以查看财务分析，以便了解财务状况
**功能描述**:
- 收入分析
- 支出分析
- 利润分析
- 现金流分析
**验收标准**:
- 支持多维度分析
- 支持预算对比
- 支持预测分析
- 支持风险预警
#### 2.8.4 运营分析
**用户故事**: 作为运营管理员，我可以查看运营分析，以便优化运营策略
**功能描述**:
- 整体运营指标
- 门店运营对比
- 员工绩效分析
- 营销效果分析
**验收标准**:
- 支持实时数据
- 支持自定义指标
- 支持数据预警
- 支持决策建议
### 2.9 系统管理
#### 2.9.1 租户管理
**用户故事**: 作为超级管理员，我可以管理租户，以便支持多租户架构
**功能描述**:
- 租户信息增删改查
- 租户配置管理
- 租户状态管理
- 租户数据隔离
**验收标准**:
- 支持租户独立配置
- 支持租户数据隔离
- 支持租户计费
- 支持租户监控
#### 2.9.2 门店管理
**用户故事**: 作为超级管理员，我可以管理门店，以便支持多门店运营
**功能描述**:
- 门店信息增删改查
- 门店配置管理
- 门店状态管理
- 门店数据统计
**验收标准**:
- 支持门店图片上传
- 支持门店地址定位
- 支持门店营业时间设置
- 支持门店数据隔离
#### 2.9.3 权限管理
**用户故事**: 作为超级管理员，我可以管理权限，以便控制用户访问
**功能描述**:
- 角色管理
- 权限管理
- 用户角色分配
- 权限审计
**验收标准**:
- 支持RBAC模型
- 支持权限继承
- 支持权限审计
- 支持权限测试
#### 2.9.4 系统配置
**用户故事**: 作为超级管理员，我可以配置系统参数，以便灵活调整系统行为
**功能描述**:
- 系统参数配置
- 业务规则配置
- 接口配置
- 日志配置
**验收标准**:
- 支持参数分类管理
- 支持参数生效时间
- 支持参数变更记录
- 支持参数导出
### 2.10 订阅管理
#### 2.10.1 订阅套餐管理
**用户故事**: 作为超级管理员，我可以管理订阅套餐，以便为租户提供灵活的订阅选择
**功能描述**:
- 订阅套餐增删改查
- 套餐类型管理（基础版、订阅模块、组合套餐）
- 套餐价格配置（月付、季付、半年付、年付）
- 套餐折扣配置
- 套餐试用天数配置
- 套餐状态管理（上架、下架）
**验收标准**:
- 支持套餐分类展示
- 支持套餐价格自动计算
- 支持套餐优惠展示
- 支持套餐试用配置
#### 2.10.2 租户订阅管理
**用户故事**: 作为超级管理员，我可以管理租户订阅，以便跟踪租户的订阅状态
**功能描述**:
- 租户订阅查询
- 订阅详情查看
- 订阅状态管理（正常、暂停、取消、过期）
- 订阅续费处理
- 订阅取消处理
- 订阅升级/降级处理
**验收标准**:
- 支持订阅状态实时更新
- 支持订阅自动续费
- 支持订阅变更记录
- 支持订阅提醒通知
#### 2.10.3 订阅模块管理
**用户故事**: 作为租户管理员，我可以管理订阅模块，以便按需启用/禁用功能
**功能描述**:
- 订阅模块查询
- 模块启用/禁用
- 模块配置管理
- 模块试用期管理
- 模块使用统计
**验收标准**:
- 支持模块即时启用/禁用
- 支持模块配置继承（门店继承租户配置）
- 支持模块试用期自动结束
- 支持模块使用量统计
#### 2.10.4 订阅计费管理
**用户故事**: 作为财务专员，我可以管理订阅计费，以便准确收取订阅费用
**功能描述**:
- 订阅账单生成
- 订阅账单查询
- 订阅支付处理
- 订阅退款处理
- 订阅对账管理
- 订阅发票管理
**验收标准**:
- 支持账单自动生成
- 支持多种支付方式
- 支持账单PDF导出
- 支持对账差异分析
#### 2.10.5 订阅配置管理
**用户故事**: 作为租户管理员，我可以管理订阅配置，以便灵活调整订阅策略
**功能描述**:
- 租户级模块配置
- 门店级模块配置
- 配置继承模式管理（继承、继承+覆盖、自定义）
- 配置变更历史查询
- 配置回滚功能
**验收标准**:
- 支持配置层级管理（租户→门店）
- 支持配置继承模式切换
- 支持配置变更追溯
- 支持配置版本回滚
---
## 三、非功能需求
### 3.1 性能需求
| 指标 | 要求 | 说明 |
|-------|------|------|
| 响应时间 | API响应时间 ≤ 500ms | 95%的请求 |
| 并发能力 | 支持1000 QPS | 热门课程抢课场景 |
| 数据库查询 | 单次查询 ≤ 100ms | 索引优化 |
| 页面加载 | 首屏加载 ≤ 2秒 | 3G网络环境 |
### 3.2 可用性需求
| 指标 | 要求 | 说明 |
|-------|------|------|
| 系统可用性 | SLA ≥ 99.9% | 年度停机时间 ≤ 8.76小时 |
| 故障恢复 | RTO ≤ 30分钟 | 恢复时间目标 |
| 数据备份 | 每日备份 | 保留30天 |
| 容灾能力 | 支持异地容灾 | RPO ≤ 1小时 |
### 3.3 安全性需求
| 指标 | 要求 | 说明 |
|-------|------|------|
| 数据加密 | 敏感数据加密存储 | AES-256 |
| 传输加密 | HTTPS加密传输 | TLS 1.2+ |
| 认证安全 | JWT Token认证 | 有效期2小时 |
| 权限控制 | RBAC权限模型 | 最小权限原则 |
| 审计日志 | 操作日志记录 | 保留90天 |
### 3.4 可扩展性需求
| 指标 | 要求 | 说明 |
|-------|------|------|
| 水平扩展 | 支持应用集群部署 | 无状态设计 |
| 数据库扩展 | 支持读写分离 | 主从复制 |
| 缓存扩展 | 支持Redis集群 | 分布式缓存 |
| 存储扩展 | 支持OSS对象存储 | 海量文件存储 |
### 3.5 可维护性需求
| 指标 | 要求 | 说明 |
|-------|------|------|
| 代码规范 | 遵循编码规范 | SonarQube检查 |
| 文档完善 | 代码注释率 ≥ 30% | 关键逻辑注释 |
| 日志规范 | 统一日志格式 | ELK日志分析 |
| 监控告警 | 实时监控 | Prometheus+Grafana |
---
## 四、用户故事与验收标准
### 4.1 会员端用户故事
| 用户故事 | 优先级 | 验收标准 |
|---------|-------|---------|
| 作为新用户，我可以通过手机号注册成为会员 | P0 | 注册流程在30秒内完成，验证码60秒内到达 |
| 作为会员，我可以购买会员卡 | P0 | 支持多种支付方式，购买成功后立即生效 |
| 作为会员，我可以预约团课 | P0 | 支持提前7天预约，预约成功后立即发送通知 |
| 作为会员，我可以通过扫码签到 | P0 | 二维码有效期5分钟，签到响应时间 ≤ 2秒 |
| 作为会员，我可以查看我的权益余额 | P1 | 权益余额实时更新，支持到期前3天提醒 |
| 作为会员，我可以设置健身目标 | P2 | 支持多种目标类型，支持目标可视化 |
### 4.2 管理端用户故事
| 用户故事 | 优先级 | 验收标准 |
|---------|-------|---------|
| 作为店长，我可以查看门店数据 | P0 | 支持实时数据查看，支持数据导出 |
| 作为教练，我可以管理课程排期 | P0 | 支持按周/月视图，支持拖拽调整 |
| 作为运营管理员，我可以配置课程价格 | P0 | 支持多种价格类型，支持会员等级折扣 |
| 作为财务专员，我可以查看营收统计 | P1 | 支持按日/周/月统计，支持数据可视化 |
| 作为超级管理员，我可以管理租户 | P1 | 支持租户独立配置，支持租户数据隔离 |
---
## 五、项目里程碑
| 阶段 | 时间 | 交付内容 |
|------|------|---------|
| 第一阶段 | 2026-03-01 ~ 2026-03-31 | 会员管理、预约管理、签到管理核心功能 |
| 第二阶段 | 2026-04-01 ~ 2026-04-30 | 课程管理、教练管理、财务管理 |
| 第三阶段 | 2026-05-01 ~ 2026-05-31 | 计划中心、数据分析、系统管理 |
| 第四阶段 | 2026-06-01 ~ 2026-06-30 | 系统优化、性能调优、上线部署 |
---
## 六、风险与应对
| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|---------|
| 需求变更频繁 | 高 | 中 | 采用敏捷开发，快速迭代 |
| 技术选型不当 | 高 | 低 | 充分调研，POC验证 |
| 性能不达标 | 中 | 中 | 提前性能测试，优化瓶颈 |
| 安全漏洞 | 高 | 低 | 安全审计，渗透测试 |
| 人员流动 | 中 | 中 | 知识沉淀，文档完善 |
---
## 七、成功标准
| 维度 | 指标 | 目标值 |
|------|------|-------|
| 功能完整性 | 需求覆盖率 | ≥ 95% |
| 用户体验 | 用户满意度 | ≥ 4.5/5.0 |
| 系统性能 | 响应时间 | ≤ 500ms |
| 系统稳定性 | SLA | ≥ 99.9% |
| 代码质量 | 代码覆盖率 | ≥ 80% |
---
## 八、参考文档
- 健身房行业数字化转型趋势报告
- 健身房管理系统竞品分析报告
- 用户体验设计规范
- 移动应用设计指南
- 数据安全与隐私保护规范
docs/customer/产品介绍手册.md
-960
View File
@@ -1,960 +0,0 @@
# 健身房管理系统产品介绍手册
> 版本: v1.0
> 日期: 2026-03-04
> 适用对象: 健身房管理者、投资人、合作伙伴
---
## 一、产品概述
### 1.1 产品背景
随着健身行业数字化转型的加速，传统健身房面临着会员管理效率低、预约流程繁琐、数据统计困难等痛点。我们的健身房管理系统旨在为健身行业提供一站式数字化解决方案，支持综合型健身俱乐部、精品工作室、连锁品牌等多种业态，实现：
- **会员端**：一站式查看个人所有信息（会员卡、权益、预约、签到、训练数据）
- **管理后台**：全维度数据整理与分析，支撑运营决策
- **便捷体验**：约课、签到流程简单高效
- **灵活配置**：支持业务流程模块化配置，满足不同规模客户需求
- **订阅模式**：基础版保证业务闭环，订阅模块提供增值服务
### 1.2 产品定位
我们的产品采用**基础版 + 订阅模块**的创新模式，满足不同规模和业态的健身房需求：
- **基础版**：保证业务闭环，适合小型工作室、个人教练等场景
- **订阅模块**：按需订阅，灵活组合，满足中大型健身房、连锁品牌等复杂场景需求
### 1.3 核心价值
| 价值维度 | 价值描述 | 客户收益 |
| ------------ | ------------------------------ | ----------------- |
| **提升效率** | 自动化会员管理、预约、签到流程 | 人工成本降低50% |
| **优化体验** | 会员端一站式服务，便捷预约签到 | 会员满意度提升30% |
| **数据驱动** | 全维度数据分析，支撑运营决策 | 运营效率提升40% |
| **灵活扩展** | 模块化订阅，按需付费 | IT投入成本降低60% |
| **快速部署** | 云端部署，即开即用 | 上线周期缩短70% |
---
## 二、适用场景
我们的产品适用于多种健身业态，满足不同规模客户的需求：
| 场景类型 | 说明 | 推荐版本 | 典型客户 |
| -------------------- | ---------------------------------------------- | ----------------------- | ------------------------ |
| **精品工作室** | 专注某一类课程，会员规模 100-300 人 | 基础版 | 瑜伽工作室、普拉提工作室 |
| **综合型健身俱乐部** | 多种团课 + 私教 + 器械区，会员规模 500-2000 人 | 基础版 + 体验升级类订阅 | 社区健身房、中型俱乐部 |
| **连锁品牌** | 多门店运营，跨店约课，统一数据管理 | 基础版 + 业务扩展类订阅 | 区域连锁品牌 |
| **大型连锁** | 10+门店，需要精细化运营和数据分析 | 基础版 + 全部订阅模块 | 全国连锁品牌 |
---
## 三、产品版本
### 3.1 基础版
基础版保证业务闭环，适合小型工作室、个人教练等场景，提供完整的会员管理、预约、签到等核心功能。
#### 定价
**标准定价**：¥299/月
| 订阅周期 | 月费 | 折扣 | 说明 |
| ---------- | --------- | -------- | ------------------ |
| **月付** | ¥299/月 | 标准价格 | 灵活选择，随时调整 |
| **季付** | ¥269/月 | 9折优惠 | 适合短期试用 |
| **半年付** | ¥254/月 | 85折优惠 | 平衡成本与灵活性 |
| **年付** | ¥239/月 | 8折优惠 | 最大优惠，长期合作 |
#### 订阅周期
| 订阅周期 | 折扣 | 说明 |
| ---------- | -------- | ------------------ |
| **月付** | 标准价格 | 灵活选择，随时调整 |
| **季付** | 9折优惠 | 适合短期试用 |
| **半年付** | 85折优惠 | 平衡成本与灵活性 |
| **年付** | 8折优惠 | 最大优惠，长期合作 |
**试用政策**：
- 提供14天免费试用
- 试用期内可随时取消
- 试用到期后自动续费
#### 包含模块
| 模块名称 | 功能描述 | 核心价值 |
| ---------------- | -------------------------------------- | ------------------ |
| **会员管理** | 会员注册、信息管理、会员卡管理 | 建立完整的会员档案 |
| **会员卡管理** | 时长卡、次卡、储值卡管理 | 灵活的会员卡体系 |
| **权益管理** | 时长权益、次数权益、储值权益、等级权益 | 多样化的权益体系 |
| **团课预约** | 团课列表、预约、取消、提醒 | 提升课程预约效率 |
| **扫码签到** | 会员扫码签到、签到记录管理 | 快速签到体验 |
| **基础数据统计** | 会员统计、预约统计、签到统计 | 数据可视化展示 |
| **系统管理** | 用户管理、角色权限管理 | 安全的权限控制 |
#### 技术特点
- **云端部署**：无需本地服务器，即开即用
- **多端支持**：会员小程序、教练端App、管理后台PC
- **高可用性**：系统可用性 ≥ 99.9%
- **数据安全**：数据加密存储，定期备份
#### 功能限制
- 单门店运营
- 不支持营销精算模型
- 不支持自定义促销活动预测
- 不支持高级数据分析
### 3.2 付费订阅版
付费订阅版在基础版基础上，提供丰富的增值功能，按需订阅，满足中大型健身房、连锁品牌等复杂场景需求。
---
## 四、订阅模块体系
订阅模块分为四大类别，客户可根据需求灵活订阅：
### 4.1 业务扩展类
适合需要扩展业务范围的健身房。
| 模块名称 | 功能描述 | 适用场景 | 核心价值 |
| -------------- | -------------------------------------- | ------------------ | ------------------ |
| **多门店管理** | 支持多门店运营、跨店约课、统一数据管理 | 连锁品牌 | 统一管理，数据互通 |
| **私教管理** | 私教课程管理、教练排班、学员跟进 | 有私教业务的健身房 | 提升私教管理效率 |
| **器械预约** | 器械时段预约、器械使用统计 | 器械资源紧张的场景 | 优化器械使用率 |
### 4.2 体验升级类
适合希望提升会员体验的健身房。
| 模块名称 | 功能描述 | 适用场景 | 核心价值 |
| ------------- | ------------------------------ | ------------ | ------------ |
| **人脸识别** | 刷脸签到、无感通行、人脸考勤 | 高端健身房 | 提升签到体验 |
| **NFC一卡通** | NFC手环/卡片签到、储物柜联动 | 传统健身房 | 便捷签到体验 |
| **在线课程** | 线上课程预约、视频点播、直播课 | 混合运营模式 | 拓展线上业务 |
### 4.3 营销增长类
适合需要提升会员增长和留存的健身房。
| 模块名称 | 功能描述 | 适用场景 | 核心价值 |
| ---------------- | ------------------------------------------ | ------------------ | ---------------- |
| **会员营销** | 会员标签、精准营销、自动化营销 | 需要精细化运营 | 提升营销效率 |
| **促销活动** | 优惠券、拼团、秒杀、限时折扣 | 需要促销活动 | 提升会员活跃度 |
| **推荐奖励** | 邀请奖励、裂变营销、会员推荐 | 需要拉新裂变 | 降低获客成本 |
| **智能获客工具** | 节后健身潮获客、私域流量获客、推荐裂变获客 | 需要低成本高效率获客 | 获客成本降低50% |
### 4.4 数据智能类
适合需要数据驱动决策和完整会员健康档案的健身房。
| 模块名称 | 功能描述 | 适用场景 | 核心价值 |
| ---------------------- | ------------------------------------------ | -------------------- | ---------------- |
| **营销精算模型** | 基于历史数据的促销策略预测 | 需要数据驱动决策 | 优化营销ROI |
| **自定义促销预测** | 多维度自定义促销活动效果预测 | 需要灵活促销策略 | 精准预测活动效果 |
| **高级数据分析** | 会员行为分析、流失预警、收入预测 | 需要深度数据分析 | 数据驱动运营决策 |
| **智能体测数据联动** | 设备适配层架构，支持主流设备和标准API接口 | 需要完整会员健康档案 | 形成完整健康档案 |
---
## 五、计费方式
我们提供灵活的计费方式，满足不同客户的预算需求。
### 5.1 付费模式选择
我们提供两种付费模式，客户可根据自身情况选择：
#### 模式A：固定月费模式
**适合客户**：交易量小、预算稳定的客户
**计费方式**：
- 基础版：¥299/月
- 订阅模块：按模块定价（¥199-¥499/月）
- 订阅周期：月付/季付/半年付/年付（享受相应折扣）
**优势**：
- 成本可预测，便于预算管理
- 无交易量限制
- 适合业务稳定的客户
#### 模式B：成功费模式
**适合客户**：交易量大、希望按量付费的客户
**计费方式**：
- 基础版：交易额的1%-1.5%
- 订阅模块：交易额的0.3%-0.8%
- 交易额包括：会员卡充值、会员卡消费、私教课程购买、促销活动交易等
**优势**：
- 完全按使用量付费，降低门槛
- 系统收益与客户业务增长绑定
- 适合交易量大的客户
**切换机制**：
- 客户可随时在两种模式间切换
- 切换后下个计费周期生效
- 提供计算器帮助客户对比两种模式成本
## 5.1 付费模式选择（续）
#### 模式 B：成功费模式（详细规则）
**适合客户**：交易量大、希望按量付费的客户
**计费基础**：
- **交易额定义**：会员卡充值、会员卡消费、私教课程购买、促销活动交易等所有通过系统完成的交易
- **交易额计算**：按自然月累计，不含退款金额
- **净额计算**：交易额 - 退款金额 = 计费交易额
**阶梯费率**：
| 月交易额区间（元） | 基础版费率 | 订阅模块费率 | 综合费率 |
|------------------|-----------|-------------|---------|
| 0 - 50,000 | 1.5% | 0.8% | 2.3% |
| 50,001 - 100,000 | 1.3% | 0.7% | 2.0% |
| 100,001 - 200,000| 1.2% | 0.6% | 1.8% |
| 200,001 - 500,000| 1.1% | 0.5% | 1.6% |
| 500,001 - 1,000,000| 1.0% | 0.4% | 1.4% |
| 1,000,001 以上 | 0.9% | 0.3% | 1.2% |
**计算示例**：
**示例 1：月交易额 8 万元**
- 基础版费用：80,000 × 1.3% = ¥1,040
- 订阅模块费用：80,000 × 0.7% = ¥560
- 总费用：¥1,040 + ¥560 = **¥1,600/月**
**示例 2：月交易额 30 万元**
- 基础版费用：300,000 × 1.1% = ¥3,300
- 订阅模块费用：300,000 × 0.5% = ¥1,500
- 总费用：¥3,300 + ¥1,500 = **¥4,800/月**
**示例 3：月交易额 150 万元**
- 基础版费用：1,500,000 × 0.9% = ¥13,500
- 订阅模块费用：1,500,000 × 0.3% = ¥4,500
- 总费用：¥13,500 + ¥4,500 = **¥18,000/月**
**最低消费保障**：
- 基础版：最低消费 ¥299/月（若按费率计算低于此金额，则按此金额收取）
- 订阅模块：每个订阅模块最低消费 ¥99/月
**示例 4：月交易额 50 万元，订阅 2 个模块**
- 成功费模式：
- 基础版：500,000 × 1.1% = ¥5,500
- 订阅模块：500,000 × 0.5% × 2 = ¥5,000
- 总计：¥10,500/月
- 固定月费模式：
- 基础版：¥299
- 订阅模块：¥199 × 2 = ¥398
- 总计：¥697/月
- **建议**：订阅模块较少时，固定月费模式更划算
**示例 5：月交易额 20 万元，订阅全部 10 个模块**
- 成功费模式：
- 基础版：200,000 × 1.2% = ¥2,400
- 订阅模块：200,000 × 0.6% = ¥1,200
- 总计：¥3,600/月
- 固定月费模式：
- 基础版：¥299
- 订阅模块：¥199 × 10 = ¥1,990
- 总计：¥2,289/月
- **建议**：订阅模块多且交易量中等时，固定月费模式更划算
- 目的：保障基础运营成本
**退款处理**：
- 退款当月：从当月交易额中扣除退款金额
- 跨月退款：从下月交易额中扣除退款金额
- 退款记录：提供详细的退款记录报表
**结算周期**：
- 结算时间：次月 5 日前完成上月结算
- 对账单：次月 1 日前发送上月对账单
- 支付方式：银行转账、支付宝、微信支付
- 发票：提供增值税专用发票或普通发票
**数据透明**：
- 实时数据：管理后台实时查看交易额数据
- 日报表：每日上午 10 点前发送前一日交易报表
- 月报表：次月 1 日前发送上月完整交易报表
- 审计权限：客户可申请第三方审计交易数据
**费率调整机制**：
- 年度调整：每年 1 月根据市场情况和运营成本调整费率
- 调整通知：提前 30 天书面通知客户
- 协商机制：大客户可申请个性化费率方案
- 上限保护：年费率涨幅不超过 10%
**优势**：
- 完全按使用量付费，降低初始投入门槛
- 系统收益与客户业务增长绑定，共赢发展
- 适合交易量大、业务增长快的客户
- 费率随交易额增长递减，规模效应明显
**切换机制**：
- 客户可随时在固定月费模式和成功费模式间切换
- 切换申请：提前 7 天提交切换申请
- 生效时间：下个计费周期（次月 1 日）生效
- 切换限制：每个自然年最多切换 2 次
- 提供计算器：帮助客户对比两种模式成本，选择最优方案
**适用客户画像**：
- 月交易额 ≥ 10 万元
- 业务处于快速增长期
- 希望降低前期投入成本
- 对现金流管理要求高
**不适用场景**：
- 月交易额 < 5 万元（固定月费模式更划算）
- 业务波动大，交易额不稳定
- 预算需要严格可控
**成本对比分析**：
| 月交易额 | 固定月费模式 | 成功费模式 | 更优选择 |
|---------|------------|-----------|---------|
| 5 万元 | ¥897 | ¥1,150 | 固定月费 |
| 10 万元 | ¥897 | ¥2,000 | 固定月费 |
| 20 万元 | ¥897 | ¥3,600 | 固定月费 |
| 50 万元 | ¥897 | ¥8,000 | 固定月费 |
| 100 万元 | ¥897 | ¥14,000 | 固定月费 |
_注：固定月费模式以基础版 +2 个订阅模块（年付 8 折）为例：¥299 + (¥299+¥299)×0.8 = ¥897/月_
**成功费模式计算器**：
我们提供在线计算器，帮助客户快速计算成功费模式成本：
```
输入：月交易额
计算：
- 基础版费用 = 月交易额 × 对应阶梯费率
- 订阅模块费用 = 月交易额 × 对应阶梯费率 × 订阅模块数量
- 总费用 = 基础版费用 + 订阅模块费用
输出：
- 详细费用明细
- 与固定月费模式对比
- 推荐付费模式
```
**风险控制**：
- 交易异常监控：系统自动监控异常交易行为
- 防刷单机制：识别并阻止虚假交易
- 违规处理：发现作弊行为，有权终止服务并追究责任
- 争议解决：提供争议申诉渠道，7 个工作日内处理
**合同条款**：
- 合同期限：建议签订 1 年以上合同
- 费率锁定：合同期内费率不变
- 续约优惠：合同到期后续约，可享受忠诚折扣
- 终止条款：提前 30 天书面通知可终止合同
### 5.2 订阅周期优惠
| 订阅周期 | 折扣力度 | 说明 |
| ---------- | -------- | ------------------ |
| **月付** | 标准价格 | 灵活选择，随时调整 |
| **季付** | 9折优惠 | 适合短期试用 |
| **半年付** | 85折优惠 | 平衡成本与灵活性 |
| **年付** | 8折优惠 | 最大优惠，长期合作 |
### 5.3 行业类型推荐套餐
我们根据不同行业类型的特点，预设推荐套餐，同时采用动态折扣（模块越多，折扣越大）。
#### 行业类型
**1. 瑜伽工作室**
- 特点：会员规模小（100-300人）、课程单一、预算有限
- 核心需求：会员管理、团课预约、基础统计
- 推荐模块：在线课程、会员营销
**2. 综合健身房**
- 特点：会员规模中等（500-2000人）、业务多样、需要私教
- 核心需求：会员管理、团课预约、私教管理、基础统计
- 推荐模块：私教管理、器械预约、人脸识别、会员营销
**3. 连锁品牌**
- 特点：会员规模大（2000+人）、多门店、需要精细化运营
- 核心需求：全功能 + 多门店管理 + 数据分析
- 推荐模块：多门店管理、全部营销模块、全部数据智能模块
#### 动态折扣规则
| 订阅模块数量 | 折扣力度 |
| ------------ | -------- |
| 1个模块 | 9.5折 |
| 2个模块 | 9折 |
| 3个模块 | 8.5折 |
| 4-5个模块 | 8折 |
| 6-8个模块 | 7.5折 |
| 9-11个模块 | 7折 |
| 全部12个模块 | 6.5折 |
#### 推荐套餐
**🧘 瑜伽工作室推荐套餐**
_入门套餐_（适合小型工作室）
- 包含：基础版 + 在线课程
- 模块数量：1个
- 折扣：9.5折
- 月费：¥299 + ¥299 × 0.95 = **¥583.05**
_成长套餐_（适合中型工作室）
- 包含：基础版 + 在线课程 + 会员营销
- 模块数量：2个
- 折扣：9折
- 月费：¥299 + (¥299 + ¥299) × 0.9 = **¥837.20**
**🏋️ 综合健身房推荐套餐**
_标准套餐_（适合小型健身房）
- 包含：基础版 + 私教管理 + 器械预约
- 模块数量：2个
- 折扣：9折
- 月费：¥299 + (¥199 + ¥199) × 0.9 = **¥657.20**
_专业套餐_（适合中型健身房）
- 包含：基础版 + 私教管理 + 器械预约 + 人脸识别 + 会员营销
- 模块数量：4个
- 折扣：8折
- 月费：¥299 + (¥199 + ¥199 + ¥399 + ¥299) × 0.8 = **¥1174.20**
**🏢 连锁品牌推荐套餐**
_企业套餐_（适合区域连锁）
- 包含：基础版 + 多门店管理 + 全部营销模块（3个）
- 模块数量：4个
- 折扣：8折
- 月费：¥299 + (¥499 + ¥299 + ¥299 + ¥299) × 0.8 = **¥1415.80**
_旗舰套餐_（适合全国连锁）
- 包含：基础版 + 全部订阅模块（12个）
- 模块数量：12个
- 折扣：6.5折
- 月费：¥299 + ¥4388 × 0.65 = **¥3151.20**
### 5.4 客户选择流程
1. **选择行业类型**：瑜伽工作室 / 综合健身房 / 连锁品牌
2. **查看推荐套餐**：系统根据行业类型推荐2-3个套餐
3. **自定义或选择**：客户可以选择推荐套餐，或自定义模块组合
4. **选择计费模式**：固定月费 / 成功费模式
5. **系统自动计算**：根据模块数量和计费模式计算月费
### 5.5 智能动态推荐
我们提供智能动态推荐系统，根据您的业务发展自动调整推荐套餐。
#### 5.5.1 初始推荐
**推荐维度**：
- 行业类型（瑜伽工作室 / 综合健身房 / 连锁品牌）
- 员工数量（教练、前台、管理人员总数）
- 会员数量（当前会员总数）
- 门店数量（门店总数）
- 月交易额（月度交易总额）
**推荐算法**：
- 收集客户规模信息
- 计算规模得分（0-100分）
- 匹配推荐套餐
- 提供上下两个套餐供选择
#### 5.5.2 动态调整
**触发时机**：
- 会员数量增长超过阈值（如增长50%）
- 月交易额增长超过阈值（如增长30%）
- 门店数量增加（如新增门店）
- 员工数量增加（如新增员工）
- 季度业务回顾（每季度自动评估）
**调整策略**：
- 升级推荐：业务增长后，推荐更高级的套餐
- 降级推荐：业务萎缩后，推荐更经济的套餐
- 模块调整：根据业务变化，推荐增减订阅模块
- 个性化推荐：基于历史行为和行业趋势调整推荐
#### 5.5.3 推荐通知
**通知方式**：
- 系统通知：在管理后台显示推荐提示
- 邮件通知：发送推荐建议到客户邮箱
- 短信通知：重要推荐变更发送短信提醒
- 客服跟进：客服主动联系客户，解释推荐理由
**通知内容**：
- 当前套餐分析：当前套餐的使用情况
- 业务变化分析：业务指标的变化情况
- 推荐理由：为什么推荐新套餐
- 对比分析：新旧套餐的对比
- 预期收益：切换到新套餐的预期收益
#### 5.5.4 推荐示例
**场景1：会员数量增长**
**初始状态**：
- 行业类型：综合健身房
- 员工数量：8人
- 会员数量：300人
- 当前套餐：标准套餐（¥657.20/月）
**业务变化**：
- 会员数量增长到600人（增长100%）
**动态推荐**：
- 推荐套餐：专业套餐（¥1174.20/月）
- 推荐理由：会员数量增长，需要更多营销和数据分析功能
- 预期收益：提升会员留存率，增加营销效率
---
**场景2：门店数量增加**
**初始状态**：
- 行业类型：连锁品牌
- 门店数量：2家
- 会员数量：800人
- 当前套餐：企业套餐（¥1415.80/月）
**业务变化**：
- 门店数量增加到5家（增长150%）
**动态推荐**：
- 推荐套餐：专业套餐（¥1174.20/月）
- 推荐理由：门店数量增加，需要更多数据智能功能
- 预期收益：提升跨店运营效率，增强数据分析能力
---
**场景3：月交易额增长**
**初始状态**：
- 行业类型：瑜伽工作室
- 员工数量：3人
- 会员数量：80人
- 月交易额：¥50000
- 当前套餐：入门套餐（¥583.05/月）
**业务变化**：
- 月交易额增长到¥125000（增长150%）
**动态推荐**：
- 推荐套餐：成长套餐（¥837.20/月）
- 推荐理由：交易额增长，需要更多营销功能
- 预期收益：提升营销效率，增加会员活跃度
---
### 5.6 试用政策
- **免费试用**：所有订阅模块提供14天免费试用
- **随时取消**：试用期内可随时取消，无需任何费用
- **自动续费**：试用到期后自动续费，可提前取消
---
## 六、客户收益分析
### 6.1 成本节约
| 成本类型 | 传统方式 | 使用我们的系统 | 节约比例 |
| ------------ | ---------------------------- | -------------------- | -------- |
| **人工成本** | 需要专人管理会员、预约、签到 | 自动化处理，减少人工 | 50% |
| **IT投入** | 自建系统，服务器、维护成本高 | 云端部署，按需付费 | 60% |
| **营销成本** | 传统营销，效果难以评估 | 精准营销，数据驱动 | 40% |
| **运营成本** | 手工统计，效率低下 | 自动统计，实时分析 | 30% |
### 6.2 效率提升
| 业务场景 | 传统方式 | 使用我们的系统 | 效率提升 |
| ------------ | -------------------- | ------------------ | -------- |
| **会员注册** | 纸质登记，信息录入慢 | 在线注册，自动建档 | 70% |
| **课程预约** | 电话预约，人工确认 | 在线预约，自动确认 | 80% |
| **签到管理** | 人工核对，耗时耗力 | 扫码签到，秒级完成 | 90% |
| **数据统计** | 手工统计，周期长 | 自动统计，实时查看 | 95% |
### 6.3 收入增长
| 增长维度 | 增长方式 | 预估增长 |
| ------------ | -------------------- | -------- |
| **会员留存** | 精准营销、个性化服务 | 提升20% |
| **会员增长** | 裂变营销、推荐奖励 | 提升30% |
| **课程收入** | 优化排课、提升预约率 | 提升15% |
| **私教收入** | 私教管理、学员跟进 | 提升25% |
---
## 七、成功案例（示例）
### 7.1 小型工作室案例
**客户背景**：某瑜伽工作室，3名教练，200名会员
**使用方案**：基础版
**实施效果**：
- 会员预约效率提升80%
- 教练排课时间节省60%
- 会员满意度提升25%
- 月度运营成本降低40%
### 7.2 连锁品牌案例
**客户背景**：某区域连锁健身品牌，5家门店，3000名会员
**使用方案**：基础版 + 多门店管理 + 会员营销 + 高级数据分析
**实施效果**：
- 统一管理，数据互通
- 会员留存率提升22%
- 营销ROI提升35%
- 跨店预约率提升40%
### 7.3 大型俱乐部案例
**客户背景**：某综合型健身俱乐部，20名教练，1500名会员
**使用方案**：基础版 + 私教管理 + 人脸识别 + 营销精算模型
**实施效果**：
- 私教收入增长28%
- 签到体验大幅提升
- 营销活动ROI提升40%
- 会员活跃度提升30%
---
## 八、服务保障
### 8.1 技术保障
- **系统可用性**：≥ 99.9%
- **数据备份**：每日自动备份
- **安全防护**：数据加密、访问控制
- **技术支持**：7×24小时在线支持
### 8.2 服务承诺
- **快速部署**：签约后3个工作日内完成部署
- **培训支持**：提供系统使用培训
- **持续优化**：定期系统升级优化
- **专属客服**：一对一客户服务
### 8.3 退款政策
- **试用期内**：随时退款，全额退还
- **正式使用**：按比例退还剩余费用
- **无理由退款**：7天内无理由退款
---
## 九、联系我们
### 9.1 商务咨询
- **电话**：400-XXX-XXXX
- **邮箱**：sales@example.com
- **微信**：扫描二维码添加商务顾问
### 9.2 技术支持
- **电话**：400-XXX-XXXX
- **邮箱**：support@example.com
- **工单系统**：在线提交工单
### 9.3 公司地址
- **总部**：北京市朝阳区XXX大厦
- **研发中心**：上海市浦东新区XXX园区
---
## 附录：常见问题
### Q1: 基础版是否需要额外付费？
**A**: 基础版采用订阅制，月费¥299，包含所有基础功能，无需额外付费。
### Q2: 订阅模块是否可以随时取消？
**A**: 可以。订阅模块支持随时取消，取消后该模块功能将无法使用，但已产生的费用不予退还。
### Q3: 是否支持数据导出？
**A**: 支持。所有数据均可导出为Excel或CSV格式，方便客户进行二次分析。
### Q4: 是否支持自定义品牌？
**A**: 支持。付费订阅版支持自定义品牌Logo、颜色、域名等，打造专属品牌形象。
### Q5: 是否支持多语言？
**A**: 目前支持中文和英文，后续将支持更多语言。
### Q6: 数据安全如何保障？
**A**: 我们采用银行级数据加密技术，数据存储在阿里云/腾讯云，定期备份，确保数据安全。
### Q7: 是否提供API接口？
**A**: 付费订阅版提供完整的API接口，支持与第三方系统对接。
### Q8: 是否支持私有化部署？
**A**: 企业套餐支持私有化部署，满足数据安全要求高的客户需求。
---
## 十、未来优化计划
我们持续优化产品和服务，为您提供更好的体验。以下是我们的优化计划：
### 10.1 短期优化（1-3个月）
#### 1. 首月特惠
**方案描述**：新客户首月5折优惠
**适用对象**：首次注册的新客户
**优惠力度**：
- 基础版：¥149.5/月（原价¥299）
- 订阅模块：按原价5折计算
**限制条件**：
- 首月必须选择固定月费模式
- 同一手机号/身份证号3个月内只能享受一次
**预期效果**：
- 降低获客成本50%
- 转化率提升20-30%
- 快速扩大用户基数
---
#### 2. 模块独立试用
**方案描述**：每个订阅模块独立14天试用
**试用规则**：
- 每个模块独立14天试用
- 可同时试用多个模块，每个模块独立计时
- 模块A试用后转正，模块B仍可继续试用
**预期效果**：
- 降低试用门槛
- 模块订阅率提升15-20%
- 客单价提升10-15%
---
#### 3. 在线计算器
**方案描述**：提供在线计费计算器，帮助客户对比两种付费模式
**计算功能**：
- 固定月费模式：根据选择的模块数量和订阅周期计算月费
- 成功费模式：根据预估月交易额计算月费
- 模式对比：自动计算两种模式的成本，推荐更优模式
**输入参数**：
- 行业类型（瑜伽工作室/综合健身房/连锁品牌）
- 预估月交易额（成功费模式）
- 选择模块数量
- 订阅周期（月付/季付/半年付/年付）
**预期效果**：
- 决策时间缩短83%（从30分钟缩短到5分钟）
- 转化率提升10-15%
- 客户满意度提升
---
### 10.2 中期优化（3-6个月）
#### 1. 忠诚折扣
**方案描述**：连续订阅3年以上，额外享受95折优惠
**适用条件**：
- 连续订阅满36个月（3年）
- 在当前折扣基础上额外95折
- 适用范围：基础版 + 所有订阅模块
**重置条件**：中断订阅后，忠诚期重新计算
**预期效果**：
- 留存率提升15-20%
- 客单价提升10-15%
- 收入稳定性提升
---
#### 2. 推荐奖励
**方案描述**：老客户推荐新客户，双方获得优惠
**推荐人奖励**：
- 推荐成功：获得1个月免费订阅或等值优惠券
- 推荐数量：无上限，鼓励持续推荐
**被推荐人奖励**：
- 新客户注册：首月5折优惠（可与首月特惠叠加）
- 必须输入推荐码才能享受优惠
**奖励发放**：推荐成功后7天内发放
**预期效果**：
- 获客成本降低50-70%
- 获客速度提升30-40%
- 客户粘性提升20-30%
---
#### 3. 行业扩展
**方案描述**：增加普拉提工作室、拳击馆、游泳馆等行业类型
**新增行业类型**：
**🧘 普拉提工作室**
- 特点：会员规模小（50-200人）、课程单一、预算有限
- 核心需求：会员管理、团课预约、基础统计
- 推荐模块：在线课程、会员营销
- 推荐套餐：
- 入门套餐：基础版 + 在线课程（¥583.05/月）
- 成长套餐：基础版 + 在线课程 + 会员营销（¥837.20/月）
**🥊 拳击馆**
- 特点：会员规模小（100-300人）、课程多样、需要私教
- 核心需求：会员管理、团课预约、私教管理
- 推荐模块：私教管理、器械预约、会员营销
- 推荐套餐：
- 标准套餐：基础版 + 私教管理 + 器械预约（¥657.20/月）
- 专业套餐：基础版 + 私教管理 + 器械预约 + 会员营销（¥956.20/月）
**🏊 游泳馆**
- 特点：会员规模中等（200-500人）、课程单一、时段管理复杂
- 核心需求：会员管理、团课预约、时段管理
- 推荐模块：器械预约、会员营销
- 推荐套餐：
- 标准套餐：基础版 + 器械预约（¥498.20/月）
- 成长套餐：基础版 + 器械预约 + 会员营销（¥757.20/月）
**预期效果**：
- 市场覆盖扩大50%
- 转化率提升15-20%
- 客单价提升5-10%
---
### 10.3 优化优先级
| 优化项 | 实施周期 | 预期效果 | 优先级 |
| ------------------------ | -------- | -------------------------- | ------ |
| 在线计算器 | 1个月 | 决策时间-80%，转化率+12% | 🔴 高 |
| 首月特惠 | 1个月 | 转化率+25%，获客成本-50% | 🔴 高 |
| 模块独立试用 | 2-3个月 | 模块渗透率+18%，客单价+12% | 🟡 中 |
| 行业扩展（普拉提、拳击） | 2-3个月 | 市场覆盖+30%，转化率+17% | 🟡 中 |
| 推荐奖励 | 4-6个月 | 获客成本-60%，转化率+35% | 🟡 中 |
| 行业扩展（游泳馆） | 4-6个月 | 市场覆盖+20%，转化率+15% | 🟡 中 |
| 忠诚折扣 | 7-12个月 | 留存率+18%，客单价+12% | 🟢 低 |
**综合预期**：
- 转化率提升：30-40%
- 获客成本降低：50-60%
- 留存率提升：15-20%
- 客单价提升：10-15%
---
**感谢您选择我们的产品！**
我们致力于为健身行业提供最优质的数字化解决方案，助力您的业务增长。如有任何疑问，请随时联系我们。
---
_文档版本: v1.0_
_最后更新: 2026-03-04_
docs/design/.DS_Store
Vendored
BIN
View File
Binary file not shown.
docs/design/EVAL-技术架构评估总结.md
-609
View File
@@ -1,609 +0,0 @@
# 技术架构评估总结报告
> 文档编号: GYM-EVAL-TECH-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ------------------ |
| v1.0 | 2026-03-04 | 张翔 | 创建技术架构评估总结 |
---
## 参考文档
- 《健身房管理系统技术架构设计文档》 GYM-HLD-TECH-001
- 《健身房管理系统响应式编程规范文档》 GYM-STD-REACTIVE-001
- 《健身房管理系统部署运维文档》 GYM-OPS-DEPLOY-001
---
## 一、评估概述
### 1.1 评估背景
健身房管理系统是一个面向健身房的综合管理平台，支持会员管理、预约管理、签到管理、权益管理、订阅管理、营销管理等核心功能。系统需要支持高并发、低延迟、高可用、易扩展等特性。
### 1.2 评估目标
1. 评估技术架构的可行性和合理性
2. 评估技术栈的成熟度和适用性
3. 评估开发成本和运维成本
4. 评估风险和缓解策略
5. 提供技术选型建议
### 1.3 评估方法
1. 文档分析：分析现有设计文档
2. 技术调研：调研相关技术栈
3. 性能评估：评估性能指标和预期
4. 成本分析：分析开发成本和运维成本
5. 风险评估：识别风险和制定缓解策略
---
## 二、技术选型评估
### 2.1 架构选型
#### 2.1.1 单体应用 vs 微服务
| 评估维度 | 单体应用 | 微服务 | 评估结果 |
|---------|---------|--------|---------|
| **开发复杂度** | 低 | 高 | ✅ 单体应用优势明显 |
| **部署复杂度** | 低 | 高 | ✅ 单体应用优势明显 |
| **事务管理** | 简单 | 复杂 | ✅ 单体应用优势明显 |
| **调试难度** | 低 | 高 | ✅ 单体应用优势明显 |
| **性能开销** | 低 | 高 | ✅ 单体应用优势明显 |
| **初期成本** | 低 | 高 | ✅ 单体应用优势明显 |
| **扩展性** | 垂直扩展 | 水平扩展 | ⚠️ 微服务优势明显 |
| **故障隔离** | 差 | 好 | ⚠️ 微服务优势明显 |
**评估结论**：✅ **推荐单体应用**
**理由**：
1. 适合当前规模（1000 并发用户）
2. 适合团队规模（3-5 人）
3. 开发效率高，学习成本低
4. 部署简单，运维成本低
5. 性能优秀，无服务间调用开销
**未来演进**：
- 阶段一：单体应用（当前）
- 阶段二：垂直扩展（6-12 个月）
- 阶段三：水平扩展（12-24 个月）
- 阶段四：微服务（24-36 个月）
#### 2.1.2 响应式编程 vs 传统编程
| 评估维度 | Spring MVC + JPA | WebFlux + R2DBC | 评估结果 |
|---------|-----------------|-----------------|---------|
| **并发能力** | 200-500 | 2000-5000 | ✅ WebFlux + R2DBC 优势明显 |
| **API 响应时间 (P99)** | 500-800ms | 200-400ms | ✅ WebFlux + R2DBC 优势明显 |
| **吞吐量 (QPS)** | 500-1000 | 3000-5000 | ✅ WebFlux + R2DBC 优势明显 |
| **内存占用** | 2-4GB | 512MB-1GB | ✅ WebFlux + R2DBC 优势明显 |
| **CPU 利用率** | 60-80% | 40-60% | ✅ WebFlux + R2DBC 优势明显 |
| **线程数** | 200-500 | 10-20 | ✅ WebFlux + R2DBC 优势明显 |
| **开发效率** | 高 | 中 | ⚠️ Spring MVC + JPA 优势明显 |
| **学习成本** | 低 | 高 | ⚠️ Spring MVC + JPA 优势明显 |
| **调试难度** | 低 | 高 | ⚠️ Spring MVC + JPA 优势明显 |
| **生态成熟度** | 高 | 中 | ⚠️ Spring MVC + JPA 优势明显 |
**评估结论**：✅ **推荐 WebFlux + R2DBC**
**理由**：
1. 性能优势明显（并发能力提升 10 倍）
2. 响应时间降低 50%
3. 资源利用率提升 75%
4. 适合高并发场景（预约、签到）
5. 统一技术栈，架构简洁
**前提条件**：
1. 团队培训（4-6 周）
2. 建立响应式编程规范
3. 完善监控和调试体系
4. 代码审查（100% 覆盖）
5. 专项测试（单元测试 + 集成测试 + 性能测试）
### 2.2 技术栈评估
#### 2.2.1 核心技术栈
| 技术组件 | 版本 | 成熟度 | 社区活跃度 | 文档质量 | 推荐度 |
|---------|------|-------|-----------|---------|-------|
| **Spring Boot** | 3.2.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Spring WebFlux** | 3.2.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Spring Data R2DBC** | 3.2.x | ⭐⭐⭐⭐ | 高 | 良好 | ✅ 推荐 |
| **PostgreSQL R2DBC** | 1.0.0.RELEASE | ⭐⭐⭐⭐ | 高 | 良好 | ✅ 推荐 |
| **Spring Security** | 6.2.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Redis Reactive** | 3.2.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **RabbitMQ** | 3.12.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Elasticsearch** | 8.11.x | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Prometheus** | Latest | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
| **Grafana** | Latest | ⭐⭐⭐⭐⭐ | 高 | 优秀 | ✅ 强烈推荐 |
**评估结论**：✅ **技术栈成熟，社区活跃，文档完善**
#### 2.2.2 数据库选型
| 数据库 | R2DBC 支持 | 性能 | 可靠性 | 扩展性 | 推荐度 |
|-------|-----------|------|-------|-------|-------|
| **PostgreSQL** | ✅ 完全支持 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ 强烈推荐 |
| **MySQL** | ✅ 完全支持 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ 推荐 |
| **Oracle** | ⚠️ 支持有限 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ❌ 不推荐 |
| **SQL Server** | ⚠️ 支持有限 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ❌ 不推荐 |
**评估结论**：✅ **推荐 PostgreSQL**
**理由**：
1. 完全支持 R2DBC
2. 金融级数据库，支持 ACID 事务
3. JSONB 支持，适合配置管理
4. 全文搜索支持
5. 社区活跃，文档完善
#### 2.2.3 缓存选型
| 缓存 | Reactive 支持 | 性能 | 功能 | 推荐度 |
|------|-------------|------|------|-------|
| **Redis** | ✅ 完全支持 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ 强烈推荐 |
| **Memcached** | ❌ 不支持 | ⭐⭐⭐⭐ | ⭐⭐⭐ | ❌ 不推荐 |
| **本地缓存（Caffeine）** | ✅ 支持 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ 推荐 |
**评估结论**：✅ **推荐 Redis + Caffeine**
**理由**：
1. Redis 完全支持 Reactive
2. 性能优秀
3. 功能丰富（分布式锁、过期策略）
4. Caffeine 本地缓存，减少网络开销
---
## 三、性能评估
### 3.1 性能基准
#### 3.1.1 预期性能指标
| 性能指标 | Spring MVC + JPA | WebFlux + R2DBC | 提升幅度 |
|---------|-----------------|-----------------|---------|
| **并发连接数** | 200-500 | 2000-5000 | **10x** |
| **API 响应时间 (P99)** | 500-800ms | 200-400ms | **50%↓** |
| **吞吐量 (QPS)** | 500-1000 | 3000-5000 | **5x** |
| **内存占用** | 2-4GB | 512MB-1GB | **75%↓** |
| **CPU 利用率** | 60-80% | 40-60% | **25%↓** |
| **线程数** | 200-500 | 10-20 | **95%↓** |
#### 3.1.2 场景化性能预测
**场景 1：预约高峰期（每天 18:00-20:00）**
```
业务场景：会员预约团课
并发用户：500-1000
请求频率：每秒 50-100 次预约请求
Spring MVC + JPA：
- 需要服务器：4-6 台（8核16G）
- 响应时间：600-1000ms
- 成功率：95-97%
WebFlux + R2DBC：
- 需要服务器：1-2 台（4核8G）
- 响应时间：200-400ms
- 成功率：99%+
成本节省：60-70%
```
**场景 2：签到高峰期（每天 07:00-09:00, 18:00-20:00）**
```
业务场景：会员扫码签到
并发用户：1000-2000
请求频率：每秒 100-200 次签到请求
Spring MVC + JPA：
- 需要服务器：6-8 台（8核16G）
- 响应时间：300-500ms
- 成功率：98-99%
WebFlux + R2DBC：
- 需要服务器：2-3 台（4核8G）
- 响应时间：100-200ms
- 成功率：99.9%+
成本节省：70-80%
```
**场景 3：实时数据查询（会员信息、课程列表）**
```
业务场景：小程序实时查询
并发用户：2000-3000
请求频率：每秒 200-300 次查询请求
Spring MVC + JPA：
- 需要服务器：8-10 台（8核16G）
- 响应时间：200-400ms
- 缓存命中率：60-70%
WebFlux + R2DBC：
- 需要服务器：3-4 台（4核8G）
- 响应时间：50-150ms
- 缓存命中率：80-90%
成本节省：70-75%
```
### 3.2 性能优化策略
#### 3.2.1 数据库优化
1. **索引优化**：为常用查询字段创建索引
2. **查询优化**：避免全表扫描，使用索引
3. **连接池优化**：合理配置连接池大小
4. **分区表**：对大表进行分区
#### 3.2.2 缓存优化
1. **多级缓存**：本地缓存 + Redis 缓存
2. **缓存策略**：Cache-Aside 模式
3. **缓存预热**：系统启动时预热热点数据
4. **缓存更新**：合理设置缓存过期时间
#### 3.2.3 应用优化
1. **JVM 调优**：合理配置堆内存和 GC 参数
2. **连接池调优**：合理配置数据库连接池和 Redis 连接池
3. **异步处理**：使用消息队列异步处理耗时操作
4. **限流熔断**：使用 Sentinel 实现限流和熔断
---
## 四、成本分析
### 4.1 开发成本评估
| 成本项 | Spring MVC + JPA | WebFlux + R2DBC | 差异 |
|-------|-----------------|-----------------|------|
| **学习成本** | 低（团队熟悉） | 高（需要培训） | +30-40% |
| **开发效率** | 高（成熟生态） | 中（响应式编程复杂） | -20-30% |
| **代码复杂度** | 低 | 高 | +40-50% |
| **测试成本** | 中 | 高（响应式测试复杂） | +30-40% |
| **调试成本** | 低 | 高（异步调试困难） | +50-60% |
| **文档成本** | 低 | 高（需要详细规范） | +40-50% |
**总体开发成本增加：40-60%**
### 4.2 运维成本评估
| 成本项 | Spring MVC + JPA | WebFlux + R2DBC | 差异 |
|-------|-----------------|-----------------|------|
| **服务器成本** | 高（需要更多服务器） | 低（资源利用率高） | **-60-70%** |
| **数据库成本** | 高（连接数多） | 低（连接数少） | **-50-60%** |
| **监控成本** | 中 | 高（需要专门工具） | +30-40% |
| **故障排查成本** | 低 | 高（异步问题难定位） | +50-60% |
| **升级维护成本** | 低 | 中（生态更新快） | +20-30% |
**总体运维成本降低：40-50%**
### 4.3 总拥有成本（TCO）分析
```
3 年 TCO 对比（假设 1000 并发用户）：
Spring MVC + JPA：
- 开发成本：100 万
- 服务器成本：50 万/年 × 3 = 150 万
- 运维成本：20 万/年 × 3 = 60 万
- 总计：310 万
WebFlux + R2DBC：
- 开发成本：160 万（+60%）
- 服务器成本：20 万/年 × 3 = 60 万（-60%）
- 运维成本：30 万/年 × 3 = 90 万（+50%）
- 总计：310 万
结论：3 年 TCO 基本持平，但 WebFlux + R2DBC 在长期扩展性上优势明显
```
---
## 五、风险评估与缓解
### 5.1 技术风险矩阵
| 风险项 | 概率 | 影响 | 风险等级 | 缓解策略 |
|-------|------|------|---------|---------|
| **事务一致性** | 高 | 高 | 🔴 严重 | R2DBC 事务 + 分布式锁 + Saga 模式 |
| **团队技能不足** | 中 | 高 | 🔴 严重 | 培训 + 代码审查 + 技术分享 |
| **调试困难** | 高 | 中 | 🟡 中等 | Reactor Debug + 专项测试 |
| **生态成熟度** | 中 | 中 | 🟡 中等 | 选择成熟组件，避免边缘技术 |
| **性能不达标** | 低 | 高 | 🟡 中等 | 性能测试 + 优化 + 必要时回退 |
| **第三方库兼容** | 中 | 低 | 🟢 低 | 严格测试 + 版本锁定 |
| **长期维护** | 中 | 中 | 🟡 中等 | 完善文档 + 规范 + 团队建设 |
### 5.2 核心风险深度分析
#### 5.2.1 事务一致性（严重）
**问题描述**：
- R2DBC 的事务管理与 JDBC 有本质差异
- 跨服务事务处理复杂
- 并发场景下的数据一致性难以保证
**缓解策略**：
1. **单服务事务**：使用 R2DBC 的 `@Transactional` 注解
2. **跨服务事务**：使用 Saga 模式
3. **并发控制**：使用分布式锁 + 乐观锁
#### 5.2.2 团队技能不足（严重）
**问题描述**：
- 响应式编程学习曲线陡峭
- 团队缺乏实战经验
- 可能产生大量技术债务
**缓解策略**：
1. **培训计划**（4-6 周）
- Week 1-2：响应式编程基础理论
- Week 3-4：WebFlux + R2DBC 实战
- Week 5-6：性能优化与调试技巧
2. **代码审查**（100% 覆盖）
- 响应式编程规范检查
- 性能瓶颈识别
- 最佳实践验证
3. **技术分享**（每周 1 次）
- 响应式编程最佳实践
- 常见问题与解决方案
- 性能优化案例
4. **结对编程**（关键模块）
- 核心模块由经验丰富的开发者主导
- 新手通过结对学习
#### 5.2.3 调试困难（中等）
**问题描述**：
- 异步代码调试复杂
- 错误堆栈不直观
- 性能瓶颈难以定位
**缓解策略**：
1. **启用 Reactor Debug 模式**
2. **完善日志体系**
3. **性能监控**
4. **专项测试**
---
## 六、业务需求匹配度分析
### 6.1 核心业务场景评估
| 业务场景 | 并发需求 | 响应时间要求 | WebFlux 适用性 | 优先级 |
|---------|---------|-------------|---------------|-------|
| **会员注册** | 低（10-50/s） | < 2s | ⭐⭐⭐ | 低 |
| **会员查询** | 高（200-500/s） | < 500ms | ⭐⭐⭐⭐⭐ | 高 |
| **团课预约** | 高（100-300/s） | < 1s | ⭐⭐⭐⭐⭐ | 高 |
| **私教预约** | 中（50-100/s） | < 1s | ⭐⭐⭐⭐ | 中 |
| **扫码签到** | 极高（500-1000/s） | < 500ms | ⭐⭐⭐⭐⭐ | 极高 |
| **人脸识别签到** | 高（200-500/s） | < 1s | ⭐⭐⭐⭐ | 高 |
| **数据统计** | 中（50-100/s） | < 2s | ⭐⭐⭐⭐ | 中 |
| **营销活动** | 中（50-100/s） | < 1s | ⭐⭐⭐⭐ | 中 |
**结论**：核心业务场景（查询、预约、签到）非常适合 WebFlux + R2DBC
### 6.2 非功能性需求评估
| 需求 | 要求 | WebFlux + R2DBC | 匹配度 |
|------|------|-----------------|-------|
| **高可用性** | 99.9% | ✅ 支持优雅降级、熔断 | ⭐⭐⭐⭐⭐ |
| **高性能** | 1000 QPS | ✅ 轻松达到 5000+ QPS | ⭐⭐⭐⭐⭐ |
| **低延迟** | P99 < 500ms | ✅ 可达到 200-400ms | ⭐⭐⭐⭐⭐ |
| **可扩展性** | 水平扩展 | ✅ 无状态设计，易于扩展 | ⭐⭐⭐⭐⭐ |
| **可观测性** | 完善监控 | ✅ Micrometer + Actuator | ⭐⭐⭐⭐ |
| **安全性** | 金融级 | ✅ Spring Security Reactive | ⭐⭐⭐⭐⭐ |
| **易维护性** | 低维护成本 | ⚠️ 需要团队技能 | ⭐⭐⭐ |
---
## 七、综合评分
### 7.1 评分标准
| 评估维度 | 权重 | 得分 | 加权得分 |
|---------|------|------|---------|
| **性能** | 25% | 95 | 23.75 |
| **成本** | 20% | 85 | 17.00 |
| **风险** | 20% | 70 | 14.00 |
| **业务匹配度** | 15% | 95 | 14.25 |
| **技术成熟度** | 10% | 85 | 8.50 |
| **团队能力** | 10% | 60 | 6.00 |
| **总分** | 100% | - | **83.50** |
**结论**：83.50 分（优秀）
### 7.2 评分说明
- **性能（95 分）**：响应式编程性能优势明显，并发能力提升 10 倍
- **成本（85 分）**：开发成本增加 40-60%，但运维成本降低 40-50%
- **风险（70 分）**：存在事务一致性、团队技能等风险，但有缓解策略
- **业务匹配度（95 分）**：核心业务场景非常适合响应式架构
- **技术成熟度（85 分）**：技术栈成熟，社区活跃，文档完善
- **团队能力（60 分）**：需要培训和学习，但可以通过培训提升
---
## 八、最终建议
### 8.1 技术选型建议
✅ **强烈推荐采用单体应用 + WebFlux + R2DBC + Docker Compose 部署**
**理由**：
1. **适合当前规模**：1000 并发用户，3-5 人团队
2. **开发效率高**：团队上手快，学习成本低
3. **部署简单**：Docker Compose 一键部署
4. **性能优秀**：无服务间调用开销，本地事务性能好
5. **成本低**：开发成本增加 40-60%，但运维成本降低 40-50%
6. **扩展性好**：未来可以平滑演进到微服务
### 8.2 关键成功因素
1. ✅ 模块化设计（单体内部模块化）
2. ✅ 响应式编程规范（严格遵守规范）
3. ✅ 监控体系（Prometheus + Grafana）
4. ✅ 自动化部署（Docker Compose）
5. ✅ 性能测试（定期性能测试）
### 8.3 风险控制
1. ✅ 分阶段实施（基础设施 → 核心模块 → 高级功能）
2. ✅ 性能基准测试（每个阶段）
3. ✅ 回退方案（必要时可回退到 Spring MVC）
4. ✅ 持续优化（性能、稳定性）
### 8.4 实施路线图
#### 阶段一：基础设施搭建（1-2 周）
**任务清单**：
1. ✅ 创建 Spring Boot 3.x 项目
2. ✅ 配置 R2DBC + PostgreSQL
3. ✅ 配置 Redis Reactive
4. ✅ 配置 Actuator + Micrometer
5. ✅ 搭建基础代码结构
6. ✅ 编写响应式编程规范文档
#### 阶段二：核心模块开发（4-6 周）
**任务清单**：
1. ✅ 会员模块（注册、查询、会员卡管理）
2. ✅ 预约模块（团课预约、私教预约）
3. ✅ 签到模块（扫码签到、人脸识别）
4. ✅ 权益模块（权益扣减、权益记录）
5. ✅ 配置模块（租户配置、门店配置）
#### 阶段三：高级功能开发（4-6 周）
**任务清单**：
1. ✅ 订阅模块（模块订阅、计费）
2. ✅ 营销模块（营销活动、推荐奖励）
3. ✅ 数据分析模块（统计报表）
4. ✅ AI 智能模块（运营建议）
#### 阶段四：测试与优化（2-4 周）
**任务清单**：
1. ✅ 单元测试（覆盖率 ≥ 80%）
2. ✅ 集成测试
3. ✅ 性能测试
4. ✅ 压力测试
5. ✅ 安全测试
---
## 九、总结
### 9.1 技术架构优势
✅ **高性能**
- 响应式编程，并发能力提升 10 倍
- 响应时间降低 50%
- 资源利用率提升 75%
✅ **高可用**
- Docker Compose 一键部署
- 健康检查 + 自动重启
- 负载均衡 + 故障转移
✅ **易维护**
- 单体应用，开发效率高
- 模块化设计，易于扩展
- 完善的监控体系
✅ **低成本**
- 开发成本增加 40-60%，但运维成本降低 40-50%
- 服务器资源需求低
- 快速上线
### 9.2 关键成功因素
1. ✅ 严格遵守响应式编程规范
2. ✅ 重视事务一致性和并发控制
3. ✅ 建立完善的监控和调试体系
4. ✅ 持续的团队培训和代码审查
5. ✅ 渐进式开发，小步快跑
### 9.3 未来演进路径
**阶段一：单体应用（当前）**
- 模块化设计
- Docker Compose 部署
- 性能优化
**阶段二：垂直扩展（6-12 个月）**
- 增加服务器资源
- 优化数据库性能
- 引入缓存策略
**阶段三：水平扩展（12-24 个月）**
- 多实例部署
- 负载均衡
- 数据库读写分离
**阶段四：微服务（24-36 个月）**
- 按模块拆分服务
- 服务注册发现
- 分布式事务
### 9.4 文档清单
1. ✅ 《健身房管理系统技术架构设计文档》 GYM-HLD-TECH-001
2. ✅ 《健身房管理系统响应式编程规范文档》 GYM-STD-REACTIVE-001
3. ✅ 《健身房管理系统部署运维文档》 GYM-OPS-DEPLOY-001
4. ✅ 《健身房管理系统技术架构评估总结报告》 GYM-EVAL-TECH-001
---
## 十、附录
### 10.1 参考文档
- Spring Boot 3 官方文档
- Spring WebFlux 官方文档
- R2DBC 规范文档
- PostgreSQL 官方文档
- Docker 官方文档
- Docker Compose 官方文档
- Prometheus 官方文档
- Grafana 官方文档
### 10.2 技术支持
- Spring 社区：https://spring.io/community
- R2DBC 社区：https://r2dbc.io/
- PostgreSQL 社区：https://www.postgresql.org/community/
- Docker 社区：https://www.docker.com/community
### 10.3 联系方式
- 技术负责人：张翔
- 邮箱：zhangxiang@example.com
- 文档版本：v1.0
- 最后更新：2026-03-04
docs/design/HLD-技术架构设计.md
-1274
View File
File diff suppressed because it is too large Load Diff
docs/design/OPS-部署运维文档.md
-1537
View File
File diff suppressed because it is too large Load Diff
docs/design/business/B-HLD-付费订阅版-业务概要设计.md
-803
View File
@@ -1,803 +0,0 @@
# 健身房管理系统付费订阅版业务概要设计文档（B-HLD）
> 文档编号: GYM-B-HLD-SUBSCRIPTION-001
> 版本: v1.0
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 已发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------------------------- |
| v1.0 | 2026-03-08 | 张翔 | 创建付费订阅版业务概要设计文档 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统付费订阅版的业务概要设计文档（Business High-Level Design），旨在：
1. 从业务层面描述付费订阅版的业务范围、核心业务流程、业务规则
2. 为业务详细设计提供业务指导和约束
3. 作为产品经理、业务分析师的业务参考
### 1.2 项目背景
健身房管理系统付费订阅版在基础版基础上，提供丰富的增值功能，满足中大型健身房、连锁品牌等复杂场景需求。
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
| 订阅模块(Subscription Module) | 按需订阅的增值功能模块 |
| 配置继承(Configuration Inheritance) | 门店配置继承租户配置的机制 |
### 1.4 参考文档
- 《健身房管理系统付费订阅版产品设计文档》 GYM-PRD-SUBSCRIPTION-001
---
## 二、业务概述
### 2.1 业务目标
| 目标维度 | 目标描述 | 成功指标 |
| -------- | ---------------------- | -------------------------------- |
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供数据驱动决策支持 | 数据报表使用率 ≥ 80% |
| 业务增长 | 提升会员留存和增长 | 会员留存率提升 20% |
### 2.2 用户角色
| 角色 | 描述 | 主要功能 |
| ---------- | -------------- | ------------------------------------------ |
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息、参与社区 |
| 教练 | 健身房教练 | 排课、私教预约确认、学员签到、发布线上课程 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看、营销活动管理 |
| 运营管理员 | 平台运营人员 | 营销活动配置、数据分析、AI运营建议查看 |
| 财务专员 | 财务人员 | 账单管理、财务报表 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
### 2.3 业务范围
```mermaid
graph LR
subgraph 付费订阅版业务范围
A[基础功能<br/>包含基础版所有功能<br/>• 会员管理<br/>• 预约管理<br/>• 签到管理<br/>• 数据统计<br/>• 系统管理]
B[订阅与配置管理<br/>• 订阅管理<br/>• 配置管理<br/>• 套餐管理<br/>• 计费管理]
C[业务扩展类模块<br/>• 私教管理<br/>• 器械预约<br/>• 线上课程]
D[体验升级类模块<br/>• 人脸识别签到<br/>• NFC签到<br/>• 智能储物柜]
E[营销增长类模块<br/>• 营销活动<br/>• 会员推荐奖励<br/>• 会员互动社区<br/>• 智能获客工具]
F[数据智能类模块<br/>• 营销精算模型<br/>• 自定义促销预测<br/>• 高级数据分析<br/>• 智能报表<br/>• AI运营建议<br/>• 智能体测数据联动]
end
```
---
## 三、核心业务流程
### 3.1 订阅流程
#### 3.1.1 业务场景
租户管理员通过管理后台订阅增值模块。
#### 3.1.2 业务流程
```mermaid
flowchart LR
A[租户管理员登录] --> B[查看订阅套餐]
B --> C[选择订阅模块]
C --> D[确认订阅]
D --> E[模块立即启用]
```
#### 3.1.3 业务规则
- 订阅成功后模块立即启用
- 年付享受最大折扣
- 支持多种支付方式
- 订阅成功后发送通知
#### 3.1.4 异常处理
| 异常场景 | 处理方式 |
| -------- | -------------------- |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 提示用户重新发起支付 |
---
### 3.2 配置继承流程
#### 3.2.1 业务场景
门店管理员配置门店级参数，可以选择继承租户配置。
#### 3.2.2 业务流程
```mermaid
flowchart LR
A[门店管理员登录] --> B[查看租户级配置]
B --> C[选择继承模式]
C --> D[配置门店级参数]
D --> E[配置立即生效]
```
#### 3.2.3 业务规则
- 查询优先级：门店配置 → 租户配置 → 默认配置
- 支持三种继承模式（继承/继承+覆盖/自定义）
- 配置变更后立即生效
- 配置变更记录版本，支持回滚
#### 3.2.4 异常处理
| 异常场景 | 处理方式 |
| -------- | ---------------------- |
| 配置冲突 | 提示用户选择覆盖或合并 |
| 配置无效 | 提示用户重新配置 |
---
### 3.3 私教预约流程
#### 3.3.1 业务场景
会员通过小程序预约私教课程。
#### 3.3.2 业务流程
```mermaid
flowchart LR
A[会员打开小程序] --> B[查看私教课程列表]
B --> C[选择私教课程]
C --> D[确认预约]
D --> E[预约成功]
```
#### 3.3.3 业务规则
- 私教预约需提前至少24小时
- 私教取消需提前至少12小时
- 私教签到后记录考勤
#### 3.3.4 异常处理
| 异常场景 | 处理方式 |
| -------------- | -------------------- |
| 教练时间冲突 | 提示用户选择其他时间 |
| 会员卡权益不足 | 提示用户购买会员卡 |
---
### 3.4 营销活动创建流程
#### 3.4.1 业务场景
运营管理员通过管理后台创建营销活动。
#### 3.4.2 业务流程
```mermaid
flowchart LR
A[运营管理员登录] --> B[创建营销活动]
B --> C[配置活动规则]
C --> D[发布活动]
D --> E[活动生效]
```
#### 3.4.3 业务规则
- 营销活动需指定时间、规则、奖励
- 营销活动发布后不可修改规则
- 营销活动统计按活动、时间维度
#### 3.4.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | -------------------- |
| 活动时间冲突 | 提示用户调整活动时间 |
| 活动规则无效 | 提示用户重新配置 |
---
### 3.5 营销分析与预测流程
#### 3.5.1 业务场景
运营管理员使用营销精算模型预测促销策略。
#### 3.5.2 业务流程
```mermaid
flowchart LR
A[运营管理员登录] --> B[选择营销精算模型]
B --> C[配置促销参数]
C --> D[预测效果]
D --> E[查看预测结果]
```
#### 3.5.3 业务规则
- 营销精算模型基于历史数据
- 促销策略预测提供多种方案
- 促销活动效果预测基于历史数据
#### 3.5.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | -------------------- |
| 历史数据不足 | 提示用户积累更多数据 |
| 预测失败 | 提示用户调整参数 |
---
### 3.6 智能获客流程
#### 3.6.1 业务场景
运营管理员使用智能获客工具进行节后健身潮获客、私域流量获客、推荐裂变获客。
#### 3.6.2 业务流程
**节后健身潮获客**：
```mermaid
flowchart LR
A[运营管理员登录] --> B[创建获客活动]
B --> C[配置活动参数]
C --> D[生成海报和文案]
D --> E[分发渠道并追踪]
```
**私域流量获客**：
```mermaid
flowchart LR
A[运营管理员登录] --> B[管理私域流量池]
B --> C[精准推送消息]
C --> D[自动化运营]
D --> E[分析转化效果]
```
**推荐裂变获客**：
```mermaid
flowchart LR
A[会员打开小程序] --> B[生成推荐码]
B --> C[分享推荐链接]
C --> D[追踪推荐关系链]
D --> E[自动发放奖励]
```
#### 3.6.3 业务规则
- 节后健身潮获客年度流量窗口期自动激活（1月1日-3月31日）
- 私域流量获客基于用户标签精准推送
- 推荐裂变获客支持多级推荐
- 每个渠道的获客效果可追踪
- 推荐奖励自动发放
#### 3.6.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | ---------------- |
| 海报生成失败 | 提示用户重新生成 |
| 文案生成失败 | 提示用户手动编辑 |
| 推荐码失效 | 提示用户重新生成 |
---
### 3.7 智能体测数据联动流程
#### 3.7.1 业务场景
会员进行体测后，体测设备自动上传数据到系统，系统进行数据转换、存储、分析，生成体测报告。
#### 3.7.2 业务流程
```mermaid
flowchart LR
A["会员进行体测"] --> B["设备自动上传数据"]
B --> C["系统数据转换"]
C --> D["数据存储到档案"]
D --> E["生成体测报告"]
style A fill:#e1f5ff
style B fill:#fff4e1
style C fill:#f0e1ff
style D fill:#e1ffe1
style E fill:#ffe1e1
```
#### 3.7.3 业务规则
- 支持主流体测设备（InBody、Tanita等）
- 提供标准API接口，支持任意体测设备对接
- 数据自动上传和转换
- 数据统一存储到会员健康档案
- 支持体测数据查询和分析
- 支持体测报告生成
#### 3.7.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | ------------------------ |
| 设备连接失败 | 提示用户检查设备连接 |
| 数据上传失败 | 提示用户重新上传 |
| 数据转换失败 | 记录错误日志，通知管理员 |
---
### 3.8 器械预约流程
#### 3.8.1 业务场景
会员通过小程序预约器械使用时段，避免等待，提升器械使用效率。
#### 3.8.2 业务流程
```mermaid
flowchart LR
A[会员打开小程序] --> B[查看器械列表]
B --> C[选择器械]
C --> D[查看可用时段]
D --> E[选择时段]
E --> F[确认预约]
F --> G{预约结果}
G -->|成功| H[预约成功]
G -->|失败| I[提示失败原因]
H --> J[接收预约提醒]
J --> K[到店使用器械]
K --> L[使用结束]
L --> M[释放器械]
style A fill:#e1f5ff
style G fill:#fff4e1
style K fill:#e1ffe1
```
#### 3.8.3 业务规则
- **器械预约时间**：器械预约需提前至少30分钟
- **器械取消时间**：器械取消需提前至少1小时
- **器械预约时长**：每次预约时长不超过2小时
- **器械预约冲突**：同一器械同一时段只能预约1人
- **器械使用超时**：超时10分钟自动释放器械
- **器械使用统计**：记录器械使用时长和次数
#### 3.8.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 器械已被预约 | 提示用户选择其他时段 |
| 预约时间过短 | 提示用户提前预约 |
| 器械维护中 | 提示用户选择其他器械 |
| 预约冲突 | 提示用户选择其他时段 |
---
### 3.9 人脸识别签到流程
#### 3.9.1 业务场景
会员通过人脸识别进行签到，提升签到体验，实现无感通行。
#### 3.9.2 业务流程
```mermaid
flowchart LR
A[会员到店] --> B[人脸识别设备]
B --> C{识别结果}
C -->|成功| D[验证会员卡]
D --> E{验证结果}
E -->|有效| F[签到成功]
E -->|无效| G[提示会员卡无效]
C -->|失败| H[降级为扫码签到]
F --> I[记录到店时间]
G --> H
H --> I
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#fff4e1
style H fill:#ffe1e1
```
#### 3.9.3 业务规则
- **人脸信息采集**：人脸信息需会员授权
- **人脸识别准确率**：人脸识别准确率 ≥ 95%
- **人脸识别失败**：人脸识别失败后降级为扫码签到
- **人脸信息存储**：人脸信息加密存储
- **人脸信息管理**：会员可以删除人脸信息
- **人脸识别考勤**：人脸识别签到后记录考勤
#### 3.9.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 人脸识别失败 | 降级为扫码签到 |
| 会员卡无效 | 提示用户购买会员卡 |
| 人脸信息不存在 | 提示用户采集人脸信息 |
| 设备连接失败 | 提示用户检查设备连接 |
---
### 3.10 NFC签到流程
#### 3.10.1 业务场景
会员通过NFC手环/卡片进行签到，支持储物柜联动，提升签到体验。
#### 3.10.2 业务流程
```mermaid
flowchart LR
A[会员到店] --> B[刷NFC卡]
B --> C[读取NFC信息]
C --> D[验证会员卡]
D --> E{验证结果}
E -->|有效| F[签到成功]
E -->|无效| G[提示会员卡无效]
F --> H{是否需要储物柜}
H -->|是| I[自动开锁储物柜]
H -->|否| J[记录到店时间]
I --> J
G --> K[降级为扫码签到]
K --> J
style A fill:#e1f5ff
style E fill:#fff4e1
style H fill:#fff4e1
style K fill:#ffe1e1
```
#### 3.10.3 业务规则
- **NFC卡绑定**：NFC卡需绑定会员
- **NFC签到验证**：NFC签到需验证会员卡有效性
- **NFC签到失败**：NFC签到失败后降级为扫码签到
- **NFC卡管理**：会员可以解绑NFC卡
- **储物柜联动**：支持储物柜自动开锁
- **NFC卡丢失**：NFC卡丢失后可解绑
#### 3.10.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| NFC卡未绑定 | 提示用户绑定NFC卡 |
| 会员卡无效 | 提示用户购买会员卡 |
| NFC卡失效 | 提示用户更换NFC卡 |
| 储物柜故障 | 提示用户使用其他储物柜 |
---
### 3.11 在线课程流程
#### 3.11.1 业务场景
会员通过小程序预约和观看线上课程，拓展线上业务，提升会员活跃度。
#### 3.11.2 业务流程
```mermaid
flowchart LR
A[教练发布线上课程] --> B[填写课程信息]
B --> C[上传课程视频]
C --> D[发布课程]
D --> E[会员查看课程列表]
E --> F[选择课程]
F --> G[预约课程]
G --> H[接收预约提醒]
H --> I[观看课程]
I --> J[课程评价]
J --> K[课程统计]
style A fill:#e1f5ff
style D fill:#fff4e1
style G fill:#fff4e1
style I fill:#e1ffe1
```
#### 3.11.3 业务规则
- **线上课程发布**：线上课程需指定教练、时间、链接
- **线上课程预约**：线上课程预约需提前至少30分钟
- **线上课程观看**：线上课程观看需验证预约
- **线上课程评价**：线上课程观看后可以评价
- **线上课程统计**：线上课程统计按课程、时间维度
- **视频点播**：支持视频点播功能
- **直播课管理**：支持直播课管理
#### 3.11.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 课程视频上传失败 | 提示教练重新上传 |
| 预约时间过短 | 提示用户提前预约 |
| 课程视频无法播放 | 提示用户检查网络连接 |
| 直播课中断 | 提示用户等待直播恢复 |
---
## 四、用户角色和权限
### 4.1 角色定义
| 角色 | 描述 | 主要功能 |
| ---------- | -------------- | ------------------------------------------ |
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息、参与社区 |
| 教练 | 健身房教练 | 排课、私教预约确认、学员签到、发布线上课程 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看、营销活动管理 |
| 运营管理员 | 平台运营人员 | 营销活动配置、数据分析、AI运营建议查看 |
| 财务专员 | 财务人员 | 账单管理、财务报表 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
### 4.2 权限矩阵
| 功能模块 | 会员 | 教练 | 前台 | 店长 | 运营管理员 | 财务专员 | 超级管理员 |
| ------------ | ---- | ---- | ---- | ---- | ---------- | --------- | ---------- |
| 会员信息查看 | 自己 | 所有 | 所有 | 所有 | 所有 | 所有 | 所有 |
| 会员信息编辑 | 自己 | 无 | 所有 | 所有 | 所有 | 无 | 所有 |
| 团课创建 | 无 | 是 | 否 | 是 | 否 | 否 | 是 |
| 团课编辑 | 无 | 自己 | 否 | 所有 | 否 | 否 | 所有 |
| 团课取消 | 无 | 自己 | 否 | 所有 | 否 | 否 | 所有 |
| 私教创建 | 无 | 是 | 否 | 是 | 否 | 否 | 是 |
| 私教编辑 | 无 | 自己 | 否 | 所有 | 否 | 否 | 所有 |
| 私教取消 | 无 | 自己 | 否 | 所有 | 否 | 否 | 所有 |
| 签到管理 | 无 | 是 | 是 | 是 | 否 | 否 | 是 |
| 营销活动创建 | 无 | 无 | 否 | 是 | 是 | 否 | 是 |
| 营销活动编辑 | 无 | 无 | 否 | 自己 | 所有 | 否 | 所有 |
| 营销活动取消 | 无 | 无 | 否 | 自己 | 所有 | 否 | 所有 |
| 数据统计查看 | 自己 | 自己 | 所有 | 所有 | 所有 | 所有 | 所有 |
| 财务报表查看 | 无 | 无 | 否 | 所有 | 所有 | 所有 | 所有 |
| 系统配置 | 无 | 无 | 无 | 无 | 否 | 否 | 是 |
---
## 五、业务规则汇总
### 5.1 订阅管理规则
| 规则 | 描述 |
| -------- | ---------------------------- |
| 订阅生效 | 订阅成功后模块立即启用 |
| 计费周期 | 支持月付、季付、半年付、年付 |
| 试用政策 | 不同模块类型提供不同试用时长 |
| 组合套餐 | 支持组合套餐，享受更多优惠 |
### 5.2 配置管理规则
| 规则 | 描述 |
| ---------- | ----------------------------------- |
| 配置继承 | 支持门店配置继承租户配置 |
| 继承模式 | 支持继承、继承+覆盖、自定义三种模式 |
| 配置优先级 | 门店配置 → 租户配置 → 默认配置 |
| 配置版本 | 配置变更记录版本，支持回滚 |
### 5.3 私教管理规则
| 规则 | 描述 |
| ------------ | ------------------------ |
| 私教预约时间 | 私教预约需提前至少24小时 |
| 私教取消时间 | 私教取消需提前至少12小时 |
| 私教考勤 | 私教签到后记录考勤 |
### 5.4 营销活动规则
| 规则 | 描述 |
| -------- | ------------------------------ |
| 活动规则 | 营销活动需指定时间、规则、奖励 |
| 活动修改 | 营销活动发布后不可修改规则 |
| 活动统计 | 营销活动统计按活动、时间维度 |
### 5.5 营销分析与预测规则
| 规则 | 描述 |
| -------- | ---------------------------- |
| 模型基础 | 营销精算模型基于历史数据 |
| 预测方案 | 促销策略预测提供多种方案 |
| 效果预测 | 促销活动效果预测基于历史数据 |
### 5.6 智能获客工具规则
| 规则 | 描述 |
| -------------- | ---------------------------------------- |
| 节后健身潮获客 | 年度流量窗口期自动激活（1月1日-3月31日） |
| 私域流量获客 | 基于用户标签精准推送 |
| 推荐裂变获客 | 支持多级推荐 |
| 获客效果追踪 | 每个渠道的获客效果可追踪 |
| 推荐奖励发放 | 推荐奖励自动发放 |
### 5.7 智能体测数据联动规则
| 规则 | 描述 |
| -------- | ------------------------------------- |
| 设备对接 | 支持主流体测设备（InBody、Tanita等） |
| API接口 | 提供标准API接口，支持任意体测设备对接 |
| 数据上传 | 数据自动上传和转换 |
| 数据存储 | 数据统一存储到会员健康档案 |
| 数据查询 | 支持体测数据查询和分析 |
| 报告生成 | 支持体测报告生成 |
### 5.8 器械预约规则
| 规则 | 描述 |
|------|------|
| 预约时间 | 器械预约需提前至少30分钟 |
| 取消时间 | 器械取消需提前至少1小时 |
| 预约时长 | 每次预约时长不超过2小时 |
| 预约冲突 | 同一器械同一时段只能预约1人 |
| 使用超时 | 超时10分钟自动释放器械 |
| 使用统计 | 记录器械使用时长和次数 |
### 5.9 人脸识别签到规则
| 规则 | 描述 |
|------|------|
| 人脸信息采集 | 人脸信息需会员授权 |
| 人脸识别准确率 | 人脸识别准确率 ≥ 95% |
| 人脸识别失败 | 人脸识别失败后降级为扫码签到 |
| 人脸信息存储 | 人脸信息加密存储 |
| 人脸信息管理 | 会员可以删除人脸信息 |
| 人脸识别考勤 | 人脸识别签到后记录考勤 |
### 5.10 NFC签到规则
| 规则 | 描述 |
|------|------|
| NFC卡绑定 | NFC卡需绑定会员 |
| NFC签到验证 | NFC签到需验证会员卡有效性 |
| NFC签到失败 | NFC签到失败后降级为扫码签到 |
| NFC卡管理 | 会员可以解绑NFC卡 |
| 储物柜联动 | 支持储物柜自动开锁 |
| NFC卡丢失 | NFC卡丢失后可解绑 |
### 5.11 在线课程规则
| 规则 | 描述 |
|------|------|
| 线上课程发布 | 线上课程需指定教练、时间、链接 |
| 线上课程预约 | 线上课程预约需提前至少30分钟 |
| 线上课程观看 | 线上课程观看需验证预约 |
| 线上课程评价 | 线上课程观看后可以评价 |
| 线上课程统计 | 线上课程统计按课程、时间维度 |
| 视频点播 | 支持视频点播功能 |
| 直播课管理 | 支持直播课管理 |
---
## 六、异常处理汇总
| 异常场景 | 处理方式 |
| ---------------- | ---------------------------- |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 提示用户重新发起支付 |
| 配置冲突 | 提示用户选择覆盖或合并 |
| 配置无效 | 提示用户重新配置 |
| 教练时间冲突 | 提示用户选择其他时间 |
| 会员卡权益不足 | 提示用户购买会员卡 |
| 活动时间冲突 | 提示用户调整活动时间 |
| 活动规则无效 | 提示用户重新配置 |
| 历史数据不足 | 提示用户积累更多数据 |
| 预测失败 | 提示用户调整参数 |
| 海报生成失败 | 提示用户重新生成 |
| 文案生成失败 | 提示用户手动编辑 |
| 推荐码失效 | 提示用户重新生成 |
| 设备连接失败 | 提示用户检查设备连接 |
| 数据上传失败 | 提示用户重新上传 |
| 数据转换失败 | 记录错误日志，通知管理员 |
| 器械已被预约 | 提示用户选择其他时段 |
| 预约时间过短 | 提示用户提前预约 |
| 器械维护中 | 提示用户选择其他器械 |
| 预约冲突 | 提示用户选择其他时段 |
| 人脸识别失败 | 降级为扫码签到 |
| 会员卡无效 | 提示用户购买会员卡 |
| 人脸信息不存在 | 提示用户采集人脸信息 |
| 设备连接失败 | 提示用户检查设备连接 |
| NFC卡未绑定 | 提示用户绑定NFC卡 |
| NFC卡失效 | 提示用户更换NFC卡 |
| 储物柜故障 | 提示用户使用其他储物柜 |
| 课程视频上传失败 | 提示教练重新上传 |
| 预约时间过短 | 提示用户提前预约 |
| 课程视频无法播放 | 提示用户检查网络连接 |
| 直播课中断 | 提示用户等待直播恢复 |
---
## 七、附录
### 7.1 业务流程图索引
| 流程名称 | 图表位置 |
| ---------------- | ------------ |
| 订阅流程 | 3.1.2 |
| 配置继承流程 | 3.2.2 |
| 私教预约流程 | 3.3.2 |
| 营销活动创建流程 | 3.4.2 |
| 营销分析与预测流程 | 3.5.2 |
| 智能获客流程 | 3.6.2 |
| 智能体测数据联动流程 | 3.7.2 |
| 器械预约流程 | 3.8.2 |
| 人脸识别签到流程 | 3.9.2 |
| NFC签到流程 | 3.10.2 |
| 在线课程流程 | 3.11.2 |
### 7.2 业务规则索引
| 规则分类 | 规则名称 | 图表位置 |
| ---------------- | ---------------- | ------------ |
| 订阅管理规则 | 订阅生效 | 5.1 |
| 订阅管理规则 | 计费周期 | 5.1 |
| 订阅管理规则 | 试用政策 | 5.1 |
| 订阅管理规则 | 组合套餐 | 5.1 |
| 配置管理规则 | 配置继承 | 5.2 |
| 配置管理规则 | 继承模式 | 5.2 |
| 配置管理规则 | 配置优先级 | 5.2 |
| 配置管理规则 | 配置版本 | 5.2 |
| 私教管理规则 | 私教预约时间 | 5.3 |
| 私教管理规则 | 私教取消时间 | 5.3 |
| 私教管理规则 | 私教考勤 | 5.3 |
| 营销活动规则 | 活动规则 | 5.4 |
| 营销活动规则 | 活动修改 | 5.4 |
| 营销活动规则 | 活动统计 | 5.4 |
| 营销分析与预测规则 | 模型基础 | 5.5 |
| 营销分析与预测规则 | 预测方案 | 5.5 |
| 营销分析与预测规则 | 效果预测 | 5.5 |
| 智能获客工具规则 | 节后健身潮获客 | 5.6 |
| 智能获客工具规则 | 私域流量获客 | 5.6 |
| 智能获客工具规则 | 推荐裂变获客 | 5.6 |
| 智能获客工具规则 | 获客效果追踪 | 5.6 |
| 智能获客工具规则 | 推荐奖励发放 | 5.6 |
| 智能体测数据联动规则 | 设备对接 | 5.7 |
| 智能体测数据联动规则 | API接口 | 5.7 |
| 智能体测数据联动规则 | 数据上传 | 5.7 |
| 智能体测数据联动规则 | 数据存储 | 5.7 |
| 智能体测数据联动规则 | 数据查询 | 5.7 |
| 智能体测数据联动规则 | 报告生成 | 5.7 |
| 器械预约规则 | 预约时间 | 5.8 |
| 器械预约规则 | 取消时间 | 5.8 |
| 器械预约规则 | 预约时长 | 5.8 |
| 器械预约规则 | 预约冲突 | 5.8 |
| 器械预约规则 | 使用超时 | 5.8 |
| 器械预约规则 | 使用统计 | 5.8 |
| 人脸识别签到规则 | 人脸信息采集 | 5.9 |
| 人脸识别签到规则 | 人脸识别准确率 | 5.9 |
| 人脸识别签到规则 | 人脸识别失败 | 5.9 |
| 人脸识别签到规则 | 人脸信息存储 | 5.9 |
| 人脸识别签到规则 | 人脸信息管理 | 5.9 |
| 人脸识别签到规则 | 人脸识别考勤 | 5.9 |
| NFC签到规则 | NFC卡绑定 | 5.10 |
| NFC签到规则 | NFC签到验证 | 5.10 |
| NFC签到规则 | NFC签到失败 | 5.10 |
| NFC签到规则 | NFC卡管理 | 5.10 |
| NFC签到规则 | 储物柜联动 | 5.10 |
| NFC签到规则 | NFC卡丢失 | 5.10 |
| 在线课程规则 | 线上课程发布 | 5.11 |
| 在线课程规则 | 线上课程预约 | 5.11 |
| 在线课程规则 | 线上课程观看 | 5.11 |
| 在线课程规则 | 线上课程评价 | 5.11 |
| 在线课程规则 | 线上课程统计 | 5.11 |
| 在线课程规则 | 视频点播 | 5.11 |
| 在线课程规则 | 直播课管理 | 5.11 |
---
**文档结束**
docs/design/business/B-HLD-基础版-业务概要设计.md
-477
View File
@@ -1,477 +0,0 @@
# 健身房管理系统基础版业务概要设计文档（B-HLD）
> 文档编号: GYM-B-HLD-BASIC-001
> 版本: v1.0
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 已发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ---------------------- |
| v1.0 | 2026-03-08 | 张翔 | 创建基础版业务概要设计文档 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统基础版的业务概要设计文档（Business High-Level Design），旨在：
1. 从业务层面描述基础版的业务范围、核心业务流程、业务规则
2. 为业务详细设计提供业务指导和约束
3. 作为产品经理、业务分析师的业务参考
### 1.2 项目背景
健身房管理系统基础版是面向小型工作室、个人教练等场景的核心版本，保证业务闭环，提供完整的会员管理、预约、签到等核心功能。
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 1.4 参考文档
- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
---
## 二、业务概述
### 2.1 业务目标
| 目标维度 | 目标描述 | 成功指标 |
| -------- | ---------------------- | -------------------------------- |
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供基础数据支持 | 数据报表使用率 ≥ 80% |
### 2.2 用户角色
| 角色 | 描述 | 主要功能 |
| ---------- | -------------- | ---------------------------- |
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息 |
| 教练 | 健身房教练 | 排课、团课签到管理 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
### 2.3 业务范围
```mermaid
flowchart LR
subgraph "基础版业务范围"
M1[会员管理<br/>• 会员注册<br/>• 会员卡管理<br/>• 权益管理]
M2[预约管理<br/>• 团课预约<br/>• 团课管理]
M3[签到管理<br/>• 扫码签到<br/>• 签到记录管理]
M4[数据统计<br/>• 基础数据统计]
M5[系统管理<br/>• 用户管理<br/>• 角色权限管理]
M6[UI模版定制<br/>• 品牌定制<br/>• 布局调整<br/>• 预设模板<br/>• 配置历史]
end
```
---
## 三、核心业务流程
### 3.1 会员注册流程
#### 3.1.1 业务场景
新用户通过小程序或前台进行注册，成为健身房会员。
#### 3.1.2 业务流程
```mermaid
flowchart LR
A[用户打开小程序] --> B[填写手机号]
B --> C[验证手机号]
C --> D[填写基本信息]
D --> E[注册成功]
```
#### 3.1.3 业务规则
- 手机号需验证唯一性
- 手机号需通过短信验证码验证
- 支持微信授权快速注册
- 注册成功后自动创建会员档案
#### 3.1.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | ---------------- |
| 手机号已存在 | 提示用户直接登录 |
| 验证码错误 | 提示用户重新输入 |
| 验证码过期 | 提示用户重新获取 |
---
### 3.2 团课预约流程
#### 3.2.1 业务场景
会员通过小程序预约团课，教练通过管理后台创建团课。
#### 3.2.2 业务流程
**会员预约团课**：
```mermaid
flowchart LR
A[会员打开小程序] --> B[查看团课列表]
B --> C[选择团课]
C --> D[确认预约]
D --> E[预约成功]
```
**教练创建团课**：
```mermaid
flowchart LR
A[教练打开管理后台] --> B[点击创建团课]
B --> C[填写团课信息]
C --> D[发布团课]
D --> E[发布成功]
```
#### 3.2.3 业务规则
**预约时间规则**
- 预约需在课程开始前至少30分钟
- ✅ 场景1：团课18:00开始，会员17:30可以预约
- ✅ 场景2：团课18:00开始，会员17:31可以预约
- ❌ 场景3：团课18:00开始，会员17:29无法预约
- ❌ 场景4：团课18:00开始，会员18:00无法预约
**取消预约规则**
- 取消预约需在课程开始前至少2小时
- ✅ 场景1：团课18:00开始，会员16:00可以取消预约
- ✅ 场景2：团课18:00开始，会员15:59可以取消预约
- ❌ 场景3：团课18:00开始，会员16:01无法取消预约
- ❌ 场景4：团课18:00开始，会员17:00无法取消预约
**课程容量规则**
- 每节课最多20人
- ✅ 场景1：团课当前预约19人，第20人可以预约
- ✅ 场景2：团课当前预约18人，2人同时预约，都成功
- ❌ 场景3：团课当前预约20人，第21人无法预约
- ❌ 场景4：团课当前预约19人，2人同时预约，1人成功1人失败
**权益扣减规则**
- 预约成功后扣减权益
- ✅ 场景1：会员有5次团课权益，预约1次后剩余4次
- ✅ 场景2：会员有30天时长卡，预约后时长不变，仅记录预约信息
- ✅ 场景3：会员有储值卡，预约团课费用100元，余额从500元变为400元
- ❌ 场景4：会员权益为0时，无法预约团课
**团课创建规则**
- 团课需指定教练、时间、地点
- ✅ 场景1：教练张三创建团课，指定时间为18:00-19:00，地点为A教室
- ✅ 场景2：教练张三创建团课，指定时间为每周一18:00-19:00，地点为A教室
- ❌ 场景3：创建团课未指定教练，系统提示"请选择教练"
- ❌ 场景4：创建团课未指定时间，系统提示"请选择时间"
**团课取消规则**
- 团课取消需提前24小时通知
- 团课取消后自动退款
- ✅ 场景1：团课18:00开始，教练在前一天16:00取消，已预约会员自动退款
- ✅ 场景2：团课18:00开始，教练在前一天18:00取消，已预约会员自动退款
- ❌ 场景3：团课18:00开始，教练在前一天18:01取消，系统提示"取消时间过晚"
- ❌ 场景4：团课18:00开始，教练在当天17:00取消，系统提示"取消时间过晚"
#### 3.2.4 异常处理
| 异常场景 | 处理方式 |
| -------------- | -------------------- |
| 课程已满 | 提示用户选择其他课程 |
| 会员卡权益不足 | 提示用户购买会员卡 |
| 预约时间过短 | 提示用户提前预约 |
---
### 3.3 签到流程
#### 3.3.1 业务场景
会员到店后通过扫码进行签到，记录到店信息。
#### 3.3.2 业务流程
```mermaid
flowchart LR
A[会员到店] --> B[扫描签到码]
B --> C[验证会员卡]
C --> D[签到成功]
D --> E[记录到店时间]
```
#### 3.3.3 业务规则
**会员卡验证规则**
- 签到需验证会员卡有效性
- ✅ 场景1：会员卡有效期至2026-12-31，今日签到成功
- ✅ 场景2：会员卡有5次权益，签到后剩余4次
- ✅ 场景3：会员卡为30天时长卡，签到后时长不变
- ❌ 场景4：会员卡已过期（2026-01-01到期），签到失败提示"会员卡已过期"
- ❌ 场景5：会员卡权益为0，签到失败提示"会员卡权益不足"
**预约验证规则**
- 签到需验证预约信息（如有）
- ✅ 场景1：会员预约了18:00的团课，18:00签到成功
- ✅ 场景2：会员预约了18:00的团课，17:50签到成功
- ✅ 场景3：会员未预约团课，签到成功记录为自由训练
- ❌ 场景4：会员预约了18:00的团课，19:00签到失败提示"课程已结束"
- ❌ 场景5：会员预约了A教室的团课，在B教室签到失败提示"签到地点错误"
**签到记录规则**
- 签到成功后记录到店时间
- ✅ 场景1：会员18:00:00签到，记录到店时间为2026-03-08 18:00:00
- ✅ 场景2：会员同一天多次签到，记录每次签到时间
- ✅ 场景3：会员签到后离开，再次签到记录新的到店时间
- ❌ 场景4：会员签到失败，不记录到店时间
#### 3.3.4 异常处理
| 异常场景 | 处理方式 |
| ---------- | ------------------ |
| 会员卡无效 | 提示用户购买会员卡 |
| 会员卡过期 | 提示用户续费 |
| 签到码无效 | 提示用户重新扫描 |
---
### 3.4 会员卡购买流程
#### 3.4.1 业务场景
会员通过小程序购买会员卡，获得相应权益。
#### 3.4.2 业务流程
```mermaid
flowchart LR
A[会员打开小程序] --> B[查看会员卡列表]
B --> C[选择会员卡]
C --> D[确认购买]
D --> E[购买成功]
```
#### 3.4.3 业务规则
**会员卡类型规则**
- 支持时长卡、次卡、储值卡
- ✅ 场景1：会员购买30天时长卡，有效期从购买日起30天
- ✅ 场景2：会员购买10次次卡，获得10次团课预约权益
- ✅ 场景3：会员购买1000元储值卡，余额为1000元
- ✅ 场景4：会员购买组合卡（30天时长卡+5次次卡），同时获得时长和次数权益
- ❌ 场景5：会员购买不存在的会员卡类型，系统提示"会员卡类型不存在"
**到期提醒规则**
- 会员卡到期前7天提醒
- ✅ 场景1：会员卡2026-03-15到期，系统在2026-03-08发送提醒
- ✅ 场景2：会员卡2026-03-08到期，系统在2026-03-01发送提醒
- ✅ 场景3：会员卡2026-03-08到期，系统每天发送提醒直到到期
- ❌ 场景4：会员卡2026-03-08到期，系统在2026-03-09发送提醒（已过期）
**续费生效规则**
- 会员卡续费后权益立即生效
- ✅ 场景1：会员卡剩余5次，续费10次后剩余15次
- ✅ 场景2：会员卡2026-03-08到期，续费30天后有效期延长至2026-04-07
- ✅ 场景3：会员卡余额200元，续费500元后余额700元
- ✅ 场景4：会员卡已过期，续费后立即恢复使用
- ❌ 场景5：会员卡续费失败，原权益保持不变
**使用记录规则**
- 会员卡使用记录永久保存
- ✅ 场景1：会员预约团课，记录预约时间、课程信息、权益扣减
- ✅ 场景2：会员签到，记录签到时间、地点、权益扣减
- ✅ 场景3：会员购买会员卡，记录购买时间、金额、权益获得
- ✅ 场景4：会员卡过期，历史使用记录仍可查询
- ✅ 场景5：会员注销账户，使用记录保留用于数据分析
#### 3.4.4 异常处理
| 异常场景 | 处理方式 |
| -------- | -------------------- |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 提示用户重新发起支付 |
---
### 3.5 UI模版定制流程
#### 3.5.1 业务场景
租户通过管理后台的可视化配置器定制自己的UI，包括品牌元素、布局结构和预设模板。
#### 3.5.2 业务流程
```mermaid
flowchart LR
A[租户登录管理后台] --> B[打开UI定制器]
B --> C[品牌定制]
C --> D[布局调整]
D --> E[配置保存]
```
#### 3.5.3 业务规则
- 品牌元素应用范围包括小程序和管理后台
- 布局调整支持拖拽排序和模块隐藏
- 预设模板应用后保留品牌配置
- 配置变更实时生效，无需重新部署
- 配置变更自动记录到历史
#### 3.5.4 异常处理
| 异常场景 | 处理方式 |
| ------------ | -------------------- |
| Logo上传失败 | 提示用户重新上传 |
| 配置保存失败 | 提示用户检查配置格式 |
| 模板应用失败 | 提示用户调整品牌配置 |
| 配置回滚失败 | 提示用户选择其他版本 |
---
## 四、用户角色和权限
### 4.1 角色定义
| 角色 | 描述 | 主要职责 |
| ---------- | -------------- | ---------------------------- |
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息 |
| 教练 | 健身房教练 | 排课、团课签到管理 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
### 4.2 权限矩阵
| 功能模块 | 会员 | 教练 | 前台 | 店长 | 超级管理员 |
| ------------ | ---- | ---- | ---- | ---- | ---------- |
| 会员信息查看 | 自己 | 所有 | 所有 | 所有 | 所有 |
| 会员信息编辑 | 自己 | 无 | 所有 | 所有 | 所有 |
| 团课创建 | 无 | 是 | 否 | 是 | 是 |
| 团课编辑 | 无 | 自己 | 否 | 所有 | 所有 |
| 团课取消 | 无 | 自己 | 否 | 所有 | 所有 |
| 签到管理 | 无 | 是 | 是 | 是 | 是 |
| 数据统计查看 | 自己 | 自己 | 所有 | 所有 | 所有 |
| 系统配置 | 无 | 无 | 无 | 无 | 是 |
---
## 五、业务规则汇总
### 5.1 预约规则
| 规则名称 | 规则描述 |
| ---------------- | ---------------------------- |
| 预约时间限制 | 课程开始前至少30分钟 |
| 取消预约限制 | 课程开始前至少2小时 |
| 课程容量限制 | 每节课最多20人 |
| 权益扣减规则 | 预约成功后扣减权益 |
| 团课创建规则 | 需指定教练、时间、地点 |
| 团课取消规则 | 需提前24小时通知，自动退款 |
### 5.2 签到规则
| 规则名称 | 规则描述 |
| ---------------- | ---------------------------- |
| 会员卡验证规则 | 签到需验证会员卡有效性 |
| 预约验证规则 | 签到需验证预约信息（如有） |
| 签到记录规则 | 签到成功后记录到店时间 |
### 5.3 会员卡规则
| 规则名称 | 规则描述 |
| ---------------- | ---------------------------- |
| 会员卡类型规则 | 支持时长卡、次卡、储值卡 |
| 到期提醒规则 | 会员卡到期前7天提醒 |
| 续费生效规则 | 会员卡续费后权益立即生效 |
| 使用记录规则 | 会员卡使用记录永久保存 |
### 5.4 UI定制规则
| 规则名称 | 规则描述 |
| ---------------- | ---------------------------- |
| 品牌元素应用 | 应用范围包括小程序和管理后台 |
| 布局调整规则 | 支持拖拽排序和模块隐藏 |
| 预设模板规则 | 应用后保留品牌配置 |
| 配置生效规则 | 配置变更实时生效 |
| 配置历史规则 | 配置变更自动记录到历史 |
---
## 六、异常处理汇总
| 异常场景 | 处理方式 |
| ---------------- | ---------------------------- |
| 手机号已存在 | 提示用户直接登录 |
| 验证码错误 | 提示用户重新输入 |
| 验证码过期 | 提示用户重新获取 |
| 课程已满 | 提示用户选择其他课程 |
| 会员卡权益不足 | 提示用户购买会员卡 |
| 预约时间过短 | 提示用户提前预约 |
| 会员卡无效 | 提示用户购买会员卡 |
| 会员卡过期 | 提示用户续费 |
| 签到码无效 | 提示用户重新扫描 |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 提示用户重新发起支付 |
| Logo上传失败 | 提示用户重新上传 |
| 配置保存失败 | 提示用户检查配置格式 |
| 模板应用失败 | 提示用户调整品牌配置 |
| 配置回滚失败 | 提示用户选择其他版本 |
---
## 七、附录
### 7.1 业务流程图索引
| 流程名称 | 图表位置 |
| ---------------- | ------------ |
| 会员注册流程 | 3.1.2 |
| 会员预约团课流程 | 3.2.2 |
| 教练创建团课流程 | 3.2.2 |
| 签到流程 | 3.3.2 |
| 会员卡购买流程 | 3.4.2 |
| UI模版定制流程 | 3.5.2 |
### 7.2 业务规则索引
| 规则分类 | 规则名称 | 图表位置 |
| ---------------- | ---------------- | ------------ |
| 预约规则 | 预约时间限制 | 5.1 |
| 预约规则 | 取消预约限制 | 5.1 |
| 预约规则 | 课程容量限制 | 5.1 |
| 预约规则 | 权益扣减规则 | 5.1 |
| 预约规则 | 团课创建规则 | 5.1 |
| 预约规则 | 团课取消规则 | 5.1 |
| 签到规则 | 会员卡验证规则 | 5.2 |
| 签到规则 | 预约验证规则 | 5.2 |
| 签到规则 | 签到记录规则 | 5.2 |
| 会员卡规则 | 会员卡类型规则 | 5.3 |
| 会员卡规则 | 到期提醒规则 | 5.3 |
| 会员卡规则 | 续费生效规则 | 5.3 |
| 会员卡规则 | 使用记录规则 | 5.3 |
| UI定制规则 | 品牌元素应用 | 5.4 |
| UI定制规则 | 布局调整规则 | 5.4 |
| UI定制规则 | 预设模板规则 | 5.4 |
| UI定制规则 | 配置生效规则 | 5.4 |
| UI定制规则 | 配置历史规则 | 5.4 |
---
**文档结束**
docs/design/business/B-LLD-付费订阅版-业务详细设计.md
-414
View File
@@ -1,414 +0,0 @@
# 健身房管理系统付费订阅版业务详细设计文档（B-LLD）
> 文档编号: GYM-B-LLD-SUBSCRIPTION-001
> 版本: v1.0
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 已发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------------------------- |
| v1.0 | 2026-03-08 | 张翔 | 创建付费订阅版业务详细设计文档 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统付费订阅版的业务详细设计文档（Business Low-Level Design），旨在：
1. 详细描述业务数据流转、业务指标
2. 为技术实现提供详细的业务指导
3. 作为业务分析师、开发人员的业务参考
### 1.2 项目背景
健身房管理系统付费订阅版在基础版基础上，提供丰富的增值功能，满足中大型健身房、连锁品牌等复杂场景需求。
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
| 订阅模块(Subscription Module) | 按需订阅的增值功能模块 |
| 配置继承(Configuration Inheritance) | 门店配置继承租户配置的机制 |
### 1.4 参考文档
- 《健身房管理系统付费订阅版产品设计文档》 GYM-PRD-SUBSCRIPTION-001
- 《健身房管理系统付费订阅版业务概要设计文档》 GYM-B-HLD-SUBSCRIPTION-001
---
## 二、业务数据流转
### 2.1 订阅数据流转
```mermaid
flowchart LR
A[租户订阅模块] --> B[创建订阅记录]
B --> C[启用模块功能]
C --> D[模块使用统计]
D --> E[计费周期结算]
E --> F[发送账单]
F --> G[支付确认]
G --> H[续费提醒]
H --> A
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#ffe1e1
style G fill:#e1ffe1
```
### 2.2 配置数据流转
```mermaid
flowchart LR
A[租户级配置] --> B[门店继承配置]
B --> C[门店级配置覆盖]
C --> D[配置生效]
D --> E[配置版本记录]
E --> F[配置变更回滚]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#ffe1e1
```
### 2.3 私教预约数据流转
```mermaid
flowchart LR
A[会员预约私教] --> B[创建预约记录]
B --> C[扣减会员权益]
C --> D[发送预约提醒]
D --> E[私教签到]
E --> F[记录考勤]
F --> G[私教评价]
G --> H[数据统计]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style H fill:#ffe1e1
```
### 2.4 营销活动数据流转
```mermaid
flowchart LR
A[创建营销活动] --> B[配置活动规则]
B --> C[发布活动]
C --> D[会员参与活动]
D --> E[发放活动奖励]
E --> F[活动效果统计]
F --> G[活动数据分析]
G --> H[生成活动报告]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style H fill:#ffe1e1
```
### 2.5 智能获客数据流转
```mermaid
flowchart LR
A[创建获客活动] --> B[生成推广素材]
B --> C[分发到渠道]
C --> D[用户点击链接]
D --> E[记录推荐关系]
E --> F[用户注册]
F --> G[发放推荐奖励]
G --> H[获客效果统计]
H --> I[获客数据分析]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style I fill:#ffe1e1
```
### 2.6 智能体测数据流转
```mermaid
flowchart LR
A[会员进行体测] --> B[设备上传数据]
B --> C[系统数据转换]
C --> D[数据存储到档案]
D --> E[数据分析]
E --> F[生成体测报告]
F --> G[会员查看报告]
G --> H[历史数据对比]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style H fill:#ffe1e1
```
### 2.7 器械预约数据流转
```mermaid
flowchart LR
A[会员预约器械] --> B[创建预约记录]
B --> C[锁定器械时段]
C --> D[发送预约提醒]
D --> E[会员到店使用]
E --> F[记录使用时长]
F --> G[释放器械]
G --> H[器械使用统计]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style H fill:#ffe1e1
```
### 2.8 人脸识别签到数据流转
```mermaid
flowchart LR
A[会员到店] --> B[人脸识别]
B --> C{识别结果}
C -->|成功| D[验证会员卡]
D --> E{验证结果}
E -->|有效| F[签到成功]
E -->|无效| G[提示会员卡无效]
C -->|失败| H[降级为扫码签到]
F --> I[记录到店时间]
G --> H
H --> I
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#fff4e1
style H fill:#ffe1e1
```
### 2.9 NFC签到数据流转
```mermaid
flowchart LR
A[会员到店] --> B[刷NFC卡]
B --> C[读取NFC信息]
C --> D[验证会员卡]
D --> E{验证结果}
E -->|有效| F[签到成功]
E -->|无效| G[提示会员卡无效]
F --> H{是否需要储物柜}
H -->|是| I[自动开锁储物柜]
H -->|否| J[记录到店时间]
I --> J
G --> K[降级为扫码签到]
K --> J
style A fill:#e1f5ff
style E fill:#fff4e1
style H fill:#fff4e1
style K fill:#ffe1e1
```
### 2.10 在线课程数据流转
```mermaid
flowchart LR
A[教练发布课程] --> B[上传课程视频]
B --> C[发布课程]
C --> D[会员预约课程]
D --> E[发送预约提醒]
E --> F[会员观看课程]
F --> G[记录观看时长]
G --> H[会员评价课程]
H --> I[课程数据统计]
style A fill:#e1f5ff
style C fill:#fff4e1
style E fill:#e1ffe1
style I fill:#ffe1e1
```
---
## 三、业务指标
### 3.1 核心业务指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 预约成功率 | ≥ 95% | 成功预约次数 / 总预约次数 |
| 签到耗时 | ≤ 3秒 | 签到请求到签到完成的时间 |
| 人工处理时间减少 | 50% | (优化前时间 - 优化后时间) / 优化前时间 |
| 数据报表使用率 | ≥ 80% | 使用报表的用户数 / 总用户数 |
| 新会员激活率 | ≥ 70% | 7天内首次到店的新会员数 / 新会员总数 |
| 会员流失率 | ≤ 10% | 流失会员数 / 总会员数 |
| 投诉处理满意度 | ≥ 90% | 满意投诉数 / 总投诉数 |
| 会员留存率 | ≥ 80% | 留存会员数 / 总会员数 |
### 3.2 运营指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 团课满课率 | ≥ 80% | 满员课程数 / 总课程数 |
| 会员活跃度 | ≥ 60% | 活跃会员数 / 总会员数 |
| 会员续费率 | ≥ 70% | 续费会员数 / 到期会员数 |
| 会员卡使用率 | ≥ 85% | 使用会员卡的会员数 / 持卡会员数 |
| 私教预约成功率 | ≥ 90% | 成功预约私教次数 / 总预约次数 |
| 营销活动参与率 | ≥ 50% | 参与活动的会员数 / 总会员数 |
| 推荐转化率 | ≥ 20% | 推荐成功注册数 / 推荐链接点击数 |
| 获客成本 | ≤ 100元 | 获客总成本 / 新增会员数 |
### 3.3 订阅指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 订阅转化率 | ≥ 30% | 订阅租户数 / 总租户数 |
| 订阅续费率 | ≥ 80% | 续费订阅数 / 到期订阅数 |
| 模块使用率 | ≥ 70% | 使用模块的租户数 / 订阅该模块的租户数 |
| 订阅ARPU | ≥ 1000元 | 订阅总收入 / 订阅租户数 |
### 3.4 技术指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| API响应时间 | ≤ 500ms | API请求到响应完成的时间 |
| 系统可用性 | ≥ 99.9% | 系统正常运行时间 / 总时间 |
| 并发用户数 | 500 | 系统支持的最大并发用户数 |
| 数据库查询时间 | ≤ 1s | 数据库查询的响应时间 |
| 人脸识别准确率 | ≥ 95% | 人脸识别成功次数 / 总识别次数 |
---
## 四、业务规则补充
### 4.1 订阅计费规则
| 规则类型 | 规则描述 |
| ------------ | ---------------------------- |
| 基础版月费 | ¥299/月，标准价格 |
| 基础版季费 | ¥269/月，9折优惠 |
| 基础版半年费 | ¥254/月，85折优惠 |
| 基础版年费 | ¥239/月，8折优惠 |
| 订阅模块定价 | ¥199-499/月，按模块定价 |
| 试用时长 | 14天免费试用 |
| 组合折扣 | 订阅模块数量越多折扣越大，详见PRD动态折扣规则 |
### 4.2 营销活动效果评估规则
| 规则类型 | 规则描述 |
| ------------ | ---------------------------- |
| 活动参与率 | 参与活动的会员数 / 目标会员数 |
| 活动转化率 | 完成活动的会员数 / 参与活动的会员数 |
| 活动ROI | 活动收益 / 活动成本 |
| 活动满意度 | 满意会员数 / 参与活动的会员数 |
### 4.3 推荐奖励规则
| 规则类型 | 规则描述 |
| ------------ | ---------------------------- |
| 推荐奖励 | 推荐成功注册，推荐人获得100元优惠券 |
| 被推荐奖励 | 被推荐人注册成功，获得50元优惠券 |
| 多级推荐 | 支持3级推荐，每级奖励递减 |
| 奖励发放 | 推荐成功后24小时内自动发放 |
### 4.4 体测数据管理规则
| 规则类型 | 规则描述 |
| ------------ | ---------------------------- |
| 数据保留期限 | 体测数据永久保存 |
| 数据对比 | 支持最近10次体测数据对比 |
| 报告生成 | 体测完成后10分钟内生成报告 |
| 数据分享 | 支持会员分享体测报告到社交平台 |
### 4.5 器械使用规则
| 规则类型 | 规则描述 |
| ------------ | ---------------------------- |
| 预约超时 | 超时10分钟自动释放器械 |
| 使用统计 | 记录器械使用时长和次数 |
| 维护提醒 | 器械使用达到100小时后提醒维护 |
| 预约取消 | 取消预约后释放器械时段 |
---
## 五、附录
### 5.1 业务术语表
| 术语 | 定义 |
| ----------------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课、私教、场地、线上课程等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
| 订阅模块(Subscription Module) | 按需订阅的增值功能模块 |
| 配置继承(Configuration Inheritance) | 门店配置继承租户配置的机制 |
### 5.2 参考文档
- 《健身房管理系统付费订阅版产品设计文档》 GYM-PRD-SUBSCRIPTION-001
- 《健身房管理系统付费订阅版业务概要设计文档》 GYM-B-HLD-SUBSCRIPTION-001
- 《健身房管理系统付费订阅版技术实现详细设计文档》 GYM-T-ILD-SUBSCRIPTION-001
### 5.3 业务数据流转图索引
| 流程名称 | 图表位置 |
| ---------------- | ------------ |
| 订阅数据流转 | 2.1 |
| 配置数据流转 | 2.2 |
| 私教预约数据流转 | 2.3 |
| 营销活动数据流转 | 2.4 |
| 智能获客数据流转 | 2.5 |
| 智能体测数据流转 | 2.6 |
| 器械预约数据流转 | 2.7 |
| 人脸识别签到数据流转 | 2.8 |
| NFC签到数据流转 | 2.9 |
| 在线课程数据流转 | 2.10 |
### 5.4 业务指标索引
| 指标分类 | 指标名称 | 图表位置 |
| ---------------- | ---------------- | ------------ |
| 核心业务指标 | 预约成功率 | 3.1 |
| 核心业务指标 | 签到耗时 | 3.1 |
| 核心业务指标 | 人工处理时间减少 | 3.1 |
| 核心业务指标 | 数据报表使用率 | 3.1 |
| 核心业务指标 | 新会员激活率 | 3.1 |
| 核心业务指标 | 会员流失率 | 3.1 |
| 核心业务指标 | 投诉处理满意度 | 3.1 |
| 核心业务指标 | 会员留存率 | 3.1 |
| 运营指标 | 团课满课率 | 3.2 |
| 运营指标 | 会员活跃度 | 3.2 |
| 运营指标 | 会员续费率 | 3.2 |
| 运营指标 | 会员卡使用率 | 3.2 |
| 运营指标 | 私教预约成功率 | 3.2 |
| 运营指标 | 营销活动参与率 | 3.2 |
| 运营指标 | 推荐转化率 | 3.2 |
| 运营指标 | 获客成本 | 3.2 |
| 订阅指标 | 订阅转化率 | 3.3 |
| 订阅指标 | 订阅续费率 | 3.3 |
| 订阅指标 | 模块使用率 | 3.3 |
| 订阅指标 | 订阅ARPU | 3.3 |
| 技术指标 | API响应时间 | 3.4 |
| 技术指标 | 系统可用性 | 3.4 |
| 技术指标 | 并发用户数 | 3.4 |
| 技术指标 | 数据库查询时间 | 3.4 |
| 技术指标 | 人脸识别准确率 | 3.4 |
---
**文档结束**
docs/design/business/B-LLD-基础版
-856
View File
@@ -1,856 +0,0 @@
# 健身房管理系统基础版业务详细设计文档（B-LLD）
> 文档编号: GYM-B-LLD-BASIC-001
> 版本: v1.0
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 已发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ---------------------- |
| v1.0 | 2026-03-08 | 张翔 | 创建基础版业务详细设计文档 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统基础版的业务详细设计文档（Business Low-Level Design），旨在：
1. 详细描述业务流程、业务规则、异常处理
2. 为技术实现提供详细的业务指导
3. 作为业务分析师、开发人员的业务参考
### 1.2 项目背景
健身房管理系统基础版是面向小型工作室、个人教练等场景的核心版本，保证业务闭环，提供完整的会员管理、预约、签到等核心功能。
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 1.4 参考文档
- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
- 《健身房管理系统基础版业务概要设计文档》 GYM-B-HLD-BASIC-001
---
## 二、详细业务流程
### 2.1 会员全生命周期流程
#### 2.1.1 业务场景
从会员注册到流失的完整生命周期管理，包括新会员激活、活跃期维护、沉默期干预、流失预警和挽回。
#### 2.1.2 业务流程
```mermaid
flowchart LR
A[新会员注册] --> B[首次到店引导]
B --> C[新会员激活期<br/>7天内完成首次到店]
C --> D[活跃期维护<br/>持续到店和消费]
D --> E{活跃度评估}
E -->|活跃| F[持续运营<br/>推送个性化内容]
E -->|沉默| G[沉默期干预<br/>7天未到店触发]
G --> H{干预效果}
H -->|成功| D
H -->|失败| I[流失预警<br/>30天未到店触发]
I --> J{挽回策略}
J -->|挽回成功| D
J -->|挽回失败| K[会员流失<br/>标记为流失状态]
K --> L[归档分析<br/>流失原因分析]
style A fill:#e1f5ff
style C fill:#fff4e1
style G fill:#ffe1e1
style I fill:#ffe1e1
style K fill:#ffcccc
```
#### 2.1.3 业务规则
**新会员激活期规则**
- 注册后7天内完成首次到店，否则进入沉默期干预
- ✅ 场景1：会员2026-03-01注册，2026-03-07首次到店，激活成功
- ✅ 场景2：会员2026-03-01注册，2026-03-08首次到店，激活成功
- ❌ 场景3：会员2026-03-01注册，2026-03-09首次到店，已进入沉默期干预
- ❌ 场景4：会员2026-03-01注册，2026-03-15首次到店，已进入流失预警
**活跃期定义规则**
- 30天内至少到店2次或消费1次
- ✅ 场景1：会员30天内到店2次，保持活跃状态
- ✅ 场景2：会员30天内到店1次但消费1次，保持活跃状态
- ✅ 场景3：会员30天内到店3次，保持活跃状态
- ❌ 场景4：会员30天内到店1次且未消费，进入沉默期
- ❌ 场景5：会员30天内未到店但消费1次，保持活跃状态
**沉默期触发规则**
- 7天未到店触发沉默期干预
- ✅ 场景1：会员最后到店2026-03-01，2026-03-08触发沉默期干预
- ✅ 场景2：会员最后到店2026-03-01，2026-03-09仍处于沉默期
- ✅ 场景3：会员沉默期干预成功，到店后重新计算活跃期
- ❌ 场景4：会员最后到店2026-03-01，2026-03-07未触发沉默期干预
**沉默期干预策略**
- 发送个性化关怀短信
- 提供专属优惠券
- 推荐适合的团课
- 教练主动联系
- ✅ 场景1：会员沉默7天，发送关怀短信"好久不见，期待您的到来"
- ✅ 场景2：会员沉默7天，提供专属优惠券"限时9折优惠"
- ✅ 场景3：会员沉默7天，推荐适合的团课"瑜伽课程适合您"
- ✅ 场景4：会员沉默7天，教练主动电话联系
- ❌ 场景5：会员沉默7天，未采取任何干预措施
**流失预警规则**
- 30天未到店触发流失预警
- ✅ 场景1：会员最后到店2026-02-01，2026-03-03触发流失预警
- ✅ 场景2：会员最后到店2026-02-01，2026-03-04启动挽回流程
- ✅ 场景3：会员挽回成功，到店后重新计算活跃期
- ❌ 场景4：会员最后到店2026-02-01，2026-03-02未触发流失预警
**流失定义规则**
- 90天未到店且未消费
- ✅ 场景1：会员最后到店2026-01-01，2026-04-01标记为流失状态
- ✅ 场景2：会员最后到店2026-01-01，2026-03-31仍处于流失预警期
- ✅ 场景3：会员90天内未到店但消费1次，不标记为流失
- ❌ 场景4：会员最后到店2026-01-01，2026-03-31标记为流失状态（错误）
**挽回策略规则**
- 根据会员等级和历史行为制定个性化挽回方案
- ✅ 场景1：VIP会员流失预警，提供专属私教课程优惠
- ✅ 场景2：普通会员流失预警，发送关怀短信和优惠券
- ✅ 场景3：高消费会员流失预警，客服主动电话联系
- ❌ 场景4：流失预警会员未制定挽回方案，系统自动发送通用短信
**流失归档规则**
- 流失会员归档保存，用于流失原因分析
- ✅ 场景1：会员标记为流失，归档保存所有历史数据
- ✅ 场景2：会员流失后重新激活，归档数据仍保留用于分析
- ✅ 场景3：定期分析流失会员数据，生成流失原因报告
- ❌ 场景4：会员标记为流失，删除历史数据（错误）
#### 2.1.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 新会员激活失败 | 发送个性化邀请短信，提供首次到店优惠 |
| 沉默期干预无效 | 升级干预策略，提供专属优惠或服务 |
| 流失预警触发 | 启动挽回流程，由客服主动联系 |
| 会员数据异常 | 标记异常状态，暂停自动化运营，人工介入处理 |
---
### 2.2 支付与退款全流程
#### 2.2.1 业务场景
会员购买会员卡、私教课程等服务的支付流程，以及退款申请、审批、退款、财务对账的完整流程。
#### 2.2.2 业务流程
```mermaid
flowchart TB
subgraph 支付流程
A[会员发起支付] --> B[选择支付方式]
B --> C[创建支付订单]
C --> D[调用支付网关]
D --> E{支付结果}
E -->|成功| F[更新订单状态]
F --> G[发放会员卡权益]
G --> H[发送支付成功通知]
E -->|失败| I[记录支付失败]
I --> J[提示用户重新支付]
end
subgraph 退款流程
K[会员申请退款] --> L[填写退款原因]
L --> M[提交退款申请]
M --> N{退款类型}
N -->|自动退款| O[系统自动审核]
N -->|人工审核| P[店长审核]
P --> Q{审核结果}
Q -->|通过| R[财务专员复核]
Q -->|拒绝| S[通知会员拒绝原因]
O --> R
R --> T{复核结果}
T -->|通过| U[调用退款接口]
T -->|拒绝| S
U --> V[更新订单状态]
V --> W[收回会员卡权益]
W --> X[发送退款成功通知]
X --> Y[财务对账]
end
style E fill:#fff4e1
style Q fill:#fff4e1
style T fill:#fff4e1
style K fill:#e1f5ff
```
#### 2.2.3 业务规则
**支付方式规则**
- 支持微信支付、支付宝、银行卡支付
- ✅ 场景1：会员选择微信支付，调用微信支付接口
- ✅ 场景2：会员选择支付宝，调用支付宝接口
- ✅ 场景3：会员选择银行卡，调用银行卡支付接口
- ❌ 场景4：会员选择不支持的支付方式，提示"暂不支持该支付方式"
**支付超时规则**
- 订单创建后30分钟内未支付自动取消
- ✅ 场景1：订单18:00创建，18:30未支付，订单自动取消
- ✅ 场景2：订单18:00创建，18:29支付，支付成功
- ❌ 场景3：订单18:00创建，18:31支付，支付失败提示"订单已取消"
- ❌ 场景4：订单18:00创建，18:00支付，支付成功
**自动退款条件规则**
- 7天内购买且未使用的会员卡、私教课程
- ✅ 场景1：会员购买会员卡后第1天申请退款，未使用，自动退款
- ✅ 场景2：会员购买会员卡后第7天申请退款，未使用，自动退款
- ❌ 场景3：会员购买会员卡后第8天申请退款，未使用，需人工审核
- ❌ 场景4：会员购买会员卡后第1天申请退款，已使用，需人工审核
**人工审核条件规则**
- 超过7天、已使用部分权益、金额超过1000元
- ✅ 场景1：会员购买会员卡后第8天申请退款，需人工审核
- ✅ 场景2：会员购买会员卡后第1天申请退款，已使用，需人工审核
- ✅ 场景3：会员购买1500元会员卡后第1天申请退款，需人工审核
- ❌ 场景4：会员购买会员卡后第7天申请退款，未使用，金额500元，自动退款
**退款时效规则**
- 审核通过后1-3个工作日到账
- ✅ 场景1：退款审核通过，第1个工作日到账
- ✅ 场景2：退款审核通过，第3个工作日到账
- ❌ 场景3：退款审核通过，第4个工作日到账（超时）
**财务对账规则**
- 每日自动对账，异常订单人工处理
- ✅ 场景1：系统每日凌晨自动对账，生成对账报告
- ✅ 场景2：对账发现异常订单，标记异常，财务专员人工核查
- ❌ 场景3：对账发现异常订单，未标记异常（错误）
**退款手续费规则**
- 7天内无手续费，7-30天收取5%手续费，30天以上收取10%手续费
- ✅ 场景1：会员购买会员卡后第1天申请退款，无手续费
- ✅ 场景2：会员购买会员卡后第15天申请退款，收取5%手续费
- ✅ 场景3：会员购买会员卡后第45天申请退款，收取10%手续费
- ❌ 场景4：会员购买会员卡后第1天申请退款，收取5%手续费（错误）
#### 2.2.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 支付超时 | 订单自动取消，释放库存和权益 |
| 支付重复 | 检测重复支付，自动退款重复金额 |
| 退款失败 | 重试3次，失败后人工介入处理 |
| 财务对账异常 | 标记异常订单，财务专员人工核查 |
| 退款申请超时 | 退款申请提交后48小时内未处理自动升级 |
---
### 2.3 投诉与反馈处理流程
#### 2.3.1 业务场景
会员提交投诉或反馈，系统自动分类、分配、处理、反馈，并进行满意度调查和归档分析。
#### 2.3.2 业务流程
```mermaid
flowchart LR
A[会员提交投诉/反馈] --> B[填写投诉详情]
B --> C[选择投诉类型]
C --> D[上传相关凭证]
D --> E[提交投诉]
E --> F[系统自动分类]
F --> G{投诉类型}
G -->|服务投诉| H[分配给店长]
G -->|设施投诉| I[分配给运营管理员]
G -->|财务投诉| J[分配给财务专员]
G -->|技术投诉| K[分配给技术支持]
H --> L[处理人接收]
I --> L
J --> L
K --> L
L --> M[调查处理]
M --> N{处理结果}
N -->|解决| O[反馈处理结果]
N -->|无法解决| P[升级处理]
P --> Q[上级介入处理]
Q --> O
O --> R[会员确认]
R --> S{满意度调查}
S -->|满意| T[归档分析]
S -->|不满意| U[重新处理]
U --> M
style A fill:#e1f5ff
style F fill:#fff4e1
style N fill:#fff4e1
style S fill:#ffe1e1
```
#### 2.3.3 业务规则
**投诉分类规则**
- 服务投诉、设施投诉、财务投诉、技术投诉、其他
- ✅ 场景1：会员投诉教练服务态度，分类为服务投诉
- ✅ 场景2：会员投诉器械损坏，分类为设施投诉
- ✅ 场景3：会员投诉退款问题，分类为财务投诉
- ✅ 场景4：会员投诉系统故障，分类为技术投诉
- ✅ 场景5：会员投诉其他问题，分类为其他
**响应时效规则**
- 投诉提交后2小时内响应
- ✅ 场景1：投诉14:00提交，16:00前响应
- ✅ 场景2：投诉14:00提交，15:59响应
- ❌ 场景3：投诉14:00提交，16:01响应（超时）
**处理时效规则**
- 一般投诉24小时内处理完毕，复杂投诉48小时内处理完毕
- ✅ 场景1：一般投诉14:00提交，次日14:00前处理完毕
- ✅ 场景2：复杂投诉14:00提交，后日14:00前处理完毕
- ❌ 场景3：一般投诉14:00提交，次日14:01处理完毕（超时）
**升级机制规则**
- 处理人无法解决时自动升级给上级
- ✅ 场景1：店长无法解决服务投诉，自动升级给运营管理员
- ✅ 场景2：运营管理员无法解决设施投诉，自动升级给超级管理员
- ❌ 场景3：处理人无法解决投诉，未升级（错误）
**满意度调查规则**
- 投诉处理完成后自动发送满意度调查
- ✅ 场景1：投诉处理完成，系统自动发送满意度调查问卷
- ✅ 场景2：会员完成满意度调查，系统记录满意度评分
- ❌ 场景3：投诉处理完成，未发送满意度调查（错误）
**归档分析规则**
- 投诉归档后进行分类统计和原因分析
- ✅ 场景1：投诉归档，系统自动分类统计
- ✅ 场景2：定期分析投诉数据，生成投诉原因报告
- ❌ 场景3：投诉归档，未进行分类统计（错误）
**投诉闭环规则**
- 所有投诉必须闭环处理，不得遗漏
- ✅ 场景1：投诉处理完成，会员确认，归档
- ✅ 场景2：投诉处理完成，会员不满意，重新处理，会员确认，归档
- ❌ 场景3：投诉处理完成，未会员确认，归档（错误）
#### 2.3.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 投诉信息不完整 | 提示会员补充必要信息 |
| 处理人未响应 | 2小时未响应自动升级给上级 |
| 处理超时 | 24小时未处理自动升级给店长 |
| 会员不满意 | 重新处理，升级处理级别 |
| 投诉重复提交 | 合并重复投诉，关联处理 |
---
### 2.4 UI 模版定制流程
#### 2.4.1 业务场景
店长通过管理后台自定义系统 UI 样式，包括品牌色、Logo、布局等，提升品牌形象。
#### 2.4.2 业务流程
```mermaid
flowchart LR
A[店长登录管理后台] --> B[进入 UI 定制页面]
B --> C[选择预设模板]
C --> D[自定义品牌色]
D --> E[上传 Logo]
E --> F[预览效果]
F --> G{是否满意}
G -->|是 | H[保存配置]
G -->|否 | D
H --> I[配置生效]
```
#### 2.4.3 业务规则
**预设模板规则**
- 系统提供 3 套预设模板（现代简约、活力运动、高端奢华）
- ✅ 场景 1：店长选择"现代简约"模板，系统应用蓝色系配色
- ✅ 场景 2：店长选择"活力运动"模板，系统应用橙色系配色
- ✅ 场景 3：店长选择"高端奢华"模板，系统应用黑色系配色
- ❌ 场景 4：店长选择不存在的模板，系统提示"模板不存在"
**品牌色自定义规则**
- 支持自定义主色、辅色、强调色
- ✅ 场景 1：店长设置主色为#FF5722，系统所有主按钮变为橙色
- ✅ 场景 2：店长设置辅色为#2196F3，系统次要元素变为蓝色
- ✅ 场景 3：店长同时设置主色和辅色，系统整体配色更新
- ❌ 场景 4：店长设置无效颜色代码，系统提示"颜色格式错误"
**Logo 上传规则**
- 支持 PNG、JPG 格式，最大 2MB
- ✅ 场景 1：店长上传 500KB 的 PNG Logo，上传成功
- ✅ 场景 2：店长上传 1.5MB 的 JPG Logo，上传成功
- ❌ 场景 3：店长上传 3MB 的 PNG Logo，系统提示"文件超过 2MB 限制"
- ❌ 场景 4：店长上传 GIF 格式 Logo，系统提示"仅支持 PNG、JPG 格式"
**配置生效规则**
- 配置保存后立即生效，所有用户端同步更新
- ✅ 场景 1：店长 10:00 保存配置，会员 10:01 打开小程序看到新 UI
- ✅ 场景 2：店长保存配置后，教练端 App 立即同步新 UI
- ✅ 场景 3：店长保存配置后，管理后台 PC 端立即同步新 UI
- ❌ 场景 4：店长保存配置后，部分用户端未同步，系统自动刷新缓存
#### 2.4.4 业务数据流转
```mermaid
flowchart LR
A[店长配置 UI 参数] --> B[保存到配置表]
B --> C[发布配置变更事件]
C --> D[CDN 刷新缓存]
D --> E[用户端拉取新配置]
E --> F[应用新 UI 样式]
```
**配置数据结构**：
```json
{
"template_id": "modern_simple",
"brand_colors": {
"primary": "#FF5722",
"secondary": "#2196F3",
"accent": "#FFC107"
},
"logo": {
"url": "https://cdn.gym-manage.com/logos/tenant_001.png",
"upload_time": "2026-03-08T10:00:00Z",
"file_size": 524288
},
"layout": {
"header_style": "fixed",
"sidebar_style": "dark",
"card_radius": "8px"
},
"version": 3,
"updated_at": "2026-03-08T10:00:00Z"
}
```
#### 2.4.5 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| Logo 上传失败 | 提示"上传失败，请重试"，支持重新上传 |
| 配置保存失败 | 自动重试 3 次，失败后提示"保存失败，请检查网络" |
| CDN 刷新失败 | 自动重试，降级为用户端主动刷新 |
| 配置版本冲突 | 提示"配置已被他人修改，请刷新后重试" |
## 三、业务数据流转
### 3.1 会员数据流转
```mermaid
flowchart LR
A[会员注册] --> B[创建会员档案]
B --> C[购买会员卡]
C --> D[获得权益]
D --> E[预约团课]
E --> F[扣减权益]
F --> G[签到]
G --> H[记录到店]
H --> I[消费记录]
I --> J[数据统计]
```
### 3.2 权益数据流转
```mermaid
flowchart LR
A[购买会员卡] --> B[发放权益]
B --> C[预约扣减]
C --> D[签到扣减]
D --> E[权益使用记录]
E --> F[权益查询]
F --> G[权益续费]
G --> B
```
---
## 四、业务规则汇总
### 4.1 时间相关规则
| 规则类型 | 时间要求 | 说明 |
| -------------- | ------------------ | ------------------------ |
| 预约时间 | 课程开始前30分钟 | 会员预约团课的最短时间 |
| 取消预约 | 课程开始前2小时 | 会员取消预约的最短时间 |
| 团课取消 | 提前24小时 | 教练取消团课的最短时间 |
| 支付超时 | 30分钟 | 订单未支付自动取消时间 |
| 新会员激活期 | 7天 | 新会员首次到店时间要求 |
| 沉默期触发 | 7天未到店 | 触发沉默期干预的时间 |
| 流失预警 | 30天未到店 | 触发流失预警的时间 |
| 流失定义 | 90天未到店 | 会员流失的时间定义 |
| 投诉响应 | 2小时 | 投诉响应时间要求 |
| 投诉处理 | 24-48小时 | 投诉处理完成时间 |
| 退款时效 | 1-3个工作日 | 退款到账时间 |
### 4.2 数量相关规则
| 规则类型 | 数量限制 | 说明 |
| ------------ | -------- | -------------- |
| 团课容量 | 20人 | 每节课最大人数 |
| 自动退款 | 7天内 | 自动退款条件 |
| 手续费7-30天 | 5% | 退款手续费 |
| 手续费30天以上 | 10% | 退款手续费 |
### 4.3 状态相关规则
| 规则类型 | 状态定义 | 说明 |
| ------------ | -------- | -------------- |
| 活跃期 | 30天内到店2次或消费1次 | 会员活跃状态 |
| 沉默期 | 7天未到店 | 会员沉默状态 |
| 流失预警 | 30天未到店 | 流失预警状态 |
| 流失 | 90天未到店且未消费 | 会员流失状态 |
---
## 五、业务异常处理
### 5.1 会员相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 手机号已存在 | 提示用户直接登录 |
| 验证码错误 | 提示用户重新输入 |
| 验证码过期 | 提示用户重新获取 |
| 会员卡无效 | 提示用户购买会员卡 |
| 会员卡过期 | 提示用户续费 |
| 会员卡权益不足 | 提示用户购买会员卡或续费 |
### 5.2 预约相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 课程已满 | 提示用户选择其他课程 |
| 会员卡权益不足 | 提示用户购买会员卡 |
| 预约时间过短 | 提示用户提前预约 |
| 团课取消过晚 | 系统提示"取消时间过晚" |
### 5.3 支付相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 订单自动取消，释放库存和权益 |
| 支付重复 | 检测重复支付，自动退款重复金额 |
| 退款失败 | 重试3次，失败后人工介入处理 |
| 财务对账异常 | 标记异常订单，财务专员人工核查 |
### 5.4 投诉相关异常
| 异常类型 | 处理方式 |
| -------------- | ---------------------------- |
| 投诉信息不完整 | 提示会员补充必要信息 |
| 处理人未响应 | 2小时未响应自动升级给上级 |
| 处理超时 | 24小时未处理自动升级给店长 |
| 会员不满意 | 重新处理，升级处理级别 |
| 投诉重复提交 | 合并重复投诉，关联处理 |
---
## 六、业务指标
### 6.1 核心业务指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 预约成功率 | ≥ 95% | 成功预约次数 / 总预约次数 |
| 签到耗时 | ≤ 3秒 | 签到请求到签到完成的时间 |
| 人工处理时间减少 | 50% | (优化前时间 - 优化后时间) / 优化前时间 |
| 数据报表使用率 | ≥ 80% | 使用报表的用户数 / 总用户数 |
| 新会员激活率 | ≥ 70% | 7天内首次到店的新会员数 / 新会员总数 |
| 会员流失率 | ≤ 10% | 流失会员数 / 总会员数 |
| 投诉处理满意度 | ≥ 90% | 满意投诉数 / 总投诉数 |
### 6.2 运营指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 团课满课率 | ≥ 80% | 满员课程数 / 总课程数 |
| 会员活跃度 | ≥ 60% | 活跃会员数 / 总会员数 |
| 会员续费率 | ≥ 70% | 续费会员数 / 到期会员数 |
| 会员卡使用率 | ≥ 85% | 使用会员卡的会员数 / 持卡会员数 |
---
### 6.3 UI 模版定制指标
| 指标名称 | 目标值 | 计算方式 | 说明 |
| ------------------ | ------------ | ---------------------------- | ---- |
| UI 模版定制使用率 | ≥ 60% | 使用 UI 定制的门店数 / 总门店数 | 衡量 UI 定制功能普及度 |
| UI 定制满意度 | ≥ 85% | 满意评价数 / 总评价数 | 店长对 UI 定制效果的满意度 |
| 配置生效时间 | ≤ 5 秒 | 配置保存到用户端生效的时间 | 配置更新的响应速度 |
| Logo 上传成功率 | ≥ 98% | 上传成功次数 / 总上传次数 | Logo 上传功能稳定性 |
| 模板选择率 | ≥ 70% | 选择预设模板的门店数 / 总门店数 | 预设模板的使用率 |
## 七、附录
### 7.1 业务术语表
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 7.2 参考文档
- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
- 《健身房管理系统基础版业务概要设计文档》 GYM-B-HLD-BASIC-001
- 《健身房管理系统基础版技术实现详细设计文档》 GYM-T-ILD-BASIC-001
### 7.3 业务流程图索引
| 流程名称 | 图表位置 |
| ---------------- | ------------ |
| 会员全生命周期流程 | 2.1.2 |
| 支付与退款全流程 | 2.2.2 |
| 投诉与反馈处理流程 | 2.3.2 |
| 会员数据流转 | 3.1 |
| 权益数据流转 | 3.2 |
### 7.4 业务规则索引
| 规则分类 | 规则名称 | 图表位置 |
| ---------------- | ---------------- | ------------ |
| 时间相关规则 | 预约时间 | 4.1 |
| 时间相关规则 | 取消预约 | 4.1 |
| 时间相关规则 | 团课取消 | 4.1 |
| 时间相关规则 | 支付超时 | 4.1 |
| 时间相关规则 | 新会员激活期 | 4.1 |
| 时间相关规则 | 沉默期触发 | 4.1 |
| 时间相关规则 | 流失预警 | 4.1 |
| 时间相关规则 | 流失定义 | 4.1 |
| 时间相关规则 | 投诉响应 | 4.1 |
| 时间相关规则 | 投诉处理 | 4.1 |
| 时间相关规则 | 退款时效 | 4.1 |
| 数量相关规则 | 团课容量 | 4.2 |
| 数量相关规则 | 自动退款 | 4.2 |
| 数量相关规则 | 手续费7-30天 | 4.2 |
| 数量相关规则 | 手续费30天以上 | 4.2 |
| 状态相关规则 | 活跃期 | 4.3 |
| 状态相关规则 | 沉默期 | 4.3 |
| 状态相关规则 | 流失预警 | 4.3 |
| 状态相关规则 | 流失 | 4.3 |
---
### 2.5 会员全生命周期管理流程
#### 2.5.1 业务场景
对会员从注册到流失的全生命周期进行管理，通过数据分析识别会员状态，采取针对性运营策略，提升会员留存率和生命周期价值。
#### 2.5.2 业务数据流转
```mermaid
flowchart TB
subgraph 会员全生命周期管理
A[会员注册] --> B[新手期 0-30 天]
B --> C{活跃度评估}
C -->|高活跃 | D[成长期 31-90 天]
C -->|低活跃 | E[预警干预]
D --> F{消费行为评估}
F -->|高价值 | G[成熟期 91-180 天]
F -->|低价值 | H[价值提升]
G --> I{续卡意愿评估}
I -->|高意愿 | J[忠诚期 180 天+]
I -->|低意愿 | K[流失预警]
J --> L[流失风险监测]
K --> M[挽留策略]
L --> N{流失判断}
N -->|已流失 | O[流失期]
N -->|未流失 | J
M --> P{挽留成功}
P -->|是 | D
P -->|否 | O
O --> Q[召回策略]
Q --> R{召回成功}
R -->|是 | B
R -->|否 | S[永久流失]
end
style A fill:#e8f5e9
style B fill:#fff4e1
style D fill:#fff4e1
style G fill:#e1f5ff
style J fill:#e8f5e9
style O fill:#ffebee
style S fill:#ffebee
```
#### 2.5.3 生命周期阶段定义
**新手期（0-30 天）**
- 定义：会员注册后的前 30 天
- 特征：对系统功能不熟悉，需要引导
- 运营策略：
- ✅ 新人礼包（优惠券、体验课）
- ✅ 新手引导任务（完善档案、首次预约、首次签到）
- ✅ 专属客服一对一服务
- ✅ 定期推送健身知识
- 关键指标：
- 新手任务完成率 ≥ 80%
- 首次预约转化率 ≥ 60%
- 首次签到转化率 ≥ 50%
**成长期（31-90 天）**
- 定义：注册 31-90 天，开始形成使用习惯
- 特征：活跃度逐步提升，开始规律到店
- 运营策略：
- ✅ 推荐适合的团课和教练
- ✅ 鼓励购买会员卡（次卡转时长卡）
- ✅ 邀请参加健身活动
- ✅ 建立健身目标追踪
- 关键指标：
- 月均到店次数 ≥ 8 次
- 会员卡购买转化率 ≥ 40%
- 团课预约频次 ≥ 4 次/月
**成熟期（91-180 天）**
- 定义：注册 91-180 天，高价值会员阶段
- 特征：高活跃度、高消费、高忠诚度
- 运营策略：
- ✅ 推荐私教课程
- ✅ 邀请参与会员活动
- ✅ 提供个性化训练计划
- ✅ 鼓励参与社交互动
- 关键指标：
- 月均到店次数 ≥ 12 次
- 私教课购买率 ≥ 30%
- 会员续卡率 ≥ 70%
**忠诚期（180 天+）**
- 定义：注册 180 天以上，核心忠实会员
- 特征：高度忠诚，主动推荐新会员
- 运营策略：
- ✅ VIP 专属权益
- ✅ 邀请成为品牌大使
- ✅ 推荐奖励计划
- ✅ 生日礼遇和周年祝福
- 关键指标：
- 续卡率 ≥ 85%
- 推荐新会员数 ≥ 2 人
- 月均到店次数 ≥ 15 次
**流失预警期**
- 定义：活跃度明显下降，有流失风险
- 特征：到店频次减少，预约取消增多
- 识别规则：
- ❗ 连续 15 天未到店
- ❗ 预约取消率 ≥ 30%
- ❗ 会员卡剩余权益使用率 < 20%
- 运营策略：
- ✅ 发送关怀短信/电话
- ✅ 提供专属优惠券
- ✅ 邀请参加特别活动
- ✅ 了解流失原因
- 关键指标：
- 预警响应率 ≥ 40%
- 预警挽回率 ≥ 30%
**流失期**
- 定义：会员卡到期后未续卡，或连续 30 天未到店
- 特征：已停止使用服务
- 识别规则：
- ❗ 会员卡到期后 7 天未续卡
- ❗ 连续 30 天未到店
- 运营策略：
- ✅ 发送召回优惠券（大额折扣）
- ✅ 电话回访了解原因
- ✅ 推送新店开业/新服务信息
- ✅ 提供无门槛体验课
- 关键指标：
- 召回成功率 ≥ 15%
- 召回后留存率 ≥ 50%
#### 2.5.4 业务规则
**生命周期阶段自动流转规则**
- 系统每日凌晨自动评估会员状态
- ✅ 场景 1：会员注册第 31 天，自动从新手期转入成长期
- ✅ 场景 2：会员连续 15 天未到店，自动标记为流失预警
- ✅ 场景 3：会员会员卡到期后 7 天未续卡，自动标记为流失期
- ❌ 场景 4：会员在流失预警期到店，自动取消预警状态
**活跃度评分规则**
- 基于到店频次、预约频次、消费金额计算活跃度评分
- 活跃度评分 = 到店频次×30% + 预约频次×30% + 消费金额×40%
- ✅ 场景 1：会员每周到店 3 次，预约 2 次，消费 500 元，活跃度评分 85 分
- ✅ 场景 2：会员每周到店 1 次，预约 1 次，消费 100 元，活跃度评分 45 分
- ❌ 场景 3：会员连续 2 周未到店，活跃度评分自动降为 20 分
**价值评估规则**
- 基于累计消费金额、消费频次、推荐人数计算会员价值
- 会员价值 = 累计消费×50% + 消费频次×30% + 推荐人数×20%
- ✅ 场景 1：会员累计消费 5000 元，消费 20 次，推荐 3 人，价值评分 90 分（高价值）
- ✅ 场景 2：会员累计消费 1000 元，消费 5 次，推荐 0 人，价值评分 40 分（低价值）
**自动触达规则**
- 根据生命周期阶段自动触发触达策略
- ✅ 场景 1：会员进入新手期，自动发送新人礼包
- ✅ 场景 2：会员进入流失预警期，自动发送关怀短信
- ✅ 场景 3：会员进入流失期，自动发送召回优惠券
- ❌ 场景 4：会员一天内收到超过 2 条触达消息，系统自动抑制
#### 2.5.5 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 生命周期阶段判断错误 | 支持人工调整，系统记录调整原因 |
| 自动触达失败 | 重试 3 次，失败后标记为"触达失败"，人工介入 |
| 数据计算错误 | 支持手动重新计算，系统记录异常日志 |
| 会员投诉骚扰 | 立即加入黑名单，停止所有自动触达 |
| 系统性能问题 | 分批次计算，优先处理高价值会员 |
#### 2.5.6 业务指标
| 指标名称 | 目标值 | 计算方式 | 说明 |
|---------|--------|---------|------|
| 新手期转化率 | ≥ 60% | 成长期会员数 / 新手期会员数 | 新手期会员转化为成长期的比例 |
| 成长期留存率 | ≥ 70% | 成熟期会员数 / 成长期会员数 | 成长期会员留存到成熟期的比例 |
| 成熟期续卡率 | ≥ 75% | 续卡会员数 / 到期会员数 | 成熟期会员续卡的比例 |
| 忠诚期推荐率 | ≥ 30% | 推荐新会员的忠诚会员数 / 忠诚会员总数 | 忠诚期会员推荐新会员的比例 |
| 流失预警响应率 | ≥ 40% | 响应预警的会员数 / 收到预警的会员数 | 流失预警会员响应的比例 |
| 流失预警挽回率 | ≥ 30% | 被挽回的会员数 / 收到预警的会员数 | 流失预警会员被挽回的比例 |
| 流失召回成功率 | ≥ 15% | 召回成功的会员数 / 发出召回的会员数 | 流失会员被召回的比例 |
| 会员生命周期价值 | ≥ 3000 元 | 会员生命周期内总消费金额 | 单个会员在整个生命周期内的消费总额 |
| 会员平均生命周期 | ≥ 365 天 | 所有会员生命周期天数平均值 | 会员从注册到流失的平均天数 |
---
**文档结束**
---
docs/design/business/B-LLD-基础版-业务详细设计.md
-654
View File
@@ -1,654 +0,0 @@
# 健身房管理系统基础版业务详细设计文档（B-LLD）
> 文档编号: GYM-B-LLD-BASIC-001
> 版本: v1.0
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 已发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ---------------------- |
| v1.0 | 2026-03-08 | 张翔 | 创建基础版业务详细设计文档 |
---
## 一、引言
### 1.1 编写目的
本文档为健身房管理系统基础版的业务详细设计文档（Business Low-Level Design），旨在：
1. 详细描述业务流程、业务规则、异常处理
2. 为技术实现提供详细的业务指导
3. 作为业务分析师、开发人员的业务参考
### 1.2 项目背景
健身房管理系统基础版是面向小型工作室、个人教练等场景的核心版本，保证业务闭环，提供完整的会员管理、预约、签到等核心功能。
### 1.3 术语定义
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 1.4 参考文档
- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
- 《健身房管理系统基础版业务概要设计文档》 GYM-B-HLD-BASIC-001
---
## 二、详细业务流程
### 2.1 会员全生命周期流程
#### 2.1.1 业务场景
从会员注册到流失的完整生命周期管理，包括新会员激活、活跃期维护、沉默期干预、流失预警和挽回。
#### 2.1.2 业务流程
```mermaid
flowchart LR
A[新会员注册] --> B[首次到店引导]
B --> C[新会员激活期<br/>7天内完成首次到店]
C --> D[活跃期维护<br/>持续到店和消费]
D --> E{活跃度评估}
E -->|活跃| F[持续运营<br/>推送个性化内容]
E -->|沉默| G[沉默期干预<br/>7天未到店触发]
G --> H{干预效果}
H -->|成功| D
H -->|失败| I[流失预警<br/>30天未到店触发]
I --> J{挽回策略}
J -->|挽回成功| D
J -->|挽回失败| K[会员流失<br/>标记为流失状态]
K --> L[归档分析<br/>流失原因分析]
style A fill:#e1f5ff
style C fill:#fff4e1
style G fill:#ffe1e1
style I fill:#ffe1e1
style K fill:#ffcccc
```
#### 2.1.3 业务规则
**新会员激活期规则**
- 注册后7天内完成首次到店，否则进入沉默期干预
- ✅ 场景1：会员2026-03-01注册，2026-03-07首次到店，激活成功
- ✅ 场景2：会员2026-03-01注册，2026-03-08首次到店，激活成功
- ❌ 场景3：会员2026-03-01注册，2026-03-09首次到店，已进入沉默期干预
- ❌ 场景4：会员2026-03-01注册，2026-03-15首次到店，已进入流失预警
**活跃期定义规则**
- 30天内至少到店2次或消费1次
- ✅ 场景1：会员30天内到店2次，保持活跃状态
- ✅ 场景2：会员30天内到店1次但消费1次，保持活跃状态
- ✅ 场景3：会员30天内到店3次，保持活跃状态
- ❌ 场景4：会员30天内到店1次且未消费，进入沉默期
- ❌ 场景5：会员30天内未到店但消费1次，保持活跃状态
**沉默期触发规则**
- 7天未到店触发沉默期干预
- ✅ 场景1：会员最后到店2026-03-01，2026-03-08触发沉默期干预
- ✅ 场景2：会员最后到店2026-03-01，2026-03-09仍处于沉默期
- ✅ 场景3：会员沉默期干预成功，到店后重新计算活跃期
- ❌ 场景4：会员最后到店2026-03-01，2026-03-07未触发沉默期干预
**沉默期干预策略**
- 发送个性化关怀短信
- 提供专属优惠券
- 推荐适合的团课
- 教练主动联系
- ✅ 场景1：会员沉默7天，发送关怀短信"好久不见，期待您的到来"
- ✅ 场景2：会员沉默7天，提供专属优惠券"限时9折优惠"
- ✅ 场景3：会员沉默7天，推荐适合的团课"瑜伽课程适合您"
- ✅ 场景4：会员沉默7天，教练主动电话联系
- ❌ 场景5：会员沉默7天，未采取任何干预措施
**流失预警规则**
- 30天未到店触发流失预警
- ✅ 场景1：会员最后到店2026-02-01，2026-03-03触发流失预警
- ✅ 场景2：会员最后到店2026-02-01，2026-03-04启动挽回流程
- ✅ 场景3：会员挽回成功，到店后重新计算活跃期
- ❌ 场景4：会员最后到店2026-02-01，2026-03-02未触发流失预警
**流失定义规则**
- 90天未到店且未消费
- ✅ 场景1：会员最后到店2026-01-01，2026-04-01标记为流失状态
- ✅ 场景2：会员最后到店2026-01-01，2026-03-31仍处于流失预警期
- ✅ 场景3：会员90天内未到店但消费1次，不标记为流失
- ❌ 场景4：会员最后到店2026-01-01，2026-03-31标记为流失状态（错误）
**挽回策略规则**
- 根据会员等级和历史行为制定个性化挽回方案
- ✅ 场景1：VIP会员流失预警，提供专属私教课程优惠
- ✅ 场景2：普通会员流失预警，发送关怀短信和优惠券
- ✅ 场景3：高消费会员流失预警，客服主动电话联系
- ❌ 场景4：流失预警会员未制定挽回方案，系统自动发送通用短信
**流失归档规则**
- 流失会员归档保存，用于流失原因分析
- ✅ 场景1：会员标记为流失，归档保存所有历史数据
- ✅ 场景2：会员流失后重新激活，归档数据仍保留用于分析
- ✅ 场景3：定期分析流失会员数据，生成流失原因报告
- ❌ 场景4：会员标记为流失，删除历史数据（错误）
#### 2.1.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 新会员激活失败 | 发送个性化邀请短信，提供首次到店优惠 |
| 沉默期干预无效 | 升级干预策略，提供专属优惠或服务 |
| 流失预警触发 | 启动挽回流程，由客服主动联系 |
| 会员数据异常 | 标记异常状态，暂停自动化运营，人工介入处理 |
---
### 2.2 支付与退款全流程
#### 2.2.1 业务场景
会员购买会员卡、私教课程等服务的支付流程，以及退款申请、审批、退款、财务对账的完整流程。
#### 2.2.2 业务流程
```mermaid
flowchart TB
subgraph 支付流程
A[会员发起支付] --> B[选择支付方式]
B --> C[创建支付订单]
C --> D[调用支付网关]
D --> E{支付结果}
E -->|成功| F[更新订单状态]
F --> G[发放会员卡权益]
G --> H[发送支付成功通知]
E -->|失败| I[记录支付失败]
I --> J[提示用户重新支付]
end
subgraph 退款流程
K[会员申请退款] --> L[填写退款原因]
L --> M[提交退款申请]
M --> N{退款类型}
N -->|自动退款| O[系统自动审核]
N -->|人工审核| P[店长审核]
P --> Q{审核结果}
Q -->|通过| R[财务专员复核]
Q -->|拒绝| S[通知会员拒绝原因]
O --> R
R --> T{复核结果}
T -->|通过| U[调用退款接口]
T -->|拒绝| S
U --> V[更新订单状态]
V --> W[收回会员卡权益]
W --> X[发送退款成功通知]
X --> Y[财务对账]
end
style E fill:#fff4e1
style Q fill:#fff4e1
style T fill:#fff4e1
style K fill:#e1f5ff
```
#### 2.2.3 业务规则
**支付方式规则**
- 支持微信支付、支付宝、银行卡支付
- ✅ 场景1：会员选择微信支付，调用微信支付接口
- ✅ 场景2：会员选择支付宝，调用支付宝接口
- ✅ 场景3：会员选择银行卡，调用银行卡支付接口
- ❌ 场景4：会员选择不支持的支付方式，提示"暂不支持该支付方式"
**支付超时规则**
- 订单创建后30分钟内未支付自动取消
- ✅ 场景1：订单18:00创建，18:30未支付，订单自动取消
- ✅ 场景2：订单18:00创建，18:29支付，支付成功
- ❌ 场景3：订单18:00创建，18:31支付，支付失败提示"订单已取消"
- ❌ 场景4：订单18:00创建，18:00支付，支付成功
**自动退款条件规则**
- 7天内购买且未使用的会员卡、私教课程
- ✅ 场景1：会员购买会员卡后第1天申请退款，未使用，自动退款
- ✅ 场景2：会员购买会员卡后第7天申请退款，未使用，自动退款
- ❌ 场景3：会员购买会员卡后第8天申请退款，未使用，需人工审核
- ❌ 场景4：会员购买会员卡后第1天申请退款，已使用，需人工审核
**人工审核条件规则**
- 超过7天、已使用部分权益、金额超过1000元
- ✅ 场景1：会员购买会员卡后第8天申请退款，需人工审核
- ✅ 场景2：会员购买会员卡后第1天申请退款，已使用，需人工审核
- ✅ 场景3：会员购买1500元会员卡后第1天申请退款，需人工审核
- ❌ 场景4：会员购买会员卡后第7天申请退款，未使用，金额500元，自动退款
**退款时效规则**
- 审核通过后1-3个工作日到账
- ✅ 场景1：退款审核通过，第1个工作日到账
- ✅ 场景2：退款审核通过，第3个工作日到账
- ❌ 场景3：退款审核通过，第4个工作日到账（超时）
**财务对账规则**
- 每日自动对账，异常订单人工处理
- ✅ 场景1：系统每日凌晨自动对账，生成对账报告
- ✅ 场景2：对账发现异常订单，标记异常，财务专员人工核查
- ❌ 场景3：对账发现异常订单，未标记异常（错误）
**退款手续费规则**
- 7天内无手续费，7-30天收取5%手续费，30天以上收取10%手续费
- ✅ 场景1：会员购买会员卡后第1天申请退款，无手续费
- ✅ 场景2：会员购买会员卡后第15天申请退款，收取5%手续费
- ✅ 场景3：会员购买会员卡后第45天申请退款，收取10%手续费
- ❌ 场景4：会员购买会员卡后第1天申请退款，收取5%手续费（错误）
#### 2.2.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 支付超时 | 订单自动取消，释放库存和权益 |
| 支付重复 | 检测重复支付，自动退款重复金额 |
| 退款失败 | 重试3次，失败后人工介入处理 |
| 财务对账异常 | 标记异常订单，财务专员人工核查 |
| 退款申请超时 | 退款申请提交后48小时内未处理自动升级 |
---
### 2.3 投诉与反馈处理流程
#### 2.3.1 业务场景
会员提交投诉或反馈，系统自动分类、分配、处理、反馈，并进行满意度调查和归档分析。
#### 2.3.2 业务流程
```mermaid
flowchart LR
A[会员提交投诉/反馈] --> B[填写投诉详情]
B --> C[选择投诉类型]
C --> D[上传相关凭证]
D --> E[提交投诉]
E --> F[系统自动分类]
F --> G{投诉类型}
G -->|服务投诉| H[分配给店长]
G -->|设施投诉| I[分配给运营管理员]
G -->|财务投诉| J[分配给财务专员]
G -->|技术投诉| K[分配给技术支持]
H --> L[处理人接收]
I --> L
J --> L
K --> L
L --> M[调查处理]
M --> N{处理结果}
N -->|解决| O[反馈处理结果]
N -->|无法解决| P[升级处理]
P --> Q[上级介入处理]
Q --> O
O --> R[会员确认]
R --> S{满意度调查}
S -->|满意| T[归档分析]
S -->|不满意| U[重新处理]
U --> M
style A fill:#e1f5ff
style F fill:#fff4e1
style N fill:#fff4e1
style S fill:#ffe1e1
```
#### 2.3.3 业务规则
**投诉分类规则**
- 服务投诉、设施投诉、财务投诉、技术投诉、其他
- ✅ 场景1：会员投诉教练服务态度，分类为服务投诉
- ✅ 场景2：会员投诉器械损坏，分类为设施投诉
- ✅ 场景3：会员投诉退款问题，分类为财务投诉
- ✅ 场景4：会员投诉系统故障，分类为技术投诉
- ✅ 场景5：会员投诉其他问题，分类为其他
**响应时效规则**
- 投诉提交后2小时内响应
- ✅ 场景1：投诉14:00提交，16:00前响应
- ✅ 场景2：投诉14:00提交，15:59响应
- ❌ 场景3：投诉14:00提交，16:01响应（超时）
**处理时效规则**
- 一般投诉24小时内处理完毕，复杂投诉48小时内处理完毕
- ✅ 场景1：一般投诉14:00提交，次日14:00前处理完毕
- ✅ 场景2：复杂投诉14:00提交，后日14:00前处理完毕
- ❌ 场景3：一般投诉14:00提交，次日14:01处理完毕（超时）
**升级机制规则**
- 处理人无法解决时自动升级给上级
- ✅ 场景1：店长无法解决服务投诉，自动升级给运营管理员
- ✅ 场景2：运营管理员无法解决设施投诉，自动升级给超级管理员
- ❌ 场景3：处理人无法解决投诉，未升级（错误）
**满意度调查规则**
- 投诉处理完成后自动发送满意度调查
- ✅ 场景1：投诉处理完成，系统自动发送满意度调查问卷
- ✅ 场景2：会员完成满意度调查，系统记录满意度评分
- ❌ 场景3：投诉处理完成，未发送满意度调查（错误）
**归档分析规则**
- 投诉归档后进行分类统计和原因分析
- ✅ 场景1：投诉归档，系统自动分类统计
- ✅ 场景2：定期分析投诉数据，生成投诉原因报告
- ❌ 场景3：投诉归档，未进行分类统计（错误）
**投诉闭环规则**
- 所有投诉必须闭环处理，不得遗漏
- ✅ 场景1：投诉处理完成，会员确认，归档
- ✅ 场景2：投诉处理完成，会员不满意，重新处理，会员确认，归档
- ❌ 场景3：投诉处理完成，未会员确认，归档（错误）
#### 2.3.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| 投诉信息不完整 | 提示会员补充必要信息 |
| 处理人未响应 | 2小时未响应自动升级给上级 |
| 处理超时 | 24小时未处理自动升级给店长 |
| 会员不满意 | 重新处理，升级处理级别 |
| 投诉重复提交 | 合并重复投诉，关联处理 |
---
## 三、业务数据流转
### 3.1 会员数据流转
```mermaid
flowchart LR
A[会员注册] --> B[创建会员档案]
B --> C[购买会员卡]
C --> D[获得权益]
D --> E[预约团课]
E --> F[扣减权益]
F --> G[签到]
G --> H[记录到店]
H --> I[消费记录]
I --> J[数据统计]
```
### 3.2 权益数据流转
```mermaid
flowchart LR
A[购买会员卡] --> B[发放权益]
B --> C[预约扣减]
C --> D[签到扣减]
D --> E[权益使用记录]
E --> F[权益查询]
F --> G[权益续费]
G --> B
```
---
## 四、业务规则汇总
### 4.1 时间相关规则
| 规则类型 | 时间要求 | 说明 |
| -------------- | ------------------ | ------------------------ |
| 预约时间 | 课程开始前30分钟 | 会员预约团课的最短时间 |
| 取消预约 | 课程开始前2小时 | 会员取消预约的最短时间 |
| 团课取消 | 提前24小时 | 教练取消团课的最短时间 |
| 支付超时 | 30分钟 | 订单未支付自动取消时间 |
| 新会员激活期 | 7天 | 新会员首次到店时间要求 |
| 沉默期触发 | 7天未到店 | 触发沉默期干预的时间 |
| 流失预警 | 30天未到店 | 触发流失预警的时间 |
| 流失定义 | 90天未到店 | 会员流失的时间定义 |
| 投诉响应 | 2小时 | 投诉响应时间要求 |
| 投诉处理 | 24-48小时 | 投诉处理完成时间 |
| 退款时效 | 1-3个工作日 | 退款到账时间 |
### 4.2 数量相关规则
| 规则类型 | 数量限制 | 说明 |
| ------------ | -------- | -------------- |
| 团课容量 | 20人 | 每节课最大人数 |
| 自动退款 | 7天内 | 自动退款条件 |
| 手续费7-30天 | 5% | 退款手续费 |
| 手续费30天以上 | 10% | 退款手续费 |
### 4.3 状态相关规则
| 规则类型 | 状态定义 | 说明 |
| ------------ | -------- | -------------- |
| 活跃期 | 30天内到店2次或消费1次 | 会员活跃状态 |
| 沉默期 | 7天未到店 | 会员沉默状态 |
| 流失预警 | 30天未到店 | 流失预警状态 |
| 流失 | 90天未到店且未消费 | 会员流失状态 |
---
## 五、业务异常处理
### 5.1 会员相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 手机号已存在 | 提示用户直接登录 |
| 验证码错误 | 提示用户重新输入 |
| 验证码过期 | 提示用户重新获取 |
| 会员卡无效 | 提示用户购买会员卡 |
| 会员卡过期 | 提示用户续费 |
| 会员卡权益不足 | 提示用户购买会员卡或续费 |
### 5.2 预约相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 课程已满 | 提示用户选择其他课程 |
| 会员卡权益不足 | 提示用户购买会员卡 |
| 预约时间过短 | 提示用户提前预约 |
| 团课取消过晚 | 系统提示"取消时间过晚" |
### 5.3 支付相关异常
| 异常类型 | 处理方式 |
| ------------ | ---------------------------- |
| 支付失败 | 提示用户重新支付 |
| 支付超时 | 订单自动取消，释放库存和权益 |
| 支付重复 | 检测重复支付，自动退款重复金额 |
| 退款失败 | 重试3次，失败后人工介入处理 |
| 财务对账异常 | 标记异常订单，财务专员人工核查 |
### 5.4 投诉相关异常
| 异常类型 | 处理方式 |
| -------------- | ---------------------------- |
| 投诉信息不完整 | 提示会员补充必要信息 |
| 处理人未响应 | 2小时未响应自动升级给上级 |
| 处理超时 | 24小时未处理自动升级给店长 |
| 会员不满意 | 重新处理，升级处理级别 |
| 投诉重复提交 | 合并重复投诉，关联处理 |
---
## 六、业务指标
### 6.1 核心业务指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 预约成功率 | ≥ 95% | 成功预约次数 / 总预约次数 |
| 签到耗时 | ≤ 3秒 | 签到请求到签到完成的时间 |
| 人工处理时间减少 | 50% | (优化前时间 - 优化后时间) / 优化前时间 |
| 数据报表使用率 | ≥ 80% | 使用报表的用户数 / 总用户数 |
| 新会员激活率 | ≥ 70% | 7天内首次到店的新会员数 / 新会员总数 |
| 会员流失率 | ≤ 10% | 流失会员数 / 总会员数 |
| 投诉处理满意度 | ≥ 90% | 满意投诉数 / 总投诉数 |
### 6.2 运营指标
| 指标名称 | 目标值 | 计算方式 |
| ------------------ | ------------ | ---------------------------- |
| 团课满课率 | ≥ 80% | 满员课程数 / 总课程数 |
| 会员活跃度 | ≥ 60% | 活跃会员数 / 总会员数 |
| 会员续费率 | ≥ 70% | 续费会员数 / 到期会员数 |
| 会员卡使用率 | ≥ 85% | 使用会员卡的会员数 / 持卡会员数 |
---
## 七、附录
### 7.1 业务术语表
| 术语 | 定义 |
| ----------------------------- | ------------------------------------------------ |
| 租户(Tenant) | 系统的多租户架构中的独立业务实体，如一个连锁品牌 |
| 门店(Store) | 租户下的具体经营场所 |
| 会员(Member) | 在门店注册的用户 |
| 权益(Benefit) | 会员卡包含的时长、次数、储值、等级等权益 |
| 可预约资源(Bookable Resource) | 团课等可被预约的对象 |
| 时段(Slot) | 资源的可预约时间窗口 |
### 7.2 参考文档
- 《健身房管理系统基础版产品设计文档》 GYM-PRD-BASIC-001
- 《健身房管理系统基础版业务概要设计文档》 GYM-B-HLD-BASIC-001
- 《健身房管理系统基础版技术实现详细设计文档》 GYM-T-ILD-BASIC-001
### 7.3 业务流程图索引
| 流程名称 | 图表位置 |
| ---------------- | ------------ |
| 会员全生命周期流程 | 2.1.2 |
| 支付与退款全流程 | 2.2.2 |
| 投诉与反馈处理流程 | 2.3.2 |
| 会员数据流转 | 3.1 |
| 权益数据流转 | 3.2 |
### 7.4 业务规则索引
| 规则分类 | 规则名称 | 图表位置 |
| ---------------- | ---------------- | ------------ |
| 时间相关规则 | 预约时间 | 4.1 |
| 时间相关规则 | 取消预约 | 4.1 |
| 时间相关规则 | 团课取消 | 4.1 |
| 时间相关规则 | 支付超时 | 4.1 |
| 时间相关规则 | 新会员激活期 | 4.1 |
| 时间相关规则 | 沉默期触发 | 4.1 |
| 时间相关规则 | 流失预警 | 4.1 |
| 时间相关规则 | 流失定义 | 4.1 |
| 时间相关规则 | 投诉响应 | 4.1 |
| 时间相关规则 | 投诉处理 | 4.1 |
| 时间相关规则 | 退款时效 | 4.1 |
| 数量相关规则 | 团课容量 | 4.2 |
| 数量相关规则 | 自动退款 | 4.2 |
| 数量相关规则 | 手续费7-30天 | 4.2 |
| 数量相关规则 | 手续费30天以上 | 4.2 |
| 状态相关规则 | 活跃期 | 4.3 |
| 状态相关规则 | 沉默期 | 4.3 |
| 状态相关规则 | 流失预警 | 4.3 |
| 状态相关规则 | 流失 | 4.3 |
---
**文档结束**
---
## 二、详细业务流程（续）
### 2.4 UI 模版定制模块
#### 2.4.1 业务场景
健身房管理者可以根据品牌特色自定义系统界面，包括品牌 Logo、主题色、布局风格等，提升品牌形象和用户体验。
#### 2.4.2 业务数据流转
```mermaid
flowchart TB
subgraph UI 模版定制流程
A[管理员进入 UI 设置] --> B[选择定制类型]
B --> C{定制类型}
C -->|品牌定制 | D[上传品牌 Logo]
C -->|主题色定制 | E[选择主题色]
C -->|布局定制 | F[选择布局模板]
D --> G[预览效果]
E --> G
F --> G
G --> H{确认发布}
H -->|是 | I[保存到数据库]
H -->|否 | B
I --> J[通知所有用户]
J --> K[更新缓存]
K --> L[完成定制]
end
style A fill:#e1f5ff
style G fill:#fff4e1
style I fill:#e8f5e9
style L fill:#e8f5e9
```
#### 2.4.3 业务规则
**品牌定制规则**
- 支持上传 PNG、JPG 格式的 Logo 文件，最大 5MB
- ✅ 场景 1：管理员上传 PNG 格式 Logo（2MB），上传成功
- ✅ 场景 2：管理员上传 JPG 格式 Logo（3MB），上传成功
- ❌ 场景 3：管理员上传 GIF 格式 Logo（1MB），格式不支持
- ❌ 场景 4：管理员上传 PNG 格式 Logo（6MB），文件大小超限
**主题色定制规则**
- 提供预设色板，支持自定义色值输入
- ✅ 场景 1：管理员从预设色板选择蓝色主题，应用成功
- ✅ 场景 2：管理员输入自定义色值#1890FF，应用成功
- ❌ 场景 3：管理员输入无效色值#GGGGGG，提示格式错误
- ❌ 场景 4：管理员选择与 Logo 颜色冲突的主题色，系统提示建议
**布局定制规则**
- 提供 3 种预设布局模板（经典、现代、简约）
- ✅ 场景 1：管理员选择经典布局，应用成功
- ✅ 场景 2：管理员选择现代布局，应用成功
- ✅ 场景 3：管理员选择简约布局，应用成功
- ❌ 场景 4：管理员自定义布局超出预设范围，提示不支持
**预览规则**
- 支持实时预览，预览效果与实际效果一致
- ✅ 场景 1：管理员修改主题色，实时预览更新
- ✅ 场景 2：管理员切换布局模板，实时预览更新
- ✅ 场景 3：管理员上传 Logo，实时预览更新
- ❌ 场景 4：管理员修改后未预览直接发布，系统强制要求预览
**发布规则**
- 发布后即时生效，所有用户端同步更新
- ✅ 场景 1：管理员发布新主题，会员小程序即时更新
- ✅ 场景 2：管理员发布新主题，教练端 App 即时更新
- ✅ 场景 3：管理员发布新主题，管理后台 PC 即时更新
- ❌ 场景 4：管理员发布后部分用户未更新，系统自动清理缓存
#### 2.4.4 异常处理
| 异常场景 | 处理方式 |
|---------|---------|
| Logo 上传失败 | 提示文件大小或格式错误，建议重新上传 |
| 主题色不兼容 | 提示颜色冲突，推荐兼容色板 |
| 预览加载失败 | 重新加载预览，失败则提示网络问题 |
| 发布失败 | 回滚到上一个版本，提示发布失败原因 |
| 缓存更新失败 | 强制清理缓存，通知运维介入 |
#### 2.4.5 业务指标
| 指标名称 | 目标值 | 计算方式 |
|---------|--------|---------|
| UI 定制使用率 | ≥ 60% | 使用定制的门店数 / 总门店数 |
| 定制满意度 | ≥ 85% | 满意评价数 / 总评价数 |
| 预览加载时间 | ≤ 2 秒 | 预览请求到渲染完成的时间 |
| 发布成功率 | ≥ 99% | 成功发布次数 / 总发布次数 |
docs/design/technical/API-接口设计规范.md
-588
View File
@@ -1,588 +0,0 @@
# 健身房管理系统 API 接口设计规范
> 文档编号：GYM-API-SPEC-001
> 版本：v1.0
> 创建日期：2026-03-08
> 最后更新日期：2026-03-08
> 作者：张翔
> 状态：正式发布
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-08 | 张翔 | 创建 API 接口设计规范 |
## 参考文档
- RESTful API 最佳实践
- OpenAPI 3.0 规范
- Spring WebFlux 官方文档
- RSocket 规范
---
## 一、API 设计原则
### 1.1 RESTful 风格
**资源导向**：
- 使用名词表示资源，不使用动词
- 使用 HTTP 方法表示操作
- 使用复数名词表示资源集合
**示例**：
```
✅ GET /api/v1/members # 获取会员列表
✅ POST /api/v1/members # 创建会员
✅ GET /api/v1/members/{id} # 获取单个会员
✅ PUT /api/v1/members/{id} # 更新会员
✅ DELETE /api/v1/members/{id} # 删除会员
❌ GET /api/v1/getMembers
❌ POST /api/v1/createMember
```
### 1.2 版本控制
**URL 路径版本化**：
```
/api/v1/members
/api/v2/members
```
**版本号规则**：
- 格式：`v{主版本号}`
- 主版本号递增：不兼容的 API 变更
- 向后兼容：在同一版本内添加字段
### 1.3 响应式 API 设计
**异步非阻塞**：
- 使用 Spring WebFlux 实现响应式 API
- 返回类型：`Mono<T>`（单个对象）、`Flux<T>`（集合）
- 支持 Server-Sent Events (SSE) 实时推送
**示例**：
```java
// 单个资源
@GetMapping("/{id}")
public Mono<Member> getMember(@PathVariable Long id) {
return memberService.findById(id);
}
// 资源集合
@GetMapping
public Flux<Member> listMembers() {
return memberService.findAll();
}
// SSE 实时推送
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<Member> streamMembers() {
return memberService.streamAll();
}
```
---
## 二、API 响应格式
### 2.1 标准响应结构
**成功响应**：
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "张三",
"phone": "138****1234"
},
"timestamp": "2026-03-08T10:30:00Z"
}
```
**列表响应**：
```json
{
"code": 200,
"message": "success",
"data": {
"items": [
{
"id": 1,
"name": "张三"
},
{
"id": 2,
"name": "李四"
}
],
"pagination": {
"page": 1,
"size": 20,
"total": 100,
"totalPages": 5
}
},
"timestamp": "2026-03-08T10:30:00Z"
}
```
**错误响应**：
```json
{
"code": 400,
"message": "参数验证失败",
"errors": [
{
"field": "phone",
"message": "手机号格式不正确"
}
],
"timestamp": "2026-03-08T10:30:00Z"
}
```
### 2.2 HTTP 状态码
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 200 OK | 成功 | GET、PUT、PATCH 成功 |
| 201 Created | 已创建 | POST 成功创建资源 |
| 204 No Content | 无内容 | DELETE 成功 |
| 400 Bad Request | 请求错误 | 参数验证失败 |
| 401 Unauthorized | 未授权 | 未登录或 Token 过期 |
| 403 Forbidden | 禁止访问 | 权限不足 |
| 404 Not Found | 未找到 | 资源不存在 |
| 409 Conflict | 冲突 | 资源已存在 |
| 422 Unprocessable Entity | 不可处理 | 业务规则验证失败 |
| 429 Too Many Requests | 请求过多 | 触发限流 |
| 500 Internal Server Error | 服务器错误 | 系统异常 |
### 2.3 数据格式
**日期时间格式**：
```
ISO 8601: 2026-03-08T10:30:00Z
日期：2026-03-08
时间：10:30:00
```
**数字格式**：
```
金额：100.00 (DECIMAL)
数量：10 (INTEGER)
比例：0.15 (DECIMAL)
```
**布尔值**：
```
true/false (JSON 原生布尔值)
```
---
## 三、API 接口分类
### 3.1 会员管理 API
#### 3.1.1 创建会员
```
POST /api/v1/members
```
**请求体**：
```json
{
"phone": "13812341234",
"name": "张三",
"gender": 1,
"birthday": "1990-01-01",
"fitnessGoal": "增肌"
}
```
**响应**：
```json
{
"code": 201,
"message": "创建成功",
"data": {
"id": 1,
"phone": "138****1234",
"name": "张三"
}
}
```
#### 3.1.2 获取会员详情
```
GET /api/v1/members/{id}
```
**响应**：
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"phone": "138****1234",
"name": "张三",
"gender": 1,
"birthday": "1990-01-01",
"fitnessGoal": "增肌",
"status": 1,
"level": 2
}
}
```
#### 3.1.3 会员列表查询
```
GET /api/v1/members
```
**查询参数**：
```
?phone=13812341234&status=1&page=1&size=20&sort=createdAt,desc
```
**响应**：
```json
{
"code": 200,
"message": "success",
"data": {
"items": [...],
"pagination": {
"page": 1,
"size": 20,
"total": 100,
"totalPages": 5
}
}
}
```
### 3.2 预约管理 API
#### 3.2.1 创建预约
```
POST /api/v1/bookings
```
**请求体**：
```json
{
"slotId": 1,
"memberId": 1
}
```
**响应**：
```json
{
"code": 201,
"message": "预约成功",
"data": {
"id": 1,
"bookingNo": "BK202603080001",
"status": 1
}
}
```
#### 3.2.2 取消预约
```
DELETE /api/v1/bookings/{id}
```
**响应**：
```json
{
"code": 204,
"message": "取消成功"
}
```
### 3.3 订阅管理 API
#### 3.3.1 开通订阅模块
```
POST /api/v1/subscriptions
```
**请求体**：
```json
{
"moduleCode": "marketing",
"billingCycle": 1,
"startDate": "2026-03-08",
"endDate": "2026-04-07"
}
```
**响应**：
```json
{
"code": 201,
"message": "开通成功",
"data": {
"id": 1,
"subscriptionNo": "SUB202603080001",
"moduleCode": "marketing",
"status": 1
}
}
```
---
## 四、错误处理
### 4.1 错误码规范
**错误码结构**：
```
业务码 (3 位) + 错误类型码 (2 位) + 具体错误码 (2 位)
```
**示例**：
```
MEM0101 - 会员创建失败
MEM0102 - 会员手机号已存在
BOK0201 - 预约失败
BOK0202 - 预约时段已满
SUB0301 - 订阅开通失败
```
### 4.2 全局异常处理
**控制器建议**：
```java
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public Mono<ApiResponse<Void>> handleResourceNotFound(
ResourceNotFoundException ex) {
return Mono.just(ApiResponse.error(404, ex.getMessage()));
}
@ExceptionHandler(ValidationException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Mono<ApiResponse<Void>> handleValidationException(
ValidationException ex) {
return Mono.just(ApiResponse.error(400, ex.getMessage(), ex.getErrors()));
}
@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public Mono<ApiResponse<Void>> handleException(Exception ex) {
log.error("系统异常", ex);
return Mono.just(ApiResponse.error(500, "系统繁忙，请稍后重试"));
}
}
```
### 4.3 参数验证
**请求体验证**：
```java
public class CreateMemberRequest {
@NotBlank(message = "手机号不能为空")
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
private String phone;
@NotBlank(message = "姓名不能为空")
@Size(min = 1, max = 50, message = "姓名长度不能超过 50 个字符")
private String name;
@NotNull(message = "性别不能为空")
@Min(value = 0, message = "性别值无效")
@Max(value = 2, message = "性别值无效")
private Integer gender;
// getters and setters
}
```
---
## 五、安全设计
### 5.1 认证机制
**JWT Token 认证**：
```
Authorization: Bearer {token}
```
**Token 结构**：
```json
{
"sub": "user123",
"tenantId": 1,
"storeId": 1,
"roles": ["ADMIN"],
"iat": 1709870400,
"exp": 1709956800
}
```
### 5.2 权限控制
**基于角色的访问控制 (RBAC)**：
```java
@PreAuthorize("hasRole('ADMIN')")
@PostMapping
public Mono<Member> createMember(@RequestBody CreateMemberRequest request) {
return memberService.create(request);
}
@PreAuthorize("hasAnyRole('ADMIN', 'COACH')")
@GetMapping("/{id}")
public Mono<Member> getMember(@PathVariable Long id) {
return memberService.findById(id);
}
```
### 5.3 限流
**令牌桶限流**：
```java
@RateLimiter(name = "apiRateLimiter")
@GetMapping
public Flux<Member> listMembers() {
return memberService.findAll();
}
```
**配置**：
```yaml
resilience4j:
ratelimiter:
instances:
apiRateLimiter:
limit-for-period: 100 # 每次允许 100 个请求
limit-refresh-period: 1s # 每秒刷新
timeout-duration: 0 # 不等待
```
---
## 六、API 文档
### 6.1 OpenAPI 规范
**使用 Springdoc OpenAPI**：
```java
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("健身房管理系统 API")
.version("v1")
.description("健身房管理系统 RESTful API 文档"))
.addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
.components(new Components()
.addSecuritySchemes("bearerAuth",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));
}
```
### 6.2 API 文档访问
**Swagger UI**：
```
http://localhost:8080/swagger-ui.html
```
**OpenAPI JSON**：
```
http://localhost:8080/v3/api-docs
```
---
## 七、API 版本迁移
### 7.1 版本兼容策略
**向后兼容**：
- 添加新字段：不影响旧版本
- 添加新接口：不影响旧版本
- 扩展枚举值：不影响旧版本
**不兼容变更**：
- 删除字段：需要升级版本
- 修改字段类型：需要升级版本
- 修改业务逻辑：需要升级版本
### 7.2 版本废弃流程
1. **标记废弃**：在旧版本 API 添加 `@Deprecated` 注解
2. **通知用户**：通过文档、邮件通知升级
3. **过渡期**：至少保留 3 个月
4. **正式下线**：移除旧版本 API
---
## 八、性能优化
### 8.1 分页优化
**游标分页**：
```
GET /api/v1/members?cursor=eyJpZCI6MTAwfQ==&size=20
```
**优势**：
- 避免深度分页性能问题
- 适合大数据量场景
### 8.2 字段过滤
**按需返回字段**：
```
GET /api/v1/members?fields=id,name,phone
```
**优势**：
- 减少网络传输
- 提升响应速度
### 8.3 缓存策略
**HTTP 缓存头**：
```
Cache-Control: max-age=3600, public
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 08 Mar 2026 10:30:00 GMT
```
**Redis 缓存**：
```java
@Cacheable(value = "members", key = "#id")
public Mono<Member> findById(Long id) {
return memberRepository.findById(id);
}
```
---
**文档结束**
docs/design/technical/DB-数据库设计.md
-505
View File
@@ -1,505 +0,0 @@
# 健身房管理系统数据库设计文档
> 文档编号：GYM-DB-DESIGN-001
> 版本：v1.0
> 创建日期：2026-03-08
> 最后更新日期：2026-03-08
> 作者：张翔
> 状态：正式发布
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-08 | 张翔 | 创建数据库设计文档 |
## 参考文档
- 《健身房管理系统基础版技术实现详细设计文档》 GYM-T-ILD-BASIC-001
- 《健身房管理系统付费订阅版技术实现详细设计文档》 GYM-T-ILD-SUBSCRIPTION-001
- PostgreSQL 官方文档
- R2DBC 规范文档
---
## 一、数据库架构设计
### 1.1 多租户架构设计
本系统采用**共享数据库、共享 Schema、租户 ID 隔离**的多租户架构：
```
租户层级：
租户 (Tenant) → 门店 (Store) → 业务数据
```
**租户隔离策略**：
- 所有业务表包含 `tenant_id` 字段
- 查询时强制添加 `tenant_id` 过滤条件
- 通过数据库视图实现租户级数据隔离
**门店隔离策略**：
- 门店级业务表包含 `store_id` 字段
- 支持跨店约课的多门店数据关联
- 通过配置继承实现门店级个性化
### 1.2 分库分表策略
**分库策略**（未来扩展）：
- 按租户分库：大型租户（月交易额>100 万）独立数据库
- 按业务分库：交易库、日志库、分析库分离
**分表策略**：
- 按时间分表：签到记录、预约记录按月分表
- 按租户分表：大型租户数据独立表空间
### 1.3 数据库选型
**核心数据库**：PostgreSQL 15+
- 完全支持 R2DBC 响应式驱动
- JSONB 支持灵活的配置管理
- 全文搜索支持
- ACID 事务保证
**缓存数据库**：Redis 7+
- 响应式缓存支持
- 分布式锁
- 过期策略
**搜索引擎**：Elasticsearch 8+（可选）
- 全文搜索
- 复杂查询
- 数据分析
---
## 二、核心表结构设计
### 2.1 会员域
#### 2.1.1 会员基础信息表（member）
```sql
CREATE TABLE member (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
store_id BIGINT NOT NULL,
phone VARCHAR(11) NOT NULL,
name VARCHAR(50) NOT NULL,
gender SMALLINT NOT NULL,
birthday DATE,
height DECIMAL(5,2),
weight DECIMAL(5,2),
fitness_goal VARCHAR(100),
avatar_url VARCHAR(500),
wechat_openid VARCHAR(100),
status SMALLINT DEFAULT 1,
level SMALLINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT uk_member_phone UNIQUE (tenant_id, phone),
CONSTRAINT fk_member_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_member_store FOREIGN KEY (store_id) REFERENCES store(id)
);
-- 索引设计
CREATE INDEX idx_member_tenant_store ON member(tenant_id, store_id);
CREATE INDEX idx_member_phone ON member(phone);
CREATE INDEX idx_member_status ON member(status);
CREATE INDEX idx_member_level ON member(level);
```
**字段说明**：
- `tenant_id`: 租户 ID，多租户隔离
- `store_id`: 门店 ID，单店运营
- `phone`: 手机号，唯一索引
- `status`: 1-正常，2-沉默，3-流失预警，4-流失
- `level`: 会员等级，1-普通，2-VIP，3-SVIP
#### 2.1.2 会员卡表（member_card）
```sql
CREATE TABLE member_card (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
card_type SMALLINT NOT NULL,
card_name VARCHAR(100) NOT NULL,
price DECIMAL(10,2) NOT NULL,
duration_days INT,
duration_times INT,
balance DECIMAL(10,2) DEFAULT 0.00,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
status SMALLINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT fk_card_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_card_member FOREIGN KEY (member_id) REFERENCES member(id)
);
-- 索引设计
CREATE INDEX idx_card_member ON member_card(member_id);
CREATE INDEX idx_card_status ON member_card(status);
CREATE INDEX idx_card_end_date ON member_card(end_date);
```
**字段说明**：
- `card_type`: 1-时长卡，2-次卡，3-储值卡，4-组合卡
- `duration_days`: 时长卡天数
- `duration_times`: 次卡次数
- `balance`: 储值卡余额
- `status`: 1-有效，2-已过期，3-已退款
#### 2.1.3 会员权益表（member_benefit）
```sql
CREATE TABLE member_benefit (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
card_id BIGINT NOT NULL,
benefit_type SMALLINT NOT NULL,
benefit_value DECIMAL(10,2) NOT NULL,
used_value DECIMAL(10,2) DEFAULT 0.00,
remaining_value DECIMAL(10,2) NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
CONSTRAINT fk_benefit_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_benefit_member FOREIGN KEY (member_id) REFERENCES member(id),
CONSTRAINT fk_benefit_card FOREIGN KEY (card_id) REFERENCES member_card(id)
);
-- 索引设计
CREATE INDEX idx_benefit_member ON member_benefit(member_id);
CREATE INDEX idx_benefit_type ON member_benefit(benefit_type);
```
**字段说明**：
- `benefit_type`: 1-时长权益，2-次数权益，3-储值权益，4-等级权益
- `benefit_value`: 权益总值
- `used_value`: 已使用值
- `remaining_value`: 剩余值
#### 2.1.4 会员生命周期表（member_lifecycle）
```sql
CREATE TABLE member_lifecycle (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
stage SMALLINT NOT NULL,
enter_time TIMESTAMP NOT NULL,
exit_time TIMESTAMP,
exit_reason VARCHAR(200),
intervention VARCHAR(500),
intervention_result SMALLINT,
created_at TIMESTAMP DEFAULT NOW(),
CONSTRAINT fk_lifecycle_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_lifecycle_member FOREIGN KEY (member_id) REFERENCES member(id)
);
-- 索引设计
CREATE INDEX idx_lifecycle_member ON member_lifecycle(member_id);
CREATE INDEX idx_lifecycle_stage ON member_lifecycle(stage);
```
**字段说明**：
- `stage`: 1-新会员，2-活跃期，3-沉默期，4-流失预警，5-流失
- `intervention`: 干预措施
- `intervention_result`: 1-成功，2-失败
---
### 2.2 预约域
#### 2.2.1 可预约资源表（booking_resource）
```sql
CREATE TABLE booking_resource (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
store_id BIGINT NOT NULL,
resource_type SMALLINT NOT NULL,
resource_name VARCHAR(100) NOT NULL,
description VARCHAR(500),
capacity INT NOT NULL,
duration_minutes INT NOT NULL,
status SMALLINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT fk_resource_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_resource_store FOREIGN KEY (store_id) REFERENCES store(id)
);
-- 索引设计
CREATE INDEX idx_resource_tenant_store ON booking_resource(tenant_id, store_id);
CREATE INDEX idx_resource_type ON booking_resource(resource_type);
```
**字段说明**：
- `resource_type`: 1-团课，2-私教，3-器械，4-场地
- `capacity`: 容量（人数）
- `status`: 1-启用，2-停用
#### 2.2.2 时段表（booking_slot）
```sql
CREATE TABLE booking_slot (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
resource_id BIGINT NOT NULL,
coach_id BIGINT,
start_time TIMESTAMP NOT NULL,
end_time TIMESTAMP NOT NULL,
booked_count INT DEFAULT 0,
status SMALLINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT fk_slot_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_slot_resource FOREIGN KEY (resource_id) REFERENCES booking_resource(id)
);
-- 索引设计
CREATE INDEX idx_slot_resource ON booking_slot(resource_id);
CREATE INDEX idx_slot_start_time ON booking_slot(start_time);
CREATE INDEX idx_slot_status ON booking_slot(status);
```
**字段说明**：
- `coach_id`: 教练 ID（私教课必填）
- `booked_count`: 已预约人数
- `status`: 1-可预约，2-已满，3-已取消
#### 2.2.3 预约记录表（booking_record）
```sql
CREATE TABLE booking_record (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
member_id BIGINT NOT NULL,
slot_id BIGINT NOT NULL,
booking_time TIMESTAMP NOT NULL,
status SMALLINT DEFAULT 1,
cancel_time TIMESTAMP,
cancel_reason VARCHAR(200),
checkin_time TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
CONSTRAINT fk_booking_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id),
CONSTRAINT fk_booking_member FOREIGN KEY (member_id) REFERENCES member(id),
CONSTRAINT fk_booking_slot FOREIGN KEY (slot_id) REFERENCES booking_slot(id)
);
-- 索引设计
CREATE INDEX idx_booking_member ON booking_record(member_id);
CREATE INDEX idx_booking_slot ON booking_record(slot_id);
CREATE INDEX idx_booking_status ON booking_record(status);
```
**字段说明**：
- `booking_time`: 预约时间
- `status`: 1-已预约，2-已签到，3-已取消，4-已爽约
- `checkin_time`: 签到时间
---
### 2.3 订阅域
#### 2.3.1 租户模块配置表（tenant_module_config）
```sql
CREATE TABLE tenant_module_config (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
module_code VARCHAR(32) NOT NULL,
enabled BOOLEAN NOT NULL,
config_data JSONB,
version INT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
created_by BIGINT,
updated_by BIGINT,
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT uk_tenant_module UNIQUE (tenant_id, module_code),
CONSTRAINT fk_tenant_module_config FOREIGN KEY (tenant_id) REFERENCES tenant(id)
);
-- 索引设计
CREATE INDEX idx_tenant_module ON tenant_module_config(tenant_id, module_code);
```
#### 2.3.2 门店模块配置表（store_module_config）
```sql
CREATE TABLE store_module_config (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
store_id BIGINT NOT NULL,
module_code VARCHAR(32) NOT NULL,
inherit_mode SMALLINT NOT NULL,
enabled BOOLEAN NOT NULL,
config_data JSONB,
version INT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
created_by BIGINT,
updated_by BIGINT,
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT uk_store_module UNIQUE (store_id, module_code),
CONSTRAINT fk_store_module_config FOREIGN KEY (store_id) REFERENCES store(id)
);
-- 索引设计
CREATE INDEX idx_store_module ON store_module_config(store_id, module_code);
```
#### 2.3.3 订阅记录表（subscription_record）
```sql
CREATE TABLE subscription_record (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
subscription_no VARCHAR(32) NOT NULL,
module_code VARCHAR(32) NOT NULL,
billing_cycle SMALLINT NOT NULL,
amount DECIMAL(10,2) NOT NULL,
discount_amount DECIMAL(10,2) DEFAULT 0.00,
actual_amount DECIMAL(10,2) NOT NULL,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
status SMALLINT DEFAULT 1,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
created_by BIGINT,
updated_by BIGINT,
deleted_at TIMESTAMP DEFAULT NULL,
CONSTRAINT uk_subscription_no UNIQUE (subscription_no),
CONSTRAINT fk_subscription_tenant FOREIGN KEY (tenant_id) REFERENCES tenant(id)
);
-- 索引设计
CREATE INDEX idx_subscription_tenant ON subscription_record(tenant_id);
CREATE INDEX idx_subscription_status ON subscription_record(status);
```
---
## 三、索引设计优化
### 3.1 核心索引清单
| 表名 | 索引字段 | 索引类型 | 说明 |
|------|---------|---------|------|
| member | (tenant_id, phone) | 唯一索引 | 租户级手机号唯一 |
| member | (tenant_id, store_id) | 复合索引 | 租户 + 门店查询 |
| member | (status) | 单列索引 | 会员状态筛选 |
| member_card | (member_id) | 复合索引 | 会员卡片查询 |
| member_card | (end_date) | 单列索引 | 到期提醒查询 |
| booking_record | (member_id, status) | 复合索引 | 会员预约查询 |
| booking_slot | (resource_id, start_time) | 复合索引 | 资源时段查询 |
### 3.2 索引优化建议
1. **避免过度索引**：单表索引数不超过 5 个
2. **优先复合索引**：将高频查询字段组合
3. **定期分析索引使用**：通过 pg_stat_user_indexes 监控
4. **及时删除无用索引**：减少写入开销
---
## 四、数据迁移策略
### 4.1 版本化管理
使用 **Flyway** 进行数据库版本管理：
```
db/
├── migration/
│ ├── V1__initial_schema.sql
│ ├── V2__add_member_lifecycle.sql
│ ├── V3__add_booking_resource.sql
│ └── ...
```
### 4.2 数据迁移流程
1. **开发环境**：创建迁移脚本 → 测试迁移 → 提交代码
2. **测试环境**：自动执行迁移 → 验证数据 → 回归测试
3. **生产环境**：备份数据 → 执行迁移 → 验证数据 → 监控告警
### 4.3 回滚策略
- 每个迁移脚本配备回滚脚本
- 回滚前必须备份当前数据
- 回滚后验证数据一致性
---
## 五、性能优化
### 5.1 查询优化
1. **避免 N+1 查询**：使用 JOIN 或批量查询
2. **使用覆盖索引**：减少回表查询
3. **分页优化**：使用游标分页替代 OFFSET
### 5.2 连接池配置
```yaml
spring:
r2dbc:
pool:
max-size: 20 # 基础版
max-size: 100 # 付费订阅版
initial-size: 10
max-idle-time: 30m
max-life-time: 60m
```
### 5.3 监控指标
- 连接池使用率
- 慢查询（>1s）
- 锁等待时间
- 表空间使用率
---
## 六、安全设计
### 6.1 数据加密
- 手机号：AES-256 加密
- 身份证：AES-256 加密
- 银行卡：AES-256 加密
### 6.2 数据脱敏
- 日志中的手机号：138****1234
- 接口响应中的身份证：110101********1234
### 6.3 审计日志
- 关键操作记录（插入、更新、删除）
- 操作人、操作时间、IP 地址
- 保留 180 天
---
**文档结束**
docs/design/technical/SEC-安全设计.md
-626
View File
@@ -1,626 +0,0 @@
# 健身房管理系统安全设计文档
> 文档编号：GYM-SEC-DESIGN-001
> 版本：v1.0
> 创建日期：2026-03-08
> 最后更新日期：2026-03-08
> 作者：张翔
> 状态：正式发布
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-08 | 张翔 | 创建安全设计文档 |
## 参考文档
- OWASP Top 10 安全规范
- Spring Security 官方文档
- GDPR 数据保护条例
- 网络安全等级保护 2.0
---
## 一、安全架构设计
### 1.1 安全分层
```
┌─────────────────────────────────────┐
│ 应用层安全 │
│ (认证、授权、输入验证、输出编码) │
├─────────────────────────────────────┤
│ 数据层安全 │
│ (加密、脱敏、审计、备份) │
├─────────────────────────────────────┤
│ 基础设施安全 │
│ (网络安全、主机安全、容器安全) │
└─────────────────────────────────────┘
```
### 1.2 安全原则
1. **纵深防御**：多层安全防护
2. **最小权限**：只授予必要权限
3. **默认安全**：默认配置即安全
4. **零信任**：始终验证，永不信任
5. **安全审计**：所有操作可追溯
---
## 二、认证与授权
### 2.1 认证机制
#### 2.1.1 JWT Token 认证
**Token 生成**：
```java
@Component
public class JwtTokenProvider {
@Value("${jwt.secret}")
private String secretKey;
@Value("${jwt.expiration}")
private long expiration;
public String generateToken(Authentication auth) {
UserPrincipal principal = (UserPrincipal) auth.getPrincipal();
Date now = new Date();
Date expiryDate = new Date(now.getTime() + expiration);
return Jwts.builder()
.setSubject(principal.getId().toString())
.claim("tenantId", principal.getTenantId())
.claim("storeId", principal.getStoreId())
.claim("roles", principal.getRoles())
.setIssuedAt(now)
.setExpiration(expiryDate)
.signWith(SignatureAlgorithm.HS512, secretKey)
.compact();
}
}
```
**Token 验证**：
```java
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
@Autowired
private JwtTokenProvider tokenProvider;
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
try {
String jwt = getJwtFromRequest(request);
if (StringUtils.hasText(jwt) && tokenProvider.validateToken(jwt)) {
Authentication auth = tokenProvider.getAuthentication(jwt);
SecurityContextHolder.getContext().setAuthentication(auth);
}
} catch (Exception ex) {
logger.error("Could not set user authentication", ex);
}
filterChain.doFilter(request, response);
}
}
```
#### 2.1.2 Token 刷新机制
**双 Token 机制**：
- Access Token：有效期 2 小时
- Refresh Token：有效期 7 天
**刷新流程**：
```java
@PostMapping("/refresh")
public Mono<ApiResponse<TokenResponse>> refreshToken(
@RequestBody RefreshTokenRequest request) {
return authService.refreshToken(request.getRefreshToken())
.map(tokens -> ApiResponse.success(tokens));
}
```
### 2.2 授权机制
#### 2.2.1 基于角色的访问控制 (RBAC)
**角色定义**：
```java
public enum Role {
SUPER_ADMIN, // 超级管理员
TENANT_ADMIN, // 租户管理员
STORE_MANAGER, // 店长
COACH, // 教练
MEMBER // 会员
}
```
**权限配置**：
```java
@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {
@Bean
public SecurityWebFilterFilterChain securityFilterChain(
ServerHttpSecurity http) {
http
.authorizeExchange(exchanges -> exchanges
.pathMatchers("/api/v1/auth/**").permitAll()
.pathMatchers("/api/v1/admin/**").hasRole("ADMIN")
.pathMatchers("/api/v1/members/**").hasAnyRole("ADMIN", "COACH")
.pathMatchers("/api/v1/my/**").authenticated()
.anyExchange().permitAll()
)
.oauth2ResourceServer(oauth2 -> oauth2.jwt());
return http.build();
}
}
```
#### 2.2.2 数据权限隔离
**租户隔离**：
```java
@Component
public class TenantInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
String tenantId = request.getHeader("X-Tenant-ID");
if (StringUtils.isEmpty(tenantId)) {
throw new UnauthorizedException("缺少租户标识");
}
TenantContext.setTenantId(tenantId);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Exception ex) {
TenantContext.clear();
}
}
```
---
## 三、数据安全
### 3.1 数据加密
#### 3.1.1 敏感数据加密存储
**加密算法**：AES-256-GCM
**加密工具类**：
```java
@Component
public class EncryptionUtil {
@Value("${encryption.key}")
private String encryptionKey;
public String encrypt(String plaintext) throws Exception {
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
SecretKeySpec keySpec = new SecretKeySpec(
encryptionKey.getBytes(), "AES");
GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(
128, generateIV());
cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmParameterSpec);
byte[] cipherText = cipher.doFinal(plaintext.getBytes());
return Base64.getEncoder().encodeToString(cipherText);
}
public String decrypt(String cipherText) throws Exception {
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
SecretKeySpec keySpec = new SecretKeySpec(
encryptionKey.getBytes(), "AES");
cipher.init(Cipher.DECRYPT_MODE, keySpec,
new GCMParameterSpec(128, generateIV()));
byte[] plainText = cipher.doFinal(
Base64.getDecoder().decode(cipherText));
return new String(plainText);
}
}
```
**加密字段**：
- 手机号
- 身份证号
- 银行卡号
- 地址
#### 3.1.2 密码加密
**BCrypt 加密**：
```java
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder(12);
}
```
### 3.2 数据脱敏
#### 3.2.1 脱敏规则
**手机号脱敏**：
```java
public class DesensitizationUtil {
public static String maskPhone(String phone) {
if (StringUtils.isEmpty(phone)) {
return "";
}
return phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
}
public static String maskIdCard(String idCard) {
if (StringUtils.isEmpty(idCard)) {
return "";
}
return idCard.replaceAll("(\\d{6})\\d{8}(\\d{4})", "$1********$2");
}
}
```
#### 3.2.2 JSON 序列化脱敏
**自定义注解**：
```java
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside
@JsonSerialize(using = DesensitizationSerializer.class)
public @interface Desensitization {
DesensitizationType type();
}
public enum DesensitizationType {
PHONE, // 手机号
ID_CARD, // 身份证
BANK_CARD, // 银行卡
ADDRESS // 地址
}
```
**使用示例**：
```java
public class MemberDTO {
@Desensitization(type = DesensitizationType.PHONE)
private String phone;
@Desensitization(type = DesensitizationType.ID_CARD)
private String idCard;
}
```
### 3.3 数据备份
#### 3.3.1 备份策略
**全量备份**：
- 频率：每天凌晨 2 点
- 保留：最近 30 天
- 存储：异地灾备中心
**增量备份**：
- 频率：每小时
- 保留：最近 7 天
- 存储：本地高速存储
#### 3.3.2 恢复演练
- 频率：每季度一次
- 范围：随机抽取 10% 数据
- 验证：数据完整性校验
---
## 四、网络安全
### 4.1 HTTPS 强制
**配置**：
```yaml
server:
ssl:
enabled: true
key-store: classpath:keystore.p12
key-store-password: ${SSL_KEY_PASSWORD}
key-store-type: PKCS12
```
**HTTP 重定向**：
```java
@Bean
public SecurityWebFilterFilterChain securityFilterChain(
ServerHttpSecurity http) {
http
.redirectHttpsRedirect(Customizer.withDefaults());
return http.build();
}
```
### 4.2 CORS 配置
**跨域配置**：
```java
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("https://yourdomain.com")
.allowedMethods("GET", "POST", "PUT", "DELETE")
.allowedHeaders("*")
.allowCredentials(true)
.maxAge(3600);
}
};
}
```
### 4.3 限流与防 DDOS
**限流配置**：
```yaml
resilience4j:
ratelimiter:
instances:
apiRateLimiter:
limit-for-period: 100
limit-refresh-period: 1s
timeout-duration: 0
loginRateLimiter:
limit-for-period: 5
limit-refresh-period: 1m
timeout-duration: 0
```
**IP 黑名单**：
```java
@Component
public class IpBlacklistFilter implements Filter {
@Autowired
private RedisTemplate<String, String> redisTemplate;
@Override
public void doFilter(ServletRequest request,
ServletResponse response,
FilterChain chain) {
String ip = getClientIp(request);
if (isBlacklisted(ip)) {
((HttpServletResponse) response).sendError(403);
return;
}
chain.doFilter(request, response);
}
}
```
---
## 五、输入验证与输出编码
### 5.1 输入验证
**请求体验证**：
```java
public class CreateMemberRequest {
@NotBlank(message = "手机号不能为空")
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
private String phone;
@NotBlank(message = "姓名不能为空")
@Size(min = 1, max = 50, message = "姓名长度不能超过 50 个字符")
private String name;
@Email(message = "邮箱格式不正确")
private String email;
@Min(value = 0, message = "年龄不能小于 0")
@Max(value = 150, message = "年龄不能大于 150")
private Integer age;
}
```
**SQL 注入防护**：
```java
// ❌ 错误示例
@Query("SELECT m FROM Member m WHERE m.phone = :phone")
Member findByPhone(@Param("phone") String phone);
// ✅ 正确示例（使用参数化查询）
@Query("SELECT m FROM Member m WHERE m.phone = :phone")
Member findByPhone(@Param("phone") String phone);
```
**XSS 防护**：
```java
@Component
public class XssFilter implements Filter {
@Override
public void doFilter(ServletRequest request,
ServletResponse response,
FilterChain chain)
throws IOException, ServletException {
XssHttpServletRequestWrapper xssRequest =
new XssHttpServletRequestWrapper(
(HttpServletRequest) request);
chain.doFilter(xssRequest, response);
}
}
```
### 5.2 输出编码
**HTML 编码**：
```java
public class HtmlUtil {
public static String escapeHtml(String html) {
return StringEscapeUtils.escapeHtml4(html);
}
}
```
---
## 六、安全审计
### 6.1 审计日志
**审计内容**：
- 登录/登出
- 创建/更新/删除操作
- 数据导出
- 权限变更
**日志格式**：
```json
{
"timestamp": "2026-03-08T10:30:00Z",
"userId": 1,
"action": "CREATE_MEMBER",
"resource": "member",
"resourceId": 123,
"ip": "192.168.1.100",
"userAgent": "Mozilla/5.0...",
"result": "SUCCESS",
"details": {...}
}
```
**审计注解**：
```java
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface AuditLog {
String action();
String resource();
}
```
**使用示例**：
```java
@AuditLog(action = "CREATE", resource = "member")
public Mono<Member> createMember(CreateMemberRequest request) {
return memberRepository.save(request.toEntity());
}
```
### 6.2 日志存储
**存储策略**：
- 热存储：最近 30 天，Elasticsearch
- 冷存储：30-180 天，对象存储
- 归档：180 天以上，磁带库
**日志保护**：
- 完整性：数字签名
- 机密性：加密存储
- 可用性：多副本备份
---
## 七、安全监控
### 7.1 监控指标
**认证监控**：
- 登录成功率
- 登录失败次数
- Token 刷新率
- 异常登录行为
**授权监控**：
- 权限拒绝次数
- 越权访问尝试
- 敏感操作频率
**数据监控**：
- 敏感数据访问
- 大批量数据导出
- 异常数据修改
### 7.2 告警规则
**告警级别**：
- P0（紧急）：系统被入侵、数据泄露
- P1（严重）：大规模认证失败、DDOS 攻击
- P2（警告）：异常登录行为、权限异常
- P3（提示）：配置变更、版本升级
**告警渠道**：
- 短信：P0、P1
- 邮件：P1、P2
- 钉钉/企业微信：P2、P3
---
## 八、合规性
### 8.1 GDPR 合规
**数据主体权利**：
- 知情权：明确告知数据收集目的
- 访问权：用户可查询个人数据
- 更正权：用户可修改个人数据
- 删除权：用户可申请删除数据
- 可携带权：支持数据导出
**数据保护措施**：
- 数据最小化：只收集必要数据
- 目的限制：仅用于声明的目的
- 存储限制：到期自动删除
- 安全保障：加密、访问控制
### 8.2 等保 2.0 合规
**技术要求**：
- 身份鉴别：多因素认证
- 访问控制：最小权限原则
- 安全审计：操作可追溯
- 入侵防范：实时监测告警
- 数据完整性：校验和验证
- 数据保密性：加密传输存储
**管理要求**：
- 安全管理制度
- 安全管理机构
- 人员安全管理
- 系统建设管理
- 系统运维管理
---
**文档结束**
docs/design/technical/T-ILD-付费订阅版-技术实现详细设计.md
-1894
View File
File diff suppressed because it is too large Load Diff
docs/design/technical/T-ILD-基础版-技术实现详细设计.md
-1009
View File
File diff suppressed because it is too large Load Diff
docs/design/前端工程化建设文档.md
-935
View File
@@ -1,935 +0,0 @@
# 健身房管理系统前端工程化建设文档
> 文档编号: GYM-FE-ENG-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 正式发布
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-04 | 张翔 | 创建前端工程化建设文档 |
---
## 参考文档
- 《健身房管理系统前端技术架构详细设计》 GYM-FE-ARCH-001
- 《健身房管理系统前端开发规范》 GYM-FE-DEV-001
- Vite 官方文档
- GitHub Actions 文档
---
## 一、工程化概述
### 1.1 工程化目标
- **提高开发效率**：自动化重复性工作，减少手动操作
- **保证代码质量**：通过自动化检查和测试，确保代码质量
- **统一开发规范**：通过工具强制执行代码规范
- **简化部署流程**：自动化构建和部署，减少人为错误
- **提升团队协作**：统一开发环境和工具链
### 1.2 工程化体系
```mermaid
flowchart TB
subgraph DevTools["开发工具链"]
DT1["Node.js"]
DT2["npm/yarn"]
DT3["Git"]
DT4["VSCode"]
end
subgraph BuildTools["构建工具"]
BT1["Vite"]
BT2["TypeScript"]
BT3["ESLint"]
BT4["Prettier"]
end
subgraph QualityTools["代码质量工具"]
QT1["Husky"]
QT2["Commitlint"]
QT3["Lint-staged"]
QT4["Stylelint"]
end
subgraph TestTools["测试工具"]
TT1["Vitest"]
TT2["Playwright"]
TT3["Coverage"]
TT4["Testing Library"]
end
subgraph CICD["CI/CD工具"]
CD1["GitHub Actions"]
CD2["Docker"]
CD3["Nginx"]
CD4["CDN"]
end
DevTools --> BuildTools
BuildTools --> QualityTools
QualityTools --> TestTools
TestTools --> CICD
style DevTools fill:#e1f5ff
style BuildTools fill:#fff4e1
style QualityTools fill:#f0e1ff
style TestTools fill:#e1ffe1
style CICD fill:#ffe1e1
```
---
## 二、构建工具配置
### 2.1 Vite配置
#### 2.1.1 基础配置
```typescript
// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd())
return {
plugins: [vue()],
resolve: {
alias: {
'@': resolve(__dirname, 'src'),
'@components': resolve(__dirname, 'src/components'),
'@utils': resolve(__dirname, 'src/utils'),
'@api': resolve(__dirname, 'src/api'),
'@stores': resolve(__dirname, 'src/stores')
}
},
server: {
port: 5173,
host: true,
open: true,
proxy: {
'/api': {
target: env.VITE_API_BASE_URL,
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
},
build: {
outDir: 'dist',
assetsDir: 'assets',
sourcemap: mode === 'development',
minify: 'terser',
terserOptions: {
compress: {
drop_console: mode === 'production',
drop_debugger: mode === 'production',
pure_funcs: mode === 'production' ? ['console.log', 'console.info'] : []
}
},
rollupOptions: {
output: {
manualChunks: {
'vue-vendor': ['vue', 'vue-router', 'pinia'],
'element-plus': ['element-plus'],
'utils': ['lodash-es', 'dayjs'],
'crypto': ['crypto-js', 'jsencrypt']
}
}
},
chunkSizeWarningLimit: 1000
},
css: {
preprocessorOptions: {
scss: {
additionalData: `@import "@/assets/styles/variables.scss";`
}
}
}
}
})
```
#### 2.1.2 插件配置
```typescript
// vite.config.ts
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import Compression from 'vite-plugin-compression'
import { visualizer } from 'rollup-plugin-visualizer'
export default defineConfig({
plugins: [
vue(),
AutoImport({
imports: ['vue', 'vue-router', 'pinia'],
dts: 'src/auto-imports.d.ts',
eslintrc: {
enabled: true
}
}),
Components({
resolvers: [ElementPlusResolver()],
dts: 'src/components.d.ts'
}),
Compression({
verbose: true,
disable: false,
threshold: 10240,
algorithm: 'gzip',
ext: '.gz'
}),
visualizer({
open: false,
gzipSize: true,
brotliSize: true
})
]
})
```
### 2.2 TypeScript配置
```json
// tsconfig.json
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "preserve",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"],
"@api/*": ["src/api/*"],
"@stores/*": ["src/stores/*"]
}
},
"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
"references": [{ "path": "./tsconfig.node.json" }]
}
```
### 2.3 环境变量配置
```typescript
// .env.development
VITE_APP_TITLE=健身房管理系统(开发环境)
VITE_API_BASE_URL=http://localhost:8080/api
VITE_UPLOAD_URL=http://localhost:8080/upload
VITE_WS_URL=ws://localhost:8080/ws
VITE_SENTRY_DSN=
VITE_CRYPTO_SECRET_KEY=your-secret-key-here
VITE_RSA_PUBLIC_KEY=your-rsa-public-key-here
// .env.production
VITE_APP_TITLE=健身房管理系统
VITE_API_BASE_URL=https://api.example.com/api
VITE_UPLOAD_URL=https://api.example.com/upload
VITE_WS_URL=wss://api.example.com/ws
VITE_SENTRY_DSN=https://xxx@sentry.io/xxx
VITE_CRYPTO_SECRET_KEY=your-production-secret-key-here
VITE_RSA_PUBLIC_KEY=your-production-rsa-public-key-here
// .env.staging
VITE_APP_TITLE=健身房管理系统(测试环境)
VITE_API_BASE_URL=https://staging-api.example.com/api
VITE_UPLOAD_URL=https://staging-api.example.com/upload
VITE_WS_URL=wss://staging-api.example.com/ws
VITE_SENTRY_DSN=https://xxx@sentry.io/xxx
VITE_CRYPTO_SECRET_KEY=your-staging-secret-key-here
VITE_RSA_PUBLIC_KEY=your-staging-rsa-public-key-here
```
---
## 三、代码规范工具
### 3.1 ESLint配置
```json
// .eslintrc.json
{
"extends": [
"plugin:vue/vue3-recommended",
"plugin:@typescript-eslint/recommended",
"prettier",
"plugin:prettier/recommended"
],
"parser": "vue-eslint-parser",
"parserOptions": {
"ecmaVersion": "latest",
"parser": "@typescript-eslint/parser",
"sourceType": "module"
},
"plugins": ["vue", "@typescript-eslint", "prettier"],
"rules": {
"vue/multi-word-component-names": "off",
"vue/no-v-html": "warn",
"@typescript-eslint/no-explicit-any": "warn",
"@typescript-eslint/no-unused-vars": [
"error",
{
"argsIgnorePattern": "^_",
"varsIgnorePattern": "^_"
}
],
"@typescript-eslint/explicit-function-return-type": "off",
"@typescript-eslint/explicit-module-boundary-types": "off",
"no-console": [
"warn",
{
"allow": ["warn", "error"]
}
],
"no-debugger": "error",
"prettier/prettier": "error"
}
}
```
### 3.2 Prettier配置
```json
// .prettierrc
{
"semi": false,
"singleQuote": true,
"printWidth": 100,
"trailingComma": "es5",
"arrowParens": "avoid",
"endOfLine": "lf",
"tabWidth": 2,
"useTabs": false,
"bracketSpacing": true,
"jsxSingleQuote": false,
"proseWrap": "preserve"
}
```
### 3.3 Stylelint配置
```json
// .stylelintrc.json
{
"extends": ["stylelint-config-standard", "stylelint-config-prettier"],
"rules": {
"selector-class-pattern": "^[a-z][a-zA-Z0-9-__]*$",
"selector-pseudo-class-no-unknown": [
true,
{
"ignorePseudoClasses": ["deep", "global"]
}
],
"selector-pseudo-element-no-unknown": [
true,
{
"ignorePseudoElements": ["v-deep", "v-global", "v-slotted"]
}
]
}
}
```
---
## 四、自动化工具
### 4.1 Husky配置
```json
// package.json
{
"scripts": {
"prepare": "husky install",
"lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
"format": "prettier --write src/",
"lint:style": "stylelint \"src/**/*.{css,scss,vue}\" --fix"
}
}
```
```bash
# 初始化Husky
npx husky install
# 添加pre-commit钩子
npx husky add .husky/pre-commit "npx lint-staged"
# 添加commit-msg钩子
npx husky add .husky/commit-msg "npx commitlint --edit $1"
```
### 4.2 Lint-staged配置
```json
// .lintstagedrc.json
{
"*.{js,jsx,ts,tsx,vue}": [
"eslint --fix",
"prettier --write"
],
"*.{css,scss,vue}": [
"stylelint --fix"
],
"*.{json,md}": [
"prettier --write"
]
}
```
### 4.3 Commitlint配置
```javascript
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'ci']
],
'type-case': [2, 'always', 'lower-case'],
'type-empty': [2, 'never'],
'scope-case': [2, 'always', 'lower-case'],
'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
'subject-empty': [2, 'never'],
'subject-full-stop': [2, 'never', '.'],
'header-max-length': [2, 'always', 100]
}
}
```
---
## 五、CI/CD流程
### 5.1 GitHub Actions配置
```yaml
# .github/workflows/ci.yml
name: CI
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run ESLint
run: npm run lint
- name: Run Prettier check
run: npm run format:check
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run unit tests
run: npm run test:unit
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/coverage-final.json
fail_ci_if_error: true
build:
runs-on: ubuntu-latest
needs: [lint, test]
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Upload build artifacts
uses: actions/upload-artifact@v3
with:
name: dist
path: dist/
```
### 5.2 CD配置
```yaml
# .github/workflows/cd.yml
name: CD
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to server
uses: easingthemes/ssh-deploy@v3
with:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
TARGET: /var/www/gym-manage/frontend
SOURCE: dist/
```
---
## 六、项目脚手架
### 6.1 项目初始化
```bash
# 创建新项目
npm create vite@latest gym-manage-frontend -- --template vue-ts
# 进入项目目录
cd gym-manage-frontend
# 安装依赖
npm install
# 安装开发依赖
npm install -D \
@vitejs/plugin-vue \
unplugin-auto-import \
unplugin-vue-components \
sass \
eslint \
@typescript-eslint/parser \
@typescript-eslint/eslint-plugin \
eslint-plugin-vue \
prettier \
eslint-config-prettier \
eslint-plugin-prettier \
husky \
lint-staged \
@commitlint/cli \
@commitlint/config-conventional \
vitest \
@vue/test-utils \
@playwright/test \
rollup-plugin-visualizer \
vite-plugin-compression
# 安装生产依赖
npm install \
vue \
vue-router \
pinia \
axios \
dayjs \
lodash-es \
element-plus \
dompurify \
crypto-js \
jsencrypt \
web-vitals
```
### 6.2 目录结构初始化
```bash
# 创建目录结构
mkdir -p src/{api,assets/{images,icons,styles},components/{base,business,layout},composables,config,directives,hooks,layouts,router,stores,types,utils,views}
mkdir -p src/test/{unit,e2e}
mkdir -p public
# 创建配置文件
touch .env.development .env.production .env.staging
touch .eslintrc.json .prettierrc .stylelintrc.json
touch tsconfig.json tsconfig.node.json
```
### 6.3 基础文件创建
```typescript
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'
import router from './router'
import './assets/styles/main.scss'
const app = createApp(App)
const pinia = createPinia()
app.use(pinia)
app.use(router)
app.use(ElementPlus)
app.mount('#app')
```
```typescript
// src/App.vue
<template>
<router-view />
</template>
<script setup lang="ts">
</script>
<style>
#app {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
</style>
```
---
## 七、开发工具链
### 7.1 VSCode配置
```json
// .vscode/settings.json
{
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true,
"source.fixAll.stylelint": true
},
"eslint.validate": [
"javascript",
"javascriptreact",
"typescript",
"typescriptreact",
"vue"
],
"typescript.tsdk": "node_modules/typescript/lib",
"volar.takeOverMode.enabled": true,
"[vue]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
```
```json
// .vscode/extensions.json
{
"recommendations": [
"vue.volar",
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"stylelint.vscode-stylelint",
"bradlc.vscode-tailwindcss",
"eamodio.gitlens"
]
}
```
### 7.2 Git配置
```bash
# .gitignore
node_modules
dist
dist-ssr
*.local
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
.DS_Store
*.log
coverage
.nyc_output
.env.local
.env.*.local
```
### 7.3 NPM脚本
```json
// package.json
{
"scripts": {
"dev": "vite",
"build": "vue-tsc && vite build",
"build:staging": "vue-tsc && vite build --mode staging",
"preview": "vite preview",
"lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
"lint:style": "stylelint \"src/**/*.{css,scss,vue}\" --fix",
"format": "prettier --write src/",
"format:check": "prettier --check src/",
"test": "vitest",
"test:unit": "vitest run",
"test:coverage": "vitest run --coverage",
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:headed": "playwright test --headed",
"type-check": "vue-tsc --noEmit",
"prepare": "husky install"
}
}
```
---
## 八、最佳实践
### 8.1 依赖管理
#### 8.1.1 依赖版本管理
```json
// package.json
{
"dependencies": {
"vue": "^3.4.0",
"vue-router": "^4.2.0",
"pinia": "^2.1.0"
},
"devDependencies": {
"vite": "^5.0.0",
"typescript": "^5.0.0",
"eslint": "^8.56.0"
}
}
```
#### 8.1.2 依赖安全检查
```bash
# 检查依赖漏洞
npm audit
# 自动修复依赖漏洞
npm audit fix
# 强制修复依赖漏洞
npm audit fix --force
```
### 8.2 性能监控
#### 8.2.1 构建分析
```bash
# 生成构建分析报告
npm run build
# 查看分析报告
open stats.html
```
#### 8.2.2 Bundle大小优化
```typescript
// vite.config.ts
export default defineConfig({
build: {
rollupOptions: {
output: {
manualChunks: {
'vue-vendor': ['vue', 'vue-router', 'pinia'],
'element-plus': ['element-plus'],
'utils': ['lodash-es', 'dayjs']
}
}
},
chunkSizeWarningLimit: 500
}
})
```
### 8.3 文档管理
#### 8.3.1 README文档
```markdown
# 健身房管理系统前端
## 项目介绍
健身房管理系统前端项目，基于Vue3 + Vite + TypeScript构建。
## 技术栈
- Vue 3.4+
- TypeScript 5.0+
- Vite 5.0+
- Pinia 2.1+
- Element Plus 2.5+
## 快速开始
### 安装依赖
\`\`\`bash
npm install
\`\`\`
### 开发
\`\`\`bash
npm run dev
\`\`\`
### 构建
\`\`\`bash
npm run build
\`\`\`
### 测试
\`\`\`bash
npm run test
\`\`\`
## 项目结构
\`\`\`
src/
├── api/ # API接口
├── assets/ # 静态资源
├── components/ # 组件
├── composables/ # Composables
├── config/ # 配置
├── router/ # 路由
├── stores/ # 状态管理
├── types/ # 类型定义
├── utils/ # 工具函数
└── views/ # 页面
\`\`\`
## 开发规范
详见 [前端开发规范](./docs/design/前端开发规范.md)
## 许可证
MIT
```
#### 8.3.2 CHANGELOG文档
```markdown
# Changelog
## [1.0.0] - 2026-03-04
### Added
- 会员管理功能
- 课程预约功能
- 扫码签到功能
- 数据统计功能
### Changed
- 升级Vue到3.4版本
- 优化构建配置
### Fixed
- 修复预约时间冲突问题
- 修复签到记录显示问题
### Security
- 添加XSS防护
- 添加CSRF防护
```
---
## 九、总结
本文档详细描述了健身房管理系统前端的工程化建设，包括：
1. **工程化概述**：工程化目标、工程化体系
2. **构建工具配置**：Vite配置、TypeScript配置、环境变量配置
3. **代码规范工具**：ESLint配置、Prettier配置、Stylelint配置
4. **自动化工具**：Husky配置、Lint-staged配置、Commitlint配置
5. **CI/CD流程**：GitHub Actions配置、CD配置
6. **项目脚手架**：项目初始化、目录结构初始化、基础文件创建
7. **开发工具链**：VSCode配置、Git配置、NPM脚本
8. **最佳实践**：依赖管理、性能监控、文档管理
通过遵循本文档的工程化建设指南，可以建立完善的前端工程化体系，提高开发效率、保证代码质量、简化部署流程。
docs/design/前端技术架构详细设计.md
-1321
View File
File diff suppressed because it is too large Load Diff
docs/plans/2026-02-28-gym-manage-design.md
-3385
View File
File diff suppressed because it is too large Load Diff
docs/plans/2026-03-05-poc-implementation-plan.md
-582
View File
@@ -1,582 +0,0 @@
# 健身房管理系统POC实施计划
> 文档编号: GYM-POC-PLAN-001
> 版本: v1.0
> 日期: 2026-03-05
> 作者: 张翔
> 状态: 初稿
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | ------------------ |
| v1.0 | 2026-03-05 | 张翔 | 创建POC实施计划 |
---
## 一、POC目标与范围
### 1.1 POC目标
**核心目标**：全面验证健身房管理系统的设计与实现，确保技术方案的可行性和性能达标。
**具体目标**：
1. ✅ 验证响应式架构（WebFlux + R2DBC）的技术可行性
2. ✅ 验证系统性能能否达到设计目标
3. ✅ 验证所有核心业务模块的端到端实现
4. ✅ 验证事务一致性和并发控制机制
5. ✅ 验证团队对响应式编程的掌握程度
### 1.2 POC范围
**实施范围**：
- ✅ 完整实施所有核心模块（会员、预约、签到、权益、订阅、营销、数据分析）
- ✅ 验证目标性能指标（并发能力、响应时间、资源利用率）
- ✅ 本地开发环境运行（不进行容器化部署）
**不包含**：
- ❌ 生产环境部署
- ❌ 完整的性能对比测试（WebFlux vs Spring MVC）
- ❌ 前端应用开发
- ❌ 第三方服务集成（微信、短信、支付）
### 1.3 成功标准
| 验证项 | 成功标准 | 验证方法 |
|-------|---------|---------|
| **技术可行性** | 所有核心功能正常运行 | 功能测试 |
| **并发能力** | 支持 1000+ 并发连接 | 性能测试 |
| **响应时间** | P99 < 500ms | 性能测试 |
| **吞吐量** | QPS ≥ 3000 | 性能测试 |
| **资源利用率** | 内存 < 1GB, CPU < 60% | 监控指标 |
| **事务一致性** | 并发场景下数据一致性 100% | 压力测试 |
| **代码质量** | 单元测试覆盖率 ≥ 80% | 测试报告 |
---
## 二、技术架构
### 2.1 技术栈
**核心技术**：
- Spring Boot 3.2.x
- Spring WebFlux 3.2.x
- Spring Data R2DBC 3.2.x
- PostgreSQL 16.x
- R2DBC PostgreSQL Driver 1.0.0.RELEASE
**开发工具**：
- JDK 17+
- Maven 3.9.x
- Lombok 1.18.x
- MapStruct 1.5.x
**测试工具**：
- JUnit 5
- Reactor Test
- Testcontainers
- JMeter / Gatling
### 2.2 项目结构
```
gym-manage-poc/
├── pom.xml
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/gym/manage/
│ │ │ ├── GymManageApplication.java
│ │ │ ├── api/ # API层
│ │ │ │ ├── controller/
│ │ │ │ │ ├── member/
│ │ │ │ │ ├── booking/
│ │ │ │ │ ├── checkin/
│ │ │ │ │ ├── benefit/
│ │ │ │ │ ├── subscription/
│ │ │ │ │ ├── marketing/
│ │ │ │ │ └── analytics/
│ │ │ │ ├── dto/
│ │ │ │ │ ├── request/
│ │ │ │ │ └── response/
│ │ │ │ └── config/
│ │ │ ├── application/ # 应用层
│ │ │ │ ├── service/
│ │ │ │ ├── facade/
│ │ │ │ └── orchestrator/
│ │ │ ├── domain/ # 领域层
│ │ │ │ ├── entity/
│ │ │ │ ├── valueobject/
│ │ │ │ ├── repository/
│ │ │ │ └── service/
│ │ │ ├── infrastructure/ # 基础设施层
│ │ │ │ ├── repository/
│ │ │ │ ├── cache/
│ │ │ │ ├── message/
│ │ │ │ └── config/
│ │ │ └── common/ # 公共模块
│ │ │ ├── exception/
│ │ │ ├── util/
│ │ │ └── constant/
│ │ └── resources/
│ │ ├── application.yml
│ │ ├── application-dev.yml
│ │ └── schema.sql
│ └── test/
│ └── java/
│ └── com/gym/manage/
│ ├── unit/
│ ├── integration/
│ └── performance/
└── README.md
```
---
## 三、实施计划
### 3.1 总体时间安排
**总工期**：4-6 周
| 阶段 | 时间 | 主要任务 |
|------|------|---------|
| **阶段一：基础设施搭建** | 第1周 | 项目搭建、数据库设计、基础配置 |
| **阶段二：核心模块开发** | 第2-3周 | 会员、预约、签到、权益模块 |
| **阶段三：高级模块开发** | 第4周 | 订阅、营销、数据分析模块 |
| **阶段四：测试与验证** | 第5-6周 | 功能测试、性能测试、优化 |
### 3.2 详细任务分解
#### 阶段一：基础设施搭建（第1周）
**Day 1-2：项目初始化**
- [x] 创建 Spring Boot 3.2.x 项目
- [x] 配置 Maven 依赖
- Spring Boot Starter WebFlux
- Spring Data R2DBC
- R2DBC PostgreSQL Driver
- Lombok
- MapStruct
- Spring Boot Starter Test
- [x] 配置 application.yml
- R2DBC 连接池配置
- 日志配置
- Actuator 配置
- [x] 创建基础包结构
- [x] 编写 README.md
**Day 3-4：数据库设计**
- [x] 设计数据库表结构
- 会员表（member）
- 会员卡表（member_card）
- 预约时段表（booking_slot）
- 预约记录表（booking_record）
- 签到记录表（checkin_record）
- 权益表（member_benefit）
- 权益记录表（benefit_record）
- 订阅表（subscription_record）
- 营销活动表（marketing_campaign）
- [x] 编写 schema.sql
- [x] 创建索引
- [x] 插入测试数据
**Day 5：基础代码框架**
- [x] 创建通用响应类（Result<T>）
- [x] 创建异常处理类
- [x] 创建全局异常处理器
- [x] 创建基础配置类
- R2DBC 配置
- Jackson 配置
- Validation 配置
#### 阶段二：核心模块开发（第2-3周）
**Week 2：会员模块 + 预约模块**
**会员模块（Day 1-3）**
- [x] 领域模型
- Member 实体
- MemberCard 实体
- MemberRepository 接口
- MemberCardRepository 接口
- [x] 业务服务
- MemberService：会员注册、查询、更新
- MemberCardService：会员卡管理
- [x] API 接口
- POST /api/v1/members：注册会员
- GET /api/v1/members/{id}：查询会员
- PUT /api/v1/members/{id}：更新会员
- GET /api/v1/members：会员列表
- POST /api/v1/members/{id}/cards：创建会员卡
- GET /api/v1/members/{id}/cards：查询会员卡
- [x] 单元测试
- MemberServiceTest
- MemberControllerTest
**预约模块（Day 4-5）**
- [x] 领域模型
- BookingSlot 实体
- BookingRecord 实体
- BookingSlotRepository 接口
- BookingRecordRepository 接口
- [x] 业务服务
- BookingSlotService：时段管理
- BookingRecordService：预约管理
- BookingOrchestrator：预约编排（Saga模式）
- [x] API 接口
- POST /api/v1/slots：创建时段
- GET /api/v1/slots：查询时段
- POST /api/v1/bookings：预约时段
- GET /api/v1/bookings/{id}：查询预约
- DELETE /api/v1/bookings/{id}：取消预约
- [x] 单元测试
- BookingServiceTest
- BookingControllerTest
**Week 3：签到模块 + 权益模块**
**签到模块（Day 1-2）**
- [x] 领域模型
- CheckinRecord 实体
- CheckinRecordRepository 接口
- [x] 业务服务
- CheckinService：签到管理
- [x] API 接口
- POST /api/v1/checkins：扫码签到
- GET /api/v1/checkins：签到记录
- GET /api/v1/members/{id}/checkins：会员签到记录
- [x] 单元测试
- CheckinServiceTest
- CheckinControllerTest
**权益模块（Day 3-5）**
- [x] 领域模型
- MemberBenefit 实体
- BenefitRecord 实体
- MemberBenefitRepository 接口
- BenefitRecordRepository 接口
- [x] 业务服务
- BenefitService：权益管理
- BenefitDeductionService：权益扣减
- [x] API 接口
- GET /api/v1/members/{id}/benefits：查询会员权益
- POST /api/v1/benefits/{id}/deduct：扣减权益
- GET /api/v1/members/{id}/benefit-records：权益记录
- [x] 单元测试
- BenefitServiceTest
- BenefitControllerTest
#### 阶段三：高级模块开发（第4周）
**订阅模块（Day 1-2）**
- [x] 领域模型
- SubscriptionRecord 实体
- SubscriptionRecordRepository 接口
- [x] 业务服务
- SubscriptionService：订阅管理
- [x] API 接口
- POST /api/v1/subscriptions：创建订阅
- GET /api/v1/subscriptions/{id}：查询订阅
- GET /api/v1/tenants/{id}/subscriptions：租户订阅列表
- [x] 单元测试
**营销模块（Day 3-4）**
- [x] 领域模型
- MarketingCampaign 实体
- MarketingCampaignRepository 接口
- [x] 业务服务
- MarketingService：营销活动管理
- [x] API 接口
- POST /api/v1/campaigns：创建活动
- GET /api/v1/campaigns/{id}：查询活动
- POST /api/v1/campaigns/{id}/join：参与活动
- [x] 单元测试
**数据分析模块（Day 5）**
- [x] 业务服务
- AnalyticsService：统计分析
- [x] API 接口
- GET /api/v1/analytics/overview：数据概览
- GET /api/v1/analytics/members：会员统计
- GET /api/v1/analytics/bookings：预约统计
- GET /api/v1/analytics/checkins：签到统计
- [x] 单元测试
#### 阶段四：测试与验证（第5-6周）
**Week 5：集成测试 + 性能测试**
**集成测试（Day 1-2）**
- [x] 编写集成测试
- 会员模块集成测试
- 预约模块集成测试
- 签到模块集成测试
- 权益模块集成测试
- [x] 使用 Testcontainers 启动 PostgreSQL
- [x] 验证端到端业务流程
**性能测试（Day 3-5）**
- [x] 编写性能测试脚本
- 会员查询性能测试
- 预约性能测试
- 签到性能测试
- [x] 使用 JMeter / Gatling 进行压力测试
- [x] 收集性能指标
- 并发连接数
- 响应时间（P50、P95、P99）
- 吞吐量（QPS）
- 资源利用率（CPU、内存）
- [x] 分析性能瓶颈
- [x] 性能优化
**Week 6：优化 + 文档**
**性能优化（Day 1-3）**
- [x] 数据库优化
- 索引优化
- 查询优化
- 连接池优化
- [x] 应用优化
- JVM 调优
- 响应式流优化
- 缓存策略
- [x] 代码优化
- 减少不必要的对象创建
- 优化响应式流链
- 避免阻塞操作
**文档编写（Day 4-5）**
- [x] 编写 POC 总结报告
- 技术可行性分析
- 性能测试报告
- 问题与解决方案
- 经验总结
- [x] 更新设计文档
- [x] 编写部署文档
---
## 四、性能验证计划
### 4.1 性能目标
| 性能指标 | 目标值 | 验证方法 |
|---------|-------|---------|
| **并发连接数** | ≥ 1000 | JMeter 并发测试 |
| **API 响应时间 (P99)** | < 500ms | JMeter 响应时间统计 |
| **吞吐量 (QPS)** | ≥ 3000 | JMeter 吞吐量统计 |
| **内存占用** | < 1GB | JVM 监控 |
| **CPU 利用率** | < 60% | 系统监控 |
| **数据库连接数** | < 20 | 数据库监控 |
### 4.2 性能测试场景
#### 场景 1：会员查询
**测试目的**：验证会员查询接口的性能
**测试步骤**：
1. 准备 10000 条会员数据
2. 使用 JMeter 进行并发查询
3. 并发数：100、500、1000
4. 持续时间：5 分钟
**验证指标**：
- P99 响应时间 < 200ms
- QPS ≥ 2000
- 错误率 < 0.1%
#### 场景 2：预约高峰
**测试目的**：验证预约接口在高并发下的性能
**测试步骤**：
1. 准备 100 个预约时段
2. 使用 JMeter 进行并发预约
3. 并发数：100、300、500
4. 持续时间：10 分钟
**验证指标**：
- P99 响应时间 < 500ms
- QPS ≥ 500
- 成功率 ≥ 99%
- 数据一致性 100%
#### 场景 3：签到高峰
**测试目的**：验证签到接口在高并发下的性能
**测试步骤**：
1. 准备 1000 个会员
2. 使用 JMeter 进行并发签到
3. 并发数：500、1000、2000
4. 持续时间：5 分钟
**验证指标**：
- P99 响应时间 < 300ms
- QPS ≥ 1000
- 成功率 ≥ 99.9%
### 4.3 性能测试工具
**JMeter 测试计划**：
```xml
<?xml version="1.0" encoding="UTF-8"?>
<jmeterTestPlan version="1.2">
<hashTree>
<TestPlan guiclass="TestPlanGui" testclass="TestPlan" testname="健身房管理系统性能测试">
<elementProp name="TestPlan.user_defined_variables" elementType="Arguments">
<collectionProp name="Arguments.arguments">
<elementProp name="BASE_URL" elementType="Argument">
<stringProp name="Argument.name">BASE_URL</stringProp>
<stringProp name="Argument.value">http://localhost:8080</stringProp>
</elementProp>
</collectionProp>
</elementProp>
</TestPlan>
<hashTree>
<!-- 会员查询测试 -->
<ThreadGroup guiclass="ThreadGroupGui" testclass="ThreadGroup" testname="会员查询">
<stringProp name="ThreadGroup.num_threads">1000</stringProp>
<stringProp name="ThreadGroup.ramp_time">10</stringProp>
<boolProp name="ThreadGroup.scheduler">true</boolProp>
<stringProp name="ThreadGroup.duration">300</stringProp>
</ThreadGroup>
<hashTree>
<HTTPSamplerProxy guiclass="HttpTestSampleGui" testclass="HTTPSamplerProxy" testname="查询会员">
<stringProp name="HTTPSampler.domain">${BASE_URL}</stringProp>
<stringProp name="HTTPSampler.path">/api/v1/members/${memberId}</stringProp>
<stringProp name="HTTPSampler.method">GET</stringProp>
</HTTPSamplerProxy>
</hashTree>
</hashTree>
</hashTree>
</jmeterTestPlan>
```
---
## 五、风险与缓解
### 5.1 技术风险
| 风险项 | 概率 | 影响 | 缓解策略 |
|-------|------|------|---------|
| **响应式编程学习曲线** | 高 | 中 | 提前学习、代码审查、结对编程 |
| **R2DBC 事务问题** | 中 | 高 | 严格测试、分布式锁、Saga 模式 |
| **性能不达标** | 低 | 高 | 性能测试、优化、必要时回退 |
| **并发问题** | 中 | 高 | 压力测试、分布式锁、乐观锁 |
### 5.2 时间风险
| 风险项 | 概率 | 影响 | 缓解策略 |
|-------|------|------|---------|
| **开发进度延迟** | 中 | 中 | 合理排期、每日站会、及时调整 |
| **性能测试时间不足** | 中 | 中 | 提前准备测试脚本、并行测试 |
| **Bug 修复时间过长** | 低 | 中 | 代码审查、单元测试、及时修复 |
---
## 六、交付物
### 6.1 代码交付物
- [x] 完整的源代码（GitHub 仓库）
- [x] 单元测试代码（覆盖率 ≥ 80%）
- [x] 集成测试代码
- [x] 性能测试脚本
### 6.2 文档交付物
- [x] POC 实施计划文档
- [x] POC 总结报告
- [x] 性能测试报告
- [x] API 文档（Swagger）
- [x] 部署文档
### 6.3 演示交付物
- [x] 功能演示视频
- [x] 性能测试演示视频
- [x] PPT 演示文稿
---
## 七、验收标准
### 7.1 功能验收
- [x] 所有核心功能正常运行
- [x] 所有 API 接口正常响应
- [x] 所有单元测试通过
- [x] 所有集成测试通过
### 7.2 性能验收
- [x] 并发连接数 ≥ 1000
- [x] P99 响应时间 < 500ms
- [x] QPS ≥ 3000
- [x] 内存占用 < 1GB
- [x] CPU 利用率 < 60%
### 7.3 质量验收
- [x] 单元测试覆盖率 ≥ 80%
- [x] 无严重 Bug
- [x] 代码规范检查通过
- [x] 文档完整
---
## 八、总结
本 POC 实施计划旨在全面验证健身房管理系统的设计与实现，确保技术方案的可行性和性能达标。通过 4-6 周的实施，我们将：
1. ✅ 完整实现所有核心模块
2. ✅ 验证响应式架构的性能优势
3. ✅ 验证事务一致性和并发控制机制
4. ✅ 积累响应式编程经验
5. ✅ 为正式开发提供技术基础
**下一步行动**：
1. 搭建项目基础架构
2. 开始会员模块开发
3. 持续跟踪进度，及时调整计划
---
## 九、附录
### 9.1 参考资料
- 《健身房管理系统技术架构设计文档》 GYM-HLD-TECH-001
- 《健身房管理系统响应式编程规范文档》 GYM-STD-REACTIVE-001
- 《健身房管理系统技术架构评估总结报告》 GYM-EVAL-TECH-001
- Spring Boot 3 官方文档
- Spring WebFlux 官方文档
- R2DBC 规范文档
### 9.2 联系方式
- 技术负责人：张翔
- 邮箱：zhangxiang@example.com
- 文档版本：v1.0
- 最后更新：2026-03-05
docs/plans/2026-03-05-poc-modules-implementation-plan.md
-1639
View File
File diff suppressed because it is too large Load Diff
docs/plans/2026-03-05-poc-progress-report.md
-404
View File
@@ -1,404 +0,0 @@
# 健身房管理系统POC进展报告
> 文档编号: GYM-POC-PROGRESS-001
> 版本: v1.0
> 日期: 2026-03-05
> 作者: 张翔
> 状态: 进行中
---
## 一、POC概述
### 1.1 POC目标
全面验证健身房管理系统的设计与实现，确保技术方案的可行性和性能达标。
### 1.2 实施范围
- ✅ 完整实施所有核心模块（会员、预约、签到、权益、订阅、营销、数据分析）
- ✅ 验证目标性能指标（并发能力、响应时间、资源利用率）
- ✅ 本地开发环境运行
---
## 二、已完成工作
### 2.1 项目基础架构 ✅
**完成时间**: 2026-03-05
**核心成果**:
1. ✅ 创建 Spring Boot 3.2.3 项目
2. ✅ 配置 Maven 依赖
- Spring Boot Starter WebFlux
- Spring Data R2DBC
- R2DBC PostgreSQL Driver 1.0.5.RELEASE
- Lombok 1.18.30
- MapStruct 1.5.5.Final
- SpringDoc OpenAPI 2.3.0
- Testcontainers 1.19.7
3. ✅ 配置 application.yml
4. ✅ 创建基础包结构
5. ✅ 编写 README.md
**技术栈验证**:
- ✅ Spring Boot 3.2.3 正常启动
- ✅ WebFlux 响应式编程模型验证
- ✅ R2DBC 连接池配置验证
### 2.2 数据库设计 ✅
**完成时间**: 2026-03-05
**核心成果**:
1. ✅ 设计数据库表结构
- 会员表（member）
- 会员卡表（member_card）
- 预约时段表（booking_slot）
- 预约记录表（booking_record）
- 签到记录表（checkin_record）
- 权益表（member_benefit）
- 权益记录表（benefit_record）
- 订阅表（subscription_record）
- 营销活动表（marketing_campaign）
2. ✅ 编写 schema.sql
3. ✅ 创建索引
4. ✅ 添加表注释和字段注释
**设计亮点**:
- ✅ 所有表支持软删除（deleted_at）
- ✅ 完善的索引设计
- ✅ 符合数据库设计规范
### 2.3 公共模块 ✅
**完成时间**: 2026-03-05
**核心成果**:
1. ✅ 通用响应类（Result<T>）
2. ✅ 业务异常类（BusinessException）
3. ✅ 全局异常处理器（GlobalExceptionHandler）
4. ✅ 错误码常量类（ErrorCode）
**设计亮点**:
- ✅ 统一的响应格式
- ✅ 完善的异常处理机制
- ✅ 响应式异常处理
### 2.4 会员模块 ✅
**完成时间**: 2026-03-05
**核心成果**:
**领域模型**:
- ✅ Member 实体
- ✅ MemberCard 实体
- ✅ MemberRepository 接口
- ✅ MemberCardRepository 接口
**业务服务**:
- ✅ MemberService：会员注册、查询、更新、删除
- ✅ MemberCardService：会员卡管理
**API 接口**:
- ✅ POST /api/v1/members：注册会员
- ✅ GET /api/v1/members/{id}：查询会员
- ✅ PUT /api/v1/members/{id}：更新会员
- ✅ GET /api/v1/members：会员列表
- ✅ DELETE /api/v1/members/{id}：删除会员
- ✅ POST /api/v1/members/{memberId}/cards：创建会员卡
- ✅ GET /api/v1/members/{memberId}/cards：查询会员卡
**技术亮点**:
- ✅ 完全响应式实现
- ✅ 使用 R2DBC Repository
- ✅ 参数验证
- ✅ 异常处理
- ✅ 日志记录
### 2.5 预约模块 ✅
**完成时间**: 2026-03-05
**核心成果**:
**领域模型**:
- ✅ BookingSlot 实体
- ✅ BookingRecord 实体
- ✅ BookingSlotRepository 接口
- ✅ BookingRecordRepository 接口
**业务服务**:
- ✅ BookingService：预约管理、取消预约
**API 接口**:
- ✅ POST /api/v1/bookings：预约时段
- ✅ GET /api/v1/bookings/{id}：查询预约
- ✅ GET /api/v1/bookings/members/{memberId}：会员预约列表
- ✅ DELETE /api/v1/bookings/{id}：取消预约
**技术亮点**:
- ✅ 响应式事务管理（@Transactional）
- ✅ 并发控制（原子操作）
- ✅ 业务规则验证
- ✅ 完善的错误处理
---
## 三、技术验证成果
### 3.1 响应式编程验证 ✅
**验证项**:
- ✅ Mono/Flux 响应式流
- ✅ 响应式 Repository
- ✅ 响应式事务管理
- ✅ 响应式异常处理
**验证结果**:
- ✅ 响应式编程模型正常工作
- ✅ R2DBC Repository 正常工作
- ✅ 响应式事务管理正常工作
- ✅ 异常处理机制完善
### 3.2 数据库访问验证 ✅
**验证项**:
- ✅ R2DBC 连接池配置
- ✅ R2DBC Repository 查询
- ✅ R2DBC 自定义查询（@Query）
- ✅ R2DBC 事务管理
**验证结果**:
- ✅ R2DBC 连接池正常工作
- ✅ Repository 查询正常工作
- ✅ 自定义查询正常工作
- ✅ 事务管理正常工作
### 3.3 API设计验证 ✅
**验证项**:
- ✅ RESTful API 设计
- ✅ 参数验证
- ✅ 统一响应格式
- ✅ 异常处理
- ✅ Swagger 文档
**验证结果**:
- ✅ API 设计符合规范
- ✅ 参数验证正常工作
- ✅ 响应格式统一
- ✅ 异常处理完善
- ✅ Swagger 文档自动生成
---
## 四、待完成工作
### 4.1 核心模块（高优先级）
#### 签到模块
- [ ] CheckinRecord 实体
- [ ] CheckinRecordRepository 接口
- [ ] CheckinService：签到管理
- [ ] CheckinController：签到接口
#### 权益模块
- [ ] MemberBenefit 实体
- [ ] BenefitRecord 实体
- [ ] MemberBenefitRepository 接口
- [ ] BenefitRecordRepository 接口
- [ ] BenefitService：权益管理、权益扣减
- [ ] BenefitController：权益接口
### 4.2 高级模块（中优先级）
#### 订阅模块
- [ ] SubscriptionRecord 实体
- [ ] SubscriptionRecordRepository 接口
- [ ] SubscriptionService：订阅管理
- [ ] SubscriptionController：订阅接口
#### 营销模块
- [ ] MarketingCampaign 实体
- [ ] MarketingCampaignRepository 接口
- [ ] MarketingService：营销活动管理
- [ ] MarketingController：营销接口
#### 数据分析模块
- [ ] AnalyticsService：统计分析
- [ ] AnalyticsController：统计接口
### 4.3 测试与验证（高优先级）
#### 单元测试
- [ ] MemberServiceTest
- [ ] MemberControllerTest
- [ ] BookingServiceTest
- [ ] BookingControllerTest
- [ ] 其他模块测试
#### 集成测试
- [ ] 会员模块集成测试
- [ ] 预约模块集成测试
- [ ] 其他模块集成测试
#### 性能测试
- [ ] 编写性能测试脚本
- [ ] 会员查询性能测试
- [ ] 预约性能测试
- [ ] 签到性能测试
- [ ] 收集性能指标
- [ ] 性能优化
---
## 五、风险与问题
### 5.1 已解决问题
| 问题 | 解决方案 | 状态 |
|------|---------|------|
| 响应式编程学习曲线 | 参考官方文档和最佳实践 | ✅ 已解决 |
| R2DBC 事务管理 | 使用 @Transactional 注解 | ✅ 已解决 |
| 并发控制 | 使用原子操作和乐观锁 | ✅ 已解决 |
### 5.2 待解决问题
| 问题 | 影响 | 解决方案 | 状态 |
|------|------|---------|------|
| 性能测试工具选择 | 中 | 评估 JMeter 和 Gatling | 🟡 进行中 |
| 监控体系搭建 | 低 | 集成 Actuator 和 Micrometer | 🟡 待开始 |
---
## 六、下一步计划
### 6.1 短期计划（1-2周）
1. ✅ 完成签到模块开发
2. ✅ 完成权益模块开发
3. ✅ 编写单元测试
4. ✅ 编写集成测试
### 6.2 中期计划（3-4周）
1. ✅ 完成订阅模块开发
2. ✅ 完成营销模块开发
3. ✅ 完成数据分析模块开发
4. ✅ 进行性能测试
### 6.3 长期计划（5-6周）
1. ✅ 性能优化
2. ✅ 编写 POC 总结报告
3. ✅ 准备演示材料
---
## 七、总结
### 7.1 当前进展
- ✅ 项目基础架构搭建完成
- ✅ 数据库设计完成
- ✅ 公共模块完成
- ✅ 会员模块完成
- ✅ 预约模块完成
- 🟡 签到模块待开发
- 🟡 权益模块待开发
- 🟡 订阅模块待开发
- 🟡 营销模块待开发
- 🟡 数据分析模块待开发
**完成度**: 约 40%
### 7.2 技术验证成果
1. ✅ **响应式架构可行**：WebFlux + R2DBC 技术栈成熟稳定
2. ✅ **开发效率高**：响应式编程模型简洁高效
3. ✅ **代码质量好**：遵循最佳实践，代码结构清晰
4. ✅ **易于维护**：模块化设计，职责分明
### 7.3 关键成功因素
1. ✅ 严格遵守响应式编程规范
2. ✅ 完善的异常处理机制
3. ✅ 统一的代码风格
4. ✅ 完整的日志记录
5. ✅ 合理的模块划分
### 7.4 经验总结
1. ✅ **响应式编程**：需要深入理解 Mono/Flux 的使用场景
2. ✅ **事务管理**：R2DBC 事务管理与 JDBC 有差异，需要特别注意
3. ✅ **并发控制**：需要使用原子操作和乐观锁来保证数据一致性
4. ✅ **异常处理**：响应式流的异常处理需要使用 onError 系列操作符
---
## 八、附录
### 8.1 项目文件清单
```
gym-manage/
├── pom.xml
├── README.md
├── .gitignore
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/gym/manage/
│ │ │ ├── GymManageApplication.java
│ │ │ ├── api/
│ │ │ │ ├── controller/
│ │ │ │ │ ├── member/
│ │ │ │ │ └── booking/
│ │ │ │ ├── dto/
│ │ │ │ │ ├── request/
│ │ │ │ │ └── response/
│ │ │ ├── application/
│ │ │ │ └── service/
│ │ │ ├── domain/
│ │ │ │ ├── entity/
│ │ │ │ └── repository/
│ │ │ └── common/
│ │ │ ├── result/
│ │ │ ├── exception/
│ │ │ └── constant/
│ │ └── resources/
│ │ ├── application.yml
│ │ └── schema.sql
│ └── test/
│ └── java/
│ └── com/gym/manage/
│ └── GymManageApplicationTests.java
└── docs/
└── plans/
├── 2026-02-28-gym-manage-design.md
├── 2026-03-05-poc-implementation-plan.md
└── 2026-03-05-poc-progress-report.md
```
### 8.2 技术栈版本
| 技术组件 | 版本 |
|---------|------|
| Spring Boot | 3.2.3 |
| Spring WebFlux | 3.2.3 |
| Spring Data R2DBC | 3.2.3 |
| PostgreSQL R2DBC | 1.0.5.RELEASE |
| Lombok | 1.18.30 |
| MapStruct | 1.5.5.Final |
| SpringDoc OpenAPI | 2.3.0 |
| Testcontainers | 1.19.7 |
### 8.3 联系方式
- 技术负责人：张翔
- 邮箱：zhangxiang@example.com
- 文档版本：v1.0
- 最后更新：2026-03-05
docs/plans/2026-03-07-ui-customization-design.md
-251
View File
@@ -1,251 +0,0 @@
# UI模版定制功能设计文档
> 文档编号: GYM-PLAN-UI-CUSTOMIZATION-001
> 版本: v1.0
> 日期: 2026-03-07
> 作者: 张翔
> 状态: 完成
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-07 | 张翔 | 初稿 |
---
## 一、功能概述
UI模版定制功能允许租户通过配置界面定制自己的品牌展示和界面布局，包括管理后台和会员端小程序。功能分为三个层次：
**品牌定制层**：租户可以上传自己的Logo、品牌主色调、辅助色、背景图、品牌名称等基础品牌元素，系统会自动应用这些元素到所有界面，确保品牌一致性。
**布局调整层**：租户可以调整页面模块的显示顺序、隐藏不需要的功能模块、自定义首页布局（如选择轮播图、快捷入口的排列方式），以及调整导航菜单的结构。
**预设模板层**：系统提供3-5个精心设计的预设模板，覆盖不同风格（简约白、运动活力、科技蓝、高端黑等），租户可以直接选择模板，然后在模板基础上进行品牌和布局的微调，快速完成定制。
---
## 二、架构设计
UI模版定制功能采用三层架构，确保配置的灵活性和系统的稳定性：
**配置存储层**：使用JSON格式存储租户的UI配置，包括品牌元素（Logo URL、颜色值、背景图）、布局设置（模块顺序、隐藏模块、首页布局类型）、模板选择（模板ID、自定义CSS覆盖）。配置按租户ID隔离，支持版本管理，允许租户切换回历史配置。
**渲染引擎层**：前端渲染引擎在加载页面时，根据当前租户ID读取对应的UI配置，动态生成CSS变量和页面结构。对于小程序端，使用微信小程序的自定义组件能力；对于管理后台，使用Vue/React的动态样式绑定。渲染引擎支持配置热更新，无需重新部署即可生效。
**模板管理层**：预设模板存储为独立的配置包，包含完整的布局结构、组件配置和默认样式。模板支持继承机制，租户选择模板后，可以覆盖模板的特定配置项而不影响其他部分。模板管理支持版本控制和灰度发布，确保模板更新的稳定性。
---
## 三、数据模型设计
UI模版定制功能需要以下核心数据表来支撑：
**租户UI配置表（tenant_ui_config）**：存储每个租户的UI定制配置，包含租户ID、模板ID、品牌配置（Logo URL、主色调、辅助色、背景图URL）、布局配置（模块顺序JSON、隐藏模块列表、首页布局类型）、自定义CSS、配置版本号、创建时间、更新时间。支持按租户ID快速查询配置。
**预设模板表（ui_template）**：存储系统提供的预设模板，包含模板ID、模板名称、模板类型（简约/运动/科技/高端）、模板描述、预览图URL、默认配置JSON、模板状态（启用/禁用）、排序权重。支持按类型和状态查询可用模板。
**配置历史表（ui_config_history）**：记录租户的配置变更历史，包含历史ID、租户ID、旧配置JSON、新配置JSON、变更原因、操作人、变更时间。支持按租户ID和时间范围查询历史，支持配置回滚。
**资源文件表（ui_resource）**：存储租户上传的品牌资源文件，包含资源ID、租户ID、资源类型（Logo/背景图/其他）、文件URL、文件大小、上传时间、状态。支持资源管理和清理。
---
## 四、核心功能设计
UI模版定制功能分为三个核心模块：
**品牌定制模块**：提供租户上传Logo（支持PNG/JPG格式，限制2MB以内）、设置品牌主色调和辅助色（提供颜色选择器和预设色板）、上传背景图（支持轮播背景）、设置品牌名称和Slogan。支持实时预览，租户在配置时可以立即看到效果。Logo上传后自动生成多种尺寸的缩略图，适配不同设备。
**布局调整模块**：提供拖拽式界面调整模块显示顺序，支持隐藏不需要的功能模块（如小型工作室可能不需要私教模块），自定义首页布局（选择卡片式、列表式、轮播式），调整导航菜单结构（添加自定义菜单项、修改菜单名称）。布局调整支持按角色区分，店长和前台可以看到不同的菜单结构。
**模板管理模块**：提供模板预览和选择界面，展示3-5个预设模板的缩略图和描述，支持一键应用模板。模板应用后保留租户已有的品牌配置，只更新布局结构。支持模板收藏和对比功能，租户可以收藏喜欢的模板进行快速切换。模板切换支持预览模式，租户可以在正式应用前预览效果。
---
## 五、可视化配置器设计
### 5.1 配置器架构
可视化配置器采用组件化架构，分为三个核心区域：
**品牌配置区**：左侧面板提供品牌元素的上传和设置，包括Logo上传组件（支持拖拽上传、实时预览、自动裁剪）、颜色选择器组件（提供色板、自定义颜色、RGB/HEX输入）、背景图上传组件（支持多图上传、轮播设置）、品牌信息输入（品牌名称、Slogan）。所有组件都支持实时预览，配置立即反映在右侧预览区。
**布局配置区**：中间面板提供布局调整功能，包括模块顺序组件（拖拽排序、分组管理、搜索过滤）、模块开关组件（开关控制、批量操作、保存提示）、首页布局组件（布局类型选择、快捷入口配置、轮播图设置）、导航菜单组件（菜单树形展示、添加/编辑/删除、图标选择）。布局调整支持撤销/重做，防止误操作。
**模板选择区**：右侧面板提供模板浏览和选择功能，包括模板网格组件（缩略图展示、类型筛选、收藏标记）、模板详情组件（大图预览、功能说明、一键应用）、模板对比组件（并排对比、差异高亮、切换建议）。模板选择支持快速切换，无需重新配置品牌元素。
### 5.2 交互设计
**拖拽交互**：模块顺序调整使用原生HTML5拖拽API，提供视觉反馈（拖拽时高亮、放置时动画、冲突时提示）。拖拽支持跨区域移动，可以隐藏的模块拖到显示区域，或反之。拖拽过程中显示放置指示器，明确可放置位置。
**实时预览**：所有配置变更都实时反映在预览区，包括Logo更换、颜色调整、布局变更、模板切换。预览区模拟真实页面结构，展示不同设备尺寸（手机、平板、桌面）的效果。预览支持全屏模式，方便查看整体效果。
**智能提示**：配置器提供上下文相关的提示和建议，包括品牌一致性提示（颜色搭配建议、Logo尺寸建议）、布局优化提示（模块分组建议、隐藏建议）、模板推荐提示（根据行业推荐模板）。提示以气泡形式展示，点击可展开详细说明。
**快捷操作**：提供常用操作的快捷入口，包括一键重置（恢复默认配置）、一键预览（全屏预览）、一键保存（保存配置）、一键发布（发布配置到生产环境）。快捷操作支持键盘快捷键，提升操作效率。
### 5.3 配置器组件
**Logo上传组件**：
- 支持拖拽上传和点击上传
- 实时预览Logo效果
- 自动生成多种尺寸缩略图
- 支持Logo裁剪和旋转
- 提供Logo尺寸建议和最佳实践提示
**颜色选择器组件**：
- 提供预设色板（包含流行配色方案）
- 支持自定义颜色输入（RGB/HEX格式）
- 实时显示颜色对比效果
- 支持颜色历史记录（最近使用的颜色）
- 提供颜色搭配建议（基于色彩理论）
**模块顺序组件**：
- 拖拽式排序界面
- 支持模块分组管理
- 提供搜索和过滤功能
- 支持批量操作（全选、反选、批量隐藏）
- 显示模块依赖关系提示
**模板选择组件**：
- 网格式模板展示（响应式布局）
- 支持模板类型筛选（简约/运动/科技/高端）
- 显示模板缩略图和预览图
- 支持模板收藏和快速切换
- 提供模板应用前的确认对话框
### 5.4 配置器技术实现
**前端技术栈**：
- 框架：Vue 3 / React 18
- 拖拽库：Vue Draggable / React DnD
- 颜色选择器：vue-color-picker / react-color
- 预览组件：iframe沙箱或虚拟DOM渲染
- 状态管理：Pinia / Redux
**配置器状态管理**：
- 使用响应式状态存储当前配置
- 配置变更自动触发预览更新
- 支持配置快照和恢复
- 实现撤销/重做功能栈
**预览渲染机制**：
- 使用虚拟DOM模拟页面渲染
- 注入CSS变量和布局配置
- 支持多设备尺寸预览切换
- 预览更新使用防抖优化性能
**配置导出功能**：
- 支持导出当前配置为JSON文件
- 支持导入配置文件恢复配置
- 导出配置包含版本信息和元数据
- 支持配置分享和备份
---
## 六、数据流设计
UI模版定制功能的数据流分为三个主要流程：
**配置保存流程**：租户在管理后台进行UI定制操作，前端实时预览效果，点击保存时，前端将配置JSON发送到后端API，后端验证配置格式和合法性，生成新的配置版本号，保存到租户UI配置表，同时记录到配置历史表，返回成功响应。前端收到成功响应后更新本地缓存，确保配置立即生效。
**配置加载流程**：用户访问小程序或管理后台时，前端首先从本地缓存读取租户UI配置，如果缓存不存在或已过期，则调用后端API获取最新配置，后端根据租户ID查询配置，返回配置JSON，前端解析配置并应用CSS变量和布局结构，渲染页面。配置加载失败时使用默认配置，确保系统可用性。
**模板切换流程**：租户选择预设模板时，前端调用模板API获取模板详情，展示模板预览，确认应用后，前端将模板ID和租户品牌配置发送到后端，后端合并模板的默认配置和租户的品牌配置，保存到租户UI配置表，记录配置历史，返回成功响应。前端重新加载配置并刷新页面展示。
---
## 六、错误处理和边界情况
UI模版定制功能需要考虑以下错误处理和边界情况：
**配置验证错误**：租户上传的Logo文件格式不支持或大小超限时，前端实时验证并提示错误信息；颜色值格式不正确时，前端颜色选择器限制输入范围；配置JSON格式错误时，后端返回详细的错误位置和建议。所有错误都提供友好的错误提示和修复建议。
**资源上传失败**：Logo或背景图上传失败时（网络错误、服务器错误），前端显示重试按钮，支持断点续传；上传成功但处理失败时，后端记录错误日志并通知管理员，前端显示"上传成功但处理中，请稍后查看"的提示。
**配置回滚失败**：租户尝试回滚到历史配置时，如果历史配置已不存在或数据损坏，后端返回错误并提示"该历史配置不可用，请选择其他版本"，同时保留当前配置不变，避免租户丢失现有配置。
**模板应用冲突**：租户应用新模板时，如果模板已被禁用或不存在，后端返回错误并提示"该模板不可用，请选择其他模板"；如果模板配置与租户当前品牌配置冲突，后端尝试自动合并，无法合并时提示"模板应用失败，请调整品牌配置后重试"。
**缓存失效**：前端缓存失效或配置加载失败时，自动降级到默认配置，记录错误日志，同时显示"使用默认样式，配置加载中"的提示，后台静默重试加载配置，成功后自动刷新页面。
---
## 七、测试设计
UI模版定制功能需要以下测试用例来确保质量：
**品牌定制测试**：验证Logo上传（支持格式、大小限制、缩略图生成）、颜色设置（颜色选择器准确性、色板应用、实时预览）、背景图上传（轮播背景、响应式适配）、品牌元素应用（所有页面一致性、缓存更新）。测试覆盖正常流程和异常情况（文件过大、格式不支持）。
**布局调整测试**：验证模块顺序调整（拖拽功能、保存生效、缓存更新）、模块隐藏（隐藏后不显示、数据安全）、首页布局（不同布局类型渲染、响应式适配）、导航菜单（自定义菜单、角色区分）。测试覆盖不同角色（店长、前台、会员）的布局差异。
**模板管理测试**：验证模板选择（模板加载、预览展示、一键应用）、模板切换（配置合并、品牌保留、历史记录）、模板收藏（收藏功能、快速切换）、模板预览（预览模式、正式应用）。测试覆盖所有预设模板（3-5个）的兼容性。
**配置历史测试**：验证配置保存（版本号生成、历史记录）、配置回滚（历史版本恢复、数据完整性）、配置对比（新旧配置差异、变更原因）。测试覆盖多次配置变更和回滚场景。
**性能测试**：验证配置加载速度（首次加载、缓存命中）、预览响应时间（实时预览延迟）、资源加载（Logo、背景图加载速度）、并发配置（多租户同时配置）。确保定制功能不影响系统整体性能。
---
## 八、实施建议
### 8.1 开发优先级
**P0（必须实现）**：
- 可视化配置器核心功能（品牌配置区、布局配置区、模板选择区）
- 品牌定制基础功能（Logo上传、颜色设置）
- 布局调整基础功能（模块顺序、模块隐藏）
- 配置保存和加载机制
- 预设模板基础功能（模板选择、模板应用）
- 实时预览功能
- 拖拽交互和快捷操作
**P1（重要实现）**：
- 配置历史和回滚功能
- 模板收藏功能
- 配置缓存机制
- 配置导出和导入功能
- 智能提示和建议
**P2（可选实现）**：
- 自定义CSS覆盖
- 模板对比功能
- 模板市场（第三方上传）
### 8.2 技术选型建议
**前端技术**：
- 小程序端：使用微信小程序自定义组件和动态样式
- 管理后台：使用Vue/React的动态样式绑定和CSS变量
**后端技术**：
- 配置存储：使用JSON格式，支持版本管理
- 资源存储：使用对象存储（如阿里云OSS）
- 缓存：使用Redis缓存配置，提升加载速度
**数据库设计**：
- 租户UI配置表：使用JSONB类型存储配置
- 预设模板表：支持模板版本和灰度发布
- 配置历史表：支持配置回滚和对比
### 8.3 风险和缓解措施
**风险1：配置冲突**
- 缓解措施：提供配置验证和自动合并机制
- 备份方案：支持配置回滚和历史记录
**风险2：性能影响**
- 缓解措施：使用缓存机制，避免频繁查询数据库
- 监控方案：监控配置加载时间，优化慢查询
**风险3：兼容性问题**
- 缓解措施：提供默认配置，确保降级可用
- 测试方案：测试所有预设模板的兼容性
---
**文档结束**
docs/plans/2026-03-08-final-summary.md
-556
View File
@@ -1,556 +0,0 @@
# 文档优化项目总结报告
> **项目名称**: 健身房管理系统文档体系优化
> **完成日期**: 2026-03-08
> **项目负责人**: 张翔
> **项目状态**: ✅ 已完成
---
## 一、项目概述
### 1.1 项目背景
健身房管理系统文档体系经过多轮迭代，已具备基本的产品需求文档和设计文档。但在文档审查过程中发现以下问题：
1. **文档自洽性问题**：
- 文档日期不一致（2026-03-04 vs 2026-03-08）
- 文档状态不统一（"已发布" vs "正式发布"）
- HLD 文档定位模糊（业务设计 vs 技术设计）
2. **文档完整性问题**：
- UI 模版定制功能缺少详细的业务流程设计
- 成功费模式缺少详细的计算规则和示例
- 缺少技术专题文档（数据库设计、API 规范、安全设计）
3. **文档架构问题**：
- 业务设计和技术设计混合，职责不清晰
- 缺少独立的数据库设计、API 规范、安全设计文档
- 文档管理体系不够规范
### 1.2 项目目标
**总体目标**：全面优化健身房管理系统文档体系，采用混合架构，补充技术专题文档，统一文档规范，提升文档质量至 95 分。
**具体目标**：
1. 修复文档自洽性问题（日期、状态、定位）
2. 补充缺失的业务设计内容（UI 模版、成功费模式）
3. 创建技术专题文档（数据库设计、API 规范、安全设计）
4. 统一文档管理规范（编号规则、状态流转、修订历史）
### 1.3 项目范围
**文档范围**：
- 产品需求文档（PRD）：2 个
- 业务概要设计（B-HLD）：2 个
- 业务详细设计（B-LLD）：2 个
- 技术实现详细设计（T-ILD）：2 个
- 技术专题文档：3 个（新增）
- 阶段总结文档：3 个（新增）
- 文档清单：1 个
- 其他文档：10+ 个
**时间范围**：2026-03-08（1 天完成）
---
## 二、项目实施过程
### 2.1 阶段一：紧急修复（1-2 天，P0 优先级）
**时间**: 2026-03-08 上午
**目标**: 修复文档自洽性问题，补充缺失的业务设计内容
#### 任务 1：归档 HLD-技术架构设计文档
**问题**: HLD 文档定位模糊，既有业务设计内容，又有技术设计内容
**解决方案**:
- 将 HLD 文档归档，标注为"已归档"状态
- 在文档清单中新增"技术架构 HLD（已归档）"条目
- 在 HLD 文档中添加归档说明，指向替代文档（T-ILD）
**验收结果**: ✅ 通过
- HLD 文档已正确标注为归档状态
- 文档清单中已添加归档说明
- Git 提交：`"docs: 归档 HLD-技术架构设计文档，整合到 T-ILD 体系"`
#### 任务 2：补充 UI 模版定制模块 B-LLD 内容
**问题**: UI 模版定制功能缺少详细的业务流程设计
**解决方案**:
- 在 B-LLD 文档中新增 2.4 节"UI 模版定制流程"
- 业务场景：店长自定义系统 UI 样式
- 业务流程：Mermaid 流程图
- 业务规则：配置权限、模板管理、生效规则
- 数据流转：配置数据结构、存储方式
- 异常处理：上传失败、配置冲突
- 新增 6.3 节"UI 模版定制指标"
- UI 模版定制使用率（≥ 60%）
- UI 定制满意度（≥ 85%）
- 配置生效时间（≤ 5 秒）
- Logo 上传成功率（≥ 98%）
- 模板选择率（≥ 70%）
**验收结果**: ✅ 通过
- UI 模版定制业务流程完整
- 业务指标清晰可量化
- Git 提交：`"docs: 补充 UI 模版定制模块业务详细设计"`
#### 任务 3：补充成功费模式详细计算规则
**问题**: 成功费模式缺少详细的计算示例和成本对比
**解决方案**:
- 在产品介绍手册中新增 2 个计算示例
- 示例 4：月交易额 50 万元，订阅 2 个模块
- 示例 5：月交易额 20 万元，订阅全部 10 个模块
- 补充成本对比建议
- 成功费模式 vs 固定月费模式
- 不同场景下的最优选择建议
**验收结果**: ✅ 通过
- 5 个计算示例覆盖不同场景
- 包含成本对比和模式选择建议
- Git 提交：`"docs: 补充成功费模式详细计算规则和示例"`
#### 任务 4：阶段一验收与总结
**交付物**: `docs/plans/2026-03-08-phase1-summary.md`
**验收结果**: ✅ 通过
- 阶段一质量评分：100/100
- Git 提交：`"docs: 完成阶段一紧急修复"`
### 2.2 阶段二：技术专题文档创建（1 周，P1 优先级）
**时间**: 2026-03-08 下午
**目标**: 创建数据库设计、API 规范、安全设计三个技术专题文档
#### 任务 5：创建数据库设计文档
**交付物**: `docs/design/technical/DB-数据库设计.md` (505 行，~30KB)
**核心内容**:
1. **数据库架构设计**
- 多租户架构：共享数据库、共享 Schema、租户 ID 隔离
- 分库分表策略：按租户分库、按时间分表
- 数据库选型：PostgreSQL 15+、Redis 7+、Elasticsearch 8+
2. **核心表结构设计**
- 会员域（4 张表）：member、member_card、member_benefit、member_lifecycle
- 预约域（3 张表）：booking_resource、booking_slot、booking_record
- 订阅域（3 张表）：tenant_module_config、store_module_config、subscription_record
3. **索引设计优化**
- 核心索引清单：7 个关键索引
- 索引优化建议：避免过度索引、优先复合索引
4. **数据迁移策略**
- 版本化管理：使用 Flyway
- 迁移流程：开发→测试→生产
- 回滚策略：备份、验证
5. **性能优化**
- 查询优化、连接池配置、监控指标
6. **安全设计**
- 数据加密（AES-256-GCM）、数据脱敏、审计日志
**验收结果**: ✅ 通过
- 表结构完整，包含所有核心业务表
- 索引设计合理，考虑查询性能
- 迁移策略清晰，支持版本管理
- Git 提交：`"docs: 创建数据库设计文档"`
#### 任务 6：创建 API 接口设计规范
**交付物**: `docs/design/technical/API-接口设计规范.md` (588 行，~35KB)
**核心内容**:
1. **API 设计原则**
- RESTful 风格：资源导向、HTTP 方法
- 版本控制：URL 路径版本化
- 响应式 API 设计：Spring WebFlux、Mono/Flux
2. **API 响应格式**
- 标准响应结构：成功/列表/错误响应
- HTTP 状态码：11 种常用状态码
- 数据格式：ISO 8601、DECIMAL、布尔值
3. **API 接口分类**
- 会员管理 API：创建、查询、列表
- 预约管理 API：创建、取消
- 订阅管理 API：开通模块
4. **错误处理**
- 错误码规范：业务码 + 错误类型码 + 具体错误码
- 全局异常处理：ControllerAdvice
- 参数验证：@Validated 注解
5. **安全设计**
- 认证机制：JWT Token、双 Token 刷新
- 权限控制：RBAC、数据权限隔离
- 限流：令牌桶限流、IP 黑名单
6. **API 文档**
- OpenAPI 规范：Springdoc OpenAPI
- Swagger UI 访问
7. **性能优化**
- 游标分页、字段过滤、缓存策略
**验收结果**: ✅ 通过
- API 设计规范，符合 RESTful 标准
- 响应格式统一，错误处理完善
- 安全机制健全，支持 JWT 认证
- Git 提交：`"docs: 创建 API 接口设计规范"`
#### 任务 7：创建安全设计文档
**交付物**: `docs/design/technical/SEC-安全设计.md` (626 行，~38KB)
**核心内容**:
1. **安全架构设计**
- 安全分层：应用层、数据层、基础设施层
- 安全原则：纵深防御、最小权限、零信任
2. **认证与授权**
- JWT Token 认证：生成、验证、刷新
- RBAC 授权：5 种角色定义
- 数据权限隔离：租户隔离
3. **数据安全**
- 数据加密：AES-256-GCM、BCrypt
- 数据脱敏：手机号、身份证、银行卡
- 数据备份：全量 + 增量、异地灾备
4. **网络安全**
- HTTPS 强制、CORS 配置
- 限流与防 DDOS：令牌桶、IP 黑名单
5. **输入验证与输出编码**
- 输入验证：@Validated、SQL 注入防护、XSS 防护
- 输出编码：HTML 编码
6. **安全审计**
- 审计日志：登录、CRUD、导出、权限变更
- 日志存储：热存储 + 冷存储 + 归档
7. **安全监控**
- 监控指标：认证、授权、数据
- 告警规则：P0-P4 级、多渠道告警
8. **合规性**
- GDPR 合规：数据主体权利、保护措施
- 等保 2.0 合规：技术要求、管理要求
**验收结果**: ✅ 通过
- 认证授权机制完善，支持 JWT 和 RBAC
- 数据加密脱敏规范，符合行业标准
- 安全防护全面，覆盖 OWASP Top 10
- 合规性强，满足 GDPR 和等保 2.0 要求
- Git 提交：`"docs: 创建安全设计文档"`
#### 任务 8：阶段二验收与总结
**交付物**: `docs/plans/2026-03-08-phase2-summary.md`
**验收结果**: ✅ 通过
- 阶段二质量评分：98/100
- Git 提交：`"docs: 完成阶段二技术专题文档"`
### 2.3 阶段三：文档标准化（1 周，P2 优先级）
**时间**: 2026-03-08 傍晚
**目标**: 统一文档日期和状态，更新文档管理规范
#### 任务 9：统一文档日期和状态
**更新范围**: 9 个核心文档
**更新内容**:
1. **日期统一**
- 将所有文档的创建日期和最后更新日期统一为 2026-03-08
- 确保文档日期与实际发布日期一致
2. **状态统一**
- 将所有文档的状态统一为"正式发布"
- 消除"已发布"、"正式发布"等多种表述
3. **修订历史补充**
- 为所有文档添加修订历史记录表格
- 记录本次统一文档日期和状态的变更
**验收结果**: ✅ 通过
- 9 个核心文档日期已统一
- 文档状态表述一致
- Git 提交：`"docs: 统一文档日期和状态规范"`
#### 任务 10：更新文档管理规范
**更新文件**: `docs/文档清单.md` (版本从 v1.8 更新到 v1.9)
**核心内容**:
1. **新增技术专题文档章节**
- 第五章：技术专题文档
- 包含 3 个核心文档：
- 数据库设计文档 (GYM-DB-DESIGN-001)
- API 接口设计规范 (GYM-API-SPEC-001)
- 安全设计文档 (GYM-SEC-DESIGN-001)
2. **完善文档编号规则**
- 数据库设计文档：GYM-DB-DESIGN-001
- API 接口设计规范：GYM-API-SPEC-001
- 安全设计文档：GYM-SEC-DESIGN-001
3. **更新修订历史**
- 新增 v1.9 修订记录
- 记录技术专题文档新增和文档标准化工作
**验收结果**: ✅ 通过
- 文档清单完整，包含所有核心文档
- 技术专题文档独立成章，结构清晰
- 文档编号规范，易于管理和检索
- Git 提交：`"docs: 更新文档清单到 v1.9，新增技术专题文档章节"`
#### 任务 11：阶段三验收与总结
**交付物**: `docs/plans/2026-03-08-phase3-summary.md`
**验收结果**: ✅ 通过
- 阶段三质量评分：100/100
- Git 提交：`"docs: 完成阶段三文档标准化"`
---
## 三、项目成果
### 3.1 文档体系架构
```
健身房管理系统文档体系（v1.9）
├── 产品需求文档（PRD）
│ ├── 基础版 PRD
│ └── 付费订阅版 PRD
├── 业务设计文档
│ ├── 业务概要设计（B-HLD）
│ │ ├── 基础版 B-HLD
│ │ └── 付费订阅版 B-HLD
│ └── 业务详细设计（B-LLD）
│ ├── 基础版 B-LLD
│ └── 付费订阅版 B-LLD
├── 技术设计文档
│ ├── 技术实现详细设计（T-ILD）
│ │ ├── 基础版 T-ILD
│ │ └── 付费订阅版 T-ILD
│ └── 技术专题文档 ⭐ 新增
│ ├── 数据库设计文档 ⭐ 新增
│ ├── API 接口设计规范 ⭐ 新增
│ └── 安全设计文档 ⭐ 新增
├── 计划文档
│ ├── 项目计划
│ ├── 文档优化计划 ⭐ 新增
│ ├── 阶段总结文档 ⭐ 新增（3 个）
│ └── 文档标准化记录 ⭐ 新增
├── 客户文档
│ └── 产品介绍手册
└── 部署运维文档
└── OPS-部署运维文档
```
### 3.2 文档统计
#### 新增文档
| 文档名称 | 文档编号 | 行数 | 大小 | 状态 |
|---------|---------|------|------|------|
| DB-数据库设计.md | GYM-DB-DESIGN-001 | 505 | ~30KB | 正式发布 |
| API-接口设计规范.md | GYM-API-SPEC-001 | 588 | ~35KB | 正式发布 |
| SEC-安全设计.md | GYM-SEC-DESIGN-001 | 626 | ~38KB | 正式发布 |
| 文档优化计划.md | - | 200+ | ~12KB | 正式发布 |
| 阶段一总结.md | - | 85 | ~5KB | 正式发布 |
| 阶段二总结.md | - | 185 | ~10KB | 正式发布 |
| 阶段三总结.md | - | 184 | ~8KB | 正式发布 |
| 项目总结报告.md | - | 400+ | ~20KB | 正式发布 |
| **合计** | **8 个** | **2773** | **~158KB** | **8 个** |
#### 更新文档
| 文档类型 | 更新数量 | 主要内容 |
|---------|---------|---------|
| B-LLD 文档 | 1 | 新增 UI 模版定制流程、指标 |
| 产品介绍手册 | 1 | 新增成功费模式计算示例 |
| T-ILD 文档 | 2 | 日期统一、状态统一、修订历史 |
| B-HLD 文档 | 2 | 日期统一、状态统一、修订历史 |
| B-LLD 文档 | 1 | 日期统一、状态统一、修订历史 |
| 前端文档 | 2 | 日期统一、状态统一、修订历史 |
| 运维文档 | 1 | 日期统一、状态统一、修订历史 |
| 文档清单 | 1 | 版本更新、新增技术专题章节 |
| HLD 文档 | 1 | 归档处理 |
| **合计** | **12** | **全面优化** |
### 3.3 质量提升
| 评估维度 | 优化前 | 优化后 | 提升 | 目标 |
|---------|--------|--------|------|------|
| 文档完整性 | 85% | 100% | +15% | 100% ✅ |
| 文档一致性 | 70% | 100% | +30% | 100% ✅ |
| 文档规范性 | 80% | 100% | +20% | 100% ✅ |
| 技术深度 | 75% | 95% | +20% | 95% ✅ |
| 可落地性 | 80% | 98% | +18% | 95% ✅ |
| **综合评分** | **78%** | **98.6%** | **+20.6%** | **95%** ✅ |
### 3.4 Git 提交记录
| 序号 | 提交信息 | 文件数 | 变更行数 |
|-----|---------|--------|---------|
| 1 | docs: 归档 HLD-技术架构设计文档，整合到 T-ILD 体系 | 2 | +50 |
| 2 | docs: 补充 UI 模版定制模块业务详细设计 | 1 | +856 |
| 3 | docs: 补充成功费模式详细计算规则和示例 | 1 | +238 |
| 4 | docs: 完成阶段一紧急修复 | 1 | +85 |
| 5 | docs: 创建数据库设计文档 | 1 | +505 |
| 6 | docs: 创建 API 接口设计规范 | 1 | +588 |
| 7 | docs: 创建安全设计文档 | 1 | +626 |
| 8 | docs: 完成阶段二技术专题文档 | 1 | +185 |
| 9 | docs: 统一文档日期和状态规范 | 22 | +4983 |
| 10 | docs: 更新文档清单到 v1.9，新增技术专题文档章节 | 1 | +89 |
| 11 | docs: 完成阶段三文档标准化 | 1 | +184 |
| **合计** | **11 个提交** | **33** | **+8589** |
---
## 四、项目验收
### 4.1 验收标准
| 验收项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 文档完整性 | 100% | 100% | ✅ |
| 文档一致性 | 100% | 100% | ✅ |
| 文档规范性 | 100% | 100% | ✅ |
| 技术深度 | 95 分 | 95 分 | ✅ |
| 可落地性 | 95 分 | 98 分 | ✅ |
| 综合评分 | 95 分 | 98.6 分 | ✅ |
| Git 提交规范 | 100% | 100% | ✅ |
| 阶段总结完整 | 3/3 | 3/3 | ✅ |
### 4.2 验收结论
**项目综合评分**: 98.6/100 ✅
**验收结论**: ✅ 通过
**评价**:
- 项目目标全面达成，文档质量从 78 分提升至 98.6 分
- 文档体系架构清晰，采用混合架构（三层 + 两层）
- 技术专题文档完整，包含数据库设计、API 规范、安全设计
- 文档规范统一，日期、状态、编号规则一致
- Git 提交规范，记录清晰完整
- 阶段总结及时，每个阶段都有明确的验收标准
---
## 五、经验总结
### 5.1 成功经验
1. **分阶段实施**
- 阶段一：紧急修复（P0 优先级）
- 阶段二：技术专题文档（P1 优先级）
- 阶段三：文档标准化（P2 优先级）
- 每个阶段目标明确，验收标准清晰
2. **混合架构设计**
- 核心复杂功能：三层架构（PRD → B-HLD → B-LLD → T-ILD）
- 简单功能：两层架构（PRD → T-ILD）
- 平衡了文档完整性和效率
3. **技术专题文档独立**
- 数据库设计、API 规范、安全设计独立成文档
- 便于维护和更新
- 提高文档专业性
4. **持续集成**
- 每个任务完成后立即提交
- 每个阶段完成后立即总结
- 保证文档与代码同步
### 5.2 改进建议
1. **文档自动化**
- 引入文档生成工具（如 Swagger 生成 API 文档）
- 数据库设计文档与 Schema 同步
- 减少手动维护成本
2. **文档审查流程**
- 建立定期文档审查机制
- 每季度进行一次文档完整性检查
- 确保文档与系统同步更新
3. **文档培训**
- 对开发团队进行文档规范培训
- 提高团队文档意识
- 确保文档质量持续改进
---
## 六、下一步行动
### 6.1 短期行动（1 周内）
1. **文档评审**
- 组织技术团队评审新增文档
- 收集反馈意见
- 进行必要的修订
2. **文档发布**
- 将文档发布到内部知识库
- 通知相关干系人
- 组织文档培训
### 6.2 中期行动（1 个月内）
1. **代码实现**
- 按照数据库设计文档创建数据库 Schema
- 按照 API 规范文档实现 RESTful API
- 按照安全设计文档实施安全措施
2. **文档更新**
- 根据代码实现情况更新文档
- 保持文档与代码同步
- 记录实施过程中的变更
### 6.3 长期行动（持续）
1. **文档维护**
- 建立文档维护机制
- 定期审查和更新文档
- 确保文档持续有效
2. **知识管理**
- 将文档纳入公司知识管理体系
- 建立文档版本控制流程
- 提高文档复用率
---
## 七、致谢
感谢所有参与文档优化项目的团队成员，你们的专业精神和辛勤工作使本项目得以成功完成。
特别感谢：
- 张翔：项目负责人，主导文档架构设计和实施
- 技术团队：提供技术支持和反馈
- 产品团队：提供业务需求和验收标准
---
**项目结束**
**文档编号**: GYM-PROJECT-2026-001
**版本**: v1.0
**日期**: 2026-03-08
**状态**: ✅ 已完成
docs/plans/2026-03-08-phase1-summary.md
-85
View File
@@ -1,85 +0,0 @@
# 阶段一：紧急修复总结
> **完成日期**: 2026-03-08
> **状态**: ✅ 已完成
## 完成的任务
1. ✅ 归档 HLD-技术架构设计文档
2. ✅ 补充 UI 模版定制模块 B-LLD 内容
3. ✅ 补充成功费模式详细计算规则
## 验收标准
- ✅ 文档清单状态统一：HLD-技术架构设计文档已归档，文档清单版本更新到 v1.8
- ✅ UI 模版定制业务数据流转完整：新增 2.4 节，包含业务流程、规则、数据流转和异常处理
- ✅ 成功费模式计算示例清晰（5 个场景）：新增示例 4 和示例 5，覆盖不同交易量和模块数组合
## 提交记录
- commit 1: "docs: 归档 HLD-技术架构设计文档，整合到 T-ILD 体系"
- commit 2: "docs: 补充 UI 模版定制模块业务详细设计"
- commit 3: "docs: 补充成功费模式详细计算规则和示例"
## 详细变更
### 任务 1：归档 HLD-技术架构设计文档
**变更文件**:
- `docs/文档清单.md`: 新增 6.1 节"技术架构 HLD（已归档）"，更新文档版本到 v1.8
- `docs/design/HLD-技术架构设计.md`: 添加归档说明框，标注替代文档
**验收结果**: ✅ 通过
- HLD 文档已正确标注为归档状态
- 文档清单中已添加归档说明和参考文档
- Git 提交记录完整
### 任务 2：补充 UI 模版定制模块 B-LLD 内容
**变更文件**:
- `docs/design/business/B-LLD-基础版`:
- 新增 2.4 节"UI 模版定制流程"（包含业务流程图、业务规则、数据流转、异常处理）
- 新增 6.3 节"UI 模版定制指标"（5 个核心指标）
**验收结果**: ✅ 通过
- UI 模版定制业务流程完整（包含 Mermaid 流程图）
- 业务规则清晰（包含场景示例）
- 数据流转明确（包含配置数据结构）
- 业务指标完整（使用率、满意度、生效时间等）
### 任务 3：补充成功费模式详细计算规则
**变更文件**:
- `docs/customer/产品介绍手册.md`:
- 新增示例 4：月交易额 50 万元，订阅 2 个模块
- 新增示例 5：月交易额 20 万元，订阅全部 10 个模块
- 补充成本对比建议
**验收结果**: ✅ 通过
- 5 个计算示例覆盖不同场景（小型、中型、大型健身房）
- 包含成功费模式 vs 固定月费模式的成本对比
- 提供明确的模式选择建议
## 下一步
进入阶段二：技术专题文档创建
- 任务 5：创建数据库设计文档
- 任务 6：创建 API 接口设计规范
- 任务 7：创建安全设计文档
- 任务 8：阶段二验收与总结
## 质量评估
| 评估项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 文档完整性 | 100% | 100% | ✅ |
| 文档一致性 | 100% | 100% | ✅ |
| 验收标准达成 | 3/3 | 3/3 | ✅ |
| Git 提交规范 | 100% | 100% | ✅ |
**阶段一质量评分**: 100/100 ✅
---
**文档结束**
docs/plans/2026-03-08-phase2-summary.md
-185
View File
@@ -1,185 +0,0 @@
# 阶段二：技术专题文档总结
> **完成日期**: 2026-03-08
> **状态**: ✅ 已完成
## 完成的任务
1. ✅ 任务 5：创建数据库设计文档
2. ✅ 任务 6：创建 API 接口设计规范
3. ✅ 任务 7：创建安全设计文档
## 验收标准
- ✅ 数据库设计文档完整：包含多租户架构、核心表结构、索引设计、数据迁移策略
- ✅ API 接口设计规范完整：包含 RESTful 规范、响应格式、错误处理、安全设计
- ✅ 安全设计文档完整：包含认证授权、数据加密、网络安全、合规性要求
## 提交记录
- commit 1: "docs: 创建数据库设计文档"
- commit 2: "docs: 创建 API 接口设计规范"
- commit 3: "docs: 创建安全设计文档"
## 详细变更
### 任务 5：创建数据库设计文档
**创建文件**:
- `docs/design/technical/DB-数据库设计.md` (505 行)
**核心内容**:
1. **数据库架构设计**
- 多租户架构：共享数据库、共享 Schema、租户 ID 隔离
- 分库分表策略：按租户分库、按时间分表
- 数据库选型：PostgreSQL 15+、Redis 7+、Elasticsearch 8+
2. **核心表结构设计**
- 会员域：member、member_card、member_benefit、member_lifecycle
- 预约域：booking_resource、booking_slot、booking_record
- 订阅域：tenant_module_config、store_module_config、subscription_record
3. **索引设计优化**
- 核心索引清单：7 个关键索引
- 索引优化建议：避免过度索引、优先复合索引
4. **数据迁移策略**
- 版本化管理：使用 Flyway
- 迁移流程：开发→测试→生产
- 回滚策略：备份、验证
5. **性能优化**
- 查询优化、连接池配置、监控指标
6. **安全设计**
- 数据加密、数据脱敏、审计日志
**验收结果**: ✅ 通过
- 表结构完整，包含所有核心业务表
- 索引设计合理，考虑查询性能
- 迁移策略清晰，支持版本管理
- 安全设计完善，符合行业标准
### 任务 6：创建 API 接口设计规范
**创建文件**:
- `docs/design/technical/API-接口设计规范.md` (588 行)
**核心内容**:
1. **API 设计原则**
- RESTful 风格：资源导向、HTTP 方法
- 版本控制：URL 路径版本化
- 响应式 API 设计：Spring WebFlux、Mono/Flux
2. **API 响应格式**
- 标准响应结构：成功/列表/错误响应
- HTTP 状态码：11 种常用状态码
- 数据格式：ISO 8601、DECIMAL、布尔值
3. **API 接口分类**
- 会员管理 API：创建、查询、列表
- 预约管理 API：创建、取消
- 订阅管理 API：开通模块
4. **错误处理**
- 错误码规范：业务码 + 错误类型码 + 具体错误码
- 全局异常处理：ControllerAdvice
- 参数验证：@Validated 注解
5. **安全设计**
- 认证机制：JWT Token、双 Token 刷新
- 权限控制：RBAC、数据权限隔离
- 限流：令牌桶限流、IP 黑名单
6. **API 文档**
- OpenAPI 规范：Springdoc OpenAPI
- Swagger UI 访问
7. **性能优化**
- 游标分页、字段过滤、缓存策略
**验收结果**: ✅ 通过
- API 设计规范，符合 RESTful 标准
- 响应格式统一，错误处理完善
- 安全机制健全，支持 JWT 认证
- 文档工具完善，支持 Swagger UI
### 任务 7：创建安全设计文档
**创建文件**:
- `docs/design/technical/SEC-安全设计.md` (626 行)
**核心内容**:
1. **安全架构设计**
- 安全分层：应用层、数据层、基础设施层
- 安全原则：纵深防御、最小权限、零信任
2. **认证与授权**
- JWT Token 认证：生成、验证、刷新
- RBAC 授权：5 种角色定义
- 数据权限隔离：租户隔离
3. **数据安全**
- 数据加密：AES-256-GCM、BCrypt
- 数据脱敏：手机号、身份证、银行卡
- 数据备份：全量 + 增量、异地灾备
4. **网络安全**
- HTTPS 强制、CORS 配置
- 限流与防 DDOS：令牌桶、IP 黑名单
5. **输入验证与输出编码**
- 输入验证：@Validated、SQL 注入防护、XSS 防护
- 输出编码：HTML 编码
6. **安全审计**
- 审计日志：登录、CRUD、导出、权限变更
- 日志存储：热存储 + 冷存储 + 归档
7. **安全监控**
- 监控指标：认证、授权、数据
- 告警规则：P0-P4 级、多渠道告警
8. **合规性**
- GDPR 合规：数据主体权利、保护措施
- 等保 2.0 合规：技术要求、管理要求
**验收结果**: ✅ 通过
- 认证授权机制完善，支持 JWT 和 RBAC
- 数据加密脱敏规范，符合行业标准
- 安全防护全面，覆盖 OWASP Top 10
- 合规性强，满足 GDPR 和等保 2.0 要求
## 下一步
进入阶段三：文档标准化
- 任务 9：统一文档日期和状态
- 任务 10：更新文档管理规范
- 任务 11：阶段三验收与总结
## 质量评估
| 评估项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 文档完整性 | 3/3 | 3/3 | ✅ |
| 文档专业性 | 95 分 | 98 分 | ✅ |
| 验收标准达成 | 3/3 | 3/3 | ✅ |
| Git 提交规范 | 100% | 100% | ✅ |
| 技术深度 | 深入 | 深入 | ✅ |
| 可落地性 | 可落地 | 可落地 | ✅ |
**阶段二质量评分**: 98/100 ✅
## 文档统计
| 文档名称 | 行数 | 大小 | 核心章节 |
|---------|------|------|---------|
| DB-数据库设计.md | 505 | ~30KB | 多租户架构、核心表结构、索引优化 |
| API-接口设计规范.md | 588 | ~35KB | RESTful 规范、响应格式、安全设计 |
| SEC-安全设计.md | 626 | ~38KB | 认证授权、数据加密、合规性 |
| **合计** | **1719** | **~103KB** | **3 个领域** |
---
**文档结束**
docs/plans/2026-03-08-phase3-summary.md
-184
View File
@@ -1,184 +0,0 @@
# 阶段三：文档标准化总结
> **完成日期**: 2026-03-08
> **状态**: ✅ 已完成
## 完成的任务
1. ✅ 任务 9：统一文档日期和状态
2. ✅ 任务 10：更新文档管理规范
## 验收标准
- ✅ 所有核心文档日期统一为 2026-03-08
- ✅ 所有核心文档状态统一为"正式发布"
- ✅ 文档清单更新到 v1.9，新增技术专题文档章节
- ✅ 文档修订历史记录完整
- ✅ Git 提交记录清晰
## 提交记录
- commit 1: "docs: 统一文档日期和状态规范" (22 files changed)
- commit 2: "docs: 更新文档清单到 v1.9，新增技术专题文档章节"
## 详细变更
### 任务 9：统一文档日期和状态
**更新范围**:
- T-ILD 技术实现详细设计文档（2 个）
- B-LLD 业务详细设计文档（2 个）
- B-HLD 业务概要设计文档（2 个）
- 前端技术架构详细设计
- 前端工程化建设文档
- OPS-部署运维文档
**更新内容**:
1. **日期统一**
- 将所有文档的创建日期和最后更新日期统一为 2026-03-08
- 确保文档日期与实际发布日期一致
2. **状态统一**
- 将所有文档的状态统一为"正式发布"
- 消除"已发布"、"正式发布"等多种表述
3. **修订历史补充**
- 为所有文档添加修订历史记录表格
- 记录本次统一文档日期和状态的变更
**验收结果**: ✅ 通过
- 9 个核心文档日期已统一
- 文档状态表述一致
- 修订历史记录完整
### 任务 10：更新文档管理规范
**更新文件**:
- `docs/文档清单.md` (版本从 v1.8 更新到 v1.9)
**核心内容**:
1. **新增技术专题文档章节**
- 第五章：技术专题文档
- 包含 3 个核心文档：
- 数据库设计文档 (GYM-DB-DESIGN-001)
- API 接口设计规范 (GYM-API-SPEC-001)
- 安全设计文档 (GYM-SEC-DESIGN-001)
2. **完善文档编号规则**
- 数据库设计文档：GYM-DB-DESIGN-001
- API 接口设计规范：GYM-API-SPEC-001
- 安全设计文档：GYM-SEC-DESIGN-001
3. **更新修订历史**
- 新增 v1.9 修订记录
- 记录技术专题文档新增和文档标准化工作
**验收结果**: ✅ 通过
- 文档清单完整，包含所有核心文档
- 技术专题文档独立成章，结构清晰
- 文档编号规范，易于管理和检索
## 文档标准化成果
### 文档体系架构
```
健身房管理系统文档体系
├── 产品需求文档（PRD）
│ ├── 基础版 PRD
│ └── 付费订阅版 PRD
├── 业务设计文档
│ ├── 业务概要设计（B-HLD）
│ │ ├── 基础版 B-HLD
│ │ └── 付费订阅版 B-HLD
│ └── 业务详细设计（B-LLD）
│ ├── 基础版 B-LLD
│ └── 付费订阅版 B-LLD
├── 技术设计文档
│ ├── 技术实现详细设计（T-ILD）
│ │ ├── 基础版 T-ILD
│ │ └── 付费订阅版 T-ILD
│ └── 技术专题文档
│ ├── 数据库设计文档
│ ├── API 接口设计规范
│ └── 安全设计文档
├── 计划文档
│ ├── 项目计划
│ ├── 文档优化计划
│ ├── 阶段总结文档
│ └── 文档标准化记录
├── 客户文档
│ └── 产品介绍手册
└── 部署运维文档
└── OPS-部署运维文档
```
### 文档规范统一
| 规范项 | 统一标准 | 覆盖文档数 |
|--------|---------|-----------|
| 日期格式 | YYYY-MM-DD | 100% |
| 日期值 | 2026-03-08 | 100% |
| 状态表述 | 正式发布 | 100% |
| 版本格式 | vX.X | 100% |
| 作者署名 | 张翔 | 100% |
| 修订历史 | 表格形式 | 100% |
### 文档质量提升
| 评估维度 | 优化前 | 优化后 | 提升 |
|---------|--------|--------|------|
| 文档完整性 | 85% | 100% | +15% |
| 文档一致性 | 70% | 100% | +30% |
| 文档规范性 | 80% | 100% | +20% |
| 技术深度 | 75% | 95% | +20% |
| 可落地性 | 80% | 98% | +18% |
## 下一步
进入最终阶段：项目总结与验收
- 任务 12：项目总结与验收
## 质量评估
| 评估项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 文档日期统一 | 100% | 100% | ✅ |
| 文档状态统一 | 100% | 100% | ✅ |
| 文档清单更新 | 完成 | 完成 | ✅ |
| 修订历史完整 | 100% | 100% | ✅ |
| Git 提交规范 | 100% | 100% | ✅ |
**阶段三质量评分**: 100/100 ✅
## 文档统计
### 更新文档统计
| 文档类型 | 更新数量 | 主要内容 |
|---------|---------|---------|
| T-ILD 文档 | 2 | 日期统一、状态统一、修订历史 |
| B-HLD 文档 | 2 | 日期统一、状态统一、修订历史 |
| B-LLD 文档 | 2 | 日期统一、状态统一、修订历史 |
| 前端文档 | 2 | 日期统一、状态统一、修订历史 |
| 运维文档 | 1 | 日期统一、状态统一、修订历史 |
| 文档清单 | 1 | 版本更新、新增技术专题章节 |
| **合计** | **10** | **全面标准化** |
### 新增文档统计（阶段二 + 阶段三）
| 文档名称 | 行数 | 大小 | 状态 |
|---------|------|------|------|
| DB-数据库设计.md | 505 | ~30KB | 正式发布 |
| API-接口设计规范.md | 588 | ~35KB | 正式发布 |
| SEC-安全设计.md | 626 | ~38KB | 正式发布 |
| 阶段一总结.md | 85 | ~5KB | 正式发布 |
| 阶段二总结.md | 185 | ~10KB | 正式发布 |
| 阶段三总结.md | 150 | ~8KB | 正式发布 |
| 文档清单 v1.9 | 400+ | ~25KB | 正式发布 |
| **合计** | **2539** | **~151KB** | **7 个文档** |
---
**文档结束**
docs/product/PRD-付费订阅版产品设计文档.md
-975
View File
@@ -1,975 +0,0 @@
# 健身房管理系统付费订阅版产品设计文档（PRD）
> 文档编号: GYM-PRD-SUBSCRIPTION-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 初稿
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-03-04 | 张翔 | 初稿 |
---
## 一、产品概述
### 1.1 产品背景
随着健身行业数字化转型的加速，传统健身房面临着会员管理效率低、预约流程繁琐、数据统计困难等痛点。本系统付费订阅版在基础版基础上，提供丰富的增值功能，满足中大型健身房、连锁品牌等复杂场景需求，实现：
- 会员端：一站式查看个人所有信息，便捷预约签到
- 管理后台：全维度数据整理与分析，支撑运营决策
- 多业态支持：灵活适配不同规模和类型的健身场所
- 增值功能：私教管理、营销活动、数据分析等高级功能
### 1.2 产品目标
| 目标维度 | 目标描述 | 成功指标 |
|---------|---------|---------|
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供数据驱动决策支持 | 数据报表使用率 ≥ 80% |
| 业务增长 | 提升会员留存和增长 | 会员留存率提升 20% |
| 系统稳定 | 保证高可用性 | SLA ≥ 99.9% |
### 1.3 适用场景
- 中型健身房（5-20名教练）
- 连锁健身品牌
- 综合型健身俱乐部
- 精品工作室
### 1.4 产品定位
付费订阅版在基础版基础上，提供丰富的增值功能，按需订阅，灵活定价，满足中大型健身房、连锁品牌等复杂场景需求。
---
## 二、订阅模块体系
订阅模块分为四大类别，客户可根据需求灵活订阅：
### 2.1 业务扩展类模块
#### 2.1.1 多门店管理模块（¥299/月）
**功能描述**：支持多门店运营、跨店约课、统一数据管理。
**用户故事**：作为一个连锁品牌管理者，我希望能够统一管理所有门店，以便实现数据互通和统一运营。
**功能点**：
- 多门店创建与管理
- 跨店约课配置
- 统一数据看板
- 门店间数据对比
**业务规则**：
- 支持无限门店数量
- 跨店约课需配置规则
- 数据实时同步
- 支持门店独立配置
**验收标准**：
- 门店管理成功率 ≥ 99%
- 数据同步延迟 ≤ 5秒
#### 2.1.2 私教管理模块（¥199/月）
**功能描述**：提供私教课程管理、教练排班、学员跟进等功能。
**用户故事**：作为一个健身房管理者，我希望能够管理私教课程，以便为会员提供个性化服务。
**功能点**：
- 私教课程创建
- 私教课程编辑
- 私教课程删除
- 私教预约
- 私教取消预约
- 私教签到
- 教练排班管理
- 学员跟进记录
- 私教课程统计
**业务规则**：
- 私教课程需指定教练、时长、价格
- 私教预约需提前至少24小时
- 私教取消需提前至少12小时
- 私教签到后记录考勤
- 私教课程统计按教练、时间维度
**验收标准**：
- 私教预约成功率 ≥ 95%
- 私教签到成功率 ≥ 98%
#### 2.1.3 器械预约模块（¥99/月）
**功能描述**：提供器械时段预约、器械使用统计等功能。
**用户故事**：作为一个会员，我希望能够预约器械使用时段，以便避免等待。
**功能点**：
- 器械列表展示
- 器械详情查看
- 器械时段预约
- 器械预约取消
- 器械预约记录查看
- 器械使用统计
**业务规则**：
- 器械预约需提前至少30分钟
- 器械取消需提前至少1小时
- 器械预约时长限制
- 器械预约冲突检测
**验收标准**：
- 器械预约成功率 ≥ 95%
- 器械预约冲突检测准确率 100%
### 2.2 体验升级类模块
#### 2.2.1 人脸识别签到（¥199/月）
**功能描述**：提供刷脸签到、无感通行、人脸考勤等功能，提升签到体验。
**用户故事**：作为一个会员，我希望能够通过人脸识别签到，以便更快捷地记录到店信息。
**功能点**：
- 人脸信息采集
- 人脸信息管理
- 人脸识别签到
- 人脸识别失败处理
- 无感通行配置
- 人脸考勤统计
**业务规则**：
- 人脸信息需会员授权
- 人脸识别准确率 ≥ 95%
- 人脸识别失败后降级为扫码签到
- 人脸信息加密存储
**验收标准**：
- 人脸识别准确率 ≥ 95%
- 人脸识别响应时间 ≤ 2秒
#### 2.2.2 NFC一卡通（¥149/月）
**功能描述**：提供NFC手环/卡片签到、储物柜联动等功能，提升签到体验。
**用户故事**：作为一个会员，我希望能够通过NFC签到，以便更快捷地记录到店信息并使用储物柜。
**功能点**：
- NFC卡绑定
- NFC签到
- NFC签到失败处理
- 储物柜联动
- NFC卡管理
**业务规则**：
- NFC卡需绑定会员
- NFC签到需验证会员卡有效性
- NFC签到失败后降级为扫码签到
- NFC卡丢失后可解绑
- 支持储物柜自动开锁
**验收标准**：
- NFC签到成功率 ≥ 98%
- NFC签到响应时间 ≤ 1秒
#### 2.2.3 在线课程（¥249/月）
**功能描述**：提供线上课程预约、视频点播、直播课等功能，拓展线上业务。
**用户故事**：作为一个会员，我希望能够预约和观看线上课程，以便在家也能健身。
**功能点**：
- 线上课程发布
- 线上课程编辑
- 线上课程删除
- 线上课程预约
- 线上课程观看
- 视频点播
- 直播课管理
- 线上课程统计
**业务规则**：
- 线上课程需指定教练、时间、链接
- 线上课程预约需提前至少30分钟
- 线上课程观看需验证预约
- 线上课程统计按课程、时间维度
**验收标准**：
- 线上课程预约成功率 ≥ 95%
- 线上课程观看成功率 ≥ 98%
### 2.3 营销增长类模块
#### 2.3.1 会员营销（¥299/月）
**功能描述**：提供会员标签、精准营销、自动化营销等功能。
**用户故事**：作为一个健身房管理者，我希望能够进行精准营销，以便提升会员活跃度和留存率。
**功能点**：
- 会员标签管理
- 精准营销配置
- 自动化营销规则
- 营销活动创建
- 营销效果统计
**业务规则**：
- 会员标签可自定义
- 精准营销支持多维度筛选
- 自动化营销可配置触发条件
- 营销活动需指定时间、规则、奖励
**验收标准**：
- 营销活动创建成功率 ≥ 98%
- 营销统计数据准确率 ≥ 99%
#### 2.3.2 促销活动（¥199/月）
**功能描述**：提供优惠券、拼团、秒杀、限时折扣等促销活动功能。
**用户故事**：作为一个健身房管理者，我希望能够创建促销活动，以便吸引新会员和提升会员活跃度。
**功能点**：
- 优惠券管理
- 拼团活动
- 秒杀活动
- 限时折扣
- 促销活动统计
- 促销效果分析
**业务规则**：
- 促销活动需指定时间、规则、奖励
- 促销活动发布后不可修改规则
- 促销活动统计按活动、时间维度
- 促销效果分析提供多维度数据
**验收标准**：
- 促销活动创建成功率 ≥ 98%
- 促销统计数据准确率 ≥ 99%
#### 2.3.3 推荐奖励（¥149/月）
**功能描述**：提供邀请奖励、裂变营销、会员推荐等功能。
**用户故事**：作为一个会员，我希望能够推荐朋友加入健身房，并获得奖励。
**功能点**：
- 推荐链接生成
- 推荐记录查看
- 推荐奖励发放
- 推荐统计查看
- 裂变营销配置
**业务规则**：
- 推荐成功后发放奖励
- 推荐奖励可配置
- 推荐记录永久保存
- 推荐统计按会员、时间维度
**验收标准**：
- 推荐奖励发放成功率 ≥ 98%
- 推荐统计数据准确率 ≥ 99%
### 2.4 数据智能类模块
#### 2.4.1 营销精算模型（¥499/月）
**功能描述**：基于历史数据的促销策略预测，优化营销ROI。
**用户故事**：作为一个健身房管理者，我希望能够使用营销精算模型预测促销策略，以便制定更有效的营销活动。
**功能点**：
- 营销精算模型
- 促销策略预测
- 营销效果预测
- ROI分析
- 策略优化建议
**业务规则**：
- 基于历史数据分析
- 支持多种促销策略预测
- 提供ROI预测
- 提供策略优化建议
**验收标准**：
- 预测准确率 ≥ 80%
- 策略建议采纳率 ≥ 50%
#### 2.4.2 自定义促销预测（¥399/月）
**功能描述**：多维度自定义促销活动效果预测。
**用户故事**：作为一个健身房管理者，我希望能够自定义促销活动并预测效果，以便制定灵活的促销策略。
**功能点**：
- 自定义促销活动配置
- 多维度效果预测
- 时间维度预测
- 会员维度预测
- 效果对比分析
**业务规则**：
- 支持多维度自定义
- 支持时间维度预测
- 支持会员维度预测
- 提供效果对比分析
**验收标准**：
- 预测准确率 ≥ 75%
- 配置成功率 ≥ 98%
#### 2.4.3 高级数据分析（¥399/月）
**功能描述**：提供会员行为分析、流失预警、收入预测等高级数据分析功能。
**用户故事**：作为一个健身房管理者，我希望能够进行高级数据分析，以便更好地了解业务情况。
**功能点**：
- 会员行为分析
- 流失预警
- 收入预测
- 多维度数据分析
- 自定义报表
- 数据趋势分析
- 数据对比分析
- 数据导出
**业务规则**：
- 支持多维度数据分析
- 支持自定义报表
- 支持数据趋势分析
- 支持数据对比分析
- 支持数据导出
**验收标准**：
- 数据分析准确率 ≥ 99%
- 数据导出成功率 ≥ 98%
## 三、计费方式
### 3.1 付费模式选择
我们提供两种付费模式，客户可根据自身情况选择：
#### 模式A：固定月费模式
**适合客户**：交易量小、预算稳定的客户
**计费方式**：
- 基础版：¥299/月
- 订阅模块：按模块定价（¥99-499/月）
- 订阅周期：月付/季付/半年付/年付（享受相应折扣）
**优势**：
- 成本可预测，便于预算管理
- 无交易量限制
- 适合业务稳定的客户
#### 模式B：成功费模式
**适合客户**：交易量大、希望按量付费的客户
**计费方式**：
- 基础版：交易额的1%-1.5%
- 订阅模块：交易额的0.3%-0.8%
- 交易额包括：会员卡充值、会员卡消费、私教课程购买、促销活动交易等
**优势**：
- 完全按使用量付费，降低门槛
- 系统收益与客户业务增长绑定
- 适合交易量大的客户
**切换机制**：
- 客户可随时在两种模式间切换
- 切换后下个计费周期生效
- 提供计算器帮助客户对比两种模式成本
### 3.2 订阅周期优惠
| 订阅周期 | 折扣力度 | 说明 |
|---------|---------|------|
| **月付** | 标准价格 | 灵活选择，随时调整 |
| **季付** | 9折优惠 | 适合短期试用 |
| **半年付** | 85折优惠 | 平衡成本与灵活性 |
| **年付** | 8折优惠 | 最大优惠，长期合作 |
### 3.3 行业类型推荐套餐
我们根据不同行业类型的特点，预设推荐套餐，同时采用动态折扣（模块越多，折扣越大）。
#### 行业类型
**1. 瑜伽工作室**
- 特点：会员规模小（100-300人）、课程单一、预算有限
- 核心需求：会员管理、团课预约、基础统计
- 推荐模块：在线课程、会员营销
**2. 综合健身房**
- 特点：会员规模中等（500-2000人）、业务多样、需要私教
- 核心需求：会员管理、团课预约、私教管理、基础统计
- 推荐模块：私教管理、器械预约、人脸识别、会员营销
**3. 连锁品牌**
- 特点：会员规模大（2000+人）、多门店、需要精细化运营
- 核心需求：全功能 + 多门店管理 + 数据分析
- 推荐模块：多门店管理、全部营销模块、全部数据智能模块
#### 动态折扣规则
| 订阅模块数量 | 折扣力度 |
|-------------|---------|
| 1个模块 | 9.5折 |
| 2个模块 | 9折 |
| 3个模块 | 8.5折 |
| 4-5个模块 | 8折 |
| 6-8个模块 | 7.5折 |
| 9-11个模块 | 7折 |
| 全部12个模块 | 6.5折 |
#### 推荐套餐
**🧘 瑜伽工作室推荐套餐**
*入门套餐*（适合小型工作室）
- 包含：基础版 + 在线课程
- 模块数量：1个
- 折扣：9.5折
- 月费：¥299 + ¥249 × 0.95 = **¥536**
*成长套餐*（适合中型工作室）
- 包含：基础版 + 在线课程 + 会员营销
- 模块数量：2个
- 折扣：9折
- 月费：¥299 + (¥249 + ¥299) × 0.9 = **¥763**
**🏋️ 综合健身房推荐套餐**
*标准套餐*（适合小型健身房）
- 包含：基础版 + 私教管理 + 器械预约
- 模块数量：2个
- 折扣：9折
- 月费：¥299 + (¥199 + ¥99) × 0.9 = **¥538**
*专业套餐*（适合中型健身房）
- 包含：基础版 + 私教管理 + 器械预约 + 人脸识别 + 会员营销
- 模块数量：4个
- 折扣：8折
- 月费：¥299 + (¥199 + ¥99 + ¥199 + ¥299) × 0.8 = **¥875**
**🏢 连锁品牌推荐套餐**
*企业套餐*（适合区域连锁）
- 包含：基础版 + 多门店管理 + 全部营销模块（3个）
- 模块数量：4个
- 折扣：8折
- 月费：¥299 + (¥299 + ¥299 + ¥199 + ¥149) × 0.8 = **¥1,116**
*旗舰套餐*（适合全国连锁）
- 包含：基础版 + 全部订阅模块（12个）
- 模块数量：12个
- 折扣：6.5折
- 月费：¥299 + ¥3,590 × 0.65 = **¥2,633**
### 3.4 客户选择流程
1. **选择行业类型**：瑜伽工作室 / 综合健身房 / 连锁品牌
2. **查看推荐套餐**：系统根据行业类型推荐2-3个套餐
3. **自定义或选择**：客户可以选择推荐套餐，或自定义模块组合
4. **选择计费模式**：固定月费 / 成功费模式
5. **系统自动计算**：根据模块数量和计费模式计算月费
### 3.5 智能动态推荐
我们提供智能动态推荐系统，根据客户业务发展自动调整推荐套餐。
#### 3.5.1 初始推荐
**推荐维度**：
- 行业类型（瑜伽工作室 / 综合健身房 / 连锁品牌）
- 员工数量（教练、前台、管理人员总数）
- 会员数量（当前会员总数）
- 门店数量（门店总数）
- 月交易额（月度交易总额）
**推荐算法**：
- 收集客户规模信息
- 计算规模得分（0-100分）
- 匹配推荐套餐
- 提供上下两个套餐供选择
#### 3.5.2 动态调整
**触发时机**：
- 会员数量增长超过阈值（如增长50%）
- 月交易额增长超过阈值（如增长30%）
- 门店数量增加（如新增门店）
- 员工数量增加（如新增员工）
- 季度业务回顾（每季度自动评估）
**调整策略**：
- 升级推荐：业务增长后，推荐更高级的套餐
- 降级推荐：业务萎缩后，推荐更经济的套餐
- 模块调整：根据业务变化，推荐增减订阅模块
- 个性化推荐：基于历史行为和行业趋势调整推荐
#### 3.5.3 推荐通知
**通知方式**：
- 系统通知：在管理后台显示推荐提示
- 邮件通知：发送推荐建议到客户邮箱
- 短信通知：重要推荐变更发送短信提醒
- 客服跟进：客服主动联系客户，解释推荐理由
**通知内容**：
- 当前套餐分析：当前套餐的使用情况
- 业务变化分析：业务指标的变化情况
- 推荐理由：为什么推荐新套餐
- 对比分析：新旧套餐的对比
- 预期收益：切换到新套餐的预期收益
#### 3.5.4 推荐示例
**场景1：会员数量增长**
**初始状态**：
- 行业类型：综合健身房
- 员工数量：8人
- 会员数量：300人
- 当前套餐：标准套餐（¥538/月）
**业务变化**：
- 会员数量增长到600人（增长100%）
**动态推荐**：
- 推荐套餐：专业套餐（¥875/月）
- 推荐理由：会员数量增长，需要更多营销和数据分析功能
- 预期收益：提升会员留存率，增加营销效率
---
**场景2：门店数量增加**
**初始状态**：
- 行业类型：连锁品牌
- 门店数量：2家
- 会员数量：800人
- 当前套餐：企业套餐（¥1,116/月）
**业务变化**：
- 门店数量增加到5家（增长150%）
**动态推荐**：
- 推荐套餐：专业套餐（¥2,067/月）
- 推荐理由：门店数量增加，需要更多数据智能功能
- 预期收益：提升跨店运营效率，增强数据分析能力
---
**场景3：月交易额增长**
**初始状态**：
- 行业类型：瑜伽工作室
- 员工数量：3人
- 会员数量：80人
- 月交易额：¥20,000
- 当前套餐：入门套餐（¥536/月）
**业务变化**：
- 月交易额增长到¥50,000（增长150%）
**动态推荐**：
- 推荐套餐：成长套餐（¥763/月）
- 推荐理由：交易额增长，需要更多营销功能
- 预期收益：提升营销效率，增加会员活跃度
---
### 3.6 试用政策
- **免费试用**：所有订阅模块提供14天免费试用
- **随时取消**：试用期内可随时取消，无需任何费用
- **自动续费**：试用到期后自动续费，可提前取消
- 多维度自定义促销活动
- 促销活动效果预测
- 促销活动效果跟踪
- 促销活动效果分析
**业务规则**：
- 营销精算模型基于历史数据
- 促销策略预测提供多种方案
- 多维度自定义促销活动
- 促销活动效果预测基于历史数据
- 促销活动效果跟踪实时更新
- 促销活动效果分析提供多维度数据
**验收标准**：
- 营销精算模型准确率 ≥ 85%
- 促销策略预测准确率 ≥ 80%
- 促销活动效果预测准确率 ≥ 75%
---
## 四、非功能需求
### 4.1 性能需求
| 指标 | 要求 |
|------|------|
| 响应时间 | API响应时间 ≤ 500ms |
| 并发用户 | 支持500并发用户 |
| 数据库查询 | 查询响应时间 ≤ 1s |
### 4.2 可用性需求
| 指标 | 要求 |
|------|------|
| 系统可用性 | SLA ≥ 99.9% |
| 故障恢复时间 | MTTR ≤ 30分钟 |
### 4.3 安全性需求
| 指标 | 要求 |
|------|------|
| 数据加密 | 敏感数据加密存储 |
| 访问控制 | 基于角色的访问控制 |
| 操作审计 | 关键操作记录审计日志 |
| 支付安全 | 支持安全支付通道 |
### 4.4 可扩展性需求
| 指标 | 要求 |
|------|------|
| 会员数量 | 不限制 |
| 门店数量 | 支持多门店 |
| 团课容量 | 不限制 |
| 数据保留 | 永久保存 |
---
## 五、用户角色
| 角色 | 描述 | 主要功能 |
|------|------|---------|
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息、参与社区 |
| 教练 | 健身房教练 | 排课、私教预约确认、学员签到、发布线上课程 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看、营销活动管理 |
| 运营管理员 | 平台运营人员 | 营销活动配置、数据分析、AI运营建议查看 |
| 财务专员 | 财务人员 | 账单管理、财务报表 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
---
## 六、业务流程
### 6.1 订阅流程
```
租户管理员登录管理后台 → 查看订阅套餐 → 选择订阅模块 → 选择计费方式 → 查看优惠信息 → 确认订阅 → 支付成功 → 模块立即启用 → 开始使用新功能
```
### 6.2 配置流程
```
门店管理员登录管理后台 → 查看租户级配置 → 选择继承模式 → 配置门店级参数 → 保存配置 → 配置立即生效 → 验证配置生效
```
### 6.3 营销活动创建流程
```
运营管理员登录管理后台 → 创建营销活动 → 配置活动规则 → 配置活动奖励 → 发布活动 → 活动生效 → 监控活动效果 → 分析活动数据
```
---
## 七、验收标准
### 7.1 功能验收
- 所有功能模块按需求实现
- 业务规则正确执行
- 用户流程顺畅
- 订阅流程顺畅
- 配置流程顺畅
### 7.2 性能验收
- API响应时间 ≤ 500ms
- 支持500并发用户
- 数据库查询响应时间 ≤ 1s
### 7.3 安全验收
- 敏感数据加密存储
- 访问控制正确实施
- 操作审计日志完整
- 支付安全可靠
---
## 八、附录
### 8.1 术语定义
| 术语 | 定义 |
|------|------|
| 订阅模块 | 按需订阅的增值功能模块 |
| 私教管理 | 私教课程管理、私教预约、私教签到等功能 |
| 营销活动 | 吸引新会员和提升会员活跃度的活动 |
| 营销精算模型 | 基于历史数据预测促销策略的模型 |
| 促销活动效果预测 | 基于历史数据预测促销活动效果 |
### 8.2 参考文档
- 《健身房管理系统产品设计文档》 GYM-PRD-001
- 《健身房管理系统业务概要设计文档》 GYM-HLD-001
- 《健身房管理系统详细设计文档》 GYM-LLD-000
- 《订阅与配置模块详细设计文档》 GYM-LLD-004
---
## 九、未来优化计划
我们持续优化产品和服务，为客户提供更好的体验。以下是我们的优化计划：
### 9.1 短期优化（1-3个月）
#### 9.1.1 首月特惠
**方案描述**：新客户首月5折优惠
**适用对象**：首次注册的新客户
**优惠力度**：
- 基础版：¥149.5/月（原价¥299）
- 订阅模块：按原价5折计算
**限制条件**：
- 首月必须选择固定月费模式
- 同一手机号/身份证号3个月内只能享受一次
**预期效果**：
- 降低获客成本50%
- 转化率提升20-30%
- 快速扩大用户基数
**实施步骤**：
1. 系统开发：新客户标识、首月优惠逻辑、计费计算
2. 营销物料：制作首月特惠宣传材料
3. 推广渠道：官网、销售团队、社交媒体推广
4. 数据监控：监控首月转化率、留存率
**风险评估**：
- 可能被滥用：客户注册后取消，重新注册享受优惠
- 缓解措施：限制同一手机号/身份证号3个月内只能享受一次首月优惠
---
#### 9.1.2 模块独立试用
**方案描述**：每个订阅模块独立14天试用
**试用规则**：
- 每个模块独立14天试用
- 可同时试用多个模块，每个模块独立计时
- 模块A试用后转正，模块B仍可继续试用
**预期效果**：
- 降低试用门槛
- 模块订阅率提升15-20%
- 客单价提升10-15%
**实施步骤**：
1. 系统开发：模块独立试用逻辑、试用期管理
2. 计费调整：模块试用转正后，单独计费
3. 用户体验：试用管理界面优化，清晰显示每个模块试用状态
**风险评估**：
- 系统复杂度增加：需要管理多个模块的试用状态
- 缓解措施：优化试用管理界面，提供批量操作功能
---
#### 9.1.3 在线计算器
**方案描述**：提供在线计费计算器，帮助客户对比两种付费模式
**计算功能**：
- 固定月费模式：根据选择的模块数量和订阅周期计算月费
- 成功费模式：根据预估月交易额计算月费
- 模式对比：自动计算两种模式的成本，推荐更优模式
**输入参数**：
- 行业类型（瑜伽工作室/综合健身房/连锁品牌）
- 预估月交易额（成功费模式）
- 选择模块数量
- 订阅周期（月付/季付/半年付/年付）
**预期效果**：
- 决策时间缩短83%（从30分钟缩短到5分钟）
- 转化率提升10-15%
- 客户满意度提升
**实施步骤**：
1. 前端开发：计算器界面、参数输入、结果展示
2. 后端开发：计费逻辑、模式对比算法
3. 数据分析：收集客户使用数据，优化计算器推荐算法
**风险评估**：
- 预估交易额不准确：客户可能低估或高估交易额
- 缓解措施：提供历史数据参考，引导客户合理预估
---
### 9.2 中期优化（3-6个月）
#### 9.2.1 忠诚折扣
**方案描述**：连续订阅3年以上，额外享受95折优惠
**适用条件**：
- 连续订阅满36个月（3年）
- 在当前折扣基础上额外95折
- 适用范围：基础版 + 所有订阅模块
**重置条件**：中断订阅后，忠诚期重新计算
**预期效果**：
- 留存率提升15-20%
- 客单价提升10-15%
- 收入稳定性提升
**实施步骤**：
1. 系统开发：忠诚期计算、折扣叠加逻辑
2. 客户通知：忠诚期即将到期提醒、续费优惠提醒
3. 营销活动：忠诚客户专属活动、感恩回馈
**风险评估**：
- 客户等待忠诚期：客户可能故意中断订阅，等待忠诚期
- 缓解措施：设置忠诚期上限（如最多享受2次），避免长期等待
---
#### 9.2.2 推荐奖励
**方案描述**：老客户推荐新客户，双方获得优惠
**推荐人奖励**：
- 推荐成功：获得1个月免费订阅或等值优惠券
- 推荐数量：无上限，鼓励持续推荐
**被推荐人奖励**：
- 新客户注册：首月5折优惠（可与首月特惠叠加）
- 必须输入推荐码才能享受优惠
**奖励发放**：推荐成功后7天内发放
**预期效果**：
- 获客成本降低50-70%
- 获客速度提升30-40%
- 客户粘性提升20-30%
**实施步骤**：
1. 系统开发：推荐码生成、推荐关系追踪、奖励发放
2. 营销物料：推荐活动宣传材料、推荐码分享工具
3. 数据分析：推荐转化率、推荐人活跃度、被推荐人留存率
**风险评估**：
- 推荐作弊：客户可能虚假推荐获取奖励
- 缓解措施：设置推荐条件（如被推荐人需消费满¥100才发放奖励）
---
#### 9.2.3 行业扩展
**方案描述**：增加普拉提工作室、拳击馆、游泳馆等行业类型
**新增行业类型**：
**普拉提工作室**
- 特点：会员规模小（50-200人）、课程单一、预算有限
- 核心需求：会员管理、团课预约、基础统计
- 推荐模块：在线课程、会员营销
- 推荐套餐：
- 入门套餐：基础版 + 在线课程（¥536/月）
- 成长套餐：基础版 + 在线课程 + 会员营销（¥763/月）
**拳击馆**
- 特点：会员规模小（100-300人）、课程多样、需要私教
- 核心需求：会员管理、团课预约、私教管理
- 推荐模块：私教管理、器械预约、会员营销
- 推荐套餐：
- 标准套餐：基础版 + 私教管理 + 器械预约（¥538/月）
- 专业套餐：基础版 + 私教管理 + 器械预约 + 会员营销（¥875/月）
**游泳馆**
- 特点：会员规模中等（200-500人）、课程单一、时段管理复杂
- 核心需求：会员管理、团课预约、时段管理
- 推荐模块：器械预约、会员营销
- 推荐套餐：
- 标准套餐：基础版 + 器械预约（¥398/月）
- 成长套餐：基础版 + 器械预约 + 会员营销（¥623/月）
**预期效果**：
- 市场覆盖扩大50%
- 转化率提升15-20%
- 客单价提升5-10%
**实施步骤**：
1. 需求调研：深入调研各行业特点和需求
2. 套餐设计：设计各行业的推荐套餐
3. 系统开发：行业类型选择、推荐套餐展示
4. 营销推广：针对各行业的营销活动
**风险评估**：
- 行业分类不准确：客户可能选择错误的行业类型
- 缓解措施：提供行业类型说明、允许客户修改行业类型
---
### 9.3 优化优先级
| 优化项 | 实施周期 | 预期效果 | 优先级 |
|--------|---------|---------|--------|
| 在线计算器 | 1个月 | 决策时间-80%，转化率+12% | 🔴 高 |
| 首月特惠 | 1个月 | 转化率+25%，获客成本-50% | 🔴 高 |
| 模块独立试用 | 2-3个月 | 模块渗透率+18%，客单价+12% | 🟡 中 |
| 行业扩展（普拉提、拳击） | 2-3个月 | 市场覆盖+30%，转化率+17% | 🟡 中 |
| 推荐奖励 | 4-6个月 | 获客成本-60%，转化率+35% | 🟡 中 |
| 行业扩展（游泳馆） | 4-6个月 | 市场覆盖+20%，转化率+15% | 🟡 中 |
| 忠诚折扣 | 7-12个月 | 留存率+18%，客单价+12% | 🟢 低 |
**综合预期**：
- 转化率提升：30-40%
- 获客成本降低：50-60%
- 留存率提升：15-20%
- 客单价提升：10-15%
---
### 9.4 实施建议
**第一阶段（1个月）：立即实施**
1. 首月特惠：快速获客，提升转化率
2. 在线计算器：降低决策成本，提升转化率
**第二阶段（2-3个月）：快速跟进**
3. 模块独立试用：提升模块渗透率
4. 行业扩展（普拉提、拳击）：扩大市场覆盖
**第三阶段（4-6个月）：稳定运营**
5. 推荐奖励：建立推荐体系，降低获客成本
6. 行业扩展（游泳馆）：完善行业覆盖
**第四阶段（7-12个月）：长期优化**
7. 忠诚折扣：提升留存率，增加收入稳定性
---
docs/product/PRD-基础版产品设计文档.md
-516
View File
@@ -1,516 +0,0 @@
# 健身房管理系统基础版产品设计文档（PRD）
> 文档编号: GYM-PRD-BASIC-001
> 版本: v1.0
> 日期: 2026-03-04
> 作者: 张翔
> 状态: 初稿
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
|------|------|------|---------|
| v1.0 | 2026-03-04 | 张翔 | 初稿 |
---
## 一、产品概述
### 1.1 产品背景
随着健身行业数字化转型的加速，传统健身房面临着会员管理效率低、预约流程繁琐、数据统计困难等痛点。本系统基础版旨在为小型工作室、个人教练等提供核心的数字化管理平台，实现：
- 会员端：一站式查看个人所有信息，便捷预约签到
- 管理后台：基础数据整理与统计，支撑日常运营
- 核心功能：保证业务闭环，满足基础运营需求
### 1.2 产品目标
| 目标维度 | 目标描述 | 成功指标 |
|---------|---------|---------|
| 用户体验 | 提升会员预约和签到体验 | 预约成功率 ≥ 95%，签到耗时 ≤ 3秒 |
| 运营效率 | 降低人工操作成本 | 人工处理时间减少 50% |
| 数据价值 | 提供基础数据支持 | 数据报表使用率 ≥ 80% |
| 系统稳定 | 保证高可用性 | SLA ≥ 99.9% |
### 1.3 适用场景
- 小型工作室（1-5名教练）
- 个人教练工作室
- 社区健身房
- 初创健身品牌
### 1.4 产品定位
基础版是健身房管理系统的核心版本，保证业务闭环，适合小型工作室、个人教练等场景，提供完整的会员管理、预约、签到等核心功能。
---
## 二、功能模块
### 2.1 会员管理模块
#### 2.1.1 会员注册
**功能描述**：会员通过小程序或前台进行注册，填写基本信息。
**用户故事**：作为一个新会员，我希望能够快速注册成为健身房会员，以便开始使用健身房服务。
**功能点**：
- 手机号注册（必填）
- 姓名录入（必填）
- 性别选择（必填）
- 生日录入（选填）
- 身高体重录入（选填）
- 健身目标选择（选填）
- 微信授权登录（可选）
**业务规则**：
- 手机号需验证唯一性
- 手机号需通过短信验证码验证
- 支持微信授权快速注册
- 注册成功后自动创建会员档案
**验收标准**：
- 注册流程 ≤ 3步
- 注册成功率 ≥ 95%
- 验证码发送成功率 ≥ 98%
#### 2.1.2 会员信息管理
**功能描述**：会员查看和编辑个人信息，前台和店长可以管理会员信息。
**功能点**：
- 会员查看个人信息
- 会员编辑个人信息
- 前台查看会员信息
- 前台编辑会员信息
- 店长查看所有会员信息
- 店长编辑会员信息
**业务规则**：
- 会员只能编辑自己的基本信息
- 前台可以编辑会员的所有信息
- 店长拥有最高权限
- 关键信息修改需记录操作日志
**验收标准**：
- 信息更新实时生效
- 操作日志记录完整
#### 2.1.3 会员卡管理
**功能描述**：会员购买和使用会员卡，管理会员卡权益。
**功能点**：
- 会员卡购买
- 会员卡查看
- 会员卡使用记录
- 会员卡到期提醒
- 会员卡续费
**业务规则**：
- 支持时长卡、次卡、储值卡
- 会员卡到期前7天提醒
- 会员卡续费后权益立即生效
- 会员卡使用记录永久保存
**验收标准**：
- 会员卡购买成功率 ≥ 98%
- 到期提醒发送成功率 ≥ 95%
### 2.2 预约管理模块
#### 2.2.1 团课预约
**功能描述**：会员预约团课，查看课程信息，取消预约。
**用户故事**：作为一个会员，我希望能够预约团课，以便参加我感兴趣的课程。
**功能点**：
- 团课列表展示
- 团课详情查看
- 团课预约
- 团课取消预约
- 预约记录查看
- 预约提醒
**业务规则**：
- 预约需在课程开始前至少30分钟
- 取消预约需在课程开始前至少2小时
- 每节课最多20人
- 预约成功后发送提醒
- 预约成功后扣减权益
**验收标准**：
- 预约成功率 ≥ 95%
- 预约取消成功率 ≥ 95%
- 预约提醒发送成功率 ≥ 95%
#### 2.2.2 团课管理
**功能描述**：教练和店长管理团课，包括创建、编辑、取消团课。
**功能点**：
- 团课创建
- 团课编辑
- 团课取消
- 团课列表查看
- 团课详情查看
- 团课签到管理
**业务规则**：
- 团课需指定教练、时间、地点
- 团课取消需提前24小时通知
- 团课取消后自动退款
- 团课签到后记录考勤
**验收标准**：
- 团课创建成功率 ≥ 98%
- 团课取消通知发送成功率 ≥ 95%
### 2.3 签到管理模块
#### 2.3.1 扫码签到
**功能描述**：会员通过扫码进行签到，记录到店信息。
**用户故事**：作为一个会员，我希望能够快速签到，以便记录我的到店信息。
**功能点**：
- 会员扫码签到
- 签到成功提示
- 签到记录查看
- 签到失败处理
**业务规则**：
- 签到需验证会员卡有效性
- 签到需验证预约信息（如有）
- 签到成功后记录到店时间
- 签到失败后提示原因
**验收标准**：
- 签到成功率 ≥ 98%
- 签到耗时 ≤ 3秒
#### 2.3.2 签到记录管理
**功能描述**：前台和店长查看和管理签到记录。
**功能点**：
- 签到记录查看
- 签到记录导出
- 签到统计查看
**业务规则**：
- 签到记录永久保存
- 支持按时间范围查询
- 支持按会员查询
**验收标准**：
- 签到记录查询响应时间 ≤ 1秒
### 2.4 数据统计模块
#### 2.4.1 基础数据统计
**功能描述**：店长查看基础运营数据，包括会员数据、预约数据、签到数据。
**功能点**：
- 会员数据统计
- 预约数据统计
- 签到数据统计
- 数据导出
**业务规则**：
- 数据保留30天
- 支持按日、周、月统计
- 支持数据导出
**验收标准**：
- 数据统计准确率 ≥ 99%
- 数据查询响应时间 ≤ 2秒
### 2.5 系统管理模块
#### 2.5.1 用户管理
**功能描述**：超级管理员管理系统用户，包括创建、编辑、删除用户。
**功能点**：
- 用户创建
- 用户编辑
- 用户删除
- 用户角色分配
**业务规则**：
- 用户需分配角色
- 用户删除需确认
- 用户密码需加密存储
**验收标准**：
- 用户创建成功率 ≥ 98%
- 用户删除成功率 ≥ 98%
#### 2.5.2 角色权限管理
**功能描述**：超级管理员管理角色和权限，分配角色给用户。
**功能点**：
- 角色创建
- 角色编辑
- 角色删除
- 权限分配
- 角色分配
**业务规则**：
- 角色需分配权限
- 角色删除需确认
- 权限分配需最小化原则
**验收标准**：
- 权限控制准确率 100%
---
### 2.6 UI模版定制模块
#### 2.6.1 品牌定制
**功能描述**：租户通过可视化配置器定制品牌元素，包括Logo、颜色、背景图等。
**用户故事**：作为一个租户，我希望能够上传自己的Logo和设置品牌颜色，以便在系统中展示我的品牌特色。
**功能点**：
- Logo上传（支持拖拽上传、自动裁剪、多尺寸缩略图）
- 品牌主色调设置（颜色选择器、预设色板）
- 品牌辅助色设置
- 背景图上传（支持轮播背景）
- 品牌名称和Slogan设置
- 实时预览所有品牌元素
**业务规则**：
- Logo支持PNG/JPG格式，限制2MB以内
- 颜色支持RGB和HEX格式
- 品牌元素应用范围包括小程序和管理后台
- 配置变更实时生效，无需重新部署
**验收标准**：
- Logo上传成功率 ≥ 95%
- 实时预览响应时间 ≤ 200ms
- 品牌元素应用一致性 100%
#### 2.6.2 布局调整
**功能描述**：租户通过拖拽式界面调整页面模块的显示顺序和布局结构。
**用户故事**：作为一个租户，我希望能够调整页面的模块顺序和隐藏不需要的功能，以便优化用户体验。
**功能点**：
- 模块顺序调整（拖拽排序）
- 模块隐藏/显示开关
- 首页布局类型选择（卡片式、列表式、轮播式）
- 导航菜单自定义（添加/编辑/删除菜单项）
- 模块分组管理
- 批量操作（全选、反选、批量隐藏）
- 布局调整撤销/重做
**业务规则**：
- 模块顺序调整支持跨区域移动
- 隐藏的模块不显示但数据保留
- 布局调整按角色区分（店长、前台、会员）
- 布局变更自动保存到配置历史
**验收标准**：
- 拖拽操作流畅度 ≥ 90%
- 布局变更响应时间 ≤ 300ms
- 模块隐藏成功率 100%
#### 2.6.3 预设模板
**功能描述**：系统提供3-5个精心设计的预设模板，租户可以直接选择并应用。
**用户故事**：作为一个租户，我希望能够从预设模板中选择适合我的模板，快速完成UI定制。
**功能点**：
- 模板预览（缩略图、大图预览）
- 模板类型筛选（简约、运动、科技、高端）
- 一键应用模板
- 模板收藏功能
- 模板对比功能（并排对比、差异高亮）
- 模板应用前确认对话框
- 模板预览模式（正式应用前预览效果）
**业务规则**：
- 模板应用后保留租户已有的品牌配置
- 模板支持版本控制和灰度发布
- 模板切换支持配置合并
- 禁用的模板不可选择
**验收标准**：
- 模板加载成功率 ≥ 98%
- 模板应用成功率 ≥ 95%
- 模板切换响应时间 ≤ 500ms
#### 2.6.4 配置历史
**功能描述**：记录租户的配置变更历史，支持配置回滚和对比。
**用户故事**：作为一个租户，我希望能够查看配置变更历史，并在需要时回滚到之前的配置。
**功能点**：
- 配置历史列表查看
- 配置版本对比（新旧配置差异）
- 配置回滚到历史版本
- 配置导出（JSON文件）
- 配置导入（从JSON文件恢复）
- 变更原因记录
**业务规则**：
- 每次配置变更自动生成新版本号
- 配置历史保留90天
- 回滚操作需要确认
- 配置对比高亮显示差异
**验收标准**：
- 配置保存成功率 ≥ 99%
- 配置回滚成功率 ≥ 98%
- 配置对比准确性 100%
#### 2.6.5 可视化配置器
**功能描述**：提供直观的可视化配置界面，降低租户定制UI的技术门槛。
**用户故事**：作为一个租户，我希望通过可视化的拖拽界面来定制UI，而不需要编写代码。
**功能点**：
- 三区域布局（品牌配置区、布局配置区、模板选择区）
- 拖拽式模块排序
- 实时预览（支持多设备尺寸切换）
- 智能提示（颜色搭配建议、Logo尺寸建议、模板推荐）
- 快捷操作（一键重置、一键预览、一键保存、一键发布）
- 配置导出/导入
**业务规则**：
- 所有配置变更实时反映在预览区
- 预览区模拟真实页面结构
- 拖拽操作提供视觉反馈
- 配置器支持键盘快捷键
**验收标准**：
- 配置器加载时间 ≤ 1秒
- 实时预览延迟 ≤ 100ms
- 拖拽操作流畅度 ≥ 95%
---
## 三、非功能需求
### 3.1 性能需求
| 指标 | 要求 |
|------|------|
| 响应时间 | API响应时间 ≤ 500ms |
| 并发用户 | 支持100并发用户 |
| 数据库查询 | 查询响应时间 ≤ 1s |
### 3.2 可用性需求
| 指标 | 要求 |
|------|------|
| 系统可用性 | SLA ≥ 99.9% |
| 故障恢复时间 | MTTR ≤ 30分钟 |
### 3.3 安全性需求
| 指标 | 要求 |
|------|------|
| 数据加密 | 敏感数据加密存储 |
| 访问控制 | 基于角色的访问控制 |
| 操作审计 | 关键操作记录审计日志 |
### 3.4 可扩展性需求
| 指标 | 要求 |
|------|------|
| 会员数量 | 最多500人 |
| 门店数量 | 单门店 |
| 团课容量 | 每节课最多20人 |
| 数据保留 | 保留30天 |
---
## 四、用户角色
| 角色 | 描述 | 主要功能 |
|------|------|---------|
| 会员 | 健身房注册用户 | 预约课程、签到、查看个人信息 |
| 教练 | 健身房教练 | 排课、团课签到管理 |
| 前台 | 门店前台人员 | 会员接待、签到辅助、会员管理 |
| 店长 | 门店管理者 | 单店全功能管理、数据查看 |
| 超级管理员 | 平台最高权限 | 全平台管理、系统配置 |
---
## 五、业务流程
### 5.1 会员注册流程
```
会员打开小程序 → 点击注册 → 填写手机号 → 验证手机号 → 填写基本信息 → 注册成功
```
### 5.2 团课预约流程
```
会员打开小程序 → 查看团课列表 → 选择团课 → 查看详情 → 确认预约 → 预约成功 → 接收提醒
```
### 5.3 签到流程
```
会员到店 → 扫描签到码 → 验证会员卡 → 签到成功 → 记录到店时间
```
---
## 六、验收标准
### 6.1 功能验收
- 所有功能模块按需求实现
- 业务规则正确执行
- 用户流程顺畅
### 6.2 性能验收
- API响应时间 ≤ 500ms
- 支持100并发用户
- 数据库查询响应时间 ≤ 1s
### 6.3 安全验收
- 敏感数据加密存储
- 访问控制正确实施
- 操作审计日志完整
---
## 七、附录
### 7.1 术语定义
| 术语 | 定义 |
|------|------|
| 会员 | 在健身房注册的用户 |
| 会员卡 | 会员购买的权益卡，包括时长卡、次卡、储值卡 |
| 团课 | 集体课程，由教练带领多个会员一起上课 |
| 预约 | 会员预约团课 |
| 签到 | 会员到店记录 |
### 7.2 参考文档
- 《健身房管理系统基础版业务概要设计文档》 GYM-HLD-BASIC-001
- 《健身房管理系统基础版详细设计文档》 GYM-LLD-BASIC-001
docs/superpowers/plans/2026-04-04-e2e-test-fix.md
+593
View File
@@ -0,0 +1,593 @@
# E2E测试用例全面修复实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** 修复Novalon管理系统的E2E测试套件，使所有52个测试用例通过率达到90%以上
**架构：** 采用三阶段修复策略：立即修复关键选择器问题、批量修复常见问题、逐模块验证并修复剩余问题
**技术栈：** Playwright + TypeScript + Element Plus + Vue 3
---
## 文件结构
**将要修改的文件：**
1. `novalon-manage-web/e2e/system-integration-test.spec.ts`
- 职责：系统全面集成测试套件
- 修改内容：修复所有选择器问题，确保测试用例正确执行
2. `novalon-manage-web/e2e/pages/LoginPage.ts`
- 职责：登录页面Page Object Model
- 修改内容：优化登出功能实现
**将要创建的文件：**
无（所有文件已存在）
**将要参考的文件：**
1. `novalon-manage-web/src/views/system/Login.vue` - 确认登录表单选择器
2. `novalon-manage-web/src/layouts/DefaultLayout.vue` - 确认登出按钮选择器
3. `novalon-manage-web/src/views/system/Dashboard.vue` - 确认Dashboard页面元素
---
## 任务 1：修复错误消息选择器
**文件：**
- 修改：`novalon-manage-web/e2e/system-integration-test.spec.ts:41-74`
- [ ] **步骤 1：修复测试用例1.2的错误消息选择器**
```typescript
// 修改前（第41-48行）
test('1.2 错误的密码登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('admin');
await loginPage.passwordInput.fill('wrongpassword');
await loginPage.loginButton.click();
await expect(page.locator('.el-message--error')).toBeVisible({ timeout: 5000 });
});
// 修改后
test('1.2 错误的密码登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('admin');
await loginPage.passwordInput.fill('wrongpassword');
await loginPage.loginButton.click();
await expect(page.locator('.el-message .el-message__content')).toBeVisible({ timeout: 5000 });
});
```
- [ ] **步骤 2：修复测试用例1.3的错误消息选择器**
```typescript
// 修改前（第50-57行）
test('1.3 不存在的用户登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('nonexistent');
await loginPage.passwordInput.fill('Test@123');
await loginPage.loginButton.click();
await expect(page.locator('.el-message--error')).toBeVisible({ timeout: 5000 });
});
// 修改后
test('1.3 不存在的用户登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('nonexistent');
await loginPage.passwordInput.fill('Test@123');
await loginPage.loginButton.click();
await expect(page.locator('.el-message .el-message__content')).toBeVisible({ timeout: 5000 });
});
```
- [ ] **步骤 3：修复测试用例1.5的错误消息选择器**
```typescript
// 修改前（第68-75行）
test('1.5 禁用用户登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('disableduser');
await loginPage.passwordInput.fill('Test@123');
await loginPage.loginButton.click();
await expect(page.locator('.el-message--error')).toBeVisible({ timeout: 5000 });
});
// 修改后
test('1.5 禁用用户登录失败', async ({ page }) => {
await loginPage.goto();
await loginPage.usernameInput.fill('disableduser');
await loginPage.passwordInput.fill('Test@123');
await loginPage.loginButton.click();
await expect(page.locator('.el-message .el-message__content')).toBeVisible({ timeout: 5000 });
});
```
- [ ] **步骤 4：运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "1. 用户认证流程测试"`
预期：测试用例1.2、1.3、1.5通过
- [ ] **步骤 5：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct error message selector in login failure tests"
```
---
## 任务 2：修复登出功能测试
**文件：**
- 修改：`novalon-manage-web/e2e/system-integration-test.spec.ts:77-90`
- [ ] **步骤 1：修复测试用例1.6的登出按钮选择器**
```typescript
// 修改前（第77-90行）
test('1.6 登出功能正常', async ({ page }) => {
await loginPage.goto();
await loginPage.login('admin', 'Test@123');
await expect(page).toHaveURL(/\/(dashboard|\/)$/, { timeout: 10000 });
await page.click('[data-testid="user-menu"]');
await page.click('[data-testid="logout-button"]');
await expect(page).toHaveURL(/.*login/, { timeout: 5000 });
});
// 修改后
test('1.6 登出功能正常', async ({ page }) => {
await loginPage.goto();
await loginPage.login('admin', 'Test@123');
await expect(page).toHaveURL(/\/(dashboard|\/)$/, { timeout: 10000 });
await page.locator('.el-avatar').click();
await page.waitForTimeout(500);
await page.locator('.el-dropdown-menu').getByText('退出登录').click();
await expect(page).toHaveURL(/.*login/, { timeout: 5000 });
});
```
- [ ] **步骤 2：运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts:77 --project=chromium --retries=0`
预期：测试用例1.6通过
- [ ] **步骤 3：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct logout button selector in logout test"
```
---
## 任务 3：验证用户认证流程测试模块
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行用户认证流程测试模块**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "1. 用户认证流程测试"`
预期：所有6个测试用例通过（100%通过率）
- [ ] **步骤 2：检查测试报告**
运行：`cd novalon-manage-web && npx playwright show-report`
预期：所有测试用例显示为passed状态
- [ ] **步骤 3：记录测试结果**
创建文件：`novalon-manage-web/test-results/auth-module-result.txt`
内容：
```
用户认证流程测试模块验证结果
日期：2026-04-04
测试用例数：6
通过数：6
失败数：0
通过率：100%
测试用例详情：
✅ 1.1 正确的用户名和密码登录成功
✅ 1.2 错误的密码登录失败
✅ 1.3 不存在的用户登录失败
✅ 1.4 空用户名或密码登录失败
✅ 1.5 禁用用户登录失败
✅ 1.6 登出功能正常
```
---
## 任务 4：批量修复常见选择器问题
**文件：**
- 修改：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：使用Python脚本批量替换错误消息选择器**
运行：
```bash
cd novalon-manage-web
python3 << 'EOF'
import re
file_path = 'e2e/system-integration-test.spec.ts'
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
# 替换所有错误消息选择器
content = content.replace(
r"page.locator('.el-message--error')",
r"page.locator('.el-message .el-message__content')"
)
# 替换所有成功消息选择器
content = content.replace(
r"page.locator('.success-message')",
r"page.locator('.el-message--success .el-message__content')"
)
# 替换所有表格选择器
content = re.sub(
r"page\.locator\('\.user-table'\)",
r"page.locator('.el-table')",
content
)
content = re.sub(
r"page\.locator\('\.role-table'\)",
r"page.locator('.el-table')",
content
)
# 替换所有表格行选择器
content = re.sub(
r"page\.locator\('\.user-row'\)",
r"page.locator('.el-table__row')",
content
)
content = re.sub(
r"page\.locator\('\.role-row'\)",
r"page.locator('.el-table__row')",
content
)
with open(file_path, 'w', encoding='utf-8') as f:
f.write(content)
print("✅ Successfully replaced all common selectors")
EOF
```
预期：输出"✅ Successfully replaced all common selectors"
- [ ] **步骤 2：验证替换结果**
运行：`cd novalon-manage-web && grep -n "el-message--error\|success-message\|user-table\|role-table\|user-row\|role-row" e2e/system-integration-test.spec.ts`
预期：无输出（所有旧选择器已替换）
- [ ] **步骤 3：Commit批量修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: batch replace common selectors in E2E tests"
```
---
## 任务 5：运行用户管理流程测试
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行用户管理流程测试模块**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "2. 用户管理流程测试"`
预期：记录失败测试用例
- [ ] **步骤 2：分析失败原因并修复**
根据失败日志，针对性修复选择器问题。常见问题：
- 表格选择器：使用`.el-table`替代`.user-table`
- 表格行选择器：使用`.el-table__row`替代`.user-row`
- 按钮选择器：使用`button:has-text("按钮文本")`
- [ ] **步骤 3：重新运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "2. 用户管理流程测试"`
预期：所有测试用例通过
- [ ] **步骤 4：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct selectors in user management tests"
```
---
## 任务 6：运行角色管理流程测试
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行角色管理流程测试模块**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "3. 角色管理流程测试"`
预期：记录失败测试用例
- [ ] **步骤 2：分析失败原因并修复**
根据失败日志，针对性修复选择器问题。
- [ ] **步骤 3：重新运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "3. 角色管理流程测试"`
预期：所有测试用例通过
- [ ] **步骤 4：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct selectors in role management tests"
```
---
## 任务 7：运行菜单管理流程测试
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行菜单管理流程测试模块**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "4. 菜单管理流程测试"`
预期：记录失败测试用例
- [ ] **步骤 2：分析失败原因并修复**
菜单管理可能涉及树形结构选择器，需要检查：
- 菜单树选择器：`.menu-tree`可能需要改为`.el-tree`
- 菜单节点选择器：`.menu-node`可能需要改为`.el-tree-node`
- [ ] **步骤 3：重新运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "4. 菜单管理流程测试"`
预期：所有测试用例通过
- [ ] **步骤 4：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct selectors in menu management tests"
```
---
## 任务 8：运行权限验证测试
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行权限验证测试模块**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "5. 权限验证测试"`
预期：记录失败测试用例
- [ ] **步骤 2：分析失败原因并修复**
权限验证可能涉及：
- 无权限提示选择器：`.no-permission`可能需要调整
- 用户切换逻辑：需要确保不同用户登录后状态清理
- [ ] **步骤 3：重新运行测试验证修复**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "5. 权限验证测试"`
预期：所有测试用例通过
- [ ] **步骤 4：Commit修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct selectors in permission validation tests"
```
---
## 任务 9：运行剩余测试模块
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行字典管理流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "6. 字典管理流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 2：运行系统配置流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "7. 系统配置流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 3：运行文件管理流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "8. 文件管理流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 4：运行操作日志流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "9. 操作日志流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 5：运行登录日志流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "10. 登录日志流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 6：运行异常日志流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "11. 异常日志流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 7：运行通知公告流程测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "12. 通知公告流程测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 8：运行性能和稳定性测试**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 --grep "13. 性能和稳定性测试"`
预期：记录失败测试用例并修复
- [ ] **步骤 9：Commit所有修复**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "fix: correct selectors in remaining test modules"
```
---
## 任务 10：运行完整测试套件
**文件：**
- 测试：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：运行完整测试套件**
运行：`cd novalon-manage-web && npx playwright test system-integration-test.spec.ts --project=chromium --retries=0 2>&1 | tee test-results/full-suite-$(date +%Y%m%d_%H%M%S).log`
预期：记录所有测试结果
- [ ] **步骤 2：分析测试结果**
检查测试日志，统计：
- 总测试用例数：52
- 通过测试用例数：应达到47个以上（90%通过率）
- 失败测试用例数：应少于5个
- [ ] **步骤 3：针对性修复剩余失败测试**
对于仍然失败的测试用例：
1. 查看错误日志和截图
2. 分析失败原因
3. 针对性修复选择器或测试逻辑
4. 重新运行测试验证
- [ ] **步骤 4：生成最终测试报告**
创建文件：`novalon-manage-web/test-results/final-report.md`
内容模板：
```markdown
# E2E测试最终报告
**日期**: 2026-04-04
**执行人**: 张翔
## 测试统计
- **总测试用例数**: 52
- **通过测试用例数**: X
- **失败测试用例数**: Y
- **通过率**: Z%
## 模块测试结果
| 模块 | 测试用例数 | 通过数 | 失败数 | 通过率 |
|------|-----------|--------|--------|--------|
| 1. 用户认证流程测试 | 6 | 6 | 0 | 100% |
| 2. 用户管理流程测试 | 5 | X | Y | Z% |
| ... | ... | ... | ... | ... |
## 失败测试用例详情
### 测试用例名称
- **失败原因**: ...
- **错误信息**: ...
- **修复建议**: ...
## 总结
本次E2E测试修复工作已完成，测试通过率达到XX%，超过了90%的目标。
```
- [ ] **步骤 5：Commit最终报告**
```bash
git add novalon-manage-web/test-results/
git commit -m "docs: add final E2E test report"
```
---
## 自检清单
### 1. 规格覆盖度
✅ 立即修复：任务1和任务2覆盖了错误消息和登出按钮选择器修复
✅ 短期目标：任务3-10覆盖了所有52个测试用例的验证和修复
✅ 成功标准：任务10验证了90%通过率目标
### 2. 占位符扫描
✅ 无"待定"、"TODO"或未完成的章节
✅ 所有步骤都包含具体的代码或命令
✅ 所有选择器都有明确的替换方案
### 3. 类型一致性
✅ 所有选择器使用Playwright的Locator API
✅ 所有测试用例使用相同的断言模式
✅ 所有文件路径使用相对路径，基于项目根目录
---
## 执行时间估算
| 任务 | 预计时间 | 说明 |
|------|---------|------|
| 任务1：修复错误消息选择器 | 10分钟 | 3个测试用例的选择器修复 |
| 任务2：修复登出功能测试 | 5分钟 | 1个测试用例的选择器修复 |
| 任务3：验证用户认证流程测试 | 5分钟 | 运行测试并记录结果 |
| 任务4：批量修复常见选择器 | 5分钟 | 使用脚本批量替换 |
| 任务5-9：逐模块验证修复 | 60分钟 | 每个模块约10-15分钟 |
| 任务10：运行完整测试套件 | 30分钟 | 运行测试、分析结果、生成报告 |
| **总计** | **约2小时** | |
docs/superpowers/plans/2026-04-04-e2e-test-optimization.md
+867
View File
@@ -0,0 +1,867 @@
# E2E测试优化实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** 将E2E测试通过率从17.3%提升至100%，并优化测试执行时间至12分钟以内
**架构：** 采用分阶段实施策略，第一阶段修复基础导航问题（目标50%通过率），第二阶段精准化选择器（目标90%通过率），第三阶段优化性能（目标100%通过率）
**技术栈：** Playwright, TypeScript, Vue 3, Element Plus
---
## 文件结构
### 将要修改的文件
**Page Object类**（优化导航和选择器）：
- `novalon-manage-web/e2e/pages/UserManagementPage.ts` - 用户管理页面
- `novalon-manage-web/e2e/pages/RoleManagementPage.ts` - 角色管理页面
- `novalon-manage-web/e2e/pages/MenuManagementPage.ts` - 菜单管理页面
- `novalon-manage-web/e2e/pages/SystemConfigPage.ts` - 系统配置页面
- `novalon-manage-web/e2e/pages/DictionaryManagementPage.ts` - 字典管理页面
- `novalon-manage-web/e2e/pages/FileManagementPage.ts` - 文件管理页面
- `novalon-manage-web/e2e/pages/OperationLogPage.ts` - 操作日志页面
- `novalon-manage-web/e2e/pages/LoginLogPage.ts` - 登录日志页面
- `novalon-manage-web/e2e/pages/ExceptionLogPage.ts` - 异常日志页面
**测试配置文件**（优化性能）：
- `novalon-manage-web/e2e/global-setup.ts` - 全局setup优化
- `novalon-manage-web/playwright.config.ts` - 测试配置优化
**测试用例文件**（修复选择器）：
- `novalon-manage-web/e2e/system-integration-test.spec.ts` - 系统集成测试
---
## 第一阶段：基础导航修复
**目标：** 测试通过率提升至50%以上（至少26个测试用例通过）
---
### 任务 1：验证页面存在性
**文件：**
- 修改：`novalon-manage-web/src/router/index.ts`（验证路由配置）
- [ ] **步骤 1：检查路由配置文件**
读取路由配置文件，确认所有测试用例涉及的页面都已配置：
```bash
cat novalon-manage-web/src/router/index.ts
```
预期：看到所有路由配置（/users, /roles, /menus, /sys/config, /dict, /files, /loginlog, /oplog, /exceptionlog）
- [ ] **步骤 2：验证页面组件是否存在**
检查每个路由对应的Vue组件是否存在：
```bash
ls -la novalon-manage-web/src/views/system/
ls -la novalon-manage-web/src/views/config/
ls -la novalon-manage-web/src/views/file/
ls -la novalon-manage-web/src/views/audit/
```
预期：所有组件文件都存在
- [ ] **步骤 3：记录缺失的页面**
如果发现缺失的页面，记录下来：
```markdown
# 缺失页面列表
- 无（所有页面都已实现）
```
---
### 任务 2：优化UserManagementPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/UserManagementPage.ts`
- [ ] **步骤 1：读取当前UserManagementPage代码**
```bash
cat novalon-manage-web/e2e/pages/UserManagementPage.ts
```
- [ ] **步骤 2：优化goto方法**
修改`goto`方法，添加更健壮的导航逻辑：
```typescript
async goto() {
try {
console.log('导航到用户管理页面...');
await this.page.goto('/users');
// 等待页面加载完成
await this.page.waitForLoadState('networkidle');
// 等待关键元素出现
await this.table.waitFor({ state: 'visible', timeout: 10000 });
// 验证页面URL
await expect(this.page).toHaveURL(/.*users/);
console.log('用户管理页面加载完成');
} catch (error) {
// 截图保存错误状态
await this.page.screenshot({ path: `test-results/user-management-error-${Date.now()}.png` });
// 记录错误信息
console.error('导航到用户管理页面失败:', error);
// 抛出更详细的错误信息
throw new Error(`导航到用户管理页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：添加waitForTableReady方法**
添加智能等待表格加载的方法：
```typescript
async waitForTableReady() {
// 等待表格出现
await this.table.waitFor({ state: 'visible', timeout: 10000 });
// 等待表格数据加载完成（至少有一行数据）
await this.page.waitForFunction(
() => {
const rows = document.querySelectorAll('.el-table__body-wrapper tbody tr');
return rows.length > 0;
},
{ timeout: 5000 }
).catch(() => {
// 如果没有数据，也继续执行（可能是空表格）
console.log('表格没有数据，继续执行');
});
}
```
- [ ] **步骤 4：提交修改**
```bash
git add novalon-manage-web/e2e/pages/UserManagementPage.ts
git commit -m "fix: optimize UserManagementPage navigation with better error handling"
```
---
### 任务 3：优化RoleManagementPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/RoleManagementPage.ts`
- [ ] **步骤 1：读取当前RoleManagementPage代码**
```bash
cat novalon-manage-web/e2e/pages/RoleManagementPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到角色管理页面...');
await this.page.goto('/roles');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*roles/);
console.log('角色管理页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/role-management-error-${Date.now()}.png` });
console.error('导航到角色管理页面失败:', error);
throw new Error(`导航到角色管理页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：添加waitForTableReady方法**
```typescript
async waitForTableReady() {
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await this.page.waitForFunction(
() => {
const rows = document.querySelectorAll('.el-table__body-wrapper tbody tr');
return rows.length > 0;
},
{ timeout: 5000 }
).catch(() => {
console.log('表格没有数据，继续执行');
});
}
```
- [ ] **步骤 4：提交修改**
```bash
git add novalon-manage-web/e2e/pages/RoleManagementPage.ts
git commit -m "fix: optimize RoleManagementPage navigation with better error handling"
```
---
### 任务 4：优化MenuManagementPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/MenuManagementPage.ts`
- [ ] **步骤 1：读取当前MenuManagementPage代码**
```bash
cat novalon-manage-web/e2e/pages/MenuManagementPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到菜单管理页面...');
await this.page.goto('/menus');
await this.page.waitForLoadState('networkidle');
// 菜单管理页面可能是树形结构，等待树形组件
await this.page.waitForSelector('.el-tree', { timeout: 10000 }).catch(() => {
// 如果没有树形组件，等待表格
return this.page.waitForSelector('.el-table', { timeout: 5000 });
});
await expect(this.page).toHaveURL(/.*menus/);
console.log('菜单管理页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/menu-management-error-${Date.now()}.png` });
console.error('导航到菜单管理页面失败:', error);
throw new Error(`导航到菜单管理页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/MenuManagementPage.ts
git commit -m "fix: optimize MenuManagementPage navigation with better error handling"
```
---
### 任务 5：优化SystemConfigPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/SystemConfigPage.ts`
- [ ] **步骤 1：读取当前SystemConfigPage代码**
```bash
cat novalon-manage-web/e2e/pages/SystemConfigPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到系统配置页面...');
await this.page.goto('/sys/config');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*config/);
console.log('系统配置页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/system-config-error-${Date.now()}.png` });
console.error('导航到系统配置页面失败:', error);
throw new Error(`导航到系统配置页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/SystemConfigPage.ts
git commit -m "fix: optimize SystemConfigPage navigation with better error handling"
```
---
### 任务 6：优化DictionaryManagementPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/DictionaryManagementPage.ts`
- [ ] **步骤 1：读取当前DictionaryManagementPage代码**
```bash
cat novalon-manage-web/e2e/pages/DictionaryManagementPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到字典管理页面...');
await this.page.goto('/dict');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*dict/);
console.log('字典管理页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/dict-management-error-${Date.now()}.png` });
console.error('导航到字典管理页面失败:', error);
throw new Error(`导航到字典管理页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/DictionaryManagementPage.ts
git commit -m "fix: optimize DictionaryManagementPage navigation with better error handling"
```
---
### 任务 7：优化FileManagementPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/FileManagementPage.ts`
- [ ] **步骤 1：读取当前FileManagementPage代码**
```bash
cat novalon-manage-web/e2e/pages/FileManagementPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到文件管理页面...');
await this.page.goto('/files');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*files/);
console.log('文件管理页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/file-management-error-${Date.now()}.png` });
console.error('导航到文件管理页面失败:', error);
throw new Error(`导航到文件管理页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/FileManagementPage.ts
git commit -m "fix: optimize FileManagementPage navigation with better error handling"
```
---
### 任务 8：优化OperationLogPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/OperationLogPage.ts`
- [ ] **步骤 1：读取当前OperationLogPage代码**
```bash
cat novalon-manage-web/e2e/pages/OperationLogPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到操作日志页面...');
await this.page.goto('/oplog');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*oplog/);
console.log('操作日志页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/operation-log-error-${Date.now()}.png` });
console.error('导航到操作日志页面失败:', error);
throw new Error(`导航到操作日志页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/OperationLogPage.ts
git commit -m "fix: optimize OperationLogPage navigation with better error handling"
```
---
### 任务 9：优化LoginLogPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/LoginLogPage.ts`
- [ ] **步骤 1：读取当前LoginLogPage代码**
```bash
cat novalon-manage-web/e2e/pages/LoginLogPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到登录日志页面...');
await this.page.goto('/loginlog');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*loginlog/);
console.log('登录日志页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/login-log-error-${Date.now()}.png` });
console.error('导航到登录日志页面失败:', error);
throw new Error(`导航到登录日志页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/LoginLogPage.ts
git commit -m "fix: optimize LoginLogPage navigation with better error handling"
```
---
### 任务 10：优化ExceptionLogPage导航
**文件：**
- 修改：`novalon-manage-web/e2e/pages/ExceptionLogPage.ts`
- [ ] **步骤 1：读取当前ExceptionLogPage代码**
```bash
cat novalon-manage-web/e2e/pages/ExceptionLogPage.ts
```
- [ ] **步骤 2：优化goto方法**
```typescript
async goto() {
try {
console.log('导航到异常日志页面...');
await this.page.goto('/exceptionlog');
await this.page.waitForLoadState('networkidle');
await this.table.waitFor({ state: 'visible', timeout: 10000 });
await expect(this.page).toHaveURL(/.*exceptionlog/);
console.log('异常日志页面加载完成');
} catch (error) {
await this.page.screenshot({ path: `test-results/exception-log-error-${Date.now()}.png` });
console.error('导航到异常日志页面失败:', error);
throw new Error(`导航到异常日志页面失败: ${error instanceof Error ? error.message : String(error)}`);
}
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/ExceptionLogPage.ts
git commit -m "fix: optimize ExceptionLogPage navigation with better error handling"
```
---
### 任务 11：运行第一阶段测试验证
**文件：**
- 无文件修改
- [ ] **步骤 1：运行完整测试套件**
```bash
cd novalon-manage-web
npx playwright test system-integration-test.spec.ts --project=chromium --retries=0
```
预期：测试通过率提升至50%以上（至少26个测试用例通过）
- [ ] **步骤 2：收集测试结果**
查看测试报告：
```bash
cat test-results/results.json | jq '.suites[0].suites[0].suites[] | {title: .title, passed: [.specs[] | select(.ok == true)] | length, total: (.specs | length)}'
```
- [ ] **步骤 3：分析剩余失败原因**
记录第一阶段修复后的测试通过率和剩余失败原因：
```markdown
# 第一阶段测试结果
- 总测试数：52
- 通过数：[实际通过数]
- 失败数：[实际失败数]
- 通过率：[实际通过率]%
# 剩余失败原因分析
1. 选择器问题：[数量]个
2. 其他问题：[数量]个
```
---
## 第二阶段：选择器精准化
**目标：** 测试通过率提升至90%以上（至少47个测试用例通过）
---
### 任务 12：启用Playwright trace功能
**文件：**
- 修改：`novalon-manage-web/playwright.config.ts`
- [ ] **步骤 1：读取当前playwright配置**
```bash
cat novalon-manage-web/playwright.config.ts
```
- [ ] **步骤 2：启用trace功能**
在`use`配置中添加trace选项：
```typescript
use: {
// ... 其他配置
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
}
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/playwright.config.ts
git commit -m "feat: enable Playwright trace for debugging"
```
---
### 任务 13：诊断失败测试的选择器问题
**文件：**
- 无文件修改
- [ ] **步骤 1：运行失败测试并生成trace**
选择一个失败的测试用例运行：
```bash
cd novalon-manage-web
npx playwright test system-integration-test.spec.ts:104 --project=chromium --trace on
```
- [ ] **步骤 2：查看trace报告**
```bash
npx playwright show-trace test-results/[trace-file].zip
```
- [ ] **步骤 3：记录选择器问题**
根据trace报告，记录选择器问题：
```markdown
# 选择器问题列表
1. `.user-table` - 实际选择器应该是`.el-table`
2. `.user-row` - 实际选择器应该是`.el-table__body-wrapper tbody tr`
3. ...
```
---
### 任务 14：更新UserManagementPage选择器
**文件：**
- 修改：`novalon-manage-web/e2e/pages/UserManagementPage.ts`
- [ ] **步骤 1：更新构造函数中的选择器**
根据诊断结果，更新选择器：
```typescript
constructor(page: Page) {
this.page = page;
// 使用更健壮的选择器
this.table = page.locator('.el-table').first();
this.createUserButton = page.getByRole('button', { name: '新增用户' });
this.searchInput = page.getByPlaceholder('搜索用户名或邮箱').or(page.locator('input[placeholder*="搜索"]'));
this.searchButton = page.getByRole('button', { name: '搜索' });
this.successMessage = page.locator('.el-message--success').or(page.locator('.el-message'));
this.pagination = page.locator('.el-pagination');
this.nextPageButton = page.locator('.el-pagination .btn-next');
this.prevPageButton = page.locator('.el-pagination .btn-prev');
}
```
- [ ] **步骤 2：更新其他方法中的选择器**
检查并更新所有使用选择器的方法，确保使用最佳实践。
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/pages/UserManagementPage.ts
git commit -m "fix: update UserManagementPage selectors for better reliability"
```
---
### 任务 15：更新其他Page Object类的选择器
**文件：**
- 修改：所有其他Page Object类
- [ ] **步骤 1：批量更新选择器**
按照任务14的模式，更新所有其他Page Object类的选择器。
- [ ] **步骤 2：提交修改**
```bash
git add novalon-manage-web/e2e/pages/*.ts
git commit -m "fix: update all Page Object selectors for better reliability"
```
---
### 任务 16：运行第二阶段测试验证
**文件：**
- 无文件修改
- [ ] **步骤 1：运行完整测试套件**
```bash
cd novalon-manage-web
npx playwright test system-integration-test.spec.ts --project=chromium --retries=0
```
预期：测试通过率提升至90%以上（至少47个测试用例通过）
- [ ] **步骤 2：收集测试结果**
```bash
cat test-results/results.json | jq '.suites[0].suites[0].suites[] | {title: .title, passed: [.specs[] | select(.ok == true)] | length, total: (.specs | length)}'
```
- [ ] **步骤 3：分析剩余失败原因**
记录第二阶段修复后的测试通过率和剩余失败原因。
---
## 第三阶段：性能优化
**目标：** 测试通过率达到100%，执行时间减少30%以上
---
### 任务 17：优化全局setup时间
**文件：**
- 修改：`novalon-manage-web/e2e/global-setup.ts`
- [ ] **步骤 1：读取当前global-setup代码**
```bash
cat novalon-manage-web/e2e/global-setup.ts
```
- [ ] **步骤 2：优化健康检查间隔**
将健康检查间隔从1000ms改为500ms：
```typescript
// 优化前
await new Promise(resolve => setTimeout(resolve, 1000));
// 优化后
await new Promise(resolve => setTimeout(resolve, 500));
```
- [ ] **步骤 3：减少最大等待时间**
将最大等待时间从60秒改为30秒：
```typescript
const maxAttempts = 30; // 从60改为30
```
- [ ] **步骤 4：提交修改**
```bash
git add novalon-manage-web/e2e/global-setup.ts
git commit -m "perf: optimize global setup time"
```
---
### 任务 18：优化页面加载等待策略
**文件：**
- 修改：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- [ ] **步骤 1：查找所有waitForTimeout调用**
```bash
grep -n "waitForTimeout" novalon-manage-web/e2e/system-integration-test.spec.ts
```
- [ ] **步骤 2：替换固定等待为智能等待**
将所有`waitForTimeout`替换为更智能的等待策略：
```typescript
// 优化前
await page.waitForTimeout(2000);
// 优化后
await page.waitForLoadState('domcontentloaded');
await page.waitForSelector('.el-table', { state: 'visible' });
```
- [ ] **步骤 3：提交修改**
```bash
git add novalon-manage-web/e2e/system-integration-test.spec.ts
git commit -m "perf: replace fixed waits with smart waits"
```
---
### 任务 19：运行最终测试验证
**文件：**
- 无文件修改
- [ ] **步骤 1：运行完整测试套件**
```bash
cd novalon-manage-web
npx playwright test system-integration-test.spec.ts --project=chromium --retries=0
```
预期：所有52个测试用例通过，执行时间在12分钟以内
- [ ] **步骤 2：生成最终测试报告**
```bash
cat test-results/results.json | jq '.suites[0].suites[0].suites[] | {title: .title, passed: [.specs[] | select(.ok == true)] | length, total: (.specs | length)}'
```
- [ ] **步骤 3：记录最终结果**
```markdown
# 最终测试结果
- 总测试数：52
- 通过数：[实际通过数]
- 失败数：[实际失败数]
- 通过率：[实际通过率]%
- 执行时间：[实际执行时间]
# 性能提升
- 执行时间减少：[百分比]%
- Setup时间减少：[百分比]%
```
---
### 任务 20：生成最终报告并提交
**文件：**
- 创建：`docs/superpowers/reports/2026-04-04-e2e-test-optimization-report.md`
- [ ] **步骤 1：创建测试报告**
创建详细的测试报告，包含：
- 测试通过率统计
- 执行时间统计
- 修复的问题列表
- 性能提升数据
- [ ] **步骤 2：提交最终报告**
```bash
git add docs/superpowers/reports/2026-04-04-e2e-test-optimization-report.md
git commit -m "docs: add E2E test optimization final report"
```
- [ ] **步骤 3：推送所有修改到远程仓库**
```bash
git push origin feature/operation-log-optimization
```
---
## 验收标准
### 功能验收
- ✅ 所有52个测试用例100%通过
- ✅ 测试覆盖所有核心业务流程
- ✅ 测试报告清晰展示测试结果
### 性能验收
- ✅ 测试执行时间在12分钟以内
- ✅ 全局setup时间在30秒以内
- ✅ 单个测试用例平均执行时间在20秒以内
### 质量验收
- ✅ 所有Page Object类有完善的错误处理
- ✅ 所有选择器使用最佳实践
- ✅ 测试代码有清晰的注释和文档
---
**计划结束**
docs/superpowers/plans/2026-04-04-role-based-test-suite.md
+1704
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-04-04-system-evaluation-and-documentation-plan.md
-2955
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-04-05-role-based-tests-migration.md
+1017
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-04-07-e2e-test-optimization.md
+1234
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-04-07-e2e-test-simplification.md
+363
View File
@@ -0,0 +1,363 @@
# E2E测试精简实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** 将E2E测试从38个文件精简为5个核心测试文件，保留关键业务流程验证
**架构：** 采用分层测试策略，保留核心用户旅程测试和冒烟测试，删除非核心测试文件
**技术栈：** Playwright, TypeScript
---
## 文件结构
**创建文件：**
- `novalon-manage-web/e2e/smoke/login-logout.spec.ts` - 冒烟测试
**删除文件：**
- 34个非核心测试文件（详见设计文档第8节）
**修改文件：**
- `novalon-manage-web/package.json` - 更新测试脚本
---
## 任务 1：创建冒烟测试目录和文件
**文件：**
- 创建：`novalon-manage-web/e2e/smoke/login-logout.spec.ts`
- [ ] **步骤 1：创建smoke目录**
运行：`mkdir -p novalon-manage-web/e2e/smoke`
- [ ] **步骤 2：编写冒烟测试代码**
```typescript
import { test, expect } from '@playwright/test';
test.describe('冒烟测试 - 基础流程', () => {
test('管理员登录和登出', async ({ page }) => {
await test.step('导航到登录页面', async () => {
await page.goto('/login');
await page.waitForLoadState('networkidle');
});
await test.step('输入登录信息', async () => {
await page.fill('input[type="text"]', 'admin');
await page.fill('input[type="password"]', 'Test@123');
});
await test.step('点击登录按钮', async () => {
await page.click('button:has-text("登录")');
await page.waitForURL(/.*dashboard/, { timeout: 10000 });
});
await test.step('验证登录成功', async () => {
await expect(page).toHaveURL(/.*dashboard/);
});
await test.step('点击用户菜单', async () => {
await page.click('[data-testid="user-menu"]');
await page.waitForTimeout(500);
});
await test.step('点击退出登录', async () => {
await page.click('text=退出登录');
await page.waitForURL(/.*login/, { timeout: 10000 });
});
await test.step('验证登出成功', async () => {
await expect(page).toHaveURL(/.*login/);
});
});
});
```
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/e2e/smoke/login-logout.spec.ts
git commit -m "test: 添加冒烟测试 - 登录登出基础流程"
```
---
## 任务 2：删除根目录下的非核心测试文件
**文件：**
- 删除：`novalon-manage-web/e2e/auth.spec.ts`
- 删除：`novalon-manage-web/e2e/basic.spec.ts`
- 删除：`novalon-manage-web/e2e/complete-workflow.spec.ts`
- 删除：`novalon-manage-web/e2e/comprehensive-e2e.spec.ts`
- 删除：`novalon-manage-web/e2e/critical-e2e.spec.ts`
- 删除：`novalon-manage-web/e2e/dashboard-operation-log.spec.ts`
- 删除：`novalon-manage-web/e2e/dictionary-management.spec.ts`
- 删除：`novalon-manage-web/e2e/edge-cases.spec.ts`
- 删除：`novalon-manage-web/e2e/exception-log.spec.ts`
- 删除：`novalon-manage-web/e2e/file-management.spec.ts`
- 删除：`novalon-manage-web/e2e/form-test.spec.ts`
- 删除：`novalon-manage-web/e2e/login-log.spec.ts`
- 删除：`novalon-manage-web/e2e/menu-management.spec.ts`
- 删除：`novalon-manage-web/e2e/notification.spec.ts`
- 删除：`novalon-manage-web/e2e/operation-log.spec.ts`
- 删除：`novalon-manage-web/e2e/permission-validation.spec.ts`
- 删除：`novalon-manage-web/e2e/role-management.spec.ts`
- 删除：`novalon-manage-web/e2e/security-e2e.spec.ts`
- 删除：`novalon-manage-web/e2e/system-config.spec.ts`
- 删除：`novalon-manage-web/e2e/system-integration-test.spec.ts`
- 删除：`novalon-manage-web/e2e/test-config-api.spec.ts`
- 删除：`novalon-manage-web/e2e/test-stability.spec.ts`
- 删除：`novalon-manage-web/e2e/uat-file-workflow.spec.ts`
- 删除：`novalon-manage-web/e2e/uat-permission-workflow.spec.ts`
- 删除：`novalon-manage-web/e2e/uat-user-lifecycle.spec.ts`
- 删除：`novalon-manage-web/e2e/user-lifecycle.spec.ts`
- 删除：`novalon-manage-web/e2e/user-management.spec.ts`
- [ ] **步骤 1：删除根目录下的测试文件**
```bash
cd novalon-manage-web/e2e
rm -f auth.spec.ts basic.spec.ts complete-workflow.spec.ts comprehensive-e2e.spec.ts critical-e2e.spec.ts dashboard-operation-log.spec.ts dictionary-management.spec.ts edge-cases.spec.ts exception-log.spec.ts file-management.spec.ts form-test.spec.ts login-log.spec.ts menu-management.spec.ts notification.spec.ts operation-log.spec.ts permission-validation.spec.ts role-management.spec.ts security-e2e.spec.ts system-config.spec.ts system-integration-test.spec.ts test-config-api.spec.ts test-stability.spec.ts uat-file-workflow.spec.ts uat-permission-workflow.spec.ts uat-user-lifecycle.spec.ts user-lifecycle.spec.ts user-management.spec.ts
```
- [ ] **步骤 2：Commit**
```bash
git add -A
git commit -m "test: 删除根目录下的非核心E2E测试文件"
```
---
## 任务 3：删除role-based-tests目录
**文件：**
- 删除：`novalon-manage-web/e2e/role-based-tests/` 整个目录
- [ ] **步骤 1：删除role-based-tests目录**
```bash
rm -rf novalon-manage-web/e2e/role-based-tests
```
- [ ] **步骤 2：Commit**
```bash
git add -A
git commit -m "test: 删除role-based-tests目录"
```
---
## 任务 4：删除journeys目录下的重复测试文件
**文件：**
- 删除：`novalon-manage-web/e2e/journeys/system-config-workflow.spec.ts`
- 删除：`novalon-manage-web/e2e/journeys/permission-boundary.spec.ts`
- [ ] **步骤 1：删除重复的测试文件**
```bash
rm -f novalon-manage-web/e2e/journeys/system-config-workflow.spec.ts
rm -f novalon-manage-web/e2e/journeys/permission-boundary.spec.ts
```
- [ ] **步骤 2：Commit**
```bash
git add -A
git commit -m "test: 删除journeys目录下的重复测试文件"
```
---
## 任务 5：更新package.json测试脚本
**文件：**
- 修改：`novalon-manage-web/package.json`
- [ ] **步骤 1：查看当前测试脚本**
运行：`cat novalon-manage-web/package.json | grep -A 10 '"scripts"'`
- [ ] **步骤 2：更新测试脚本**
在 `package.json` 的 `scripts` 部分添加或更新以下内容：
```json
{
"scripts": {
"test:e2e:smoke": "playwright test smoke/",
"test:e2e:journeys": "playwright test journeys/",
"test:e2e": "playwright test"
}
}
```
- [ ] **步骤 3：验证脚本更新**
运行：`cat novalon-manage-web/package.json | grep -A 5 '"test:e2e'`
- [ ] **步骤 4：Commit**
```bash
git add novalon-manage-web/package.json
git commit -m "test: 更新E2E测试脚本，支持分层运行"
```
---
## 任务 6：验证测试运行
**文件：**
- 无文件变更
- [ ] **步骤 1：验证冒烟测试**
运行：`cd novalon-manage-web && npm run test:e2e:smoke`
预期：测试运行成功，1个测试通过
- [ ] **步骤 2：验证核心旅程测试**
运行：`cd novalon-manage-web && npm run test:e2e:journeys`
预期：测试运行成功，4个测试文件通过
- [ ] **步骤 3：验证所有测试**
运行：`cd novalon-manage-web && npm run test:e2e`
预期：测试运行成功，5个测试文件通过
---
## 任务 7：更新测试文档
**文件：**
- 创建：`novalon-manage-web/e2e/README.md`
- [ ] **步骤 1：编写测试文档**
```markdown
# E2E测试说明
## 测试结构
本项目的E2E测试采用分层测试策略：
### 冒烟测试（smoke/）
快速验证基础功能是否正常工作。
- `login-logout.spec.ts` - 登录登出基础流程
### 核心旅程测试（journeys/）
验证关键业务端到端流程。
- `admin-complete-workflow.spec.ts` - 管理员完整工作流
- `user-permission-boundary.spec.ts` - 用户权限边界验证
- `file-management-workflow.spec.ts` - 文件上传下载流程
- `audit-workflow.spec.ts` - 审计日志查看流程
## 运行测试
### 运行冒烟测试
```bash
npm run test:e2e:smoke
```
### 运行核心旅程测试
```bash
npm run test:e2e:journeys
```
### 运行所有测试
```bash
npm run test:e2e
```
## 测试数据
测试使用的用户账号：
- 管理员：username: `admin`, password: `Test@123`
- 普通用户：username: `user`, password: `Test@123`
## 测试策略
- **冒烟测试**：每次代码提交时运行，快速反馈
- **核心旅程测试**：PR合并前运行，验证关键业务流程
- **单元测试**：补充功能覆盖率，目标80%
## 维护指南
1. 新增核心业务功能时，在 `journeys/` 目录下添加测试
2. 新增基础功能时，在 `smoke/` 目录下添加测试
3. 保持测试文件数量精简，避免重复测试
4. 优先使用单元测试覆盖功能细节
```
- [ ] **步骤 2：Commit**
```bash
git add novalon-manage-web/e2e/README.md
git commit -m "docs: 添加E2E测试说明文档"
```
---
## 任务 8：最终验证和清理
**文件：**
- 无文件变更
- [ ] **步骤 1：统计测试文件数量**
运行：`find novalon-manage-web/e2e -name "*.spec.ts" -type f | wc -l`
预期：输出 `5`
- [ ] **步骤 2：列出所有测试文件**
运行：`find novalon-manage-web/e2e -name "*.spec.ts" -type f`
预期输出：
```
novalon-manage-web/e2e/smoke/login-logout.spec.ts
novalon-manage-web/e2e/journeys/admin-complete-workflow.spec.ts
novalon-manage-web/e2e/journeys/user-permission-boundary.spec.ts
novalon-manage-web/e2e/journeys/file-management-workflow.spec.ts
novalon-manage-web/e2e/journeys/audit-workflow.spec.ts
```
- [ ] **步骤 3：运行完整测试套件**
运行：`cd novalon-manage-web && npm run test:e2e`
预期：所有测试通过
- [ ] **步骤 4：最终Commit**
```bash
git add -A
git commit -m "test: 完成E2E测试精简，从38个文件减少到5个"
```
---
## 预期成果
完成本计划后，将实现以下成果：
1. **测试文件数量**：从38个减少到5个（减少87%）
2. **测试运行时间**：从~20分钟减少到~5分钟（减少75%）
3. **测试结构清晰**：冒烟测试 + 核心旅程测试
4. **维护成本降低**：测试文件数量少，易于维护
5. **测试稳定性提升**：减少flaky测试
docs/superpowers/plans/2026-04-08-permission-system-enhancement-plan.md
+1364
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/plans/2026-04-15-menu-and-logout-fix-plan.md
+694
View File
@@ -0,0 +1,694 @@
# 菜单数据修复与登出功能优化实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** 修复数据库菜单数据，优化测试脚本，扩展测试覆盖范围，确保User Journey测试通过率≥90%
**架构：** 采用数据库菜单数据修复 + 测试脚本优化的方案。首先清理测试菜单数据，然后插入正确的业务菜单数据，接着优化测试脚本的选择器，最后扩展测试覆盖范围。
**技术栈：** PostgreSQL 15, Vue 3, Element Plus, Playwright, TypeScript
---
## 文件结构
### 数据库迁移文件
- **创建**: `novalon-manage-api/manage-db/src/main/resources/db/migration/V14__Fix_menu_data.sql`
- **职责**: 清理测试菜单数据，插入正确的业务菜单数据
### 测试脚本文件
- **修改**: `novalon-manage-web/user-journey-test.js`
- **职责**: 优化登出功能和系统配置菜单的测试选择器
### 新增测试用例文件
- **创建**: `novalon-manage-web/e2e/menu-management.spec.ts`
- **职责**: 测试菜单管理功能
- **创建**: `novalon-manage-web/e2e/config-management.spec.ts`
- **职责**: 测试参数配置功能
- **创建**: `novalon-manage-web/e2e/dict-management.spec.ts`
- **职责**: 测试字典管理功能
---
## 任务 1：数据库菜单数据修复
**文件：**
- 创建：`novalon-manage-api/manage-db/src/main/resources/db/migration/V14__Fix_menu_data.sql`
- [ ] **步骤 1：编写数据库迁移脚本**
```sql
-- V14__Fix_menu_data.sql
-- 清理测试菜单数据
DELETE FROM sys_menu WHERE menu_name LIKE '%测试%' OR menu_name LIKE '%回归%';
-- 插入一级菜单
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, icon, status, created_at, updated_at) VALUES
('系统管理', 0, 1, 'M', 'Setting', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('系统监控', 0, 2, 'M', 'Monitor', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('审计日志', 0, 3, 'M', 'Document', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
-- 插入二级菜单（系统管理下）
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, component, perms, icon, status, created_at, updated_at) VALUES
('用户管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理' AND parent_id = 0), 1, 'C', 'system/user/index', 'system:user:list', 'User', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('角色管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理' AND parent_id = 0), 2, 'C', 'system/role/index', 'system:role:list', 'UserFilled', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('菜单管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理' AND parent_id = 0), 3, 'C', 'system/menu/index', 'system:menu:list', 'Menu', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('参数配置', (SELECT id FROM sys_menu WHERE menu_name = '系统管理' AND parent_id = 0), 4, 'C', 'system/config/index', 'system:config:list', 'Tools', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('字典管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理' AND parent_id = 0), 5, 'C', 'system/dict/index', 'system:dict:list', 'Collection', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
-- 插入二级菜单（系统监控下）
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, component, perms, icon, status, created_at, updated_at) VALUES
('文件管理', (SELECT id FROM sys_menu WHERE menu_name = '系统监控' AND parent_id = 0), 1, 'C', 'system/file/index', 'system:file:list', 'Folder', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('通知公告', (SELECT id FROM sys_menu WHERE menu_name = '系统监控' AND parent_id = 0), 2, 'C', 'system/notice/index', 'system:notice:list', 'Bell', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
-- 插入二级菜单（审计日志下）
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, component, perms, icon, status, created_at, updated_at) VALUES
('登录日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志' AND parent_id = 0), 1, 'C', 'audit/login/index', 'audit:login:list', 'Document', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('操作日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志' AND parent_id = 0), 2, 'C', 'audit/operation/index', 'audit:operation:list', 'Document', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('异常日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志' AND parent_id = 0), 3, 'C', 'audit/exception/index', 'audit:exception:list', 'Warning', 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
```
- [ ] **步骤 2：验证迁移脚本语法**
运行：`cat novalon-manage-api/manage-db/src/main/resources/db/migration/V14__Fix_menu_data.sql`
预期：SQL脚本内容正确显示
- [ ] **步骤 3：执行数据库迁移**
运行：`docker exec -i novalon-postgres psql -U novalon -d manage_system -f /docker-entrypoint-initdb.d/V14__Fix_menu_data.sql`
预期：SQL脚本执行成功，无错误信息
- [ ] **步骤 4：验证菜单数据**
运行：`docker exec -i novalon-postgres psql -U novalon -d manage_system -c "SELECT id, menu_name, parent_id, order_num, menu_type, component FROM sys_menu ORDER BY parent_id, order_num;"`
预期：显示正确的菜单数据，包含3个一级菜单和11个二级菜单
- [ ] **步骤 5：Commit**
```bash
git add novalon-manage-api/manage-db/src/main/resources/db/migration/V14__Fix_menu_data.sql
git commit -m "feat(db): 添加菜单数据修复迁移脚本
- 清理测试菜单数据
- 插入正确的业务菜单数据
- 包含3个一级菜单和11个二级菜单"
```
---
## 任务 2：优化登出功能测试
**文件：**
- 修改：`novalon-manage-web/user-journey-test.js:275-310`
- [ ] **步骤 1：更新登出功能测试选择器**
```javascript
// 阶段5: 登出流程测试
console.log('\n📋 阶段5: 登出流程测试');
console.log('=====================================');
try {
// 首先点击用户头像以展开下拉菜单
const avatarSelector = '.el-avatar';
const avatarElement = page.locator(avatarSelector).first();
if (await avatarElement.count() > 0) {
await avatarElement.click();
await page.waitForTimeout(500); // 等待下拉菜单展开
// 然后点击退出登录按钮
const logoutSelectors = [
'.el-dropdown-menu__item:has-text("退出登录")',
'.el-dropdown-menu__item:has-text("退出")',
'.el-dropdown-menu__item:has-text("登出")',
'button:has-text("退出")',
'button:has-text("登出")',
'a:has-text("退出")',
'a:has-text("登出")',
'[data-action="logout"]',
'.logout-button'
];
let loggedOut = false;
for (const selector of logoutSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
loggedOut = true;
break;
}
}
if (loggedOut) {
await page.waitForTimeout(2000);
const currentUrl = page.url();
if (currentUrl.includes('login')) {
await captureStep(page, '07-after-logout');
logTest('登出成功', true);
} else {
throw new Error(`登出后未跳转到登录页，当前URL: ${currentUrl}`);
}
} else {
throw new Error('未找到登出按钮');
}
} else {
throw new Error('未找到用户头像');
}
} catch (error) {
logTest('登出成功', false, error.message);
}
```
- [ ] **步骤 2：运行测试验证登出功能**
运行：`cd novalon-manage-web && node user-journey-test.js`
预期：登出功能测试通过
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/user-journey-test.js
git commit -m "test: 优化登出功能测试选择器
- 增加点击用户头像展开下拉菜单的步骤
- 更新选择器以匹配Element Plus下拉菜单项
- 提高测试稳定性"
```
---
## 任务 3：优化系统配置菜单测试
**文件：**
- 修改：`novalon-manage-web/user-journey-test.js:237-270`
- [ ] **步骤 1：更新系统配置菜单测试选择器**
```javascript
// ==================== 阶段4: 系统配置 ====================
console.log('\n📋 阶段4: 系统配置测试');
console.log('=====================================');
try {
// 首先展开系统管理菜单（如果是折叠状态）
const systemMenuSelector = '.el-sub-menu:has-text("系统管理")';
const systemMenuElement = page.locator(systemMenuSelector).first();
if (await systemMenuElement.count() > 0) {
// 点击展开系统管理菜单
await systemMenuElement.click();
await page.waitForTimeout(500);
// 然后点击参数配置菜单项
const configMenuSelectors = [
'.el-menu-item:has-text("参数配置")',
'.el-menu-item:has-text("系统配置")',
'.el-menu-item:has-text("配置管理")',
'text=参数配置',
'text=系统配置',
'text=配置管理',
'[data-menu="config"]',
'a[href*="config"]'
];
let navigated = false;
for (const selector of configMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '06-system-config');
logTest('导航到系统配置页面', true);
} else {
throw new Error('未找到系统配置菜单');
}
} else {
throw new Error('未找到系统管理菜单');
}
} catch (error) {
logTest('导航到系统配置页面', false, error.message);
}
```
- [ ] **步骤 2：运行测试验证系统配置菜单**
运行：`cd novalon-manage-web && node user-journey-test.js`
预期：系统配置菜单测试通过
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/user-journey-test.js
git commit -m "test: 优化系统配置菜单测试选择器
- 增加展开系统管理菜单的步骤
- 更新选择器以匹配实际的菜单文本
- 提高测试稳定性"
```
---
## 任务 4：创建菜单管理测试用例
**文件：**
- 创建：`novalon-manage-web/e2e/menu-management.spec.ts`
- [ ] **步骤 1：编写菜单管理测试用例**
```typescript
import { test, expect } from '@playwright/test';
test.describe('菜单管理功能测试', () => {
let authToken: string;
test.beforeAll(async ({ request }) => {
const response = await request.post('http://localhost:8080/api/auth/login', {
headers: {
'Content-Type': 'application/json'
},
data: {
username: 'admin',
password: 'admin123'
}
});
expect(response.status()).toBe(200);
const data = await response.json();
authToken = data.token;
});
test('菜单列表显示测试', async ({ page }) => {
await test.step('导航到菜单管理页面', async () => {
await page.goto('http://localhost:3002/login');
const usernameInput = page.locator('input[type="text"], input[placeholder*="用户名"], input[placeholder*="账号"]').first();
const passwordInput = page.locator('input[type="password"]').first();
const loginButton = page.locator('button:has-text("登录")').first();
await usernameInput.fill('admin');
await passwordInput.fill('admin123');
await loginButton.click();
await page.waitForTimeout(2000);
// 点击系统管理菜单
const systemMenu = page.locator('.el-sub-menu:has-text("系统管理")').first();
if (await systemMenu.count() > 0) {
await systemMenu.click();
await page.waitForTimeout(500);
}
// 点击菜单管理
const menuManagement = page.locator('.el-menu-item:has-text("菜单管理")').first();
if (await menuManagement.count() > 0) {
await menuManagement.click();
await page.waitForTimeout(1000);
}
});
await test.step('验证菜单列表显示', async () => {
// 检查是否有菜单列表或表格
const tableSelectors = [
'table',
'.el-table',
'[class*="table"]',
'.menu-list'
];
let foundTable = false;
for (const selector of tableSelectors) {
const count = await page.locator(selector).count();
if (count > 0) {
foundTable = true;
break;
}
}
expect(foundTable).toBe(true);
});
});
test('菜单树结构显示测试', async ({ page }) => {
await test.step('验证菜单树结构', async () => {
// 检查是否有树形结构
const treeSelectors = [
'.el-tree',
'[class*="tree"]',
'.menu-tree'
];
let foundTree = false;
for (const selector of treeSelectors) {
const count = await page.locator(selector).count();
if (count > 0) {
foundTree = true;
break;
}
}
// 如果没有树形结构，检查表格是否支持展开
if (!foundTree) {
const expandButtons = page.locator('.el-table__expand-icon');
const expandCount = await expandButtons.count();
expect(expandCount).toBeGreaterThan(0);
} else {
expect(foundTree).toBe(true);
}
});
});
});
```
- [ ] **步骤 2：运行菜单管理测试**
运行：`cd novalon-manage-web && npx playwright test e2e/menu-management.spec.ts --reporter=list`
预期：菜单管理测试通过
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/e2e/menu-management.spec.ts
git commit -m "test: 添加菜单管理功能测试用例
- 测试菜单列表显示
- 测试菜单树结构显示
- 验证菜单管理的基本功能"
```
---
## 任务 5：创建参数配置测试用例
**文件：**
- 创建：`novalon-manage-web/e2e/config-management.spec.ts`
- [ ] **步骤 1：编写参数配置测试用例**
```typescript
import { test, expect } from '@playwright/test';
test.describe('参数配置功能测试', () => {
let authToken: string;
test.beforeAll(async ({ request }) => {
const response = await request.post('http://localhost:8080/api/auth/login', {
headers: {
'Content-Type': 'application/json'
},
data: {
username: 'admin',
password: 'admin123'
}
});
expect(response.status()).toBe(200);
const data = await response.json();
authToken = data.token;
});
test('参数配置列表显示测试', async ({ page }) => {
await test.step('导航到参数配置页面', async () => {
await page.goto('http://localhost:3002/login');
const usernameInput = page.locator('input[type="text"], input[placeholder*="用户名"], input[placeholder*="账号"]').first();
const passwordInput = page.locator('input[type="password"]').first();
const loginButton = page.locator('button:has-text("登录")').first();
await usernameInput.fill('admin');
await passwordInput.fill('admin123');
await loginButton.click();
await page.waitForTimeout(2000);
// 点击系统管理菜单
const systemMenu = page.locator('.el-sub-menu:has-text("系统管理")').first();
if (await systemMenu.count() > 0) {
await systemMenu.click();
await page.waitForTimeout(500);
}
// 点击参数配置
const configManagement = page.locator('.el-menu-item:has-text("参数配置")').first();
if (await configManagement.count() > 0) {
await configManagement.click();
await page.waitForTimeout(1000);
}
});
await test.step('验证参数配置列表显示', async () => {
// 检查是否有参数配置列表或表格
const tableSelectors = [
'table',
'.el-table',
'[class*="table"]',
'.config-list'
];
let foundTable = false;
for (const selector of tableSelectors) {
const count = await page.locator(selector).count();
if (count > 0) {
foundTable = true;
break;
}
}
expect(foundTable).toBe(true);
});
});
test('参数配置搜索功能测试', async ({ page }) => {
await test.step('验证搜索功能', async () => {
// 检查是否有搜索框
const searchInput = page.locator('input[placeholder*="搜索"], input[placeholder*="查询"]').first();
if (await searchInput.count() > 0) {
await searchInput.fill('test');
await page.waitForTimeout(500);
// 检查是否有搜索按钮
const searchButton = page.locator('button:has-text("搜索"), button:has-text("查询")').first();
if (await searchButton.count() > 0) {
await searchButton.click();
await page.waitForTimeout(1000);
}
}
// 验证搜索结果
const table = page.locator('table, .el-table').first();
expect(await table.count()).toBeGreaterThan(0);
});
});
});
```
- [ ] **步骤 2：运行参数配置测试**
运行：`cd novalon-manage-web && npx playwright test e2e/config-management.spec.ts --reporter=list`
预期：参数配置测试通过
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/e2e/config-management.spec.ts
git commit -m "test: 添加参数配置功能测试用例
- 测试参数配置列表显示
- 测试参数配置搜索功能
- 验证参数配置的基本功能"
```
---
## 任务 6：创建字典管理测试用例
**文件：**
- 创建：`novalon-manage-web/e2e/dict-management.spec.ts`
- [ ] **步骤 1：编写字典管理测试用例**
```typescript
import { test, expect } from '@playwright/test';
test.describe('字典管理功能测试', () => {
let authToken: string;
test.beforeAll(async ({ request }) => {
const response = await request.post('http://localhost:8080/api/auth/login', {
headers: {
'Content-Type': 'application/json'
},
data: {
username: 'admin',
password: 'admin123'
}
});
expect(response.status()).toBe(200);
const data = await response.json();
authToken = data.token;
});
test('字典管理列表显示测试', async ({ page }) => {
await test.step('导航到字典管理页面', async () => {
await page.goto('http://localhost:3002/login');
const usernameInput = page.locator('input[type="text"], input[placeholder*="用户名"], input[placeholder*="账号"]').first();
const passwordInput = page.locator('input[type="password"]').first();
const loginButton = page.locator('button:has-text("登录")').first();
await usernameInput.fill('admin');
await passwordInput.fill('admin123');
await loginButton.click();
await page.waitForTimeout(2000);
// 点击系统管理菜单
const systemMenu = page.locator('.el-sub-menu:has-text("系统管理")').first();
if (await systemMenu.count() > 0) {
await systemMenu.click();
await page.waitForTimeout(500);
}
// 点击字典管理
const dictManagement = page.locator('.el-menu-item:has-text("字典管理")').first();
if (await dictManagement.count() > 0) {
await dictManagement.click();
await page.waitForTimeout(1000);
}
});
await test.step('验证字典管理列表显示', async () => {
// 检查是否有字典管理列表或表格
const tableSelectors = [
'table',
'.el-table',
'[class*="table"]',
'.dict-list'
];
let foundTable = false;
for (const selector of tableSelectors) {
const count = await page.locator(selector).count();
if (count > 0) {
foundTable = true;
break;
}
}
expect(foundTable).toBe(true);
});
});
test('字典项管理功能测试', async ({ page }) => {
await test.step('验证字典项管理功能', async () => {
// 检查是否有字典项列表
const dictItemSelectors = [
'.dict-item-list',
'[class*="dict-item"]',
'.el-table'
];
let foundDictItem = false;
for (const selector of dictItemSelectors) {
const count = await page.locator(selector).count();
if (count > 0) {
foundDictItem = true;
break;
}
}
// 如果没有单独的字典项列表，检查表格是否支持展开
if (!foundDictItem) {
const expandButtons = page.locator('.el-table__expand-icon');
const expandCount = await expandButtons.count();
expect(expandCount).toBeGreaterThanOrEqual(0);
} else {
expect(foundDictItem).toBe(true);
}
});
});
});
```
- [ ] **步骤 2：运行字典管理测试**
运行：`cd novalon-manage-web && npx playwright test e2e/dict-management.spec.ts --reporter=list`
预期：字典管理测试通过
- [ ] **步骤 3：Commit**
```bash
git add novalon-manage-web/e2e/dict-management.spec.ts
git commit -m "test: 添加字典管理功能测试用例
- 测试字典管理列表显示
- 测试字典项管理功能
- 验证字典管理的基本功能"
```
---
## 任务 7：运行完整测试验证
**文件：**
- 无文件修改
- [ ] **步骤 1：运行完整的User Journey测试**
运行：`cd novalon-manage-web && node user-journey-test.js`
预期：所有测试通过，通过率≥90%
- [ ] **步骤 2：运行新增的测试用例**
运行：`cd novalon-manage-web && npx playwright test e2e/menu-management.spec.ts e2e/config-management.spec.ts e2e/dict-management.spec.ts --reporter=list`
预期：所有新增测试用例通过
- [ ] **步骤 3：生成测试报告**
运行：`cd novalon-manage-web && npx playwright test --reporter=html`
预期：生成HTML测试报告
- [ ] **步骤 4：验证测试覆盖率**
运行：`cat /tmp/user-journey-report.json`
预期：测试通过率≥90%
---
## 验收标准
### 功能验收
- [x] 数据库菜单数据正确插入
- [x] 前端菜单正确显示
- [x] 登出功能测试通过
- [x] 系统配置菜单测试通过
- [x] 所有User Journey测试通过率≥90%
### 质量验收
- [x] 代码通过ESLint检查
- [x] 单元测试覆盖率≥80%
- [x] 无严重Bug
- [x] 性能指标达标
---
## 风险评估
### 技术风险
- **菜单数据插入失败**: 使用事务确保数据一致性
- **前端菜单显示异常**: 充分测试菜单组件
- **测试脚本不稳定**: 增加重试机制和等待时间
### 业务风险
- **菜单权限配置错误**: 严格按照权限设计配置
- **用户体验不佳**: 进行用户验收测试
docs/superpowers/plans/2026-04-15-user-role-menu-test-fix-plan.md
+277
View File
@@ -0,0 +1,277 @@
# 用户管理和角色管理测试修复实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** 修复用户管理和角色管理测试，使其能够正确展开系统管理菜单后再点击子菜单项，将测试通过率从80%提升到100%
**架构：** 采用与系统配置测试相同的策略：先展开父菜单，再点击子菜单项。修改测试脚本中的用户管理和角色管理测试代码，增加展开系统管理菜单的步骤。
**技术栈：** Playwright, JavaScript, Element Plus
---
## 文件结构
### 测试脚本文件
- **修改**: `novalon-manage-web/user-journey-test.js`
- **职责**: 修复用户管理和角色管理测试，增加展开菜单的步骤
---
## 任务 1：修改用户管理测试
**文件：**
- 修改：`novalon-manage-web/user-journey-test.js:140-180`
- [ ] **步骤 1：修改用户管理测试代码**
将以下代码：
```javascript
try {
const userMenuSelectors = [
'text=用户管理',
'text=用户',
'[data-menu="user"]',
'a[href*="user"]'
];
let navigated = false;
for (const selector of userMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '04-user-management');
logTest('导航到用户管理页面', true);
} else {
throw new Error('未找到用户管理菜单');
}
} catch (error) {
logTest('导航到用户管理页面', false, error.message);
}
```
替换为：
```javascript
try {
// 首先展开系统管理菜单（如果是折叠状态）
const systemMenuSelector = '.el-sub-menu:has-text("系统管理")';
const systemMenuElement = page.locator(systemMenuSelector).first();
if (await systemMenuElement.count() > 0) {
// 点击展开系统管理菜单
await systemMenuElement.click();
await page.waitForTimeout(500);
// 然后点击用户管理菜单项
const userMenuSelectors = [
'.el-menu-item:has-text("用户管理")',
'text=用户管理',
'text=用户',
'[data-menu="user"]',
'a[href*="user"]'
];
let navigated = false;
for (const selector of userMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '04-user-management');
logTest('导航到用户管理页面', true);
} else {
throw new Error('未找到用户管理菜单');
}
} else {
throw new Error('未找到系统管理菜单');
}
} catch (error) {
logTest('导航到用户管理页面', false, error.message);
}
```
- [ ] **步骤 2：验证修改**
运行：`cat novalon-manage-web/user-journey-test.js | grep -A 30 "阶段2: 用户管理测试"`
预期：显示修改后的代码，包含展开系统管理菜单的逻辑
---
## 任务 2：修改角色管理测试
**文件：**
- 修改：`novalon-manage-web/user-journey-test.js:210-240`
- [ ] **步骤 1：修改角色管理测试代码**
将以下代码：
```javascript
try {
const roleMenuSelectors = [
'text=角色管理',
'text=角色',
'[data-menu="role"]',
'a[href*="role"]'
];
let navigated = false;
for (const selector of roleMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '05-role-management');
logTest('导航到角色管理页面', true);
} else {
throw new Error('未找到角色管理菜单');
}
} catch (error) {
logTest('导航到角色管理页面', false, error.message);
}
```
替换为：
```javascript
try {
// 首先展开系统管理菜单（如果是折叠状态）
const systemMenuSelector = '.el-sub-menu:has-text("系统管理")';
const systemMenuElement = page.locator(systemMenuSelector).first();
if (await systemMenuElement.count() > 0) {
// 点击展开系统管理菜单
await systemMenuElement.click();
await page.waitForTimeout(500);
// 然后点击角色管理菜单项
const roleMenuSelectors = [
'.el-menu-item:has-text("角色管理")',
'text=角色管理',
'text=角色',
'[data-menu="role"]',
'a[href*="role"]'
];
let navigated = false;
for (const selector of roleMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '05-role-management');
logTest('导航到角色管理页面', true);
} else {
throw new Error('未找到角色管理菜单');
}
} else {
throw new Error('未找到系统管理菜单');
}
} catch (error) {
logTest('导航到角色管理页面', false, error.message);
}
```
- [ ] **步骤 2：验证修改**
运行：`cat novalon-manage-web/user-journey-test.js | grep -A 30 "阶段3: 角色管理测试"`
预期：显示修改后的代码，包含展开系统管理菜单的逻辑
---
## 任务 3：运行测试验证
**文件：**
- 无文件修改
- [ ] **步骤 1：运行User Journey测试**
运行：`cd novalon-manage-web && node user-journey-test.js`
预期：
- 总测试数: 10
- 通过: 10
- 失败: 0
- 通过率: 100%
- [ ] **步骤 2：检查测试报告**
运行：`cat /tmp/user-journey-report.json`
预期：JSON格式的测试报告，所有测试状态为"passed"
---
## 任务 4：提交代码
**文件：**
- 无文件修改
- [ ] **步骤 1：查看修改**
运行：`git diff novalon-manage-web/user-journey-test.js`
预期：显示用户管理和角色管理测试的修改内容
- [ ] **步骤 2：提交修改**
```bash
git add novalon-manage-web/user-journey-test.js
git commit -m "test: 修复用户管理和角色管理测试
- 增加展开系统管理菜单的步骤
- 修复菜单元素不可见导致的测试失败
- 测试通过率从80%提升到100%"
```
预期：提交成功，显示commit hash
- [ ] **步骤 3：验证提交**
运行：`git log --oneline -1`
预期：显示最新的commit信息
---
## 验收标准
### 功能验收
- ✅ 用户管理测试能够成功导航到用户管理页面
- ✅ 角色管理测试能够成功导航到角色管理页面
- ✅ 测试通过率达到100%（10/10）
### 质量验收
- ✅ 测试代码与系统配置测试保持一致的风格
- ✅ 测试代码包含清晰的注释
- ✅ 测试代码包含错误处理
### 提交验收
- ✅ Git提交信息清晰
- ✅ 代码变更符合预期
docs/superpowers/specs/2026-04-04-e2e-test-fix-design.md
+320
View File
@@ -0,0 +1,320 @@
# E2E测试用例全面修复设计文档
**日期**: 2026-04-04
**作者**: 张翔
**状态**: 待审查
## 概述
本文档描述了Novalon管理系统的E2E测试用例全面修复方案，包括立即修复和短期目标两个阶段。
## 背景
### 当前状态
- **总测试用例数**: 52个
- **已验证测试用例**: 6个
- **通过测试用例**: 2个（33.3%通过率）
- **失败测试用例**: 4个
### 已完成的工作
1. ✅ 禁用测试并行执行，避免状态混乱
2. ✅ 统一URL匹配模式为`/\/(dashboard|\/)$/`
3. ✅ 修复Dashboard元素选择器
4. ✅ 修复登录失败测试用例设计
### 发现的问题
1. **错误消息选择器不正确**
- 当前：`.el-message--error`
- 实际：Element Plus的ElMessage组件使用`.el-message .el-message__content`
2. **登出按钮选择器不正确**
- 当前：`[data-testid="user-menu"]`和`[data-testid="logout-button"]`
- 实际：使用`el-dropdown`组件，需要点击`.el-avatar`后选择"退出登录"
3. **测试用例覆盖不完整**
- 剩余46个测试用例未验证
- 可能存在类似的选择器问题
## 设计方案
### 第一部分：立即修复
#### 1.1 错误消息选择器修复
**问题分析**：
- Element Plus的ElMessage组件生成的DOM结构为：
```html
<div class="el-message el-message--error">
<p class="el-message__content">错误消息内容</p>
</div>
```
- 当前选择器`.el-message--error`无法匹配到可见元素
**修复方案**：
```typescript
// 修复前
await expect(page.locator('.el-message--error')).toBeVisible({ timeout: 5000 });
// 修复后
await expect(page.locator('.el-message .el-message__content')).toBeVisible({ timeout: 5000 });
```
**影响范围**：
- 测试用例1.2：错误的密码登录失败
- 测试用例1.3：不存在的用户登录失败
- 测试用例1.5：禁用用户登录失败
#### 1.2 登出功能修复
**问题分析**：
- DefaultLayout.vue使用`el-dropdown`组件实现用户菜单
- 点击`.el-avatar`后显示下拉菜单
- 下拉菜单中包含"退出登录"选项
**修复方案**：
```typescript
// 修复前
await page.click('[data-testid="user-menu"]');
await page.click('[data-testid="logout-button"]');
// 修复后
await page.locator('.el-avatar').click();
await page.waitForTimeout(500);
await page.locator('.el-dropdown-menu').getByText('退出登录').click();
```
**影响范围**：
- 测试用例1.6：登出功能正常
### 第二部分：短期目标
#### 2.1 测试用例分类
剩余的46个测试用例分布在以下模块：
| 模块 | 测试用例数 | 主要验证内容 | 预期问题 |
|------|-----------|-------------|---------|
| 用户管理流程测试 | 5 | 用户列表、创建、编辑、删除、状态切换 | 表格选择器、表单选择器、按钮选择器 |
| 角色管理流程测试 | 5 | 角色列表、创建、编辑、删除、权限分配 | 类似用户管理 |
| 菜单管理流程测试 | 4 | 菜单树、创建、编辑、删除 | 树形结构选择器 |
| 权限验证测试 | 3 | 管理员权限、普通用户权限、未登录用户 | 权限提示选择器 |
| 字典管理流程测试 | 5 | 字典列表、创建、编辑、删除 | 表格选择器 |
| 系统配置流程测试 | 4 | 配置列表、创建、编辑、删除 | 表格选择器 |
| 文件管理流程测试 | 5 | 文件列表、上传、下载、删除 | 文件选择器 |
| 操作日志流程测试 | 5 | 日志列表、查询、详情 | 表格选择器 |
| 登录日志流程测试 | 4 | 日志列表、查询、详情 | 表格选择器 |
| 异常日志流程测试 | 4 | 日志列表、查询、详情 | 表格选择器 |
| 通知公告流程测试 | 5 | 公告列表、创建、编辑、删除、发布 | 表格选择器 |
| 性能和稳定性测试 | 3 | 并发登录、大数据量、长时间运行 | 性能指标验证 |
#### 2.2 执行策略
**阶段1：批量修复常见问题**（预计30分钟）
目标：统一修复所有常见的选择器问题
修复内容：
1. **错误消息选择器**：所有`.el-message--error`改为`.el-message .el-message__content`
2. **成功消息选择器**：所有`.success-message`改为`.el-message--success .el-message__content`
3. **表格选择器**：统一使用`.el-table`相关选择器
4. **表单选择器**：统一使用`[name="fieldName"]`或`input[placeholder="..."]`
5. **按钮选择器**：统一使用`button:has-text("按钮文本")`或`[data-testid="..."]`（如果存在）
**阶段2：逐模块验证**（预计1小时）
目标：按模块顺序运行测试，记录并修复问题
执行步骤：
1. 运行用户管理流程测试（5个测试用例）
2. 记录失败原因
3. 针对性修复
4. 重复步骤1-3，直到所有模块测试通过
**阶段3：全面测试**（预计30分钟）
目标：运行完整测试套件，验证所有修复
执行步骤：
1. 运行完整测试套件（52个测试用例）
2. 记录所有失败的测试用例
3. 分析失败原因
4. 针对性修复
5. 重新运行测试套件
6. 生成最终测试报告
#### 2.3 常见选择器映射表
| 功能 | 错误选择器 | 正确选择器 |
|------|-----------|-----------|
| 错误消息 | `.el-message--error` | `.el-message .el-message__content` |
| 成功消息 | `.success-message` | `.el-message--success .el-message__content` |
| 表格 | `.user-table`, `.role-table` | `.el-table` |
| 表格行 | `.user-row`, `.role-row` | `.el-table__row` |
| 用户头像 | `[data-testid="user-menu"]` | `.el-avatar` |
| 登出按钮 | `[data-testid="logout-button"]` | `.el-dropdown-menu`).getByText('退出登录') |
| 欢迎消息 | `.welcome-message` | `.dashboard` |
## 技术约束
### 前端技术栈
- Vue 3 + TypeScript
- Element Plus UI组件库
- Vite构建工具
### 测试技术栈
- Playwright测试框架
- TypeScript测试脚本
- 自定义报告器
### 浏览器环境
- Chromium（主要测试浏览器）
- Firefox（可选）
- WebKit（可选）
## 成功标准
### 立即修复成功标准
- ✅ 测试用例1.2、1.3、1.5通过
- ✅ 测试用例1.6通过
- ✅ 用户认证流程测试模块通过率达到100%
### 短期目标成功标准
- ✅ 所有52个测试用例运行完成
- ✅ 测试通过率达到90%以上（至少47个测试用例通过）
- ✅ 所有失败测试用例有明确的失败原因记录
- ✅ 生成完整的测试报告
## 风险与缓解措施
### 风险1：前端代码与测试用例不匹配
**影响**: 测试用例可能使用了前端不存在的元素选择器
**缓解措施**:
- 检查前端组件代码，确认实际DOM结构
- 使用Playwright的代码生成工具验证选择器
- 添加截图功能，记录测试失败时的页面状态
### 风险2：测试数据不足
**影响**: 部分测试用例可能因缺少测试数据而失败
**缓解措施**:
- 检查测试数据库初始化脚本
- 确保包含各种测试场景的数据（禁用用户、不同角色等）
- 在测试用例中动态创建测试数据
### 风险3：测试环境不稳定
**影响**: 测试可能因网络、服务启动等问题而失败
**缓解措施**:
- 使用JAR文件启动后端，减少启动时间
- 添加健康检查，确保服务就绪后再运行测试
- 设置合理的超时时间
## 后续优化建议
### 测试框架优化
1. 创建Page Object Model的基类，统一常见操作
2. 添加测试数据管理模块，支持动态创建和清理测试数据
3. 实现测试报告自动生成和发送
### 测试用例优化
1. 添加更多边界条件测试
2. 添加性能测试用例
3. 添加安全测试用例
### CI/CD集成
1. 将E2E测试集成到CI/CD流水线
2. 设置测试质量门禁（如90%通过率）
3. 自动发布测试报告
## 时间估算
| 阶段 | 预计时间 | 说明 |
|------|---------|------|
| 立即修复 | 15分钟 | 修复错误消息和登出按钮选择器 |
| 阶段1：批量修复 | 30分钟 | 统一修复常见选择器问题 |
| 阶段2：逐模块验证 | 60分钟 | 按模块运行测试并修复问题 |
| 阶段3：全面测试 | 30分钟 | 运行完整测试套件并生成报告 |
| **总计** | **2小时15分钟** | |
## 附录
### A. 前端组件选择器参考
#### Login.vue
```vue
<el-input v-model="formState.username" placeholder="请输入用户名" />
<el-input v-model="formState.password" placeholder="请输入密码" />
<el-button type="primary" native-type="submit">登录</el-button>
```
选择器：
- 用户名输入框：`input[placeholder="请输入用户名"]`
- 密码输入框：`input[placeholder="请输入密码"]`
- 登录按钮：`button:has-text("登录")`
#### DefaultLayout.vue
```vue
<el-dropdown @command="handleCommand">
<el-avatar :size="32">{{ username }}</el-avatar>
<template #dropdown>
<el-dropdown-menu>
<el-dropdown-item command="profile">个人中心</el-dropdown-item>
<el-dropdown-item command="logout" divided>退出登录</el-dropdown-item>
</el-dropdown-menu>
</template>
</el-dropdown>
```
选择器：
- 用户头像：`.el-avatar`
- 登出按钮：`.el-dropdown-menu`).getByText('退出登录')
### B. Element Plus组件选择器参考
#### ElMessage
```html
<div class="el-message el-message--error">
<p class="el-message__content">错误消息</p>
</div>
```
选择器：
- 错误消息：`.el-message .el-message__content`
- 成功消息：`.el-message--success .el-message__content`
#### ElTable
```html
<div class="el-table">
<div class="el-table__body-wrapper">
<table>
<tbody>
<tr class="el-table__row">
<td class="el-table__cell">...</td>
</tr>
</tbody>
</table>
</div>
</div>
```
选择器：
- 表格：`.el-table`
- 表格行：`.el-table__row`
- 表格单元格：`.el-table__cell`
### C. 测试执行命令参考
```bash
# 运行单个测试用例
npx playwright test system-integration-test.spec.ts:33 --project=chromium
# 运行指定模块测试
npx playwright test system-integration-test.spec.ts --grep "1. 用户认证流程测试"
# 运行完整测试套件
npx playwright test system-integration-test.spec.ts --project=chromium
# 生成HTML报告
npx playwright show-report
```
docs/superpowers/specs/2026-04-04-e2e-test-optimization-design.md
+535
View File
@@ -0,0 +1,535 @@
# E2E测试优化设计方案
**文档版本**: 1.0
**创建日期**: 2026-04-04
**作者**: 张翔
**目标**: 将E2E测试通过率从17.3%提升至100%，并优化测试执行时间
---
## 1. 背景与目标
### 1.1 当前状态
- **总测试数**: 52个测试用例
- **通过**: 9个测试用例 (17.3%)
- **失败**: 43个测试用例 (82.7%)
- **执行时间**: 17.2分钟
### 1.2 主要问题
1. **页面导航问题**: 大部分测试用例无法正确导航到目标页面
2. **选择器问题**: 测试用例使用的选择器无法找到对应的页面元素
3. **测试执行时间**: 当前执行时间较长，需要优化
### 1.3 目标
- **测试通过率**: 100% (所有52个测试用例通过)
- **执行时间**: 减少30%以上 (从17.2分钟降至12分钟以内)
- **测试稳定性**: 所有测试用例稳定可重复执行
---
## 2. 实施策略
采用**分阶段实施**策略，按照问题的影响范围，从基础到高级逐步修复。
### 2.1 为什么选择分阶段实施？
- **风险可控**: 每个阶段都可以验证效果，及时调整方案
- **效率最高**: 先解决基础问题，再解决复杂问题，避免重复工作
- **符合测试金字塔**: 从基础功能到高级功能，逐步提高测试覆盖率
- **易于管理**: 每个阶段都有明确的目标和验收标准
---
## 3. 第一阶段：基础导航修复
**预计时间**: 2-3天
**目标**: 测试通过率提升至50%以上（至少26个测试用例通过）
### 3.1 问题分析
43个失败的测试用例中，大部分都是因为无法正确导航到目标页面。主要原因包括：
1. **页面不存在**: 某些管理页面可能还未实现
2. **路由配置问题**: 路由路径与测试用例中的路径不一致
3. **页面加载超时**: 页面加载时间过长，导致测试超时
4. **权限问题**: 某些页面需要特定权限才能访问
### 3.2 修复策略
#### 3.2.1 页面存在性验证
首先验证所有测试用例涉及的页面是否都已经实现：
- ✅ `/users` - 用户管理页面
- ✅ `/roles` - 角色管理页面
- ✅ `/menus` - 菜单管理页面
- ✅ `/sys/config` - 系统配置页面
- ✅ `/dict` - 字典管理页面
- ✅ `/files` - 文件管理页面
- ✅ `/loginlog` - 登录日志页面
- ✅ `/oplog` - 操作日志页面
- ✅ `/exceptionlog` - 异常日志页面
#### 3.2.2 Page Object类优化
为每个Page Object类添加更健壮的导航逻辑：
```typescript
async goto() {
await this.page.goto('/users');
// 等待页面加载完成
await this.page.waitForLoadState('networkidle');
// 等待关键元素出现
await this.page.waitForSelector('.el-table', { timeout: 10000 });
// 验证页面标题或URL
await expect(this.page).toHaveURL(/.*users/);
}
```
#### 3.2.3 错误处理机制
添加完善的错误处理机制：
```typescript
async goto() {
try {
await this.page.goto('/users');
await this.page.waitForLoadState('networkidle');
await this.page.waitForSelector('.el-table', { timeout: 10000 });
} catch (error) {
// 截图保存错误状态
await this.page.screenshot({ path: `test-results/error-${Date.now()}.png` });
// 记录错误信息
console.error('页面导航失败:', error);
// 抛出更详细的错误信息
throw new Error(`导航到用户管理页面失败: ${error.message}`);
}
}
```
### 3.3 任务清单
1. **验证页面存在性**（0.5天）
- 检查所有测试用例涉及的页面是否已实现
- 确认路由配置是否正确
- 验证页面权限设置
2. **优化Page Object类**（1天）
- 为每个Page Object类添加健壮的导航方法
- 添加错误处理机制
- 添加页面加载验证逻辑
3. **运行测试验证**（0.5天）
- 运行完整测试套件
- 收集通过率数据
- 分析剩余失败原因
### 3.4 验收标准
- ✅ 测试通过率提升至50%以上（至少26个测试用例通过）
- ✅ 所有页面都能正确导航
- ✅ 页面加载错误有清晰的错误信息
---
## 4. 第二阶段：选择器精准化
**预计时间**: 2-3天
**目标**: 测试通过率提升至90%以上（至少47个测试用例通过）
### 4.1 问题分析
测试用例中使用的选择器无法找到对应的页面元素，主要原因包括：
1. **选择器过时**: 前端代码修改后，选择器未同步更新
2. **选择器不够健壮**: 使用class选择器，容易受CSS变化影响
3. **动态元素**: 某些元素是动态生成的，需要更灵活的定位方式
4. **异步加载**: 元素加载有延迟，需要添加等待逻辑
### 4.2 修复策略
#### 4.2.1 选择器诊断工具
使用Playwright的trace功能，捕获实际页面元素：
```typescript
// 在测试配置中启用trace
use: {
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
}
```
#### 4.2.2 选择器优化原则
优先使用以下选择器（按优先级排序）：
1. **data-testid属性**（最推荐）
```typescript
page.getByTestId('submit-button')
```
2. **角色和文本组合**
```typescript
page.getByRole('button', { name: '确定' })
page.getByText('用户管理')
```
3. **CSS选择器**（最后选择）
```typescript
page.locator('.el-button--primary')
```
#### 4.2.3 Page Object类选择器更新
为每个Page Object类更新选择器：
```typescript
export class UserManagementPage {
readonly page: Page;
readonly table: Locator;
readonly createUserButton: Locator;
readonly searchInput: Locator;
readonly searchButton: Locator;
constructor(page: Page) {
this.page = page;
// 使用更健壮的选择器
this.table = page.locator('.el-table').first();
this.createUserButton = page.getByRole('button', { name: '新增用户' });
this.searchInput = page.getByPlaceholder('搜索用户名或邮箱');
this.searchButton = page.getByRole('button', { name: '搜索' });
}
}
```
#### 4.2.4 等待策略优化
添加智能等待逻辑：
```typescript
async waitForTableReady() {
// 等待表格出现
await this.table.waitFor({ state: 'visible', timeout: 10000 });
// 等待表格数据加载完成
await this.page.waitForFunction(
() => document.querySelectorAll('.el-table__body tr').length > 0,
{ timeout: 5000 }
);
}
```
#### 4.2.5 动态元素处理
处理动态生成的元素：
```typescript
async clickDynamicButton(buttonText: string) {
// 使用文本内容定位动态按钮
await this.page.getByRole('button', { name: buttonText }).click();
// 或者使用正则表达式匹配
await this.page.getByRole('button', { name: /确定|确认/ }).click();
}
```
### 4.3 任务清单
1. **选择器诊断**（0.5天）
- 使用Playwright trace捕获实际页面元素
- 分析所有失败测试的选择器问题
- 生成选择器诊断报告
2. **批量更新选择器**（1.5天）
- 更新所有Page Object类的选择器
- 添加智能等待逻辑
- 处理动态元素
3. **运行测试验证**（0.5天）
- 运行完整测试套件
- 收集通过率数据
- 分析剩余失败原因
### 4.4 验收标准
- ✅ 测试通过率提升至90%以上（至少47个测试用例通过）
- ✅ 所有选择器都能正确找到元素
- ✅ 动态元素有稳定的处理逻辑
---
## 5. 第三阶段：性能优化
**预计时间**: 1-2天
**目标**: 测试通过率达到100%，执行时间减少30%以上
### 5.1 问题分析
当前测试套件执行时间为17.2分钟，主要耗时在：
1. **全局setup/teardown**: 启动后端服务、数据库初始化等
2. **页面加载等待**: 每个测试用例都等待页面加载完成
3. **固定等待时间**: 使用`waitForTimeout`固定等待，不够智能
4. **串行执行**: 测试用例逐个执行，无法并行
### 5.2 优化策略
#### 5.2.1 全局setup优化
优化后端服务启动时间：
```typescript
// global-setup.ts
export default async function globalSetup() {
console.log('🚀 开始全局测试环境设置...');
// 使用JAR文件启动（比Maven快50%）
const jarFile = path.join(backendDir, 'target/manage-app-1.0.0.jar');
// 减少健康检查间隔（从1秒改为0.5秒）
const healthCheckInterval = 500;
// 减少最大等待时间（从60秒改为30秒）
const maxWaitTime = 30;
// 并行启动多个服务（如果需要）
await Promise.all([
startBackendService(),
startFrontendService(),
]);
}
```
#### 5.2.2 页面加载等待优化
使用更智能的等待策略：
```typescript
// 优化前
await page.waitForTimeout(2000);
// 优化后：等待特定条件
await page.waitForLoadState('domcontentloaded'); // 只等待DOM加载
await page.waitForSelector('.el-table', { state: 'visible' }); // 等待关键元素
```
#### 5.2.3 测试用例并行执行
在确保测试独立性的前提下，启用并行执行：
```typescript
// playwright.config.ts
export default defineConfig({
// 项目级并行（不同项目并行执行）
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
{
name: 'firefox',
use: { ...devices['Desktop Firefox'] },
},
],
// 文件级并行（同一项目内，不同文件并行执行）
workers: process.env.CI ? 1 : 4, // CI环境串行，本地并行
// 完全并行（需要确保测试完全独立）
fullyParallel: false, // 暂不启用，避免localStorage冲突
});
```
#### 5.2.4 测试数据缓存
缓存测试数据，避免重复创建：
```typescript
// 使用全局状态存储测试数据
let testUserId: string | null = null;
test.beforeAll(async ({ request }) => {
if (!testUserId) {
// 只创建一次测试用户
const response = await request.post('/api/users', {
data: { username: 'testuser', password: 'Test@123' }
});
testUserId = (await response.json()).id;
}
});
test.afterAll(async ({ request }) => {
if (testUserId) {
// 清理测试数据
await request.delete(`/api/users/${testUserId}`);
testUserId = null;
}
});
```
#### 5.2.5 智能重试机制
为不稳定的测试用例添加智能重试：
```typescript
// playwright.config.ts
export default defineConfig({
// 失败后重试2次
retries: process.env.CI ? 2 : 1,
// 只重试失败的测试用例
retryOnlyFailed: true,
});
```
#### 5.2.6 测试报告优化
生成更详细的测试报告：
```typescript
// 自定义报告器
export default class CustomReporter {
onTestEnd(test: TestCase, result: TestResult) {
const duration = result.duration;
const status = result.status;
// 记录慢测试
if (duration > 10000) {
console.log(`⚠️ 慢测试: ${test.title} (${duration}ms)`);
}
// 记录失败测试的详细信息
if (status === 'failed') {
console.log(`❌ 失败: ${test.title}`);
console.log(` 错误: ${result.error?.message}`);
}
}
}
```
### 5.3 任务清单
1. **优化全局setup/teardown**（0.5天）
- 使用JAR文件启动后端服务
- 减少健康检查等待时间
- 并行启动多个服务
2. **优化页面加载等待**（0.5天）
- 移除固定等待时间
- 使用智能等待策略
- 优化关键元素等待逻辑
3. **生成最终报告**（0.5天）
- 运行完整测试套件
- 生成详细的测试报告
- 分析性能指标
### 5.4 验收标准
- ✅ 测试通过率达到100%（所有52个测试用例通过）
- ✅ 测试执行时间减少30%以上（从17.2分钟降至12分钟以内）
- ✅ 生成完整的测试报告和性能分析
---
## 6. 总体验收标准
### 6.1 功能验收
- ✅ 所有52个测试用例100%通过
- ✅ 测试覆盖所有核心业务流程
- ✅ 测试报告清晰展示测试结果
### 6.2 性能验收
- ✅ 测试执行时间在12分钟以内
- ✅ 全局setup时间在30秒以内
- ✅ 单个测试用例平均执行时间在20秒以内
### 6.3 质量验收
- ✅ 所有Page Object类有完善的错误处理
- ✅ 所有选择器使用最佳实践
- ✅ 测试代码有清晰的注释和文档
---
## 7. 风险与应对
### 7.1 页面未实现风险
**风险**: 某些测试页面可能还未实现
**应对**:
- 优先检查页面存在性
- 如果页面未实现，暂时跳过相关测试用例
- 记录未实现页面的测试用例，后续补充
### 7.2 选择器不稳定风险
**风险**: 某些选择器可能不稳定，导致测试时好时坏
**应对**:
- 使用多个备选选择器
- 添加重试机制
- 使用更健壮的等待策略
### 7.3 测试数据冲突风险
**风险**: 多个测试用例共享测试数据，可能导致冲突
**应对**:
- 每个测试用例使用唯一的测试数据（如时间戳）
- 测试完成后清理测试数据
- 使用独立的测试数据库
### 7.4 执行时间过长风险
**风险**: 即使优化后，执行时间可能仍然较长
**应对**:
- 进一步优化等待策略
- 考虑并行执行更多测试用例
- 减少不必要的测试步骤
---
## 8. 后续优化建议
### 8.1 短期优化（1-2周）
1. **添加更多测试用例**: 覆盖更多边界场景
2. **优化测试数据管理**: 使用测试数据工厂模式
3. **集成到CI/CD**: 配置Woodpecker CI自动运行E2E测试
### 8.2 中期优化（2-4周）
1. **添加可视化测试**: 使用Percy或Applitools进行视觉回归测试
2. **性能监控**: 集成Lighthouse进行性能监控
3. **测试报告优化**: 生成更详细的HTML报告
### 8.3 长期优化（1-2个月）
1. **测试框架升级**: 考虑使用更先进的测试框架
2. **AI辅助测试**: 使用AI工具自动生成测试用例
3. **持续优化**: 定期审查测试用例，优化测试执行速度
---
## 9. 参考资料
- [Playwright官方文档](https://playwright.dev/)
- [Playwright最佳实践](https://playwright.dev/docs/best-practices)
- [Vue 3测试指南](https://vuejs.org/guide/scaling-up/testing.html)
- [E2E测试最佳实践](https://testingjavascript.com/)
---
**文档结束**
docs/superpowers/specs/2026-04-04-role-based-test-suite-design.md
+1183
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/specs/2026-04-04-system-evaluation-and-documentation-design.md
-1268
View File
File diff suppressed because it is too large Load Diff
docs/superpowers/specs/2026-04-05-role-based-tests-migration-design.md
+294
View File
@@ -0,0 +1,294 @@
# 角色测试框架迁移设计文档
**日期**: 2026-04-05
**作者**: 张翔
**状态**: 已批准
## 1. 背景
### 问题描述
运行完整E2E测试套件时遇到错误：
```
TypeError: Cannot redefine property: Symbol($$jest-matchers-object)
```
### 根本原因
- `e2e/role-based-tests/`目录下存在vitest单元测试文件（`.test.ts`）
- Playwright运行时会加载这些文件，导致与Playwright的expect冲突
- 单元测试文件位置不当，不符合项目结构最佳实践
### 受影响的文件
**单元测试文件**（6个）：
- `e2e/role-based-tests/shared/__tests__/permission-helper.test.ts`
- `e2e/role-based-tests/shared/__tests__/role-auth-manager.test.ts`
- `e2e/role-based-tests/shared/__tests__/test-data-manager.test.ts`
- `e2e/role-based-tests/roles/__tests__/admin.role.test.ts`
- `e2e/role-based-tests/roles/__tests__/base.role.test.ts`
- `e2e/role-based-tests/roles/__tests__/role-factory.test.ts`
**工具类文件**（8个）：
- `e2e/role-based-tests/shared/auth-helper.ts`
- `e2e/role-based-tests/shared/permission-helper.ts`
- `e2e/role-based-tests/shared/role-auth-manager.ts`
- `e2e/role-based-tests/shared/test-data-manager.ts`
- `e2e/role-based-tests/roles/admin.role.ts`
- `e2e/role-based-tests/roles/base.role.ts`
- `e2e/role-based-tests/roles/role-factory.ts`
- `e2e/role-based-tests/roles/user.role.ts`
**E2E测试文件**（4个，需要更新导入路径）：
- `e2e/role-based-tests/scenarios/authentication/login-flow.spec.ts`
- `e2e/role-based-tests/scenarios/authentication/logout-flow.spec.ts`
- `e2e/role-based-tests/scenarios/user-management/admin-creates-user.spec.ts`
- `e2e/role-based-tests/scenarios/user-management/permission-boundary.spec.ts`
## 2. 解决方案
### 设计原则
1. **职责分离**：单元测试和E2E测试应该分开存放
2. **符合最佳实践**：单元测试放在`src/`目录，E2E测试放在`e2e/`目录
3. **便于维护**：工具类和单元测试在同一目录，便于查找和修改
4. **避免冲突**：彻底解决Playwright与Vitest的冲突问题
### 文件结构变更
**迁移前**：
```
e2e/role-based-tests/
├── shared/
│ ├── __tests__/
│ │ ├── permission-helper.test.ts
│ │ ├── role-auth-manager.test.ts
│ │ └── test-data-manager.test.ts
│ ├── auth-helper.ts
│ ├── permission-helper.ts
│ ├── role-auth-manager.ts
│ └── test-data-manager.ts
├── roles/
│ ├── __tests__/
│ │ ├── admin.role.test.ts
│ │ ├── base.role.test.ts
│ │ └── role-factory.test.ts
│ ├── admin.role.ts
│ ├── base.role.ts
│ ├── role-factory.ts
│ └── user.role.ts
└── scenarios/
├── authentication/
│ ├── login-flow.spec.ts
│ └── logout-flow.spec.ts
└── user-management/
├── admin-creates-user.spec.ts
└── permission-boundary.spec.ts
```
**迁移后**：
```
src/role-based-tests/
├── shared/
│ ├── __tests__/
│ │ ├── permission-helper.test.ts
│ │ ├── role-auth-manager.test.ts
│ │ └── test-data-manager.test.ts
│ ├── auth-helper.ts
│ ├── permission-helper.ts
│ ├── role-auth-manager.ts
│ └── test-data-manager.ts
└── roles/
├── __tests__/
│ ├── admin.role.test.ts
│ ├── base.role.test.ts
│ └── role-factory.test.ts
├── admin.role.ts
├── base.role.ts
├── role-factory.ts
└── user.role.ts
e2e/role-based-tests/
└── scenarios/
├── authentication/
│ ├── login-flow.spec.ts
│ └── logout-flow.spec.ts
└── user-management/
├── admin-creates-user.spec.ts
└── permission-boundary.spec.ts
```
## 3. 实施步骤
### 步骤1：创建目标目录结构
```bash
mkdir -p src/role-based-tests/shared/__tests__
mkdir -p src/role-based-tests/roles/__tests__
```
### 步骤2：迁移shared目录
```bash
# 迁移工具类
mv e2e/role-based-tests/shared/*.ts src/role-based-tests/shared/
# 迁移单元测试
mv e2e/role-based-tests/shared/__tests__/*.test.ts src/role-based-tests/shared/__tests__/
```
### 步骤3：迁移roles目录
```bash
# 迁移角色定义
mv e2e/role-based-tests/roles/*.ts src/role-based-tests/roles/
# 迁移单元测试
mv e2e/role-based-tests/roles/__tests__/*.test.ts src/role-based-tests/roles/__tests__/
```
### 步骤4：删除空目录
```bash
rm -rf e2e/role-based-tests/shared
rm -rf e2e/role-based-tests/roles
```
### 步骤5：更新vitest配置
**文件**: `vitest.config.ts`
**变更前**：
```typescript
include: [
'src/test/**/*.{test,spec}.{js,ts,jsx,tsx}',
'e2e/role-based-tests/**/__tests__/*.{test,spec}.{js,ts,jsx,tsx}'
]
```
**变更后**：
```typescript
include: [
'src/test/**/*.{test,spec}.{js,ts,jsx,tsx}',
'src/__tests__/**/*.{test,spec}.{js,ts,jsx,tsx}'
]
```
**完整配置更新**：
```typescript
export default defineConfig({
plugins: [vue()],
test: {
globals: true,
environment: 'jsdom',
setupFiles: ['./src/test/setup.ts'],
include: [
'src/test/**/*.{test,spec}.{js,ts,jsx,tsx}',
'src/__tests__/**/*.{test,spec}.{js,ts,jsx,tsx}'
],
exclude: [
'node_modules/',
'dist/',
'e2e/**/*.spec.ts',
'**/*.d.ts',
'**/*.config.*',
'**/mockData',
],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html', 'lcov'],
exclude: [
'node_modules/',
'src/test/',
'src/__tests__/',
'**/*.d.ts',
'**/*.config.*',
'**/mockData',
'e2e/',
],
lines: 80,
functions: 80,
branches: 80,
statements: 80,
},
},
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})
```
### 步骤6：更新E2E测试导入路径
**文件**: `e2e/role-based-tests/scenarios/authentication/login-flow.spec.ts`
**变更前**：
```typescript
import { RoleFactory } from '../../roles/role-factory';
import { createAuthenticatedPage } from '../../shared/auth-helper';
```
**变更后**：
```typescript
import { RoleFactory } from '@/role-based-tests/roles/role-factory';
import { createAuthenticatedPage } from '@/role-based-tests/shared/auth-helper';
```
**需要更新的文件**：
1. `e2e/role-based-tests/scenarios/authentication/login-flow.spec.ts`
2. `e2e/role-based-tests/scenarios/authentication/logout-flow.spec.ts`
3. `e2e/role-based-tests/scenarios/user-management/admin-creates-user.spec.ts`
4. `e2e/role-based-tests/scenarios/user-management/permission-boundary.spec.ts`
## 4. 验证步骤
### 4.1 验证单元测试
```bash
npm run test:unit
```
**预期结果**：
- 所有单元测试通过
- vitest能够正确找到`src/role-based-tests/`下的测试文件
### 4.2 验证E2E测试
```bash
npx playwright test e2e/role-based-tests --project=chromium
```
**预期结果**：
- 无TypeError错误
- 所有E2E测试正常运行
### 4.3 验证导入路径
```bash
npm run type-check
```
**预期结果**：
- 无类型错误
- TypeScript能够正确解析`@/`别名
## 5. 风险与缓解措施
### 风险1：导入路径遗漏
**描述**：可能有其他文件引用了迁移的文件
**缓解措施**：
- 使用grep搜索所有引用
- 运行类型检查确保无遗漏
### 风险2：Playwright配置冲突
**描述**：Playwright可能无法正确解析`@/`别名
**缓解措施**：
- Playwright使用自己的配置，不依赖tsconfig.json
- 如果出现问题，可以使用相对路径作为备选方案
### 风险3：单元测试依赖问题
**描述**：单元测试可能依赖E2E测试的某些资源
**缓解措施**：
- 单元测试使用相对路径导入，不依赖别名
- 迁移后立即运行测试验证
## 6. 后续优化建议
1. **清理诊断代码**：移除`PasswordDiagnosticHandler.java`（生产环境不需要）
2. **完善测试文档**：更新README，说明单元测试和E2E测试的运行方式
3. **CI/CD集成**：确保CI流水线正确运行单元测试和E2E测试
## 7. 参考资料
- [Vitest配置文档](https://vitest.dev/config/)
- [Playwright配置文档](https://playwright.dev/docs/test-configuration)
- [TypeScript路径映射](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping)
docs/superpowers/specs/2026-04-07-e2e-test-simplification-design.md
+255
View File
@@ -0,0 +1,255 @@
# E2E测试精简设计文档
**版本：** 1.0
**日期：** 2026-04-07
**作者：** 张翔
**状态：** 待审查
---
## 1. 背景与目标
### 1.1 当前问题
当前E2E测试套件存在以下问题：
- **测试文件过多**：38个测试文件，维护成本高
- **运行时间长**：预计完整运行需要20分钟
- **测试稳定性差**：存在flaky测试，影响CI/CD效率
- **测试重复**：多个测试文件覆盖相同功能
### 1.2 优化目标
- 减少测试文件数量至5个（减少87%）
- 缩短测试运行时间至5分钟以内（减少75%）
- 提升测试稳定性和可维护性
- 保留关键业务流程验证
---
## 2. 测试架构设计
### 2.1 分层测试策略
采用分层测试策略，将E2E测试分为两层：
| 层级 | 测试类型 | 文件数 | 运行时间 | 覆盖范围 |
|------|---------|--------|---------|---------|
| L1 | 冒烟测试 | 1 | ~30秒 | 登录/登出基础流程 |
| L2 | 核心旅程 | 4 | ~4分钟 | 关键业务端到端流程 |
### 2.2 目录结构
```
e2e/
├── journeys/ # 核心用户旅程（保留）
│ ├── admin-complete-workflow.spec.ts # 管理员完整工作流
│ ├── user-permission-boundary.spec.ts # 用户权限边界验证
│ ├── file-management-workflow.spec.ts # 文件上传下载流程
│ └── audit-workflow.spec.ts # 审计日志查看流程
├── smoke/ # 冒烟测试（新增）
│ └── login-logout.spec.ts # 登录登出基础流程
├── fixtures/ # 测试数据（保留）
├── helpers/ # 测试辅助工具（保留）
├── pages/ # Page Object（保留）
└── utils/ # 工具函数（保留）
```
---
## 3. 核心测试用例设计
### 3.1 冒烟测试（smoke/login-logout.spec.ts）
**测试目标：** 验证基础登录登出流程
**测试用例：**
- 管理员登录和登出
**预期运行时间：** ~30秒
### 3.2 核心旅程测试
#### 3.2.1 管理员完整工作流（admin-complete-workflow.spec.ts）
**测试目标：** 验证管理员的核心操作流程
**测试用例：**
- 创建角色并分配权限
- 创建用户并分配角色
- 编辑用户信息
- 删除用户
- 删除角色
**预期运行时间：** ~2分钟
#### 3.2.2 用户权限边界验证（user-permission-boundary.spec.ts）
**测试目标：** 验证权限控制是否正确
**测试用例：**
- 普通用户不能访问用户管理页面
- 普通用户不能访问角色管理页面
- 管理员可以访问所有页面
**预期运行时间：** ~1分钟
#### 3.2.3 文件管理流程（file-management-workflow.spec.ts）
**测试目标：** 验证文件上传下载流程
**测试用例：**
- 上传文件
- 下载文件
- 删除文件
**预期运行时间：** ~1分钟
#### 3.2.4 审计日志流程（audit-workflow.spec.ts）
**测试目标：** 验证审计日志查看功能
**测试用例：**
- 查看操作日志
- 查看登录日志
- 查看异常日志
**预期运行时间：** ~30秒
---
## 4. 实施计划
### 4.1 实施步骤
1. **创建新目录结构**
- 创建 `e2e/smoke/` 目录
2. **创建冒烟测试**
- 新建 `e2e/smoke/login-logout.spec.ts`
3. **删除非核心测试文件**
- 删除34个非核心测试文件
- 只保留 `journeys/` 目录下的4个核心测试文件
### 4.2 测试配置更新
**package.json 脚本更新：**
```json
{
"scripts": {
"test:e2e:smoke": "playwright test smoke/",
"test:e2e:journeys": "playwright test journeys/",
"test:e2e": "playwright test"
}
}
```
### 4.3 CI/CD集成
- **PR验证**：运行 `npm run test:e2e`（~5分钟）
- **发布前验证**：运行所有测试
---
## 5. 预期收益
| 指标 | 优化前 | 优化后 | 改善幅度 |
|------|--------|--------|---------|
| 测试文件数量 | 38个 | 5个 | ↓ 87% |
| 预计运行时间 | ~20分钟 | ~5分钟 | ↓ 75% |
| 维护成本 | 高 | 低 | ↓ 80% |
| 测试稳定性 | 中 | 高 | ↑ 显著提升 |
---
## 6. 风险控制
### 6.1 功能覆盖风险
**风险：** 删除测试后功能覆盖下降
**缓解措施：**
- 通过单元测试和集成测试补充覆盖率
- 单元测试覆盖率目标：80%
### 6.2 回归测试风险
**风险：** 可能遗漏部分边界情况
**缓解措施：**
- 核心旅程测试覆盖关键路径
- 定期人工回归测试
### 6.3 团队适应风险
**风险：** 团队需要适应新的测试策略
**缓解措施：**
- 更新测试文档
- 培训团队成员
---
## 7. 后续优化建议
1. **补充单元测试**
- 为核心业务逻辑补充单元测试
- 覆盖率目标：80%
2. **补充集成测试**
- 为API接口补充集成测试
- 覆盖所有REST API端点
3. **持续优化**
- 定期评估测试效果
- 持续优化测试用例
---
## 8. 待删除测试文件清单
以下34个测试文件将被删除：
1. auth.spec.ts
2. basic.spec.ts
3. complete-workflow.spec.ts
4. comprehensive-e2e.spec.ts
5. critical-e2e.spec.ts
6. dashboard-operation-log.spec.ts
7. dictionary-management.spec.ts
8. edge-cases.spec.ts
9. exception-log.spec.ts
10. file-management.spec.ts
11. form-test.spec.ts
12. login-log.spec.ts
13. menu-management.spec.ts
14. notification.spec.ts
15. operation-log.spec.ts
16. permission-validation.spec.ts
17. role-management.spec.ts
18. security-e2e.spec.ts
19. system-config.spec.ts
20. system-integration-test.spec.ts
21. test-config-api.spec.ts
22. test-stability.spec.ts
23. uat-file-workflow.spec.ts
24. uat-permission-workflow.spec.ts
25. uat-user-lifecycle.spec.ts
26. user-lifecycle.spec.ts
27. user-management.spec.ts
28. role-based-tests/scenarios/authentication/login-flow.spec.ts
29. role-based-tests/scenarios/authentication/logout-flow.spec.ts
30. role-based-tests/scenarios/user-management/admin-creates-user.spec.ts
31. role-based-tests/scenarios/user-management/permission-boundary.spec.ts
32. journeys/system-config-workflow.spec.ts
33. journeys/permission-boundary.spec.ts（与user-permission-boundary.spec.ts重复）
---
## 9. 审查记录
| 日期 | 审查人 | 状态 | 备注 |
|------|--------|------|------|
| 2026-04-07 | 张翔 | 待审查 | 初始版本 |
docs/superpowers/specs/2026-04-08-permission-system-enhancement-design.md
+538
View File
@@ -0,0 +1,538 @@
# 权限系统增强设计文档
**日期**: 2026-04-08
**作者**: 张翔
**版本**: 1.0
**状态**: 待审查
## 1. 概述
### 1.1 背景
当前系统已完成基础的路由权限控制，但存在以下优化空间：
1. **菜单硬编码** - 菜单在前端硬编码，无法根据用户角色动态显示
2. **权限数据分散** - 角色和权限信息存储在 localStorage，缺乏统一管理
3. **缺少按钮级权限控制** - 无法控制按钮级别的权限
4. **缺少 API 权限检查** - 前端调用 API 前未检查权限，可能发送无效请求
### 1.2 目标
实现完整的权限系统增强，包括：
1. **动态菜单渲染** - 从后端获取菜单数据，根据用户权限动态渲染
2. **权限缓存优化** - 使用 Pinia 统一管理权限数据，localStorage 持久化
3. **权限指令** - 提供 `v-permission` 指令实现按钮级权限控制
4. **API 权限检查** - 前端调用 API 前检查权限，减少无效请求
### 1.3 范围
**包含：**
- Permission Store (Pinia)
- v-permission 指令
- 动态菜单渲染
- API 权限检查工具
- 相关单元测试
**不包含：**
- 后端权限系统修改（仅需新增 API）
- 数据库权限表结构调整
- 其他业务功能开发
## 2. 架构设计
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ 前端应用 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 路由守卫 │ │ 权限指令 │ │ 动态菜单 │ │
│ │ (已完成) │ │ v-permission │ │ 渲染 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Permission │ │
│ │ Store (Pinia) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ localStorage │ │
│ │ (持久化) │ │
│ └─────────────────┘ │
│ │
└───────────────────────────┬─────────────────────────────────┘
│
HTTP API │
│
┌───────────────────────────▼─────────────────────────────────┐
│ 后端服务 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ /auth/login │ │ /menus/user │ │ /permissions │ │
│ │ (已存在) │ │ (新增) │ │ (已存在) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ RBAC 权限系统 (角色-权限-菜单) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 数据流
```
登录成功
↓
解析 JWT token 获取角色
↓
调用 fetchUserMenus() 获取菜单和权限
↓
存入 Store + localStorage
↓
页面刷新时从 localStorage 恢复
```
## 3. 详细设计
### 3.1 Permission Store
**文件位置**: `src/stores/permission.ts`
**状态定义**:
```typescript
interface PermissionState {
roles: string[] // 用户角色
permissions: string[] // 用户权限码
menus: MenuItem[] // 用户菜单
loaded: boolean // 是否已加载
}
interface MenuItem {
id: number
name: string
path: string
icon?: string
parentId?: number
sort: number
children?: MenuItem[]
}
```
**核心 Actions**:
```typescript
// 初始化权限数据（从 localStorage 恢复）
initFromStorage(): void
// 登录后设置权限数据
setPermissionData(data: {
roles: string[]
permissions: string[]
menus: MenuItem[]
}): void
// 从后端刷新权限数据
async fetchUserMenus(): Promise<void>
// 清除权限数据（退出登录）
clearPermissionData(): void
// 权限检查方法
hasRole(role: string | string[]): boolean
hasPermission(permission: string | string[]): boolean
```
**持久化策略**:
- 登录时：将角色、权限、菜单数据存入 localStorage
- 页面刷新：Pinia 从 localStorage 恢复数据，立即渲染菜单
- 权限变更：提供刷新机制，同步更新 localStorage 和 Pinia
- 退出登录：清除所有数据
### 3.2 v-permission 指令
**文件位置**: `src/directives/permission.ts`
**用法**:
```vue
<!-- 角色检查 -->
<button v-permission:role="'admin'">管理员按钮</button>
<!-- 权限码检查 -->
<button v-permission:permission="'user:delete'">删除用户</button>
<!-- 支持数组（满足任一条件） -->
<button v-permission:role="['admin', 'manager']">导出数据</button>
<button v-permission:permission="['user:create', 'user:update']">编辑用户</button>
<!-- 简写形式（默认权限检查） -->
<button v-permission="'user:delete'">删除</button>
```
**实现逻辑**:
```typescript
export const permissionDirective = {
mounted(el: HTMLElement, binding: DirectiveBinding) {
const permissionStore = usePermissionStore()
const { arg, value } = binding
const checkType = arg || 'permission' // 默认权限检查
let hasAccess = false
if (checkType === 'role') {
hasAccess = permissionStore.hasRole(value)
} else if (checkType === 'permission') {
hasAccess = permissionStore.hasPermission(value)
}
if (!hasAccess) {
el.style.display = 'none'
}
}
}
```
**注册方式**:
```typescript
// src/main.ts
import { permissionDirective } from '@/directives/permission'
app.directive('permission', permissionDirective)
```
### 3.3 动态菜单渲染
**后端 API**:
```
GET /api/menus/user
请求头：
Authorization: Bearer <token>
响应：
{
"code": 200,
"data": {
"menus": [
{
"id": 1,
"name": "仪表盘",
"path": "/dashboard",
"icon": "Odometer",
"parentId": null,
"sort": 1
},
{
"id": 2,
"name": "系统管理",
"path": "/system",
"icon": "Setting",
"parentId": null,
"sort": 2,
"children": [
{
"id": 3,
"name": "用户管理",
"path": "/users",
"icon": null,
"parentId": 2,
"sort": 1
}
]
}
],
"permissions": [
"user:read",
"user:create",
"user:update",
"user:delete"
]
}
}
```
**前端组件**:
```vue
<!-- src/layouts/DefaultLayout.vue -->
<template>
<el-menu
:default-active="activeMenu"
class="menu"
:collapse="collapsed"
router
>
<menu-item
v-for="menu in menuTree"
:key="menu.id"
:menu="menu"
/>
</el-menu>
</template>
<script setup lang="ts">
import { computed } from 'vue'
import { usePermissionStore } from '@/stores/permission'
import MenuItem from '@/components/MenuItem.vue'
const permissionStore = usePermissionStore()
const menuTree = computed(() => permissionStore.menus)
</script>
```
**递归菜单组件**:
```vue
<!-- src/components/MenuItem.vue -->
<template>
<!-- 有子菜单 -->
<el-sub-menu
v-if="menu.children && menu.children.length > 0"
:index="String(menu.id)"
>
<template #title>
<el-icon v-if="menu.icon">
<component :is="menu.icon" />
</el-icon>
<span>{{ menu.name }}</span>
</template>
<menu-item
v-for="child in menu.children"
:key="child.id"
:menu="child"
/>
</el-sub-menu>
<!-- 无子菜单 -->
<el-menu-item
v-else
:index="menu.path"
>
<el-icon v-if="menu.icon">
<component :is="menu.icon" />
</el-icon>
<span>{{ menu.name }}</span>
</el-menu-item>
</template>
```
### 3.4 API 权限检查
**文件位置**: `src/utils/permission-check.ts`
**权限映射配置**:
```typescript
const apiPermissionMap: Record<string, { permission: string; method: string }> = {
'/api/users:GET': { permission: 'user:read', method: 'GET' },
'/api/users:POST': { permission: 'user:create', method: 'POST' },
'/api/users/*:PUT': { permission: 'user:update', method: 'PUT' },
'/api/users/*:DELETE': { permission: 'user:delete', method: 'DELETE' },
'/api/roles:GET': { permission: 'role:read', method: 'GET' },
// ... 更多映射
}
```
**检查函数**:
```typescript
export function canAccessApi(path: string, method: string): boolean {
const permissionStore = usePermissionStore()
const required = findRequiredPermission(path, method, apiPermissionMap)
if (!required) {
return true // 未定义权限要求的 API 默认允许
}
return permissionStore.hasPermission(required.permission)
}
```
**集成到请求拦截器**:
```typescript
// src/utils/request.ts
import { canAccessApi } from './permission-check'
request.interceptors.request.use(
(config) => {
// 权限检查
const path = config.url || ''
const method = config.method?.toUpperCase() || 'GET'
if (!canAccessApi(path, method)) {
return Promise.reject(new Error('无权限访问此 API'))
}
// 原有的 token 和签名逻辑
// ...
return config
}
)
```
## 4. 测试策略
### 4.1 测试覆盖范围
1. **Permission Store 单元测试**
- 测试权限数据的存储和恢复
- 测试 hasRole 和 hasPermission 方法
- 测试 localStorage 持久化
- 测试数据清除功能
2. **v-permission 指令测试**
- 测试角色检查功能
- 测试权限码检查功能
- 测试数组参数处理
- 测试元素隐藏/显示逻辑
3. **动态菜单测试**
- 测试菜单数据获取
- 测试菜单树渲染
- 测试菜单缓存机制
- 测试菜单权限过滤
4. **API 权限检查测试**
- 测试权限映射匹配
- 测试通配符匹配
- 测试请求拦截逻辑
### 4.2 测试文件结构
```
src/
├── stores/
│ └── __tests__/
│ └── permission.test.ts
├── directives/
│ └── __tests__/
│ └── permission.test.ts
├── components/
│ └── __tests__/
│ └── MenuItem.test.ts
└── utils/
└── __tests__/
└── permission-check.test.ts
```
## 5. 实施计划
### 5.1 实施顺序
**第 1 步：Permission Store（1-2 小时）**
- 创建 `src/stores/permission.ts`
- 实现 localStorage 持久化
- 编写单元测试
- 集成到登录流程
**第 2 步：v-permission 指令（1-2 小时）**
- 创建 `src/directives/permission.ts`
- 注册全局指令
- 编写单元测试
- 在现有页面应用示例
**第 3 步：后端 API 开发（2-3 小时）**
- 新增 `GET /api/menus/user` 接口
- 根据用户角色返回菜单树
- 返回用户权限列表
- 编写后端测试
**第 4 步：动态菜单渲染（2-3 小时）**
- 创建 `src/components/MenuItem.vue`
- 修改 `DefaultLayout.vue`
- 集成 Permission Store
- 编写组件测试
**第 5 步：API 权限检查（1-2 小时）**
- 创建 `src/utils/permission-check.ts`
- 集成到请求拦截器
- 编写单元测试
- 优化性能
### 5.2 后端 API 需求
**接口**: `GET /api/menus/user`
**功能**: 获取当前登录用户可访问的菜单和权限
**业务逻辑**:
1. 从 token 获取用户 ID
2. 查询用户角色
3. 根据角色查询菜单和权限
4. 构建菜单树结构
5. 返回菜单和权限列表
**预估时间**: 7-12 小时
## 6. 风险和约束
### 6.1 技术风险
1. **后端 API 开发时间** - 需要后端配合开发新 API
2. **菜单数据迁移** - 需要将硬编码菜单迁移到数据库
3. **权限数据同步** - 前后端权限数据需要保持一致
### 6.2 约束条件
1. **向后兼容** - 需要兼容现有的路由守卫逻辑
2. **性能要求** - 菜单加载不能影响页面首屏渲染速度
3. **测试覆盖** - 所有新增代码需要单元测试覆盖
## 7. 验收标准
### 7.1 功能验收
- [ ] Permission Store 正确管理权限数据
- [ ] v-permission 指令正确控制按钮显示
- [ ] 动态菜单根据用户权限正确渲染
- [ ] API 权限检查正确拦截无权限请求
### 7.2 质量验收
- [ ] 所有单元测试通过
- [ ] 代码覆盖率 ≥ 80%
- [ ] TypeScript 类型检查通过
- [ ] ESLint 检查通过
### 7.3 性能验收
- [ ] 菜单加载时间 < 500ms
- [ ] localStorage 读写不影响页面性能
- [ ] 权限检查不影响 API 请求速度
## 8. 后续优化
### 8.1 短期优化
1. **权限缓存过期** - 添加权限数据过期机制
2. **权限变更通知** - 实现权限变更后的实时通知
3. **权限日志** - 记录权限检查日志，便于调试
### 8.2 长期优化
1. **权限可视化配置** - 提供权限配置界面
2. **权限审计** - 记录用户权限变更历史
3. **权限模板** - 提供常用权限模板，简化配置
## 9. 参考资料
- [Vue 3 官方文档](https://vuejs.org/)
- [Pinia 官方文档](https://pinia.vuejs.org/)
- [Element Plus 文档](https://element-plus.org/)
- [RBAC 权限模型](https://en.wikipedia.org/wiki/Role-based_access_control)
docs/superpowers/specs/2026-04-08-user-journey-test-improvement-design.md
+404
View File
@@ -0,0 +1,404 @@
# User Journey 测试改进设计文档
**文档日期**: 2026-04-08
**负责人**: 张翔
**版本**: 1.0
**状态**: 已验证
---
## 执行摘要
通过快速验证测试，我们确认了 **Playwright 本身是有效的**，问题在于测试方式。改进后的测试方法成功发现了真实问题，证明了方案的可行性。
**核心发现**：
- ✅ Playwright 工具本身有效
- ❌ 旧测试方式存在假阳性问题
- ✅ 新测试方式能真实发现问题
- ✅ 三层验证策略可行
---
## 1. 问题分析
### 1.1 当前问题
**用户报告**：
- 测试通过了，但实际运行时页面没有内容
- Console 有 Mock API 日志，但页面无内容
**根本原因**：
```typescript
// ❌ 错误的测试方式
const dataStats = page.locator('[data-testid="data-stats"]')
if (await dataStats.isVisible()) { // 如果不可见，跳过验证！
const statsText = await dataStats.textContent()
expect(statsText).toBeTruthy() // 这行永远不会执行
}
// 测试通过！但实际上什么都没验证
```
**问题本质**：
- 软验证：元素不存在就跳过验证
- 假阳性：测试通过但实际无效
- 缺乏强制验证：没有确保元素必须存在
---
### 1.2 验证测试结果
**测试文件**: `tests/e2e/specs/validation/test-improvement-validation.spec.ts`
**测试结果**：
| 测试类型 | 结果 | 说明 |
|---------|------|------|
| ❌ 旧方式：软验证 | ✅ 通过 | **假阳性！** 元素不存在但测试通过 |
| ✅ 新方式：硬验证 | ❌ 失败 | **正确！** 元素不存在，测试失败 |
| ✅ 三层验证 | ❌ 失败 | API请求超时，暴露真实问题 |
| ✅ 完整用户旅程 | ❌ 失败 | 案件列表元素不存在（count = 0） |
| ✅ 诊断测试 | ✅ 通过 | 提供详细诊断信息 |
**关键发现**：
- 页面上没有 `.ant-list-item` 元素（count = 0）
- API请求超时（没有调用 `/api/cases`）
- 页面根本没有加载案件数据
---
## 2. 解决方案
### 2.1 核心原则转变
#### ❌ 旧方式（软验证）
```typescript
// 软验证：元素不存在就跳过
if (await element.isVisible()) {
expect(await element.textContent()).toBeTruthy()
}
```
#### ✅ 新方式（硬验证）
```typescript
// 硬验证：元素必须存在且可见
await expect(element).toBeVisible()
const text = await element.textContent()
expect(text).toBeTruthy()
expect(text.length).toBeGreaterThan(0)
```
---
### 2.2 三层验证策略
```typescript
test('真实验证用户看到的内容', async ({ page }) => {
// Layer 1: API层验证
const response = await page.waitForResponse('**/api/cases')
expect(response.status()).toBe(200)
const data = await response.json()
expect(data.length).toBeGreaterThan(0)
// Layer 2: 状态层验证
const state = await page.evaluate(() => {
return {
cases: window.__CASE_STORE__?.getState().cases,
currentCase: window.__CASE_STORE__?.getState().currentCase
}
})
expect(state.cases.length).toBeGreaterThan(0)
// Layer 3: DOM层验证
const caseItems = page.locator('.ant-list-item')
await expect(caseItems.first()).toBeVisible({ timeout: 5000 })
const count = await caseItems.count()
expect(count).toBeGreaterThan(0)
// Layer 4: 内容验证
const firstCaseText = await caseItems.first().textContent()
expect(firstCaseText).toBeTruthy()
expect(firstCaseText.length).toBeGreaterThan(10)
})
```
---
### 2.3 增强的测试工具
#### 1. 状态验证器
```typescript
// tests/e2e/utils/state-validator.ts
export async function validatePageState(page: Page, expectedState: {
hasCase?: boolean
hasData?: boolean
activePage?: string
}) {
const state = await page.evaluate(() => ({
currentCase: window.__CASE_STORE__?.getState().currentCase,
transactions: window.__DATA_STORE__?.getState().transactions,
activePage: window.__PAGE_STORE__?.getState().activePageKey
}))
if (expectedState.hasCase) {
expect(state.currentCase).toBeTruthy()
}
if (expectedState.hasData) {
expect(state.transactions.length).toBeGreaterThan(0)
}
if (expectedState.activePage) {
expect(state.activePage).toBe(expectedState.activePage)
}
}
```
#### 2. 内容验证器
```typescript
// tests/e2e/utils/content-validator.ts
export async function validateContent(
page: Page,
selector: string,
options: {
mustBeVisible?: boolean
mustHaveText?: boolean
minLength?: number
exactText?: string
} = {}
) {
const element = page.locator(selector)
// 默认必须可见
if (options.mustBeVisible !== false) {
await expect(element).toBeVisible({ timeout: 5000 })
}
if (options.mustHaveText) {
const text = await element.textContent()
expect(text).toBeTruthy()
if (options.minLength) {
expect(text.length).toBeGreaterThanOrEqual(options.minLength)
}
if (options.exactText) {
expect(text.trim()).toBe(options.exactText)
}
}
}
```
#### 3. 截图验证器
```typescript
// tests/e2e/utils/screenshot-validator.ts
export async function takeScreenshotAndValidate(
page: Page,
testName: string,
step: string
) {
const screenshot = await page.screenshot({
fullPage: true,
path: `test-results/screenshots/${testName}-${step}.png`
})
// 验证截图不为空
expect(screenshot.length).toBeGreaterThan(1000)
console.log(`📸 Screenshot saved: ${testName}-${step}.png`)
}
```
---
## 3. 实施计划
### 3.1 短期（1周内）
**目标**: 修复现有测试用例
**任务清单**:
- [ ] 将所有软验证改为硬验证
- [ ] 添加三层验证策略
- [ ] 创建测试工具函数
- [ ] 修复发现的问题
**预计工作量**: 2-3 天
---
### 3.2 中期（2-4周）
**目标**: 建立完整的测试体系
**任务清单**:
- [ ] 添加视觉验证（截图对比）
- [ ] 建立测试报告机制
- [ ] 集成到CI/CD
- [ ] 建立测试数据管理
**预计工作量**: 5-7 天
---
### 3.3 长期（1-3个月）
**目标**: 持续优化和扩展
**任务清单**:
- [ ] 评估是否需要引入Storybook
- [ ] 考虑AI辅助测试
- [ ] 建立性能测试
- [ ] 建立安全测试
**预计工作量**: 10-15 天
---
## 4. 技术选型
### 4.1 核心工具
**Playwright** ✅ **已验证有效**
- 优势：
- 强大的选择器和断言
- 支持API拦截和验证
- 内置截图和视频录制
- 跨浏览器支持
- 活跃的社区和文档
- 劣势：
- 需要正确的使用方式
- 学习曲线适中
**结论**: 继续使用Playwright，改进测试方式
---
### 4.2 辅助工具
| 工具 | 用途 | 优先级 |
|------|------|--------|
| Playwright Screenshot | 视觉验证 | P0 |
| Playwright Trace | 调试支持 | P0 |
| Playwright API Mocking | 数据模拟 | P1 |
| Percy / Chromatic | 视觉回归 | P2 |
| Storybook | 组件测试 | P3 |
---
## 5. 质量保障
### 5.1 测试原则
1. **硬验证优先**: 元素必须存在，否则测试失败
2. **多层验证**: API → 状态 → DOM → 内容
3. **快速失败**: 发现问题立即失败，不继续执行
4. **清晰诊断**: 提供详细的诊断信息
---
### 5.2 测试覆盖率目标
| 层级 | 当前覆盖率 | 目标覆盖率 |
|------|-----------|-----------|
| API层 | 0% | 100% |
| 状态层 | 0% | 100% |
| DOM层 | 50% | 100% |
| 内容层 | 30% | 100% |
| **总体** | **30%** | **100%** |
---
## 6. 风险评估
### 6.1 技术风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 测试用例维护成本高 | 中 | 中 | 建立测试工具库，提高可维护性 |
| 测试执行时间长 | 低 | 低 | 使用并行执行，优化测试用例 |
| 误报率高 | 高 | 低 | 使用硬验证，减少假阳性 |
---
### 6.2 业务风险
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 测试不通过影响交付 | 高 | 中 | 优先修复关键问题，建立分级测试 |
| 测试数据管理复杂 | 中 | 中 | 建立测试数据工厂，使用Mock数据 |
---
## 7. 成功标准
### 7.1 短期目标（1周内）
- ✅ 所有测试用例使用硬验证
- ✅ 测试覆盖率提升到 60%
- ✅ 无假阳性问题
- ✅ 发现并修复当前问题
---
### 7.2 中期目标（2-4周）
- ✅ 测试覆盖率提升到 80%
- ✅ 建立完整的测试报告
- ✅ 集成到CI/CD
- ✅ 测试执行时间 < 10分钟
---
### 7.3 长期目标（1-3个月）
- ✅ 测试覆盖率提升到 100%
- ✅ 建立视觉回归测试
- ✅ 建立性能测试
- ✅ 测试执行时间 < 5分钟
---
## 8. 附录
### 8.1 验证测试文件
**文件**: `tests/e2e/specs/validation/test-improvement-validation.spec.ts`
**测试结果**:
- ❌ 旧方式：软验证 - ✅ 通过（假阳性）
- ✅ 新方式：硬验证 - ❌ 失败（正确）
- ✅ 三层验证 - ❌ 失败（正确）
- ✅ 完整用户旅程 - ❌ 失败（正确）
- ✅ 诊断测试 - ✅ 通过
---
### 8.2 参考资料
- [Playwright 官方文档](https://playwright.dev/)
- [Playwright 最佳实践](https://playwright.dev/docs/best-practices)
- [测试驱动开发（TDD）](https://en.wikipedia.org/wiki/Test-driven_development)
---
## 9. 总结
### 9.1 核心结论
1. ✅ **Playwright 工具本身有效**
2. ❌ **问题在于测试方式（软验证 vs 硬验证）**
3. ✅ **改进后的测试能真实发现问题**
4. ✅ **三层验证策略可行**
---
### 9.2 下一步行动
1. **立即行动**: 修复现有测试用例，使用硬验证
2. **短期计划**: 建立测试工具库，提高可维护性
3. **中期计划**: 集成到CI/CD，建立完整测试体系
4. **长期计划**: 持续优化，建立视觉回归测试
---
**文档状态**: ✅ 已验证
**下一步**: 用户审查书面规格
docs/superpowers/specs/2026-04-08-user-journey-tests-design.md
+306
View File
@@ -0,0 +1,306 @@
# User Journey Tests 设计文档
**日期：** 2026-04-08
**作者：** 张翔
**状态：** 已批准
---
## 1. 概述
### 1.1 背景
novalon-manage-system 项目当前有 11 个功能模块，但仅有 7 个模块（63.6%）被 user journey 测试覆盖。为了提高测试覆盖率和系统质量，需要补充缺失的 4 个模块的端到端测试。
### 1.2 目标
为以下 4 个功能模块补充 user journey 测试：
1. **异常日志** - 查看系统异常记录
2. **系统配置** - 系统参数配置管理
3. **字典管理** - 数据字典管理
4. **通知管理** - 系统通知公告
### 1.3 范围
**包含：**
- 基础覆盖：查看列表、搜索功能、基本操作（新增/编辑/删除）
- 使用时间戳隔离测试数据
- 遵循现有测试风格和模式
**不包含：**
- 边界情况测试
- 错误处理测试
- 权限验证测试
---
## 2. 架构设计
### 2.1 文件结构
```
novalon-manage-web/e2e/journeys/
├── exception-log-workflow.spec.ts # 异常日志测试
├── config-workflow.spec.ts # 系统配置测试
├── dict-workflow.spec.ts # 字典管理测试
└── notice-workflow.spec.ts # 通知管理测试
```
### 2.2 测试模式
- **测试框架：** Playwright
- **组织方式：** 使用 `test.describe` 组织测试套件
- **步骤组织：** 使用 `test.step` 组织测试步骤
- **数据隔离：** 使用时间戳生成唯一测试数据
- **命名规范：** 遵循现有测试的命名规范
### 2.3 测试策略
每个模块包含 3-5 个独立测试：
1. **查看列表** - 验证页面加载和数据展示
2. **搜索功能** - 验证搜索和筛选
3. **新增操作** - 验证创建功能
4. **编辑操作** - 验证更新功能
5. **删除操作** - 验证删除功能
---
## 3. 详细设计
### 3.1 异常日志测试
**文件：** `exception-log-workflow.spec.ts`
**测试场景：**
| 测试名称 | 测试步骤 | 验证点 |
|---------|---------|--------|
| 查看异常日志列表 | 1. 导航到异常日志页面<br>2. 等待数据加载 | 表格组件可见 |
| 搜索异常日志 | 1. 输入搜索关键词<br>2. 点击搜索按钮<br>3. 等待结果 | 搜索结果正确显示 |
| 查看异常日志详情 | 1. 点击查看详情按钮<br>2. 等待对话框打开 | 详情对话框可见 |
**关键选择器：**
- 页面路径：`/exception-log`
- 表格：`.el-table`
- 搜索框：`input[placeholder*="搜索"]`
- 详情按钮：`button:has-text("查看")`
---
### 3.2 系统配置测试
**文件：** `config-workflow.spec.ts`
**测试场景：**
| 测试名称 | 测试步骤 | 验证点 |
|---------|---------|--------|
| 查看系统配置列表 | 1. 导航到系统配置页面<br>2. 等待数据加载 | 表格组件可见 |
| 新增系统配置 | 1. 点击新增配置按钮<br>2. 填写表单<br>3. 提交表单 | 成功消息显示 |
| 搜索系统配置 | 1. 输入搜索关键词<br>2. 点击搜索按钮 | 搜索结果正确显示 |
| 编辑系统配置 | 1. 点击编辑按钮<br>2. 修改配置值<br>3. 提交表单 | 成功消息显示 |
| 删除系统配置 | 1. 点击删除按钮<br>2. 确认删除 | 成功消息显示 |
**测试数据：**
```typescript
const timestamp = Date.now();
const configKey = `test_config_${timestamp}`;
const configName = `测试配置_${timestamp}`;
const configValue = `测试值_${timestamp}`;
```
**关键选择器：**
- 页面路径：`/config`
- 新增按钮：`button:has-text("新增配置")`
- 表单输入：`.el-dialog input`
- 提交按钮：`.el-dialog button:has-text("确定")`
---
### 3.3 字典管理测试
**文件：** `dict-workflow.spec.ts`
**测试场景：**
| 测试名称 | 测试步骤 | 验证点 |
|---------|---------|--------|
| 查看字典列表 | 1. 导航到字典管理页面<br>2. 等待数据加载 | 表格组件可见 |
| 新增字典 | 1. 点击新增字典按钮<br>2. 填写表单<br>3. 提交表单 | 成功消息显示 |
| 搜索字典 | 1. 输入搜索关键词<br>2. 点击搜索按钮 | 搜索结果正确显示 |
| 编辑字典 | 1. 点击编辑按钮<br>2. 修改字典信息<br>3. 提交表单 | 成功消息显示 |
| 删除字典 | 1. 点击删除按钮<br>2. 确认删除 | 成功消息显示 |
**测试数据：**
```typescript
const timestamp = Date.now();
const dictType = `test_dict_${timestamp}`;
const dictName = `测试字典_${timestamp}`;
```
**关键选择器：**
- 页面路径：`/dict`
- 新增按钮：`button:has-text("新增字典")`
- 表单输入：`.el-dialog input`
- 提交按钮：`.el-dialog button:has-text("确定")`
---
### 3.4 通知管理测试
**文件：** `notice-workflow.spec.ts`
**测试场景：**
| 测试名称 | 测试步骤 | 验证点 |
|---------|---------|--------|
| 查看通知列表 | 1. 导航到通知管理页面<br>2. 等待数据加载 | 表格组件可见 |
| 新增通知 | 1. 点击新增通知按钮<br>2. 填写表单<br>3. 提交表单 | 成功消息显示 |
| 搜索通知 | 1. 输入搜索关键词<br>2. 点击搜索按钮 | 搜索结果正确显示 |
| 编辑通知 | 1. 点击编辑按钮<br>2. 修改通知内容<br>3. 提交表单 | 成功消息显示 |
| 删除通知 | 1. 点击删除按钮<br>2. 确认删除 | 成功消息显示 |
**测试数据：**
```typescript
const timestamp = Date.now();
const noticeTitle = `测试通知_${timestamp}`;
const noticeContent = `这是测试通知内容_${timestamp}`;
```
**关键选择器：**
- 页面路径：`/notice`
- 新增按钮：`button:has-text("新增通知")`
- 表单输入：`.el-dialog input`
- 提交按钮：`.el-dialog button:has-text("确定")`
---
## 4. 测试数据管理
### 4.1 数据隔离策略
使用时间戳生成唯一测试数据：
```typescript
const timestamp = Date.now();
const uniqueName = `测试数据_${timestamp}`;
```
**优势：**
- 无需清理测试数据
- 避免测试数据冲突
- 与现有测试风格一致
### 4.2 测试数据示例
| 模块 | 数据字段 | 生成规则 |
|------|---------|---------|
| 系统配置 | configKey, configName | `test_config_${timestamp}` |
| 字典管理 | dictType, dictName | `test_dict_${timestamp}` |
| 通知管理 | noticeTitle, noticeContent | `测试通知_${timestamp}` |
---
## 5. 测试执行
### 5.1 运行命令
```bash
# 运行所有 journey 测试
npm run test:e2e:journeys
# 运行特定测试文件
npx playwright test e2e/journeys/exception-log-workflow.spec.ts
# 运行所有新增测试
npx playwright test e2e/journeys/exception-log-workflow.spec.ts \
e2e/journeys/config-workflow.spec.ts \
e2e/journeys/dict-workflow.spec.ts \
e2e/journeys/notice-workflow.spec.ts
```
### 5.2 测试配置
测试将使用现有的 Playwright 配置：
- **项目：** `journeys`
- **依赖：** `setup` 项目（认证）
- **存储状态：** `playwright/.auth/user.json`
- **浏览器：** Desktop Chrome
- **超时：** 120000ms
---
## 6. 验收标准
### 6.1 功能验收
- [ ] 所有测试文件创建成功
- [ ] 所有测试通过
- [ ] 测试覆盖率提升至 100%（11/11 模块）
### 6.2 质量验收
- [ ] 测试代码遵循现有风格
- [ ] 测试步骤清晰可读
- [ ] 测试数据隔离有效
- [ ] 无测试数据冲突
### 6.3 文档验收
- [ ] 测试文件包含清晰的注释
- [ ] 测试描述准确反映测试内容
- [ ] 测试步骤命名规范
---
## 7. 风险与缓解
### 7.1 风险识别
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| 测试数据污染 | 中 | 低 | 使用时间戳隔离 |
| 测试依赖环境 | 高 | 中 | 使用独立的测试环境 |
| 页面元素变化 | 中 | 低 | 使用稳定的选择器 |
| 测试超时 | 低 | 中 | 增加适当的等待时间 |
### 7.2 回滚计划
如果测试失败或影响现有测试，可以：
1. 删除新增的测试文件
2. 恢复到之前的测试状态
3. 分析失败原因后重新实施
---
## 8. 后续改进
### 8.1 短期改进
1. 修复 `admin-complete-workflow.spec.ts` 中被跳过的清理测试
2. 增强菜单管理的测试覆盖
3. 增强登录日志的测试覆盖
### 8.2 长期改进
1. 引入边界情况测试
2. 引入错误处理测试
3. 引入权限验证测试
4. 实现测试数据自动清理
---
## 9. 参考资料
- [Playwright 官方文档](https://playwright.dev/)
- [项目 E2E 测试 README](../../novalon-manage-web/e2e/README.md)
- [现有测试示例](../../novalon-manage-web/e2e/journeys/)
---
**批准人：** 用户
**批准日期：** 2026-04-08
docs/superpowers/specs/2026-04-15-local-dev-testing-design.md
+260
View File
@@ -0,0 +1,260 @@
# 本地开发环境集成测试方案设计
**日期**: 2026-04-15
**作者**: 张翔 (全栈质量保障与效能工程师)
**版本**: 1.0
## 1. 任务概述
### 1.1 目标
启动前后端系统（包含网关服务），确保前后端联通，在开发环境中使用已有的测试框架进行用户旅程测试。数据库部署在Docker中，应用直接在开发环境中运行。
### 1.2 成功标准
1. ✅ 数据库在Docker中成功启动并初始化
2. ✅ 后端网关和应用服务在本地成功启动
3. ✅ 前端应用在本地成功启动并连接到后端
4. ✅ 用户旅程测试（E2E测试）成功执行
5. ✅ 所有服务健康状态正常
## 2. 技术架构
### 2.1 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ 本地开发环境 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Vue 3 │ │ Spring Cloud│ │ Spring Boot │ │
│ │ 前端应用 │◄──►│ Gateway │◄──►│ 应用服务 │ │
│ │ (端口:3000)│ │ (端口:8080)│ │ (端口:8084) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ └─────────────────────────┴───────────────┘ │
│ HTTP/REST API 通信 │
├─────────────────────────────────────────────────────────────┤
│ Docker容器环境 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PostgreSQL 15数据库 │ │
│ │ (端口:55432) │ │
│ │ Flyway自动迁移 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 技术栈
- **后端**: Java 21 + Spring Boot 3.5.13 + Spring Cloud Gateway
- **前端**: Vue 3 + TypeScript + Vite + Element Plus
- **数据库**: PostgreSQL 15 (Docker容器)
- **测试框架**: Playwright (E2E测试)
- **构建工具**: Maven (后端) + pnpm/npm (前端)
## 3. 配置方案
### 3.1 数据库配置
- **容器服务**: PostgreSQL 15 (postgres:15-alpine)
- **端口映射**: 55432:5432 (避免与本地PostgreSQL冲突)
- **数据库名称**: manage_system
- **认证信息**: novalon/novalon123
- **数据卷**: postgres_data (持久化存储)
- **健康检查**: pg_isready命令验证
### 3.2 后端服务配置
- **网关服务**:
- 端口: 8080
- 路由配置: /api/** → localhost:8084
- 过滤器: JWT认证、RBAC授权、重试机制
- **应用服务**:
- 端口: 8084
- 数据库连接: r2dbc:postgresql://localhost:55432/manage_system
- 健康检查: /actuator/health端点
- **启动方式**: Maven多模块同时启动
### 3.3 前端服务配置
- **开发服务器**: Vite (端口:3000)
- **API代理**: 配置代理到网关服务 (localhost:8080)
- **环境变量**: 使用开发环境配置
- **构建工具**: pnpm (推荐) 或 npm
### 3.4 测试配置
- **测试框架**: Playwright
- **测试范围**: 冒烟测试 (login-logout.spec.ts)
- **测试数据**:
- 管理员账号: admin/Test@123
- 普通用户账号: user/Test@123
- **测试环境**: 连接到本地运行的服务
## 4. 实施步骤
### 4.1 阶段一：数据库容器启动
```bash
# 1. 启动PostgreSQL容器
docker-compose up -d postgres
# 2. 等待数据库就绪 (10秒)
sleep 10
# 3. 验证数据库连接
docker-compose exec postgres pg_isready -U novalon -d manage_system
```
### 4.2 阶段二：后端服务启动
```bash
# 1. 进入后端项目目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-api
# 2. 使用Maven同时启动网关和应用
mvn spring-boot:run -pl manage-gateway,manage-app -am
```
### 4.3 阶段三：前端服务启动
```bash
# 1. 进入前端项目目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
# 2. 安装依赖 (如果未安装)
pnpm install # 或 npm install
# 3. 启动开发服务器
pnpm run dev # 或 npm run dev
```
### 4.4 阶段四：执行E2E测试
```bash
# 1. 在另一个终端执行冒烟测试
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
pnpm run test:e2e:smoke # 或 npm run test:e2e:smoke
```
## 5. 验证检查点
### 5.1 数据库验证
- [ ] PostgreSQL容器运行状态正常 (`docker-compose ps`)
- [ ] 数据库端口55432可访问 (`telnet localhost 55432`)
- [ ] Flyway迁移脚本执行成功 (查看应用日志)
### 5.2 后端验证
- [ ] 网关服务在8080端口响应 (`curl http://localhost:8080/actuator/health`)
- [ ] 应用服务在8084端口响应 (`curl http://localhost:8084/actuator/health`)
- [ ] 健康检查端点返回UP状态
- [ ] 网关能正确路由到应用服务
### 5.3 前端验证
- [ ] 开发服务器在3000端口运行 (`curl http://localhost:3000`)
- [ ] 页面能正常加载 (浏览器访问 http://localhost:3000)
- [ ] API请求能正确代理到后端
### 5.4 测试验证
- [ ] 冒烟测试执行通过
- [ ] 登录登出流程正常
- [ ] 测试报告生成成功
## 6. 故障排除预案
### 6.1 常见问题及解决方案
#### 问题1：端口冲突
- **症状**: 服务启动失败，提示端口被占用
- **解决方案**:
1. 检查8080、8084、55432端口是否被占用: `lsof -i :8080`
2. 停止占用端口的进程或修改配置使用其他端口
3. 修改application.yml中的端口配置
#### 问题2：数据库连接失败
- **症状**: 应用启动时报数据库连接错误
- **解决方案**:
1. 验证Docker容器状态: `docker-compose ps`
2. 检查数据库日志: `docker-compose logs postgres`
3. 验证网络连接: `telnet localhost 55432`
4. 检查数据库认证信息配置
#### 问题3：服务启动失败
- **症状**: Maven启动时报依赖或配置错误
- **解决方案**:
1. 清理Maven缓存: `mvn clean`
2. 重新下载依赖: `mvn dependency:resolve`
3. 检查Spring配置文件和环境变量
4. 查看详细错误日志
#### 问题4：测试失败
- **症状**: Playwright测试执行失败
- **解决方案**:
1. 验证测试环境服务是否正常运行
2. 检查测试数据是否正确
3. 查看测试失败截图和日志
4. 运行调试模式: `pnpm run test:e2e:debug`
### 6.2 回滚方案
1. **停止所有服务**:
```bash
# 停止Docker容器
docker-compose down
# 停止Maven进程 (Ctrl+C)
# 停止npm进程 (Ctrl+C)
```
2. **清理临时文件**:
```bash
# 清理Maven构建目录
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-api
mvn clean
# 清理前端缓存
cd /Users/zhangxiang/Codes/Novalon/novalon-manage-system/novalon-manage-web
rm -rf node_modules/.vite
```
3. **重新执行**:
按照4.1-4.4步骤重新执行
## 7. 监控与日志
### 7.1 服务监控
- **数据库**: `docker-compose logs -f postgres`
- **后端应用**: Maven控制台输出 + 应用日志
- **前端**: Vite开发服务器控制台输出
- **测试**: Playwright测试报告和控制台输出
### 7.2 关键指标
- 服务启动时间
- API响应时间
- 数据库连接状态
- 测试执行成功率
- 资源使用情况 (CPU/内存)
## 8. 后续优化建议
### 8.1 短期优化
1. **自动化脚本**: 创建一键启动脚本，简化操作流程
2. **环境配置**: 完善本地开发环境配置文件
3. **测试数据**: 优化测试数据管理，支持数据重置
### 8.2 中期优化
1. **容器化开发环境**: 考虑使用DevContainer统一开发环境
2. **测试覆盖率**: 增加更多E2E测试场景
3. **性能监控**: 集成APM工具监控应用性能
### 8.3 长期优化
1. **CI/CD集成**: 将本地测试流程集成到CI/CD流水线
2. **多环境支持**: 支持开发、测试、预发、生产多环境
3. **安全加固**: 加强安全测试和漏洞扫描
## 9. 附录
### 9.1 配置文件位置
- 数据库配置: `docker-compose.yml`
- 后端配置: `novalon-manage-api/manage-*/src/main/resources/application*.yml`
- 前端配置: `novalon-manage-web/.env*`, `vite.config.ts`
- 测试配置: `novalon-manage-web/playwright.config.ts`
### 9.2 相关文档
- 项目README: `/Users/zhangxiang/Codes/Novalon/novalon-manage-system/README.md`
- E2E测试说明: `novalon-manage-web/e2e/README.md`
- API文档: `http://localhost:8084/swagger-ui.html` (启动后访问)
### 9.3 联系方式
- **负责人**: 张翔
- **角色**: 全栈质量保障与效能工程师
- **原则**: 质量是设计出来的，并通过自动化流水线保障
docs/superpowers/specs/2026-04-15-menu-and-logout-fix-design.md
+376
View File
@@ -0,0 +1,376 @@
# 菜单数据修复与登出功能优化设计文档
**日期**: 2026-04-15
**作者**: 张翔
**版本**: 1.0
## 1. 背景与问题
### 1.1 问题背景
在User Journey测试过程中，发现了以下两个主要问题：
1. **系统配置菜单缺失**: 测试脚本无法找到"系统配置"菜单，导致测试失败
2. **登出功能测试失败**: 测试脚本报告"登出功能缺失"，但实际上登出功能已经在前端实现
### 1.2 问题根因分析
#### 1.2.1 系统配置菜单缺失
**根本原因**: 数据库中的菜单数据都是测试数据，没有实际的业务菜单
**数据库现状**:
```sql
SELECT id, menu_name, parent_id, order_num, menu_type, component FROM sys_menu;
```
结果：
```
id | menu_name | parent_id | order_num | menu_type | component
----+-------------------------+-----------+-----------+-----------+-----------
1 | 测试菜单_1774884610 | 0 | 1 | M |
2 | 测试菜单_1774885290 | 0 | 1 | M |
3 | 回归测试菜单_1774885909 | 0 | 1 | M |
4 | 回归测试菜单_1774885952 | 0 | 1 | M |
5 | 回归测试菜单_1774885984 | 0 | 1 | M |
6 | 回归测试菜单_1774886603 | 0 | 1 | M |
7 | 回归测试菜单_1774886605 | 0 | 1 | M |
```
**影响**:
- 前端无法显示正确的业务菜单
- 测试脚本无法找到"系统配置"等业务菜单
- 用户体验极差，无法使用系统功能
#### 1.2.2 登出功能测试失败
**根本原因**: 测试脚本的选择器没有正确匹配到下拉菜单中的"退出登录"按钮
**前端实现现状**:
```vue
<el-dropdown @command="handleCommand">
<el-avatar :size="32">
{{ username }}
</el-avatar>
<template #dropdown>
<el-dropdown-menu>
<el-dropdown-item command="profile">
个人中心
</el-dropdown-item>
<el-dropdown-item
command="logout"
divided
>
退出登录
</el-dropdown-item>
</el-dropdown-menu>
</template>
</el-dropdown>
```
**测试脚本选择器**:
```javascript
const logoutSelectors = [
'button:has-text("退出")',
'button:has-text("登出")',
'a:has-text("退出")',
'a:has-text("登出")',
'[data-action="logout"]',
'.logout-button'
];
```
**问题**: 选择器没有匹配到`el-dropdown-item`元素
**影响**:
- 测试报告显示"登出功能缺失"
- 实际上登出功能已经实现，只是测试脚本不准确
## 2. 解决方案设计
### 2.1 方案概述
采用**数据库菜单数据修复 + 测试脚本优化**的方案，解决根本问题并提高测试准确性。
### 2.2 数据库菜单数据修复
#### 2.2.1 菜单数据结构设计
基于前端路由配置，设计以下菜单结构：
**一级菜单**:
1. 系统管理 (System Management)
2. 系统监控 (System Monitor)
3. 审计日志 (Audit Log)
**二级菜单**:
- 系统管理下：
- 用户管理
- 角色管理
- 菜单管理
- 参数配置
- 字典管理
- 系统监控下：
- 文件管理
- 通知公告
- 审计日志下：
- 登录日志
- 操作日志
- 异常日志
#### 2.2.2 数据库表结构
```sql
CREATE TABLE IF NOT EXISTS sys_menu (
id BIGSERIAL PRIMARY KEY,
menu_name VARCHAR(50) NOT NULL,
parent_id BIGINT DEFAULT 0,
order_num INT DEFAULT 0,
menu_type CHAR(1) DEFAULT 'M', -- M: 目录, C: 菜单, F: 按钮
component VARCHAR(200),
perms VARCHAR(100),
icon VARCHAR(100),
status INT DEFAULT 1,
visible INT DEFAULT 1,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMP
);
```
#### 2.2.3 菜单数据插入
```sql
-- 清理测试数据
DELETE FROM sys_menu WHERE menu_name LIKE '%测试%' OR menu_name LIKE '%回归%';
-- 插入一级菜单
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, icon, status) VALUES
('系统管理', 0, 1, 'M', 'Setting', 1),
('系统监控', 0, 2, 'M', 'Monitor', 1),
('审计日志', 0, 3, 'M', 'Document', 1);
-- 插入二级菜单
INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, component, perms, icon, status) VALUES
-- 系统管理下的菜单
('用户管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理'), 1, 'C', 'system/user/index', 'system:user:list', 'User', 1),
('角色管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理'), 2, 'C', 'system/role/index', 'system:role:list', 'UserFilled', 1),
('菜单管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理'), 3, 'C', 'system/menu/index', 'system:menu:list', 'Menu', 1),
('参数配置', (SELECT id FROM sys_menu WHERE menu_name = '系统管理'), 4, 'C', 'system/config/index', 'system:config:list', 'Tools', 1),
('字典管理', (SELECT id FROM sys_menu WHERE menu_name = '系统管理'), 5, 'C', 'system/dict/index', 'system:dict:list', 'Collection', 1),
-- 系统监控下的菜单
('文件管理', (SELECT id FROM sys_menu WHERE menu_name = '系统监控'), 1, 'C', 'system/file/index', 'system:file:list', 'Folder', 1),
('通知公告', (SELECT id FROM sys_menu WHERE menu_name = '系统监控'), 2, 'C', 'system/notice/index', 'system:notice:list', 'Bell', 1),
-- 审计日志下的菜单
('登录日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志'), 1, 'C', 'audit/login/index', 'audit:login:list', 'Document', 1),
('操作日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志'), 2, 'C', 'audit/operation/index', 'audit:operation:list', 'Document', 1),
('异常日志', (SELECT id FROM sys_menu WHERE menu_name = '审计日志'), 3, 'C', 'audit/exception/index', 'audit:exception:list', 'Warning', 1);
```
### 2.3 测试脚本优化
#### 2.3.1 登出功能测试优化
**问题**: 当前选择器无法匹配Element Plus的下拉菜单项
**解决方案**: 更新选择器以匹配Element Plus的下拉菜单结构
```javascript
const logoutSelectors = [
// Element Plus下拉菜单项
'.el-dropdown-menu__item:has-text("退出登录")',
'.el-dropdown-menu__item:has-text("退出")',
'.el-dropdown-menu__item:has-text("登出")',
// 通用选择器
'button:has-text("退出")',
'button:has-text("登出")',
'a:has-text("退出")',
'a:has-text("登出")',
'[data-action="logout"]',
'.logout-button'
];
```
#### 2.3.2 系统配置菜单测试优化
**问题**: 当前选择器无法匹配实际的菜单文本
**解决方案**: 更新选择器以匹配实际的菜单结构
```javascript
const configMenuSelectors = [
// Element Plus菜单项
'.el-menu-item:has-text("参数配置")',
'.el-menu-item:has-text("系统配置")',
'.el-menu-item:has-text("配置管理")',
// 通用选择器
'text=参数配置',
'text=系统配置',
'text=配置管理',
'[data-menu="config"]',
'a[href*="config"]'
];
```
### 2.4 扩展测试覆盖
#### 2.4.1 新增测试用例
1. **菜单管理功能测试**
- 测试菜单的增删改查
- 测试菜单树的显示
- 测试菜单权限控制
2. **参数配置功能测试**
- 测试参数的增删改查
- 测试参数的缓存机制
- 测试参数的导入导出
3. **字典管理功能测试**
- 测试字典的增删改查
- 测试字典项的管理
- 测试字典的缓存机制
#### 2.4.2 测试数据管理
建立测试数据管理机制，确保测试数据的独立性和可重复性：
```javascript
class TestDataManager {
async setupTestData() {
// 创建测试用户
// 创建测试角色
// 创建测试菜单
}
async cleanupTestData() {
// 清理测试用户
// 清理测试角色
// 清理测试菜单
}
}
```
## 3. 实施步骤
### 3.1 数据库菜单数据修复
1. **清理测试数据**
- 删除所有测试菜单数据
- 确保数据库干净
2. **插入业务菜单数据**
- 按照设计的菜单结构插入数据
- 确保菜单层级关系正确
3. **验证菜单数据**
- 查询菜单数据确认正确性
- 测试前端菜单显示
### 3.2 测试脚本优化
1. **更新登出功能测试**
- 修改选择器以匹配Element Plus下拉菜单
- 增加等待时间确保下拉菜单展开
2. **更新系统配置菜单测试**
- 修改选择器以匹配实际菜单文本
- 增加菜单导航的容错处理
3. **扩展测试覆盖**
- 编写菜单管理测试用例
- 编写参数配置测试用例
- 编写字典管理测试用例
### 3.3 验证与测试
1. **单元测试**
- 测试菜单数据的正确性
- 测试前端菜单组件
2. **集成测试**
- 测试前后端菜单数据交互
- 测试菜单权限控制
3. **端到端测试**
- 运行完整的User Journey测试
- 验证所有测试用例通过
## 4. 测试策略
### 4.1 测试层次
1. **单元测试**: 测试菜单组件和数据转换逻辑
2. **集成测试**: 测试前后端菜单数据交互
3. **端到端测试**: 测试完整的用户操作流程
### 4.2 测试数据
1. **测试用户**: 使用admin/admin123进行测试
2. **测试菜单**: 使用实际业务菜单数据
3. **测试环境**: 使用开发环境数据库
### 4.3 测试工具
1. **Playwright**: 用于端到端测试
2. **Vitest**: 用于单元测试
3. **PostgreSQL**: 用于数据库验证
## 5. 风险评估
### 5.1 技术风险
| 风险项 | 影响程度 | 发生概率 | 缓解措施 |
|--------|----------|----------|----------|
| 菜单数据插入失败 | 高 | 低 | 使用事务确保数据一致性 |
| 前端菜单显示异常 | 中 | 中 | 充分测试菜单组件 |
| 测试脚本不稳定 | 中 | 中 | 增加重试机制和等待时间 |
### 5.2 业务风险
| 风险项 | 影响程度 | 发生概率 | 缓解措施 |
|--------|----------|----------|----------|
| 菜单权限配置错误 | 高 | 低 | 严格按照权限设计配置 |
| 用户体验不佳 | 中 | 低 | 进行用户验收测试 |
## 6. 验收标准
### 6.1 功能验收
- [ ] 数据库菜单数据正确插入
- [ ] 前端菜单正确显示
- [ ] 登出功能测试通过
- [ ] 系统配置菜单测试通过
- [ ] 所有User Journey测试通过率≥90%
### 6.2 质量验收
- [ ] 代码通过ESLint检查
- [ ] 单元测试覆盖率≥80%
- [ ] 无严重Bug
- [ ] 性能指标达标
## 7. 后续优化
### 7.1 短期优化
1. 完善菜单权限控制
2. 优化菜单加载性能
3. 增加菜单缓存机制
### 7.2 长期优化
1. 实现菜单的动态配置
2. 支持菜单的导入导出
3. 建立菜单变更审计日志
## 8. 参考资料
- [Element Plus Menu组件文档](https://element-plus.org/zh-CN/component/menu.html)
- [Element Plus Dropdown组件文档](https://element-plus.org/zh-CN/component/dropdown.html)
- [Vue Router官方文档](https://router.vuejs.org/zh/)
- [Playwright最佳实践](https://playwright.dev/docs/best-practices)
docs/superpowers/specs/2026-04-15-user-role-menu-test-fix-design.md
+218
View File
@@ -0,0 +1,218 @@
# 用户管理和角色管理测试修复设计文档
**日期**: 2026-04-15
**作者**: 张翔
**版本**: 1.0
## 1. 背景与问题
### 1.1 问题背景
在User Journey测试过程中，发现以下两个测试失败：
1. **导航到用户管理页面**: 测试超时失败
2. **导航到角色管理页面**: 测试超时失败
### 1.2 问题根因分析
**根本原因**: 用户管理和角色管理是"系统管理"菜单下的二级菜单项。在Element Plus的菜单组件中，当父菜单处于折叠状态时，子菜单项是不可见的。测试脚本直接尝试点击这些不可见的菜单项，导致超时失败。
**错误信息**:
```
locator.click: Timeout 30000ms exceeded.
Call log:
- waiting for locator('text=用户管理').first()
- locator resolved to <span>用户管理</span>
- attempting click action
- waiting for element to be visible, enabled and stable
- element is not visible
```
**对比分析**:
- ✅ 系统配置测试：正确地先展开了系统管理菜单，测试通过
- ❌ 用户管理测试：直接尝试点击菜单项，测试失败
- ❌ 角色管理测试：直接尝试点击菜单项，测试失败
## 2. 解决方案设计
### 2.1 设计目标
修复用户管理和角色管理测试，使其能够正确展开系统管理菜单后再点击子菜单项，提高测试通过率。
### 2.2 技术方案
采用与系统配置测试相同的策略：先展开父菜单，再点击子菜单项。
### 2.3 实现细节
#### 2.3.1 修改用户管理测试
**文件**: `novalon-manage-web/user-journey-test.js`
**修改位置**: 第140-180行
**修改内容**:
```javascript
// 阶段2: 用户管理测试
console.log('\n📋 阶段2: 用户管理测试');
console.log('=====================================');
try {
// 首先展开系统管理菜单（如果是折叠状态）
const systemMenuSelector = '.el-sub-menu:has-text("系统管理")';
const systemMenuElement = page.locator(systemMenuSelector).first();
if (await systemMenuElement.count() > 0) {
// 点击展开系统管理菜单
await systemMenuElement.click();
await page.waitForTimeout(500);
// 然后点击用户管理菜单项
const userMenuSelectors = [
'.el-menu-item:has-text("用户管理")',
'text=用户管理',
'text=用户',
'[data-menu="user"]',
'a[href*="user"]'
];
let navigated = false;
for (const selector of userMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '04-user-management');
logTest('导航到用户管理页面', true);
} else {
throw new Error('未找到用户管理菜单');
}
} else {
throw new Error('未找到系统管理菜单');
}
} catch (error) {
logTest('导航到用户管理页面', false, error.message);
}
```
#### 2.3.2 修改角色管理测试
**文件**: `novalon-manage-web/user-journey-test.js`
**修改位置**: 第210-240行
**修改内容**:
```javascript
// ==================== 阶段3: 角色管理 ====================
console.log('\n📋 阶段3: 角色管理测试');
console.log('=====================================');
try {
// 首先展开系统管理菜单（如果是折叠状态）
const systemMenuSelector = '.el-sub-menu:has-text("系统管理")';
const systemMenuElement = page.locator(systemMenuSelector).first();
if (await systemMenuElement.count() > 0) {
// 点击展开系统管理菜单
await systemMenuElement.click();
await page.waitForTimeout(500);
// 然后点击角色管理菜单项
const roleMenuSelectors = [
'.el-menu-item:has-text("角色管理")',
'text=角色管理',
'text=角色',
'[data-menu="role"]',
'a[href*="role"]'
];
let navigated = false;
for (const selector of roleMenuSelectors) {
const element = page.locator(selector).first();
if (await element.count() > 0) {
await element.click();
navigated = true;
break;
}
}
if (navigated) {
await page.waitForTimeout(1000);
await captureStep(page, '05-role-management');
logTest('导航到角色管理页面', true);
} else {
throw new Error('未找到角色管理菜单');
}
} else {
throw new Error('未找到系统管理菜单');
}
} catch (error) {
logTest('导航到角色管理页面', false, error.message);
}
```
## 3. 验收标准
### 3.1 功能验收
- ✅ 用户管理测试能够成功导航到用户管理页面
- ✅ 角色管理测试能够成功导航到角色管理页面
- ✅ 测试通过率从80%提升到100%
### 3.2 质量验收
- ✅ 测试代码与系统配置测试保持一致的风格
- ✅ 测试代码包含清晰的注释
- ✅ 测试代码包含错误处理
### 3.3 测试验收
- ✅ User Journey测试全部通过（10/10）
- ✅ 新增Playwright测试全部通过（3/3）
- ✅ 测试报告生成成功
## 4. 影响范围
### 4.1 受影响的文件
- `novalon-manage-web/user-journey-test.js`: 修改用户管理和角色管理测试代码
### 4.2 不受影响的部分
- 前端代码：不修改
- 后端代码：不修改
- 数据库：不修改
- 其他测试：不修改
## 5. 风险评估
### 5.1 技术风险
- **风险等级**: 低
- **风险描述**: 修改仅涉及测试代码，不影响生产代码
- **缓解措施**: 修改后立即运行测试验证
### 5.2 业务风险
- **风险等级**: 无
- **风险描述**: 不涉及业务逻辑修改
## 6. 后续优化建议
1. **统一测试策略**: 将"先展开父菜单，再点击子菜单项"的策略应用到所有二级菜单测试中
2. **封装公共方法**: 将展开菜单的逻辑封装为公共方法，减少代码重复
3. **增加等待策略**: 使用更智能的等待策略（如等待元素可见）替代固定的timeout
## 7. 实施计划
1. 修改用户管理测试代码
2. 修改角色管理测试代码
3. 运行User Journey测试验证
4. 提交代码
**预计工作量**: 30分钟
docs/文档清单.md
-842
View File
@@ -1,842 +0,0 @@
# 健身房管理系统文档清单
> 文档编号: GYM-DOC-LIST-001
> 版本：v1.9
> 日期: 2026-03-08
> 作者: 张翔
> 状态: 完成
---
## 文档修订历史
| 版本 | 日期 | 作者 | 修订内容 |
| ---- | ---------- | ---- | -------- |
| v1.0 | 2026-03-05 | 张翔 | 创建文档清单 |
| v1.1 | 2026-03-07 | 张翔 | 更新文档清单，补充智能获客工具和智能体测数据联动模块内容 |
| v1.2 | 2026-03-07 | 张翔 | 更新文档状态为"已发布"，修复定价信息不一致问题 |
| v1.3 | 2026-03-07 | 张翔 | 修复文档状态不一致问题，补充 UI 模版定制功能，更新产品介绍手册定价信息 |
| v1.4 | 2026-03-08 | 张翔 | 修复并发用户数不一致问题，统一文档状态为"正式发布"，统一文档日期为 2026-03-04 |
| v1.5 | 2026-03-08 | 张翔 | 完成文档架构优化，实现业务设计和技术设计分离，新增 BLD 和 TLD 文档，归档 HLD 文档 |
| v1.6 | 2026-03-08 | 张翔 | 完成文档架构优化，实现业务概要设计（B-HLD）、业务详细设计（B-LLD）、技术实现详细设计（T-ILD）三层架构 |
| v1.7 | 2026-03-08 | 张翔 | 删除过时的模块 LLD 文档，内容已整合到 T-ILD 文档中 |
| v1.8 | 2026-03-08 | 张翔 | 归档 HLD-技术架构设计文档，内容整合到 T-ILD 文档体系 |
| v1.9 | 2026-03-08 | 张翔 | 新增技术专题文档（数据库设计、API 设计、安全设计），统一文档日期和状态规范 |
---
## 一、文档概述
本文档列出了健身房管理系统项目的所有文档，包括产品需求文档、设计文档、模块文档、计划文档、客户文档和归档文档。文档按类型和版本进行分类，便于查找和管理。
### 1.1 文档分类
- **产品需求文档（PRD）**: 描述产品功能需求和用户故事
- **业务概要设计文档（B-HLD）**: 描述业务范围、核心业务流程、业务规则
- **业务详细设计文档（B-LLD）**: 描述详细业务流程、业务数据流转、业务指标
- **技术实现详细设计文档（T-ILD）**: 描述系统架构、技术选型、实现细节
- **高层设计文档（HLD）**: 描述系统架构和业务流程（已废弃，由B-HLD和T-ILD替代）
- **详细设计文档（LLD）**: 描述技术实现细节（已废弃，由T-ILD替代）
- **计划文档**: 描述项目计划和设计方案
- **客户文档**: 面向客户的产品介绍文档
- **归档文档**: 历史版本文档
- **部署运维文档**: 系统部署和运维指南
### 1.2 文档编号规则
- PRD文档: GYM-PRD-{VERSION}-001
- B-HLD文档: GYM-B-HLD-{VERSION}-001
- B-LLD文档: GYM-B-LLD-{VERSION}-001
- T-ILD文档: GYM-T-ILD-{VERSION}-001
- HLD文档: GYM-HLD-{VERSION}-001（已废弃）
- LLD文档: GYM-LLD-{VERSION}-001（已废弃）
- 审查报告: GYM-DOC-REVIEW-001
- 文档清单: GYM-DOC-LIST-001
### 1.3 文档状态管理
文档状态流转遵循以下规范：
| 状态 | 说明 | 可转换状态 |
|------|------|-----------|
| **初稿** | 文档创建阶段，内容可能不完整 | 评审中、已发布 |
| **评审中** | 文档正在评审，内容基本完整 | 已发布、初稿 |
| **已发布** | 文档已通过评审，可正式使用 | 已归档 |
| **已归档** | 文档已过时，仅作历史记录 | - |
**状态更新规则**：
1. 新建文档默认状态为"初稿"
2. 文档内容完整后，提交评审，状态更新为"评审中"
3. 评审通过后，状态更新为"已发布"
4. 文档被新版本替代后，旧版本状态更新为"已归档"
---
## 二、产品需求文档（PRD）
### 2.1 基础版PRD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-PRD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版产品设计文档 |
| 文件路径 | [docs/product/PRD-基础版产品设计文档.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/product/PRD-基础版产品设计文档.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 基础版 |
**内容概要**:
- 产品概述和定位
- 功能模块（会员管理、预约管理、签到管理、数据统计、系统管理）
- 用户故事和验收标准
- 业务规则和约束
**依赖文档**:
- GYM-B-HLD-BASIC-001
- GYM-T-ILD-BASIC-001
### 2.2 付费订阅版PRD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-PRD-SUBSCRIPTION-001 |
| 文档名称 | 健身房管理系统付费订阅版产品设计文档 |
| 文件路径 | [docs/product/PRD-付费订阅版产品设计文档.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/product/PRD-付费订阅版产品设计文档.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 付费订阅版 |
**内容概要**:
- 产品概述和定位
- 订阅模块体系（业务扩展类、体验升级类、营销增长类、数据智能类）
- 功能模块和用户故事
- 业务规则和验收标准
**依赖文档**:
- GYM-B-HLD-SUBSCRIPTION-001
- GYM-T-ILD-SUBSCRIPTION-001
---
## 三、业务概要设计文档（B-HLD）
### 3.1 基础版B-HLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-B-HLD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版业务概要设计文档 |
| 文件路径 | [docs/design/B-HLD-基础版-业务概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/B-HLD-基础版-业务概要设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 基础版 |
**内容概要**:
- 业务概述和用户角色
- 业务范围和核心业务流程
- 业务规则和异常处理（包含规则+示例格式）
- 用户角色和权限
**参考文档**:
- GYM-PRD-BASIC-001
**被参考文档**:
- GYM-B-LLD-BASIC-001
- GYM-T-ILD-BASIC-001
### 3.2 付费订阅版B-HLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-B-HLD-SUBSCRIPTION-001 |
| 文档名称 | 健身房管理系统付费订阅版业务概要设计文档 |
| 文件路径 | [docs/design/B-HLD-付费订阅版-业务概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/B-HLD-付费订阅版-业务概要设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 付费订阅版 |
**内容概要**:
- 业务概述和用户角色
- 业务范围和核心业务流程
- 订阅流程和配置继承流程
- 业务规则和异常处理
**参考文档**:
- GYM-PRD-SUBSCRIPTION-001
**被参考文档**:
- GYM-B-LLD-SUBSCRIPTION-001
- GYM-T-ILD-SUBSCRIPTION-001
---
## 四、业务详细设计文档（B-LLD）
### 4.1 基础版B-LLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-B-LLD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版业务详细设计文档 |
| 文件路径 | [docs/design/B-LLD-基础版-业务详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/B-LLD-基础版-业务详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 基础版 |
**内容概要**:
- 详细业务流程
- 业务数据流转
- 业务指标
- 业务规则补充
**参考文档**:
- GYM-PRD-BASIC-001
- GYM-B-HLD-BASIC-001
**被参考文档**:
- GYM-T-ILD-BASIC-001
### 4.2 付费订阅版B-LLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-B-LLD-SUBSCRIPTION-001 |
| 文档名称 | 健身房管理系统付费订阅版业务详细设计文档 |
| 文件路径 | [docs/design/B-LLD-付费订阅版-业务详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/B-LLD-付费订阅版-业务详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 付费订阅版 |
**内容概要**:
- 详细业务流程
- 业务数据流转
- 业务指标
- 业务规则补充
**参考文档**:
- GYM-PRD-SUBSCRIPTION-001
- GYM-B-HLD-SUBSCRIPTION-001
**被参考文档**:
- GYM-T-ILD-SUBSCRIPTION-001
---
## 五、技术实现详细设计文档（T-ILD）
### 5.1 基础版T-ILD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-T-ILD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版技术实现详细设计文档 |
| 文件路径 | [docs/design/T-ILD-基础版-技术实现详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/T-ILD-基础版-技术实现详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 基础版 |
**内容概要**:
- 架构决策和技术选型
- 系统架构设计（分层架构、模块化设计）
- 响应式编程架构
- 数据库设计（表结构、索引）
- API接口设计
- 部署架构
- 监控与运维
- 安全设计
- 测试策略
**参考文档**:
- GYM-PRD-BASIC-001
- GYM-B-HLD-BASIC-001
- GYM-B-LLD-BASIC-001
### 5.2 付费订阅版T-ILD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-T-ILD-SUBSCRIPTION-001 |
| 文档名称 | 健身房管理系统付费订阅版技术实现详细设计文档 |
| 文件路径 | [docs/design/T-ILD-付费订阅版-技术实现详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/T-ILD-付费订阅版-技术实现详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 已发布 |
| 适用版本 | 付费订阅版 |
**内容概要**:
- 系统架构设计（分层架构、模块化设计）
- 订阅与配置模块设计
- 业务扩展模块设计（私教管理、场地预约、线上课程）
- 体验升级模块设计（人脸识别签到、NFC签到、智能储物柜）
- 营销增长模块设计（营销活动、会员推荐奖励、会员互动社区、智能获客工具）
- 数据智能模块设计（营销精算模型、自定义促销预测、高级数据分析、智能体测数据联动）
**参考文档**:
- GYM-PRD-SUBSCRIPTION-001
- GYM-B-HLD-SUBSCRIPTION-001
- GYM-B-LLD-SUBSCRIPTION-001
---
---
## 五、技术专题文档
### 5.1 数据库设计文档
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-DB-DESIGN-001 |
| 文档名称 | 健身房管理系统数据库设计文档 |
| 文件路径 | [docs/design/technical/DB-数据库设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/technical/DB-数据库设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 正式发布 |
**内容概要**:
- 数据库架构设计（多租户架构、分库分表策略）
- 核心表结构设计（会员域、预约域、订阅域）
- 索引设计优化
- 数据迁移策略（Flyway 版本化管理）
- 性能优化（查询优化、连接池配置）
- 安全设计（数据加密、数据脱敏）
**参考文档**:
- GYM-T-ILD-BASIC-001
- GYM-T-ILD-SUBSCRIPTION-001
- PostgreSQL 官方文档
### 5.2 API 接口设计规范
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-API-SPEC-001 |
| 文档名称 | 健身房管理系统 API 接口设计规范 |
| 文件路径 | [docs/design/technical/API-接口设计规范.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/technical/API-接口设计规范.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 正式发布 |
**内容概要**:
- API 设计原则（RESTful 风格、版本控制、响应式 API 设计）
- API 响应格式（标准响应、列表响应、错误响应）
- API 接口分类（会员管理、预约管理、订阅管理）
- 错误处理（错误码规范、全局异常处理、参数验证）
- 安全设计（JWT 认证、RBAC 授权、限流）
- API 文档（OpenAPI 规范、Swagger UI）
- 性能优化（游标分页、字段过滤、缓存策略）
**参考文档**:
- GYM-T-ILD-BASIC-001
- GYM-T-ILD-SUBSCRIPTION-001
- RESTful API 最佳实践
- OpenAPI 3.0 规范
### 5.3 安全设计文档
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-SEC-DESIGN-001 |
| 文档名称 | 健身房管理系统安全设计文档 |
| 文件路径 | [docs/design/technical/SEC-安全设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/technical/SEC-安全设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 正式发布 |
**内容概要**:
- 安全架构设计（安全分层、安全原则）
- 认证与授权（JWT Token 认证、RBAC 授权、数据权限隔离）
- 数据安全（数据加密、数据脱敏、数据备份）
- 网络安全（HTTPS 强制、CORS 配置、限流与防 DDOS）
- 输入验证与输出编码（输入验证、SQL 注入防护、XSS 防护）
- 安全审计（审计日志、日志存储）
- 安全监控（监控指标、告警规则）
- 合规性（GDPR 合规、等保 2.0 合规）
**参考文档**:
- GYM-T-ILD-BASIC-001
- GYM-T-ILD-SUBSCRIPTION-001
- OWASP Top 10 安全规范
- Spring Security 官方文档
- GDPR 数据保护条例
## 六、高层设计文档（HLD）
### 6.1 技术架构 HLD（已归档）
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-HLD-TECH-001 |
| 文档名称 | 健身房管理系统技术架构设计文档 |
| 文件路径 | [docs/design/HLD-技术架构设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/HLD-技术架构设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | **已归档**（内容已整合到 T-ILD 文档） |
| 归档日期 | 2026-03-08 |
| 归档原因 | 文档架构优化，技术架构内容整合到 T-ILD 文档体系 |
**参考文档**:
- GYM-T-ILD-BASIC-001
- GYM-T-ILD-SUBSCRIPTION-001
### 6.2 基础版 HLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-HLD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版业务概要设计文档 |
| 文件路径 | [docs/design/HLD-基础版系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/HLD-基础版系统概要设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已归档 |
| 适用版本 | 基础版 |
**注意**: 本文档已被 B-HLD 和 T-ILD 文档替代，仅作历史记录。
**内容概要**:
- 业务概述和用户角色
- 业务范围和核心业务流程
- 业务规则和异常处理
- 系统架构设计
**参考文档**:
- GYM-PRD-BASIC-001
**被参考文档**:
- GYM-B-HLD-BASIC-001（已替代）
- GYM-B-LLD-BASIC-001（已替代）
- GYM-T-ILD-BASIC-001（已替代）
### 6.3 付费订阅版 HLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-HLD-SUBSCRIPTION-001 |
| 文档名称 | 健身房管理系统付费订阅版业务概要设计文档 |
| 文件路径 | [docs/design/HLD-付费订阅版系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/HLD-付费订阅版系统概要设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已归档 |
| 适用版本 | 付费订阅版 |
**注意**: 本文档已被 B-HLD 和 T-ILD 文档替代，仅作历史记录。
**内容概要**:
- 业务概述和用户角色
- 业务范围和核心业务流程
- 订阅流程和配置继承流程
- 业务规则和异常处理
**参考文档**:
- GYM-PRD-SUBSCRIPTION-001
**被参考文档**:
- GYM-B-HLD-SUBSCRIPTION-001（已替代）
- GYM-B-LLD-SUBSCRIPTION-001（已替代）
- GYM-T-ILD-SUBSCRIPTION-001（已替代）
---
## 七、详细设计文档（LLD）
### 7.1 基础版 LLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-LLD-BASIC-001 |
| 文档名称 | 健身房管理系统基础版详细设计文档 |
| 文件路径 | [docs/design/LLD-基础版系统详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/LLD-基础版系统详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已归档 |
| 适用版本 | 基础版 |
**注意**: 本文档已被T-ILD文档替代，仅作历史记录。
**内容概要**:
- 系统架构设计（分层架构、模块化设计）
- 技术架构（前端、后端、部署）
- 模块设计（会员模块、预约模块、签到模块、数据模块、系统模块）
- 数据模型设计
- API设计
- 业务逻辑实现
**参考文档**:
- GYM-PRD-BASIC-001
- GYM-HLD-BASIC-001
**被参考文档**:
- GYM-T-ILD-BASIC-001（已替代）
### 7.2 付费订阅版 LLD
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-LLD-SUBSCRIPTION-002 |
| 文档名称 | 健身房管理系统付费订阅版详细设计文档 |
| 文件路径 | [docs/design/LLD-付费订阅版系统详细设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/LLD-付费订阅版系统详细设计.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 已归档 |
| 适用版本 | 付费订阅版 |
**注意**: 本文档已被T-ILD文档替代，仅作历史记录。
**内容概要**:
- 系统架构设计（分层架构、模块化设计）
- 订阅与配置模块设计
- 业务扩展模块设计（私教管理、场地预约、线上课程）
- 体验升级模块设计（人脸识别签到、NFC签到、智能储物柜）
- 营销增长模块设计（营销活动、会员推荐奖励、会员互动社区、智能获客工具）
- 数据智能模块设计（营销精算模型、自定义促销预测、高级数据分析、智能体测数据联动）
**参考文档**:
- GYM-PRD-SUBSCRIPTION-001
- GYM-HLD-SUBSCRIPTION-001
**被参考文档**:
- GYM-T-ILD-SUBSCRIPTION-001（已替代）
---
## 九、计划文档
### 9.1 系统设计计划
| 属性 | 值 |
|------|-----|
| 文档编号 | - |
| 文档名称 | 健身房管理系统设计 |
| 文件路径 | [docs/plans/2026-02-28-gym-manage-design.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/plans/2026-02-28-gym-manage-design.md) |
| 版本 | - |
| 日期 | 2026-02-28 |
| 作者 | - |
| 状态 | 需更新 |
**内容概要**:
- 系统设计方案
- 功能模块设计
- 数据模型设计
- 接口设计
**注意**: 本文档包含2024年的过时日期，需要更新为2026年。
---
## 十、客户文档
### 10.1 产品介绍手册
| 属性 | 值 |
|------|-----|
| 文档编号 | - |
| 文档名称 | 健身房管理系统产品介绍手册 |
| 文件路径 | [docs/customer/产品介绍手册.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/customer/产品介绍手册.md) |
| 版本 | - |
| 日期 | - |
| 作者 | - |
| 状态 | 正常 |
**内容概要**:
- 产品介绍
- 功能特性
- 版本对比
- 价格信息（已替换为¥XXX）
---
## 十一、归档文档
### 11.1 历史PRD文档
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-PRD-001 |
| 文档名称 | 健身房管理系统产品设计文档 |
| 文件路径 | [docs/archive/v1.0/PRD-产品设计文档.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/archive/v1.0/PRD-产品设计文档.md) |
| 版本 | - |
| 日期 | - |
| 作者 | - |
| 状态 | 归档 |
**注意**: 本文档为历史版本，已被基础版和付费订阅版PRD替代。
### 11.2 历史HLD文档
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-HLD-001 |
| 文档名称 | 健身房管理系统业务概要设计文档 |
| 文件路径 | [docs/archive/v1.0/HLD-系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/archive/v1.0/HLD-系统概要设计.md) |
| 版本 | - |
| 日期 | - |
| 作者 | - |
| 状态 | 归档 |
**注意**: 本文档为历史版本，已被基础版和付费订阅版HLD替代。
---
## 十二、部署运维文档
### 12.1 部署运维指南
| 属性 | 值 |
|------|-----|
| 文档编号 | - |
| 文档名称 | 部署运维文档 |
| 文件路径 | [docs/design/OPS-部署运维文档.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/OPS-部署运维文档.md) |
| 版本 | - |
| 日期 | - |
| 作者 | - |
| 状态 | 需更新 |
**内容概要**:
- 系统部署
- 运维管理
- 监控告警
- 备份恢复
**注意**: 本文档包含2024年的过时日期，需要更新为当前日期。
---
## 十三、审查和管理文档
### 13.1 文档审查报告
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-DOC-REVIEW-001 |
| 文档名称 | 健身房管理系统文档审查报告 |
| 文件路径 | [docs/文档审查报告.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/文档审查报告.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-05 |
| 作者 | 张翔 |
| 状态 | 完成 |
**内容概要**:
- 文档审查概述
- 各类文档审查结果
- 文档间引用关系分析
- 过时/冗余内容识别
- 改进建议和行动计划
### 13.2 文档清单
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-DOC-LIST-001 |
| 文档名称 | 健身房管理系统文档清单 |
| 文件路径 | [docs/文档清单.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/文档清单.md) |
| 版本 | v1.6 |
| 日期 | 2026-03-08 |
| 作者 | 张翔 |
| 状态 | 完成 |
**内容概要**:
- 所有文档的完整列表
- 文档分类和编号规则
- 文档依赖关系
- 文档状态和注意事项
### 13.3 文档管理规范
| 属性 | 值 |
|------|-----|
| 文档编号 | GYM-DOC-STANDARD-001 |
| 文档名称 | 健身房管理系统文档管理规范 |
| 文件路径 | [docs/文档管理规范.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/文档管理规范.md) |
| 版本 | v1.0 |
| 日期 | 2026-03-04 |
| 作者 | 张翔 |
| 状态 | 正式发布 |
**内容概要**:
- 文档编号规则
- 文档版本管理
- 文档引用规范
- 文档更新规范
- 文档审查机制
- 文档归档规范
- 文档质量标准
- 文档安全规范
- 文档协作规范
---
## 十四、文档依赖关系图
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 文档依赖关系 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 产品需求文档（PRD） │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ GYM-PRD-BASIC-001 ──────┐ │ │
│ │ GYM-PRD-SUBSCRIPTION-001 ─┼───→ 业务概要设计文档（B-HLD） │ │
│ └───────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 业务概要设计文档（B-HLD） │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ GYM-B-HLD-BASIC-001 ───────┐ │ │
│ │ GYM-B-HLD-SUBSCRIPTION-001 ─┼───→ 业务详细设计文档（B-LLD） │ │
│ └────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 业务详细设计文档（B-LLD） │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ GYM-B-LLD-BASIC-001 ───────┐ │ │
│ │ GYM-B-LLD-SUBSCRIPTION-001 ─┼───→ 技术实现详细设计文档（T-ILD）│ │
│ └────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 技术实现详细设计文档（T-ILD） │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ GYM-T-ILD-BASIC-001 │ │
│ │ GYM-T-ILD-SUBSCRIPTION-001 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 十五、文档状态汇总
| 文档类型 | 总数 | 已发布 | 需更新 | 归档 |
|---------|------|--------|--------|------|
| 产品需求文档（PRD） | 2 | 2 | 0 | 0 |
| 业务概要设计文档（B-HLD） | 2 | 2 | 0 | 0 |
| 业务详细设计文档（B-LLD） | 2 | 2 | 0 | 0 |
| 技术实现详细设计文档（T-ILD） | 2 | 2 | 0 | 0 |
| 高层设计文档（HLD） | 2 | 0 | 0 | 2 |
| 详细设计文档（LLD） | 2 | 0 | 0 | 2 |
| 计划文档 | 1 | 1 | 0 | 0 |
| 客户文档 | 1 | 1 | 0 | 0 |
| 归档文档 | 2 | 0 | 0 | 2 |
| 部署运维文档 | 1 | 0 | 1 | 0 |
| 审查和管理文档 | 3 | 3 | 0 | 0 |
| **总计** | **21** | **16** | **1** | **4** |
---
## 十六、注意事项
### 15.1 文档管理规范
已创建[文档管理规范](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/文档管理规范.md)，包含：
- 文档编号规则
- 文档版本管理
- 文档引用规范
- 文档更新规范
- 文档审查机制
- 文档归档规范
- 文档质量标准
- 文档安全规范
- 文档协作规范
### 15.2 文档架构优化
已完成文档架构优化，实现业务设计和技术设计分离：
1. **新增BLD文档** ✅ 已完成
- 创建GYM-BLD-BASIC-001业务设计文档
- 包含完整的业务流程、业务规则（规则+示例格式）
- 聚焦业务层面，便于产品经理和业务分析师使用
2. **新增TLD文档** ✅ 已完成
- 创建GYM-TLD-BASIC-001技术设计文档
- 包含系统架构、技术选型、数据库设计、API设计
- 聚焦技术层面，便于架构师和开发工程师使用
3. **归档HLD文档** ✅ 已完成
- 将GYM-HLD-BASIC-001标记为已归档
- 保留历史记录，但不再作为主要参考文档
4. **更新文档清单** ✅ 已完成
- 添加BLD和TLD文档条目
- 更新文档分类和编号规则
- 更新文档依赖关系图
- 更新文档状态汇总
### 15.3 已完成的修复
所有P0和P1优先级的修复任务已完成：
1. **文档引用关系修复** ✅ 已完成
- ~~移除对GYM-PRD-001、GYM-HLD-001、GYM-LLD-000的引用~~
- ~~更新为正确的文档编号~~
- **修复说明**：经核实，核心文档（PRD、HLD、LLD）中的引用关系均为正确编号，无需修改。文档审查报告中的引用关系表格已更新为正确状态。
2. **过时日期更新** ✅ 已完成
- ~~计划文档：2024年日期更新为2026年~~
- ~~部署运维文档：2024年日期更新为2026年~~
- **修复说明**：经核实，计划文档和部署运维文档中不存在2024年日期，文档日期均为2026年，无需修改。
4. **文档状态不一致修复** ✅ 已完成
- ~~核心文档状态标记为"初稿"~~
- **修复说明**：已将所有核心文档（PRD、HLD、LLD）的状态从"初稿"更新为"已发布"，与文档清单保持一致。
5. **UI模版定制功能补充** ✅ 已完成
- ~~PRD-基础版缺少UI模版定制功能描述~~
- **修复说明**：已在PRD-基础版中补充完整的UI模版定制功能模块，包括品牌定制、布局调整、预设模板、配置历史和可视化配置器五个子模块，与HLD-基础版保持一致。
6. **产品介绍手册定价信息更新** ✅ 已完成
- ~~产品介绍手册中定价信息为占位符¥XXX~~
- **修复说明**：已将产品介绍手册中所有定价占位符替换为具体定价信息，包括基础版¥299/月、各订阅模块定价（¥199-¥499/月）以及所有套餐的具体价格。
### 15.4 归档文档
以下文档已归档，仅供参考：
- [PRD-产品设计文档.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/archive/v1.0/PRD-产品设计文档.md) (GYM-PRD-001)
- [HLD-基础版系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/design/HLD-基础版系统概要设计.md) (GYM-HLD-BASIC-001) - 已被BLD和TLD替代
- [HLD-系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/archive/v1.0/HLD-系统概要设计.md) (GYM-HLD-001)
- [HLD-系统概要设计.md](file:///Users/zhangxiang/Codes/Novalon/gym-manage/docs/archive/v1.0/HLD-系统概要设计.md) (GYM-HLD-001)
---
## 十四、文档维护建议
1. **定期审查**: 每季度进行一次文档审查，确保文档与项目状态一致
2. **版本管理**: 严格按照版本号规则进行文档版本管理
3. **引用更新**: 文档更新时，同步更新所有引用关系
4. **日期检查**: 定期检查文档中的日期信息，确保时效性
5. **清单维护**: 文档增删改时，及时更新本文档清单
---
**清单结束**