Edu/docs/architecture/0010_architecture.md

抛开历史包袱和重构成本，如果我们站在 2026 年的上帝视角，为一个支撑百万级日活、多端（Web、App、小程序）、高并发（如全校同时交卷）的 K12 教育生态系统设计企业级理想架构，那么整个系统必须走向 “领域驱动设计 (DDD) + 彻底的事件驱动 (EDA) + 读写分离 (CQRS) + 异构微服务” 的云原生架构。

以下是现代企业级最优架构的设计蓝图：

一、 现代企业级架构全景图 在这种规模下，Next.js 不再充当“全栈巨石”，而是退化为纯粹的展示层 (Micro-Frontends) 和 BFF (Backend for Frontend)。

code Mermaid graph TB subgraph ClientLayer["1. 多端访问层 (Micro-Frontends)"] direction LR MFE1[Teacher Portal] MFE2[Student Portal] MFE3[Parent App] MFE4[Admin Console] end

subgraph EdgeLayer["2. 边缘与网关层 (API Gateway & BFF)"]
    WAF[WAF / CDN / 防火墙]
    Gateway[全局统一网关 API Gateway<br/>Kong / APISIX / 鉴权 / 限流]
    BFF1[Teacher BFF<br/>GraphQL]
    BFF2[Student BFF<br/>GraphQL]
    BFF3[Parent BFF<br/>GraphQL]
end

subgraph ServiceLayer["3. 领域微服务层 (Domain Services)"]
    IAM[IAM 服务<br/>认证授权/RBAC]
    CoreEdu[核心教学服务<br/>班级/排课/试卷/作业]
    Content[教研内容服务<br/>教材/知识图谱]
    DataAna[学情分析服务<br/>诊断/错题/成绩]
    Msg[消息调度服务<br/>通知/短信/SSE长连接]
    AI[AI 调度网关<br/>大模型接入/Prompt管理]
end

subgraph EventLayer["4. 事件驱动总线 (Event Data Platform)"]
    Kafka[Kafka / Pulsar 集群<br/>统一企业级事件总线]
end

subgraph DataLayer["5. 异构存储与数据层 (Polyglot Persistence)"]
    MySQL[(关系型主库<br/>分布式 MySQL/TiDB)]
    Redis[(缓存/分布式锁<br/>Redis Cluster)]
    ClickHouse[(分析型数据仓库<br/>ClickHouse / Doris)]
    Neo4j[(图数据库<br/>Neo4j / 知识图谱)]
    ES[(搜索引擎<br/>Elasticsearch)]
end

ClientLayer --> WAF
WAF --> Gateway
Gateway --> BFF1 & BFF2 & BFF3
BFF1 & BFF2 & BFF3 --> ServiceLayer

%% 服务与存储的交互
CoreEdu --> MySQL
IAM --> MySQL
Content --> Neo4j
DataAna --> ClickHouse
ServiceLayer --> Redis

%% CDC 与总线
MySQL -- "CDC (Debezium)<br/>捕获变更" --> Kafka
ServiceLayer -- "发布领域事件<br/>Outbox Pattern" --> Kafka
Kafka -- "消费事件" --> ServiceLayer
Kafka -- "同步读视图" --> ClickHouse
Kafka -- "索引同步" --> ES

二、 彻底解耦的四大核心设计模式 在最优架构中，系统通过以下企业级模式解决耦合问题：

1. 读写分离 (CQRS)：解决“上帝模块”与复杂聚合查询 在当前的 Next_Edu 中，Dashboard（仪表盘）需要查询所有模块。在企业级架构中，写入逻辑和查询逻辑是完全物理隔离的。

Command (写) 链路：教师批改作业，请求只打到 CoreEdu 微服务，该服务只更新 MySQL 中的作业表，并迅速返回。

Query (读) 链路：系统背后通过 CDC（如 Debezium）监听 MySQL 的 binlog，将数据变更实时推送到 Kafka。

物化视图构建：DataAna (数据分析微服务) 消费 Kafka 消息，在 ClickHouse 或 ES 中构建一个高度扁平的“宽表”（如 student_dashboard_view）。

