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