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