收益：前端 Dashboard 请求 BFF 时，BFF 只查 ClickHouse 中的那一张宽表，毫秒级返回。没有 Join，没有跨服务调用，系统彻底解耦。

2. 发件箱模式 (Transactional Outbox)：解决跨模块数据一致性 如果模块 A 成功了，模块 B 失败了怎么办？企业级系统绝对不允许跨服务的数据库事务 (如 2PC)，因为会拖垮性能。

设计：教师发布考试时，CoreEdu 服务在同一个本地事务中做两件事：

往 exams 表写入考试数据。

往 outbox_events 表写入一条事件：{"type": "EXAM_PUBLISHED", "data": {...}}。

流转：后台的 CDC 组件（Debezium）监控到 outbox_events 表有新数据，自动将其投递到 Kafka。

收益：实现了 100% 保证的不丢消息的最终一致性。业务逻辑无需关心外部模块是否存活。

3. 编排与协同 (Orchestration vs. Choreography) 企业级架构处理复杂业务流（例如：考试创建 -> 智能组卷 -> 题目查重 -> 通知分发 -> 家长推送）必须区分两种模式：

协同 (Choreography - 基于事件)：适用于低耦合业务。发完作业后，发出 HomeworkCreated 事件，通知服务、积分服务各自监听，互相不知道对方存在。

编排 (Orchestration - 基于工作流)：适用于强状态依赖的业务。引入工作流引擎（如 Temporal 或 Camunda）。由一个中央 Coordinator 负责指挥：“先调 AI 生成题目，成功后再调试卷服务，如果失败就执行补偿逻辑回滚”。

4. 前端微前端化 (Micro-Frontends) 后端的解耦如果不配合前端的解耦，依然是一场灾难。

设计：通过 Module Federation（模块联邦）或 qiankun，将巨大的前端应用拆解。

收益：“排课组”的前端和后端可以独立发版，“题库组”的前端和后端可以独立发版。页面的组装在运行时由宿主框架完成。

三、 基础设施与扩展性设计 统一 API 网关 (API Gateway)

所有端点不再直接暴露。网关（如 Kong 或 APISIX）负责统一的 JWT 鉴权校验、黑名单拦截、全局限流（防 CC 攻击）。业务微服务默认收到请求时，用户身份已经是合法的。

长连接与推送网关独立

SSE 或 WebSocket 不再由业务容器承载。设立专门的 Push Gateway 服务（底层可基于 Go 或 Netty 编写，单节点支撑十万级连接）。业务服务只需往 Redis Pub/Sub 或 Kafka 发送消息，Push Gateway 负责广播给对应连接的客户端。

异构存储 (Polyglot Persistence)

知识图谱：教材和知识点的层级不再强行用 MySQL 存储，改为 Neo4j（图数据库），在执行“求某知识点的前置知识树”时性能提升百倍。

错题本/诊断：这些包含海量日志和时序数据的业务，直接存入 ClickHouse（列式数据库），亿级数据聚合秒级返回。

题库检索：题目内容实时同步到 Elasticsearch，支持分词、拼音、公式模糊全文搜索，而不是 MySQL 的 FULLTEXT。

四、 对比：为什么这是“最优”？ 维度 当前的单体/模块化 (Next_Edu V3) 现代企业级架构 结果差异 模块依赖 物理隔离，但代码级强引用 (import) 纯事件通信与 API 契约 任意微服务宕机/重构，完全不影响其他服务 聚合查询 并行查 5 个模块的 DB 再在内存拼装 后台预计算，直接查 ClickHouse 宽表 Dashboard 响应从 1.5s 降至 50ms 技术栈绑定 全部被绑死在 TypeScript + Next.js 异构。AI网关用Python，高并发网关用Go 能够根据业务特性选择最优技术 实时推送 Next.js SSE，连接数多了容易爆内存 独立的 Push Gateway + Redis PubSub 支持全校十万人同时在线答题的广播推送 容灾与扩容 只能整个应用一起扩容 核心教学扩 50 个 Pod，后台审计缩至 1 个 Pod 资源利用率极高，抗高并发能力呈指数级提升 总结 企业级架构的本质是承认分布式环境下的不完美，用基础设施的复杂性来换取业务代码的简单性。

