295 lines
11 KiB
Markdown
295 lines
11 KiB
Markdown
# 教练业绩统计设计文档
|
||
|
||
**版本**: v2.0
|
||
**日期**: 2026-07-26
|
||
**状态**: 已确定
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
教练业绩统计为体育馆管理系统提供按教练维度的绩效评估，帮助管理者横向对比教练表现、激励教练提升教学质量。
|
||
|
||
### 核心能力
|
||
|
||
- **教练排行榜**：按综合评分降序排列所有教练
|
||
- **教练详情**：查看单个教练的六项指标详情
|
||
- **自查看板**：教练查看自己的业绩表现
|
||
|
||
---
|
||
|
||
## 二、指标体系
|
||
|
||
### 2.1 六项指标总览
|
||
|
||
| 序号 | 指标 | 类型 | 含义 | 数据源 |
|
||
|------|------|------|------|--------|
|
||
| 1 | 授课量 | 基础指标 | 统计周期内已完成的团课数量 | `group_course.status IN ('2','6')` |
|
||
| 2 | 出席人次 | 基础指标 | 学员实际参与的人次 | `group_course_booking.status IN ('2','4','5')` |
|
||
| 3 | 总预约数 | 基础指标 | 学员预约该教练课程的次数（仅已预约状态） | `group_course_booking.status = '0'` |
|
||
| 4 | 出勤率 | 派生指标 | 出席人次 / 总预约数 * 100 | 指标2 + 指标3 |
|
||
| 5 | 满员率 | 派生指标 | 各课程出席人数/满员上限的平均值 | `group_course.max_members` + 指标2明细 |
|
||
| 6 | 违规次数 | 基础指标 | 统计周期内违规记录数 | `coach_violation` |
|
||
| 7 | 综合评分 | 派生指标 | 加权综合得分（详见第三章） | 指标1-6 |
|
||
|
||
### 2.2 指标口径详解
|
||
|
||
#### 授课量
|
||
|
||
```
|
||
SELECT coach_id, COUNT(*) FROM group_course
|
||
WHERE end_time >= :startTime AND end_time < :endTime
|
||
AND status IN ('2', '6') AND deleted_at IS NULL
|
||
GROUP BY coach_id
|
||
```
|
||
|
||
- **status='2'**: 教练手动结课
|
||
- **status='6'**: 系统自动结课
|
||
- **排除**: 已取消(status='1')、教练缺席(status='5')的课程
|
||
|
||
#### 出席人次
|
||
|
||
```
|
||
SELECT gc.coach_id, COUNT(*) FROM group_course_booking b
|
||
INNER JOIN group_course gc ON b.course_id = gc.id
|
||
WHERE b.status IN ('2', '4', '5') AND b.deleted_at IS NULL
|
||
AND gc.deleted_at IS NULL
|
||
AND gc.end_time >= :startTime AND gc.end_time < :endTime
|
||
GROUP BY gc.coach_id
|
||
```
|
||
|
||
- **status='2'**: 已出席 — 学员正常到课
|
||
- **status='4'**: 教练缺席 — 教练未到，学员仍需记录
|
||
- **status='5'**: 迟到 — 学员迟到但仍到场参与
|
||
|
||
> **设计意图**: 教练缺席和迟到时，学员仍到达了现场（或尝试参与），责任在教练而非学员，故计入出席人次。学员无故缺席(status='3')不计入，因其既非教练功劳也非教练责任。
|
||
|
||
#### 总预约数
|
||
|
||
```
|
||
SELECT gc.coach_id, COUNT(*) FROM group_course_booking b
|
||
INNER JOIN group_course gc ON b.course_id = gc.id
|
||
WHERE b.status = '0' AND b.deleted_at IS NULL
|
||
AND gc.deleted_at IS NULL
|
||
AND gc.end_time >= :startTime AND gc.end_time < :endTime
|
||
GROUP BY gc.coach_id
|
||
```
|
||
|
||
- **仅 status='0'（已预约）**: 作为出勤率分母，表示"承诺来上课的学员"。
|
||
|
||
#### 满员率
|
||
|
||
```
|
||
SELECT gc.coach_id, gc.max_members, COUNT(b.id) AS attended
|
||
FROM group_course gc
|
||
LEFT JOIN group_course_booking b ON gc.id = b.course_id
|
||
AND b.status IN ('2','4','5') AND b.deleted_at IS NULL
|
||
WHERE gc.end_time >= :startTime AND gc.end_time < :endTime
|
||
AND gc.status IN ('2', '6') AND gc.deleted_at IS NULL
|
||
GROUP BY gc.coach_id, gc.id, gc.max_members
|
||
```
|
||
|
||
- 对每个已完成课程，计算 `出席人数 / max_members`
|
||
- 所有课程的比值取平均值
|
||
- `max_members = 0` 的课程被跳过（除零防御）
|
||
|
||
#### 违规次数
|
||
|
||
```
|
||
SELECT coach_id, COUNT(*) FROM coach_violation
|
||
WHERE violation_time >= :startTime AND violation_time < :endTime
|
||
AND deleted_at IS NULL
|
||
GROUP BY coach_id
|
||
```
|
||
|
||
- 违规类型: `COACH_LATE`（迟到）、`COACH_ABSENT`（缺席）、`NOT_MANUAL_END`（未手动结课）
|
||
|
||
#### 时间基准
|
||
|
||
所有指标均基于 `group_course.end_time` 过滤时间范围。跨月课程归属于结束时间所在的月份。
|
||
|
||
---
|
||
|
||
## 三、综合评分算法
|
||
|
||
### 3.1 最终公式
|
||
|
||
```
|
||
综合评分 = 授课量归一化分 * 0.35
|
||
+ 出勤率 * 0.25
|
||
+ 满员率 * 0.25
|
||
+ 违规分 * 0.15
|
||
```
|
||
|
||
### 3.2 授课量归一化：百分位排名法（方案 B）
|
||
|
||
对于教练数为 N 的集合：
|
||
|
||
1. 将所有教练按授课量升序排列
|
||
2. 统计授课量严格小于当前教练的教练数 `C_fewer`
|
||
3. `normalizedCourses = C_fewer / (N - 1) * 100`（N=1 时取 100）
|
||
|
||
**示例**（4 位教练）:
|
||
|
||
| 教练 | 授课量 | 小于其的教练数 | 归一化分 |
|
||
|------|--------|---------------|---------|
|
||
| A | 20 | 3 | 100.0 |
|
||
| B | 15 | 2 | 66.7 |
|
||
| C | 10 | 1 | 33.3 |
|
||
| D | 5 | 0 | 0.0 |
|
||
|
||
**设计意图**: 百分位排名在"相对比较"和"公平性"之间取得平衡。授课量最大的教练得满分，最少的得 0 分，中间按排名线性分布。不受极端值影响——即使第一名开 100 节课、第二名只开 20 节，第二名的排名分数依然是 `2/3 * 100 ≈ 66.7`。
|
||
|
||
### 3.3 违规分：线性扣分法（方案 A）
|
||
|
||
```
|
||
violationScore = max(0, 100 - violations * 20)
|
||
```
|
||
|
||
| 违规次数 | 违规分 |
|
||
|----------|--------|
|
||
| 0 | 100 |
|
||
| 1 | 80 |
|
||
| 2 | 60 |
|
||
| 3 | 40 |
|
||
| 4 | 20 |
|
||
| 5+ | 0 |
|
||
|
||
**设计意图**: 线性扣分简单直观，每次违规固定扣 20 分，累计 5 次后清零。在 15% 的权重下，每次违规对综合评分的影响约为 `20 * 0.15 = 3 分`。
|
||
|
||
### 3.4 出勤率 & 满员率
|
||
|
||
这两项直接使用原始百分比（0-100），无需归一化——它们天然在 0-100 范围内且具有绝对含义。
|
||
|
||
```
|
||
出勤率 = 出席人次 / 总预约数 * 100（分母为 0 时取 0）
|
||
满员率 = avg(单个课程出席人数 / max_members) * 100（跳过 max_members=0 的课程）
|
||
```
|
||
|
||
---
|
||
|
||
## 四、方案选择记录
|
||
|
||
### 4.1 授课量归一化方案
|
||
|
||
| 方案 | 公式 | 优点 | 缺点 | 决定 |
|
||
|------|------|------|------|------|
|
||
| **B: 百分位排名** | `C_fewer / (N-1) * 100` | 直观、不受极端值影响 | 对教练总数敏感（N<3 时分布粗糙） | **采纳** |
|
||
| A: 最大值归一化 | `courses / max(courses) * 100` | 数学简洁 | 极端值压缩中游得分 | 初版方案，已废弃 |
|
||
| C: 对数归一化 | `ln(x+1)/ln(m+1)*100` | 压制极端值 | 解释性弱 | 已拒绝 |
|
||
| D: 固定目标 | `min(x/target*100, 100)` | 达标制、不互卷 | target 难校准 | 已拒绝 |
|
||
|
||
### 4.2 违规扣分方案
|
||
|
||
| 方案 | 公式 | 优点 | 缺点 | 决定 |
|
||
|------|------|------|------|------|
|
||
| **A: 线性扣分** | `max(0, 100 - v*20)` | 简单直白，每次等量扣分 | 多次违规后惩罚不再加剧 | **采纳** |
|
||
| B: 阶梯扣分 | 0→100, 1→70, 2→40, 3→10 | 首次违规惩罚重，有威慑力 | 第 1 到第 2 次差距 30 分，太激进 | 已拒绝 |
|
||
| C: 归一化扣分 | `(1 - v/max)*100` | 相对最差教练 | 依赖数据集，全员无违规则无意义 | 已拒绝 |
|
||
|
||
### 4.3 权重分配方案
|
||
|
||
| 方案 | 授课量 | 出勤率 | 满员率 | 违规 | 决定 |
|
||
|------|--------|--------|--------|------|------|
|
||
| **A: 轻违规** | 35% | 25% | 25% | 15% | **采纳** |
|
||
| B: 中违规 | 30% | 25% | 25% | 20% | 已拒绝 |
|
||
| C: 重违规 | 30% | 23% | 22% | 25% | 已拒绝 |
|
||
|
||
### 4.4 出勤率口径方案
|
||
|
||
| 方案 | 分子 | 分母 | 决定 |
|
||
|------|------|------|------|
|
||
| **当前** | status IN ('2','4','5') | status='0' | **采纳** |
|
||
| 初版 | status='2' | status!='1' | 已废弃 |
|
||
| 替代方案1 | status='2' | status IN ('0','2','3') | 已拒绝（无故缺席应排除） |
|
||
| 替代方案2 | status='2' | status IN ('0','2') | 已拒绝（不能区分取消预约） |
|
||
|
||
---
|
||
|
||
## 五、数据模型
|
||
|
||
### 5.1 API 响应模型
|
||
|
||
```java
|
||
public class CoachPerformance {
|
||
Long coachId; // 教练ID
|
||
String coachName; // 教练昵称
|
||
String avatar; // 头像URL
|
||
Long completedCourses; // 授课量
|
||
Long attendedStudents; // 出席人次
|
||
Long totalBookings; // 总预约数
|
||
Double attendanceRate; // 出勤率 (%)
|
||
Double fillRate; // 满员率 (%)
|
||
Long violationCount; // 违规次数
|
||
Double compositeScore; // 综合评分
|
||
}
|
||
```
|
||
|
||
### 5.2 API 接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/datacount/coach-performance/ranking` | 全部教练业绩排行榜 |
|
||
| GET | `/api/datacount/coach-performance/{coachId}` | 单个教练业绩详情 |
|
||
| GET | `/api/datacount/coach-performance/mine?coachId=` | 教练自查看板 |
|
||
|
||
**查询参数**: `statType`, `periodType`（DAY/WEEK/MONTH/LAST_30_DAYS/LAST_90_DAYS/YEAR）, `startTime`, `endTime`
|
||
|
||
---
|
||
|
||
## 六、代码架构
|
||
|
||
```
|
||
CoachPerformanceHandler ── Reactive Router Function，解析请求
|
||
│
|
||
IDataStatisticsService ── 接口定义
|
||
│
|
||
DataStatisticsServiceImpl ── 6 并行查询 + 聚合计算
|
||
│
|
||
DataStatisticsDao ── DatabaseClient SQL 聚合
|
||
│
|
||
┌───┼───┬───┬───┬───┐
|
||
▼ ▼ ▼ ▼ ▼ ▼
|
||
sys_user group_course group_course_booking coach_violation
|
||
```
|
||
|
||
### 查询执行流程
|
||
|
||
```
|
||
1. Flux: getAllCoachesWithInfo() ─→ Map<coachId, 基本信息>
|
||
2. Flux: countCompletedCoursesByCoach() ─→ Map<coachId, 授课量> ┐
|
||
3. Flux: countAttendedStudentsByCoach() ─→ Map<coachId, 出席人次> │
|
||
4. Flux: countTotalBookingsByCoach() ─→ Map<coachId, 总预约数> ├─ Mono.zip
|
||
5. Flux: getFillRateDetailByCoach() ─→ Map<coachId, List<明细>> │
|
||
6. Flux: countViolationsByCoach() ─→ Map<coachId, 违规次数> ┘
|
||
│
|
||
flatMapMany: 逐教练计算指标
|
||
│
|
||
sorted: 按综合评分降序
|
||
│
|
||
Flux<CoachPerformance>
|
||
```
|
||
|
||
---
|
||
|
||
## 七、边界情况处理
|
||
|
||
| 场景 | 行为 |
|
||
|------|------|
|
||
| 教练无任何已完成课程 | 所有指标为 0，综合评分 = 0 + 0 + 0 + 15 = **15**（违规分满分 100 * 0.15） |
|
||
| 教练有课程但无人预约 | 授课量 > 0，出勤率/满员率 = 0 |
|
||
| 课程 max_members = 0 | 该课程跳过，不参与满员率计算 |
|
||
| 仅有 1 位教练 | 百分位排名直接返回 100 |
|
||
| 所有教练授课量相同 | 所有教练 `C_fewer = 0`，授课量归一化分均为 0 |
|
||
| 跨月课程 | 以 end_time 所在月份归类 |
|
||
| 查询单个教练不存在 | 返回零值 `CoachPerformance`，coachName="未知教练" |
|
||
|
||
---
|
||
|
||
## 八、变更历史
|
||
|
||
| 日期 | 版本 | 变更内容 |
|
||
|------|------|---------|
|
||
| 2026-07-22 | v1.0 | 初版：最大值归一化 + 三维度评分（4:3:3），违规仅展示 |
|
||
| 2026-07-26 | v2.0 | 时间基准改为 end_time；出席人次扩展为(2,4,5)；出勤率分母改为仅 status='0'；授课量归一化改为百分位排名；违规纳入综合评分(权重 15%)；满员率防御除零 |
|