配置统计把用户账号、班级、教材、知识点和 APP 绑定教程放到同一张看板里，用来检查教育管理系统的基础配置是否完整。这个页面的价值不在于展示漂亮图表，而在于把后续教学、考试、内容生产依赖的数据底座提前校准。
本文按照 Demo 的技术文章结构，围绕真实源码梳理配置统计如何转换成 Codex 可以执行的代码生成任务。文档只引用 ConfigStatisticsViewSet、Statistics/index.vue、路由和菜单同步脚本中已经存在的能力。
文章目录
设计与需求
配置统计不能只理解成配置中心的数量汇总。ConfigStatisticsViewSet.build_overview_data 把 StudentClasses、TextBook、KnowledgePoint、LessonPlanChapter 和用户账号信息组合成 summary、cards、dimensions，前端再按班级、教材、知识点、APP绑定教程拆成可核对的统计块。
验收阶段
展示阶段
设计阶段
输入阶段
业务数据
统计口径
菜单入口
后端聚合
接口返回
前端看板
指标卡
矩阵树图
明细表格
数据一致
布局稳定
权限可见
这张图表达的是统计类模块从业务数据到页面展示的转换关系。Codex 处理这类需求时，不能只生成一个空页面或普通 CRUD，需要把统计口径、接口返回结构、前端矩阵展示和菜单权限一起纳入设计。
| 需求层描述 | 设计层转换 | Codex 代码生成方向 |
|---|---|---|
| 基础配置需要统一巡检 | 将班级、教材、知识点、教程绑定和用户账号纳入同一统计接口 | 生成 summary、cards、dimensions 三层数据结构 |
| 班级配置需要检查启停用 | 按行政班、小三科、教学班和年级学科聚合 | 生成班级类型矩阵树图、类型明细表和启用率 |
| 教材配置需要看初始化状态 | 按教材分类、学科、版本、备选数量和初始化结果统计 | 生成教材分类 Tab、初始化占比和教材配置表格 |
| 知识点配置需要看覆盖 | 按年级、学科、层级和启停用统计知识点 | 生成年级知识点分布、学科明细和层级堆叠条 |
| APP教程绑定需要看缺口 | 按年级、学科、章节绑定状态统计教程绑定进度 | 生成绑定进度图、待绑定明细和绑定率 |
配置统计的真实统计对象来自后端 cards 与 dimensions，前端页面重点展示配置完整度和待补齐项。
| 统计对象 | 代码口径 | 页面呈现 |
|---|---|---|
| 班级配置 | StudentClasses.objects.filter(level=3)，按班级类型、年级、学科和 enable 聚合 |
班级类型占比、分类型班级明细、启用/停用统计 |
| 教材初始化 | TextBook 与 menu_data_dict，按教材分类和学科整理初始化状态 |
教材初始化占比、分类 Tab、教材名称和备选数量表格 |
| 知识点配置 | KnowledgePoint 按年级、学科、层级和 enable 聚合 |
年级知识点分布、学科明细、层级构成、启用率 |
| APP绑定教程 | LessonPlanChapter 结合 LessonPlanChapterViewUtils 识别教程章节绑定 |
整体绑定进度、已绑定/待绑定统计、年级学科明细 |
| 用户账号 | StudentManage、TeacherManage 汇总账号规模 |
进入配置统计 summary 和 cards，用于基础数据完整度判断 |
可以直接使用下面的Prompt进行模块功能的设计
text
请基于 ManageBak-ExamEdu 项目设计并实现【配置统计】统计模块。
模块前端入口为：server_vue3/src/views/modules/Config/Statistics/index.vue
后端接口入口为：server_backend/modules/Config/views_app/Statistics.py
接口地址为：/api/Config/Statistics/overview/
菜单路径为：/system/MyWork/ConfigStatistics
请先读取上述前端页面、后端 ViewSet、路由注册、统计缓存工具、共享样式文件和菜单同步脚本，再设计模块。不要只按模块名称联想功能，必须以真实源码中的统计口径为准。
模块需要覆盖这些统计对象：用户统计、班级设置、教材配置、知识点配置、APP绑定教程。
请输出完整模块设计方案，包括业务定位、后端聚合口径、接口返回结构、前端页面结构、指标卡设计、矩阵树图与明细表格关系、菜单权限、缓存策略、验收标准。设计确认后，再按照当前项目技术栈生成或补齐项目代码。后端设计
后端入口是 server_backend/modules/Config/views_app/Statistics.py。这个 ViewSet 只开放 GET，核心方法 build_overview_data 负责组织配置中心的统计口径，overview action 使用缓存工具返回数据。
| 后端设计项 | 真实代码依据 | Codex 生成方向 |
|---|---|---|
| ViewSet 入口 | ConfigStatisticsViewSet，文件 server_backend/modules/Config/views_app/Statistics.py |
保持统计接口集中在 ViewSet action 内，避免把聚合逻辑散落到前端 |
| 接口方法 | overview` action 调用 `build_overview_data |
生成 GET 统计接口，返回可直接驱动页面的结构化数据 |
| 数据模型 | StudentClasses、TextBook、KnowledgePoint、LessonPlanChapter、StudentManage、TeacherManage |
按真实模型字段聚合，不在接口里编造不存在的维度 |
| 统计构建 | build_overview_data` 组装 `summary`、`cards`、`dimensions |
把 summary、cards、detail 或 dimensions 拆清楚，便于前端复用 |
| 缓存策略 | get_or_build_stats_payload("config.statistics.overview", "配置统计", ...) |
使用统计缓存减少重复聚合开销，并保留刷新入口 |
| 路由注册 | server_backend/modules/Config/urls.py |
通过 DRF router 暴露 /api/.../ 接口，不新增孤立 URL |
| 菜单入口 | server_backend/dvadmin/system/management/commands/sync_mywork_statistics_menu.py 中的 /system/MyWork/ConfigStatistics |
让统计页面进入"我的工作/数据统计"入口并同步角色权限 |
后端设计的重点是把配置完整度放在服务端统一计算。班级、教材、知识点和教程绑定都有各自的维度整理方法，前端不需要再理解模型关系，只负责把 dimensions.classes、dimensions.textbook_initialization、dimensions.knowledge_points、dimensions.lesson_bindings 渲染成图表和表格。
可以直接使用下面的Prompt进行后端代码的设计
text
请为【配置统计】补齐后端统计接口。
读取并遵循：
1. `server_backend/modules/Config/views_app/Statistics.py`
2. `server_backend/modules/Config/urls.py`
3. `server_backend/modules/MyWork/utils.py`
4. `server_backend/dvadmin/system/management/commands/sync_mywork_statistics_menu.py`
后端接口地址：/api/Config/Statistics/overview/
缓存 Key：config.statistics.overview
涉及模型：StudentClasses、TextBook、KnowledgePoint、LessonPlanChapter、StudentManage、TeacherManage
实现要求：
- 统计口径必须来自真实模型字段，不能凭页面名称补字段。
- 返回结构需要覆盖页面顶部 summary、模块 cards、明细 detail 或 dimensions。
- 百分比统一按 `value / total` 计算，total 为 0 时返回 0。
- 空值要归入"未填写、未设置、未分类"等明确标签。
- 接口只承担统计聚合，不把前端展示样式写进后端。
- 保持 `get_or_build_stats_payload` 缓存调用，支持统一刷新统计渲染缓存。
- 路由继续使用已有 DRF router 注册方式，避免新增重复路径。
完成后给出字段口径、返回结构示例、缓存 Key 和接口验收点。前端设计
前端入口是 server_vue3/src/views/modules/Config/Statistics/index.vue，页面使用 stats-dashboard-standard 作为根容器，调用 /api/Config/Statistics/overview/ 后把数据拆成班级、教材、知识点和 APP绑定教程四个 panel。
| 前端设计项 | 真实代码依据 | Codex 生成方向 |
|---|---|---|
| 页面入口 | server_vue3/src/views/modules/Config/Statistics/index.vue |
保持统计页单文件入口，必要时只抽取真正复用的展示组件 |
| 接口调用 | request({ url: '/api/Config/Statistics/overview/', method: 'get' }) |
页面加载时拉取统计数据，失败时保留空态和 loading 状态 |
| 共享样式 | server_vue3/src/theme/stats-dashboard.scss |
使用 stats-dashboard-standard、stats-module-header、stats-kpi-strip 统一看板骨架 |
| 顶部 Hero | 页面标题、说明和三枚核心指标 | 让用户进入页面后立即看到模块规模、记录量和完成率 |
| 模块 Frame | Header、描述、指标卡、Body | 每个统计对象独立成块，避免图表和表格混在一层 |
| 明细展示 | 矩阵树图、分类 Tab、Element Plus 表格、层级堆叠条、绑定进度条 |
同一批接口数据同时支撑概览图和可核对表格 |
| 交互状态 | activeTextbookCategory、activeKnowledgeLevel、activeBindingLevel、classTypeSections、textbookCategorySections、knowledgeGradeSections、bindingGradeSections |
Tab、矩阵、表格高度和空态要跟随接口数据稳定变化 |
页面的 computed 状态承担格式化职责，例如 classTypeSections、textbookCategorySections、knowledgeGradeSections、bindingGradeSections。这些状态将接口返回的维度数据转换为矩阵树图、Tab、Element Plus 表格和进度条，业务口径仍来自后端。
可以直接使用下面的Prompt进行前端代码的设计
text
请为【配置统计】实现或补齐前端统计看板。
读取并遵循：
1. `server_vue3/src/views/modules/Config/Statistics/index.vue`
2. `server_vue3/src/theme/stats-dashboard.scss`
3. `docs/sop/server/04.统计看板表格化改造SOP.md`
4. 后端接口 `/api/Config/Statistics/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
请为【配置统计】设计数据统计能力。
统计对象：用户统计、班级设置、教材配置、知识点配置、APP绑定教程
后端入口：server_backend/modules/Config/views_app/Statistics.py
接口地址：/api/Config/Statistics/overview/
要求：
- 明确每个统计对象对应的模型、过滤条件、计数字段和完成率字段。
- 统一输出 summary、cards、detail 或 dimensions，不让前端重新推导业务口径。
- 所有 rate 字段返回 0 到 1 的小数，前端再格式化为百分比。
- 分布数据要同时能驱动矩阵树图、图例和明细表格。
- 空值必须归并为可读标签，例如未填写、未设置、未分类、待初始化。
- 给出接口返回示例和异常数据处理规则。数据联动
配置统计的联动主要发生在教材分类、知识点年级和绑定年级之间。Tab 当前值决定表格展示范围，矩阵树图展示同一批数据的占比，KPI 展示当前统计对象的总量和完成情况。
结果阶段
处理阶段
输入阶段
接口数据
当前 Tab
统计维度
computed 转换
图表数据
表格行列
指标同步
图表同步
表格同步
一致校验
可以直接使用下面的Prompt进行数据联动设计
text
请为【配置统计】补齐前端数据联动。
前端入口：server_vue3/src/views/modules/Config/Statistics/index.vue
联动状态：activeTextbookCategory、activeKnowledgeLevel、activeBindingLevel、classTypeSections、textbookCategorySections、knowledgeGradeSections、bindingGradeSections
展示组件：矩阵树图、分类 Tab、Element Plus 表格、层级堆叠条、绑定进度条
要求：
- Tab 当前值、指标卡、矩阵树图和明细表格必须来自同一份接口数据。
- computed 只做排序、分组、百分比格式化和空值兜底，不改变后端统计结论。
- 切换 Tab 后标题、描述、指标、图表、表格同步更新。
- 接口为空时展示 el-empty，不出现 NaN、undefined 或布局塌陷。
- 表格高度、滚动区域和移动端布局保持稳定。统计缓存与菜单入口
配置统计使用缓存 Key config.statistics.overview，并在 MyWork 的统一刷新计划中注册。菜单入口同时存在于"我的工作/数据统计"的 sync_mywork_statistics_menu.py 和配置中心单独的 sync_config_statistics_menu.py，需要避免两个入口的组件路径不一致。
| 入口类型 | 真实文件 | 说明 |
|---|---|---|
| 接口缓存 | 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/ConfigStatistics、组件 modules/Config/Statistics/index 和角色权限 |
| 共享样式 | server_vue3/src/theme/stats-dashboard.scss |
统一 Hero、Header Frame、KPI、滚动容器样式 |
可以直接使用下面的Prompt进行统计缓存与菜单入口设计
text
请为【配置统计】检查统计缓存和菜单入口。
缓存 Key：config.statistics.overview
菜单路径：/system/MyWork/ConfigStatistics
组件路径：modules/Config/Statistics/index
前端页面：server_vue3/src/views/modules/Config/Statistics/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/Config/Statistics/overview/ 返回 summary、模块数据和明细数据 |
页面无数据或字段 undefined |
| 统计口径 | 后端统计与模型字段一致，rate 计算稳定 | 图表、表格、指标卡口径不一致 |
| 页面结构 | Hero、模块 Header、KPI、图表、表格层次清晰 | 统计页像普通列表或内容拥挤 |
| 数据联动 | Tab 切换后图表和表格同步 | 用户看到不同区域数据互相冲突 |
| 缓存入口 | 缓存 Key 能被统一刷新计划覆盖 | 数据更新后页面仍长期显示旧统计 |
| 菜单权限 | /system/MyWork/ConfigStatistics 可见且组件路径正确 |
卡片能看到但进入页面失败 |
| 构建验证 | 前端构建通过，无类型和模板错误 | 代码合入后影响管理后台构建 |
可以直接使用下面的Prompt进行PDD 验收
text
请为【配置统计】输出 PDD 验收清单。
需要检查：
1. 后端接口 `/api/Config/Statistics/overview/` 的返回结构和字段口径。
2. 前端页面 `server_vue3/src/views/modules/Config/Statistics/index.vue` 的 Hero、Header Frame、指标卡、矩阵树图、表格、Tab、空态和 loading。
3. 共享样式 `stats-dashboard.scss` 是否被正确使用。
4. 缓存 Key `config.statistics.overview` 是否进入统一刷新计划。
5. 菜单路径 `/system/MyWork/ConfigStatistics` 和组件 `modules/Config/Statistics/index` 是否能通过菜单同步脚本落库。
6. `npm run build` 是否通过。
输出结果用表格列出验收项、检查方法、通过标准和风险说明。总结
配置统计文档落点是基础配置完整度。后端已经把班级、教材、知识点、教程绑定和用户账号聚合成稳定接口，前端按统计看板 SOP 展示为 Header Frame、KPI、矩阵树图和明细表格。
Codex 处理这类统计页时，真正要生成的不只是一个 Vue 页面，而是一条从业务模型、统计接口、缓存刷新、菜单权限到前端可视化的完整链路。只要输入中把真实源码路径、接口地址和统计口径交代清楚，生成出来的代码就更容易接入 ManageBak-ExamEdu 的现有工程结构。