【Codex】用班级设置模块维护教学组织基础数据

教育管理系统班级设置模块用Codex生成项目代码

班级设置是教育管理系统中学生分班、行政班管理和选科走班的基础配置模块。它维护班级类型、年级分类、父子层级和启用状态，为学生管理、考试安排和班级分析提供统一班级口径。

本文基于 StudentClasses 模型、StudentClassesViewSet、Excel 初始化接口和 FastCrud 树表页面，说明如何把班级层级、模板下载、文件导入、清空配置和页面懒加载，转换成 Codex 可执行的项目代码生成任务。

文章目录

• 设计与需求
• • 后端设计
  • 前端设计
• 扩展功能
• • 数据联动
  • 导入导出
  • 文件管理
• Codex开发标准
• • [SOP 标准](#SOP 标准)
  • [PDD 标准](#PDD 标准)
• 总结

设计与需求

班级设置不能只理解成普通 CRUD。server_backend/modules/Config/models.py 中的 StudentClasses 使用 code 和 pcode 建立父子关系，category 区分年级分类，type_class 和 type_class_level 表示班级类型。后端接口位于 server_backend/modules/Config/views_app/StudentClasses.py，前端页面位于 server_vue3/src/views/modules/Config/StudentClasses/index.vue、api.ts、crud.tsx 和 components/SchoolDataInit.vue。

交给 Codex 的任务需要把业务需求拆成树形模型、模板下载、Excel 上传导入、内置模板初始化、接口权限和前端联动。页面不仅要能维护班级节点，还要通过"初始化数据"弹窗下载模板、上传 xls/xlsx、按 category 覆盖同类别数据，并支持清空全部班级配置。
验收阶段
生成阶段
设计阶段
输入阶段
班级配置
模板文件
源码上下文
树形模型
初始化接口
导入导出
权限验收
读取源码
生成后端
生成前端
联动检查
PDD验收

需求层描述	设计层转换	Codex 代码生成方向
班级配置需要层级结构	使用 code、pcode、level 表达父子关系。	生成树形模型、懒加载查询和父级刷新。
班级类型需要分类	使用 category、type_class、type_class_level 区分行政班、选科走班等类型。	生成筛选、表单字典和选择接口。
初始化需要模板	后端提供普通高中、培训学校、职业教育模板下载任务。	生成模板下载按钮、下载中心任务和异常提示。
导入需要 Excel	前端上传 xls/xlsx 到 api/system/file/，后端按 URL 下载并解析。	生成上传组件、文件地址校验、导入结果回显。
数据需要可清空	delete_all 在事务中删除全部班级配置。	生成高危确认、权限控制和 PDD 验收。
其他模块需要选班	get_classes 按 category 或 type_class 返回班级树。	生成选择接口说明和联调用例。

可以直接使用下面的Prompt进行模块功能的设计

请 Codex 基于教育管理系统真实源码设计"班级设置"模块。

模块定位：
班级设置用于维护行政班、选科走班、小三科等班级类型配置，支持树形维护、模板下载、Excel 上传导入、内置模板初始化、清空配置和班级选择接口。

源码范围：
server_backend/modules/Config/models.py
server_backend/modules/Config/views_app/StudentClasses.py
server_backend/modules/Config/utils.py
server_vue3/src/views/modules/Config/StudentClasses/index.vue
server_vue3/src/views/modules/Config/StudentClasses/api.ts
server_vue3/src/views/modules/Config/StudentClasses/crud.tsx
server_vue3/src/views/modules/Config/StudentClasses/components/SchoolDataInit.vue

核心字段：
name：班级设置名称
category：年级分类
code：班级编码
level：班级类型层级
type_class：班级类型
type_class_level：班级大类名称
enable：是否启用
pcode：父级编码

接口范围：
GET/POST/PUT/DELETE /api/Config/StudentClasses/
POST /api/Config/StudentClasses/export_template_download_task/
GET /api/Config/StudentClasses/get_init_data_high_school/
GET /api/Config/StudentClasses/get_init_data_training_school/
GET /api/Config/StudentClasses/get_init_data_vocational_education/
POST /api/Config/StudentClasses/update_init_data/
POST /api/Config/StudentClasses/update_init_data_preset/
POST /api/Config/StudentClasses/delete_all/
GET /api/Config/StudentClasses/get_classes/

设计要求：
1. 输出页面结构、数据模型、接口规则、权限边界和验收标准。
2. 说明 code、pcode、level 如何构成树形结构。
3. 说明模板下载、文件上传、Excel 导入和清空配置的流程。
4. 说明 get_classes 如何为其他模块提供班级选择数据。
5. 只允许设计源码中存在的数据联动、导入导出和文件管理能力。

后端设计

后端设计重点不是堆班级字典接口，而是保证班级层级、初始化和导入流程可复用。StudentClasses 模型包含 name、category、code、level、type_class、type_class_level、enable、pcode。其中 code 唯一，pcode 指向自身 code 字段，用于形成树形结构。

StudentClassesViewSet 使用 PCodeTreeSerializer 处理树形序列化。get_queryset 根据 type 参数筛选行政班、选科走班、小三科或指定二级目录下的班级叶子节点。create 通过 StudentClassesViewUtils.prepare_create_payload 自动准备新增载荷，遇到唯一编码冲突会重试。destroy 通过工具类校验删除目标，避免破坏层级结构。

初始化能力集中在模板和 Excel 流程。export_template_download_task 会读取内置模板并通过 create_download_center_task 创建下载任务；update_init_data 会根据上传后的 URL 下载 Excel 并调用 import_with_category_isolation，按 category 隔离覆盖；update_init_data_preset 直接读取内置模板初始化；delete_all 在事务中清空全部配置。

后端设计项	设计重点	Codex 生成方向
树形模型	code 唯一，pcode 指向自身，level 表示层级。	生成父子节点校验、树形序列化和懒加载查询。
类型筛选	type、category、type_class 决定班级选择范围。	生成行政班、学科班和指定类型选择接口。
模板下载	export_template_download_task 创建下载中心任务。	生成模板 key、文件读取、下载任务和错误响应。
Excel 导入	update_init_data 下载上传文件并按类别隔离导入。	生成 URL 规范化、文件下载、解析和导入结果。
预设初始化	update_init_data_preset 使用内置模板初始化。	生成模板校验、内置文件读取和结果回显。
清空配置	delete_all 在事务中删除全部记录。	生成高危权限、确认流程和审计说明。

可以直接使用下面的Prompt进行后端代码的设计

请 Codex 按"班级设置"业务从零设计或补齐后端代码。

后端源码范围：
server_backend/modules/Config/models.py
server_backend/modules/Config/views_app/StudentClasses.py
server_backend/modules/Config/utils.py
dvadmin/data/student_classes_utils.py

必须遵守的现有结构：
1. 模型为 StudentClasses，字段包含 name、category、code、level、type_class、type_class_level、enable、pcode。
2. code 是唯一编码，pcode 通过 to_field=code 指向父级。
3. ViewSet 为 StudentClassesViewSet，序列化使用 PCodeTreeSerializer。
4. 接口前缀为 /api/Config/StudentClasses/。

需要实现或校准：
1. 列表查询支持根节点默认 level=1，子节点按 pcode 查询。
2. get_queryset 支持 type 参数过滤行政班、学科班或指定类型。
3. export_template_download_task 创建下载中心任务。
4. update_init_data 根据上传 URL 下载 Excel 并按 category 隔离导入。
5. update_init_data_preset 使用内置模板初始化。
6. delete_all 清空全部配置，必须有权限和确认边界。
7. get_classes 按 category 或 type_class 返回班级选择树。

输出涉及文件、模型字段、接口返回结构、权限规则、异常响应和测试建议。

前端设计

前端设计重点是让配置人员在树表中维护班级层级，并通过初始化弹窗完成模板下载和 Excel 导入。index.vue 使用 fs-crud，在 actionbar-right 放入 SchoolDataInit。页面挂载后执行 crudExpose.doRefresh()，初始化弹窗通过 inject('refreshView') 触发列表刷新。

api.ts 中的 GetList 会在没有 pcode、name、code 时默认补 level=1，并将 pcode_count 转成 hasChildren。crud.tsx 开启 table.lazy，展开节点时请求 /api/Config/StudentClasses/ 并传 pcode=row.code。SchoolDataInit.vue 提供模板下载、Excel 上传、提交导入和清空配置按钮，上传目标为 api/system/file/，成功后把返回的 url 交给 InitData。

前端设计项	设计重点	Codex 生成方向
页面容器	index.vue 使用 fs-page、fs-crud 和 SchoolDataInit。	生成初始化入口、刷新注入和挂载刷新。
树表查询	根节点默认 level=1，子节点按 pcode 查询。	生成懒加载、hasChildren 标记和父节点刷新。
模板下载	DownloadInitTemplate(template) 调用下载任务接口。	生成模板按钮、下载成功提示和失败提示。
文件上传	el-upload 限制 .xlsx,.xls，上传到 api/system/file/。	生成 token header、上传状态和文件地址校验。
导入提交	上传成功后调用 InitData({ url })。	生成导入 loading、结果提示和列表刷新。
清空配置	handleClearAll 使用 ElMessageBox.confirm 二次确认。	生成高危操作防护和成功刷新。

可以直接使用下面的Prompt进行前端代码的设计

请 Codex 按"班级设置"业务生成或补齐前端页面代码。

前端源码范围：
server_vue3/src/views/modules/Config/StudentClasses/index.vue
server_vue3/src/views/modules/Config/StudentClasses/api.ts
server_vue3/src/views/modules/Config/StudentClasses/crud.tsx
server_vue3/src/views/modules/Config/StudentClasses/components/SchoolDataInit.vue

页面现状：
1. index.vue 使用 fs-page 和 fs-crud。
2. actionbar-right 放置 SchoolDataInit。
3. GetList 在根节点查询时默认补 level=1。
4. GetList 将 pcode_count 转成 hasChildren。
5. crud.tsx 开启 table.lazy，展开节点时按 pcode 查询。
6. SchoolDataInit 支持模板下载、Excel 上传导入和清空配置。

需要生成或修正：
1. 保持树表懒加载和父节点刷新。
2. 模板下载按钮对应 high_school、training_school、vocational_education。
3. 上传组件只接受 xls/xlsx，并带 Authorization header。
4. 上传成功后必须校验响应 url，再调用 InitData。
5. 清空全部配置必须二次确认。
6. 不生成源码中不存在的审批或图表入口。

输出页面结构、API 封装、树表配置、初始化弹窗、文件上传、导入结果、异常提示和验收步骤。

扩展功能

班级设置的扩展能力集中在数据联动、导入导出和文件管理。它超出普通 CRUD 的地方，是班级树、Excel 模板、上传文件、下载中心任务和初始化结果都要形成闭环。

扩展功能	主要用途	落地重点
数据联动	将 code、pcode、level、type_class 和树表懒加载串成稳定数据流。	前端 hasChildren、后端 pcode_count 和父级刷新必须一致。
导入导出	下载内置模板，上传 Excel 后按类别初始化班级配置。	模板 key、上传 URL、导入结果和错误提示必须清晰。
文件管理	管理 Excel 文件上传和下载中心任务。	上传文件只作为导入来源，下载模板通过下载中心交付。

数据联动

数据联动围绕树形班级结构展开。前端首次查询根节点时传 level=1，展开节点时传 pcode，后端返回 pcode_count，前端转换成 hasChildren。删除子节点后，前端会刷新父节点状态，避免树表展开图标失真。
结果阶段
处理阶段
输入阶段
根节点
父级编码
班级类型
生成参数
查询接口
转换标记
树表展示
节点展开
父级刷新

交给 Codex 生成时，不能把 code、pcode、level 当普通文本处理。新增节点需要知道父级编码，删除节点要刷新父节点，选择班级时要明确使用 category 还是 type_class。

可以直接使用下面的Prompt进行数据联动设计

请 Codex 基于真实源码补齐"班级设置"的数据联动能力。

源码范围：
server_backend/modules/Config/models.py
server_backend/modules/Config/views_app/StudentClasses.py
server_vue3/src/views/modules/Config/StudentClasses/index.vue
server_vue3/src/views/modules/Config/StudentClasses/api.ts
server_vue3/src/views/modules/Config/StudentClasses/crud.tsx

联动对象：
code、pcode、level、category、type_class、type_class_level、enable、pcode_count、hasChildren

联动要求：
1. 根节点查询默认 level=1。
2. 子节点展开按 pcode 查询。
3. 后端 pcode_count 要转换为前端 hasChildren。
4. 删除子节点后刷新父节点状态。
5. get_classes 支持 category 和 type_class 两种选择方式。
6. 不新增源码中不存在的业务能力。

输出接口设计、前端交互、字段转换、异常处理、权限约束和验收清单。

导入导出

导入导出能力来自班级初始化流程。后端内置三类模板：普通高中、培训学校、职业教育；前端通过 DownloadInitTemplate 创建下载中心任务。导入时，前端把 Excel 上传到系统文件接口，再把返回的 URL 交给 update_init_data，后端下载文件并按 category 隔离覆盖。
结果阶段
处理阶段
输入阶段
模板选择
Excel文件
下载任务
上传文件
解析导入
任务创建
导入结果
列表刷新

Codex 生成时要明确模板 key 和中文名称的映射，导入失败不能吞掉错误，导入成功后要清空上传列表并刷新树表。

可以直接使用下面的Prompt进行导入导出功能设计

请 Codex 基于真实源码补齐"班级设置"的导入导出能力。

后端接口：
POST /api/Config/StudentClasses/export_template_download_task/
POST /api/Config/StudentClasses/update_init_data/
POST /api/Config/StudentClasses/update_init_data_preset/

前端组件：
server_vue3/src/views/modules/Config/StudentClasses/components/SchoolDataInit.vue

设计要求：
1. 支持 high_school、training_school、vocational_education 三类模板。
2. 模板下载通过下载中心任务交付。
3. Excel 上传只接受 xls/xlsx。
4. 上传成功后读取 response.data.url，再调用 InitData。
5. 导入按 category 覆盖同类别数据，不影响其他类别。
6. 导入成功后清空上传文件并刷新树表。

输出后端流程、前端交互、异常边界和验收用例。

文件管理

文件管理能力体现在 Excel 上传和模板下载任务。上传文件走 api/system/file/，并携带 JWT 认证头；模板下载不直接返回文件流给前端，而是创建下载中心任务，让用户到下载中心获取模板。
结果阶段
处理阶段
输入阶段
上传Excel
模板文件
系统上传
URL校验
创建任务
导入来源
下载中心

文件上传结果不能直接当作导入成功。前端必须拿到上传响应中的文件 URL，再调用后端导入接口；后端必须对 URL 做规范化和文件下载校验。

可以直接使用下面的Prompt进行文件管理功能设计

请 Codex 基于真实源码补齐"班级设置"的文件管理能力。

源码范围：
server_vue3/src/views/modules/Config/StudentClasses/components/SchoolDataInit.vue
server_backend/modules/Config/views_app/StudentClasses.py

文件能力：
Excel 上传
模板下载中心任务

设计要求：
1. 上传地址为 api/system/file/。
2. 上传请求带 Authorization JWT。
3. 只接受 xls/xlsx 文件。
4. 上传成功后校验 response.data.url。
5. 模板下载创建下载中心任务，不在页面直接拼文件流。
6. 文件上传失败、URL 缺失、下载任务创建失败都要提示。

输出前端组件设计、后端接口边界、异常处理和验收用例。

Codex开发标准

使用 Codex 开发班级设置模块时，不能只生成一个班级列表。PDD、SOP、接口权限规则和验收标准需要同时约束树形模型、Excel 初始化、文件上传、下载任务和危险操作。
验收交付
Codex开发
模块设计
输入约束
需求边界
PDD设计
SOP目录
接口权限
后端设计
前端设计
导入导出
读取上下文
生成后端
生成前端
联动补齐
功能自检
PDD验收
问题修复
模块交付

SOP 标准

SOP 用于约束代码目录、文件职责和开发顺序。班级设置模块需要同时维护模型、ViewSet、工具类、前端 API、树表页面、初始化弹窗和模块文档。

docs/modules/班级设置/
├── pdd.md
├── api.md
├── test-cases.md
└── codex-sop.md

server_backend/modules/Config/
├── models.py
├── utils.py
└── views_app/
    └── StudentClasses.py

server_vue3/src/views/modules/Config/StudentClasses/
├── index.vue
├── api.ts
├── crud.tsx
└── components/
    └── SchoolDataInit.vue

开发阶段	Codex 执行目标	输出结果
模块设计	读取 StudentClasses、StudentClassesViewSet、前端 api.ts/crud.tsx/index.vue。	输出字段、接口、树形结构和初始化边界。
文档规划	建立 PDD、API、测试和 SOP 文档。	形成 pdd.md、api.md、test-cases.md、codex-sop.md。
后端实现	校准树形模型、模板下载、Excel 导入、预设初始化、清空配置和选择接口。	后端接口可支撑树表和初始化。
前端实现	校准树表懒加载、初始化弹窗、上传导入、清空确认和保存回显。	页面可维护班级配置树。
数据联动	打通 code、pcode、level、pcode_count 和 hasChildren。	前后端树形口径一致。
验收修复	按 PDD 检查接口、权限、导入、下载、清空和异常。	输出验收结果与需修复文件位置。

可以直接使用下面的Prompt进行SOP撰写

请 Codex 按教育管理系统模块开发 SOP，从零实现或补齐"班级设置"模块。

执行要求：
1. 先输出目录结构，不要直接写代码。
2. 先生成 docs/modules/班级设置/pdd.md、api.md、test-cases.md 和 codex-sop.md。
3. 文档确认模块边界后，再根据文档生成或修正项目代码。
4. 后端范围限定在 Config/models.py、Config/views_app/StudentClasses.py、Config/utils.py。
5. 前端范围限定在 Config/StudentClasses/index.vue、api.ts、crud.tsx 和 SchoolDataInit.vue。
6. 后端需要覆盖树形模型、列表查询、模板下载、Excel 导入、预设初始化、清空配置、get_classes。
7. 前端需要覆盖树表懒加载、初始化入口、模板下载、文件上传、导入提交、清空确认、字段回显。
8. 不生成源码中不存在的扩展能力。

输出目录结构、开发阶段表、后端任务清单、前端任务清单、导入导出清单和验收修复清单。

PDD 标准

PDD 是模块设计与验收文档，用来约束 Codex 输出是否符合真实业务。班级设置模块的 PDD 要把树形字段、模板下载、Excel 导入、清空配置、前端懒加载和权限边界写成可验证条目。

验收维度	验收标准	需要检查的文件
业务目标	模块能维护班级层级和班级类型，为分班、考试和分析提供统一口径。	pdd.md、models.py、StudentClasses.py
页面结构	页面包含树表、初始化弹窗、模板下载、文件上传、清空确认、节点删除。	index.vue、crud.tsx、SchoolDataInit.vue
数据模型	StudentClasses 字段覆盖 name、category、code、level、type_class、type_class_level、enable、pcode。	models.py
接口规则	列表、详情、新增、更新、删除、模板下载、导入、预设初始化、清空、选择接口可用。	StudentClasses.py、api.ts、api.md
权限控制	导入、清空、删除节点需要明确权限和误操作防护。	StudentClasses.py、SchoolDataInit.vue
数据联动	code、pcode、level、pcode_count、hasChildren 前后端一致。	StudentClasses.py、api.ts、crud.tsx
导入导出	模板下载任务、Excel 上传、URL 校验、导入结果、列表刷新完整。	StudentClasses.py、SchoolDataInit.vue
文件管理	上传限制、认证头、文件 URL、下载中心任务处理完整。	SchoolDataInit.vue、StudentClasses.py
测试用例	覆盖根节点查询、子节点展开、模板下载、上传导入、预设初始化、清空、无效参数。	test-cases.md

可以直接使用下面的Prompt进行PDD 验收

请 Codex 根据 docs/modules/班级设置/pdd.md 对"班级设置"模块进行验收。

验收范围：
server_backend/modules/Config/models.py
server_backend/modules/Config/views_app/StudentClasses.py
server_backend/modules/Config/utils.py
server_vue3/src/views/modules/Config/StudentClasses/index.vue
server_vue3/src/views/modules/Config/StudentClasses/api.ts
server_vue3/src/views/modules/Config/StudentClasses/crud.tsx
server_vue3/src/views/modules/Config/StudentClasses/components/SchoolDataInit.vue
docs/modules/班级设置/api.md
docs/modules/班级设置/test-cases.md

验收维度：
1. 业务目标：是否能维护班级层级和类型。
2. 页面结构：是否包含树表、初始化弹窗、模板下载、上传导入和清空确认。
3. 数据模型：StudentClasses 字段和树形关系是否正确。
4. 接口规则：列表、导入、导出、预设初始化、清空、选择接口是否可用。
5. 权限控制：危险操作是否有权限与确认。
6. 数据联动：pcode_count、hasChildren、pcode、level 是否一致。
7. 导入导出：模板下载和 Excel 导入是否可验收。
8. 文件管理：上传限制、认证头和文件 URL 是否完整。
9. 测试用例：是否覆盖成功路径和失败路径。

输出验收结果表，标记通过、未通过和需要修复的文件位置。不要只给结论，需要指出具体问题、影响范围和修复建议。

总结

班级设置不是普通字典表，而是教育管理系统中支撑学生分班、行政班管理和选科走班的配置闭环。它通过 code、pcode 和 level 维护层级，通过模板下载和 Excel 导入降低初始化成本。

用 Codex 开发该模块时，PDD 负责定义树形结构和验收标准，SOP 负责约束目录结构和开发顺序，Prompt 负责把模型、接口、页面、权限、数据联动、导入导出和文件管理拆成分阶段任务。这样生成的代码更容易支撑真实配置维护。