AI教育平台系统开发文档 V1.0

1. 文档目标

本文档基于现有的 ai教育平台后端系统设计文档_v_0_1.md 进行开发落地化整理，目标不是重复数据库字段设计，而是形成一份可直接指导项目启动、分工、编码、联调、测试和部署的系统开发文档。

本文档重点回答五类问题：

这个系统第一版到底做什么，不做什么。
用什么技术栈最稳，哪些能力先做，哪些能力后做。
后端、前端、AI 能力、文件、知识库分别怎么分层。
参照优质项目时，哪些做法值得借鉴，哪些不适合直接照搬。
项目如何按阶段交付，保证每一阶段都能演示、能验收、能继续扩展。

2. 项目背景与目标

2.1 项目背景

当前项目的原始基础是一个偏前端展示型的 AI 教育系统。新系统的目标是将其升级为一个真实可运行的教育平台后端，并逐步形成完整业务闭环。

系统将覆盖三类角色：

学生：学习、答题、查看作业、查看错题、AI 问答、接收学习建议
教师：课程管理、班级管理、题库管理、作业管理、AI 出题、AI 批改、学情查看
管理员：用户权限、模型配置、Prompt 配置、知识库配置、日志监控、资源管理

2.2 第一版建设目标

第一版不是做“大而全平台”，而是完成可演示、可交付、可持续迭代的真实教学闭环：

登录认证
+ 基础 RBAC
+ 学校/班级/课程/教师/学生基础数据
+ 题库与作业
+ 学生答题
+ 客观题判分
+ AI 主观题批改
+ AI 对话
+ 文件上传

2.3 第一版不做的内容

以下内容不进入第一版主线：

微服务拆分
多租户 SaaS
支付、电商、直播
复杂 BPM 工作流
全量教务系统
高复杂 Agent 编排平台
大规模分布式向量检索

3. 参考项目与借鉴策略

本项目不直接照搬开源后台，但应明确借鉴对象与可吸收能力。

3.1 参考项目清单

参考项目	借鉴方向	本项目采用方式
芋道 / RuoYi-Vue-Pro 体系	系统管理、RBAC、菜单权限、日志、基础设施模块拆分	借鉴模块边界和后台能力组织方式，不直接复制业务代码
Spring AI Alibaba	Java 生态下 AI 能力接入、工作流、后续 Agent 扩展	作为中长期 AI 集成参考，第一版不强依赖其复杂 Agent 能力
LangChain4j	Java LLM 调用统一抽象、RAG、文档解析、Embedding/Retriever 组件化	第一版 AI 编排主推荐方案
Dify	知识库流水线、分块策略、Rerank、引用来源、元数据过滤	借鉴知识库产品思路与检索策略，不引入其平台作为主业务后台
MaxKB	面向业务系统嵌入的知识库问答产品形态、模型无关接入、RAG 基础闭环	借鉴知识库模块的产品边界和接入方式

3.2 建议吸收的成熟做法

来自后台管理项目的做法

采用清晰的 system / infra / biz / ai 模块边界
统一菜单、角色、权限、日志、字典、配置
保留数据状态、逻辑删除、审计字段
列表查询、分页、导出、操作日志统一处理

来自 AI 平台项目的做法

AI 调用统一走网关式服务层，不在业务模块直接拼 Prompt
文件解析、切片、Embedding、检索分成独立阶段
模型配置与 Prompt 模板配置后台化
返回结果尽量结构化，便于复用与审计
保留调用日志、Token 统计、失败重试与降级能力

3.3 不建议直接照搬的做法

不建议一开始引入微服务版后台脚手架，部署和调试成本过高
不建议一开始做复杂多 Agent 编排
不建议一开始强上独立向量平台与复杂工作流 DSL
不建议让 AI 输出直接成为教学最终结果，必须保留教师确认链路

4. 系统总体开发思路

4.1 开发原则

后端先做成模块化单体。
教育业务和 AI 能力严格分层。
先做业务闭环，再做智能增强。
每阶段必须具备可演示页面和可验证接口。
数据库设计以真实项目可维护为先，不为了“企业级感”过度设计。

4.2 总体架构

Web 前端
├── 学生端
├── 教师端
└── 管理员端
        ↓
API Gateway（可选，第一版可省）
        ↓
