2026-05-12

training/workspace/specs/V2-StatisticsCenter.md

@@ -0,0 +1,554 @@
+# V2 统计报表中心 - 产品需求文档
+
+> 版本：V2.0.0-draft
+> 作者：Product Agent
+> 日期：2026-02-04
+> 状态：待评审
+
+---
+
+## 一、功能概述
+
+### 1.1 背景与目标
+
+**背景**：V1 版本完成了培训系统的基础功能，但管理层无法量化培训效果，讲师无法追踪学员学习情况，缺乏数据支撑决策。
+
+**目标**：构建统计报表中心，让培训效果可量化、可追踪、可对比。
+
+### 1.2 目标用户
+
+| 角色 | 核心诉求 |
+|------|----------|
+| **管理员** | 全局数据概览，跨部门对比，发现问题部门 |
+| **讲师** | 本部门数据，学员学习进度，考试成绩分布 |
+| **学员** | 个人学习记录，成绩趋势，与平均水平对比 |
+
+### 1.3 功能边界
+
+| 范围 | 说明 |
+|------|------|
+| **包含** | 数据看板、培训统计、考试统计、学员统计、数据导出 |
+| **不包含** | 实时监控、预测分析、自定义报表设计器 |
+
+---
+
+## 二、功能清单
+
+### 2.1 模块总览
+
+```
+统计报表中心
+├── 2.1 数据概览看板
+│   ├── 关键指标卡片
+│   ├── 趋势图表
+│   └── 快捷入口
+│
+├── 2.2 培训统计
+│   ├── 培训计划完成率
+│   ├── 知识学习统计
+│   └── 部门培训排名
+│
+├── 2.3 考试统计
+│   ├── 考试通过率
+│   ├── 成绩分布
+│   └── 题目正确率分析
+│
+├── 2.4 学员统计
+│   ├── 学员学习排行
+│   ├── 个人学习报告
+│   └── 学习时长统计
+│
+└── 2.5 数据导出
+    ├── Excel 导出
+    └── 定期报表
+```
+
+---
+
+## 三、详细需求
+
+### 3.1 数据概览看板
+
+#### 3.1.1 功能描述
+
+为不同角色提供个性化的数据概览首页，一目了然掌握关键指标。
+
+#### 3.1.2 管理员看板
+
+**关键指标卡片（4个）**：
+
+| 指标 | 计算方式 | 对比 |
+|------|----------|------|
+| 总学员数 | 状态=启用的学员数量 | 较上月增减 |
+| 本月培训完成率 | 本月已完成培训人次 / 本月应完成培训人次 | 较上月变化 |
+| 本月考试通过率 | 本月通过考试人次 / 本月参考人次 | 较上月变化 |
+| 活跃学员数 | 本月有学习行为的学员数 | 较上月增减 |
+
+**趋势图表**：
+- 近6个月培训完成率趋势（折线图）
+- 近6个月考试通过率趋势（折线图）
+- 部门培训完成率排名（横向柱状图，TOP 8）
+
+**快捷入口**：
+- 查看详细培训报表
+- 查看详细考试报表
+- 导出月度汇总
+
+#### 3.1.3 讲师看板
+
+**关键指标卡片（4个）**：
+
+| 指标 | 范围 |
+|------|------|
+| 本部门学员数 | 本部门 |
+| 本部门培训完成率 | 本部门本月 |
+| 本部门考试通过率 | 本部门本月 |
+| 待批阅数 | 如有主观题（V2暂无） |
+
+**趋势图表**：
+- 本部门近6个月培训完成率趋势
+- 本部门学员学习进度分布（饼图：已完成/进行中/未开始）
+
+#### 3.1.4 学员看板
+
+**关键指标卡片（4个）**：
+
+| 指标 | 说明 |
+|------|------|
+| 我的培训进度 | 已完成/总计划数 |
+| 我的考试成绩 | 最近一次考试分数 |
+| 学习排名 | 在本部门的排名 |
+| 累计学习时长 | 总学习时长 |
+
+**图表**：
+- 我的成绩趋势（近5次考试）
+- 与部门平均分对比
+
+#### 3.1.5 验收标准
+
+```gherkin
+Feature: 数据概览看板
+
+Scenario: 管理员查看全局看板
+  Given 我是管理员角色
+  When 我进入统计报表中心
+  Then 我应该看到4个关键指标卡片
+  And 我应该看到培训完成率趋势图
+  And 我应该看到部门排名图表
+  And 所有数据应反映全平台数据
+
+Scenario: 讲师查看部门看板
+  Given 我是讲师角色
+  When 我进入统计报表中心
+  Then 所有数据应仅包含本部门数据
+  And 我不应该看到其他部门的数据
+
+Scenario: 指标卡片显示环比变化
+  Given 当前月份培训完成率为 80%
+  And 上月培训完成率为 75%
+  When 我查看培训完成率卡片
+  Then 应显示 "+5%" 的环比增长标记
+  And 增长应显示为绿色
+```
+
+---
+
+### 3.2 培训统计
+
+#### 3.2.1 培训计划完成率
+
+**筛选条件**：
+- 时间范围：本月/本季度/本年度/自定义
+- 部门：全部/指定部门（管理员可选）
+- 培训计划：全部/指定计划
+
+**统计维度**：
+
+| 维度 | 指标 |
+|------|------|
+| 按计划 | 计划名称、应参加人数、实际完成人数、完成率 |
+| 按部门 | 部门名称、计划数、完成率、排名 |
+| 按时间 | 月度完成率趋势 |
+
+**列表展示**：
+
+| 培训计划 | 部门 | 应参加 | 已完成 | 完成率 | 状态 |
+|----------|------|--------|--------|--------|------|
+| 2026Q1安全培训 | 救援一部 | 50 | 45 | 90% | 进行中 |
+| 新员工入职培训 | 救援二部 | 20 | 20 | 100% | 已结束 |
+
+#### 3.2.2 知识学习统计
+
+**统计内容**：
+- 知识总数、已发布数
+- 学习总人次
+- 热门知识 TOP 10（按学习人次）
+- 最少学习知识（提醒优化或下架）
+
+#### 3.2.3 验收标准
+
+```gherkin
+Feature: 培训统计
+
+Scenario: 按部门查看培训完成率
+  Given 我是管理员
+  When 我选择按部门维度查看
+  Then 应显示所有部门的培训完成率列表
+  And 列表应按完成率降序排列
+  And 应显示部门排名
+
+Scenario: 筛选指定时间范围
+  Given 我在培训统计页面
+  When 我选择时间范围为 "2026年1月"
+  Then 所有数据应仅包含该月份的培训数据
+
+Scenario: 导出培训报表
+  Given 我在培训统计页面
+  When 我点击导出按钮
+  Then 应下载 Excel 文件
+  And 文件应包含当前筛选条件下的所有数据
+```
+
+---
+
+### 3.3 考试统计
+
+#### 3.3.1 考试通过率
+
+**筛选条件**：
+- 时间范围：本月/本季度/本年度/自定义
+- 部门：全部/指定部门
+- 考试：全部/指定考试
+
+**统计指标**：
+
+| 指标 | 说明 |
+|------|------|
+| 参考人数 | 实际参加考试的人数 |
+| 通过人数 | 分数 >= 及格线的人数 |
+| 通过率 | 通过人数 / 参考人数 |
+| 平均分 | 所有考生的平均分数 |
+| 最高分 / 最低分 | 分数极值 |
+
+#### 3.3.2 成绩分布
+
+**图表展示**：
+- 分数段分布（柱状图）：0-59 / 60-69 / 70-79 / 80-89 / 90-100
+- 各部门平均分对比（横向柱状图）
+
+**列表展示**：
+
+| 考试名称 | 参考人数 | 通过率 | 平均分 | 最高分 | 最低分 |
+|----------|----------|--------|--------|--------|--------|
+| 安全规范考核 | 120 | 85% | 78.5 | 98 | 42 |
+| 月度技能测试 | 95 | 72% | 71.2 | 100 | 35 |
+
+#### 3.3.3 题目正确率分析
+
+**功能描述**：分析每道题的正确率，发现难题和易错题。
+
+**统计内容**：
+
+| 字段 | 说明 |
+|------|------|
+| 题目内容 | 题干摘要（前50字） |
+| 题型 | 单选/多选/判断 |
+| 作答人次 | 该题被作答的总次数 |
+| 正确率 | 正确人次 / 作答人次 |
+| 错误选项分布 | 各错误选项的选择占比 |
+
+**排序**：
+- 默认按正确率升序（易错题优先）
+- 可切换按作答人次排序
+
+**用途**：
+- 正确率 < 30% 的题目：可能题目有问题或知识点难度大
+- 正确率 > 95% 的题目：可能过于简单
+
+#### 3.3.4 验收标准
+
+```gherkin
+Feature: 考试统计
+
+Scenario: 查看考试成绩分布
+  Given 我在考试统计页面
+  When 我选择某场考试
+  Then 应显示分数段分布柱状图
+  And 应显示通过率、平均分等指标
+
+Scenario: 查看题目正确率
+  Given 我在考试统计页面
+  When 我点击 "题目分析"
+  And 选择某场考试
+  Then 应显示该考试所有题目的正确率
+  And 默认按正确率升序排列
+  And 可以查看每道题的错误选项分布
+
+Scenario: 识别易错题
+  Given 某道题的正确率为 25%
+  When 我查看题目分析列表
+  Then 该题应标记为 "易错题"
+  And 应显示主要错误选项
+```
+
+---
+
+### 3.4 学员统计
+
+#### 3.4.1 学员学习排行
+
+**排行维度**：
+- 学习时长排行（本月/本季度）
+- 考试成绩排行（平均分/最高分）
+- 培训完成数排行
+
+**展示内容**：
+
+| 排名 | 学员 | 部门 | 学习时长 | 完成培训数 | 平均分 |
+|------|------|------|----------|------------|--------|
+| 1 | 张三 | 救援一部 | 45h | 8 | 92 |
+| 2 | 李四 | 救援二部 | 42h | 7 | 88 |
+
+**范围控制**：
+- 管理员：可查看全平台排行
+- 讲师：仅可查看本部门排行
+- 学员：可查看本部门排行，自己会高亮显示
+
+#### 3.4.2 个人学习报告
+
+**入口**：
+- 讲师点击学员姓名进入
+- 学员点击"我的学习报告"进入
+
+**报告内容**：
+
+| 模块 | 内容 |
+|------|------|
+| 基本信息 | 姓名、部门、入职时间、角色 |
+| 学习概览 | 累计学习时长、完成培训数、参加考试数 |
+| 培训记录 | 参加的培训计划列表，包含进度和状态 |
+| 考试记录 | 参加的考试列表，包含成绩和是否通过 |
+| 成绩趋势 | 近10次考试成绩折线图 |
+| 能力雷达图 | 按知识分类的掌握程度（基于考试正确率） |
+
+#### 3.4.3 学习时长统计
+
+**统计规则**：
+- 知识学习：从打开到关闭/切换的时长（上限30分钟/次）
+- 视频学习：实际播放时长
+- 考试时长：从开始到交卷的时长
+
+**展示**：
+- 个人：日/周/月学习时长统计
+- 部门：部门平均学习时长、学习时长分布
+
+#### 3.4.4 验收标准
+
+```gherkin
+Feature: 学员统计
+
+Scenario: 查看学习排行榜
+  Given 我是讲师
+  When 我进入学员排行榜页面
+  Then 应显示本部门学员排行
+  And 不应显示其他部门学员
+
+Scenario: 查看个人学习报告
+  Given 我是讲师
+  When 我点击某学员的姓名
+  Then 应进入该学员的学习报告页面
+  And 应显示该学员的培训记录
+  And 应显示该学员的考试记录
+  And 应显示成绩趋势图
+
+Scenario: 学员查看自己的报告
+  Given 我是学员
+  When 我点击 "我的学习报告"
+  Then 应显示我的学习报告
+  And 应显示我在部门中的排名
+```
+
+---
+
+### 3.5 数据导出
+
+#### 3.5.1 Excel 导出
+
+**支持导出的报表**：
+
+| 报表 | 内容 | 权限 |
+|------|------|------|
+| 培训完成率报表 | 按计划/部门的完成率明细 | 管理员、讲师 |
+| 考试成绩报表 | 学员成绩明细 | 管理员、讲师 |
+| 学员学习报表 | 学员学习时长和完成情况 | 管理员、讲师 |
+| 题目分析报表 | 题目正确率明细 | 管理员、讲师 |
+
+**导出规则**：
+- 导出当前筛选条件下的数据
+- 文件名格式：`报表类型_日期_导出人.xlsx`
+- 单次导出上限：10000 条记录
+
+#### 3.5.2 验收标准
+
+```gherkin
+Feature: 数据导出
+
+Scenario: 导出考试成绩报表
+  Given 我在考试统计页面
+  And 当前筛选条件为 "2026年1月"
+  When 我点击导出按钮
+  Then 应下载 Excel 文件
+  And 文件名应为 "考试成绩报表_20260204_张三.xlsx"
+  And 数据应仅包含2026年1月的考试成绩
+
+Scenario: 导出数据量限制
+  Given 当前筛选条件下有 15000 条记录
+  When 我点击导出按钮
+  Then 应提示 "数据量超过限制，请缩小筛选范围"
+```
+
+---
+
+## 四、数据模型（建议）
+
+### 4.1 新增统计表（可选，用于性能优化）
+
+#### 日统计汇总表 (stat_daily_summary)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 主键 |
+| stat_date | Date | 统计日期 |
+| department_id | Long | 部门ID（0=全平台） |
+| total_users | Integer | 学员总数 |
+| active_users | Integer | 活跃学员数 |
+| training_complete_count | Integer | 培训完成人次 |
+| exam_pass_count | Integer | 考试通过人次 |
+| exam_total_count | Integer | 考试参与人次 |
+| total_learning_minutes | Long | 总学习时长（分钟） |
+
+#### 学习时长记录表 (stat_learning_log)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 主键 |
+| user_id | Long | 用户ID |
+| knowledge_id | Long | 知识ID |
+| start_time | DateTime | 开始时间 |
+| end_time | DateTime | 结束时间 |
+| duration_seconds | Integer | 学习时长（秒） |
+| create_time | DateTime | 创建时间 |
+
+---
+
+## 五、页面原型
+
+### 5.1 管理员数据看板
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│  统计报表中心                                                              │
+├────────────────────────────────────────────────────────────────────────────┤
+│                                                                            │
+│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐             │
+│  │  总学员数   │ │ 培训完成率  │ │ 考试通过率  │ │ 活跃学员数  │             │
+│  │    486     │ │    82%     │ │    78%     │ │    312     │             │
+│  │   +12 ↑   │ │   +5% ↑   │ │   -2% ↓   │ │   +28 ↑   │             │
+│  └────────────┘ └────────────┘ └────────────┘ └────────────┘             │
+│                                                                            │
+│  ┌─────────────────────────────────┐ ┌─────────────────────────────────┐  │
+│  │ 培训完成率趋势                   │ │ 部门培训完成率排名               │  │
+│  │                                 │ │                                 │  │
+│  │  100%│                         │ │ 救援一部  ████████████  92%     │  │
+│  │   80%│    ╭──╮    ╭──╮        │ │ 救援三部  ██████████    85%     │  │
+│  │   60%│╭──╯  ╰──╮╭╯  ╰──      │ │ 救援二部  █████████     80%     │  │
+│  │   40%│           ╰            │ │ 救援四部  ███████       72%     │  │
+│  │      └─────────────────       │ │ 综合部    ██████        65%     │  │
+│  │       9  10  11  12  1   2    │ │                                 │  │
+│  └─────────────────────────────────┘ └─────────────────────────────────┘  │
+│                                                                            │
+│  [查看培训详情]  [查看考试详情]  [导出月度报表]                            │
+│                                                                            │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 考试统计页面
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│  统计报表中心 > 考试统计                                                   │
+├────────────────────────────────────────────────────────────────────────────┤
+│                                                                            │
+│  时间范围: [本月 ▼]  部门: [全部 ▼]  考试: [全部 ▼]    [查询]  [导出]    │
+│                                                                            │
+│  ┌─────────────────────────────────┐ ┌─────────────────────────────────┐  │
+│  │ 成绩分布                         │ │ 汇总指标                        │  │
+│  │                                 │ │                                 │  │
+│  │      ┌───┐                      │ │  参考人数:     320              │  │
+│  │      │   │ ┌───┐                │ │  通过人数:     256              │  │
+│  │ ┌───┐│   │ │   │ ┌───┐         │ │  通过率:       80%              │  │
+│  │ │   ││   │ │   │ │   │ ┌───┐   │ │  平均分:       76.5             │  │
+│  │ │   ││   │ │   │ │   │ │   │   │ │  最高分:       100              │  │
+│  │ └───┘└───┘ └───┘ └───┘ └───┘   │ │  最低分:       32               │  │
+│  │ 0-59 60-69 70-79 80-89 90-100  │ │                                 │  │
+│  └─────────────────────────────────┘ └─────────────────────────────────┘  │
+│                                                                            │
+│  ┌──────────────────────────────────────────────────────────────────────┐  │
+│  │ 考试名称          参考人数   通过率   平均分   最高分   操作         │  │
+│  ├──────────────────────────────────────────────────────────────────────┤  │
+│  │ 安全规范考核        120       85%     78.5     98     [详情][分析]  │  │
+│  │ 月度技能测试         95       72%     71.2    100     [详情][分析]  │  │
+│  │ 新员工入职考试       45       91%     82.3     96     [详情][分析]  │  │
+│  └──────────────────────────────────────────────────────────────────────┘  │
+│                                                                            │
+│                                                      < 1  2  3 >          │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 六、非功能需求
+
+| 类型 | 要求 |
+|------|------|
+| **性能** | 看板页面加载时间 < 2秒 |
+| **性能** | 报表查询响应时间 < 3秒（万级数据） |
+| **兼容性** | 支持 Chrome、Edge、Firefox 最新版本 |
+| **数据安全** | 严格按角色和部门隔离数据 |
+| **导出** | Excel 导出支持 .xlsx 格式 |
+
+---
+
+## 七、不做什么（Out of Scope）
+
+| 排除项 | 原因 |
+|--------|------|
+| 实时数据监控 | V2 不需要实时性，T+1 统计即可 |
+| 自定义报表设计器 | 复杂度高，用户需求不明确 |
+| 数据预测/AI分析 | 数据量不足，价值有限 |
+| 打印报表 | 使用 Excel 导出替代 |
+
+---
+
+## 八、里程碑建议
+
+| 阶段 | 内容 | 建议周期 |
+|------|------|----------|
+| M1 | 数据看板（管理员+讲师+学员） | - |
+| M2 | 培训统计 + 考试统计 | - |
+| M3 | 学员统计 + 数据导出 | - |
+| M4 | 测试 + 优化 | - |
+
+---
+
+## 九、开放问题
+
+| 问题 | 待确认 |
+|------|--------|
+| 学习时长统计是否需要精确到秒级？ | 建议分钟级即可 |
+| 是否需要支持定时自动发送报表邮件？ | 建议 V3 考虑 |
+| 能力雷达图的维度如何定义？ | 建议按知识分类一级目录 |
+
+---
+
+**文档状态：待评审**