池馆 3.0 · 数据结构设计
池馆 3.0 资源结构设计草案
三层架构：资源层 / 内容产品层 / 教学运行层
zigzagYang
一、设计目标
- 数字教材是固定出版物：审定后不可由教师修改，班级只能决定「教哪些、按什么顺序教」。
- 资源可复用：语料（Material）与题组（QuestionBlock）在题库与教材之间灵活调用，物理上统一存储。
- 教学编排独立于教材结构：班级不复制教材节点，只引用教材的
StructureNode或ContentBlock。 - 任务独立成实体：无论来源是题库、教材还是临时编写，每次发布的任务都是独立副本，拥有独立作答记录。
二、三层架构总览
| 层级 | 作用 | 核心实体 |
|---|---|---|
| 资源层 | 可复用的教学内容原材料 | Material、QuestionBlock、Question、Point |
| 内容产品层 | 固定出版的数字教材 | CourseBook、StructureNode、ContentBlock 及其 Payload 表 |
| 教学运行层 | 班级、编排、任务、学习痕迹 | Class、TeachingSchedule、ScheduleItem、Task、ContentBlockProgress、TaskAttempt |
三、资源层
Material（语料）
教材与题库共用的语料实体。通过 owner_type 区分题库级与教材内嵌级，内嵌语料不进入题库检索范围。
| 标记 | 字段 | 类型 | 说明 |
|---|---|---|---|
| PK | id | UUID | 主键 |
| owner_type | ENUM | question_bank / course_book | |
| owner_id | UUID | 所属题库或教材 | |
| genre | VARCHAR | 体裁 | |
| modality | VARCHAR[] | TEXT / AUDIO / VIDEO / IMAGE | |
| content | JSONB | 正文与媒体链接 | |
| source | ENUM | ai / human / hybrid | |
| review_status | ENUM | 仅题库级必填 |
QuestionBlock（题组）
题组与语料共用所有权模型。按 owner_type 区分题库级与教材内嵌级。
| 标记 | 字段 | 类型 |
|---|---|---|
| PK | id | UUID |
| owner_type | ENUM | |
| owner_id | UUID | |
| block_type | VARCHAR | |
| primary_skill | VARCHAR | |
| secondary_skills | VARCHAR[] | |
| instruction | TEXT | |
| difficulty | DECIMAL | |
| version | VARCHAR | |
| review_status | ENUM |
Question 与 Point
沿用题库四层模型：QuestionBlock → Question → Point。
| 实体 | 标记 | 字段 | 类型 |
|---|---|---|---|
| Question | PK | id | UUID |
| FK | question_block_id | UUID | |
| seq / body / b_form / scoring | — | ||
| Point | PK | id | UUID |
| FK | question_id | UUID | |
| seq / answer / score / blank_placeholder | — |
四、内容产品层
CourseBook（数字教材）
固定出版的内容产品，拥有版次、版本与出版状态。
StructureNode（结构节点）
教材的层级树，与内容块完全分离。level 决定深度，node_type 支持自定义层级名（Unit / Part / Section 等）。
ContentBlock（内容块壳）
最小可教学单元，按教学角色分为 6 类。仅挂载在叶子 StructureNode 下。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | UUID | 主键 |
| structure_node_id | UUID / FK | 所属叶子节点 |
| seq | INT | 节点内排序 |
| title | VARCHAR | 可选标题 |
| block_type | ENUM | material / instruction / activity / question / reference / navigation |
| is_assessed | BOOLEAN | 是否参与评分 |
| visible_to | ENUM | all / teacher / student / custom |
| version | VARCHAR | 版本号 |
ContentBlock 多态 Payload
每种 block_type 对应一张 Payload 表，与 content_block 一对一。关键 Payload 包括：
- MaterialBlock：
material_id、role_in_unit、teaching_notes、student_prompt - QuestionBlock Payload：
ref_type（引用/内嵌）、question_block_id、pinned_version - InstructionBlock / ActivityBlock / ReferenceBlock / NavigationBlock：各类型专有字段
五、教学运行层
Class（班级）
教学过程容器。引用主教材与辅助教材，但不复制教材结构。
TeachingSchedule 与 ScheduleItem
每个班级一份编排表；ScheduleItem 是最小编排单位。可写定日期，也可以仅表示顺序。
全范围 Item 机制
建班时自动生成一个 is_all_inclusive=true 的全范围 Item，引用主教材根节点。老师拖拽 ContentBlock 到具体 Item 时，该块从全范围 Item 的教学范围中移除，但仍对学生可见；删除具体 Item 时，内容自动回到全范围 Item。
| 状态 | 学生可见 | 纳入成绩 |
|---|---|---|
| 被 ScheduleItem 引用 | 是 | 是（若含计分 Task） |
| 全范围 Item 中的剩余块 | 是 | 否（可自学） |
| 老师明确隐藏 | 否 | 否 |
ScheduleItemTarget
一个 ScheduleItem 可引用多个 ContentBlock 或 StructureNode，支持跨教材。通过 source_course_book_id 与 pinned_version 锁定来源与版本。
Task（任务）
独立发布的作业、测验或练习。每次发布都是新实体，与来源题组解耦，拥有独立作答记录。
| 字段 | 说明 |
|---|---|
| task_type | from_question_block / from_material / free_form |
| source_question_block_id | 来源题组，发布时复制内容 |
| questions_json | 题目副本 |
| scoring_type | machine / ai / human / hybrid |
ContentBlockProgress 与 TaskAttempt
学习痕迹锚定到最小单元。ContentBlockProgress 记录内容消费，TaskAttempt 记录任务作答，共同支撑过程性评价。
六、关键边界约束
- 内嵌型
QuestionBlock/Material只归所在教材所有，不进入题库检索范围。 - 教材发布时，内嵌题组数量超过阈值或包含高风险题型，强制进入教材内容审核。
- 班级引用教材节点时，必须锁定教材版本，避免教材改版导致班级内容漂移。
Task复制后的题目副本与来源题组解耦，来源题组更新不影响已发布任务。
七、ER 图
说明
zigzagYang
POOLHOUSE-3.0-DATA-MODEL-20260820