00_Eins 数据库 Schema (v2) — 课程引导手册建模

本版本在 v1 基础上，围绕引导手册（Guide Handbook）重构课程相关数据结构，覆盖以下字段：课程名称、课程简介、课程课件 URL、课件页数、教学平台、课程章节数、章节标题、章节类型（Engage/Explore/Explain/Extend/Evaluate）、章节简介、章节步骤数、步骤学习任务、步骤学习目标、步骤 AI 交互类型（多选：文生文/文生图/文生代码…）、步骤 AI 提示词、步骤拓展阅读（类型/标题/URL）。

1. 变更摘要（对比 v1）

新增枚举：chapter_type、ai_interaction_type、extension_type。
扩展 courses：新增 name、courseware_url、courseware_pages、platform、chapters_count（冗余统计）。
重命名：courses.teacher_id → created_by（仅记录创建者）。
新增克隆链路：courses.forked_from_id（指向来源课程）。
新增手册结构表：
- course_chapters（章节）
- chapter_steps（步骤）
- step_learning_tasks / step_learning_objectives（多条文本）
- step_ai_interactions（步骤 × 交互类型，M:N）
- step_ai_prompts（提示词建议，多条）
- step_extensions（拓展阅读/资源）
v1 的 lessons / tasks 保留兼容；手册模型独立于内容投放。

2. 枚举类型

sql

-- 章节类型（Engage/Explore/Explain/Extend/Evaluate）
CREATE TYPE chapter_type AS ENUM (
  'engage', 'explore', 'explain', 'extend', 'evaluate'
);

-- AI 交互类型（文生文/文生图/文生代码）
CREATE TYPE ai_interaction_type AS ENUM (
  'text_gen',   -- 文生文
  'image_gen',  -- 文生图
  'code_gen'    -- 文生代码
);

-- 拓展资源类型（文章/视频/工具/网站）
CREATE TYPE extension_type AS ENUM (
  'article', 'video', 'tool', 'website'
);

注：v1 中 user_role、task_type、media_type 保持不变。

3. 表结构

3.1 `courses`（扩展）

sql

-- v2 已迁移：删除 title，统一使用 name（升级时先回填 name = title 再删列）。
CREATE TABLE courses (
    id               bigserial PRIMARY KEY,
    name             varchar(256),           -- 课程名称
    description      text,
    created_by       bigint REFERENCES users(id) ON DELETE SET NULL,  -- 创建者
    forked_from_id   bigint REFERENCES courses(id) ON DELETE SET NULL, -- 来源课程（模板/他人课程）
    is_public        boolean DEFAULT false,
    is_template      boolean DEFAULT false,

    -- v2 新增手册元数据
    courseware_url   varchar(1024),          -- 课件 URL
    textbook_url     varchar(1024),          -- 教材 URL
    courseware_pages int,                    -- 课件页数
    platform         varchar(256),           -- 教学平台（如“模多多教育版”）
    chapters_count   int DEFAULT 0,          -- 冗余：章节数
    logo_url         varchar(1024),          -- 课程 logo（封面）
    course_type      varchar(64),            -- 课程类型（自定义，如 STEM/艺术 等）


    created_at       timestamptz DEFAULT now()
);
CREATE INDEX idx_courses_created_by ON courses(created_by);

3.2 `course_chapters`（章节）

sql

CREATE TABLE course_chapters (
    id           bigserial PRIMARY KEY,
    course_id    bigint REFERENCES courses(id) ON DELETE CASCADE,
    title        varchar(256),
    chapter_type chapter_type NOT NULL,
    intro        text,
    steps_count  int DEFAULT 0,
    sort_order   int DEFAULT 0
);
CREATE INDEX idx_course_chapters_course_id ON course_chapters(course_id);

（已移除 lessons 表，tasks 直接挂到 courses 上）

3.3 `chapter_steps`（步骤）

sql

CREATE TABLE chapter_steps (
    id          bigserial PRIMARY KEY,
    chapter_id  bigint REFERENCES course_chapters(id) ON DELETE CASCADE,
    sort_order  int DEFAULT 0,
    step_type   steptype NOT NULL -- courseware | ai_task | assignment
);
CREATE INDEX idx_chapter_steps_chapter_id ON chapter_steps(chapter_id);

