xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
594a4e65fef7f575a888fd2772829826e7d76311
Edu/docs/architecture/004_architecture_impact_map.md

80 KiB
Raw Blame History

架构影响地图（微服务版）

版本：2.0 日期：2026-07-14 状态：实施状态同步（基于代码现状校准） 适用范围：Edu 微服务架构（DDD + EDA + CQRS） 关联文档：

v2.0 变更摘要：基于代码现状（截至 2026-07-14）全面校准服务清单、模块边界、依赖关系、Kafka topic、可观测性栈、BFF 实现细节；新增 §15 实施状态索引。

目录

  1. 项目概述
  2. 技术栈
  3. 分层架构
  4. 服务依赖图
  5. 认证与权限
  6. 数据访问与缓存
  7. 事件驱动架构
  8. 跨服务协作
  9. 核心业务流程
  10. 可观测性
  11. 契约与 API 架构
  12. 架构约束
  13. ADR 记录
  14. 附录：6 阶段路线图
  15. 实施状态索引（v2.0 新增）

1. 项目概述

1.1a 技术分层视角（系统边界）

本图展示部署分层结构（自上而下：用户 → 微前端 → 网关 → BFF → 业务服务 → 总线 → 数据）。 用户层按"使用场景域"标注，BFF 层按场景域分（不是按角色分）。业务领域视角见 1.1b。 端口标注见 infra/port-allocation.md（唯一源）。

graph TB
    subgraph Users["用户层（场景域用户）"]
        Teacher["教学场景域用户<br/>（教师 / 教导主任 / 教研组长 共用）"]
        Student["学习场景域用户<br/>（学生）"]
        Parent["家长场景域用户<br/>（家长）"]
        Admin["管理场景域用户<br/>（系统管理员 / 校管理员）"]
    end

    subgraph MFE["微前端层（Module Federation）<br/>Next.js 15 + standalone"]
        TeacherPortal["teacher-portal :4000<br/>Shell 宿主 + 教学场景域"]
        StudentPortal["student-portal :4001<br/>Remote"]
        ParentPortal["parent-portal :4002<br/>Remote（被 teacher-portal 加载）"]
        AdminPortal["admin-portal :4003<br/>Remote"]
    end

    subgraph PortalShell["Portal Shell 层（规划中）<br/>详见 [0020 Portal Shell 架构](./0020_portal_shell_architecture.md)"]
        PortalShellApp["portal-shell :4010<br/>Modular Monolith + Micro-kernel<br/>取代 MF 微前端，单服务部署"]
    end

    subgraph Gateway["网关层（Go 1.25 / Gin）"]
        APIGateway["api-gateway :8080<br/>JWT RS256 + JWKS + 限流 + 熔断"]
        PushGateway["push-gateway :8081<br/>WebSocket + Redis Pub/Sub<br/>（gRPC 豁免，HTTP /internal/*）"]
    end

    subgraph BFF["BFF 聚合层（NestJS / GraphQL Yoga）<br/>按使用场景域分 BFF"]
        TeacherBFF["teacher-bff :3003<br/>Teacher + Admin Resolvers<br/>6 下游 gRPC 客户端"]
        StudentBFF["student-bff :3009<br/>Cache + CircuitBreaker + Event"]
        ParentBFF["parent-bff :3010<br/>Aggregation + Kafka 订阅"]
    end

    subgraph Services["业务微服务（NestJS + FastAPI）"]
        IAM["iam :3002 / gRPC :50052<br/>5 Controller + Outbox"]
        CoreEdu["core-edu :3004 / gRPC :50053<br/>10 模块（含合并的 classes）"]
        Content["content :3005 / gRPC :50054<br/>7 模块 + Neo4j + ES sync"]
        DataAna["data-ana :3006 / gRPC :50055<br/>FastAPI + CDC consumer"]
        Msg["msg :3007 / gRPC :50056<br/>4 模块 + 4 渠道 + Kafka 16 事件"]
        AI["ai :3008 / gRPC :50058<br/>FastAPI + LLM Failover + Workflow"]
    end

    subgraph Bus["事件总线"]
        Kafka[("Kafka<br/>双 listener 29092/9092")]
        Debezium["Debezium Connect 2.7<br/>CDC MySQL → Kafka"]
    end

    subgraph Data["数据层"]
        MySQL[("MySQL 8.0<br/>每服务独占 schema")]
        Redis[("Redis 7<br/>缓存/会话/Pub/Sub")]
        ClickHouse[("ClickHouse 24.3<br/>读模型宽表")]
        Neo4j[("Neo4j 5.20<br/>知识图谱")]
        ES[("Elasticsearch 8.13<br/>题库检索")]
    end

    Teacher --> TeacherPortal
    Student --> StudentPortal
    Parent --> ParentPortal
    Admin --> AdminPortal

    TeacherPortal --> APIGateway
    StudentPortal --> APIGateway
    ParentPortal --> APIGateway
    AdminPortal --> APIGateway
    TeacherPortal -.MF Remote 加载.-> ParentPortal
    TeacherPortal -.WS 推送.-> PushGateway
    StudentPortal -.WS 推送.-> PushGateway
    ParentPortal -.WS 推送.-> PushGateway

    APIGateway --> TeacherBFF
    APIGateway --> StudentBFF
    APIGateway --> ParentBFF
    APIGateway -.admin graphql 透传.-> TeacherBFF
    PushGateway -.HTTP /internal/push.-> Msg

    TeacherBFF --> IAM
    TeacherBFF --> CoreEdu
    TeacherBFF --> Content
    TeacherBFF --> DataAna
    TeacherBFF --> AI
    TeacherBFF --> Msg
    StudentBFF --> IAM
    StudentBFF --> CoreEdu
    StudentBFF --> DataAna
    ParentBFF --> IAM
    ParentBFF --> CoreEdu
    ParentBFF --> DataAna
    ParentBFF --> Msg
    ParentBFF -.HTTP.-> PushGateway

    CoreEdu <--> Kafka
    Content <--> Kafka
    DataAna <--> Kafka
    Msg <--> Kafka
    IAM <--> Kafka
    AI <--> Kafka

    MySQL --> Debezium
    Debezium --> Kafka

    IAM --> MySQL
    CoreEdu --> MySQL
    Content --> MySQL
    Msg --> MySQL
    Content --> Neo4j
    Content --> ES
    DataAna --> ClickHouse
    AI --> ES

    IAM --> Redis
    CoreEdu --> Redis
    TeacherBFF --> Redis
    StudentBFF --> Redis
    ParentBFF --> Redis
    DataAna --> Redis
    AI --> Redis
    PushGateway --> Redis

1.1b 业务领域视角

本图按 DDD 限界上下文展示 6 个业务领域及其依赖关系。同一服务可横跨多个领域（如 core-edu 同时承载"教学组织"与"教学核心"）。 技术分层视角见 1.1a。

graph TB
    subgraph D1["D1 身份认证领域（iam 服务）"]
        IAM[iam 服务]
        IAM_M["5 Controller: Iam / Rbac / Audit / Jwks / IamGrpc<br/>users / roles / permissions / refresh_tokens / sessions<br/>totp / audit_logs / navigation_config / route_permission"]
    end

    subgraph D2["D2 教学组织领域（core-edu 服务）"]
        ORG["core-edu 服务<br/>classes + scheduling + leave-requests"]
        ORG_M["classes / teacher-associations / subjects<br/>schedule / leave-requests"]
    end

    subgraph D3["D3 教学核心领域（core-edu 服务）"]
        TEACH["core-edu 服务<br/>exams + homework + grades + attendance"]
        TEACH_M["exams / exam-extensions / homework / grades<br/>attendance / dashboard / admin / iam-consumer<br/>（含 state machine + datascope-injector）"]
    end

    subgraph D4["D4 内容资源领域（content 服务）"]
        CONTENT["content 服务"]
        CONTENT_M["7 模块: textbooks / chapters / knowledge-points<br/>questions / electives / lesson-plans / course-plans<br/>Neo4j 知识图谱 + ES 题库检索 + sync worker"]
    end

    subgraph D5["D5 沟通通知领域（msg 服务）"]
        MSG["msg 服务"]
        MSG_M["4 模块: notifications / preferences / templates / announcements<br/>4 渠道: email / sms / push / in-app<br/>Kafka 消费 16 类事件 + Idempotency Guard"]
    end

    subgraph D6["D6 智能洞察领域（data-ana + ai 服务）"]
        DATA["data-ana 服务"]
        AI["ai 服务"]
        DATA_M["FastAPI HTTP /analytics + gRPC 50055<br/>CDC consumer + ClickHouse 宽表<br/>analytics / dashboard / diagnostic / warnings / mastery"]
        AI_M["FastAPI HTTP /v1/ai + gRPC 50058<br/>LLM FailoverChain + Prompt Service + Quality Gate<br/>chat / question / expression / lesson-plan / report"]
    end

    IAM --> ORG
    IAM --> TEACH
    IAM --> CONTENT
    IAM --> MSG
    ORG --> TEACH
    TEACH --> CONTENT
    TEACH --> MSG
    CONTENT --> DATA
    TEACH --> DATA
    AI -.gRPC.-> CONTENT
    AI -.gRPC.-> DATA
    AI -.gRPC.-> IAM