业务模块不再需要操心“谁要我的数据”、“如何拼装别人的数据”、“事务失败怎么回滚”。它们只做一件事：接收指令 -> 改变自身领域模型 -> 将改变广播给全宇宙（Event Bus）.

蓝图设计的合理性（几乎全对，但有几个地方需要微调）

1. 各层选型精准，但有一处“过度理想” API Gateway + BFF + GraphQL： Gateway 做统一鉴权限流，BFF 做面向前端的聚合，GraphQL 允许不同端按需取数——这在多端下非常正确。 ✅ 唯一需要警惕的是 GraphQL 的 N+1 和深度嵌套，必须在 BFF 层用 DataLoader 批量化解，否则可能引入严重的下游放大调用。

事件总线选 Kafka/Pulsar： 对业务事件和 CDC 均用同一总线，完全可行。 ✅ 建议明确划分 领域事件 topic 与 数据同步 topic，两者消费模型不同（业务事件可能需回溯、重试；数据同步更适合顺序日志），在企业级通常用不同集群或至少独立 namespace。

CQRS + CDC + ClickHouse 宽表： 这是“彻底解耦聚合查询”的王道方案。 ⚠️ 但实时性要谨慎定义：从 MySQL binlog → Kafka → 消费者写入 ClickHouse，一般有 1-5 秒延迟。对于需要实时成绩展示的场景，可能需要 BFF 支持“查询主库 + 降级宽表”的混合读。 ⚠️ ClickHouse 宽表可能会变得非常庞大（列特别多），需要设计好聚合引擎表（SummingMergeTree / AggregatingMergeTree）和合理的分区键（如按学校+日期），否则维护成本极高。

图数据库 Neo4j 用于知识图谱： 正确，前置依赖查询性能会远远优于 MySQL 递归 CTE。但也要考虑知识图谱写入频率低、读频率高，Neo4j 单机足够，如果为了运维一致性，也可以用 PostgreSQL + Apache AGE 插件，但你的蓝图用 Neo4j 没问题。

Push Gateway 独立 + Redis Pub/Sub： 十万级连接通过独立长连接服务处理，是正确的。 ✅ 注意：Redis Pub/Sub 不持久化，如果有消息可靠性要求（离线再上线收不到历史推送），需要引入一个持久化队列或消息主题，由 Push Gateway 消费后推送给在线用户，同时标记已读。

2. 四大核心模式评价 CQRS：正确，这是消除“上帝模块”的根本解。

Transactional Outbox + CDC： 这是 唯一能保证最终一致性的分布式事务方案，比 2PC 和 Saga 都更适合高并发教育场景。 ✅ 但要注意：Outbox 表必须随业务服务独立部署，CDC 连接器（Debezium）需要监控其心跳和落后量，否则可能成为链路瓶颈。

Choreography vs Orchestration： 你提到用 Temporal/Camunda 做编排，这非常对。 ⚠️ 但要小心：“考试创建 → AI组卷 → 查重 → 通知分发”这类流程，如果使用全事件协同，会出现隐式状态机，维护复杂。用 Temporal 作为工作流引擎是明智的，Temporal 本身已经内置了重试、补偿、超时，比自研编排器强得多。

微前端： 在多团队并行开发下必要，但教育产品交互一致性要求高，需要强约束的设计系统和跨应用状态共享机制（如通过 BFF 或客户端共享 token + 用户上下文）。模块联邦 + 统一 UI 库是标配。

3. 基础设施层的一个潜在疏漏 你提到了 WAF、Gateway、Kafka、异构存储，但没有提到统一的配置中心与服务发现（如 Consul/Nacos/K8s Service）。在微服务体系下，服务动态扩缩容、配置热更新（如限流阈值、功能开关）必须同步规划，否则运维会变得困难。这一层通常与 Service Mesh（Istio）配合，可以在架构图中补上。