3.4 章节级课件（1:1）

sql

CREATE TABLE chapter_coursewares (
    chapter_id        bigint PRIMARY KEY REFERENCES course_chapters(id) ON DELETE CASCADE,
    file_url          varchar(1024),
    page_count        int,
    learning_task_text text
);

3.5 步骤类型化配置（1:1）

sql

CREATE TABLE step_ai_task_configs (
    step_id     bigint PRIMARY KEY REFERENCES chapter_steps(id) ON DELETE CASCADE,
    ai_type     ai_interaction_type NOT NULL,
    task_desc   text,
    guide_text  text
);

CREATE TABLE step_assignment_configs (
    step_id     bigint PRIMARY KEY REFERENCES chapter_steps(id) ON DELETE CASCADE,
    task_desc   text,
    guide_text  text
);

3.4 `step_learning_tasks`（学习任务）

sql

CREATE TABLE step_learning_tasks (
    id          bigserial PRIMARY KEY,
    step_id     bigint REFERENCES chapter_steps(id) ON DELETE CASCADE,
    content     text,
    sort_order  int DEFAULT 0
);
CREATE INDEX idx_step_learning_tasks_step_id ON step_learning_tasks(step_id);

3.5 `step_learning_objectives`（学习目标）

sql

CREATE TABLE step_learning_objectives (
    id          bigserial PRIMARY KEY,
    step_id     bigint REFERENCES chapter_steps(id) ON DELETE CASCADE,
    content     text,
    sort_order  int DEFAULT 0
);
CREATE INDEX idx_step_learning_objectives_step_id ON step_learning_objectives(step_id);

3.5.1 `step_ai_interactions`（AI 交互类型，多选）

sql

CREATE TABLE step_ai_interactions (
    step_id          bigint REFERENCES chapter_steps(id) ON DELETE CASCADE,
    interaction_type ai_interaction_type NOT NULL,
    PRIMARY KEY (step_id, interaction_type)
);
CREATE INDEX idx_step_ai_interactions_step_id ON step_ai_interactions(step_id);

3.7 `step_ai_prompts`（AI 提示词建议）

sql

CREATE TABLE step_ai_prompts (
    id          bigserial PRIMARY KEY,
    step_id     bigint REFERENCES chapter_steps(id) ON DELETE CASCADE,
    prompt_text text,
    sort_order  int DEFAULT 0
);
CREATE INDEX idx_step_ai_prompts_step_id ON step_ai_prompts(step_id);

3.6 `step_extensions`（拓展阅读/资源）

sql

CREATE TABLE step_extensions (
    id              bigserial PRIMARY KEY,
    step_id         bigint REFERENCES chapter_steps(id) ON DELETE CASCADE,
    extension_type  extension_type NOT NULL,
    title           varchar(512),
    url             varchar(1024),
    sort_order      int DEFAULT 0
);
CREATE INDEX idx_step_extensions_step_id ON step_extensions(step_id);

3.9 `course_handbook_snapshots`（整课 JSON 快照，仅保留一份最新）

sql

CREATE TABLE course_handbook_snapshots (
    id               bigserial PRIMARY KEY,
    course_id        bigint REFERENCES courses(id) ON DELETE CASCADE,
    snapshot         jsonb NOT NULL,
    source_file_url  varchar(1024),
    source_file_type varchar(16),     -- docx/xlsx
    created_at       timestamptz DEFAULT now(),
    updated_at       timestamptz DEFAULT now(),
    UNIQUE(course_id)
);
CREATE INDEX idx_course_handbook_snapshots_course_id ON course_handbook_snapshots(course_id);

4. 外键速查（新增）

子表	父表	外键字段
course_chapters	courses	course_id
chapter_steps	course_chapters	chapter_id
step_coursewares	chapter_steps	step_id
step_ai_task_configs	chapter_steps	step_id
step_assignment_configs	chapter_steps	step_id
step_learning_tasks	chapter_steps	step_id
step_learning_objectives	chapter_steps	step_id
step_ai_interactions	chapter_steps	step_id
step_ai_prompts	chapter_steps	step_id
step_extensions	chapter_steps	step_id
chapter_learning_objectives	course_chapters	chapter_id
chapter_extensions	course_chapters	chapter_id