双图并存说明：

  • 1.1a 技术分层：描述部署、流量路径、网络边界，关注"如何部署与调用"
  • 1.1b 业务领域：描述 DDD 限界上下文、聚合根、领域依赖，关注"业务边界与归属"
  • 两图互补，分别服务于运维/SRE 与产品/架构视角

1.2 服务清单

端口、阶段、实施状态基于代码现状（2026-07-14）。✅ = 已落地，🚧 = 部分落地，⏳ = 规划中。

类别 服务名 语言/框架 HTTP 端口 gRPC 端口 限界上下文 业务领域 阶段 状态
基础设施 api-gateway Go 1.25 (Gin) 8080 — 网关（路由+鉴权+限流+熔断+CORS） — P1 ✅
基础设施 push-gateway Go 1.25 (Gin) 8081 — 推送（WS + Redis Pub/Sub + Kafka 消费） — P5 ✅
BFF teacher-bff TS (NestJS + GraphQL Yoga) 3003 — 教师聚合 + Admin 命名空间聚合 教学场景域 P2 ✅
BFF student-bff TS (NestJS + GraphQL Yoga) 3009 — 学生聚合 学习场景域 P3 ✅
BFF parent-bff TS (NestJS + GraphQL Yoga) 3010 — 家长聚合 家长场景域 P4 ✅
业务 iam TS (NestJS) 3002 50052 身份认证 D1 身份认证 P2 ✅
业务 core-edu TS (NestJS) 3004 50053 教学核心（含原 classes） D2 教学组织 + D3 教学核心 P3 ✅
业务 content TS (NestJS) 3005 50054 内容资源 D4 内容资源 P4 ✅
业务 data-ana Python (FastAPI) 3006 50055 数据分析 D6 智能洞察 P4 ✅
业务 msg TS (NestJS) 3007 50056 消息通知 D5 沟通通知 P5 ✅
业务 ai Python (FastAPI) 3008 50058 AI 网关 D6 智能洞察 P5 ✅
微前端 teacher-portal TS (Next.js 15) 4000 — 教师端（MF Shell） 教学场景域 P2 ✅
微前端 student-portal TS (Next.js 15) 4001 — 学生端（MF Remote） 学习场景域 P3 ✅
微前端 parent-portal TS (Next.js 15) 4002 — 家长端（MF Remote，被 teacher-portal 加载） 家长场景域 P4 ✅
微前端 admin-portal TS (Next.js 15) 4003 — 管理端（MF Remote） 管理场景域 P6 ✅
共享包 shared-proto protobuf + buf v2 — — 跨语言契约（8 proto 文件） — P1 ✅
共享包 shared-ts TS — — TS 共享（bff / outbox） — P1 ✅
共享包 shared-go Go — — Go 共享（env / jwks / logger / tracer） — P1 ✅
共享包 shared-py Python — — Python 共享 — P4 🚧
共享包 contracts TS — — 跨端权限点常量 — P3 🚧
共享包 hooks TS (React) — — React Hooks（auth / permission / viewports / graphql / trace / a11y） — P2 ✅
共享包 ui-components TS (shadcn 风格) — — UI 组件库（data-table / form / modal / chart / filter-bar / status-badge） — P2 ✅
共享包 ui-tokens TS + CSS — — 设计令牌（primitive / semantic-light/dark / tailwind-theme） — P2 ✅

历史服务：classes（端口 3001）已合并入 core-edu（C1 裁决），目录保留作历史参考，不再构建部署。

1.3 CICD → Edu 模块映射

CICD 模块（旧） Edu 服务（新） 迁移阶段
auth + users + rbac iam P2
classes + subjects + enrollment core-edu P3
courses + lessons + schedule + attendance core-edu P3
assignments + grades + exams core-edu P3
textbooks + knowledge-points content P4
questions + grading content P4
messaging + notifications msg P5
analytics + dashboard + diagnostic data-ana P4
ai + lesson-preparation ai P5
search content (ES) P4

2. 技术栈

2.1 多语言技术栈矩阵

层级 语言 框架/版本 用途
网关层 Go 1.25 Gin + otelgin + prometheus api-gateway、push-gateway
业务服务 TypeScript 5.6+ NestJS 10 + Drizzle ORM iam、core-edu、content、msg
分析/AI Python 3.12 FastAPI + structlog + prometheus-client data-ana、ai
BFF TypeScript 5.6+ NestJS 10 + GraphQL Yoga + DataLoader + opossum（熔断） teacher-bff / student-bff / parent-bff
微前端 TypeScript 5.6+ Next.js 15 + Module Federation + Tailwind + shadcn 风格 4 端门户
契约 protobuf buf v2（FILE 级 breaking） 跨语言契约定义与生成
包管理 — pnpm 11 / go.work / uv workspace 多语言 monorepo

2.2 多存储矩阵

存储 版本 用途 使用服务
MySQL 8.0 写模型主库（每服务独占 schema） iam、core-edu、content、msg
Redis 7-alpine 缓存、会话、限流计数、分布式锁、Pub/Sub iam、core-edu、teacher-bff、student-bff、parent-bff、data-ana、ai、push-gateway
ClickHouse 24.3 读模型宽表、分析聚合 data-ana
Neo4j 5.20 知识图谱、前置依赖 content
Elasticsearch 8.13 题库全文检索、消息全文检索 content、msg

2.3 基础设施矩阵

组件 版本 用途
Kafka cp-kafka 7.6 事件总线，领域事件异步通信（双 listener）
Zookeeper cp-zookeeper 7.6 Kafka 协调
Debezium Connect 2.7 CDC，MySQL Binlog → Kafka 实时同步
OpenTelemetry SDK + OTLP 分布式追踪（HTTP / gRPC 自动埋点）
Jaeger all-in-one 1.57 分布式 Trace 存储 + UI（OTLP 4317/4318）
Loki 3.2.1 日志聚合
Promtail 3.2.1 日志采集
Prometheus v2.51.0 指标采集（--web.enable-lifecycle，15d 保留）
Alertmanager v0.27.0 告警路由与抑制
Grafana 10.4.0 可观测性可视化
node-exporter v1.8.2 主机指标
mysqld-exporter v0.15.1 MySQL 指标（命令行参数模式）
redis-exporter v1.67.0 Redis 指标
Temporal ⏳ 规划中 工作流编排（考试生命周期、AI 编排）
Vault ⏳ P6 密钥管理

v2.0 修正：Trace 存储实际使用 Jaeger all-in-one（OTLP 接收），原 v1.0 文档误写为 Tempo。当前未引入 Temporal，长流程编排暂由 ai 服务内 WorkflowStateStore（Redis）实现备课工作流。

3. 分层架构

3.1 六层架构

graph TB
    subgraph L1["L1 客户端层"]
        Browser[浏览器]
        Mobile[移动端]
    end

    subgraph L2["L2 微前端层"]
        MFE[Module Federation<br/>4 端门户 Next.js 15]
    end

    subgraph L3["L3 网关层（Go 1.25 / Gin）"]
        GW[API Gateway :8080<br/>HTTP 反向代理 + JWT RS256 + 限流 + 熔断]
        Push[Push Gateway :8081<br/>WebSocket + Redis Pub/Sub + Kafka 消费]
    end

    subgraph L4["L4 BFF 聚合层（NestJS + GraphQL Yoga）"]
        BFF[3 个 BFF<br/>聚合 + DataLoader + 熔断（opossum）]
    end

    subgraph L5["L5 业务微服务层"]
        SVC[6 业务服务<br/>NestJS + FastAPI<br/>DDD + CQRS + Outbox]
    end

    subgraph L6["L6 数据与总线层"]
        DB[(MySQL / ClickHouse / Neo4j / ES)]
        REDIS[(Redis 7)]
        KAFKA[(Kafka + Debezium CDC)]
        TEMPORAL["Temporal<br/>⏳ 规划中"]
    end

    Browser --> MFE
    Mobile --> MFE
    MFE --> GW
    MFE -.WS 推送.-> Push
    GW -- HTTP 代理 --> BFF
    GW -- HTTP 代理 --> SVC
    BFF -- gRPC --> SVC
    SVC --> DB
    SVC --> REDIS
    BFF --> REDIS
    SVC <--> KAFKA
    SVC -.规划中.-> TEMPORAL
    Push --> REDIS
    Push -.Kafka 消费.-> KAFKA

3.2 依赖方向

L1 客户端 → L2 微前端 → L3 网关 → L4 BFF → L5 业务服务 → L6 数据/总线