Spring Boot 模块化单体
├── common 公共能力
├── auth 认证与权限
├── system 系统管理
├── edu 教育业务
├── ai AI 能力
├── file 文件模块
└── monitor 监控模块
        ↓
基础设施
├── MySQL
├── Redis
├── MinIO
└── PostgreSQL + pgvector（第二/三阶段）
        ↓
模型层
├── 通义千问
├── DeepSeek
├── 智谱
├── OpenAI Compatible
└── 本地 Ollama（可选）

4.3 为什么采用模块化单体

这是当前最符合项目目标的方案：

对实习/比赛/作品集最友好
部署成本低
调试链路短
能快速做出完整闭环
后续仍可按模块拆分

5. 技术栈与选型建议

5.1 后端主栈

分类	选型	说明
语言	Java 17	与 Spring Boot 3 兼容性稳定
框架	Spring Boot 3.x	主开发框架
ORM	MyBatis-Plus	快速搭建管理类模块
认证	Sa-Token	适合前后端分离场景
缓存	Redis	登录态、验证码、限流、热点缓存
数据库	MySQL 8	主业务库
文件	MinIO	本地与服务器部署友好
文档	Knife4j	接口调试与联调
AI 编排	LangChain4j	第一版主推荐
部署	Docker Compose	一键拉起依赖

5.2 AI 选型建议

第一阶段

直接使用大模型厂商 OpenAI-Compatible 接口
通过 ai-model-provider + ai-model-config 实现多模型切换
使用 LangChain4j 统一封装 Chat、Prompt、Structured Output

第二阶段

增加统一 Prompt 模板管理
增加 AI 结果结构化输出校验
增加失败重试、限流、模型降级

第三阶段

增加文档解析、切片、Embedding、RAG
引入 PostgreSQL + pgvector

5.3 关于 Spring AI Alibaba 的定位

第一版不建议把系统核心强耦合到复杂 Agent 能力上，但可以：

保持接口适配层设计，为后期切换或接入 Spring AI Alibaba 留出空间
将其作为后续“可视化 AI 工作流 / Agent 扩展”的方向

换句话说：

第一版：LangChain4j 优先，简单、稳、快
后续增强：可逐步引入 Spring AI Alibaba 的工作流与 Agent 能力

6. 模块划分与职责边界

6.1 模块分层

common

负责：

统一返回结构
全局异常
分页对象
公共枚举
工具类
审计基础类

auth / security

负责：

登录、登出
Token 生成与校验
当前用户上下文
权限校验
菜单与角色权限装配

system

负责：

用户
角色
菜单
字典
参数配置
登录日志
操作日志

edu

负责：

学校、院系、专业、班级
教师、学生
课程、章节、知识点
题库、作业、答题记录
错题、学习报告

ai

负责：

模型供应商与模型配置
Prompt 模板
普通对话
AI 批改
AI 生成题目
知识库问答
调用日志与 Token 统计

file

负责：

文件上传
文件元数据
文件归属关联
文件访问控制

monitor

负责：

在线用户
缓存监控
健康检查
定时清理任务

6.2 关键边界约束

必须遵守以下约束：

edu 模块不得直接依赖第三方模型 SDK
所有 AI 调用必须先走 ai 模块能力层
所有文件访问必须经过 file 模块，不允许业务层直接拼 MinIO 地址
管理端配置模型参数时，密钥不能明文出库

7. 代码组织规范

7.1 包结构建议

采用“按领域分包 + 模块内标准分层”的结构：

com.aiedu.platform
├── common
├── config
├── security
├── system
├── education
├── ai
├── file
└── monitor

模块内部结构建议统一：

controller
service
service.impl
domain/entity
mapper
dto
vo
convert
enums
constant

7.2 DTO / VO / Entity 约束

Entity 只映射数据库字段
DTO 只用于接收请求参数
VO 只用于响应前端
不允许 Controller 直接返回 Entity
不允许前端直接依赖数据库字段命名风格

7.3 API 设计约束

后台管理接口统一走 REST 风格
所有列表接口统一分页
所有删除接口优先逻辑删除
所有写接口保留操作日志
AI 类接口除流式对话外，必须优先返回结构化对象

8. 权限、身份与数据权限设计

8.1 角色设计

建议最小角色集合：

超级管理员
学校管理员
教师
学生

