3yangyang9 / DeepTutor-AILearning

# ailearning 机构智能学习平台
一个面向线下培训机构的多租户智能学习平台。平台方管理机构、模型和计费策略，机构管理自己的校区，校区管理教师与学生，学生在中文学习空间中完成教材测评、查缺补漏和知识点学习。
> [!IMPORTANT]
> 本仓库是基于 HKUDS/DeepTutor 的派生项目，并在其能力引擎、Web 工作区和文档处理能力之上增加了机构、校区、学生、教材、测评和点数计费功能。本项目不是 HKUDS/DeepTutor 官方发行版。上游版权和许可信息请参阅 LICENSE、CITATION.cff 和 THIRD_PARTY_NOTICES.md。
## 目录
- 项目定位
- 功能概览
- 角色与入口
- 学习流程
- 快速启动
- 首次配置
- 配置说明
- 数据与安全
- 项目结构
- 测试与检查
- 开源协议与第三方项目
## 项目定位
这个项目把 DeepTutor 的智能对话、问题生成、知识检索和学习能力，组织成培训机构可以运营的业务系统：
 [code] 
平台服务端通过 OpenAI 兼容接口连接 New API 或其他中转服务。学生端不会接触服务端 Key，模型由平台管理员统一指定，机构只管理自己的额度和人员。
### 当前状态
- 适合本地部署、局域网部署和二次开发。
- 业务功能正在持续完善，生产环境使用前应完成权限、备份、HTTPS、日志和压力测试。
- 项目不附带教材、题库、模型权重或任何 API Key。
- 文档、教材和模型输出可能受第三方版权或服务商条款约束，使用者需要自行确认合规性。
## 功能概览
### 平台运营中心
- 机构客户、校区、平台账户和角色权限管理。
- 给机构充值点数，设置设备总上限、有效期和使用限制。
- 模型同步、启用模型、默认模型和业务功能模型分配。
- New API 地址、服务端专用 Key 和连接测试配置。
- 按模型、业务功能、机构和时间统计调用量与点数消耗。
- 可调的上游价格、汇率、功能倍率、机构系数、最低消费和固定点数。
- 教材上传、年级/学科/版本/上下册信息维护和处理状态查看。
- AI 提取教材章节与核心知识点，并生成知识关系图谱。
- 测评题库生成、发布、归档和删除。
### 机构与校区
- 机构管理员创建多个校区，并向校区分配点数、设备上限和有效期。
- 校区管理员创建、修改和删除学生账号，学号自动生成。
- 管理教师、教务、校区管理员、班级和校区本地档案。
- 学生数据导入、导出和备份。
- 从机构进入校区，再查看学生的教材、测评和知识点掌握度。
### 学生学习空间
- 中文、面向学生的简洁学习主页，不要求学生配置模型。
- 在个人资料中按学科确定教材版本，系统自动关联同版本上下册。
- 数学、语文等学科独立维护学习进度、知识图谱和测评记录。
- 首次测评覆盖教材核心章节，一道题可以关联多个知识点。
- 交卷后分析正确率、题型、难度和相关知识点。
- 对不确定的薄弱点自动安排深入测试，区分当前知识和前置知识问题。
- 根据测评结果生成查缺补漏任务、知识点练习和学习计划。
- 知识地图支持缩放、拖动、全局预览和按节点查看关系。
- AI 对话作为辅助入口；测评、查缺补漏和复习任务由系统自动安排。
### 教材与知识图谱
- 本地优先提取 PDF 文本和目录书签，减少不必要的多模态调用。
- 优先以教材目录构建章节层级，再生成章节内的核心知识点。
- 避免把定义中的单个例子拆成过细的知识节点。
- 自动生成章节归属、前置关系和递进关系，管理员可以查看和修改。
- 整本分析超时或上游不可用时，支持按章节降级处理。
## 角色与入口
| 使用者 | 入口 | 主要职责 |
| --- | --- | --- |
| 平台管理员 | `/admin/commercial` | 机构、模型、教材、题库、计费和审计 |
| 机构管理员 | `/organization/login`、`/organization` | 机构资料、校区、点数和机构员工 |
| 校区管理员 | `/campus-admin` | 校区、教师、学生、班级和备份 |
| 学生 | `/student/login`、`/student` | 学科教材、测评、知识图谱和学习任务 |
旧的 `/campus` 地址保留学生与校区管理的入口选择页；它不是校区管理后台。
产品名和 Python 发行名为 `ailearning`，前端包名为 `ailearning-web`。为兼容上游引擎与已有部署，内部 `deeptutor` 模块、`DEEPTUTOR_*` 环境变量和本地存储键保持不变，原 `deeptutor` CLI 命令作为兼容别名保留。开源来源和版权声明不随产品改名而移除。
## 学习流程
 [code] 
学习情况用于安排测评起点、难度与前置知识检查范围。这部分流程仍在完善，正式运营前需要验证不同选择下的测评入口和后续任务。
计费简化公式：
 [code] 
价格调整会产生新的价格版本，历史调用保留当时的价格快照。
## 快速启动
### Windows 一键启动
安装 Python 3.11、3.12 或 3.13、Node.js 20 或更高版本及 npm，并确保可以访问 New API（如果使用 AI 功能）。然后在项目根目录双击：
 [code] 
启动脚本会创建或检查 `.venv`、安装后端和前端依赖、启动前后端、检查服务状态并打开平台运营中心。
默认地址：
 [code] 
如果 3782 被占用或被 Windows 保留，启动脚本会选择可用端口，并在命令行打印实际地址。启动窗口会持续显示日志；关闭窗口或按 `Ctrl+C` 会停止本次启动的服务。
### 局域网访问
启动器会让前端绑定 `0.0.0.0`。同一局域网手机可以访问运行电脑的局域网 IP，例如：
 [code] 
实际端口以启动命令行输出为准。Windows 防火墙需要允许对应端口，生产环境不要直接把管理后台暴露到公网。
## 首次配置
平台管理员打开“API 与模型”页面：
1. 填写 New API 基础地址和服务端专用 Key。
2. 保存配置并测试连接。
3. 同步模型，指定默认模型和业务功能模型。
4. 配置模型价格和各 AI 功能的点数倍率。
5. 创建机构、充值并设置有效期、设备上限。
6. 创建机构管理员，机构管理员再创建校区并分配额度。
7. 校区管理员创建教师和学生账号。
服务端 Key 不会下发给学生或校区浏览器。管理后台保存的 Key 会加密写入商业数据库；如果同时设置了环境变量，环境变量优先。推荐使用 New API 管理员创建的专用服务 Key，并在 New API 侧限制来源 IP、允许模型和访问范围。
上传教材时填写年级、学科、教材名称、出版社/版本、上下册或学期以及 PDF 文件。处理完成后应抽查章节、核心知识点和关系，再发布给学生。
## 手动开发启动
 [code] 
分别启动后端和前端：
 [code] 
容器化部署请先阅读 CONTAINERIZATION.md 和对应的 `compose