5. 建表顺序

提示：本版本已移除 courses.title 与 courses.syllabus_json，新增 courses.textbook_url，并引入 created_by / forked_from_id。

sql

-- 1) Enums: chapter_type, ai_interaction_type, extension_type
-- 2) courses
-- 3) course_chapters → chapter_steps
-- 4) step_learning_tasks / step_learning_objectives / step_ai_interactions / step_ai_prompts / step_extensions

6. 冗余字段维护

courses.chapters_count 与 course_chapters.steps_count 用于显示/统计优化。
通过应用层或触发器维护插入/删除时的计数变化。

（示例触发器，PostgreSQL）

sql

CREATE OR REPLACE FUNCTION bump_chapters_count() RETURNS trigger AS $$
BEGIN
  IF TG_OP = 'INSERT' THEN
    UPDATE courses SET chapters_count = COALESCE(chapters_count,0) + 1 WHERE id = NEW.course_id;
  ELSIF TG_OP = 'DELETE' THEN
    UPDATE courses SET chapters_count = GREATEST(COALESCE(chapters_count,1) - 1, 0) WHERE id = OLD.course_id;
  END IF;
  RETURN NULL;
END; $$ LANGUAGE plpgsql;

CREATE TRIGGER trg_course_chapters_bump
AFTER INSERT OR DELETE ON course_chapters
FOR EACH ROW EXECUTE FUNCTION bump_chapters_count();

7. 迁移指引（Alembic）

新增 Python 枚举：ChapterType、AIInteractionType、ExtensionType。
扩展 Course 模型字段：name、courseware_url、courseware_pages、platform、chapters_count、created_by、forked_from_id。
新建表：course_chapters、chapter_steps、step_learning_tasks、step_learning_objectives、step_ai_interactions、step_ai_prompts、step_extensions。

参考命令：

bash

alembic revision -m "v2: course handbook tables and enums"
alembic upgrade head

8. 示例写入（基于 `Guide_Handbook_Planning.json`）

sql

INSERT INTO courses (name, description, courseware_url, courseware_pages, platform, chapters_count)
VALUES (
  '人工智能应用与探索：机器人规划专题课程引导手册',
  '通过与大模型互动，学习规划求解与分解思维',
  'https://example.com/courseware.pdf',
  42,
  '模多多教育版',
  5
) RETURNING id;

INSERT INTO course_chapters (course_id, title, chapter_type, intro, sort_order, steps_count)
VALUES ($course_id, '初识 AI 与机器人', 'engage', '激发兴趣，建立初步认识', 1, 1) RETURNING id;

INSERT INTO chapter_steps (chapter_id, sort_order) VALUES ($chapter1_id, 1) RETURNING id;

INSERT INTO step_learning_tasks (step_id, content, sort_order) VALUES
  ($step1_id, '观看 Boston Dynamics 机器人视频片段', 1),
  ($step1_id, '探索更多现代机器人的应用案例', 2);

INSERT INTO step_learning_objectives (step_id, content, sort_order) VALUES
  ($step1_id, '了解机器人的发展现状和能力', 1),
  ($step1_id, '理解 AI 是驱动现代机器人的核心技术', 2);

INSERT INTO step_ai_interactions (step_id, interaction_type) VALUES
  ($step1_id, 'image_gen'),
  ($step1_id, 'text_gen');

INSERT INTO step_ai_prompts (step_id, prompt_text, sort_order) VALUES
  ($step1_id, '展示现代机器人的图片（工业/服务/仿生）', 1),
  ($step1_id, '介绍 Boston Dynamics 的 Atlas 和 Spot 应用领域', 2);

INSERT INTO step_extensions (step_id, extension_type, title, url, sort_order) VALUES
  ($step1_id, 'article', 'Boston Dynamics 官网', 'https://bostondynamics.com', 1),
  ($step1_id, 'video', 'The Astonishing Capabilities of Modern Robots', 'https://example.com/video', 2);

9. 设计说明

强规范化，保证顺序与可编辑性（统一 sort_order）。
多值字段（任务/目标/提示词/拓展）拆表，避免 JSON/数组带来的查询与迁移复杂度。
多选交互类型使用 M:N 表，兼容未来新增类型。
兼容 v1：保留 lessons/tasks，逐步迁移到手册驱动。