严格规则：

  1. L3 网关层只做路由、鉴权、限流、熔断，不写业务逻辑；只做 HTTP 反向代理，不做协议转换
  2. L4 BFF 层只做聚合、裁剪、协议转换（GraphQL → gRPC），不持有业务状态
  3. L5 业务服务之间通过 gRPC（同步）或 Kafka 事件（异步）通信，不直接访问对方数据库
  4. L6 数据层每个微服务独占自身数据库，禁止跨库联表

4. 服务依赖图

graph TB
    subgraph Gateway["网关层"]
        APIGW[api-gateway :8080]
        PushGW[push-gateway :8081]
    end

    subgraph BFF["BFF 层"]
        TBFF[teacher-bff :3003]
        SBFF[student-bff :3009]
        PBFF[parent-bff :3010]
    end

    subgraph Services["业务服务"]
        IAM[iam :3002]
        CoreEdu[core-edu :3004]
        Content[content :3005]
        DataAna[data-ana :3006]
        Msg[msg :3007]
        AI[ai :3008]
    end

    subgraph Shared["共享包"]
        Proto[shared-proto<br/>8 proto]
        SharedTS[shared-ts<br/>bff/outbox]
        SharedGo[shared-go<br/>env/jwks/logger/tracer]
        SharedPy[shared-py]
        Contracts[contracts<br/>权限点]
        Hooks[hooks<br/>React Hooks]
        UIComps[ui-components]
        UITokens[ui-tokens]
    end

    %% Gateway → BFF（HTTP 反向代理 + 路径重写）
    APIGW -- HTTP 代理 --> TBFF
    APIGW -- HTTP 代理 --> SBFF
    APIGW -- HTTP 代理 --> PBFF
    APIGW -. /api/admin/graphql 透传 .-> TBFF
    APIGW -- HTTP 代理 --> IAM
    APIGW -- HTTP 代理 --> CoreEdu
    APIGW -- HTTP 代理 --> Content
    APIGW -- HTTP 代理 --> Msg
    APIGW -- HTTP 代理 --> AI
    APIGW -- HTTP 代理 --> DataAna
    PushGW -. HTTP /internal/push .-> Msg
    PushGW -. Kafka edu.notify.notification.sent .-> Msg

    %% BFF → 业务服务（gRPC）
    TBFF -- gRPC --> IAM
    TBFF -- gRPC --> CoreEdu
    TBFF -- gRPC --> Content
    TBFF -- gRPC --> DataAna
    TBFF -- gRPC --> AI
    TBFF -- gRPC --> Msg

    SBFF -- gRPC --> IAM
    SBFF -- gRPC --> CoreEdu
    SBFF -- gRPC --> DataAna
    SBFF -. Kafka 事件 .-> PushGW

    PBFF -- gRPC --> IAM
    PBFF -- gRPC --> CoreEdu
    PBFF -- gRPC --> DataAna
    PBFF -- gRPC --> Msg
    PBFF -. HTTP .-> PushGW
    PBFF -. Kafka 订阅 .-> CoreEdu
    PBFF -. Kafka 订阅 .-> IAM

    %% 业务服务间事件
    CoreEdu -. Kafka 事件 .-> Content
    CoreEdu -. Kafka 事件 .-> DataAna
    CoreEdu -. Kafka 事件 .-> Msg
    Content -. Kafka 事件 .-> DataAna
    IAM -. Kafka 事件 .-> CoreEdu
    IAM -. Kafka 事件 .-> Msg
    AI -. gRPC .-> Content
    AI -. gRPC .-> DataAna
    AI -. gRPC .-> IAM
    DataAna -. Kafka 事件 .-> CoreEdu
    DataAna -. Kafka 事件 .-> Msg

    %% 共享包依赖
    IAM --> Proto
    CoreEdu --> Proto
    Content --> Proto
    DataAna --> Proto
    Msg --> Proto
    AI --> Proto
    APIGW --> SharedGo
    PushGW --> SharedGo
    IAM --> SharedTS
    CoreEdu --> SharedTS
    Content --> SharedTS
    Msg --> SharedTS
    TBFF --> SharedTS
    SBFF --> SharedTS
    PBFF --> SharedTS

4.1 服务间通信矩阵

调用方 → 被调用方 协议 场景
api-gateway → BFF HTTP 反向代理 路由分发 + 剥离 /api/v1/{bff} 前缀
api-gateway → 业务服务 HTTP 反向代理 剥离 /api 前缀，保留 /v1/{domain}/*
api-gateway → teacher-bff HTTP 透传 /api/admin/graphql → /graphql（admin）
BFF → 业务服务 gRPC 同步查询聚合 + DataLoader 批量去重
push-gateway → msg HTTP /internal/* msg 主动推送（X-Internal-Key 鉴权）
push-gateway → msg Kafka 消费 消费 edu.notify.notification.sent
parent-bff → push-gateway HTTP 触发家长端推送
CoreEdu → Content Kafka 事件 教学内容变更通知
CoreEdu → DataAna Kafka 事件 学情数据投递（9 类事件）
CoreEdu → Msg Kafka 事件 通知触发（考试/作业/成绩/考勤）
IAM → CoreEdu Kafka 事件 用户变更同步（6 类事件）
IAM → Msg Kafka 事件 用户/角色变更通知（6 类事件）
Content → DataAna Kafka 事件 内容发布同步
DataAna → CoreEdu Kafka 事件 掌握度更新 → 推荐练习
DataAna → Msg Kafka 事件 掌握度预警触发
AI → Content gRPC 题库查询 / 知识点查询
AI → DataAna gRPC 学情数据查询
AI → IAM gRPC 用户信息查询
AI → Kafka Kafka 生产 AI 用量事件发布（edu.ai.usage.*）

4.2 BFF 下游客户端矩阵

所有 BFF 下游客户端统一抽象（B8 裁决）：每个客户端有 gRPC + mock 两个实现，未配置 gRPC target 时自动降级为 mock。

BFF 下游客户端（gRPC :port）
teacher-bff iam (:50052) / core-edu (:50053) / content (:50054) / data-ana (:50055) / msg (:50056) / ai (:50058)
student-bff iam / core-edu / data-ana
parent-bff iam / core-edu / data-ana / msg / push-gateway (HTTP)

5. 认证与权限

5.1 JWT RS256 认证流程

实施细节：api-gateway 通过 JWKS Fetcher（shared-go/jwks）缓存 RS256 公钥校验 JWT； 校验通过后注入 x-user-id / x-user-roles / x-user-data-scope / x-request-id 头部，HTTP 反向代理到下游服务； 下游服务（NestJS）通过 AuthMiddleware 解析头部、PermissionGuard（APP_GUARD）做权限校验。 DEV_MODE=true 时跳过 JWT 校验，接受 dev-token。

sequenceDiagram
    participant U as 用户
    participant GW as API Gateway (Go)
    participant IAM as iam 服务
    participant SVC as 下游服务 (NestJS / FastAPI)

    rect rgb(240, 248, 255)
        Note over U,IAM: 阶段 1: 登录签发
        U->>GW: POST /api/v1/iam/login {username, password}
        GW->>IAM: HTTP 反向代理（无鉴权路由）
        IAM->>IAM: bcrypt 校验 + 查询权限 (PermissionCacheService)
        IAM->>IAM: 生成 JWT（RS256 私钥签发）+ refresh_token
        IAM->>IAM: 写 iam_outbox（USER_EVENTS）
        IAM-->>GW: {accessToken, refreshToken, userInfo}
        GW-->>U: 200 Set-Cookie httpOnly + ActionState 信封
    end

    rect rgb(240, 255, 240)
        Note over U,SVC: 阶段 2: 请求鉴权
        U->>GW: GET /api/v1/classes + Authorization: Bearer <token>
        GW->>GW: JWKS Fetcher 取 RS256 公钥
        GW->>GW: 校验签名 + exp/iss/aud
        GW->>GW: 提取 userId/roles/dataScope
        GW->>SVC: HTTP 代理 + 注入 x-user-* 头部
        SVC->>SVC: AuthMiddleware 解析头部
        SVC->>SVC: PermissionGuard (APP_GUARD) 校验权限
        SVC->>SVC: DataScopeInjector 注入 WHERE 条件
        SVC-->>GW: ActionState 响应
        GW-->>U: 200 响应
    end

5.2 三层角色模型

层级 来源 示例 优先级
系统角色 系统预设 admin、teacher、student、parent 最高
组织角色 学校/班级分配 年级组长、班主任、学科组长 中
临时角色 临时授权 代课教师、临时代理 最低

规则：权限取三层角色权限的并集，拒绝权限取交集（任一层拒绝则拒绝）。

5.3 DataScope 6 级数据范围

级别 名称 数据范围 典型角色
L0 SELF 仅本人数据 学生、家长
L1 CLASS 本班数据 班主任、学生
L2 GRADE 本年级数据 年级组长
L3 SCHOOL 本校数据 校管理员
L4 DISTRICT 本区数据 区教研员
L5 ALL 全部数据 系统管理员

实现：业务服务在 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.1 CQRS 读写分离

graph LR
    subgraph Write["写路径"]
        Cmd[Command 命令] --> App[Application Service]
        App --> Domain[Domain 领域模型]
        Domain --> Repo[Repository 写模型]
        Repo --> mysql_w[(MySQL 主库)]
        App --> Outbox[(Outbox 表<br/>同事务)]
    end

    subgraph Sync["同步链路"]
        Outbox --> Relay[Relay Worker]
        Relay --> kafka_sync[(Kafka)]
        kafka_sync --> Proj[Projection]
        Proj --> ch_sync[(ClickHouse 宽表)]
        Proj --> redis_sync[(Redis 缓存)]
        Proj --> es_sync[(ES 索引)]
    end

    subgraph Read["读路径"]
        Query[Query 查询] --> ReadModel[Read Model]
        ReadModel --> ch_read[(ClickHouse 宽表)]
        ReadModel --> redis_read[(Redis 缓存)]
        ReadModel --> es_read[(ES 索引)]
    end

6.2 BFF 混合读策略

flowchart TD
    Q[BFF 收到查询请求] --> C1{Redis 命中?}
    C1 -- 是 --> R1[返回缓存]
    C1 -- 否 --> C2{需要聚合多服务?}
    C2 -- 否 --> C3[直接 gRPC 调用单一服务]
    C3 --> C4[写入 Redis]
    C4 --> R2[返回]
    C2 -- 是 --> C5[并行 gRPC 调用多服务]
    C5 --> C6[内存聚合裁剪]
    C6 --> C7[写入 Redis 5-30s 短缓存]
    C7 --> R3[返回聚合结果]

6.3 缓存策略矩阵

数据类型 存储 TTL 失效策略
用户会话 Redis 30 分钟 滑动过期
权限列表 Redis 5 分钟 事件驱动失效
班级/年级列表 Redis 5 分钟 事件驱动失效
教学资源详情 Redis 30 秒 短 TTL
BFF 聚合结果 Redis 5-30 秒 短 TTL
学情宽表 ClickHouse 实时 CDC 同步
题库检索 ES 实时 CDC 同步

7. 事件驱动架构

7.1 Outbox + Kafka + CDC 全链路

graph LR
    subgraph Service["业务服务"]
        Cmd[Command 处理]
        Domain[Domain 聚合]
        Repo[Repository]
        Outbox[(Outbox 表)]
    end

    subgraph MySQL["MySQL 主库"]
        BizTable[(业务表)]
        OutboxTable[(outbox 表)]
    end

    subgraph Relay["Relay Worker"]
        Poll[轮询 outbox<br/>每 100ms]
        Publish[发布到 Kafka]
        Mark[标记 processed]
    end

    subgraph Bus["事件总线"]
        kafka_bus[(Kafka topic)]
    end

    subgraph Consumers["消费者"]
        Proj[Projection<br/>更新读模型]
        OtherSvc[其他服务<br/>业务订阅]
    end

    Cmd --> Domain
    Domain --> Repo
    Repo --> BizTable
    Repo --> OutboxTable
    OutboxTable --> Poll
    Poll --> Publish
    Publish --> kafka_bus
    kafka_bus --> Proj
    kafka_bus --> OtherSvc
    Proj --> read_stores[(ClickHouse / Redis / ES)]

7.2 事件 Topic 分类

实际命名（基于 services/*/src/shared/kafka/topic-map.ts 与 services/iam/src/config/kafka.ts）： 模式 edu.<domain>.<aggregate>.<action>。msg 服务统一使用 edu.notify.notification.* 发布（ARB-013）。

