文档指标：补充数据分析业务指标口径确认清单

docs/requirements/数据分析指标口径确认清单.md

@@ -0,0 +1,40 @@
+# SYFJGYD学员管理系统 - 数据分析业务指标口径确认清单 (Business Metric Definition Matrix)
+
+> **版本**：V1.0  
+> **制定日期**：2026-09-20  
+> **适用范围**：数据分析与可视化 V1（管理驾驶舱、考勤专题分析、学员360画像）  
+> **原则**：基于正式数据库真实结构，严禁制造 Mock 数据，客观展示事实，业务定义未定指标严格标注待确认。
+
+---
+
+## 一、指标口径确认矩阵 (Metric Definition Matrix)
+
+| 序号 | 业务指标 | 当前系统事实 (Current System Truth) | 当前建议口径 (Proposed Baseline) | 是否阻塞 V1 | 是否需甲方确认 |
+| :--- | :--- | :--- | :--- | :---: | :---: |
+| 1 | **当前参训人数** | `train_student_enrollment` 仅记录学员在各计划下的报名/报到流水；计划处于“进行中”且学员已报到的定义目前尚未在业务上达成共识。 | 处于执行中（`status='in_progress'`）培训计划且学员状态为已报到（`status='1'`）的去重学员人数。<br>*V1处置：暂不作为驾驶舱核心KPI，改用客观明确的“累计参训人数”与“累计报到人数”。* | **否** | **是** |
+| 2 | **报到率口径** | 学员报名表中 `status` 包含待报到、已报到等状态。但分母是“核定计划名额”还是“实际报名总人次”，以及未报到学员撤销报名是否扣除分母未定。 | 报到率 = 累计报到人次（`status='1'`） / 累计报名参训人次（`train_student_enrollment` 总行数）。<br>*V1处置：驾驶舱采用“参训人数 vs 报到人数”绝对值对比柱状图，直观展示事实，避免固化争议比率。* | **否** | **是** |
+| 3 | **出勤率分母** | 考勤流水 `train_lesson_attendance` 仅在打卡行为发生时产生行记录。若学员缺席未打卡，流水中无行记录，因此不能用流水记录总数作为分母。 | 出勤率 = 正常出勤人次（`status=1`） / 应到人次（已开课课次所属班级的学员人次总和）。<br>*V1处置：代码与界面均统一明确标注 `BUSINESS_METRIC_DEFINITION_PENDING_CONFIRMATION`，禁止以已有流水总数作为分母。* | **否** | **是** |
+| 4 | **无签到记录归类** | 考勤状态字典定义：`0=缺勤, 1=正常, 2=迟到, 3=早退, 4=请假`。无打卡流水的记录在数据库中为空。 | 课次已开课（`start_time <= CURRENT_TIMESTAMP`）且无任何签到流水的应到人次，独立归类为“无签到记录”（No Record）。<br>*V1处置：严禁自动视作 status=0 明确缺勤，直至教务人员核实补录。* | **否** | **是** |
+| 5 | **成绩总评方式** | 历史遗留表 `train_score_info` 已下线，当前表 `train_student_score` 记录为 0 行。尚未建立理论、实操及出勤学时的加权综合评价配置机制。 | 课程最终成绩为卷面综合得分；培训计划总评按教学大纲设定的各课程学时或学分权重加权平均。<br>*V1处置：严格不展示成绩分析大屏；学员画像展示“暂无成绩数据”客观占位提示。* | **否** | **是** |
+| 6 | **及格线** | 数据库中无统一的及格阈值字典，铁路系统各专业工种（如动车组司机、调度员与普通乘务）合格分数线存在差异。 | 百分制默认以 60 分为及格线；后续根据培训计划和课程类别配置独立的合格标准线。 | **否** | **是** |
+| 7 | **优秀线** | 系统中无优秀/良好标准配置。 | 推荐以 90 分（或各科目均在 85 分以上且无异常考勤）作为优秀线，优秀学员比例建议控制在 15% 以内。 | **否** | **是** |
+| 8 | **成绩区间** | 数据库无成绩分布区间划分配置。 | 推荐标准区间：`[0, 60) 不及格`、`[60, 70) 及格`、`[70, 80) 中等`、`[80, 90) 良好`、`[90, 100] 优秀`；支持五级等级制（优、良、中、及格、不及格）映射。 | **否** | **是** |
+| 9 | **画像标签规则** | 原学员个人中心存在基于伪数据或未统一度量衡的雷达图评价，缺乏实际可解释性与数据依据。 | 建立基于客观行为事件的标签机制（例如：“全勤学员”=出勤率100%、“预警学员”=缺勤/迟到累计≥3次、“在宿学员”=拥有有效床位分配记录），严禁黑盒算法生成 AI 综合能力分。<br>*V1处置：个人中心彻底下线伪雷达图，替换为客观指标卡；360画像展示全景客观事实。* | **否** | **是** |
+
+---
+
+## 二、V1 实施策略与系统边界说明
+
+1. **管理驾驶舱 KPI 选型**：
+   - 纳入：学员总数、教师总数、课程总数、培训计划总数、累计排课课次、累计参训人数、累计报到人数、当前在宿人数。
+   - 计划状态明确分类：未开始、进行中、已结束、已取消。
+   - 场地运营分析：客观采用“使用频次”与“累计课时”指标，杜绝在缺少总运营可用工时分母时滥用“教室利用率”。
+
+2. **考勤专题指标防范**：
+   - 严格在后端 SQL 与 Service 实现聚合，分母以计划参训名单与已开课课次笛卡尔积算出真实“应到人次”。
+   - 严格区分“明确缺勤”（已有教务或系统标记 status=0）与“无签到记录”（未产生打卡流水）。
+
+3. **学员 360 画像与雷达图整改**：
+   - 全面移除原学员个人中心（`/train/me/student`）中无数据支撑的四维雷达图（出勤纪律、理论成绩、实操成绩、学时评价）。
+   - 替换为基于客观事实的“打卡出勤”、“培训履历”、“在宿床位”、“成绩状态”、“自主学习状态”指标卡。
+   - 敏感信息（身份证号等）严格脱敏，不回传明文。