• 新增：课程发布到班级的能力（Course-Class Scope）
  • 表：course_class_scope(course_id, class_id, created_at)，唯一键 (course_id, class_id)
  • 规则：
    • 草稿（is_public=false）：仅创建者可见（忽略 scope/visibility）
    • 已发布（is_public=true）：
      • 若存在 scope 绑定：仅绑定班级成员可见（学校管理员同校放行，平台管理员忽略限制）
      • 若无 scope 绑定：按 visibility（private/school/public）放行
  • 接口：
    • GET /courses/{course_id}/classes 列出绑定的班级 ID
    • POST /courses/{course_id}/classes:assign 绑定到多个班级（body: { class_ids: number[] })
    • DELETE /courses/{course_id}/classes/{class_id} 解绑

03_课程模块 API 设计（v1）

本文档规划课程相关 API 与上传 URL 规范，覆盖最小可用集，便于前后端对齐开发。

---

1. 资源与命名

• 资源名：courses
• 嵌套资源：/courses/{course_id}/...（课程下子资源）
• 上传资源：使用动词化子路径 upload 聚合（见 4. 上传）

---

2. 数据模型 (简)

映射 app/models/course.py 与 docs/00_DB_Schema_v2.md：

• id, name, description, created_by, forked_from_id, is_public, courseware_url, textbook_url, courseware_pages, platform, chapters_count, created_at
• 手册结构：见 v2 手册表（course_chapters 等）
• 手册快照：course_handbook_snapshots

---

3. 课程主资源 API

• 创建课程
  • POST /courses
  • 请求：

    {"name":"课程名","description":"...","created_by":1,"platform":"模多多教育版"}

  • 响应：201 + 课程对象
• 获取课程详情
  • GET /courses/{id}
• 查询课程列表
  • GET /courses?created_by=&is_template=&user_id=&page=&size=
  • 说明：
    • created_by：按创建者筛选
    • is_template：按是否模板筛选
    • 可见性：草稿仅作者可见；发布后按 visibility（private/school/public）或班级范围（如有绑定）放行
    • page / size：分页，默认 1 / 20
  • 示例：

    GET /courses
    GET /courses?created_by=7
    GET /courses?is_template=false&page=1&size=20

• Fork 课程（从模板或他人课程克隆一份到个人空间）
  • POST /courses/{course_id}:fork
  • 请求：

    {"created_by": 7, "name": "我的AI课程（副本）"}

  • 行为：深拷贝课程 + 章节 + 步骤，返回新课程；新课程 forked_from_id = {course_id}
• 更新课程（基本信息）
  • PUT /courses/{id}（或 PATCH）
• 删除课程
  • DELETE /courses/{id}

---

3.2 学生课程进度

• 获取当前用户在某课程的进度
  • GET /courses/{course_id}/progress/me
  • 响应：

    {
      "course_id": 1,
      "user_id": 123,
      "total_assignments": 8,
      "submitted_assignments": 5,
      "progress_percent": 62.5
    }

---

3.3 课程发布到班级（Course-Class Scope）

• 列出绑定班级
  • GET /courses/{course_id}/classes
• 绑定到多个班级
  • POST /courses/{course_id}/classes:assign
  • Body:

    { "class_ids": [101, 102, 103] }

• 解绑某班级
  • DELETE /courses/{course_id}/classes/{class_id}
• 权限

  • 教师/管理员可操作

  • 可见性优先级：草稿（仅作者） > 已发布且有 scope（仅绑定班级成员/同校学校管理员/平台管理员）> 否则按 visibility

  • 计算口径：

    • 分母 total_assignments：该课程下，面向该学生所在班级且状态为 published 的作业总数
    • 分子 submitted_assignments：该学生对上述作业产生过提交（按 assignment 去重）
    • 百分比：submitted / total * 100，保留两位小数

  • 权限：与课程可见性一致（需能查看该课程）

---

3.1 元数据轻量列表（Meta）

• GET /meta/courses?created_by=&is_template=&user_id=&page=&size=
• 返回字段：id, name, is_template, created_by
• 用途：前端下拉/列表轻量查询，支持与主资源相同的筛选（含 user_id 过滤）

---

4. 上传 API 设计（URL 规范）

当前实现（已简化）：

• POST /upload/{course_id}/courseware → 返回：{"course_id":1, "courseware_url":"/static/courseware/1/xxx.ext"}
• POST /upload/{course_id}/handbook →
  • 当上传 JSON：直接入库快照，返回：{"course_id":1, "source_file_url": null}
  • 当上传文件：入库并返回：{"course_id":1, "source_file_url":"/static/handbook/1/xxx.ext"}
• POST /upload/{course_id}/textbook → 返回：{"course_id":1, "textbook_url":"/static/textbook/1/xxx.ext"}

说明：

• 统一返回 course_id + 类型化 URL 字段，便于前端直写课程对象对应字段。
• 上传文件仍通过 /static 挂载对外访问。

---

5. 章节与步骤 API（分表）

• 章节
  • 创建：POST /courses/{id}/chapters
  • 详情/更新/删除：GET/PUT/DELETE /chapters/{chapter_id}
  • 排序：POST /courses/{id}/chapters:reorder
• 步骤
  • 创建：POST /chapters/{chapter_id}/steps（body: step_type in [courseware, ai_task, assignment]）
  • 详情/更新/删除：GET/PUT/DELETE /steps/{step_id}
  • 排序：POST /chapters/{chapter_id}/steps:reorder
  • 类型化配置：
    • 课件（改为章节级）：PUT /chapters/{chapter_id}/courseware（file_url, page_count, learning_task_text）
    • AI 任务：PUT /steps/{id}/ai_task（ai_type, task_desc, guide_text）
    • 作业：PUT /steps/{id}/assignment（task_desc, guide_text）
  • 步骤级上传：POST /courses/{course_id}/steps/{step_id}/uploads/courseware

---

6. 手册与课程文件 URL

• 读取手册快照：GET /courses/{id}/handbook
• 读取课件 URL：GET /courses/{id}/courseware → {"course_id":1, "courseware_url":"/static/courseware/1/xxx.ext"}
• 读取教材 URL：GET /courses/{id}/textbook → {"course_id":1, "textbook_url":"/static/textbook/1/xxx.ext"}

---

7. 权限与鉴权

• 需登录（教师/管理员）方可创建/更新/上传。
• 列表/详情/手册/文件 URL 均按角色可见性控制（本人/本校/平台）。

---

8. 错误码约定

• 404：课程不存在
• 400：文件类型不支持 / JSON 无效
• 413：文件过大（可由 Nginx/反向代理控制）

---

9. 下一步开发顺序

1. 实现课程 CRUD（含分页查询）
2. 优化上传 URL 路径（兼容旧路径一段时间）
3. 手册快照的 GET/POST 接口
4. 手册结构批量导入（JSON → 分表）

---

10. 示例（curl）

• 获取课件/教材 URL（需登录）

curl -H 'Authorization: Bearer TOKEN' http://localhost:8000/courses/1/courseware
curl -H 'Authorization: Bearer TOKEN' http://localhost:8000/courses/1/textbook