Topic 生产者 消费者 说明
edu.identity.user.created iam core-edu (iam-consumer)、msg 用户创建
edu.identity.user.updated iam core-edu、msg 用户更新
edu.identity.user.deleted iam msg 用户删除
edu.identity.user.role_changed iam core-edu、msg 用户角色变更
edu.identity.role.created iam msg 角色创建
edu.identity.role.updated iam msg 角色更新
edu.teaching.exam.published core-edu msg 考试发布
edu.teaching.exam.extended core-edu msg 考试延时（实时）
edu.teaching.exam.force_submitted core-edu msg 考试强制交卷（实时）
edu.teaching.exam.question_reordered core-edu msg 题序打乱（实时）
edu.teaching.homework.assigned core-edu msg 作业布置
edu.teaching.assignment.submitted core-edu data-ana、msg 作业提交
edu.teaching.assignment.graded core-edu msg 作业批改完成
edu.teaching.grade.recorded core-edu data-ana、msg 成绩录入
edu.teaching.attendance.recorded core-edu msg 考勤记录
edu.content.question.published content ai、ES sync worker 题目发布
edu.content.textbook.updated content data-ana 教材更新
edu.insight.mastery.updated data-ana core-edu、msg 掌握度更新
edu.notify.notification.sent msg push-gateway 通知投递（驱动推送）
edu.notify.notification.read msg — 通知已读
edu.notify.notification.recalled msg — 通知撤回
edu.notify.notification.failed msg — 通知投递失败
edu.notify.notification.events msg — 兜底 topic
edu.ai.usage.* ai （data-ana 规划中） AI 用量事件

Outbox 表命名：每服务独立 outbox 表（iam_outbox / core_edu_outbox / content_outbox / msg_outbox），由 shared-ts/outbox 模块统一管理。

必需依赖软失败标注（ARB-015 §17.6，ISSUE-058 覆盖 ISSUE-055）：

  • push-gateway → Redis：软失败（Redis 故障仅告警 + degraded: true + /readyz 返 200，不返 503、不触发 Pod 重启）
  • 理由：Redis 故障时单实例仍能服务本地连接（仅跨实例广播失效）；重启会丢失本地连接表，加剧雪崩风险
  • ISSUE-055 必需依赖列表应排除 push-gateway → Redis

7.3 核心领域事件

事件 触发场景 消费者动作
UserRegistered 新用户注册 CoreEdu 初始化默认班级关联；Msg 发送欢迎通知
ExamPublished 考试发布 Msg 推送考试通知给学生；DataAna 创建考试分析骨架
HomeworkSubmitted 学生提交作业 DataAna 记录提交行为；Msg 通知教师
HomeworkGraded 教师批改完成 DataAna 更新掌握度；Msg 通知学生
MasteryUpdated 掌握度计算完成 CoreEdu 推荐个性化练习；Msg 触发预警
NotificationRequested 通知请求 Msg 投递通知到 4 渠道（email/sms/push/in-app）
NotificationSent 通知投递完成 push-gateway 通过 Kafka 消费触发 WebSocket 推送

8. 跨服务协作

8.1 同步 vs 异步决策

flowchart TD
    Req[跨服务协作需求] --> C1{需要强一致性?}
    C1 -- 是 --> C2{调用方需要立即结果?}
    C2 -- 是 --> Sync[同步 gRPC 调用]
    C2 -- 否 --> Saga[Saga 编排<br/>Temporal]
    C1 -- 否 --> C3{需要事件最终一致?}
    C3 -- 是 --> Async[异步 Kafka 事件]
    C3 -- 否 --> C4{仅查询读取?}
    C4 -- 是 --> Read[读模型冗余]
    C4 -- 否 --> Sync

8.2 BFF 同步聚合

sequenceDiagram
    participant U as 教师端
    participant BFF as teacher-bff
    participant IAM as iam
    participant CoreEdu as core-edu
    participant DataAna as data-ana

    U->>BFF: 查询班级仪表盘
    BFF->>BFF: 解析 token 获取 userId
    par 并行查询
        BFF->>IAM: gRPC GetUser(userId)
        IAM-->>BFF: 用户信息
    and
        BFF->>CoreEdu: gRPC GetClassesByTeacher(userId)
        CoreEdu-->>BFF: 班级列表
    and
        BFF->>DataAna: gRPC GetTeacherDashboardStats(userId)
        DataAna-->>BFF: 统计数据
    end
    BFF->>BFF: 内存聚合裁剪
    BFF-->>U: 仪表盘聚合数据

8.3 异步事件闭环

flowchart LR
    A[教师录入成绩] --> B[CoreEdu 写入 MySQL + Outbox]
    B --> C[Outbox Relay 发布事件]
    C --> D[teaching.grade.recorded]
    D --> E[DataAna 消费更新掌握度]
    D --> F[Msg 消费通知学生]
    E --> G[insight.mastery.updated]
    G --> H[CoreEdu 消费推荐练习]
    G --> I[Msg 消费掌握度预警]

8.4 Temporal 工作流编排

