949 lines
31 KiB
Markdown
949 lines
31 KiB
Markdown
# 数据模型与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. 开发环境搭建
|