实施级目标架构与模块依赖图

1. 文档目的

本文档用于把蓝图层结论收敛成可实施的目标架构，重点定义包级职责、依赖方向和禁止越层规则。

2. 架构目标

当前目标架构固定为：

• 单仓 monorepo
• pnpm workspace
• 服务端为权威
• 模块化单体

第一阶段不拆成长生命周期微服务。

3. 模块清单

3.1 应用层

• apps/web
• apps/api

3.2 核心包

• packages/domain-model
• packages/generation-contracts
• packages/course-kernel
• packages/runtime-engine
• packages/subject-enhancers
• packages/infra-adapters

4. 模块职责

4.1 apps/web

负责：

• 老师创建、预览、播放入口
• 学生学习入口
• 训练与诊断结果展示

不负责：

• 定义课程协议
• 直接接入 provider SDK

4.2 apps/api

负责：

• 请求接入
• 任务编排
• 持久化
• 对外 API

4.3 packages/domain-model

负责：

• 领域对象
• 枚举
• 共享值对象

4.4 packages/generation-contracts

负责：

• 输入协议
• 阶段产物协议
• 任务与错误协议
• 投影协议

4.5 packages/course-kernel

负责：

• 三条主线装配
• 课程工厂主编排
• 训练结构装配

4.6 packages/runtime-engine

负责：

• 课堂运行状态机
• Scene 切换
• Action 执行
• 检查点和快照

4.7 packages/subject-enhancers

负责：

• 语数英等学科增强
• 模式库和学科表达策略

4.8 packages/infra-adapters

负责：

• LLM
• Image / Video
• TTS / ASR
• PDF
• Search
• DB / Queue / Storage

5. 依赖方向

flowchart LR
    WEB["apps/web"] --> API["apps/api"]
    API --> GC["generation-contracts"]
    API --> CK["course-kernel"]
    API --> RT["runtime-engine"]
    API --> IA["infra-adapters"]
    CK --> DM["domain-model"]
    CK --> GC
    CK --> SE["subject-enhancers"]
    CK --> IA
    RT --> DM
    RT --> IA
    SE --> DM
    GC --> DM
    IA --> EXT["DB / Queue / Object Storage / Providers"]

6. 禁止规则

1. domain-model 不依赖任何应用或基础设施模块
2. generation-contracts 不依赖 apps/*
3. runtime-engine 不依赖 course-kernel
4. subject-enhancers 不得反向主导核心协议
5. apps/web 不得直连数据库和 provider SDK

7. 生成链、运行链、适配层边界

7.1 生成链

从输入到 StageArtifact 的装配路径。

所属模块：

• generation-contracts
• course-kernel
• subject-enhancers
• infra-adapters

7.2 运行链

从 StageArtifact 到课堂执行、检查点和快照的路径。

所属模块：

• runtime-engine
• infra-adapters

7.3 基础设施适配层

负责把外部能力封装成稳定接口。

它不能决定课程结构，只能提供能力。

8. 当前实施顺序

1. 先建 domain-model
2. 再建 generation-contracts
3. 再建 course-kernel
4. 再接 apps/api
5. 再接 runtime-engine
6. 最后补 apps/web

9. 结论

当前实施级目标架构的核心不是“服务拆分得多细”，而是：

• 包级边界清晰
• 依赖方向单向
• 课程工厂与教学运行内核分离

只要这三点成立，后续实现就不会再被旧页面结构反向绑架。