flowchart TD
    Start[考试发布] --> A1[Activity: 创建考试实例]
    A1 --> A2[Activity: 通知学生]
    A2 --> A3[Activity: 等待作答窗口]
    A3 --> A4[Activity: 收集提交]
    A4 --> C1{是否全部提交?}
    C1 -- 否 --> A5[Activity: 自动提交未答]
    C1 -- 是 --> A6[Activity: 批改]
    A5 --> A6
    A6 --> A7[Activity: 发布成绩]
    A7 --> A8[Activity: 生成分析]
    A8 --> End[工作流完成]

9. 核心业务流程

9.1 考试生命周期

sequenceDiagram
    participant T as 教师
    participant BFF as teacher-bff
    participant Core as core-edu
    participant Msg as msg
    participant DA as data-ana
    participant S as 学生

    rect rgb(240, 248, 255)
        Note over T,Core: 阶段 1: 创建发布
        T->>BFF: 创建考试
        BFF->>Core: gRPC CreateExam
        Core->>Core: 写入 MySQL + Outbox
        Core-->>BFF: examId
        BFF-->>T: 创建成功
        Core->>Msg: ExamPublished 事件
        Msg->>S: 推送考试通知
    end

    rect rgb(240, 255, 240)
        Note over S,Core: 阶段 2: 作答提交
        S->>BFF: 提交答卷
        BFF->>Core: gRPC SubmitExam
        Core->>Core: 写入答卷 + Outbox
        Core-->>BFF: 提交成功
        Core->>DA: ExamSubmitted 事件
        DA->>DA: 记录提交行为
    end

    rect rgb(255, 240, 245)
        Note over T,DA: 阶段 3: 批改出分
        T->>BFF: 批改答卷
        BFF->>Core: gRPC GradeExam
        Core->>Core: 写入成绩 + Outbox
        Core-->>BFF: 批改完成
        Core->>DA: GradeRecorded 事件
        DA->>DA: 更新掌握度
        Core->>Msg: GradeRecorded 事件
        Msg->>S: 推送成绩通知
    end

9.2 高并发提交

flowchart TD
    S[学生提交] --> GW[API Gateway]
    GW --> GW1{限流检查}
    GW1 -- 通过 --> BFF[BFF]
    GW1 -- 拒绝 --> R1[429 限流响应]
    BFF --> Core[CoreEdu]
    Core --> C1{Redis 分布式锁}
    C1 -- 获取锁 --> C2[写入答卷]
    C2 --> C3[Outbox 事件]
    C3 --> C4[释放锁]
    C4 --> R2[成功]
    C1 -- 锁竞争 --> C5[排队等待 500ms]
    C5 --> C1
    C5 --> C6{超时?}
    C6 -- 是 --> R3[排队中，请稍后]

9.3 AI 辅助出题

sequenceDiagram
    participant T as 教师
    participant BFF as teacher-bff
    participant AI as ai 网关
    participant Content as content
    participant DA as data-ana

    T->>BFF: 请求 AI 出题
    BFF->>AI: gRPC GenerateQuestions
    AI->>Content: gRPC 查询知识点
    Content-->>AI: 知识点列表
    AI->>DA: gRPC 查询班级学情
    DA-->>AI: 学情数据
    AI->>AI: LLM 调用生成题目
    AI-->>BFF: 生成的题目列表
    BFF-->>T: 返回题目供教师审核
    T->>BFF: 确认入库
    BFF->>Content: gRPC CreateQuestions
    Content-->>BFF: 入库成功

10. 可观测性

10.1 三支柱可观测性

实际落地：Jaeger all-in-one 接收 OTLP（HTTP 4318 / gRPC 4317），Loki + Promtail 采集容器日志，Prometheus 抓取 /metrics 端点。 所有 NestJS 服务通过 shared/observability/{logger,metrics,tracer}.ts 注册；Go 网关通过 shared-go/{logger,tracer} + otelgin；Python 服务通过 structlog + opentelemetry-instrumentation-fastapi + prometheus-client。

graph TB
    subgraph App["应用层"]
        NESTJS[NestJS 服务<br/>pino + prom-client + OTLP]
        GO[Go 网关<br/>slog + prometheus + otelgin]
        PY[Python 服务<br/>structlog + prometheus-client + OTLP]
        PORTAL[Next.js portal<br/>OTel Web + Sentry]
    end

    subgraph Collect["采集层"]
        OTEL[OpenTelemetry SDK<br/>OTLP exporter]
        PROM[Prometheus 抓取<br/>/metrics]
        PROMTAIL[Promtail<br/>容器日志]
    end

    subgraph Storage["存储层"]
        LOKI[(Loki 3.2.1<br/>日志)]
        JAEGER[(Jaeger 1.57<br/>Trace，OTLP 4317/4318)]
        PROMDB[(Prometheus v2.51<br/>指标 15d 保留)]
    end

    subgraph Exporters["Exporters"]
        NODE[node-exporter :9100<br/>host.docker.internal]
        MYSQL[mysqld-exporter :9104]
        REDIS[redis-exporter :9121]
    end

    subgraph Vis["可视化层"]
        GRAFANA[Grafana 10.4<br/>统一面板 :3030]
        ALERT[Alertmanager v0.27<br/>告警路由]
    end

    NESTJS --> OTEL
    GO --> OTEL
    PY --> OTEL
    PORTAL -.OTLP HTTP.-> OTEL
    OTEL --> JAEGER
    NESTJS --> PROM
    GO --> PROM
    PY --> PROM
    PROM --> PROMDB
    PROMTAIL --> LOKI
    NODE --> PROM
    MYSQL --> PROM
    REDIS --> PROM
    LOKI --> GRAFANA
    JAEGER --> GRAFANA
    PROMDB --> GRAFANA
    PROMDB --> ALERT

10.2 Trace 上下文传播

flowchart LR
    A[客户端请求] --> B[API Gateway<br/>otelgin 生成 traceId]
    B --> C[BFF<br/>继承 W3C traceparent]
    C --> D[业务服务 gRPC<br/>继承 metadata]
    D --> E[Kafka 事件<br/>traceId 写入 header]
    E --> F[消费者服务<br/>继承 traceId]
    F --> G[下游存储<br/>span 记录]
    G --> H[Jaeger UI<br/>查询链路]

规则：

  • 所有跨服务调用必须透传 W3C Trace Context（HTTP traceparent 头 / gRPC metadata）
  • Kafka 事件必须将 traceId 写入消息 header
  • 日志必须包含 traceId / requestId 用于关联查询
  • 关键业务操作必须创建 span（创建考试、提交作业、批改、AI 生成、通知投递等）
  • 每服务暴露 /metrics（Prometheus 抓取）+ /healthz（liveness）+ /readyz（readiness）

10.3 健康检查与降级

服务类型 /healthz 行为 /readyz 行为
网关层 进程存活即 ok 检查下游可达性（soft-failure）
BFF 进程存活即 ok 检查 Redis + 下游 gRPC probe（6 个 probe）
业务服务 进程存活即 ok 检查 DB + Redis + Kafka + gRPC server
push-gateway 进程存活即 ok Redis 软失败（不返 503）+ Kafka consumer 状态
data-ana 进程存活即 ok ClickHouse 1s 超时 + CDC lag < 1000 + Redis + iam

11. 契约与 API 架构

11.1 Protobuf 契约体系

实际 proto 文件位于 packages/shared-proto/proto/，共 8 个：ai.proto / analytics.proto / classes.proto / content.proto / core_edu.proto / events.proto / iam.proto / msg.proto。 arch.db 统计（2026-07-14）：8 proto 文件 / 23 service / 305 message / 139 RPC。 buf v2 配置：lint STANDARD（含 5 项 except 豁免）+ breaking FILE 级别。 buf.gen.yaml 生成 6 套代码：protocolbuffers {go/js/python} + grpc {go/node/python}，输出到 shared-{go,ts,py}/gen/proto/。

graph TB
    subgraph Proto["shared-proto/proto/ (8 文件)"]
        IamProto[iam.proto<br/>IamService]
        CoreEduProto[core_edu.proto<br/>9 Service: Exam/Homework/Grade/<br/>Attendance/Class/Schedule/<br/>LeaveRequest/Dashboard/Admin]
        ClassesProto[classes.proto<br/>ClassService（历史保留）]
        ContentProto[content.proto<br/>Textbook/Chapter/<br/>KnowledgeGraph/Question/<br/>Elective/LessonPlan/CoursePlan]
        MsgProto[msg.proto<br/>Notification/Preference/<br/>Template Service]
        DataAnaProto[analytics.proto<br/>AnalyticsService]
        AiProto[ai.proto<br/>AiService]
        EventsProto[events.proto<br/>领域事件 schema]
    end

    subgraph Gen["buf generate (buf v2)"]
        BufGen[buf generate]
        TSGen[shared-ts/gen/proto<br/>@bufbuild/protobuf + grpc-node]
        GoGen[shared-go/gen/proto<br/>protobuf-go + grpc-go]
        PyGen[shared-py/gen/proto<br/>protobuf + grpc-python]
    end

    subgraph Services["消费服务"]
        SvcTS[NestJS 服务<br/>iam/core-edu/content/msg<br/>teacher-bff/student-bff/parent-bff]
        SvcGo[Go 网关<br/>api-gateway/push-gateway]
        SvcPy[Python 服务<br/>data-ana/ai]
    end

    IamProto --> BufGen
    CoreEduProto --> BufGen
    ClassesProto --> BufGen
    ContentProto --> BufGen
    MsgProto --> BufGen
    DataAnaProto --> BufGen
    AiProto --> BufGen
    EventsProto --> BufGen

    BufGen --> TSGen
    BufGen --> GoGen
    BufGen --> PyGen

    TSGen --> SvcTS
    GoGen --> SvcGo
    PyGen --> SvcPy

