教育管理系统教材配置用Codex自动生成项目代码
教材配置是教育管理系统里承接课程、教案、题库和 APP 教程绑定的基础数据模块。它管理的不是一张普通教材表，而是按学段、学科、版本、册、单元和章节组织起来的树形教材目录，后续教案主体同步、课程文档生成和 NotebookLM 绑定都会依赖这套目录。
本文围绕 server_backend/modules/Config/views_app/TextBook.py 与 server_vue3/src/views/modules/Config/TextBook/ 的真实代码，说明如何把教材目录初始化、树形列表、清空保护和状态回显转换成 Codex 可执行的后端、前端、SOP 和 PDD 任务。
文章目录
设计与需求
教材配置不能只理解成"教材名称的增删改查"。在当前项目中，TextBook 模型保存教材树节点，get_init_menu 读取内置 menu_data 并回填 initialized、version、chapter_initialized，update_subject_book 会按学段、学科和教材 JSON 文件重建目录。这个模块实际承担的是教育资源目录底座，必须先把业务需求拆成页面结构、数据模型、接口规则和权限验收，再交给 Codex 生成项目代码。
教材配置需求
模块设计
页面结构
教材模型
接口规则
权限验收
Codex生成代码
模块交付
| 需求层描述 | 设计层转换 | Codex 代码生成方向 |
|---|---|---|
| 配置中心需要维护教材目录 | 以 TextBook 保存教材册、单元、章节树 |
生成树形模型、懒加载列表和目录初始化接口 |
| 教材来自内置 JSON 数据 | 通过 level、subject、filename 定位 bak_data/textbook 文件 |
生成教材文件读取、版本解析、节点递归写入逻辑 |
| 页面要展示初始化状态 | get_init_menu 返回 initialized、version、chapter_initialized |
生成初始化弹窗、学段标签、学科卡片和状态标签 |
| 教材树需要按父级加载 | 前端使用 pcode 查询子节点并设置 hasChildren |
生成 FastCrud 树表、懒加载和刷新父节点逻辑 |
| 全量初始化有风险 | delete_all 使用 SYSTEM_CLEAR_PASSWORD 校验口令 |
生成清空确认、口令输入、后端事务保护 |
| 后续教案绑定依赖教材路径 | 目录结构需要稳定输出 type_book_level、type_book_subject、version、name |
保证教材目录可被 LessonPlanChapter 初始化复用 |
教材配置的核心对象是树形教材节点。TextBook 模型包含 name、version、code、level、type_book_subject、type_book_level、enable、pcode，其中 code 是唯一编码，pcode 通过自关联表达目录父子关系。Codex 在生成代码时，需要围绕树形目录、初始化状态和清空保护组织任务，不能把它简化成普通表格维护。
可以直接使用下面的Prompt进行模块功能的设计
text
请基于当前教育管理系统源码设计教材配置模块，模块位置为配置中心。不要把它设计成普通 CRUD，而要围绕教材目录初始化、树形教材维护和初始化状态回显完成模块设计。
后端需要参考 server_backend/modules/Config/models.py 中的 TextBook 模型，字段包括 name、version、code、level、type_book_subject、type_book_level、enable、pcode。接口需要参考 server_backend/modules/Config/views_app/TextBook.py，支持教材树列表、懒加载查询、get_init_menu、update_subject_book、delete_all。
教材初始化需要从 server_backend/modules/Config/views_app/bak_data/textbook 下读取内置 JSON 文件，按 level、subject、filename 解析教材版本，按教材册、单元、章节递归写入 TextBook，并清理同学段同学科旧目录。
前端需要参考 server_vue3/src/views/modules/Config/TextBook/index.vue、api.ts、crud.tsx 和 components/InitTextBookDialog.vue，实现 FastCrud 树表、初始化教材弹窗、学段标签、学科卡片、教材文件选择、初始化状态标签、全量清空口令确认和列表刷新。
请输出完整模块设计，覆盖页面结构、模型字段、接口规则、树形目录、初始化流程、清空保护、权限按钮和验收标准，再按当前项目结构生成代码。后端设计
教材配置后端的重点不是堆 CRUD 接口，而是构建可复用的教材目录底座。TextBookViewSet 继承 CustomModelViewSet，列表查询使用 CustomModelInFilter.create_for_model 支持 name、type_book_subject、type_book_level 的模糊筛选；更新序列化使用 PCodeTreeSerializer.update_for_model(TextBook)，让树节点的父子关系能按 pcode 维护。
| 后端设计项 | 设计重点 | Codex 生成方向 |
|---|---|---|
| 数据模型 | TextBook 保存教材名称、版本、编码、层级、学科、学段、启用状态和父级编码 |
生成树形目录模型与自关联字段 |
| 查询筛选 | filterset_class 支持教材名、学科、学段模糊查询 |
生成列表查询和懒加载参数处理 |
| 初始化菜单 | get_init_menu 遍历 menu_data 并检查教材与章节初始化状态 |
生成初始化状态接口和返回结构 |
| 教材初始化 | update_subject_book 校验 subject、level、filename，读取教材 JSON 并递归写入 |
生成事务保护、版本提取、旧数据清理和节点 upsert |
| 清空保护 | delete_all 校验 SYSTEM_CLEAR_PASSWORD 后事务删除全部教材 |
生成口令校验和危险操作响应 |
| 路由注册 | modules/Config/urls.py 注册 TextBookViewSet |
生成 REST 路由与自定义 action |
update_subject_book 是后端设计的核心。它通过 level_map 和 GeneralSubject 生成编码前缀，用 TextBookViewUtils.load_textbook_payload 读取教材 JSON，用 extract_version 从文件名提取版本。写入前按 type_book_subject、type_book_level 和 level 清理旧数据，再通过递归函数生成 code、pcode、level 和 version。这类逻辑需要让 Codex 明确按事务处理，避免初始化失败后留下半截教材树。
可以直接使用下面的Prompt进行后端代码的设计
text
请为教育管理系统配置中心实现教材配置模块后端代码，要求从零设计或补齐现有代码，并严格贴合当前项目结构。
后端模块路径：server_backend/modules/Config/。
模型参考：server_backend/modules/Config/models.py 中的 TextBook。
接口参考：server_backend/modules/Config/views_app/TextBook.py。
请实现 TextBook 数据模型，字段包含 name、version、code、level、type_book_subject、type_book_level、enable、pcode，并保证 code 唯一、pcode 支持自关联树形目录。
请实现 TextBookViewSet，包含教材列表、详情、新增、更新、删除、树形懒加载查询、get_init_menu、update_subject_book、delete_all。列表筛选需要支持 name、type_book_subject、type_book_level 模糊查询，并能按 pcode 查询子节点。
get_init_menu 需要读取 dvadmin.data.textbook.menu_data，返回每个学段和学科的 initialized、version、chapter_initialized 状态。initialized 来自 TextBook，chapter_initialized 来自 LessonPlanChapter 的 text_book 前缀匹配。
update_subject_book 接收 subject、level、filename，校验参数后从 server_backend/modules/Config/views_app/bak_data/textbook 读取对应教材 JSON 文件，解析教材版本，按学段和学科清理旧目录，再递归写入教材册、单元、章节。整个初始化过程需要使用事务保护。
delete_all 需要读取 settings.SYSTEM_CLEAR_PASSWORD，只有口令正确才能清空 TextBook，清空过程使用事务，返回 deleted_rows。
请补齐序列化规则、接口视图、路由注册、筛选查询、权限控制和基础校验，并保证接口返回结构能被 server_vue3/src/views/modules/Config/TextBook/api.ts 和 InitTextBookDialog.vue 使用。前端设计
教材配置前端不是把字段堆到表格上，而是让管理员能查看教材树、初始化指定学科教材、识别已初始化版本，并在危险操作前完成确认。index.vue 只保留 fs-crud 主页面和 InitTextBookDialog actionbar 插槽，表格细节集中在 crud.tsx，接口封装集中在 api.ts。
| 前端设计项 | 设计重点 | Codex 生成方向 |
|---|---|---|
| 页面入口 | index.vue 使用 fs-page、fs-crud 和 InitTextBookDialog |
生成模块主页面和刷新回调 |
| 接口封装 | api.ts 封装 /api/Config/TextBook/、get_init_menu、update_subject_book、delete_all |
生成统一请求函数与初始化接口 |
| 树形列表 | crud.tsx 开启 table.lazy，按 pcode 请求子节点 |
生成树表字段、懒加载和 hasChildren 转换 |
| 字段展示 | 展示 code、version、type_book_level、type_book_subject、name |
生成查询项、列宽和表单隐藏规则 |
| 初始化弹窗 | InitTextBookDialog.vue 使用左侧学段 tabs、学科卡片和教材文件下拉 |
生成初始化交互和状态标签 |
| 清空确认 | 全量初始化调用 ClearAll，通过 ElMessageBox.prompt 输入密码 |
生成危险操作确认和加载状态 |
| 权限按钮 | 初始化教材按钮使用 v-permission="'Update'" |
生成按钮权限控制 |
前端需要注意字段命名一致性。当前 api.ts 的 GetList 会把根节点查询约束到 level = 1，并将 pcode_count 转成 hasChildren，crud.tsx 再用 table.load 按 pcode: row.code 查询子节点。InitTextBookDialog 通过 initMenu 获取菜单状态，选择教材文件后调用 initSubjectBook，成功后更新 subject.initialized 与 subject.version 并触发列表刷新。
可以直接使用下面的Prompt进行前端代码的设计
text
请为教育管理系统配置中心实现教材配置模块前端代码，要求贴合当前 server_vue3 项目和 FastCrud 写法。
前端模块路径：server_vue3/src/views/modules/Config/TextBook/。
需要实现或补齐 index.vue、api.ts、crud.tsx、components/InitTextBookDialog.vue。
index.vue 需要使用 fs-page 和 fs-crud 承载教材树表，并在 actionbar-left 插槽放置 InitTextBookDialog。初始化成功后需要调用 crudExpose.doRefresh 刷新列表。
api.ts 需要封装 /api/Config/TextBook/ 的列表、详情、新增、更新、删除接口，并封装 get_init_menu、update_subject_book、delete_all。GetList 在无 pcode、name、code 时默认查询 level=1，并把 pcode_count 转成 hasChildren。
crud.tsx 需要生成教材树表，字段包含 code、version、type_book_level、type_book_subject、name。表格开启 lazy、children、hasChild，子节点加载时按 pcode=row.code 请求 /api/Config/TextBook/，并保持 hasChildren 转换。新增、编辑、删除按钮按当前页面需要隐藏或控制。
InitTextBookDialog.vue 需要实现初始化教材弹窗：打开时请求 get_init_menu，左侧按学段展示 tabs，右侧按学科展示卡片；每个学科可选择教材 JSON 文件并调用 update_subject_book；卡片显示 initialized、version 状态；全量初始化教材版本需要弹出口令输入框并调用 delete_all。
请保证列表查询、树形懒加载、教材初始化、初始化状态回显、全量清空确认、按钮权限、加载状态和错误提示完整可用。扩展功能
教材配置的扩展能力来自源码中的真实业务逻辑。它不只是维护教材名称，还需要让内置教材 JSON、树形目录、初始化状态和清空保护形成闭环。这些能力超出普通 CRUD，因为它们会影响后续 APP 绑定教程、教案主体同步和课程文档任务。
| 扩展功能 | 主要用途 | 落地重点 |
|---|---|---|
| 数据联动 | 保证教材树、初始化菜单、学段学科和版本状态同步 | get_init_menu、GetList、table.load、初始化刷新要一致 |
| 教材初始化 | 将内置教材 JSON 转成 TextBook 树形目录 |
参数校验、版本解析、编码生成、事务写入 |
| 清空保护 | 约束全量清空教材配置的危险操作 | 口令校验、事务删除、前端确认和结果回显 |
数据联动
教材配置中的数据联动主要发生在列表查询、树形懒加载和初始化弹窗之间。列表根节点按 level=1 查询；点击展开教材册时，前端按 pcode=row.code 请求子节点；初始化弹窗通过 get_init_menu 获取每个学段学科的 initialized、version、chapter_initialized；初始化成功后刷新菜单和树表。
结果阶段
处理阶段
输入阶段
筛选条件
展开节点
选择教材
生成查询参数
请求子节点
初始化教材
刷新菜单
教材树更新
版本回显
状态更新
交给 Codex 生成时，需要明确联动边界：TextBook 的树表数据来自 /api/Config/TextBook/，初始化菜单来自 /api/Config/TextBook/get_init_menu/，教材初始化来自 /api/Config/TextBook/update_subject_book/。初始化成功后，不只更新按钮状态，还要重新拉取菜单并刷新树表，避免页面版本标签和真实目录不一致。
可以直接使用下面的Prompt进行数据联动设计
text
请为教材配置模块实现数据联动逻辑。
模块路径包括 server_backend/modules/Config/views_app/TextBook.py 和 server_vue3/src/views/modules/Config/TextBook/。
列表根节点查询在没有 pcode、name、code 时默认传 level=1。展开树节点时，需要按 pcode=row.code 请求子节点，并将后端 pcode_count 转成前端 hasChildren。
初始化弹窗打开时请求 /api/Config/TextBook/get_init_menu/，按学段 tabs 和学科卡片展示 initialized、version、chapter_initialized。选择教材文件并调用 update_subject_book 成功后，需要更新当前学科 initialized 和 version，再重新请求 get_init_menu，并刷新 fs-crud 列表。
请保证列表筛选、树形懒加载、教材初始化、版本回显、状态标签和列表刷新之间保持一致，避免出现初始化成功但列表或状态不更新的问题。教材初始化
教材初始化是当前模块最重要的扩展能力。后端 update_subject_book 接收 subject、level、filename，从 bak_data/textbook/{level}/{filename} 读取教材 JSON，通过 TextBookViewUtils.extract_version 解析版本，再按教材树层级递归生成 TextBook 节点。写入前会清理同学段同学科的旧数据，保证当前版本目录是干净的。
结果阶段
处理阶段
输入阶段
学段
学科
教材文件
校验参数
读取JSON
解析版本
递归写入
返回版本
刷新教材树
Codex 生成这部分代码时，边界要写清楚：教材文件不是用户上传文件，而是项目内置 JSON；初始化不是追加写入，而是清理同学段同学科旧目录后重建；编码不是随机值，而是由学段编码、学科编码和层级序号拼接；整个过程必须放在事务里。
可以直接使用下面的Prompt进行教材初始化设计
text
请为教材配置模块实现教材初始化功能。
接口为 /api/Config/TextBook/update_subject_book/，请求方法 POST，参数为 subject、level、filename。接口需要校验三个参数均不能为空，并根据 dvadmin.data.textbook.level_map 和 dvadmin.data.dictionary.GeneralSubject 生成教材编码前缀。
请从 server_backend/modules/Config/views_app/bak_data/textbook/{level}/{filename} 读取教材 JSON，调用 TextBookViewUtils.extract_version 提取版本。写入前按 type_book_subject、type_book_level 和 level=3、2、1 的顺序删除旧目录，避免外键约束影响。
请递归读取 JSON 中 result 节点，为每个教材册、单元、章节生成 TextBook 数据。字段包括 name、level、type_book_subject、type_book_level、enable、pcode、code，第一层节点额外写入 version。code 规则为学段编码 + 学科编码 + 每层两位序号。
初始化过程必须使用 transaction.atomic。接口成功后返回 version，并输出明确 msg。前端初始化弹窗需要接收 version 并更新状态标签。清空保护
教材配置有全量清空入口，源码中通过 delete_all 实现。这个能力不是常规删除按钮，它会清空 TextBook 全表，所以后端必须校验 settings.SYSTEM_CLEAR_PASSWORD，前端必须通过 ElMessageBox.prompt 要求输入口令，不能直接暴露无保护的清空接口。
输入口令
后端校验
事务清空
返回数量
刷新页面
Codex 生成这部分时，要把清空保护当成后端能力，而不是只靠前端弹窗。接口缺少口令、口令错误、配置项为空都应该返回错误；口令正确时用事务删除并返回 deleted_rows，前端拿到成功结果后重新请求初始化菜单和教材树。
可以直接使用下面的Prompt进行清空保护设计
text
请为教材配置模块实现全量清空保护功能。
后端接口为 /api/Config/TextBook/delete_all/，请求方法 POST，参数为 password。接口必须校验 password 是否存在，并读取 settings.SYSTEM_CLEAR_PASSWORD 进行比对。未配置口令或口令错误时返回错误响应，不能执行删除。
口令正确时，使用 transaction.atomic 清空 TextBook 数据，并返回 deleted_rows。接口 msg 需要说明教材配置已清空。
前端 InitTextBookDialog.vue 中的全量初始化教材版本按钮需要弹出口令输入框，口令不能为空。确认后调用 delete_all，成功后刷新 get_init_menu 和教材树列表，失败时展示后端错误信息。
请保证危险操作只通过该受保护接口执行，不能在前端绕过口令直接删除教材配置。Codex开发标准
使用 Codex 开发教材配置模块，不能只给一句"做教材管理"。更稳的方式是用需求边界、PDD、SOP、接口权限规则和验收标准约束它，让 Codex 先读取 Config 模块上下文，再按后端、前端和扩展能力分阶段改代码。
验收交付
Codex开发
模块设计
输入约束
需求边界
PDD设计
SOP目录规范
接口与权限规则
后端设计
前端设计
扩展能力
读取上下文
生成后端代码
生成前端代码
补齐初始化逻辑
功能自检
PDD验收
问题修复
模块交付
SOP 标准
SOP 用来约束教材配置的目录、文件职责和开发顺序。当前模块已经有清晰的前后端落点，Codex 需要沿用这些路径补齐功能，不应另建一套教材管理目录。
text
ManageBak-ExamEdu/
├── server_backend/
│ └── modules/
│ └── Config/
│ ├── models.py
│ ├── urls.py
│ ├── utils.py
│ └── views_app/
│ ├── TextBook.py
│ └── bak_data/
│ └── textbook/
│ ├── 普通高中/
│ ├── 普通初中/
│ └── 职业教育编程/
├── server_vue3/
│ └── src/
│ └── views/
│ └── modules/
│ └── Config/
│ └── TextBook/
│ ├── index.vue
│ ├── api.ts
│ ├── crud.tsx
│ └── components/
│ └── InitTextBookDialog.vue
└── docs/
└── modules/
└── config-textbook/
├── pdd.md
├── api.md
├── test-cases.md
└── codex-sop.md| 开发阶段 | Codex 执行目标 | 输出结果 |
|---|---|---|
| 模块设计 | 明确教材配置的树形目录、初始化菜单和清空保护 | pdd.md |
| 目录规划 | 沿用 Config/TextBook 前后端目录 |
codex-sop.md |
| 后端实现 | 补齐模型、视图、筛选、自定义 action、路由 | 后端模块代码 |
| 前端实现 | 补齐树表、接口封装、初始化弹窗、权限按钮 | 前端页面代码 |
| 数据联动 | 打通根节点查询、懒加载、初始化状态和列表刷新 | 联动逻辑代码 |
| 功能补齐 | 完成教材初始化和清空保护 | 初始化与保护代码 |
| 验收修复 | 按 PDD 检查接口、页面、状态回显和危险操作 | 验收记录与修复提交 |
可以直接使用下面的Prompt进行SOP撰写
text
请按照教育管理系统模块开发 SOP，从零实现或补齐配置中心的教材配置模块。
开发前先输出目录结构，不要直接写代码。目录必须贴合当前项目：后端放在 server_backend/modules/Config/，前端放在 server_vue3/src/views/modules/Config/TextBook/，文档放在 docs/modules/config-textbook/。
请先生成 docs/modules/config-textbook/pdd.md、api.md、test-cases.md 和 codex-sop.md。文档需要明确 TextBook 模型字段、教材树列表、get_init_menu、update_subject_book、delete_all、树形懒加载、初始化弹窗、权限按钮和验收规则。
文档确认后，再根据 SOP 生成或补齐后端模型、序列化、接口视图、路由注册、筛选查询、权限控制、前端页面、接口封装、FastCrud 树表和 InitTextBookDialog。
实现过程中不得新增代码里不存在的 LLM、OCR、审批、统计、导入导出功能。只实现教材配置真实需要的树形目录、教材初始化、数据联动和清空保护。PDD 标准
PDD 是教材配置的设计与验收文档，用来约束 Codex 输出是否符合真实业务。对这个模块来说，验收不能只看列表能不能打开，还要检查教材 JSON 是否能转成树、初始化状态是否回显、清空保护是否在后端生效。
| 验收维度 | 验收标准 | 不通过表现 |
|---|---|---|
| 业务目标 | 能维护配置中心教材目录，并支撑后续教案与 APP 绑定 | 只生成普通教材名称列表 |
| 页面结构 | 包含教材树表、初始化教材弹窗、学段 tabs、学科卡片 | 初始化入口缺失或状态不可见 |
| 数据模型 | TextBook 字段覆盖 name、version、code、level、type_book_subject、type_book_level、enable、pcode |
字段与后端模型不一致 |
| 接口规则 | /api/Config/TextBook/、get_init_menu、update_subject_book、delete_all 可用 |
前端按钮存在但接口缺失 |
| 权限控制 | 初始化按钮有 Update 权限约束，清空接口有口令校验 |
仅前端确认，后端可直接清空 |
| 测试用例 | 覆盖根节点查询、子节点懒加载、单学科初始化、口令错误、清空成功 | 只有页面截图，没有可执行验收路径 |
| 数据联动 | 初始化成功后菜单状态、版本标签和教材树同步刷新 | 初始化成功但页面仍显示未初始化 |
| 教材初始化 | 内置 JSON 能按层级写入 TextBook，同学段同学科旧数据会清理 |
重复初始化产生脏数据 |
| 清空保护 | 口令缺失或错误不删除，口令正确返回 deleted_rows |
危险操作无后端保护 |
可以直接使用下面的Prompt进行PDD 验收
text
请根据 docs/modules/config-textbook/pdd.md 对教材配置模块进行 PDD 验收。
验收范围包括 server_backend/modules/Config/models.py、server_backend/modules/Config/views_app/TextBook.py、server_backend/modules/Config/utils.py、server_backend/modules/Config/urls.py，以及 server_vue3/src/views/modules/Config/TextBook/index.vue、api.ts、crud.tsx、components/InitTextBookDialog.vue。
请检查 TextBook 字段是否完整，教材树列表和懒加载是否可用，get_init_menu 是否返回 initialized、version、chapter_initialized，update_subject_book 是否按 subject、level、filename 读取内置 JSON 并事务写入教材树，delete_all 是否使用 SYSTEM_CLEAR_PASSWORD 做后端口令校验。
请检查前端是否包含 FastCrud 树表、初始化教材弹窗、学段 tabs、学科卡片、教材文件选择、初始化状态标签、全量清空口令确认、Update 权限按钮和初始化后刷新逻辑。
请输出验收结果表，标记通过、未通过和需要修复的文件位置。不要只给结论，需要指出具体问题、影响范围和修复建议。总结
教材配置模块的价值不在于维护几条教材名称，而在于把学段、学科、版本、教材册、单元和章节沉淀成教育管理系统可复用的目录底座。它会影响教案主体、APP 绑定教程和课程文档任务，因此更接近资源配置闭环模块，而不是普通 CRUD 页面。
使用 Codex 开发这类模块时，PDD 要定义教材树、初始化接口、清空保护和验收标准，SOP 要约束 Config/TextBook 的目录结构和开发顺序，Prompt 要把页面、模型、接口、权限和真实扩展能力分阶段交给 Codex 实现。