持久化与资源边界设计

1. 文档目的

本文档用于明确课程内核的持久化边界，防止课程资产、运行状态、任务日志和资源资产混写。

2. 四类核心对象

2.1 课程资产

表示课程工厂生成出的稳定结果。

核心对象：

• StageArtifact
• StageProjection

2.2 运行快照

表示课堂运行中间状态。

核心对象：

• RuntimeSnapshot
• LearningProgress

2.3 任务与审计日志

表示生成过程和运行过程的追踪对象。

核心对象：

• GenerationJob
• StageExecutionLog

2.4 资源资产

表示图片、视频、音频、导出文件等外部资源。

核心对象：

• AssetRef

3. 边界定义

3.1 StageArtifact

职责：

• 保存课程主骨架
• 保存课程可运行版本
• 保存训练结构

包含：

• Stage
• Unit[]
• Scene[]
• PracticePlan[]

不包含：

• 运行时游标
• 临时 provider 调用状态

3.2 StageProjection

职责：

• 表示某种消费视图

例如：

• ClassroomProjection
• TeacherNotesProjection
• PracticeSetProjection

3.3 RuntimeSnapshot

职责：

• 保存当前播放位置和运行上下文

3.4 AssetRef

职责：

• 引用对象存储中的外部文件
• 不承担业务主骨架

3.5 GenerationJob

职责：

• 记录任务生命周期
• 记录当前阶段和结果摘要

3.6 StageExecutionLog

职责：

• 保存阶段级事件与审计信息
• 用于重试、回溯和诊断

4. 数据库与对象存储分工

数据库存储

• 课程资产元数据
• 运行快照
• 学习进度
• 任务状态与日志
• 资源引用

对象存储保存

• 图片
• 视频
• 音频
• 大附件
• 导出文件

5. 当前推荐实践

1. 数据库保存结构和引用
2. 对象存储保存大体积资源
3. 运行快照单独存储，不写回课程资产正文
4. 任务日志单独存储，不混入课程表

6. 与主骨架的关系

课程主骨架是：

• Stage -> Unit -> Scene -> PracticePlan

持久化设计必须围绕它服务，而不是反过来让表结构决定课程结构。

7. 结论

只要以下四类边界稳定成立：

1. 课程资产
2. 运行快照
3. 任务日志
4. 资源资产

后续数据库设计和对象存储落地就不会再混层。