Appearance
后端技术开发文档v1
模多多教育版 后端技术开发文档 版本：V1.0 日期：2025‑07‑25
文档大纲
- 技术栈与工程结构
- 环境与依赖配置
- 通用接口规范
- API 映射总览（前端按钮 ↔ 后端接口 ↔ 数据库字段）
- API 详细说明（含示例请求/响应）
- 数据库 Schema 说明
- 日志与监控
- 部署与持续集成
1. 技术栈与工程结构
• 语言：Python 3.11 • 框架：FastAPI（异步），使用 Uvicorn + Gunicorn 运行 • ORM：SQLAlchemy 2.0 + Alembic 迁移 • 数据库：PostgreSQL 15 • 缓存 / 队列：Redis 7（同步令牌扣费、AI 作业队列） • 消息通知：WebSocket（Starlette）、RabbitMQ（可选异步任务） • 第三方：腾讯 TRTC SDK（WebRTC 直播）、OpenAI / Baidu AI API（AI 绘画 / 对话）
工程目录示例： app/ ├── api/ # 路由定义 │ │ ├── auth.py │ │ ├── courses.py │ │ ├── tasks.py │ │ ├── ai.py │ │ └── billing.py ├── core/ # 配置、JWT、依赖 ├── models/ # SQLAlchemy Models ├── schemas/ # Pydantic Schemas ├── services/ # 业务逻辑（AI、直播、计费） ├── db.py └── main.py
2. 环境与依赖配置
• Python 环境：使用 Poetry 或 pipenv 管理依赖。 • 核心依赖：fastapi、uvicorn[standard]、sqlalchemy、psycopg2‑binary、redis, python‑jwt、pydantic。 • AI 依赖：openai、qcloud‑trtc、httpx。
3. 通用接口规范
• RESTful 设计，路径使用复数资源名；所有 JSON 字段采用 snake_case。 • 鉴权：HTTP Header Authorization: Bearer <JWT>。 • 错误响应：统一格式 {"code": <int>, "message": <str>, "detail": <obj>}。 • 分页：查询参数 ?page=1&size=20，响应包含 meta 字段。
4. API 映射总览
| # | 前端页面 / 按钮 | HTTP | 后端 Endpoint | DB 表 / 字段 | 说明 |
|---|---|---|---|---|---|
| 1 | 学生仪表盘加载 | GET | /courses?student_id | courses(id,title,teacher_id) | 获取学生课程列表 |
| 2 | 学生仪表盘加载 | GET | /tasks/todo?student_id | tasks(id,title,course_id,due_date) | 待办任务 |
| 3 | 课程卡片点击 | GET | /courses/ | courses, lessons | 进入课程学习页面 |
| 4 | 任务提交按钮 | POST | /tasks/submit | assignment_submissions(score,content_json) | 保存任务完成状态 |
| 5 | AI 绘画“生成” | POST | /ai/draw | ai_sessions(prompt,output_image_url) | 生成绘画内容并扣费 |
| 6 | AI 绘画“提交” | POST | /ai/submit | ai_sessions(is_submitted) | 标记作品完成 |
| 7 | 作品查看页加载 | GET | /works?student_id | ai_sessions(output_image_url) | 获取学生作品 |
| 8 | 教师仪表盘加载 | GET | /courses?teacher_id | courses | 获取教师课程 |
| 9 | “创建新课程”按钮 | POST | /courses | courses(title,teacher_id) | 创建课程 |
| 10 | “保存课程”按钮 | PUT | /courses/{id}/structure | courses.structure_json | 保存章节任务结构 |
| 11 | “发布课程”按钮 | POST | /courses/{id}/publish | courses.is_published | 课程发布 |
| 12 | “发布作业”按钮 | POST | /assignments | assignments(course_id,task_id,class_id) | 布置作业 |
| 13 | 作业批改“发布” | POST | /submissions/{id}/grade | assignment_submissions(score,teacher_comment) | 保存评分 |
| 14 | 学生“加入课程” | POST | /enrollments | course_enrollments(course_id,user_id) | 加入课程/班级 |
| 15 | 学生“查看进度” | GET | /progress?course_id | course_enrollments(progress) | 查询学习进度 |
| 16 | 学生“AI 对话发送” | POST | /ai/chat | ai_sessions(input_prompt,output_text) | AI 对话 |
| 17 | 学生“查看 AI 历史” | GET | /ai/history?task_id | ai_sessions | 查看历史记录 |
| 18 | 教师“创建班级” | POST | /classes | classes(name,teacher_id) | 创建班级 |
| 19 | 教师“导入学生” | POST | /classes/{id}/students/bulk | class_members(class_id,user_id) | 批量导入学生 |
| 20 | 教师“开始直播” | POST | /live/start | - | 开始直播课堂 |
| 21 | 教师“触发 AI 任务” | POST | /live/ai/trigger | tasks(id) | 同步学生端 |
| 22 | 教师“结束直播” | POST | /live/end | - | 结束直播并归档 |
| 23 | 教师“下载作业ZIP” | GET | /assignments/{id}/download | assignment_submissions | 批量下载作业 |
| 24 | 教师“评分提交” | POST | /submissions/{id}/grade | assignment_submissions(score,teacher_comment) | 批改并评分 |
| 25 | 管理员“充值 Tokens” | POST | /billing/topup | tokens(balance) | 充值余额 |
| 26 | 系统“扣费记录” | POST | /billing/deduct | token_logs | 后台扣费记录 |
| 27 | 用户“查询余额” | GET | /billing/balance | tokens(balance) | 查询个人余额 |
| 28 | 学生“重置密码” | POST | /auth/reset_password | users | 邮件验证码重置 |
| 29 | 教师“上传课件” | POST | /lessons/{id}/resources | lessons(resource_url) | 上传 PPT/视频 |
| 30 | 平台“内容审查回调” | POST | /callback/content_check | - | 内容安全结果回调 |
5. API 详细说明
5.1 获取学生课程列表 (GET /courses)
前端学生仪表盘初始化时调用，返回学生已加入的课程卡片数据。
请求示例
GET /courses?student_id=123 Authorization: Bearer <token>
响应示例
{ "data": [ { "id": 1, "title": "AI 科学趣味课", "progress": 0.45 } ], "meta": { "count": 1} }
数据库映射
SELECT id, title FROM courses JOIN enrollments ON courses.id = enrollments.course_id WHERE enrollments.student_id = :student_id
处理流程
- 验证 JWT → 查询 enrollments → 聚合 progress → 返回 JSON
5.2 AI 绘画生成 (POST /ai/draw)
学生在 AI 绘画任务中点击“生成”触发，系统扣除 tokens 并调用第三方 AI 服务。
请求示例
POST /ai/draw { "task_id": 321, "prompt": "组合素材: 狮子+树" }
响应示例
{ "image_url": "https://cdn.example.com/ai/abcdef.png", "tokens_used": 5 }
数据库映射
INSERT INTO ai_sessions (user_id, task_id, input_prompt, output_image_url, tokens_used) UPDATE tokens SET balance = balance - 5 WHERE user_id = :uid
处理流程
- 校验 task_id 与权限
- 计算 tokens 消耗 → 检查余额
- 调用 AI 服务 → 获取图像 URL
- 事务插入 ai_sessions 与扣费
- 返回图像 URL
6. 数据库 Schema 说明
主要表及字段：users, schools, classes, courses, lessons, tasks, assignments, assignment_submissions, ai_sessions, tokens, token_logs。详细字段见附录 SQL 建表文件。 完整建表脚本文件：moduoduo_schema_v1.sql。 执行方式示例： psql -U \<user\> -d moduoduo -f moduoduo_schema_v1.sql
7. 日志与监控
• 访问日志：Nginx + Loki； • 应用日志：结构化 JSON，推送至 Grafana； • 指标：Prometheus FastAPI Instrumentator，重点监控 AI 调用时延、错误率。
8. 部署与持续集成
• Dockerfile 基于 python:3.11-slim，采用多阶段构建； • CI：GitHub Actions 进行单元测试、黑盒 API 测试； • CD：ArgoCD 部署至 Kubernetes，使用 rollingUpdate 策略。