2026-02-28 16:41:39 +08:00

31 KiB

Raw Permalink Blame History

数据模型与API设计

⚠️ 本文档已过时

本文档需要按新结构重构。请参考 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（租户表）

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（教师表）

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（学生表）

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（班级表）

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（课程包表）

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（课程包资源表）

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（课程脚本表）

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（逐页配置表）

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（延伸活动表）

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（授课记录表）

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（课程反馈表）

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（学生测评记录表）

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（标签体系表）

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（租户课程授权表）

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 通用响应格式

// 成功响应
{
  "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`	获取当前用户信息

登录请求示例：

POST /api/v1/auth/login
{
  "account": "teacher@school.com",
  "password": "123456",
  "role": "teacher"
}

登录响应示例：

{
  "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`	获取课程包统计数据

创建课程包请求示例：

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`	授权课程包

创建租户请求示例：

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 教师端完整流程

// 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）
审计日志	记录关键操作日志
敏感数据	加密存储敏感信息

五、下一步

前端技术栈确认（Vue/React）
后端技术栈确认（Node.js/Java/Go）
数据库选型确认
开发环境搭建

31 KiB Raw Permalink Blame History Unescape Escape

数据模型与API设计

一、数据模型设计

1.1 核心实体关系图

1.2 数据表清单

1.3 详细表结构

tenants（租户表）

teachers（教师表）

students（学生表）

classes（班级表）

courses（课程包表）

course_resources（课程包资源表）

course_scripts（课程脚本表）

course_script_pages（逐页配置表）

course_activities（延伸活动表）

lessons（授课记录表）

lesson_feedbacks（课程反馈表）

student_records（学生测评记录表）

tags（标签体系表）

tenant_courses（租户课程授权表）

二、API接口设计

2.1 接口规范

2.2 通用响应格式

2.3 认证接口

2.4 超管端API

课程包管理

课程包资源管理

课程包脚本管理

租户管理

2.5 学校端API

教师管理

学生管理

班级管理

数据统计

2.6 教师端API

课程包

授课

反馈

学生测评

班级与学生

2.7 公共API

三、接口调用示例

3.1 教师端完整流程

四、后续优化方向

4.1 性能优化

4.2 安全加固

五、下一步

31 KiB

Raw Permalink Blame History