11.2 契约规则

规则 说明
包命名 proto 包名采用 next_edu_cloud.<domain>.v1 格式（如 next_edu_cloud.iam.v1、next_edu_cloud.core_edu.v1）
Topic 命名 Kafka topic 采用 edu.<domain>.<aggregate>.<action> 格式（如 edu.identity.user.created）
版本化 破坏性变更必须升版本（v1 → v2），buf breaking FILE 级别 CI 强制
字段编号 禁止复用已删除字段编号，使用 reserved
消息命名 PascalCase
字段命名 snake_case
注释 每个 message 和字段必须注释
CI 强制 buf lint + buf breaking 必须通过
代码生成 buf generate 生成 6 套代码（go/js/python × protobuf/grpc）

11.3 BFF 聚合模式

graph LR
    subgraph Client["客户端"]
        Q[GraphQL 查询]
    end

    subgraph BFF["BFF 层"]
        Resolver[GraphQL Resolver]
        DataLoader[DataLoader 批量去重]
        Cache[Redis 短缓存]
    end

    subgraph Services["业务服务"]
        S1[服务 A]
        S2[服务 B]
        S3[服务 C]
    end

    Q --> Resolver
    Resolver --> Cache
    Cache --> DataLoader
    DataLoader --> S1
    DataLoader --> S2
    DataLoader --> S3

11.4 错误码前缀矩阵

来源：coord 仲裁 ARB-017 §19.6 / ARB-014 / ARB-015 / ARB-018 / G14 / F4 规则：服务名大写 + 下划线分隔，禁止子前缀（如 EXAMS_/HOMEWORK_/GRADES_ 已移除）

层级 服务 前缀 示例 仲裁依据
网关 api-gateway GW_ GW_UNAUTHORIZED / GW_RATE_LIMITED ARB-014
网关 push-gateway PUSH_ PUSH_DEVICE_NOT_FOUND / PUSH_CHANNEL_FAILED ARB-015
BFF teacher-bff BFF_TEACHER_ BFF_TEACHER_UNAUTHORIZED / BFF_TEACHER_BAD_GATEWAY ARB-016
BFF student-bff BFF_STUDENT_ BFF_STUDENT_UNAUTHORIZED / BFF_STUDENT_VALIDATION_ERROR ARB-017
BFF parent-bff BFF_PARENT_ BFF_PARENT_CHILD_NOT_BOUND / BFF_PARENT_BAD_GATEWAY ARB-018
业务 iam IAM_ IAM_USER_NOT_FOUND / IAM_INVALID_CREDENTIALS ARB-003
业务 core-edu CORE_EDU_ CORE_EDU_EXAM_NOT_FOUND / CORE_EDU_GRADE_NOT_FOUND ARB-004
业务 content CONTENT_ CONTENT_QUESTION_NOT_FOUND / CONTENT_TEXTBOOK_NOT_FOUND ARB-005
业务 msg MSG_ MSG_NOTIFICATION_NOT_FOUND / MSG_TEMPLATE_NOT_FOUND ARB-008
业务 data-ana DATA_ANA_ DATA_ANA_DASHBOARD_UNAVAILABLE / DATA_ANA_ANALYTICS_NOT_READY ARB-009
业务 ai AI_ AI_GENERATION_FAILED / AI_QUOTA_EXCEEDED ARB-010

前端 i18n key 映射规则（F4 裁决）：

服务 i18n key 模式 示例
api-gateway error.gateway.<code_snake> error.gateway.unauthorized
push-gateway error.push.<code_snake> error.push.device_not_found
teacher-bff error.bffTeacher.<code_snake> error.bffTeacher.unauthorized
student-bff error.bffStudent.<code_snake> error.bffStudent.validation_error
parent-bff error.bffParent.<code_snake> error.bffParent.child_not_bound
iam error.iam.<code_snake> error.iam.user_not_found
core-edu error.core_edu.<code_snake> error.core_edu.exam_not_found
content error.content.<code_snake> error.content.question_not_found
msg error.msg.<code_snake> error.msg.notification_not_found
data-ana error.data_ana.<code_snake> error.data_ana.dashboard_unavailable
ai error.ai.<code_snake> error.ai.generation_failed

11.5 ActionState 信封规范

来源：coord 仲裁 ARB-017 §19.6 适用范围：所有 BFF / Gateway HTTP 响应、GraphQL response 的 errors 扩展字段 设计原则：统一错误信封 + 降级模式方案 B（degraded 放 error.details 子字段）

信封结构：

interface ActionState<T = unknown> {
  success: boolean; // 整体成功/失败
  data: T | null; // 成功时返回数据，失败时为 null
  error: {
    code: string; // 错误码（见 §11.4 前缀矩阵）
    message: string; // 人类可读错误消息（i18n key 解析后）
    details?: Record<string, unknown>; // 附加详情（含 degraded 字段）
    traceId: string; // 链路追踪 ID（X-Request-Id）
  } | null; // 成功时为 null
}

降级模式（方案 B）：

  • success = true（整体成功）
  • data 内含 extensions.degraded: true 子字段
  • error 仍为 null（非错误）
  • 用于部分聚合失败场景（如 teacher-bff 聚合 iam 成功但 core-edu 失败）

示例 1：完全成功

{
  "success": true,
  "data": { "userId": "u001", "name": "张老师" },
  "error": null
}

示例 2：完全失败

{
  "success": false,
  "data": null,
  "error": {
    "code": "BFF_TEACHER_BAD_GATEWAY",
    "message": "下游服务不可用",
    "details": { "downstream": "core-edu", "reason": "timeout" },
    "traceId": "req-abc123"
  }
}

示例 3：降级模式（部分聚合成功）

{
  "success": true,
  "data": {
    "user": { "userId": "u001", "name": "张老师" },
    "classes": null,
    "extensions": { "degraded": true, "failedServices": ["core-edu"] }
  },
  "error": null
}

GraphQL errors 数组扩展：

GraphQL 响应中，错误通过 errors[].extensions 携带 ActionState 字段：

{
  "errors": [
    {
      "message": "下游服务不可用",
      "extensions": {
        "code": "BFF_TEACHER_BAD_GATEWAY",
        "details": { "downstream": "core-edu" },
        "traceId": "req-abc123"
      }
    }
  ]
}

12. 架构约束

12.1 服务独立性约束

约束 说明
数据库独占 每个微服务独占自身数据库，禁止跨库联表
契约先行 所有跨服务通信必须先定义 protobuf 契约
Outbox 强制 所有领域事件必须通过 Outbox 模式发布
幂等消费 所有事件消费者必须实现幂等性
单一职责 每个服务只负责一个限界上下文
无状态服务 业务服务不持有会话状态（Redis 承载）

12.2 通信约束

