xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): 004 架构图补充分层/领域双视角与视口四层模型

Browse Source 
- 1.1a 技术分层视角：用户层标注改为场景域用户
- 1.1b 业务领域视角：新增 6 领域 subgraph（D1-D6）
- 1.2 服务清单新增业务领域列
- 5.4 新增视口四层模型章节（L1-L4 + 场景域 BFF 复用策略）
This commit is contained in:
SpecialX
2026-07-08 12:50:13 +08:00
parent 3fbb97791d
commit bc3176cb05
1 changed files with 277 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

458
docs/architecture/004_architecture_impact_map.md
View File

@@ -5,8 +5,9 @@
> 状态：基线发布 > 状态：基线发布
> 适用范围：Edu 微服务架构（DDD + EDA + CQRS） > 适用范围：Edu 微服务架构（DDD + EDA + CQRS）
> 关联文档： > 关联文档：
>
> - [理想蓝图](./0010_architecture.md) > - [理想蓝图](./0010_architecture.md)
> - [项目规则](../../project_rules.md) > - [项目规则](../../.trae/rules/project_rules.md)
> - [路线图](./roadmap/README.md) > - [路线图](./roadmap/README.md)
--- ---
@@ -32,22 +33,25 @@
## 1. 项目概述 ## 1. 项目概述
### 1.1 系统边界 ### 1.1a 技术分层视角（系统边界）
> 本图展示**部署分层结构**（自上而下：用户 → 微前端 → 网关 → BFF → 业务服务 → 总线 → 数据）。
> 用户层按"使用场景域"标注，BFF 层按场景域分（不是按角色分）。业务领域视角见 [1.1b](#11b-业务领域视角)。
```mermaid ```mermaid
graph TB graph TB
subgraph Users["用户层"] subgraph Users["用户层（场景域用户）"]
Teacher[教师] Teacher["教学场景域用户<br/>（教师 / 教导主任 / 教研组长 共用）"]
Student[学生] Student["学习场景域用户<br/>（学生）"]
Parent[家长] Parent["家长场景域用户<br/>（家长）"]
Admin[管理员] Admin["管理场景域用户<br/>（系统管理员 / 校管理员）"]
end end
subgraph MFE["微前端层（Module Federation）"] subgraph MFE["微前端层（Module Federation）"]
TeacherPortal[teacher-portal] TeacherPortal["teacher-portal<br/>教学场景域前端"]
StudentPortal[student-portal] StudentPortal["student-portal<br/>学习场景域前端"]
ParentPortal[parent-portal] ParentPortal["parent-portal<br/>家长场景域前端"]
AdminPortal[admin-portal] AdminPortal["admin-portal<br/>管理场景域前端"]
end end
subgraph Gateway["网关层（Go）"] subgraph Gateway["网关层（Go）"]
@@ -55,10 +59,10 @@ graph TB
PushGateway[push-gateway<br/>WebSocket/SSE] PushGateway[push-gateway<br/>WebSocket/SSE]
end end
subgraph BFF["BFF 聚合层（NestJS）"] subgraph BFF["BFF 聚合层（NestJS）<br/>按使用场景域分 BFF（不是按角色分）"]
TeacherBFF[teacher-bff<br/>GraphQL] TeacherBFF["teacher-bff<br/>教学场景域聚合"]
StudentBFF[student-bff<br/>GraphQL] StudentBFF["student-bff<br/>学习场景域聚合"]
ParentBFF[parent-bff<br/>GraphQL] ParentBFF["parent-bff<br/>家长场景域聚合"]
end end
subgraph Services["业务微服务（NestJS + FastAPI）"] subgraph Services["业务微服务（NestJS + FastAPI）"]
@@ -128,44 +132,100 @@ graph TB
CoreEdu --> Redis CoreEdu --> Redis
``` ```
### 1.1b 业务领域视角
> 本图按 **DDD 限界上下文**展示 6 个业务领域及其依赖关系。同一服务可横跨多个领域（如 core-edu 同时承载"教学组织"与"教学核心"）。
> 技术分层视角见 [1.1a](#11a-技术分层视角系统边界)。
```mermaid
graph TB
subgraph D1["D1 身份认证领域"]
IAM[iam 服务]
IAM_M[users / roles / permissions<br/>refresh_tokens / sessions]
end
subgraph D2["D2 教学组织领域"]
ORG[core-edu 服务<br/>classes 模块]
ORG_M[classes / subjects / enrollment]
end
subgraph D3["D3 教学核心领域"]
TEACH[core-edu 服务<br/>exams/homework/grades]
TEACH_M[exams / homework / grades<br/>courses / lessons / schedule / attendance]
end
subgraph D4["D4 内容资源领域"]
CONTENT[content 服务]
CONTENT_M[textbooks / knowledge-points<br/>questions / grading / search(ES)]
end
subgraph D5["D5 沟通通知领域"]
MSG[msg 服务]
MSG_M[messaging / notifications / announcements]
end
subgraph D6["D6 智能洞察领域"]
DATA[data-ana 服务]
AI[ai 服务]
DATA_M[analytics / dashboard / diagnostic(ClickHouse)]
AI_M[ai 备课/出题/分析 / search]
end
D1 --> D2
D1 --> D3
D1 --> D4
D1 --> D5
D2 --> D3
D3 --> D4
D3 --> D5
D4 --> D6
D3 --> D6
```
**双图并存说明**：
- **1.1a 技术分层**：描述部署、流量路径、网络边界，关注"如何部署与调用"
- **1.1b 业务领域**：描述 DDD 限界上下文、聚合根、领域依赖，关注"业务边界与归属"
- 两图互补，分别服务于运维/SRE 与产品/架构视角
### 1.2 服务清单 ### 1.2 服务清单
| 类别 | 服务名 | 语言/框架 | 限界上下文 | 阶段 | | 类别 | 服务名 | 语言/框架 | 限界上下文 | 业务领域 | 阶段 |
|------|--------|-----------|-----------|------| | -------- | -------------- | ---------------- | --------------- | ----------------------------- | ---- |
| 基础设施 | api-gateway | Go (Gin) | 网关 | P1 | | 基础设施 | api-gateway | Go (Gin) | 网关 | — | P1 |
| 基础设施 | push-gateway | Go (Gin) | 推送 | P5 | | 基础设施 | push-gateway | Go (Gin) | 推送 | — | P5 |
| BFF | teacher-bff | TS (NestJS) | 教师聚合 | P2 | | BFF | teacher-bff | TS (NestJS) | 教师聚合 | 教学场景域 | P2 |
| BFF | student-bff | TS (NestJS) | 学生聚合 | P3 | | BFF | student-bff | TS (NestJS) | 学生聚合 | 学习场景域 | P3 |
| BFF | parent-bff | TS (NestJS) | 家长聚合 | P4 | | BFF | parent-bff | TS (NestJS) | 家长聚合 | 家长场景域 | P4 |
| 业务 | iam | TS (NestJS) | 身份认证 | P2 | | 业务 | iam | TS (NestJS) | 身份认证 | **D1 身份认证** | P2 |
| 业务 | core-edu | TS (NestJS) | 教学核心 | P3 | | 业务 | core-edu | TS (NestJS) | 教学核心 | **D2 教学组织 + D3 教学核心** | P3 |
| 业务 | content | TS (NestJS) | 内容资源 | P4 | | 业务 | content | TS (NestJS) | 内容资源 | **D4 内容资源** | P4 |
| 业务 | data-ana | Python (FastAPI) | 数据分析 | P4 | | 业务 | data-ana | Python (FastAPI) | 数据分析 | **D6 智能洞察** | P4 |
| 业务 | msg | TS (NestJS) | 消息通知 | P5 | | 业务 | msg | TS (NestJS) | 消息通知 | **D5 沟通通知** | P5 |
| 业务 | ai | Python (FastAPI) | AI 网关 | P5 | | 业务 | ai | Python (FastAPI) | AI 网关 | **D6 智能洞察** | P5 |
| 微前端 | teacher-portal | TS (Next.js) | 教师端 | P2 | | 微前端 | teacher-portal | TS (Next.js) | 教师端 | 教学场景域 | P2 |
| 微前端 | student-portal | TS (Next.js) | 学生端 | P3 | | 微前端 | student-portal | TS (Next.js) | 学生端 | 学习场景域 | P3 |
| 微前端 | parent-portal | TS (Next.js) | 家长端 | P4 | | 微前端 | parent-portal | TS (Next.js) | 家长端 | 家长场景域 | P4 |
| 微前端 | admin-portal | TS (Next.js) | 管理端 | P6 | | 微前端 | admin-portal | TS (Next.js) | 管理端 | 管理场景域 | P6 |
| 共享包 | shared-proto | TS | protobuf 契约 | P1 | | 共享包 | shared-proto | TS | protobuf 契约 | — | P1 |
| 共享包 | shared-ts | TS | TS 共享工具 | P1 | | 共享包 | shared-ts | TS | TS 共享工具 | — | P1 |
| 共享包 | shared-go | Go | Go 共享工具 | P1 | | 共享包 | shared-go | Go | Go 共享工具 | — | P1 |
| 共享包 | shared-py | Python | Python 共享工具 | P4 | | 共享包 | shared-py | Python | Python 共享工具 | — | P4 |
### 1.3 CICD → Edu 模块映射 ### 1.3 CICD → Edu 模块映射
| CICD 模块（旧） | Edu 服务（新） | 迁移阶段 | | CICD 模块（旧） | Edu 服务（新） | 迁移阶段 |
|----------------|---------------|----------| | ----------------------------------------- | -------------- | -------- |
| auth + users + rbac | iam | P2 | | auth + users + rbac | iam | P2 |
| classes + subjects + enrollment | core-edu | P3 | | classes + subjects + enrollment | core-edu | P3 |
| courses + lessons + schedule + attendance | core-edu | P3 | | courses + lessons + schedule + attendance | core-edu | P3 |
| assignments + grades + exams | core-edu | P3 | | assignments + grades + exams | core-edu | P3 |
| textbooks + knowledge-points | content | P4 | | textbooks + knowledge-points | content | P4 |
| questions + grading | content | P4 | | questions + grading | content | P4 |
| messaging + notifications | msg | P5 | | messaging + notifications | msg | P5 |
| analytics + dashboard + diagnostic | data-ana | P4 | | analytics + dashboard + diagnostic | data-ana | P4 |
| ai + lesson-preparation | ai | P5 | | ai + lesson-preparation | ai | P5 |
| search | content (ES) | P4 | | search | content (ES) | P4 |
--- ---
@@ -173,38 +233,38 @@ graph TB
### 2.1 多语言技术栈矩阵 ### 2.1 多语言技术栈矩阵
| 层级 | 语言 | 框架 | 用途 | | 层级 | 语言 | 框架 | 用途 |
|------|------|------|------| | -------- | --------------- | ------------------------------ | -------------------------- |
| 网关层 | Go 1.22+ | Gin | API Gateway、Push Gateway | | 网关层 | Go 1.22+ | Gin | API Gateway、Push Gateway |
| 业务服务 | TypeScript 5.5+ | NestJS 10 | IAM、CoreEdu、Content、Msg | | 业务服务 | TypeScript 5.5+ | NestJS 10 | IAM、CoreEdu、Content、Msg |
| 分析/AI | Python 3.12+ | FastAPI | DataAna、AI 网关 | | 分析/AI | Python 3.12+ | FastAPI | DataAna、AI 网关 |
| BFF | TypeScript 5.5+ | NestJS 10 + GraphQL | 教师/学生/家长聚合 | | BFF | TypeScript 5.5+ | NestJS 10 + GraphQL | 教师/学生/家长聚合 |
| 微前端 | TypeScript 5.5+ | Next.js 15 + Module Federation | 4 端门户 | | 微前端 | TypeScript 5.5+ | Next.js 15 + Module Federation | 4 端门户 |
| 契约 | protobuf | buf | 跨语言契约定义 | | 契约 | protobuf | buf | 跨语言契约定义 |
### 2.2 多存储矩阵 ### 2.2 多存储矩阵
| 存储 | 用途 | 使用服务 | | 存储 | 用途 | 使用服务 |
|------|------|----------| | ------------- | ------------------------ | -------------------------- |
| MySQL 8 | 写模型主库（每服务独占） | IAM、CoreEdu、Content、Msg | | MySQL 8 | 写模型主库（每服务独占） | IAM、CoreEdu、Content、Msg |
| Redis 7 | 缓存、会话、限流计数 | 全部服务 | | Redis 7 | 缓存、会话、限流计数 | 全部服务 |
| ClickHouse | 读模型宽表、分析聚合 | DataAna、CoreEdu（读模型） | | ClickHouse | 读模型宽表、分析聚合 | DataAna、CoreEdu（读模型） |
| Neo4j | 知识图谱、前置依赖 | Content | | Neo4j | 知识图谱、前置依赖 | Content |
| Elasticsearch | 题库全文检索 | Content、AI | | Elasticsearch | 题库全文检索 | Content、AI |
### 2.3 基础设施矩阵 ### 2.3 基础设施矩阵
| 组件 | 用途 | | 组件 | 用途 |
|------|------| | ------------- | ----------------------------------- |
| Kafka | 事件总线，领域事件异步通信 | | Kafka | 事件总线，领域事件异步通信 |
| Debezium | CDC，MySQL Binlog → Kafka 实时同步 | | Debezium | CDC，MySQL Binlog → Kafka 实时同步 |
| Temporal | 工作流编排（考试生命周期、AI 编排） | | Temporal | 工作流编排（考试生命周期、AI 编排） |
| OpenTelemetry | 分布式追踪 | | OpenTelemetry | 分布式追踪 |
| Loki | 日志聚合 | | Loki | 日志聚合 |
| Tempo | 分布式 Trace 存储 | | Tempo | 分布式 Trace 存储 |
| Prometheus | 指标采集 | | Prometheus | 指标采集 |
| Grafana | 可观测性可视化 | | Grafana | 可观测性可视化 |
| Vault | 密钥管理（P6） | | Vault | 密钥管理（P6） |
--- ---
@@ -260,6 +320,7 @@ L1 客户端 → L2 微前端 → L3 网关 → L4 BFF → L5 业务服务 → L
``` ```
**严格规则**： **严格规则**：
1. L3 网关层只做路由、鉴权、限流、熔断，**不写业务逻辑** 1. L3 网关层只做路由、鉴权、限流、熔断，**不写业务逻辑**
2. L4 BFF 层只做聚合、裁剪、协议转换，**不持有业务状态** 2. L4 BFF 层只做聚合、裁剪、协议转换，**不持有业务状态**
3. L5 业务服务之间通过 gRPC（同步）或 Kafka 事件（异步）通信，**不直接访问对方数据库** 3. L5 业务服务之间通过 gRPC（同步）或 Kafka 事件（异步）通信，**不直接访问对方数据库**
@@ -339,17 +400,17 @@ graph TB
### 4.1 服务间通信矩阵 ### 4.1 服务间通信矩阵
| 调用方 → 被调用方 | 协议 | 场景 | | 调用方 → 被调用方 | 协议 | 场景 |
|-------------------|------|------| | ------------------ | ---------- | ---------------- |
| api-gateway → BFF | gRPC | 请求路由 | | api-gateway → BFF | gRPC | 请求路由 |
| BFF → 业务服务 | gRPC | 同步查询聚合 | | BFF → 业务服务 | gRPC | 同步查询聚合 |
| CoreEdu → Content | Kafka 事件 | 教学内容变更通知 | | CoreEdu → Content | Kafka 事件 | 教学内容变更通知 |
| CoreEdu → DataAna | Kafka 事件 | 学情数据投递 | | CoreEdu → DataAna | Kafka 事件 | 学情数据投递 |
| CoreEdu → Msg | Kafka 事件 | 通知触发 | | CoreEdu → Msg | Kafka 事件 | 通知触发 |
| IAM → CoreEdu | Kafka 事件 | 用户变更同步 | | IAM → CoreEdu | Kafka 事件 | 用户变更同步 |
| AI → Content | gRPC | 题库查询 | | AI → Content | gRPC | 题库查询 |
| AI → DataAna | gRPC | 学情数据查询 | | AI → DataAna | gRPC | 学情数据查询 |
| push-gateway → Msg | gRPC | 推送通道建立 | | push-gateway → Msg | gRPC | 推送通道建立 |
--- ---
@@ -389,27 +450,61 @@ sequenceDiagram
### 5.2 三层角色模型 ### 5.2 三层角色模型
| 层级 | 来源 | 示例 | 优先级 | | 层级 | 来源 | 示例 | 优先级 |
|------|------|------|--------| | -------- | ------------- | ------------------------------- | ------ |
| 系统角色 | 系统预设 | admin、teacher、student、parent | 最高 | | 系统角色 | 系统预设 | admin、teacher、student、parent | 最高 |
| 组织角色 | 学校/班级分配 | 年级组长、班主任、学科组长 | 中 | | 组织角色 | 学校/班级分配 | 年级组长、班主任、学科组长 | 中 |
| 临时角色 | 临时授权 | 代课教师、临时代理 | 最低 | | 临时角色 | 临时授权 | 代课教师、临时代理 | 最低 |
**规则**：权限取三层角色权限的并集，拒绝权限取交集（任一层拒绝则拒绝）。 **规则**：权限取三层角色权限的并集，拒绝权限取交集（任一层拒绝则拒绝）。
### 5.3 DataScope 6 级数据范围 ### 5.3 DataScope 6 级数据范围
| 级别 | 名称 | 数据范围 | 典型角色 | | 级别 | 名称 | 数据范围 | 典型角色 |
|------|------|----------|----------| | ---- | -------- | ---------- | ------------ |
| L0 | SELF | 仅本人数据 | 学生、家长 | | L0 | SELF | 仅本人数据 | 学生、家长 |
| L1 | CLASS | 本班数据 | 班主任、学生 | | L1 | CLASS | 本班数据 | 班主任、学生 |
| L2 | GRADE | 本年级数据 | 年级组长 | | L2 | GRADE | 本年级数据 | 年级组长 |
| L3 | SCHOOL | 本校数据 | 校管理员 | | L3 | SCHOOL | 本校数据 | 校管理员 |
| L4 | DISTRICT | 本区数据 | 区教研员 | | L4 | DISTRICT | 本区数据 | 区教研员 |
| L5 | ALL | 全部数据 | 系统管理员 | | L5 | ALL | 全部数据 | 系统管理员 |
**实现**：业务服务在 Repository 层根据 dataScope 级别动态注入 WHERE 条件。 **实现**：业务服务在 Repository 层根据 dataScope 级别动态注入 WHERE 条件。
### 5.4 视口四层模型
视口（Viewport）是用户在特定场景域下的可见范围。视口既可独立配置（RoleViewport 表），
也可由权限推导（permission → viewport 默认映射）。新角色只需配置权限集，视口自动推导；
需要差异化时再显式配置视口。
| 层级 | 含义 | 配置载体 | 示例 |
| ------- | ---------------- | ---------------------------------- | -------------------------------------------- |
| L1 导航 | 侧边栏菜单项 | navigation_config 表 | 教导主任看到"全校成绩分析"菜单 |
| L2 路由 | 可访问路由 | route_permission 表 + Gateway 校验 | 教导主任可访问 /admin/grade-analysis |
| L3 组件 | 页面内组件可见性 | usePermission().hasPermission() | 教导主任看到"导出全校报表"按钮 |
| L4 数据 | 数据行级过滤 | DataScope 枚举 | 教导主任 DataScope=grade_managed（管辖年级） |
**场景域 BFF 复用策略**：
按"使用场景域"分 BFF，而非按角色分。新角色复用现有 BFF，通过视口差异化。
| BFF | 场景域 | 复用角色 |
| ----------- | -------- | ------------------------ |
| Teacher BFF | 教学场景 | 教师、教导主任、教研组长 |
| Student BFF | 学习场景 | 学生 |
| Parent BFF | 家长场景 | 家长 |
| Admin BFF | 管理场景 | 系统管理员、校管理员 |
**实现**：教导主任归入 Teacher BFF + 额外管理视口（L1 导航增加管理菜单项，L4 数据范围扩大到年级）。
**iam 服务职责**：
- 认证：登录/登出/JWT/2FA
- RBAC：角色/权限/角色-权限映射 CRUD
- 视口配置：导航/路由/组件级视口配置 CRUD
- DataScope：数据范围解析（all/grade_managed/class_taught/children/owned + 自定义）
- 权限解析 API：getEffectivePermissions(userId) → {permissions, viewports, dataScope}
--- ---
## 6. 数据访问与缓存 ## 6. 数据访问与缓存
@@ -461,15 +556,15 @@ flowchart TD
### 6.3 缓存策略矩阵 ### 6.3 缓存策略矩阵
| 数据类型 | 存储 | TTL | 失效策略 | | 数据类型 | 存储 | TTL | 失效策略 |
|----------|------|-----|----------| | ------------- | ---------- | ------- | ------------ |
| 用户会话 | Redis | 30 分钟 | 滑动过期 | | 用户会话 | Redis | 30 分钟 | 滑动过期 |
| 权限列表 | Redis | 5 分钟 | 事件驱动失效 | | 权限列表 | Redis | 5 分钟 | 事件驱动失效 |
| 班级/年级列表 | Redis | 5 分钟 | 事件驱动失效 | | 班级/年级列表 | Redis | 5 分钟 | 事件驱动失效 |
| 教学资源详情 | Redis | 30 秒 | 短 TTL | | 教学资源详情 | Redis | 30 秒 | 短 TTL |
| BFF 聚合结果 | Redis | 5-30 秒 | 短 TTL | | BFF 聚合结果 | Redis | 5-30 秒 | 短 TTL |
| 学情宽表 | ClickHouse | 实时 | CDC 同步 | | 学情宽表 | ClickHouse | 实时 | CDC 同步 |
| 题库检索 | ES | 实时 | CDC 同步 | | 题库检索 | ES | 实时 | CDC 同步 |
--- ---
@@ -520,27 +615,27 @@ graph LR
### 7.2 事件 Topic 分类 ### 7.2 事件 Topic 分类
| Topic 模式 | 示例 | 生产者 | 消费者 | | Topic 模式 | 示例 | 生产者 | 消费者 |
|-----------|------|--------|--------| | ----------------------------------- | ---------- | ------- | ------------ |
| `edu.identity.user.created` | 用户创建 | IAM | CoreEdu、Msg | | `edu.identity.user.created` | 用户创建 | IAM | CoreEdu、Msg |
| `edu.identity.user.updated` | 用户更新 | IAM | CoreEdu、Msg | | `edu.identity.user.updated` | 用户更新 | IAM | CoreEdu、Msg |
| `edu.org.class.created` | 班级创建 | CoreEdu | DataAna | | `edu.org.class.created` | 班级创建 | CoreEdu | DataAna |
| `edu.teaching.assignment.submitted` | 作业提交 | CoreEdu | DataAna、Msg | | `edu.teaching.assignment.submitted` | 作业提交 | CoreEdu | DataAna、Msg |
| `edu.teaching.exam.published` | 考试发布 | CoreEdu | Msg | | `edu.teaching.exam.published` | 考试发布 | CoreEdu | Msg |
| `edu.teaching.grade.recorded` | 成绩录入 | CoreEdu | DataAna、Msg | | `edu.teaching.grade.recorded` | 成绩录入 | CoreEdu | DataAna、Msg |
| `edu.content.question.published` | 题目发布 | Content | AI、ES | | `edu.content.question.published` | 题目发布 | Content | AI、ES |
| `edu.insight.mastery.updated` | 掌握度更新 | DataAna | CoreEdu、Msg | | `edu.insight.mastery.updated` | 掌握度更新 | DataAna | CoreEdu、Msg |
### 7.3 核心领域事件 ### 7.3 核心领域事件
| 事件 | 触发场景 | 消费者动作 | | 事件 | 触发场景 | 消费者动作 |
|------|----------|-----------| | --------------------- | -------------- | ------------------------------------------------ |
| UserRegistered | 新用户注册 | CoreEdu 初始化默认班级关联；Msg 发送欢迎通知 | | UserRegistered | 新用户注册 | CoreEdu 初始化默认班级关联；Msg 发送欢迎通知 |
| ExamPublished | 考试发布 | Msg 推送考试通知给学生；DataAna 创建考试分析骨架 | | ExamPublished | 考试发布 | Msg 推送考试通知给学生；DataAna 创建考试分析骨架 |
| HomeworkSubmitted | 学生提交作业 | DataAna 记录提交行为；Msg 通知教师 | | HomeworkSubmitted | 学生提交作业 | DataAna 记录提交行为；Msg 通知教师 |
| HomeworkGraded | 教师批改完成 | DataAna 更新掌握度；Msg 通知学生 | | HomeworkGraded | 教师批改完成 | DataAna 更新掌握度；Msg 通知学生 |
| MasteryUpdated | 掌握度计算完成 | CoreEdu 推荐个性化练习；Msg 触发预警 | | MasteryUpdated | 掌握度计算完成 | CoreEdu 推荐个性化练习；Msg 触发预警 |
| NotificationRequested | 通知请求 | Msg 投递通知到多渠道 | | NotificationRequested | 通知请求 | Msg 投递通知到多渠道 |
--- ---
@@ -768,6 +863,7 @@ flowchart LR
``` ```
**规则**： **规则**：
- 所有跨服务调用必须透传 W3C Trace Context - 所有跨服务调用必须透传 W3C Trace Context
- Kafka 事件必须将 traceId 写入消息 header - Kafka 事件必须将 traceId 写入消息 header
- 日志必须包含 traceId 用于关联查询 - 日志必须包含 traceId 用于关联查询
@@ -821,15 +917,15 @@ graph TB
### 11.2 契约规则 ### 11.2 契约规则
| 规则 | 说明 | | 规则 | 说明 |
|------|------| | -------- | -------------------------------------- |
| 包命名 | `edu.[context].[aggregate].v[version]` | | 包命名 | `edu.[context].[aggregate].v[version]` |
| 版本化 | 破坏性变更必须升版本（v1 → v2） | | 版本化 | 破坏性变更必须升版本（v1 → v2） |
| 字段编号 | 禁止复用已删除字段编号，使用 reserved | | 字段编号 | 禁止复用已删除字段编号，使用 reserved |
| 消息命名 | PascalCase | | 消息命名 | PascalCase |
| 字段命名 | snake_case | | 字段命名 | snake_case |
| 注释 | 每个 message 和字段必须注释 | | 注释 | 每个 message 和字段必须注释 |
| CI 强制 | buf lint + buf breaking 必须通过 | | CI 强制 | buf lint + buf breaking 必须通过 |
### 11.3 BFF 聚合模式 ### 11.3 BFF 聚合模式
@@ -865,56 +961,56 @@ graph LR
### 12.1 服务独立性约束 ### 12.1 服务独立性约束
| 约束 | 说明 | | 约束 | 说明 |
|------|------| | ----------- | -------------------------------------- |
| 数据库独占 | 每个微服务独占自身数据库，禁止跨库联表 | | 数据库独占 | 每个微服务独占自身数据库，禁止跨库联表 |
| 契约先行 | 所有跨服务通信必须先定义 protobuf 契约 | | 契约先行 | 所有跨服务通信必须先定义 protobuf 契约 |
| Outbox 强制 | 所有领域事件必须通过 Outbox 模式发布 | | Outbox 强制 | 所有领域事件必须通过 Outbox 模式发布 |
| 幂等消费 | 所有事件消费者必须实现幂等性 | | 幂等消费 | 所有事件消费者必须实现幂等性 |
| 单一职责 | 每个服务只负责一个限界上下文 | | 单一职责 | 每个服务只负责一个限界上下文 |
| 无状态服务 | 业务服务不持有会话状态（Redis 承载） | | 无状态服务 | 业务服务不持有会话状态（Redis 承载） |
### 12.2 通信约束 ### 12.2 通信约束
| 场景 | 允许 | 禁止 | | 场景 | 允许 | 禁止 |
|------|------|------| | -------------------- | ---------------- | ------------------- |
| 客户端 → Gateway | REST + WebSocket | 直连业务服务 | | 客户端 → Gateway | REST + WebSocket | 直连业务服务 |
| Gateway → BFF | gRPC | REST | | Gateway → BFF | gRPC | REST |
| BFF → 业务服务 | gRPC | 直接访问 DB | | BFF → 业务服务 | gRPC | 直接访问 DB |
| 业务服务之间（同步） | gRPC + 必要时 | REST、直接 DB | | 业务服务之间（同步） | gRPC + 必要时 | REST、直接 DB |
| 业务服务之间（异步） | Kafka 事件 | 直接 producer 调用 | | 业务服务之间（异步） | Kafka 事件 | 直接 producer 调用 |
| 事件发布 | Outbox 模式 | 直接 Kafka producer | | 事件发布 | Outbox 模式 | 直接 Kafka producer |
### 12.3 数据一致性约束 ### 12.3 数据一致性约束
| 场景 | 一致性级别 | 实现 | | 场景 | 一致性级别 | 实现 |
|------|-----------|------| | ------ | ---------- | --------------------- |
| 聚合内 | 强一致 | 单事务 | | 聚合内 | 强一致 | 单事务 |
| 聚合间 | 最终一致 | Kafka 事件 | | 聚合间 | 最终一致 | Kafka 事件 |
| 服务间 | 最终一致 | Kafka 事件 / Saga | | 服务间 | 最终一致 | Kafka 事件 / Saga |
| 读模型 | 最终一致 | Projection 异步更新 | | 读模型 | 最终一致 | Projection 异步更新 |
| 缓存 | 最终一致 | 事件驱动失效 + 短 TTL | | 缓存 | 最终一致 | 事件驱动失效 + 短 TTL |
--- ---
## 13. ADR 记录 ## 13. ADR 记录
| 编号 | 决策 | 原因 | 状态 | | 编号 | 决策 | 原因 | 状态 |
|------|------|------|------| | ------- | ----------------------------- | --------------------------------- | ------ |
| ADR-001 | 采用 DDD 限界上下文划分服务 | 业务边界清晰，独立演进 | 已采纳 | | ADR-001 | 采用 DDD 限界上下文划分服务 | 业务边界清晰，独立演进 | 已采纳 |
| ADR-002 | 采用 NestJS 作为业务服务框架 | TS 生态成熟，装饰器 + DI 适合 DDD | 已采纳 | | ADR-002 | 采用 NestJS 作为业务服务框架 | TS 生态成熟，装饰器 + DI 适合 DDD | 已采纳 |
| ADR-003 | 采用 Go 作为网关语言 | 高并发、低内存、适合网关场景 | 已采纳 | | ADR-003 | 采用 Go 作为网关语言 | 高并发、低内存、适合网关场景 | 已采纳 |
| ADR-004 | 采用 Python 作为分析/AI 语言 | 数据科学/AI 生态丰富 | 已采纳 | | ADR-004 | 采用 Python 作为分析/AI 语言 | 数据科学/AI 生态丰富 | 已采纳 |
| ADR-005 | 采用 CQRS 读写分离 | 读多写少，读模型可独立优化 | 已采纳 | | ADR-005 | 采用 CQRS 读写分离 | 读多写少，读模型可独立优化 | 已采纳 |
| ADR-006 | 采用 Outbox 模式发布事件 | 保证事务与事件最终一致 | 已采纳 | | ADR-006 | 采用 Outbox 模式发布事件 | 保证事务与事件最终一致 | 已采纳 |
| ADR-007 | 采用 Kafka 作为事件总线 | 高吞吐、持久化、成熟生态 | 已采纳 | | ADR-007 | 采用 Kafka 作为事件总线 | 高吞吐、持久化、成熟生态 | 已采纳 |
| ADR-008 | 采用 Debezium CDC | 解耦 Outbox Relay，减少业务侵入 | 已采纳 | | ADR-008 | 采用 Debezium CDC | 解耦 Outbox Relay，减少业务侵入 | 已采纳 |
| ADR-009 | 采用 protobuf + buf 契约先行 | 多语言契约统一、版本化、CI 强制 | 已采纳 | | ADR-009 | 采用 protobuf + buf 契约先行 | 多语言契约统一、版本化、CI 强制 | 已采纳 |
| ADR-010 | 采用 JWT RS256 非对称签名 | 网关公钥校验无需共享私钥 | 已采纳 | | ADR-010 | 采用 JWT RS256 非对称签名 | 网关公钥校验无需共享私钥 | 已采纳 |
| ADR-011 | 采用 DataScope 6 级数据范围 | 满足 K12 多层级数据隔离 | 已采纳 | | ADR-011 | 采用 DataScope 6 级数据范围 | 满足 K12 多层级数据隔离 | 已采纳 |
| ADR-012 | 采用 Module Federation 微前端 | 独立部署、技术栈无关、渐进迁移 | 已采纳 | | ADR-012 | 采用 Module Federation 微前端 | 独立部署、技术栈无关、渐进迁移 | 已采纳 |
| ADR-013 | 采用 Temporal 工作流编排 | 长流程编排、可观测、可回滚 | 已采纳 | | ADR-013 | 采用 Temporal 工作流编排 | 长流程编排、可观测、可回滚 | 已采纳 |
| ADR-014 | 采用 ClickHouse 读模型宽表 | 分析查询亚秒级响应 | 已采纳 | | ADR-014 | 采用 ClickHouse 读模型宽表 | 分析查询亚秒级响应 | 已采纳 |
--- ---
@@ -933,13 +1029,13 @@ graph LR
### 14.2 服务与阶段映射 ### 14.2 服务与阶段映射
| 阶段 | 周期 | 交付服务 | 退出标准 | | 阶段 | 周期 | 交付服务 | 退出标准 |
|------|------|----------|----------| | ----------- | ------- | ----------------------------------------------------- | ------------------------------ |
| P1 地基 | M1-M3 | api-gateway、classes（黄金模板）、shared-proto | classes 域 CRUD 端到端跑通 | | P1 地基 | M1-M3 | api-gateway、classes（黄金模板）、shared-proto | classes 域 CRUD 端到端跑通 |
| P2 身份 | M4-M6 | iam、teacher-bff、teacher-portal 骨架 | 教师可登录并看到空白 Dashboard | | P2 身份 | M4-M6 | iam、teacher-bff、teacher-portal 骨架 | 教师可登录并看到空白 Dashboard |
| P3 核心教学 | M7-M10 | core-edu（合并 classes）、student-bff、student-portal | 考试→作答→批改→成绩全链路 | | P3 核心教学 | M7-M10 | core-edu（合并 classes）、student-bff、student-portal | 考试→作答→批改→成绩全链路 |
| P4 内容分析 | M11-M13 | content、data-ana、parent-bff、parent-portal | 知识图谱查询 + 学情宽表 5s | | P4 内容分析 | M11-M13 | content、data-ana、parent-bff、parent-portal | 知识图谱查询 + 学情宽表 5s |
| P5 沟通AI | M14-M16 | msg、push-gateway、ai | 全校广播 + AI 辅助出题 | | P5 沟通AI | M14-M16 | msg、push-gateway、ai | 全校广播 + AI 辅助出题 |
| P6 硬化 | M17-M18 | admin-portal、Service Mesh | 99.9% 可用性 + 独立扩缩容 | | P6 硬化 | M17-M18 | admin-portal、Service Mesh | 99.9% 可用性 + 独立扩缩容 |
> 详细规划见 [路线图目录](./roadmap/README.md) > 详细规划见 [路线图目录](./roadmap/README.md)