8.2 RBAC 模型

采用标准 RBAC：

用户 -> 角色 -> 菜单/按钮权限

扩展字段预留：

角色数据范围
用户所属学校
用户所属班级
用户所属课程

8.3 数据权限建议

第一版就要预留数据权限，但不需要一步到位做得很重。

建议策略：

超级管理员：全量数据
学校管理员：本学校数据
教师：本人课程、本人班级、本人作业、本人学生答题
学生：本人数据

数据权限实现建议：

先在 Service 查询层做显式范围控制
第二阶段再抽象为统一数据权限拦截器或注解

9. 核心业务开发范围

9.1 第一阶段业务清单

必须完成：

登录认证
当前用户信息
菜单与权限返回
用户、角色、菜单管理
学校、班级、教师、学生、课程管理
模型配置与 Prompt 模板配置
文件上传基础能力

9.2 第二阶段业务清单

必须完成：

章节、知识点、题库
作业发布
学生提交答案
客观题判分
主观题 AI 批改
教师确认批改结果
AI 对话
AI 出题

9.3 第三阶段业务清单

必须完成：

知识库管理
文档解析
文本切片
Embedding
向量检索
RAG 问答
引用来源
错题分析
学习报告

10. AI 能力开发设计

10.1 AI 模块职责

AI 模块不是“调用模型的工具类集合”，而是一个独立业务子系统。

应包含以下能力：

模型供应商管理
模型配置管理
Prompt 模板管理
AI 调用统一网关
AI 结果结构化解析
调用日志
Token 用量统计
失败重试
内容安全审核

10.2 推荐调用链

业务请求
↓
选择 AI 任务类型
↓
读取 Prompt 模板
↓
拼装上下文
↓
选择模型配置
↓
调用 LLM
↓
解析结构化结果
↓
记录 ai_review_record / ai_chat_message / ai_token_usage
↓
返回业务结果

10.3 AI 输出规范

所有需要落库或参与教学业务决策的 AI 输出，都应尽量结构化。

例如主观题批改统一返回：

{
  "score": 7,
  "isCorrect": false,
  "missingPoints": ["缺少边界处理", "复杂度说明不完整"],
  "feedback": "主要思路正确，但得分点覆盖不全。",
  "suggestion": "补充边界分析并明确时间复杂度。",
  "riskLevel": "low"
}

10.4 AI 批改的业务定位

必须明确：

AI 批改结果默认是“评分建议”
教师可以确认、驳回、修改
最终分数以教师确认结果为准

这条规则非常关键，它决定了系统的教学可信度和演示可信度。

11. 知识库与 RAG 开发设计

11.1 第一原则

知识库不是第一阶段必做，但必须从架构上预留。

11.2 参考成熟项目后的推荐实现

结合 Dify、MaxKB、LangChain4j 的思路，推荐采用以下路径：

文档上传
↓
文件归档
↓
文档解析
↓
清洗与规范化
↓
切片
↓
Metadata 标注
↓
Embedding
↓
向量存储
↓
检索
↓
Rerank（第二步优化）
↓
拼装 Prompt
↓
生成答案 + 引用来源

11.3 切片策略建议

第一版推荐：

普通课程资料：固定窗口切片 + overlap
教材 / 讲义：按标题层级切片
FAQ / 问答库：按问答对切片

第二版可增强：

父子块切片
混合检索
元数据过滤
Rerank 模型

11.4 引用来源设计

RAG 返回必须支持来源引用，至少返回：

文档名称
文档章节/页码
chunkId
相似度/命中顺序

这不仅是产品体验要求，也是后期项目答辩的重要可信度支撑。

12. 文件模块开发设计

12.1 文件分类

文件类型建议至少区分：

用户头像
课程封面
课件资料
作业附件
学生提交附件
知识库文档
系统临时文件

12.2 文件元数据建议

文件表需记录：

存储路径
原始文件名
文件类型
文件大小
上传人
业务归属
存储桶/目录
hash 值
状态

12.3 文件安全控制

不允许前端直接推导真实文件路径
下载接口必须校验归属权限
知识库文档和学生答卷必须有更严格的权限控制

13. 前后端协作建议

13.1 接口风格

统一约定：