场景 允许 禁止
客户端 → Gateway REST + WebSocket 直连业务服务
Gateway → BFF HTTP 反向代理（路径重写剥离前缀） gRPC 转换、REST 业务逻辑
Gateway → 业务服务 HTTP 反向代理（剥离 /api 前缀） gRPC 转换
BFF → 业务服务 gRPC + DataLoader 批量去重 直接访问 DB
push-gateway → msg HTTP /internal/* + Kafka 消费 gRPC（豁免，ARB-015）
业务服务之间（同步） gRPC REST、直接 DB
业务服务之间（异步） Kafka 事件（Outbox 模式） 直接 producer 调用
事件发布 Outbox 模式 直接 Kafka producer

12.3 数据一致性约束

场景 一致性级别 实现
聚合内 强一致 单事务
聚合间 最终一致 Kafka 事件
服务间 最终一致 Kafka 事件 / Saga
读模型 最终一致 Projection 异步更新
缓存 最终一致 事件驱动失效 + 短 TTL

13. ADR 记录

编号 决策 原因 状态
ADR-001 采用 DDD 限界上下文划分服务 业务边界清晰，独立演进 已采纳
ADR-002 采用 NestJS 作为业务服务框架 TS 生态成熟，装饰器 + DI 适合 DDD 已采纳
ADR-003 采用 Go 作为网关语言 高并发、低内存、适合网关场景 已采纳
ADR-004 采用 Python 作为分析/AI 语言 数据科学/AI 生态丰富 已采纳
ADR-005 采用 CQRS 读写分离 读多写少，读模型可独立优化 已采纳
ADR-006 采用 Outbox 模式发布事件 保证事务与事件最终一致 已采纳
ADR-007 采用 Kafka 作为事件总线 高吞吐、持久化、成熟生态 已采纳
ADR-008 采用 Debezium CDC 解耦 Outbox Relay，减少业务侵入 已采纳
ADR-009 采用 protobuf + buf 契约先行 多语言契约统一、版本化、CI 强制 已采纳
ADR-010 采用 JWT RS256 非对称签名 网关公钥校验无需共享私钥 已采纳
ADR-011 采用 DataScope 6 级数据范围 满足 K12 多层级数据隔离 已采纳
ADR-012 采用 Module Federation 微前端 独立部署、技术栈无关、渐进迁移 已采纳
ADR-013 采用 Temporal 工作流编排 长流程编排、可观测、可回滚 ⏳ 规划中（当前由 ai 内 WorkflowStateStore 临时实现）
ADR-014 采用 ClickHouse 读模型宽表 分析查询亚秒级响应 已采纳
ADR-015 api-gateway 采用 HTTP 反向代理（非 gRPC 转换） Go 网关只做 HTTP，简化部署；下游 HTTP/gRPC 双协议 已采纳
ADR-016 push-gateway 豁免 gRPC 基础设施层无流式推送场景；msg/student-bff/parent-bff 改用 HTTP /internal/* 已采纳
ADR-017 classes 服务合并入 core-edu 教学组织与教学核心共享聚合根边界 已采纳
ADR-018 BFF 统一 GraphQL Yoga + DataLoader + opossum 熔断 协议统一、批量去重、降级模式 B（degraded 子字段） 已采纳
ADR-019 admin-portal GraphQL 经 teacher-bff 命名空间 复用 teacher-bff resolver，admin role 中间件强制隔离 已采纳
ADR-020 parent-portal 作为 MF Remote 被 teacher-portal 加载 家长入口可由教师端嵌入，统一 Shell 宿主 已采纳
ADR-021 Trace 存储 Jaeger 替代 Tempo all-in-one 镜像部署简单，OTLP 原生支持 已采纳
ADR-022 共享包 ui-tokens 替代原 shared-tokens 命名 三层令牌（primitive/semantic/tailwind-theme）实际落地 已采纳

14. 附录：6 阶段路线图

14.1 阶段总览

graph LR
    P1[P1 地基<br/>M1-M3] --> P2[P2 身份<br/>M4-M6]
    P2 --> P3[P3 核心教学<br/>M7-M10]
    P3 --> P4[P4 内容分析<br/>M11-M13]
    P4 --> P5[P5 沟通AI<br/>M14-M16]
    P5 --> P6[P6 硬化<br/>M17-M18]

14.2 服务与阶段映射

状态基于代码现状（2026-07-14）。✅ 已落地 / 🚧 部分落地 / ⏳ 规划中。

阶段 周期 交付服务 退出标准 实际状态
P1 地基 M1-M3 api-gateway、classes（黄金模板）、shared-proto classes 域 CRUD 端到端跑通 ✅ 完成（classes 已合并入 core-edu）
P2 身份 M4-M6 iam、teacher-bff、teacher-portal 骨架 教师可登录并看到空白 Dashboard ✅ 完成
P3 核心教学 M7-M10 core-edu（合并 classes）、student-bff、student-portal 考试→作答→批改→成绩全链路 ✅ 完成（含 LeaveRequests/Dashboard/Admin/IamConsumer 扩展）
P4 内容分析 M11-M13 content、data-ana、parent-bff、parent-portal 知识图谱查询 + 学情宽表 5s ✅ 完成（含 7 模块 + Neo4j + ES sync + CDC consumer + 11 analytics 端点）
P5 沟通AI M14-M16 msg、push-gateway、ai 全校广播 + AI 辅助出题 ✅ 完成（msg 4 模块 4 渠道 + push-gateway WS + Kafka + ai 11 端点 + 备课工作流）
P6 硬化 M17-M18 admin-portal、Service Mesh 99.9% 可用性 + 独立扩缩容 🚧 admin-portal 已落地；Service Mesh / Vault / 99.9% SLO 待硬化

详细规划见 路线图目录、tech-debt、pending-features

15. 实施状态索引（v2.0 新增）

本节按服务/包罗列实际落地的模块、Controller、关键组件，作为代码现状的快速索引。 详细模块设计见各服务 README.md 与 docs/01-understanding.md。

15.1 api-gateway（Go :8080）

  • 中间件链：Recovery → otelgin → RequestID → CORS → SecurityHeaders → RequestBodyLimit(10MB) → RateLimit(100rps+20burst) → CircuitBreaker → AuthMiddleware(JWKS RS256) → Metrics
  • 路由组：
    • /healthz、/readyz、/metrics（公开）
    • /api/v1/{classes,iam,exams,homework,grades,textbooks,chapters,knowledge-points,questions,notifications,messages,announcements,ai,analytics,dashboard}/* → HTTP 反向代理
    • /api/v1/{teacher,student,parent}/* → BFF 反向代理（剥离 /api/v1/{bff} 前缀）
    • /api/admin/graphql → teacher-bff /graphql（AdminRoleMiddleware 强制）
  • 关键依赖：shared-go/jwks（公钥缓存）、shared-go/env、shared-go/logger、shared-go/tracer

15.2 push-gateway（Go :8081）

  • WebSocket 端点：/ws（JWT RS256 via query ?token= 或 Authorization 头）
  • 内部 HTTP API：/internal/push、/internal/broadcast、/internal/online/:userID（X-Internal-Key 鉴权）
  • 跨实例广播：Redis Pub/Sub（SubscribeAll + RebuildPresenceOnStartup）
  • Kafka 消费：edu.notify.notification.sent（ARB-013）
  • 健康检查：/healthz（liveness）、/readyz（Redis 软失败 + Kafka consumer 状态）
  • 依赖：hub（in-memory connection registry）、redisclient、kafkaconsumer、ws、observability

15.3 iam（NestJS :3002 / gRPC :50052）

  • Controllers：IamController、RbacController、AuditController、JwksController、IamGrpcController
  • Services：IamService、JwksService、PermissionCacheService（Redis）、TokenBlacklistService
  • Outbox：iam_outbox 表，发布到 edu.identity.user.* topic
  • APP_GUARD：PermissionGuard（DB 驱动 + Redis 缓存，I3 裁决）
  • AuthMiddleware 应用范围：v1/iam/me、logout、change-password、viewports、permissions/effective、children、roles、permissions、users、audit、totp

15.4 core-edu（NestJS :3004 / gRPC :50053）

  • 业务模块（10）：
    • exams（含 exam-extensions、exam-state-machine）
    • homework（含 homework-state-machine）
    • grades（含 grade-calculator）
    • attendance
    • classes（含 teacher-associations，C1 合并自原 classes 服务）
    • scheduling（含 schedule-conflict 检测）
    • leave-requests（P3.13）
    • dashboard
    • admin
    • iam-consumer（消费 IAM 6 类事件）
  • 共享组件：datascope-injector（Repository 层 WHERE 注入）、outbox（core_edu_outbox）、global-error.filter
  • gRPC 服务（9，43 RPC）：ExamService / HomeworkService / GradeService / AttendanceService / ClassService / ScheduleService / LeaveRequestService / DashboardService / AdminService

15.5 content（NestJS :3005 / gRPC :50054）

  • 业务模块（7）：textbooks、chapters、knowledge-points、questions、electives、lesson-plans、course-plans
  • gRPC controllers（7）：Textbook / Chapter / KnowledgeGraph / Question / Elective / LessonPlan / CoursePlan
  • 同步 worker：es-sync.worker（题库 ES 索引）、neo4j-sync.worker（知识图谱节点）
  • Outbox：content_outbox，发布 edu.content.* 事件
  • 存储：MySQL（业务表）+ Neo4j（知识图谱）+ Elasticsearch（题库检索）

15.6 msg（NestJS :3007 / gRPC :50056）

  • 业务模块（4）：notifications、preferences、templates、announcements
  • gRPC controllers（3，17 RPC）：NotificationService（9 RPC）/ NotificationPreferenceService（2 RPC）/ NotificationTemplateService（6 RPC，ARB-008 裁剪）
  • 渠道（4）：email、sms、push、in-app（channel-dispatcher 路由）
  • Kafka 消费：16 类事件（iam 6 + core-edu 9 + data-ana 1），见 shared/kafka/topic-map.ts
  • Kafka 生产：4 类 edu.notify.notification.* 事件 + 1 兜底 topic
  • 辅助组件：push-gateway.client（HTTP 调用 /internal/push）、idempotency.guard（Redis SETNX 去重）、Outbox（msg_outbox）
  • 存储：MySQL + Elasticsearch（消息全文检索）+ Redis（幂等性）

15.7 data-ana（FastAPI :3006 / gRPC :50055）

  • HTTP 端点（3 基础 + 11 业务 = 14）：
    • 基础：/、/healthz、/readyz
    • 业务（全部 ActionState 信封）：
      • /analytics/class/{class_id}/performance
      • /analytics/student/{student_id}/{weakness,trend,errorbook,mastery}
      • /analytics/{teacher,student,parent,admin}/dashboard
      • /analytics/warnings + /analytics/warnings/trigger
      • /analytics/class/{class_id}/mastery-distribution
  • gRPC 服务：AnalyticsService（18 RPC）
  • CDC 消费者：手动 commit，lag 阈值 1000（超过 readyz 返 503）
  • /readyz 4 依赖：ClickHouse（1s）+ CDC consumer（lag<1000）+ Redis（200ms）+ iam gRPC（2s）
  • 存储：ClickHouse（宽表）+ Redis（缓存）+ iam gRPC（用户信息）

15.8 ai（FastAPI :3008 / gRPC :50058）

  • HTTP 端点（11）：
    • /healthz、/readyz
    • /v1/ai/chat（非流式）+ /v1/ai/chat/stream（SSE）
    • /v1/ai/generate/question + /v1/ai/generate/question/stream（SSE）
    • /v1/ai/optimize/expression
    • /v1/ai/lesson-plan/generate + /v1/ai/lesson-plan/status/{workflow_id} + /v1/ai/lesson-plan/confirm/{workflow_id}
    • /v1/ai/generate/report（class_summary / student_detail / exam_analysis）
  • gRPC 服务：AiService（9 RPC）
  • 核心组件：LLM FailoverChain（4 适配器 + 熔断 + 故障切换）、PromptTemplateService（Jinja2 + YAML）、QualityGate（RuleValidator + LLMJudge）
  • 用量与配额：UsageRecorder（Redis）+ QuotaEnforcer + KafkaProducer（edu.ai.usage.*）
  • 限流：RateLimiter（Redis 三维度令牌桶：user/ip/school）
  • 安全：PII redactor + 输入清洗 + 输出审核
  • 备课工作流：4 步编排 + WorkflowStateStore（Redis TTL）
  • 下游 gRPC 客户端：ContentClientGrpc / DataAnaClientGrpc / IamClientGrpc（连接失败降级，不阻断启动）

15.9 teacher-bff（NestJS :3003 / GraphQL Yoga）

  • 模块：GraphQLModule（Teacher + Admin Resolvers，ARB-001 扁平合并）+ HealthModule + MiddlewareModule
  • 下游客户端（6）：iam / core-edu / content / data-ana / msg / ai（B8 裁决统一抽象，gRPC + mock 双实现）
  • GraphQL 端点：/graphql（同时承载 teacher 与 admin 命名空间）
  • SSE 控制器：ai-chat-sse.controller.ts（透传 ai 服务流式响应）
  • Health probes（6）：iam-grpc / core-edu-grpc / content-grpc / data-ana-grpc / ai-grpc / msg-grpc + redis probe

15.10 student-bff（NestJS :3009 / GraphQL Yoga）

  • 模块（8）：CacheModule（Global Redis）+ DownstreamModule（Global gRPC）+ CircuitBreakerModule（Global opossum）+ HealthModule + DataLoaderModule + StudentModule（GraphQL Yoga + Resolver）+ PushGatewayModule（HTTP /internal/push）+ EventModule（Kafka 事件订阅 + push-gateway 推送）
  • 下游客户端：iam / core-edu / data-ana

15.11 parent-bff（NestJS :3010 / GraphQL Yoga）

  • 模块：HealthModule + GraphqlModule（Yoga /v1/graphql）+ ClientsModule（iam + core-edu + data-ana + msg + push-http）+ KafkaModule（cache-invalidation + notification-push handler）
  • 聚合组件：AggregationModule（orchestrator + fallback-strategy + child-guard + response-mapper）
  • DataLoader：dataloader.factory + loaders（批量去重）
  • 缓存：Redis + LRU cache + cache-key.builder

15.12 teacher-portal（Next.js 15 :4000，MF Shell）

  • 路由组（25+ 业务页面）：dashboard、classes、schedule、exams、homework、grades、attendance、analytics、knowledge-graph、lesson-plans、course-plans、textbooks、questions、notifications、students、ai-assist、ai-lesson-plan、ai-report、diagnostic、error-book、practice、leave、elective、schedule-changes、settings
  • MF Remote 加载：ParentPortalRemote（在 teacher-portal 内嵌入家长端视图）
  • GraphQL 客户端文件：graphql.ts（base）+ graphql-p4.ts / p5.ts / p7-admin.ts / p7-advanced.ts / p7-exams.ts / p7-grades.ts / p7-insights.ts（按阶段渐进扩展）
  • 可观测性：observability-provider（OTel Web + Sentry + web-vitals + performance-dashboard）
  • 国际化：messages/{en,zh-CN}.json
  • 认证：lib/auth.ts（cookie 迁移 + token 刷新 + cross-tab sync）

15.13 student-portal / parent-portal / admin-portal（Next.js 15 :4001/:4002/:4003，MF Remote）

  • student-portal：路由组 leave + 主页；exam-types 类型；mocks/handlers + server
  • parent-portal：login + 主页 + providers；child-store（Zustand）；middleware.ts；PWA（manifest + sw.js）
  • admin-portal：login + admin layout；hooks（use-classes/files/roles/school/students/teachers/users/graphql）；lib/{auth,i18n,permissions,web-vitals}

15.14 共享包实施状态

包 关键导出 状态
shared-proto 8 proto 文件 + buf.yaml + buf.gen.yaml（生成 6 套代码） ✅
shared-ts bff/（logger）、outbox/（OutboxModule + publisher + schema + types，被 iam/core-edu/content/msg/BFF 共享） ✅
shared-go env/（config.Load）、jwks/（Fetcher，RS256 公钥缓存）、logger/（slog JSON）、tracer/（OTLP init） ✅
shared-py pyproject.toml（uv workspace member） 🚧
contracts STUDENT_PERMISSIONS 常量（12 权限点） 🚧
hooks use-auth / use-permission / use-viewports / use-graphql-client / use-trace-id / use-a11y-id / use-aria-live / use-api / use-toast ✅
ui-components data-table / filter-bar / form / modal / chart / calendar / status-badge / empty / loading + utils/cn ✅
ui-tokens primitive.css / semantic-light.css / semantic-dark.css / tailwind-theme.css / all.css + colors/shadows/spacing/typography (.ts) ✅

15.15 部署与运维实施状态

  • 本地开发：infra/docker-compose.yml（基础设施）+ pnpm dev / go run / uv run
  • 最小化部署：infra/docker-compose.minimal.yml
  • 生产部署：infra/docker-compose.deploy.yml（build: 替代 image:）
  • 测试部署：infra/docker-compose.test.yml
  • 监控栈：infra/docker-compose.monitoring.yml（observability profile）
  • K8s Helm chart：infra/k8s/helm/（edu-platform umbrella + 各子 chart）
  • CI/CD：.github/workflows/ci.yml（quality-ts / quality-go / quality-proto / deploy，no-push 本地构建模式）
  • 备份：infra/backup/backup-mysql.sh（每服务独立，保留 7 天）
  • 混沌工程：infra/chaos/experiments.yaml
  • WAF：infra/security/waf-rules.conf
  • 端口分配：infra/port-allocation.md（唯一源）

15.16 文档体系实施状态

路径 用途
docs/architecture/004_architecture_impact_map.md 本文件（架构影响地图，设计意图唯一源）
docs/architecture/0010_architecture.md 理想蓝图（目标态）
docs/architecture/004-p6-addendum.md P6 硬化附录
docs/architecture/roadmap/ tech-debt / pending-features / integration-test-phase
docs/architecture/runbooks/ p6-hardening / post-p6-followup / incident-response
docs/architecture/issues/ 协调记录（coord / matrix / workline）+ contracts/ + objections/ + worklines/
docs/architecture/ai-allocation.md AI 模块分配
docs/architecture/ai-work-orchestration.md AI 工作编排
docs/architecture/coord-cross-review.md coord 交叉审查
docs/architecture/coord-final-decisions.md coord 最终裁决（ARB-001~022+）
docs/architecture/president-final-rulings.md president 最终裁决（batch 0.9+）
docs/modules/<service>/README.md 各服务模块文档（iam/core-edu/content/msg/data-ana/ai/api-gateway/push-gateway/classes）
docs/standards/ coding-standards / cicd-runbook / full-stack-runbook / git-workflow / local-dev-runbook / multi-ai-collaboration / ui-design-system
docs/troubleshooting/known-issues.md 已知问题速查（索引式场景→技术映射）

本文件 v2.0 已基于代码现状（2026-07-14）全面校准。后续代码变更须按 项目规则 §1 同步更新本文件 + 运行 pnpm run arch:scan。

Reference in New Issue View Git Blame Copy Permalink