用户统计把教师、学生、账号配置、分班情况和学生画像数据整合到一张看板中，用来核对教育管理系统的用户底座。学生是否分班、教师是否配置学科、学生支持数据是否覆盖，都会影响后续教学和考试分析。
本文按照 Demo 的写法，把用户统计拆成后端聚合、前端看板、数据联动和 Codex 生成标准。所有能力都来自 UserStatsViewSet 与 UserStats/index.vue，不补写源码里没有的功能。
文章目录
设计与需求
用户统计不是单纯统计用户数量。UserStatsViewSet.build_overview_data 同时读取学生、教师、分班、性别、入学成绩、小三科和学生画像相关模型，前端将这些数据分成用户结构、学生分布和学生数据模块三组统计区域。
验收阶段
展示阶段
设计阶段
输入阶段
业务数据
统计口径
菜单入口
后端聚合
接口返回
前端看板
指标卡
矩阵树图
明细表格
数据一致
布局稳定
权限可见
这张图表达的是统计类模块从业务数据到页面展示的转换关系。Codex 处理这类需求时，不能只生成一个空页面或普通 CRUD，需要把统计口径、接口返回结构、前端矩阵展示和菜单权限一起纳入设计。
| 需求层描述 | 设计层转换 | Codex 代码生成方向 |
|---|---|---|
| 管理端需要看到用户规模 | 将学生和教师数量统一进入 summary 与 user_composition |
生成用户类型占比、用户配置明细和顶部指标 |
| 学生需要核对分班状态 | 按行政班、分班信息、性别、入学成绩、小三科拆分 | 生成学生分布矩阵、分班明细和入学成绩表 |
| 教师需要核对学科配置 | 解析教师类型、教师账号和 name_subject 多值学科 |
生成教师统计 Tab、学科分布和类型分布 |
| 学生画像需要看覆盖率 | 汇总生活画像、生活日常、支持周报、健康事件、出勤行为、入学评估 | 生成学生数据模块卡片、覆盖学生数和指标明细 |
| 用户统计需要稳定刷新 | 使用缓存 Key mywork.user.overview 返回聚合结果 |
生成可缓存的 overview 接口并进入统一刷新计划 |
用户统计的真实统计对象分成用户基础结构、学生分布和学生扩展数据覆盖三类。
| 统计对象 | 代码口径 | 页面呈现 |
|---|---|---|
| 用户结构 | StudentManage、TeacherManage 统计学生数、教师数、账号数 |
用户类型占比、学生/教师 Tab、用户配置明细 |
| 学生分布 | 学生性别、行政班、分数段、小三科字段聚合 | 性别矩阵树图、入学成绩表、行政班表、小三科表 |
| 教师配置 | 教师账号、教师类型、教师学科多值解析 | 教师类型分布、教师学科分布、教师统计表 |
| 学生生活画像 | StudentProfileLife 统计住校、通勤、学习空间、设备干扰等 |
学生数据模块卡片和覆盖率 |
| 学生日常与支持 | StudentLifeDaily、StudentSupportWeekly 统计睡眠、压力、家庭支持、归属感等 |
模块指标、平均值、异常标记数量 |
| 健康、出勤、入学评估 | StudentHealthEvent、StudentAttendanceBehavior、StudentAdmissionAssessment |
健康事件、出勤行为、入学评估覆盖和风险指标 |
可以直接使用下面的Prompt进行模块功能的设计
text
请基于 ManageBak-ExamEdu 项目设计并实现【用户统计】统计模块。
模块前端入口为：server_vue3/src/views/system/MyWork/UserStats/index.vue
后端接口入口为：server_backend/modules/MyWork/views_app/UserStats.py
接口地址为：/api/MyWork/UserStats/overview/
菜单路径为：/system/MyWork/UserStats
请先读取上述前端页面、后端 ViewSet、路由注册、统计缓存工具、共享样式文件和菜单同步脚本，再设计模块。不要只按模块名称联想功能，必须以真实源码中的统计口径为准。
模块需要覆盖这些统计对象：用户结构、学生分布、教师配置、学生生活画像、学生生活日常、学生支持周报、学生健康事件、学生出勤行为、学生入学评估。
请输出完整模块设计方案，包括业务定位、后端聚合口径、接口返回结构、前端页面结构、指标卡设计、矩阵树图与明细表格关系、菜单权限、缓存策略、验收标准。设计确认后，再按照当前项目技术栈生成或补齐项目代码。后端设计
后端入口是 server_backend/modules/MyWork/views_app/UserStats.py。文件中既有基础分布函数，也有 _student_module_stats 这样的学生扩展模块聚合函数，overview action 返回完整用户统计数据。
| 后端设计项 | 真实代码依据 | Codex 生成方向 |
|---|---|---|
| ViewSet 入口 | UserStatsViewSet，文件 server_backend/modules/MyWork/views_app/UserStats.py |
保持统计接口集中在 ViewSet action 内，避免把聚合逻辑散落到前端 |
| 接口方法 | overview` action 调用 `build_overview_data |
生成 GET 统计接口，返回可直接驱动页面的结构化数据 |
| 数据模型 | StudentManage、TeacherManage、StudentProfileLife、StudentLifeDaily、StudentSupportWeekly、StudentHealthEvent、StudentAttendanceBehavior、StudentAdmissionAssessment |
按真实模型字段聚合，不在接口里编造不存在的维度 |
| 统计构建 | build_overview_data` 组装 `summary`、`cards`、用户分布和 `student_module_stats |
把 summary、cards、detail 或 dimensions 拆清楚，便于前端复用 |
| 缓存策略 | get_or_build_stats_payload("mywork.user.overview", "用户统计", ...) |
使用统计缓存减少重复聚合开销，并保留刷新入口 |
| 路由注册 | server_backend/modules/MyWork/urls.py |
通过 DRF router 暴露 /api/.../ 接口，不新增孤立 URL |
| 菜单入口 | server_backend/dvadmin/system/management/commands/sync_mywork_statistics_menu.py 中的 /system/MyWork/UserStats |
让统计页面进入"我的工作/数据统计"入口并同步角色权限 |
用户统计后端需要特别注意多值字段和空值归类。_json_values 用于解析教师学科、小三科等字段，_field_distribution、_class_gender_distribution、_score_band_gender_distribution 用于生成可展示分布，避免前端直接处理模型细节。
可以直接使用下面的Prompt进行后端代码的设计
text
请为【用户统计】补齐后端统计接口。
读取并遵循：
1. `server_backend/modules/MyWork/views_app/UserStats.py`
2. `server_backend/modules/MyWork/urls.py`
3. `server_backend/modules/MyWork/utils.py`
4. `server_backend/dvadmin/system/management/commands/sync_mywork_statistics_menu.py`
后端接口地址：/api/MyWork/UserStats/overview/
缓存 Key：mywork.user.overview
涉及模型：StudentManage、TeacherManage、StudentProfileLife、StudentLifeDaily、StudentSupportWeekly、StudentHealthEvent、StudentAttendanceBehavior、StudentAdmissionAssessment
实现要求：
- 统计口径必须来自真实模型字段，不能凭页面名称补字段。
- 返回结构需要覆盖页面顶部 summary、模块 cards、明细 detail 或 dimensions。
- 百分比统一按 `value / total` 计算，total 为 0 时返回 0。
- 空值要归入"未填写、未设置、未分类"等明确标签。
- 接口只承担统计聚合，不把前端展示样式写进后端。
- 保持 `get_or_build_stats_payload` 缓存调用，支持统一刷新统计渲染缓存。
- 路由继续使用已有 DRF router 注册方式，避免新增重复路径。
完成后给出字段口径、返回结构示例、缓存 Key 和接口验收点。前端设计
前端入口是 server_vue3/src/views/system/MyWork/UserStats/index.vue。页面通过 /api/MyWork/UserStats/overview/ 拉取数据，使用用户结构、学生分布、学生数据模块三个 dashboard 展示统计结果。
| 前端设计项 | 真实代码依据 | Codex 生成方向 |
|---|---|---|
| 页面入口 | server_vue3/src/views/system/MyWork/UserStats/index.vue |
保持统计页单文件入口，必要时只抽取真正复用的展示组件 |
| 接口调用 | request({ url: '/api/MyWork/UserStats/overview/', method: 'get' }) |
页面加载时拉取统计数据，失败时保留空态和 loading 状态 |
| 共享样式 | server_vue3/src/theme/stats-dashboard.scss |
使用 stats-dashboard-standard、stats-module-header、stats-kpi-strip 统一看板骨架 |
| 顶部 Hero | 页面标题、说明和三枚核心指标 | 让用户进入页面后立即看到模块规模、记录量和完成率 |
| 模块 Frame | Header、描述、指标卡、Body | 每个统计对象独立成块，避免图表和表格混在一层 |
| 明细展示 | 矩阵树图、Element Plus Tab、统计表格、进度条、学生模块卡片 |
同一批接口数据同时支撑概览图和可核对表格 |
| 交互状态 | activeUserTab、activeStudentTab、userCompositionRows、genderRows、scoreRows、classRows、minorSubjectRows、studentModuleStats |
Tab、矩阵、表格高度和空态要跟随接口数据稳定变化 |
页面通过 activeUserTab、activeStudentTab 控制学生和教师、入学统计和班级统计等区域切换。userTreemapRows、genderTreemapRows、studentModuleStats 等 computed 状态把后端数据变成矩阵树图、进度条和表格。
可以直接使用下面的Prompt进行前端代码的设计
text
请为【用户统计】实现或补齐前端统计看板。
读取并遵循：
1. `server_vue3/src/views/system/MyWork/UserStats/index.vue`
2. `server_vue3/src/theme/stats-dashboard.scss`
3. `docs/sop/server/04.统计看板表格化改造SOP.md`
4. 后端接口 `/api/MyWork/UserStats/overview/` 的真实返回结构
页面要求：
- 使用 `stats-dashboard-standard` 作为统计页根容器。
- 顶部 Hero 展示标题、说明和三项核心指标。
- 每个统计对象使用 `stats-module-header` 组织标题、描述和 KPI。
- 图形展示只做概览，必须提供可核对的明细表格或矩阵。
- Tab、矩阵树图、明细表格要消费同一份数据，避免前后口径不一致。
- loading、空数据、接口异常、移动端布局都要有稳定状态。
- 不改后端字段名称，不在前端伪造不存在的统计维度。
完成后给出页面区域、接口字段映射、交互状态和构建验证结果。扩展功能
【用户统计】不是普通管理页，它的扩展能力集中在数据统计、统计维度联动、缓存刷新和菜单权限。源码没有 LLM、OCR、导入导出或审批流入口，因此文档只描述真实存在的统计能力。
| 扩展功能 | 主要用途 | 落地重点 |
|---|---|---|
| 数据统计 | 把多个业务表聚合成 summary、cards、detail 或 dimensions | 后端统一计算数量、完成率、启用率和字段覆盖率 |
| 数据联动 | 让 Tab、矩阵树图、指标卡、表格共用一套接口数据 | 前端 computed 状态只做格式化，不改变业务口径 |
| 统计缓存与菜单入口 | 降低统计接口重复聚合成本，并让页面进入数据统计菜单 | 使用 get_or_build_stats_payload 与菜单同步脚本维护入口 |
数据统计
用户统计的数据统计能力覆盖基础人数、分布占比和学生扩展模块覆盖率。后端把学生、教师和学生画像相关模型聚合到一个接口，前端可以在同一页面检查用户账号、分班、学科、生活画像和出勤健康数据。
结果阶段
处理阶段
输入阶段
业务模型
字段口径
空值规则
数量聚合
占比计算
结构组装
概览指标
分布数据
明细矩阵
口径校验
可以直接使用下面的Prompt进行数据统计功能设计
text
请为【用户统计】设计数据统计能力。
统计对象：用户结构、学生分布、教师配置、学生生活画像、学生生活日常、学生支持周报、学生健康事件、学生出勤行为、学生入学评估
后端入口：server_backend/modules/MyWork/views_app/UserStats.py
接口地址：/api/MyWork/UserStats/overview/
要求：
- 明确每个统计对象对应的模型、过滤条件、计数字段和完成率字段。
- 统一输出 summary、cards、detail 或 dimensions，不让前端重新推导业务口径。
- 所有 rate 字段返回 0 到 1 的小数，前端再格式化为百分比。
- 分布数据要同时能驱动矩阵树图、图例和明细表格。
- 空值必须归并为可读标签，例如未填写、未设置、未分类、待初始化。
- 给出接口返回示例和异常数据处理规则。数据联动
用户统计的联动集中在学生/教师 Tab、学生分布 Tab 和学生模块卡片之间。切换 Tab 时，表格行和顶部说明同步变化；矩阵树图显示同一批用户结构或性别数据的占比，明细表格用于核对具体分布。
结果阶段
处理阶段
输入阶段
接口数据
当前 Tab
统计维度
computed 转换
图表数据
表格行列
指标同步
图表同步
表格同步
一致校验
可以直接使用下面的Prompt进行数据联动设计
text
请为【用户统计】补齐前端数据联动。
前端入口：server_vue3/src/views/system/MyWork/UserStats/index.vue
联动状态：activeUserTab、activeStudentTab、userCompositionRows、genderRows、scoreRows、classRows、minorSubjectRows、studentModuleStats
展示组件：矩阵树图、Element Plus Tab、统计表格、进度条、学生模块卡片
要求：
- Tab 当前值、指标卡、矩阵树图和明细表格必须来自同一份接口数据。
- computed 只做排序、分组、百分比格式化和空值兜底，不改变后端统计结论。
- 切换 Tab 后标题、描述、指标、图表、表格同步更新。
- 接口为空时展示 el-empty，不出现 NaN、undefined 或布局塌陷。
- 表格高度、滚动区域和移动端布局保持稳定。统计缓存与菜单入口
用户统计使用缓存 Key mywork.user.overview，在 refresh_all_stats_render_cache 的计划中刷新。菜单入口由 sync_mywork_statistics_menu.py 写入 /system/MyWork/UserStats，组件指向 system/MyWork/UserStats/index。
| 入口类型 | 真实文件 | 说明 |
|---|---|---|
| 接口缓存 | server_backend/modules/MyWork/utils.py |
get_or_build_stats_payload 读取或构建统计结果 |
| 刷新计划 | server_backend/modules/MyWork/utils.py |
_refresh_plans 覆盖配置、用户、教学、考试、内容统计 |
| 菜单同步 | server_backend/dvadmin/system/management/commands/sync_mywork_statistics_menu.py |
维护 /system/MyWork/UserStats、组件 system/MyWork/UserStats/index 和角色权限 |
| 共享样式 | server_vue3/src/theme/stats-dashboard.scss |
统一 Hero、Header Frame、KPI、滚动容器样式 |
可以直接使用下面的Prompt进行统计缓存与菜单入口设计
text
请为【用户统计】检查统计缓存和菜单入口。
缓存 Key：mywork.user.overview
菜单路径：/system/MyWork/UserStats
组件路径：system/MyWork/UserStats/index
前端页面：server_vue3/src/views/system/MyWork/UserStats/index.vue
要求：
- 统计接口必须接入 `get_or_build_stats_payload`。
- 统一刷新计划需要包含该模块缓存 Key。
- 菜单同步脚本需要写入正确的 web_path、component、component_name、icon、image、sort 和 cache 配置。
- 菜单权限要同步到已有角色权限表，避免页面有路由但角色不可见。
- 交付时列出缓存 Key、菜单路径和接口地址。Codex开发标准
使用 Codex 开发统计看板时，输入不能只写"做一个统计页面"。更稳的方式是把统计口径、接口字段、页面结构、共享样式、缓存策略和验收清单一次性交给 Codex，让代码生成围绕真实工程边界展开。
验收交付
Codex开发
模块设计
输入约束
源码路径
接口口径
SOP规范
后端聚合
前端布局
缓存菜单
生成代码
补齐状态
统一样式
构建通过
口径一致
页面稳定
SOP 标准
| SOP 项 | 执行标准 | 对【用户统计】的要求 |
|---|---|---|
| 文档规范 | 参考 _Demo/_教程撰写.md 的固定结构 |
标题、开头、TOC、设计、后端、前端、扩展、Codex 标准、总结齐全 |
| 统计页规范 | 参考 docs/sop/server/04.统计看板表格化改造SOP.md |
页面使用 Header Frame、指标卡、矩阵树图、明细表格 |
| 源码真实性 | 只写真实代码存在的接口、模型和页面状态 | 不写 LLM、OCR、导入导出、审批流等不存在能力 |
| 样式复用 | 共享样式统一进入 stats-dashboard.scss |
单页只处理必要差异，不复制一套统计页框架 |
| 接口稳定 | 后端给前端结构化统计结果 | 前端不重新计算复杂业务口径 |
可以直接使用下面的Prompt进行SOP撰写
text
请按照 `_Demo/_教程撰写.md` 和 `docs/sop/server/04.统计看板表格化改造SOP.md`，为【用户统计】整理开发 SOP。
SOP 需要覆盖：源码读取顺序、后端统计口径、前端页面结构、共享样式使用、缓存 Key、菜单同步、构建验证、页面验收清单。
文档只写真实存在的文件、接口和模型。涉及流程时使用 Mermaid，涉及口径映射和验收标准时使用 Markdown 表格。PDD 标准
| 验收项 | 验收标准 | 失败风险 |
|---|---|---|
| 接口可用 | /api/MyWork/UserStats/overview/ 返回 summary、模块数据和明细数据 |
页面无数据或字段 undefined |
| 统计口径 | 后端统计与模型字段一致，rate 计算稳定 | 图表、表格、指标卡口径不一致 |
| 页面结构 | Hero、模块 Header、KPI、图表、表格层次清晰 | 统计页像普通列表或内容拥挤 |
| 数据联动 | Tab 切换后图表和表格同步 | 用户看到不同区域数据互相冲突 |
| 缓存入口 | 缓存 Key 能被统一刷新计划覆盖 | 数据更新后页面仍长期显示旧统计 |
| 菜单权限 | /system/MyWork/UserStats 可见且组件路径正确 |
卡片能看到但进入页面失败 |
| 构建验证 | 前端构建通过，无类型和模板错误 | 代码合入后影响管理后台构建 |
可以直接使用下面的Prompt进行PDD 验收
text
请为【用户统计】输出 PDD 验收清单。
需要检查：
1. 后端接口 `/api/MyWork/UserStats/overview/` 的返回结构和字段口径。
2. 前端页面 `server_vue3/src/views/system/MyWork/UserStats/index.vue` 的 Hero、Header Frame、指标卡、矩阵树图、表格、Tab、空态和 loading。
3. 共享样式 `stats-dashboard.scss` 是否被正确使用。
4. 缓存 Key `mywork.user.overview` 是否进入统一刷新计划。
5. 菜单路径 `/system/MyWork/UserStats` 和组件 `system/MyWork/UserStats/index` 是否能通过菜单同步脚本落库。
6. `npm run build` 是否通过。
输出结果用表格列出验收项、检查方法、通过标准和风险说明。总结
用户统计文档的核心是用户数据底座验收。后端把学生、教师、分班、学科和学生画像模型整理成统一接口，前端用统计看板结构展示用户规模、学生分布和模块覆盖率。
Codex 处理这类统计页时，真正要生成的不只是一个 Vue 页面，而是一条从业务模型、统计接口、缓存刷新、菜单权限到前端可视化的完整链路。只要输入中把真实源码路径、接口地址和统计口径交代清楚，生成出来的代码就更容易接入 ManageBak-ExamEdu 的现有工程结构。