/api/auth/**：认证接口
/api/system/**：系统管理
/api/edu/**：教育业务
/api/ai/**：AI 能力
/api/files/**：文件接口
/api/monitor/**：监控接口

13.2 前端路由与后端模块对齐

学生端：

首页
AI 问答
作业中心
我的错题
学习报告

教师端：

班级管理
课程管理
题库管理
作业管理
AI 批改
AI 出题
学情分析

管理员端：

用户与角色
菜单与权限
模型配置
Prompt 配置
知识库管理
日志监控

13.3 联调策略

建议采用以下联调顺序：

登录与菜单
基础字典与下拉数据
用户/教师/学生/班级/课程
题库与作业
AI 批改
AI 对话
文件上传
知识库

14. 数据库与中间件开发策略

14.1 MySQL

策略：

第一版优先完成主业务表
审计字段统一下沉
逻辑删除字段统一
先保证可查可改，再逐步补索引优化

14.2 Redis

第一版用途：

登录态缓存
验证码
短期限流
热点字典与配置缓存

14.3 MinIO

第一版用途：

头像
作业附件
知识库文档

14.4 PostgreSQL + pgvector

建议第三阶段再启用，避免第一阶段运维复杂度过高。

15. 测试与质量保障

15.1 测试分层

至少包含：

单元测试：工具类、权限判断、AI 结果解析
集成测试：登录、权限、作业流程、AI 批改接口
接口测试：核心 API 的成功/失败场景
人工验收：教师端、学生端主流程演示

15.2 重点测试对象

必须重点测：

登录与权限边界
班级/课程归属关系
学生是否能看到不属于自己的数据
AI 批改失败时是否正确回退
文件上传后的权限访问控制

15.3 AI 测试策略

AI 测试不能只测“有没有返回”，要测：

返回结构是否稳定
是否满足 JSON 解析
是否能处理空答案、异常答案、超长答案
批改结果是否支持教师确认
Prompt 修改后是否影响旧功能

16. 部署与环境规划

16.1 环境划分

建议至少区分：

local 本地开发
dev 开发联调
test 演示测试
prod 作品展示 / 服务器环境

16.2 Docker Compose 建议

建议第一版就提供：

MySQL
Redis
MinIO
PostgreSQL（可先注释）

后端服务本体可本地 IDE 跑，也可后续容器化。

16.3 配置管理

建议配置分层：

application.yml
application-local.yml
application-dev.yml
application-prod.yml

敏感信息：

API Key
MinIO Secret
数据库密码
Redis 密码

全部走环境变量或加密配置注入。

17. 分阶段实施计划

阶段 A：项目骨架阶段

目标：

项目可启动
数据库可连通
Redis / MinIO 可用
接口文档可访问

交付物：

Spring Boot 工程骨架
通用返回、异常、分页、日志
Docker Compose

阶段 B：权限与基础数据阶段

目标：

管理员端真实可登录
基础数据可维护

交付物：

登录认证
用户、角色、菜单
学校、教师、学生、班级、课程

阶段 C：教学业务闭环阶段

目标：

教师可布置作业
学生可提交答案
客观题自动判分

交付物：

题库
作业
答题记录
错题入库

阶段 D：AI 教学能力阶段

目标：

AI 能真正参与教学闭环

交付物：

AI 对话
AI 主观题批改
AI 出题
Prompt 模板
调用日志与 Token 统计

阶段 E：知识库与分析阶段

目标：

形成 AI 教育平台差异化能力

交付物：

知识库
文档解析
向量检索
RAG 问答
学习报告
学情分析

18. 建议的团队分工

如果是 2-4 人小团队，建议按以下方式拆分：

方案一：2 人

A：后端基础架构、权限、系统管理、文件模块
B：教育业务、AI 模块、前端联调

方案二：3 人

A：权限与系统管理
B：教育业务与数据库
C：AI 模块、知识库、前端集成

方案三：4 人

A：基础架构与部署
B：系统管理与权限
C：教育业务
D：AI 模块与知识库

19. 风险清单与控制策略

风险	表现	控制策略
技术栈过重	迟迟无法进入业务开发	第一版坚持模块化单体
AI 输出不稳定	结构化结果难落库	强制 JSON Schema / DTO 校验
权限边界混乱	学生看到非本人数据	业务查询层先显式加范围限制
知识库投入过早	项目周期被拖慢	RAG 放第三阶段
文件权限缺失	教学文档泄露	文件下载必须走鉴权接口
模型调用成本失控	演示期频繁报错或超额	增加模型开关、限流和日志统计
过度借鉴后台框架	项目失去业务特色	系统管理借鉴，教育业务自建

20. 当前推荐结论

本项目的最优启动路径不是“先把所有 AI 能力做全”，而是：

先用 Spring Boot 3 + MyBatis-Plus + Sa-Token + Redis + MySQL + MinIO
搭起一个真实教育业务后台
再通过 LangChain4j 把 AI 问答、AI 批改、AI 出题逐步接入
最后再补知识库 RAG、引用来源、学习报告与学情分析

这条路径的优点是：

启动快
风险小
可演示
容易分工
容易扩展
既能体现 Java 后端能力，也能体现 AI 应用能力

21. 参考来源

以下项目和文档对本文档的开发建议有直接参考价值：

芋道 / yudao-cloud（RBAC、模块化后台、AI 模块与基础设施拆分）
https://github.com/YunaiV/yudao-cloud
Spring AI Alibaba（Java 生态下可扩展的 Agent / Workflow / Multi-agent 框架）
https://github.com/alibaba/spring-ai-alibaba
LangChain4j（Java LLM 接入、RAG、文档解析、Metadata 与 Retriever 设计）
https://docs.langchain4j.dev/
LangChain4j RAG 文档（文档加载、切片、Embedding、Retriever、QueryTransformer）
https://docs.langchain4j.dev/tutorials/rag/
Dify Knowledge Pipeline（知识库流水线、父子块、混合检索、Rerank、引用来源）
https://docs.dify.ai/en/use-dify/knowledge/knowledge-pipeline/create-knowledge-pipeline
Dify Knowledge Integration（检索策略、元数据过滤、Citation、Rerank）
https://docs.dify.ai/versions/3-0-x/en/user-guide/knowledge-base/integrate-knowledge-within-application
MaxKB（面向业务系统嵌入的模型无关知识库问答产品）
https://www.maxkb.ai/

FilesExpand file tree

AI教育平台系统开发文档_v1_0.md

Latest commit

History

AI教育平台系统开发文档_v1_0.md

File metadata and controls

AI教育平台系统开发文档 V1.0

1. 文档目标

2. 项目背景与目标

2.1 项目背景

2.2 第一版建设目标

2.3 第一版不做的内容

3. 参考项目与借鉴策略

3.1 参考项目清单

3.2 建议吸收的成熟做法

来自后台管理项目的做法

来自 AI 平台项目的做法

3.3 不建议直接照搬的做法

4. 系统总体开发思路

4.1 开发原则

4.2 总体架构

4.3 为什么采用模块化单体

5. 技术栈与选型建议

5.1 后端主栈

5.2 AI 选型建议

第一阶段

第二阶段

第三阶段

5.3 关于 Spring AI Alibaba 的定位

6. 模块划分与职责边界

6.1 模块分层

common

auth / security

system

edu

ai

file

monitor

6.2 关键边界约束

7. 代码组织规范

7.1 包结构建议

7.2 DTO / VO / Entity 约束

7.3 API 设计约束

8. 权限、身份与数据权限设计

8.1 角色设计

8.2 RBAC 模型

8.3 数据权限建议

9. 核心业务开发范围

9.1 第一阶段业务清单

9.2 第二阶段业务清单

9.3 第三阶段业务清单

10. AI 能力开发设计

10.1 AI 模块职责

10.2 推荐调用链

10.3 AI 输出规范

10.4 AI 批改的业务定位

11. 知识库与 RAG 开发设计

11.1 第一原则

11.2 参考成熟项目后的推荐实现

11.3 切片策略建议

11.4 引用来源设计

12. 文件模块开发设计

12.1 文件分类

12.2 文件元数据建议

12.3 文件安全控制

13. 前后端协作建议

13.1 接口风格

13.2 前端路由与后端模块对齐

13.3 联调策略

14. 数据库与中间件开发策略

14.1 MySQL

14.2 Redis

14.3 MinIO

14.4 PostgreSQL + pgvector

15. 测试与质量保障

15.1 测试分层

15.2 重点测试对象

15.3 AI 测试策略

16. 部署与环境规划

16.1 环境划分