_sop_workflow/server 是教育管理系统中面向 Codex 自动化开发的工程规范目录。它不是普通说明文档，而是一套把 Django 后端、Vue3 前端、菜单权限、图标资源、三方 AI 服务和验收流程串起来的 SOP 标准。
这套 SOP 的目标很明确：当一个新管理模块进入开发时，不再临时口头描述"做个页面和接口"，而是让 Codex 按固定输入、固定目录、固定权限、固定验收顺序完成前后端模块交付。
文章目录
目录定位
当前 server 目录主要包含三类规范：常规后台模块开发、三方服务模块开发、后端 ViewSet Action 规范。它们共同服务 ManageBak-ExamEdu 这个 Django + Vue3 前后端项目。
text
_sop_workflow/server/
README.md
01.管理后台模块开发SOP.md
02.三方服务模块开发SOP.md
03.后端视图 Action 规范改造SOP.md| 文档 | 适用场景 | Codex 自动化开发价值 |
|---|---|---|
01.管理后台模块开发SOP.md |
常规 Django + Vue3 管理模块 | 统一后端接口、前端 CRUD、菜单权限、icon 和验收 |
02.三方服务模块开发SOP.md |
LLM/OCR/TTS/ASR/WORKFLOW 等 AI 服务模块 | 统一平台配置、默认配置、系统配置同步和异步任务 |
03.后端视图 Action 规范改造SOP.md |
ViewSet 中的自定义 @action 接口 |
统一接口命名、docstring、前端路径和按钮权限 |
systemWorkWorkbenches |
三方服务子模块 PDD/SOP | 沉淀 LLM、OCR、TTS、ASR 的差异化交付标准 |
项目架构
这套 SOP 服务的是一个真实的 Django + Vue3 教育管理后台项目。Django 后端负责数据模型、接口视图、路由注册、权限控制、菜单数据、系统配置、异步任务和三方 AI 服务；Vue3 前端负责后台页面、菜单路由、接口封装、CRUD 配置、表单交互、按钮权限和保存回显。
常规模块的后端入口通常在 server_backend/modules/<Module>/，前端入口通常在 server_vue3/src/views/modules/<Module>/<ModelName>/。Codex 生成代码时，不能脱离这两个目录结构，否则生成出来的页面和接口很难接入现有后台。
Django模型
ViewSet接口
路由注册
菜单权限
Vue3页面
api封装
CRUD配置
角色授权
SOP验收
| 层级 | 典型文件 | 开发重点 |
|---|---|---|
| Django 模型层 | server_backend/modules/<Module>/models.py |
字段、默认值、枚举、软删除、关联关系 |
| Django 接口层 | views_app/<ModelName>.py、urls.py |
ViewSet、序列化、筛选、权限、Action |
| Django 工具层 | modules/<Module>/utils.py |
查询、参数处理、任务、资源等复杂逻辑复用 |
| Vue3 页面层 | index.vue |
页面容器、复杂交互、刷新、弹窗、状态 |
| Vue3 配置层 | crud.tsx |
列表、搜索、表单、字段格式化、保存回显 |
| Vue3 接口层 | api.ts |
API 前缀、CRUD 方法、自定义 Action 调用 |
| 系统配置层 | Menu、按钮权限、角色权限、icon、image | 菜单可见、按钮可用、图标路径真实 |
SOP开发闭环
server 目录里的 SOP 把 Codex 开发拆成四个阶段：输入约束、模块设计、代码生成、验收交付。这样做的价值，是让每次新增模块都能复用相同的开发路径，而不是每次重新解释项目结构。
验收交付
代码生成
模块设计
输入约束
ORM位置
目标模型
菜单挂载
特殊要求
后端接口
前端页面
菜单权限
图标规范
生成ViewSet
生成Vue页面
同步菜单
补齐权限
后端check
前端build
菜单回查
页面自测
| 阶段 | 输入 | Codex 输出 |
|---|---|---|
| 需求输入 | ORM 文件、模型名、菜单分组、中文名、特殊要求 | 模块开发任务边界 |
| 后端生成 | 模型字段、软删除、筛选需求、Action 需求 | views_app、urls.py、utils.py |
| 前端生成 | 页面目录、接口前缀、列表字段、表单字段 | api.ts、crud.tsx、index.vue |
| 系统接入 | 菜单层级、按钮权限、角色权限、icon 路径 | 菜单同步命令与图标文件 |
| 验收交付 | check、migrate、build、菜单回查、页面自测 | 变更摘要、文件清单、校验结果 |
常规模块开发
常规后台模块优先按 01.管理后台模块开发SOP.md 执行。这个 SOP 的核心是"后端 + 前端 + 菜单 + icon + 权限一体化"，也就是说，一个模块只有接口和页面还不算完成，必须在后台菜单中可见、角色权限可用、按钮权限完整、图标路径真实。
最小输入很克制：ORM 文件位置、目标模型类名、模块归属、菜单分组结构、菜单中文名。Codex 只要拿到这些信息，就能按现有项目规范生成后端 ViewSet、前端 FastCrud 页面、路由注册、菜单权限和交付检查。
后端生成标准
后端视图统一放在 server_backend/modules/<Module>/views_app/。每个模型对应一个 <ModelName>.py，默认包含 ViewSet、序列化规则、筛选字段和 HTTP 方法约束。路由在 modules/<Module>/urls.py 注册。
views_app 文件要保持薄。复杂业务逻辑不能散落成顶层函数，而要沉淀到 server_backend/modules/<Module>/utils.py，并按工具类组织，例如 <Domain>QueryUtils、<Domain>ParamUtils、<Domain>TaskUtils、<Domain>ResourceUtils。
| 后端文件 | 职责 | Codex 生成要求 |
|---|---|---|
models.py |
ORM 数据模型 | 读取字段、枚举、默认值、软删除能力 |
views_app/<ModelName>.py |
API 视图 | 生成 ViewSet、序列化、筛选、权限和 Action |
urls.py |
路由注册 | 注册 /api/<Module>/<ModelName>/ |
utils.py |
复杂业务工具 | 下沉查询、参数、任务、资源处理逻辑 |
前端生成标准
前端页面统一落在 server_vue3/src/views/modules/<Module>/<ModelName>/。一个常规模块至少包含 api.ts、crud.tsx、index.vue 三个文件。
api.ts 负责接口前缀和方法封装，crud.tsx 负责列表、搜索、表单和字段转换，index.vue 负责页面容器和刷新逻辑。这样 Codex 生成的代码能与现有 Vue3 管理后台保持一致，不会变成孤立页面。
| 前端文件 | 职责 | Codex 生成要求 |
|---|---|---|
api.ts |
API 封装 | 导出 apiPrefix、GetList、GetObj、AddObj、UpdateObj、DelObj |
crud.tsx |
CRUD 配置 | 生成 columns、search、form、formatter、保存转换 |
index.vue |
页面入口 | 使用 <fs-page><fs-crud /></fs-page> 与 useFs |
可以直接使用下面的Prompt进行常规管理模块开发
text
请按 `_sop_workflow/server/01.管理后台模块开发SOP.md` 执行一个 Django + Vue3 管理后台模块开发任务。
输入信息：
1. ORM位置：server_backend/modules/<Module>/models.py
2. 目标模型：<ModelName>
3. 模块归属：modules/<Module>
4. 菜单挂载：<一级目录> > <二级分组>
5. 菜单中文名：<中文名>
6. 特殊要求：没有就写"无"
开发要求：
1. 后端生成 server_backend/modules/<Module>/views_app/<ModelName>.py。
2. 后端在 server_backend/modules/<Module>/urls.py 注册路由。
3. 复杂逻辑下沉到 server_backend/modules/<Module>/utils.py，不在 views_app 中新增顶层 def。
4. 前端生成 server_vue3/src/views/modules/<Module>/<ModelName>/api.ts、crud.tsx、index.vue。
5. 生成菜单节点、按钮权限、角色权限同步方案。
6. 生成 SVG icon，并同步 menu.icon 与 menu.image。
7. 输出需要执行的 check、migrate、build、菜单同步和菜单回查命令。
请先输出文件结构、接口清单、菜单权限清单和验收步骤，再开始修改代码。菜单权限与图标
菜单权限是这个 SOP 里很重要的一环。后台管理模块不是代码生成完就结束，而是要写入菜单树，并把按钮权限绑定到对应 API。叶子菜单需要维护 web_path、component、component_name、is_catalog、visible、status、icon、image 等字段。
按钮权限默认包含查询、详情、新增、编辑、删除。自定义 Action 则需要补充对应权限点，并同步前端按钮和接口路径。SOP 还要求使用可重复执行的管理命令同步菜单，支持 --dry-run，避免手工改库导致环境不一致。
| 菜单字段 | 标准值 | 作用 |
|---|---|---|
web_path |
/modules/<Module>/<ModelName> |
前端访问路径 |
component |
modules/<Module>/<ModelName>/index |
Vue 页面组件 |
component_name |
<ModelName> |
菜单和路由标识 |
icon |
ele-* 或 iconfont icon-* |
侧栏菜单图标 |
image |
media/icon/modules/<Module>/<ModelName>.svg |
工作台卡片图标 |
图标统一使用 SVG。业务模块图标放在 server_backend/media/icon/modules/<Module>/，系统类图标放在 server_backend/media/icon/system/，三方服务图标放在 server_backend/media/icon/system/ThirdPartyService/。当前 SOP 统一采用 320x200 的卡片风格，避免后台工作台出现图标风格混乱。
三方服务模块
三方服务模块按 02.三方服务模块开发SOP.md 执行，适用于 LLM、OCR、TTS、ASR、AUDIOCLONE、WORKFLOW、TencentAgent 等能力。这类模块和普通 CRUD 不同，重点不只是页面和接口，而是平台配置、默认配置、应用配置、系统配置同步、异步任务、计费积分和厂商差异。
后端公共能力集中在 server_backend/dvadmin/third_party_service。子模块标准结构至少包含 api.py、setting.py、provider_xxx.py、__init__.py。API 层只做参数解析、调用服务类和组装响应，不承载大段业务逻辑。
| 服务模块 | 关键能力 | 验收重点 |
|---|---|---|
| LLM | 厂商配置、模型管理、默认模型分组 | text/reasoning/function_calling 可保存可回显 |
| OCR | 厂商配置、鉴权差异、默认厂商 | api_key 与 secret_id/secret_key 差异正确 |
| TTS | 语音合成厂商与默认配置 | 配置保存、默认服务、调用参数稳定 |
| ASR | 音频转录厂商与异步任务 | 长任务提交、状态查询、失败信息可读 |
| WORKFLOW | 工作流服务与计费 | 积分扣费、任务状态、配置同步 |
可以直接使用下面的Prompt进行三方服务模块开发
text
请按 `_sop_workflow/server/02.三方服务模块开发SOP.md` 执行一个三方服务模块开发任务。
输入信息：
1. 模块分类：LLM / OCR / TTS / ASR / AUDIOCLONE / WORKFLOW
2. 平台清单：厂商名、是否启用、鉴权字段、API 地址字段
3. 默认配置规则：需要哪些默认模型或默认厂商
4. 应用配置规则：是否需要 app_setting
5. 特殊差异：没有就写"无"
开发要求：
1. 后端遵守 server_backend/dvadmin/third_party_service 当前结构。
2. 子模块包含 api.py、setting.py、provider_xxx.py、__init__.py。
3. 默认配置统一保存到 exam_ai_service_setting_data，并同步 exam_system_config 的 api_service 分组。
4. 空值提交必须触发清理，不保留无效空字符串字段。
5. 长任务统一通过 ai_async_task_submit/status。
6. 前端页面采用左侧平台菜单、右侧详情 Tabs、系统默认配置弹窗。
7. 激活开关独立保存，失败时回滚 UI。
8. 输出 PDD 验收清单、接口清单、前端页面结构和联调步骤。Action规范
03.后端视图 Action 规范改造SOP.md 用来约束 ViewSet 中的自定义接口。它要求 @action 函数名必须按业务功能命名，允许前缀包括 get_、generate_、update_、delete_、export_、render_。
这个规范看似细节，其实直接影响前后端联动。Action 名称会变成 API 路径的一部分，前端 api.ts、页面调用方法和按钮权限都会依赖它。命名混乱会导致权限难配、接口难查、前端路径不稳定。
| 前缀 | docstring 起始词 | 示例用途 |
|---|---|---|
get_ |
查询 | 查询统计、查询配置、查询模板 |
generate_ |
生成 | 生成内容、生成报告、生成试题 |
update_ |
更新 | 更新状态、更新配置、批量更新 |
delete_ |
删除 | 删除临时数据、批量删除 |
export_ |
导出 | 导出 Excel、导出报告 |
render_ |
渲染 | 渲染预览、渲染模板 |
可以直接使用下面的Prompt进行Action规范检查
text
请按 `_sop_workflow/server/03.后端视图 Action 规范改造SOP.md` 检查当前模块的 ViewSet Action。
检查范围：
- server_backend/modules/<Module>/views_app/<ModelName>.py
- server_vue3/src/views/modules/<Module>/<ModelName>/api.ts
- server_vue3/src/views/modules/<Module>/<ModelName>/index.vue 或 crud.tsx
检查要求：
1. @action 函数名必须使用 get_/generate_/update_/delete_/export_/render_ 前缀。
2. 禁止 handle_xxx、process_xxx、do_xxx、save_xxx、build_xxx。
3. 每个 @action 必须包含一行中文 docstring，并以中文句号结尾。
4. docstring 起始词必须与前缀匹配。
5. Action 改名后同步前端 api.ts URL、页面调用处和按钮权限映射。
6. 复杂逻辑优先复用 utils.py 工具类。
请输出问题清单、修复方案、涉及文件和回归测试点。验收标准
SOP 自动化开发的交付标准必须可验证。常规模块至少需要通过后端检查、迁移检查、前端构建、菜单回查、页面操作和目录结构检查。三方服务模块还要验证默认配置保存、清空清理、系统配置同步、平台切换、激活开关、异步任务状态和失败信息。
| 验收类型 | 检查内容 | 通过标准 |
|---|---|---|
| 后端检查 | manage.py check、必要迁移、路由可达 |
无系统检查错误，接口可访问 |
| 前端构建 | npm run build:dev 或项目当前构建命令 |
构建通过，无明显类型或语法错误 |
| 菜单权限 | 菜单层级、按钮权限、角色权限 | 页面可见，按钮按权限显示 |
| 图标资源 | menu.icon、menu.image、SVG 文件 |
侧栏和卡片图标正常显示 |
| 页面操作 | 列表、新增、编辑、删除、详情 | 请求成功，保存后可回显 |
| Action 联动 | 后端函数、前端 URL、按钮权限 | 路径一致，无权限遗漏 |
| 三方服务 | 默认配置、应用配置、系统配置同步 | 刷新后可回显，清空后可清理 |
可以直接使用下面的Prompt进行SOP验收
text
请按 `_sop_workflow/server` 中的 SOP 文档，对当前管理模块进行交付验收。
验收范围：
- 后端：server_backend/modules/<Module>/models.py、views_app/<ModelName>.py、urls.py、utils.py
- 前端：server_vue3/src/views/modules/<Module>/<ModelName>/api.ts、crud.tsx、index.vue
- 系统：菜单、按钮权限、角色权限、icon、image
- 如为三方服务：server_backend/dvadmin/third_party_service 与 server_vue3/src/views/system/ThirdPartyService/<Module>/
请检查：
1. 是否符合 01.管理后台模块开发SOP。
2. 如涉及三方服务，是否符合 02.三方服务模块开发SOP。
3. 所有 @action 是否符合 03.后端视图 Action 规范改造SOP。
4. 前后端接口路径、HTTP 方法、权限按钮是否一致。
5. 菜单是否写入数据库，角色权限是否补齐，图标路径是否真实存在。
6. 是否执行或列出后端 check、迁移、前端 build、菜单回查命令。
7. 是否存在未验收的扩展能力或空口承诺。
请输出验收结果表，标记通过、未通过、风险项和需要修复的文件位置。总结
_sop_workflow/server 的价值，是把 Django + Vue3 管理后台开发从"凭经验写代码"变成"按 SOP 执行的自动化交付"。常规模块通过 01 统一后端、前端、菜单、权限和图标；三方服务通过 02 统一 AI 服务配置、默认设置、系统同步和异步任务；Action 规范通过 03 保证接口命名、前端路径和按钮权限一致。
当这些规范被写进 Codex Prompt 后，AI 不再只是补代码片段，而是能沿着项目既有结构生成可接入、可验收、可维护的前后端管理模块。这就是教育管理系统进入 AI 开发时代后，真正能复用的工程化路径。