tonytech/kindergarten_java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
57a86a3bd0
kindergarten_java/docs/design/13-数据模型与API设计.md

949 lines
31 KiB
Markdown
Raw Normal View History

提交说明
2026-02-28 16:41:39 +08:00
# 数据模型与API设计
> ⚠️ **本文档已过时**
>
> 本文档需要按新结构重构。请参考 **[17-课程包套餐重构需求.md](./17-课程包套餐重构需求.md)** 中的数据模型部分。
>
> 主要变更：
> - 新增：课程套餐表、套餐-课程包关联表
> - 新增：课程表（导入课/集体课/领域课）、教学环节表
> - 新增：校本课程包表、主题字典表
> - 重构：课程包表结构大幅调整
> - 废弃：课程脚本表、逐页配置表（改为课程-环节结构）
>
> 本文档仅供参考，待重构更新。
---
> 创建时间：2025-02-04
> 最后更新：2025-02-13
> **状态：已过时，待重构**
> 版本：MVP v1.1
---
## 一、数据模型设计
### 1.1 核心实体关系图
```
┌─────────────────────────────────────────────────────────────────┐
│ 核心实体关系 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 租户 │────│ 教师 │────│ 班级 │ │
│ │ (Tenant) │ 1 │(Teacher) │ M │ (Class) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ M │ M │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 学生 │ │ 授课记录 │ │
│ │(Student) │ │(Lesson) │ │
│ └──────────┘ └──────────┘ │
│ │ │ │
│ │ M │ │
│ └────────────────────────────────┘ │
│ │ │
│ │ M │
│ ▼ │
│ ┌──────────┐ │
│ │ 课程包 │ │
│ │(Course) │ │
│ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 数据表清单
| 表名 | 说明 | 核心字段 |
|-----|------|---------|
| tenants | 租户（幼儿园） | id, name, package_type, status |
| teachers | 教师 | id, tenant_id, name, phone, classes[], status |
| students | 学生 | id, tenant_id, class_id, name, gender, parent_phone |
| classes | 班级 | id, tenant_id, name, grade, teacher_id |
| courses | 课程包 | id, name, grade_tags[], domain_tags[], status, version |
| course_resources | 课程包资源 | id, course_id, resource_type, file_url |
| course_scripts | 课程脚本 | id, course_id, step_index, content, interactions[] |
| course_activities | 延伸活动 | id, course_id, name, domain, materials[], guide |
| lessons | 授课记录 | id, tenant_id, teacher_id, class_id, course_id, datetime |
| lesson_feedbacks | 课程反馈 | id, lesson_id, teacher_id, rating, comments |
| student_records | 学生测评记录 | id, lesson_id, student_id, participation, understanding |
| tags | 标签体系 | id, level, code, name, parent_id |
| tenant_courses | 租户课程授权 | id, tenant_id, course_id, authorized |
---
### 1.3 详细表结构
#### tenants（租户表）
```sql
CREATE TABLE tenants (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100) NOT NULL COMMENT '幼儿园名称',
address VARCHAR(255) COMMENT '地址',
contact_person VARCHAR(50) COMMENT '联系人',
contact_phone VARCHAR(20) COMMENT '联系电话',
logo_url VARCHAR(255) COMMENT 'Logo URL',
-- 套餐信息
package_type ENUM('basic', 'standard', 'advanced') NOT NULL COMMENT '套餐类型',
teacher_quota INT DEFAULT 20 COMMENT '教师账号配额',
student_quota INT DEFAULT 200 COMMENT '学生档案配额',
storage_quota BIGINT DEFAULT 5368709120 COMMENT '存储配额(字节)',
-- 时间信息
start_date DATE NOT NULL COMMENT '套餐开始日期',
expire_date DATE NOT NULL COMMENT '套餐到期日期',
-- 使用统计
teacher_count INT DEFAULT 0 COMMENT '已使用教师数',
student_count INT DEFAULT 0 COMMENT '已使用学生数',
storage_used BIGINT DEFAULT 0 COMMENT '已使用存储',
-- 状态
status ENUM('active', 'suspended', 'expired') DEFAULT 'active',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_package_type (package_type),
INDEX idx_status (status),
INDEX idx_expire_date (expire_date)
) COMMENT='租户（幼儿园）表';
```
#### teachers（教师表）
```sql
CREATE TABLE teachers (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL COMMENT '所属租户ID',
name VARCHAR(50) NOT NULL COMMENT '姓名',
phone VARCHAR(20) NOT NULL COMMENT '手机号',
email VARCHAR(100) COMMENT '邮箱',
-- 账号信息
login_account VARCHAR(100) NOT NULL COMMENT '登录账号',
password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希',
-- 班级信息（JSON数组）
class_ids JSON COMMENT '负责的班级ID列表',
-- 状态
status ENUM('active', 'suspended') DEFAULT 'active',
-- 统计字段
lesson_count INT DEFAULT 0 COMMENT '授课次数',
feedback_count INT DEFAULT 0 COMMENT '反馈提交数',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
last_login_at DATETIME COMMENT '最后登录时间',
UNIQUE KEY uk_login_account (login_account),
INDEX idx_tenant_id (tenant_id),
INDEX idx_status (status),
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
) COMMENT='教师表';
```
#### students（学生表）
```sql
CREATE TABLE students (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL COMMENT '所属租户ID',
class_id BIGINT NOT NULL COMMENT '所属班级ID',
name VARCHAR(50) NOT NULL COMMENT '姓名',
gender ENUM('male', 'female') COMMENT '性别',
birth_date DATE COMMENT '出生日期',
parent_phone VARCHAR(20) COMMENT '家长手机号',
parent_name VARCHAR(50) COMMENT '家长姓名',
-- 统计字段
reading_count INT DEFAULT 0 COMMENT '阅读数量',
lesson_count INT DEFAULT 0 COMMENT '参与课程次数',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_tenant_class (tenant_id, class_id),
INDEX idx_parent_phone (parent_phone),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (class_id) REFERENCES classes(id)
) COMMENT='学生表';
```
#### classes（班级表）
```sql
CREATE TABLE classes (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL COMMENT '所属租户ID',
name VARCHAR(50) NOT NULL COMMENT '班级名称',
grade ENUM('small', 'middle', 'big') NOT NULL COMMENT '年级',
teacher_id BIGINT COMMENT '负责教师ID',
-- 统计字段
student_count INT DEFAULT 0 COMMENT '学生人数',
lesson_count INT DEFAULT 0 COMMENT '本月授课次数',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_tenant_id (tenant_id),
INDEX idx_grade (grade),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (teacher_id) REFERENCES teachers(id)
) COMMENT='班级表';
```
#### courses（课程包表）
```sql
CREATE TABLE courses (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(200) NOT NULL COMMENT '课程包名称',
description TEXT COMMENT '课程简介',
-- 绘本关联
picture_book_id BIGINT COMMENT '关联绘本ID',
picture_book_name VARCHAR(200) COMMENT '绘本名称',
-- 封面图片
cover_image_path VARCHAR(500) COMMENT '封面图片路径',
-- 标签
grade_tags JSON COMMENT '适切年级标签 ["small", "middle"]',
domain_tags JSON COMMENT '领域标签 [{"level1":"语言", "level2":"阅读与书写准备"}]',
-- 时长
duration INT DEFAULT 25 COMMENT '教学时长（分钟）',
-- 数字资源（JSON数组存储多文件路径）
ebook_paths JSON COMMENT '电子绘本路径 [{"name":"xxx.pdf", "path":"/uploads/..."}]',
audio_paths JSON COMMENT '音频路径',
video_paths JSON COMMENT '视频路径',
other_resources JSON COMMENT '其他资源路径',
-- 教学材料
ppt_path VARCHAR(500) COMMENT 'PPT文件路径',
ppt_name VARCHAR(200) COMMENT 'PPT文件名',
poster_paths JSON COMMENT '挂图路径',
tools JSON COMMENT '教具列表 [{"name":"剪刀", "quantity":10}]',
student_materials TEXT COMMENT '学生材料',
-- 复杂数据（JSON存储）- 2025-02-13 新增
lesson_plan_data JSON COMMENT '课堂计划数据 {phases:[], scriptPages:[]}',
activities_data JSON COMMENT '延伸活动数据 [{name, type, content, materials, duration}]',
assessment_data JSON COMMENT '测评工具数据 {enabled, types[], indicators[], ...}',
-- 状态
status ENUM('draft', 'pending', 'rejected', 'published', 'archived') DEFAULT 'draft',
version VARCHAR(20) DEFAULT '1.0' COMMENT '版本号',
-- 审核相关
submitted_at DATETIME COMMENT '提交审核时间',
submitted_by BIGINT COMMENT '提交人ID',
reviewed_at DATETIME COMMENT '审核时间',
reviewed_by BIGINT COMMENT '审核人ID',
review_comment TEXT COMMENT '审核意见',
review_checklist JSON COMMENT '审核检查项',
-- 版本管理
parent_id BIGINT COMMENT '父版本ID（迭代时指向原版本）',
is_latest BOOLEAN DEFAULT TRUE COMMENT '是否最新版本',
-- 统计字段
usage_count INT DEFAULT 0 COMMENT '使用次数',
teacher_count INT DEFAULT 0 COMMENT '使用教师数',
avg_rating DECIMAL(3,2) DEFAULT 0 COMMENT '平均评分',
-- 审计字段
created_by BIGINT COMMENT '创建者ID（超管端用户）',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
published_at DATETIME COMMENT '发布时间',
INDEX idx_status (status),
INDEX idx_grade_tags (grade_tags(100)),
INDEX idx_published_at (published_at)
) COMMENT='课程包表';
```
#### course_resources（课程包资源表）
```sql
CREATE TABLE course_resources (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
course_id BIGINT NOT NULL COMMENT '课程包ID',
resource_type ENUM('ebook', 'audio', 'video', 'ppt', 'animation', 'interactive') NOT NULL,
resource_name VARCHAR(255) NOT NULL COMMENT '资源名称',
file_url VARCHAR(500) NOT NULL COMMENT '文件URL',
file_size BIGINT COMMENT '文件大小（字节）',
mime_type VARCHAR(100) COMMENT 'MIME类型',
metadata JSON COMMENT '其他元数据（时长、分辨率等）',
-- 排序
sort_order INT DEFAULT 0,
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_course_id (course_id),
INDEX idx_resource_type (resource_type),
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE
) COMMENT='课程包资源表';
```
#### course_scripts（课程脚本表）
```sql
CREATE TABLE course_scripts (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
course_id BIGINT NOT NULL COMMENT '课程包ID',
step_index INT NOT NULL COMMENT '环节序号',
step_name VARCHAR(100) NOT NULL COMMENT '环节名称',
step_type ENUM('intro', 'guide', 'reading', 'activity', 'ending') NOT NULL,
-- 环节内容
duration INT NOT NULL COMMENT '预计时长（分钟）',
objective TEXT COMMENT '环节目标',
teacher_script TEXT COMMENT '教师话术脚本',
interaction_points JSON COMMENT '互动要点',
-- 关联资源
resource_ids JSON COMMENT '关联的资源ID列表',
-- 排序
sort_order INT DEFAULT 0,
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_course_step (course_id, step_index),
INDEX idx_course_id (course_id),
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE
) COMMENT='课程脚本表';
```
#### course_script_pages（逐页配置表）
```sql
CREATE TABLE course_script_pages (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
script_id BIGINT NOT NULL COMMENT '脚本ID',
page_number INT NOT NULL COMMENT '页码',
questions JSON COMMENT '提问列表',
interaction_component JSON COMMENT '互动组件配置',
teacher_notes TEXT COMMENT '教师提示',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_script_page (script_id, page_number),
INDEX idx_script_id (script_id),
FOREIGN KEY (script_id) REFERENCES course_scripts(id) ON DELETE CASCADE
) COMMENT='课程脚本逐页配置表';
```
#### course_activities（延伸活动表）
```sql
CREATE TABLE course_activities (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
course_id BIGINT NOT NULL COMMENT '课程包ID',
name VARCHAR(200) NOT NULL COMMENT '活动名称',
-- 分类
domain VARCHAR(100) COMMENT '所属领域',
domain_tag_id BIGINT COMMENT '关联领域标签ID',
activity_type ENUM('hands_on', 'communication', 'game', 'other') NOT NULL,
duration INT COMMENT '预计时长（分钟）',
-- 素材
online_materials JSON COMMENT '线上素材 [{"name":"xxx", "url":"xxx"}]',
offline_materials TEXT COMMENT '线下素材说明',
-- 活动指引
activity_guide TEXT COMMENT '详细活动指引',
objectives TEXT COMMENT '活动目标',
-- 排序
sort_order INT DEFAULT 0,
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_course_id (course_id),
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE
) COMMENT='延伸活动表';
```
#### lessons（授课记录表）
```sql
CREATE TABLE lessons (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL COMMENT '租户ID',
teacher_id BIGINT NOT NULL COMMENT '教师ID',
class_id BIGINT NOT NULL COMMENT '班级ID',
course_id BIGINT NOT NULL COMMENT '课程包ID',
-- 时间
planned_datetime DATETIME COMMENT '计划上课时间',
start_datetime DATETIME COMMENT '实际开始时间',
end_datetime DATETIME COMMENT '实际结束时间',
actual_duration INT COMMENT '实际时长（分钟）',
-- 状态
status ENUM('planned', 'in_progress', 'completed', 'cancelled') DEFAULT 'planned',
-- 快速记录
overall_rating ENUM('excellent', 'good', 'average', 'needs_improvement') COMMENT '整体效果',
participation_rating ENUM('very_high', 'high', 'medium', 'low') COMMENT '参与度',
completion_note ENUM('all_completed', 'adjusted', 'partial') COMMENT '完成情况',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_tenant_teacher (tenant_id, teacher_id),
INDEX idx_class_id (class_id),
INDEX idx_course_id (course_id),
INDEX idx_status (status),
INDEX idx_start_datetime (start_datetime),
FOREIGN KEY (tenant_id) REFERENCES tenants(id),
FOREIGN KEY (teacher_id) REFERENCES teachers(id),
FOREIGN KEY (class_id) REFERENCES classes(id),
FOREIGN KEY (course_id) REFERENCES courses(id)
) COMMENT='授课记录表';
```
#### lesson_feedbacks（课程反馈表）
```sql
CREATE TABLE lesson_feedbacks (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
lesson_id BIGINT NOT NULL COMMENT '授课记录ID',
teacher_id BIGINT NOT NULL COMMENT '教师ID',
-- 整体评价
design_quality TINYINT COMMENT '课程设计质量 1-5',
participation TINYINT COMMENT '孩子参与度 1-5',
goal_achievement TINYINT COMMENT '教学目标达成度 1-5',
-- 环节反馈（JSON）
step_feedbacks JSON COMMENT '各环节反馈和评分',
-- 优点与建议
pros TEXT COMMENT '优点',
suggestions TEXT COMMENT '改进建议',
-- 延伸活动开展
activities_done JSON COMMENT '开展的延伸活动列表',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_lesson_teacher (lesson_id, teacher_id),
INDEX idx_lesson_id (lesson_id),
INDEX idx_teacher_id (teacher_id),
FOREIGN KEY (lesson_id) REFERENCES lessons(id) ON DELETE CASCADE,
FOREIGN KEY (teacher_id) REFERENCES teachers(id)
) COMMENT='课程反馈表';
```
#### student_records（学生测评记录表）
```sql
CREATE TABLE student_records (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
lesson_id BIGINT NOT NULL COMMENT '授课记录ID',
student_id BIGINT NOT NULL COMMENT '学生ID',
-- 参与度评分（1-5）
focus TINYINT COMMENT '专注度',
participation TINYINT COMMENT '参与度',
interest TINYINT COMMENT '兴趣度',
understanding TINYINT COMMENT '理解度',
-- 领域目标达成（JSON）
domain_achievements JSON COMMENT '各领域目标达成情况',
-- 备注
notes TEXT COMMENT '备注',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_lesson_student (lesson_id, student_id),
INDEX idx_lesson_id (lesson_id),
INDEX idx_student_id (student_id),
FOREIGN KEY (lesson_id) REFERENCES lessons(id) ON DELETE CASCADE,
FOREIGN KEY (student_id) REFERENCES students(id)
) COMMENT='学生测评记录表';
```
#### tags（标签体系表）
```sql
CREATE TABLE tags (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
level TINYINT NOT NULL COMMENT '层级 1-4',
code VARCHAR(50) NOT NULL COMMENT '标签编码',
name VARCHAR(100) NOT NULL COMMENT '标签名称',
parent_id BIGINT COMMENT '父标签ID',
-- 额外信息
description TEXT COMMENT '说明',
metadata JSON COMMENT '其他元数据',
-- 排序
sort_order INT DEFAULT 0,
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_code (code),
INDEX idx_parent_id (parent_id),
INDEX idx_level (level)
) COMMENT='标签体系表';
```
#### tenant_courses（租户课程授权表）
```sql
CREATE TABLE tenant_courses (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL COMMENT '租户ID',
course_id BIGINT NOT NULL COMMENT '课程包ID',
-- 授权信息
authorized BOOLEAN DEFAULT TRUE COMMENT '是否授权',
authorized_at DATETIME COMMENT '授权时间',
-- 审计字段
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_tenant_course (tenant_id, course_id),
INDEX idx_tenant_id (tenant_id),
INDEX idx_course_id (course_id),
FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE
) COMMENT='租户课程授权表';
```
---
## 二、API接口设计
### 2.1 接口规范
| 项目 | 说明 |
|-----|------|
| 协议 | HTTPS |
| 数据格式 | JSON |
| 认证方式 | JWT Token |
| 基础路径 | `/api/v1` |
| 错误码 | 标准HTTP状态码 + 业务错误码 |
### 2.2 通用响应格式
```json
// 成功响应
{
"code": 0,
"message": "success",
"data": {}
}
// 错误响应
{
"code": 1001,
"message": "参数错误",
"data": null
}
```
### 2.3 认证接口
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/auth/login` | 登录 |
| POST | `/auth/logout` | 登出 |
| POST | `/auth/refresh` | 刷新Token |
| GET | `/auth/profile` | 获取当前用户信息 |
**登录请求示例：**
```json
POST /api/v1/auth/login
{
"account": "teacher@school.com",
"password": "123456",
"role": "teacher"
}
```
**登录响应示例：**
```json
{
"code": 0,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"name": "李老师",
"role": "teacher",
"tenant_id": 1
}
}
}
```
---
### 2.4 超管端API
#### 课程包管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/admin/courses` | 创建课程包 |
| GET | `/admin/courses` | 获取课程包列表 |
| GET | `/admin/courses/:id` | 获取课程包详情 |
| PUT | `/admin/courses/:id` | 更新课程包 |
| DELETE | `/admin/courses/:id` | 删除课程包 |
| POST | `/admin/courses/:id/publish` | 发布课程包 |
| POST | `/admin/courses/:id/unpublish` | 下架课程包 |
| GET | `/admin/courses/:id/stats` | 获取课程包统计数据 |
**创建课程包请求示例：**
```json
POST /api/v1/admin/courses
{
"name": "好饿的毛毛虫完整阅读活动",
"picture_book_id": 1,
"grade_tags": ["middle", "big"],
"domain_tags": [
{"level1": "语言", "level2": "阅读与书写准备"},
{"level1": "科学", "level2": "科学探究"}
],
"duration": 25,
"description": "通过绘本..."
}
```
#### 课程包资源管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/admin/courses/:id/resources` | 上传资源 |
| GET | `/admin/courses/:id/resources` | 获取资源列表 |
| DELETE | `/admin/resources/:id` | 删除资源 |
#### 课程包脚本管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/admin/courses/:id/scripts` | 创建教学环节 |
| GET | `/admin/courses/:id/scripts` | 获取教学环节列表 |
| PUT | `/admin/scripts/:id` | 更新教学环节 |
| DELETE | `/admin/scripts/:id` | 删除教学环节 |
| POST | `/admin/scripts/:id/pages` | 添加逐页配置 |
| PUT | `/admin/script-pages/:id` | 更新逐页配置 |
#### 租户管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/admin/tenants` | 创建租户 |
| GET | `/admin/tenants` | 获取租户列表 |
| GET | `/admin/tenants/:id` | 获取租户详情 |
| PUT | `/admin/tenants/:id` | 更新租户 |
| DELETE | `/admin/tenants/:id` | 删除租户 |
| POST | `/admin/tenants/:id/suspend` | 停用租户 |
| POST | `/admin/tenants/:id/activate` | 启用租户 |
| PUT | `/admin/tenants/:id/package` | 更改套餐 |
| POST | `/admin/tenants/:id/courses` | 授权课程包 |
**创建租户请求示例：**
```json
POST /api/v1/admin/tenants
{
"name": "阳光幼儿园",
"address": "北京市朝阳区xx路xx号",
"contact_person": "张园长",
"contact_phone": "010-12345678",
"package_type": "advanced",
"start_date": "2024-09-01",
"expire_date": "2025-09-01"
}
```
---
### 2.5 学校端API
#### 教师管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/school/teachers` | 新增教师 |
| GET | `/school/teachers` | 获取教师列表 |
| GET | `/school/teachers/:id` | 获取教师详情 |
| PUT | `/school/teachers/:id` | 更新教师信息 |
| POST | `/school/teachers/:id/suspend` | 停用教师 |
| POST | `/school/teachers/:id/activate` | 启用教师 |
| POST | `/school/teachers/:id/reset-password` | 重置密码 |
#### 学生管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/school/students` | 新增学生 |
| GET | `/school/students` | 获取学生列表 |
| GET | `/school/students/:id` | 获取学生详情 |
| PUT | `/school/students/:id` | 更新学生信息 |
| DELETE | `/school/students/:id` | 删除学生 |
| POST | `/school/students/import` | 批量导入学生 |
| GET | `/school/students/:id/growth` | 获取学生成长档案 |
#### 班级管理
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/school/classes` | 新增班级 |
| GET | `/school/classes` | 获取班级列表 |
| PUT | `/school/classes/:id` | 更新班级信息 |
#### 数据统计
| 方法 | 路径 | 说明 |
|-----|------|-----|
| GET | `/school/stats/overview` | 获取概览数据 |
| GET | `/school/stats/teachers` | 获取教师统计 |
| GET | `/school/stats/courses` | 获取课程统计 |
| GET | `/school/stats/report` | 导出数据报表 |
---
### 2.6 教师端API
#### 课程包
| 方法 | 路径 | 说明 |
|-----|------|-----|
| GET | `/teacher/courses` | 获取课程包列表（已授权） |
| GET | `/teacher/courses/:id` | 获取课程包详情 |
| GET | `/teacher/courses/:id/preview` | 预览课程包（备课模式） |
| POST | `/teacher/courses/:id/favorite` | 收藏课程包 |
| DELETE | `/teacher/courses/:id/favorite` | 取消收藏 |
| POST | `/teacher/planned-lessons` | 添加到待上清单 |
#### 授课
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/teacher/lessons` | 创建授课计划 |
| GET | `/teacher/lessons` | 获取授课记录列表 |
| GET | `/teacher/lessons/:id` | 获取授课详情 |
| POST | `/teacher/lessons/:id/start` | 开始上课 |
| POST | `/teacher/lessons/:id/complete` | 结束上课 |
#### 反馈
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/teacher/lessons/:id/quick-feedback` | 快速反馈 |
| POST | `/teacher/lessons/:id/detailed-feedback` | 详细反馈 |
| GET | `/teacher/lessons/:id/feedback` | 获取反馈记录 |
#### 学生测评
| 方法 | 路径 | 说明 |
|-----|------|-----|
| POST | `/teacher/lessons/:id/student-records` | 批量创建学生测评 |
| PUT | `/teacher/student-records/:id` | 更新学生测评 |
#### 班级与学生
| 方法 | 路径 | 说明 |
|-----|------|-----|
| GET | `/teacher/classes` | 获取我的班级列表 |
| GET | `/teacher/classes/:id/students` | 获取班级学生 |
| GET | `/teacher/students/:id/growth` | 查看学生成长档案 |
---
### 2.7 公共API
| 方法 | 路径 | 说明 |
|-----|------|-----|
| GET | `/common/tags` | 获取标签体系 |
| GET | `/common/grades` | 获取年级配置 |
| GET | `/common/upload-url` | 获取文件上传URL |
| GET | `/common/resources/:id/download` | 下载资源 |
---
## 三、接口调用示例
### 3.1 教师端完整流程
```javascript
// 1. 登录
const loginResponse = await fetch('/api/v1/auth/login', {
method: 'POST',
body: JSON.stringify({
account: 'teacher@school.com',
password: '123456',
role: 'teacher'
})
});
const { token } = loginResponse.data;
// 2. 获取课程包列表
const coursesResponse = await fetch('/api/v1/teacher/courses?grade=middle', {
headers: { 'Authorization': `Bearer ${token}` }
});
// 3. 获取课程包详情（备课模式）
const courseDetailResponse = await fetch(`/api/v1/teacher/courses/${courseId}/preview`, {
headers: { 'Authorization': `Bearer ${token}` }
});
// 4. 创建授课计划
const lessonResponse = await fetch('/api/v1/teacher/lessons', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
course_id: courseId,
class_id: classId,
planned_datetime: '2025-02-05 10:00:00'
})
});
const lessonId = lessonResponse.data.id;
// 5. 开始上课
await fetch(`/api/v1/teacher/lessons/${lessonId}/start`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${token}` }
});
// 6. 结束上课并快速反馈
await fetch(`/api/v1/teacher/lessons/${lessonId}/complete`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
overall_rating: 'good',
participation_rating: 'high',
completion_note: 'all_completed'
})
});
// 7. 提交详细反馈
await fetch(`/api/v1/teacher/lessons/${lessonId}/detailed-feedback`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
design_quality: 5,
participation: 5,
goal_achievement: 4,
pros: '课件精美，互动丰富',
suggestions: '共读环节可以延长'
})
});
// 8. 提交学生测评记录
await fetch(`/api/v1/teacher/lessons/${lessonId}/student-records`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
records: [
{
student_id: 1,
focus: 4,
participation: 5,
interest: 5,
understanding: 4
},
{
student_id: 2,
focus: 3,
participation: 4,
interest: 4,
understanding: 3
}
]
})
});
```
---
## 四、后续优化方向
### 4.1 性能优化
| 优化项 | 说明 |
|-------|------|
| 缓存 | Redis缓存热点数据（课程包、标签等） |
| 分页 | 所有列表接口支持分页 |
| 索引 | 优化查询索引，提升查询效率 |
| CDN | 静态资源（音视频、图片）使用CDN |
### 4.2 安全加固
| 优化项 | 说明 |
|-------|------|
| 数据隔离 | 租户数据完全隔离，防止跨租户访问 |
| 权限控制 | 基于角色的权限控制（RBAC） |
| 审计日志 | 记录关键操作日志 |
| 敏感数据 | 加密存储敏感信息 |
---
## 五、下一步
1. 前端技术栈确认（Vue/React）
2. 后端技术栈确认（Node.js/Java/Go）
3. 数据库选型确认
4. 开发环境搭建
Reference in New Issue Copy Permalink