10. 开发环境默认种子数据（Alembic `db513ced18e7_seed_initial_data`）

为了便于本地开发与前端联调，alembic/versions/db513ced18e7_seed_initial_data.py 会在 alembic upgrade head 结束时自动写入一批演示数据：

表	关键字段	说明
`schools`	`id=1`, `name='测试学校'`	默认学校
`classes`	`id=1`, `name='五年五班'`, `school_id=1`	默认班级
`users`	`admin / school / teacher / student`	四级账号层次：平台管理员 → 学校管理员 → 教师 → 学生，密码同用户名
`class_teachers`	`class_id=1`, `teacher_id=(teacher 用户 id)`	将教师绑定到班级
`class_members`	`class_id=1`, `user_id=(student 用户 id)`	将学生加入班级
`courses`	模板课程“人工智能应用与探索：机器人规划专题课程引导手册”，`is_template=true`	来自根目录 `Guide_Handbook_Planning.json`
`course_chapters` & 子表	共 5 章、若干步骤	根据 JSON 生成完整章节-步骤层级
`course_handbook_snapshots`	`snapshot` = JSON, `source_file_type='json'`	备份原始手册，供后续比较/回溯

⚠️ 生产环境部署时，可在执行迁移前删除或注释该种子脚本，避免写入演示账号及课程。

完成迁移后，可通过：

bash

# 查看课程与章节
psql -U moduoduo -d moduoduo -c "SELECT id,name,chapters_count FROM courses;"

# 查看 handbook 快照
psql -U moduoduo -d moduoduo -c "SELECT course_id, jsonb_path_query(snapshot, '$.chapters[*].title') FROM course_handbook_snapshots;"

或经过 FastAPI 接口：

bash

curl http://localhost:8000/courses            # 列出课程
curl http://localhost:8000/courses/1/handbook # 获取整份 JSON 快照

以上数据仅用于开发验证，可放心重建数据库。

00_Eins 数据库 Schema (v2) — 课程引导手册建模 ​

1. 变更摘要（对比 v1） ​

2. 枚举类型 ​

3. 表结构 ​

3.1 courses（扩展） ​

3.2 course_chapters（章节） ​

3.3 chapter_steps（步骤） ​

3.4 章节级课件（1:1） ​

3.5 步骤类型化配置（1:1） ​

3.4 step_learning_tasks（学习任务） ​

3.5 step_learning_objectives（学习目标） ​

3.5.1 step_ai_interactions（AI 交互类型，多选） ​

3.7 step_ai_prompts（AI 提示词建议） ​

3.6 step_extensions（拓展阅读/资源） ​

3.9 course_handbook_snapshots（整课 JSON 快照，仅保留一份最新） ​

4. 外键速查（新增） ​

5. 建表顺序 ​

6. 冗余字段维护 ​

7. 迁移指引（Alembic） ​

8. 示例写入（基于 Guide_Handbook_Planning.json） ​

9. 设计说明 ​

10. 开发环境默认种子数据（Alembic db513ced18e7_seed_initial_data） ​

00_Eins 数据库 Schema (v2) — 课程引导手册建模

1. 变更摘要（对比 v1）

2. 枚举类型

3. 表结构

3.1 `courses`（扩展）

3.2 `course_chapters`（章节）

3.3 `chapter_steps`（步骤）

3.4 章节级课件（1:1）

3.5 步骤类型化配置（1:1）

3.4 `step_learning_tasks`（学习任务）

3.5 `step_learning_objectives`（学习目标）

3.5.1 `step_ai_interactions`（AI 交互类型，多选）

3.7 `step_ai_prompts`（AI 提示词建议）

3.6 `step_extensions`（拓展阅读/资源）

3.9 `course_handbook_snapshots`（整课 JSON 快照，仅保留一份最新）

4. 外键速查（新增）

5. 建表顺序

6. 冗余字段维护

7. 迁移指引（Alembic）

8. 示例写入（基于 `Guide_Handbook_Planning.json`）

9. 设计说明

10. 开发环境默认种子数据（Alembic `db513ced18e7_seed_initial_data`）