# 企业级微服务架构升级设计
> 日期: 2026-07-07
> 状态: 已批准（待书面审阅）
> 范围: 基于 0010_architecture.md 蓝图，将现有 Next.js 单体应用升级为 DDD+EDA+CQRS 微服务架构
> 实施策略: 方案 A（基础设施优先）+ 黄金模板服务驱动
> 团队: 1 人 + AI 辅助
> 周期: 12-18 个月，分 6 阶段（P1-P6）
> 仓库: 全新独立 Git 仓库（next-edu-cloud），与现有 e:\Desktop\CICD 仓库分离
---
## 1. 背景与目标
### 1.1 现状
**现有项目**（e:\Desktop\CICD）：
- 单 Next.js 16 应用 + 严格三层模块化架构（app → modules → shared）
- 35 业务模块、1030 源文件、54 数据库表、61 权限点、6 系统角色
- 已完成企业级规范化（P0 权限治理 + P1 工具链 + P2 配置升级）
- 文档体系成熟：004 架构设计文档 + arch.db 元数据库 + 35 模块 README + known-issues 索引
**0010 蓝图**（理想架构）：
- DDD + EDA + CQRS + 异构微服务云原生架构
- 面向百万级 DAU、多端、全校同时交卷场景
- 6+ 领域微服务、Kafka 事件总线、异构存储（MySQL/ClickHouse/Neo4j/ES）、Push Gateway、Service Mesh
### 1.2 升级意图
用户选择**完整微服务重构**（非选择性借鉴），以 0010 蓝图为终态目标，12-18 个月内分阶段实施。新架构独立于现有 Next.js 项目，从零开始构建。
### 1.3 核心约束
| 维度 | 约束 |
| -------- | ------------------------------------------------------------------ |
| 团队 | 1 人 + AI 辅助生成大部分代码 |
| 周期 | 12-18 个月，分 6 阶段 |
| 仓库 | 全新独立 Git 仓库，与现有 Next.js 仓库分离 |
| 基础设施 | 微服务基础设施先用 Docker Desktop 本地构建 |
| 技术栈 | 异构：Go（网关/长连接）+ Python（AI/分析）+ TypeScript（业务服务） |
| 文档纪律 | 与现有项目等价：架构文档 + 模块文档 + 经验文档 + arch.db 查询 |
| Git 管理 | 严格分支策略、Conventional Commits、模块管理 |
| 数据策略 | 全新 DDD 限界上下文 schema，不迁移旧 schema，不共享数据库 |
### 1.4 目标
- 终态：实现 0010 蓝图的完整微服务架构
- 过程：每阶段有可独立验证的交付物，逐步深入
- 质量：企业级文档纪律、契约先行、CI 强制、可观测先行
- 风险控制：黄金模板服务驱动，避免分布式复杂度一次性爆发
---
## 2. 总体架构与阶段总览
### 2.1 目标系统终态架构
```mermaid
graph TB
subgraph Client["多端访问层"]
MF[Micro-Frontends
Teacher/Student/Parent/Admin
Module Federation]
end
subgraph Edge["边缘与网关层"]
GW[API Gateway
Go: 鉴权/限流/路由]
BFF_T[Teacher BFF
TS: GraphQL+DataLoader]
BFF_S[Student BFF
TS: GraphQL]
BFF_P[Parent BFF
TS: GraphQL]
end
subgraph Services["领域微服务层"]
IAM[IAM 服务
TS/NestJS]
CoreEdu[CoreEdu 服务
TS/NestJS]
Content[Content 服务
TS/NestJS+Neo4j]
DataAna[DataAna 服务
Python: 学情分析]
Msg[Msg 服务
TS/NestJS]
AI[AI 网关
Python: Prompt 管理]
Push[Push Gateway
Go: 长连接]
end
subgraph Bus["事件总线"]
Kafka[(Kafka
领域事件+CDC)]
end
subgraph Storage["异构存储"]
MySQL[(MySQL/TiDB
关系型主库)]
Redis[(Redis Cluster
缓存/锁/PubSub)]
CH[(ClickHouse
分析宽表)]
Neo4j[(Neo4j
知识图谱)]
ES[(Elasticsearch
全文检索)]
end
subgraph Infra["基础设施"]
CDC[Debezium CDC]
Temporal[Temporal
工作流编排]
Conf[配置中心
Consul/Nacos]
Mesh[Service Mesh
Istio]
end
MF --> GW
GW --> BFF_T & BFF_S & BFF_P
BFF_T & BFF_S & BFF_P --> Services
Services --> MySQL
Services --> Redis
Content --> Neo4j
DataAna --> CH
Services -- Outbox --> Kafka
MySQL -- binlog --> CDC --> Kafka
Kafka --> DataAna
Kafka --> Push
Kafka --> ES
```
### 2.2 服务语言分配
| 服务 | 语言 | 框架 | 选型理由 |
| ----------------------------- | ---------- | ------------------------- | ------------------------------ |
| API Gateway | Go | Gin/Echo | 高并发网关性能 |
| Push Gateway | Go | net/http + gorilla | 十万级长连接 |
| IAM / CoreEdu / Content / Msg | TypeScript | NestJS | 业务逻辑 + 类型安全 + DDD 友好 |
| DataAna 服务 | Python | FastAPI + ClickHouse | 数据分析生态 |
| AI 网关 | Python | FastAPI | LLM SDK 生态 |
| BFF × 3 | TypeScript | GraphQL Yoga + DataLoader | 前端聚合 |
### 2.3 角色可扩展性设计（三层解耦模型）
将"角色"拆成三个独立维度，角色只是配置载体，支持未来扩展（教导主任、教研组长、宿管等）：
```mermaid
graph LR
subgraph Role["角色层（可动态扩展）"]
R1[admin]
R2[teacher]
R3[student]
R4[parent]
R5[grade_head
年级主任]
R6[teaching_head
教研组长]
R7[...未来角色]
end
subgraph Perm["权限层（resource:action）"]
P1[exam:create]
P2[exam:read]
P3[...N 个权限点]
end
subgraph View["视口层（UI 可见性配置）"]
V1[L1 导航
侧边栏菜单项]
V2[L2 路由
可访问路由]
V3[L3 组件
页面内组件可见性]
V4[L4 数据
DataScope 行级过滤]
end
Role -.->|"多对多
RolePermission 表"| Perm
Role -.->|"多对多
RoleViewport 表"| View
Perm -.->|"权限推导视口
permission→viewport 映射"| View
```
**关键决策**：视口既可独立配置（RoleViewport 表），也可由权限推导（permission → viewport 默认映射）。新角色只需配置权限集，视口自动推导；需要差异化时再显式配置视口。
**视口四层模型**：
| 层级 | 含义 | 配置载体 | 示例 |
| ------- | ---------------- | ------------------------------------ | -------------------------------------- |
| L1 导航 | 侧边栏菜单项 | `navigation_config` 表 | 教导主任看到"全校成绩分析"菜单 |
| L2 路由 | 可访问路由 | `route_permission` 表 + Gateway 校验 | 教导主任可访问 `/admin/grade-analysis` |
| L3 组件 | 页面内组件可见性 | `usePermission().hasPermission()` | 教导主任看到"导出全校报表"按钮 |
| L4 数据 | 数据行级过滤 | `DataScope` 枚举 | 教导主任 DataScope=`grade_managed` |
**BFF 划分决策**：按"使用场景域"分 4 个稳定 BFF，新角色映射到最接近的场景域 + 通过权限/视口差异化：
- Teacher BFF（教学场景：教师/教导主任/教研组长共用）
- Student BFF（学习场景）
- Parent BFF（家长场景）
- Admin BFF（管理场景）
**微前端划分决策**：按场景域分 4 个稳定 portal，内部通过 `viewports` 配置渲染差异化 UI：
- teacher-portal / student-portal / parent-app / admin-console
### 2.4 六阶段里程碑总览
| 阶段 | 周期 | 核心交付 | 退出标准 |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **P1 地基** | M1-M3 | 仓库骨架 + Docker 全量 infra + API Gateway 骨架 + 契约层 + CI/CD + 文档体系 + classes 域黄金模板服务 | classes 域 CRUD 端到端跑通 + 全横切关注点落地 + 30 分钟可复制新服务 |
| **P2 身份** | M4-M6 | IAM 服务 + Teacher BFF(GraphQL) + 微前端骨架 | 教师可登录并看到空白 Dashboard |
| **P3 核心教学** | M7-M10 | CoreEdu 服务 + Outbox 模式 + 考试/作业/成绩域 | 教师创建考试→学生作答→教师批改→成绩统计 全链路 |
| **P4 内容+分析** | M11-M13 | Content 服务(Neo4j，CRUD only) + DataAna(Python+CH) + CDC 链路 | 知识图谱查询 + 学情诊断宽表 5s 内返回 |
| **P5 沟通+AI** | M14-M16 | Msg 服务 + Push Gateway + AI 网关 + ES 题库检索 | 全校广播推送 + AI 辅助出题 + 题库检索 < 200ms |
| **P6 硬化** | M17-M18 | Service Mesh + 全链路可观测 + 生产硬化 | 单服务可独立扩缩容 + 99.9% 可用性 |
### 2.5 新仓库目录结构
```
next-edu-cloud/ # 新独立仓库
├─ .github/workflows/ # CI/CD（每服务独立 workflow）
├─ docs/
│ ├─ architecture/
│ │ ├─ 0010_architecture.md # 从旧仓库迁移的理想蓝图
│ │ ├─ 004_architecture_impact_map.md # 架构设计意图（多服务版）
│ │ ├─ roadmap/ # 长远规划
│ │ └─ audit/ # 架构审查报告
│ ├─ modules/ # 各服务 README（每个服务一份）
│ ├─ standards/ # 编码规范（按语言分）
│ ├─ troubleshooting/ # known-issues 索引
│ └─ superpowers/specs/ # 设计 spec
├─ packages/ # 共享包
│ ├─ shared-types/ # TS 共享类型（protobuf 生成）
│ ├─ shared-proto/ # protobuf 契约源
│ └─ shared-go/ # Go 共享库
├─ services/ # 领域微服务
│ ├─ api-gateway/ # Go
│ ├─ push-gateway/ # Go
│ ├─ iam/ # TS/NestJS
│ ├─ core-edu/ # TS/NestJS
│ ├─ content/ # TS/NestJS
│ ├─ data-ana/ # Python/FastAPI
│ ├─ messaging/ # TS/NestJS
│ └─ ai-gateway/ # Python/FastAPI
├─ bff/ # BFF 层
│ ├─ teacher-bff/
│ ├─ student-bff/
│ └─ parent-bff/
├─ apps/ # 微前端应用
│ ├─ teacher-portal/
│ ├─ student-portal/
│ ├─ parent-app/
│ └─ admin-console/
├─ infra/ # 基础设施编排
│ ├─ docker-compose.yml # 本地全量 infra
│ ├─ docker-compose.minimal.yml # 最小开发集
│ └─ k8s/ # K8s 清单（P6 阶段）
├─ scripts/ # 工具脚本
│ ├─ arch-scan/ # arch.db 扫描器（多语言）
│ └─ arch-query/ # arch.db 查询
├─ arch.db # 架构元数据库（多语言扩展）
├─ package.json # monorepo 根（pnpm workspace）
├─ pnpm-workspace.yaml
├─ go.work # Go workspace
└─ pyproject.toml # Python workspace（uv/poetry）
```
### 2.6 与现有 Next.js 项目的关系
| 维度 | 关系 |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| 代码 | **不迁移**。新仓库从零开始，旧 schema 仅作领域知识参考 |
| 数据库 | **不共享**。新系统全新 schema，未来通过 CDC/ETL 迁移数据 |
| 文档体系 | **移植并扩展**：004 模板、arch.db 扫描器、模块 README 模板、known-issues 索引格式全部迁移，扩展支持 Go/Python |
| 项目规则 | **移植 project_rules.md** 并按多语言/微服务特性调整 |
| Git 管理 | 新独立仓库，独立分支策略，但提交规范（Conventional Commits）延续 |
---
## 3. P1 地基阶段详细设计
### 3.1 P1 范围与不做清单
**做**：
- 新仓库初始化（独立 git 仓库，独立分支策略）
- 多语言 monorepo 骨架（pnpm + go.work + pyproject）
- Docker Compose 全量基础设施（一次性到位）
- API Gateway 骨架（Go，仅路由+鉴权转发，不做限流高级功能）
- 契约层（protobuf + OpenAPI，先定义 classes 域契约）
- CI/CD 骨架（每语言独立 workflow，lint+test+build）
- 文档体系移植（004 模板 / arch.db 多语言扫描器 / 模块 README 模板 / project_rules 多语言版）
- **classes 域黄金模板服务**（完整实现所有横切关注点，作为后续服务复制范本）
**不做**（P1 严格禁止，避免膨胀）：
- 不实现 IAM 服务（P1 用 Gateway 内置最小鉴权，P2 才建 IAM 服务）
- 不实现 Outbox/Kafka/CDC（P1 classes 域直接 CRUD MySQL）
- 不实现 BFF/微前端完整骨架（P1 用单一测试页验证链路）
- 不实现 ClickHouse/Neo4j/ES 的业务逻辑（仅 docker-compose 起容器备用）
- 不实现任何复杂业务逻辑（classes 域仅 CRUD）
- 不预实现阶段特有模式（Outbox/CDC/长连接在对应阶段实现后回写黄金模板）
### 3.2 P1 目录骨架（实际创建）
```
next-edu-cloud/
├─ .github/workflows/
│ ├─ ci-go.yml # Go: lint+test+build
│ ├─ ci-ts.yml # TS: lint+tsc+test
│ └─ ci-py.yml # Python: ruff+pytest
├─ docs/
│ ├─ architecture/
│ │ ├─ 0010_architecture.md # 迁移自旧仓库
│ │ ├─ 004_architecture_impact_map.md # 架构设计意图（多服务版）
│ │ ├─ roadmap/ # tech-debt / decoupling / pending-features
│ │ └─ audit/
│ ├─ modules/ # 各服务 README
│ ├─ standards/
│ │ ├─ coding-standards.md # 多语言编码规范
│ │ └─ git-workflow.md # 分支策略 + Conventional Commits
│ ├─ troubleshooting/known-issues.md
│ └─ superpowers/specs/
├─ packages/
│ ├─ shared-proto/ # protobuf 契约源 + 生成脚本
│ │ ├─ proto/classes.proto
│ │ └─ buf.yaml
│ ├─ shared-ts/ # TS 共享类型（从 proto 生成）
│ └─ shared-go/ # Go 共享库
├─ services/
│ ├─ api-gateway/ # Go: 仅路由+鉴权转发
│ │ ├─ main.go
│ │ ├─ go.mod
│ │ └─ Dockerfile
│ └─ classes/ # TS/NestJS 黄金模板服务
│ ├─ src/
│ │ ├─ main.ts # NestJS bootstrap + OTel 初始化
│ │ ├─ app.module.ts
│ │ ├─ config/
│ │ │ ├─ config.ts # 三层配置加载
│ │ │ └─ env.ts # @t3-oss/env-nextjs 校验
│ │ ├─ middleware/
│ │ │ ├─ auth.middleware.ts # JWT 公钥校验
│ │ │ ├─ permission.guard.ts # requirePermission()
│ │ │ └─ data-scope.interceptor.ts # DataScope 注入
│ │ ├─ classes/
│ │ │ ├─ classes.controller.ts # gRPC handler
│ │ │ ├─ classes.service.ts # 业务编排
│ │ │ ├─ classes.repository.ts # 数据访问（Drizzle）
│ │ │ └─ classes.dto.ts # 从 proto 生成
│ │ ├─ shared/
│ │ │ ├─ errors/ # ApplicationError 基类 + 子类
│ │ │ ├─ observability/ # logger/metrics/tracer
│ │ │ └─ i18n/ # 错误码 → key 映射
│ │ └─ generated/ # proto 生成代码
│ ├─ test/
│ │ ├─ unit/ # vitest 单元测试
│ │ ├─ integration/ # Testcontainers 集成测试
│ │ ├─ contract/ # Pact 契约测试
│ │ └─ e2e/ # Playwright E2E
│ ├─ Dockerfile # 多阶段构建模板
│ ├─ nest-cli.json
│ ├─ tsconfig.json
│ ├─ vitest.config.ts
│ └─ README.md # 8 章模板（黄金范本）
├─ bff/
│ └─ teacher-bff/ # P1 仅占位，P2 实现
├─ apps/
│ └─ teacher-portal/ # P1 仅一个测试页验证链路
│ ├─ package.json
│ └─ src/
├─ infra/
│ ├─ docker-compose.yml # 全量基础设施
│ ├─ docker-compose.minimal.yml # 仅 MySQL+Redis（开发最小集）
│ └─ init-sql/ # MySQL 初始化脚本
├─ scripts/
│ ├─ arch-scan/ # 多语言 arch.db 扫描器
│ └─ arch-query/
├─ .commitlintrc.js
├─ .husky/
├─ arch.db
├─ package.json # pnpm workspace 根
├─ pnpm-workspace.yaml
├─ go.work
├─ pyproject.toml
├─ LICENSE
├─ CHANGELOG.md
├─ CONTRIBUTING.md
├─ SECURITY.md
└─ .env.example
```
### 3.3 Docker Compose 全量基础设施
一次性起齐所有容器，业务逻辑按阶段填入。最小开发集（`docker-compose.minimal.yml`）仅 mysql + redis，用于日常开发快速启动。
P1 仅启动 MySQL + Redis；P3 加 Kafka + Zookeeper；P4 加 Debezium + ClickHouse + Neo4j；P5 加 Elasticsearch；P6 加 Consul + Istio。每服务配置 `mem_limit` 避免单服务吃满内存。
### 3.4 契约层设计
P1 用 **protobuf 作为服务间契约的唯一源**，OpenAPI 作为 BFF 对前端的契约：
```
packages/shared-proto/
├─ proto/
│ ├─ classes.proto # P1 唯一契约
│ ├─ iam.proto # P2 占位
│ └─ core_edu.proto # P3 占位
├─ buf.yaml # buf 工具配置（lint+breaking change 检测）
├─ buf.gen.yaml # 代码生成配置（TS+Go+Python 三端）
└─ README.md
```
**契约先行的硬约束**：
- 任何服务间通信必须先改 proto，CI 检测 breaking change 阻止违规合并
- proto 版本化：包名带版本（`classes.v1`、`classes.v2`），新旧版本共存
- 生成三端代码：`shared-ts/`（NestJS 用）、`shared-go/`（Gateway 用）、`services/*/generated/`（Python 用）
### 3.5 API Gateway 骨架（Go）
P1 仅实现：路由 + JWT 校验 + 转发。不做限流/熔断/灰度（P6 硬化）。
**P1 鉴权**：Gateway 内置最小 JWT 校验（HS256 + 用户 ID + 角色列表），P2 由 IAM 服务接管签发（RS256）。P1 用测试 JWT 工具生成 token 验证链路。
### 3.6 classes 域黄金模板服务
P1 末尾用 classes 域端到端验证地基。classes 服务不再只是"验证链路"，而是**完整实现所有横切关注点**，作为后续 8 个服务的复制模板：
| 横切关注点 | classes 黄金模板实现 | 后续服务复用方式 |
| ---------- | ----------------------------------------------------------------------- | ------------------------- |
| 错误处理 | TS `ApplicationError` 基类 + 错误码 `CORE_EDU_*` | 复制基类，改错误码前缀 |
| 可观测 | pino 结构化日志 + prom-client metrics + OTel trace | 复制 SDK 初始化代码 |
| 安全 | JWT 公钥校验 + `requirePermission()` 中间件 + DataScope 过滤 | 复制中间件 |
| 契约 | classes.proto + buf lint/breaking + 三端代码生成 | 复制 buf 配置，加新 proto |
| 测试 | 单元（vitest）+ 集成（Testcontainers）+ 契约（Pact）+ E2E（Playwright） | 复制测试目录结构与配置 |
| 文档 | 模块 README 8 章模板 + arch.db 扫描 + known-issues 条目 | 复制 README 模板 |
| 配置 | 三层配置（env/yaml/默认值）+ `@t3-oss/env-nextjs` | 复制配置加载代码 |
| i18n | 错误码 → i18n key 映射 | 复制映射表结构 |
| CI/CD | Go/TS/Python 三语言 workflow 模板 | 复制 workflow，改服务名 |
| Dockerfile | 多阶段构建模板 | 复制 Dockerfile，改入口 |
**后续服务复制流程**：
1. `cp -r services/classes services/iam`
2. 改错误码前缀 `CORE_EDU → IAM`
3. 改 proto 文件 `iam.proto`
4. 改业务逻辑（controller/service/repository）
5. 改 README 模块名与架构图
6. 改 CI workflow 服务名
7. 改 Dockerfile 入口（如需要）
8. 运行 `npm run arch:scan` 确认 arch.db 更新
9. 运行 `buf lint` + `buf breaking` 确认契约合规
**Outbox/CDC/长连接等阶段特有模式**：在对应阶段实现后**回写黄金模板**（在 classes 服务的 README 增加章节示例），后续服务复制时即包含。
### 3.7 P1 Git 管理策略
**分支策略**（trunk-based 简化版，适合 1 人 + AI）：
```
main # 受保护，仅通过 PR 合入，始终可发布
├─ feature/p1-repo-init # P1 仓库初始化
├─ feature/p1-infra-compose # Docker Compose 基础设施
├─ feature/p1-api-gateway-skel # Gateway 骨架
├─ feature/p1-contract-classes # classes 契约
├─ feature/p1-classes-service # classes 黄金模板服务
├─ feature/p1-teacher-portal # 测试页
├─ feature/p1-docs-system # 文档体系移植
└─ feature/p1-arch-scan-multilang # arch.db 多语言扫描器
```
- 每个 feature 分支独立 PR，CI 通过后合入 main
- main 始终保持可运行（`docker-compose up` 可起所有 infra）
- 每阶段末打 tag：`v0.1.0-p1`、`v0.2.0-p2`...
- commitlint 强制 Conventional Commits（与旧项目一致）
### 3.8 P1 退出标准（验收）
| 维度 | 验收项 |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| 基础设施 | `docker-compose up -d` 全量容器健康（P1 仅起 MySQL+Redis，其余容器配置就绪但不启动） |
| 链路 | 浏览器创建班级 → MySQL 落库 → 列表显示 |
| 横切关注点 | 全横切关注点落地：错误处理 + 可观测 + 安全 + 契约 + 测试 + 文档 + 配置 + i18n + CI + Dockerfile |
| 契约 | `buf lint` + `buf breaking` 通过，三端代码生成成功 |
| CI | 三语言 workflow 全绿（lint+test+build） |
| 测试 | 单元 + 阈值集成 + 契约 + E2E 四类测试齐备，覆盖率达标（领域逻辑 ≥ 80%，Handler ≥ 60%，整体 ≥ 60%） |
| 文档 | 004 + 2 个模块 README（api-gateway + classes）+ coding-standards + known-issues + project_rules 齐全 |
| arch.db | `npm run arch:scan` 扫描 Go+TS 代码，`arch:query -- violations` 输出 0 |
| 可复制性 | 新建一个空服务复制 classes 模板，30 分钟内可跑起来 |
| Git | main 受保护，所有 feature 经 PR 合入，打 tag `v0.1.0-p1` |
---
## 4. P2-P6 各阶段详细设计
### 4.1 P2 身份层（M4-M6）
**目标**：建 IAM 服务，替换 P1 Gateway 内置最小鉴权；建首个完整 BFF（Teacher）与微前端骨架。
**交付物**：
| 组件 | 内容 |
|------|------|
| IAM 服务（TS/NestJS） | 认证（登录/登出/JWT/2FA）+ RBAC（角色/权限/角色-权限 CRUD）+ 视口配置（4 层模型）+ DataScope 解析 + `getEffectivePermissions(userId)` API |
| MySQL schema | `users` / `roles` / `permissions` / `role_permissions` / `role_viewports` / `parent_student_relations` / `class_subject_teachers`（DataScope 依赖） |
| Teacher BFF（TS/GraphQL） | GraphQL Yoga + DataLoader（防 N+1）+ 调 IAM 的 `getEffectivePermissions` 注入视口到响应 |
| teacher-portal（微前端宿主） | Module Federation 宿主 + 路由骨架 + 侧边栏（由 `viewports.L1` 驱动渲染）+ 登录页 |
| API Gateway | 移除内置 JWT，改调 IAM 校验；路由表扩展 `/api/v1/iam/*` |
**关键技术决策**：
- JWT 由 IAM 签发（RS256，非对称），Gateway 用公钥校验，无需调 IAM 即可校验签名
- `getEffectivePermissions` 结果用 Redis 缓存（TTL 5 分钟），角色变更时主动失效
- 视口配置存 MySQL（`role_viewports` 表），不硬编码到前端
**退出标准**：教师登录 → 获取 JWT → 访问 teacher-portal → 侧边栏按 `viewports.L1` 渲染 → 看到空白 Dashboard 占位页。
### 4.2 P3 核心教学层（M7-M10）
**目标**：建 CoreEdu 服务，实现考试全生命周期；落地 Outbox + Kafka 事件模式。
**交付物**：
| 组件 | 内容 |
|------|------|
| CoreEdu 服务（TS/NestJS） | 考试/作业/成绩域 CRUD + 批改业务编排 + Outbox 事件发布 |
| MySQL schema | `exams` / `exam_questions` / `homework_assignments` / `homework_submissions` / `homework_answers` / `grade_records` / `outbox_events` |
| Outbox 模式 | 业务事务同写 `outbox_events` 表；后台 relay worker 投递到 Kafka |
| Kafka | 启用业务 topic：`exam.published` / `homework.graded` / `grade.recorded` |
| Teacher BFF 扩展 | 考试/作业/成绩的 GraphQL 查询与 mutation |
| teacher-portal 扩展 | 考试创建/作业批改/成绩查看页面 |
| student-portal（微前端） | 学生作答作业页面（Module Federation 子应用） |
| Temporal | 引入但仅做 1 个工作流（考试发布编排：创建作业→通知）作为试点 |
**关键技术决策**：
- **不引入 Saga**：跨服务一致性用 Outbox + 最终一致性，避免 Saga 复杂度
- **批改后联动**（沿用旧项目模式）：批改完成 → 发 `homework.graded` 事件 → 各下游消费（P4 的 DataAna 消费、P5 的 Msg 消费通知）
- Outbox relay worker 用 Go 写（轻量、高吞吐），独立服务 `services/outbox-relay/`
- **Outbox 实现后回写黄金模板**
**退出标准**：教师创建考试 → 发布 → 学生作答提交 → 教师批改 → 事件发到 Kafka → 成绩统计更新（CoreEdu 内部消费自己事件做统计）→ 全链路可观测（trace 追踪）。
### 4.3 P4 内容与分析层（M11-M13）
**目标**：建 Content 服务（Neo4j 知识图谱）+ DataAna 服务（Python+ClickHouse）；落地 CDC 链路。
**交付物**：
| 组件 | 内容 |
|------|------|
| Content 服务（TS/NestJS） | 教材/章节/知识点 CRUD（**仅 CRUD，不实现检索**）+ 知识图谱查询（调 Neo4j）+ 题库 CRUD（**不实现检索**） |
| MySQL schema | `textbooks` / `chapters` / `knowledge_points` / `questions` |
| Neo4j 数据 | 知识点前置依赖图（从 MySQL `knowledge_points` 同步） |
| DataAna 服务（Python/FastAPI） | 学情诊断 API + 错题本 API + 消费 Kafka 构建宽表 |
| ClickHouse | `student_dashboard_view` 宽表（由 DataAna 消费 Kafka 填充） |
| CDC 链路 | Debezium 监听 MySQL binlog → Kafka（`mysql.cdc.*` topic）→ DataAna 消费写 ClickHouse |
| BFF 扩展 | Teacher BFF 加知识图谱查询；Student BFF 加学情诊断查询（降级查 MySQL 主库 + 升级查 CH 宽表） |
**关键技术决策**：
- **题库检索延后到 P5**：P4 Content 服务题库只做 CRUD，P5 引入 ES 直接实现检索，避免 MySQL FULLTEXT → ES 迁移成本
- **双轨读策略**：实时性要求高的查 MySQL 主库（如刚提交的作业成绩），聚合统计查 ClickHouse 宽表（延迟 1-5s 可接受）
- **Neo4j 写入**：Content 服务写 MySQL 同时发事件，独立 worker 消费事件同步 Neo4j（避免双写不一致）
- **CDC 实现后回写黄金模板**
**退出标准**：教师查看知识图谱前置依赖（Neo4j 秒级返回）→ 学生查看学情诊断（ClickHouse 宽表 5s 内返回）→ CDC 链路延迟 < 5s。
### 4.4 P5 沟通与 AI 层（M14-M16）
**目标**：建 Msg 服务 + Push Gateway + AI 网关；全文检索迁 ES。
**交付物**：
| 组件 | 内容 |
|------|------|
| Msg 服务（TS/NestJS） | 会话/消息 CRUD + 调 Push Gateway 推送 + 通知偏好 |
| Push Gateway（Go） | WebSocket 长连接管理 + 消费 Kafka 广播 + Redis PubSub 跨实例同步 |
| AI 网关（Python/FastAPI） | LLM Provider 适配（OpenAI/Anthropic）+ Prompt 模板管理 + 流式 SSE + 用量计费 |
| ES | 题库全文检索（从 MySQL 同步）+ 全局搜索 API |
| Notifications 模块 | 沿用旧项目 dispatcher 模式，多渠道（站内/SMS/邮件/微信） |
| BFF/前端扩展 | Teacher BFF 加 AI 辅助出题 mutation；teacher-portal 加 SSE 流式 AI 对话 |
**关键技术决策**：
- **Push Gateway 用 Go**：单节点支撑 10w+ 连接，业务服务只需发 Kafka 消息
- **AI 网关用 Python**：LLM SDK 生态（langchain/litellm）成熟，Prompt 版本管理友好
- **离线消息**：Push Gateway 仅推在线用户，离线消息存 MySQL，上线时拉取
- **流式 SSE**：AI 网关 → BFF → 前端，三层透传，BFF 不缓冲
- **长连接模式实现后回写黄金模板**
**退出标准**：教师发广播通知 → 全在线学生实时收到（Push Gateway）→ AI 辅助出题流式返回 → 题库全文检索 < 200ms。
### 4.5 P6 硬化层（M17-M18）
**目标**：生产硬化，达到可部署状态。
**交付物**：
| 组件 | 内容 |
|------|------|
| Service Mesh | Istio 服务网格（mTLS + 流量治理 + 可观测） |
| 配置中心 | Consul 接入，配置热更新（限流阈值、功能开关） |
| 全链路可观测 | OpenTelemetry + Jaeger（trace）+ Prometheus（metrics）+ Loki（logs） |
| 限流/熔断 | Gateway 层限流（令牌桶）+ 服务间熔断（Envoy） |
| 灰度发布 | Istio 流量拆分（金丝雀） |
| K8s 部署 | 每服务 K8s manifest + HPA 自动扩缩容 |
| 生产 CI/CD | Git tag 触发镜像构建 + 滚动部署 |
| 灾备 | MySQL 主从 + Redis 哨兵 + Kafka 多副本 |
**降级方案**：若 P6 时间紧张，Service Mesh 可降级为 K8s 原生 Service + Ingress，Istio 延后。
**退出标准**：单服务可独立扩缩容（HPA 生效）→ 全链路 trace 可追 → 模拟单服务宕机不影响核心链路 → 99.9% 可用性压测通过。
### 4.6 阶段依赖与并行机会
```mermaid
graph LR
P1[P1 地基] --> P2[P2 身份]
P2 --> P3[P3 核心教学]
P3 --> P4[P4 内容分析]
P3 --> P5[P5 沟通AI]
P4 --> P6[P6 硬化]
P5 --> P6
```
**并行机会**：P4 与 P5 理论上可并行（都依赖 P3 的事件），但 1 人项目建议串行避免上下文切换。
### 4.7 跨阶段不变约束
每阶段都必须遵守：
- 契约先行（先改 proto，后写实现）
- 文档同步（004 + 模块 README + arch.db + known-issues 实时更新）
- CI 全绿才能合入 main
- 每阶段末打 tag
- Server/Handler 接口必须权限校验
- 单文件行数遵循语言规范（TS ≤ 500/800/1000，Go ≤ 800，Python ≤ 800）
---
## 5. 跨阶段横切关注点
### 5.1 错误处理与响应规范
#### 5.1.1 错误分类体系
```mermaid
graph TB
subgraph Domain["领域错误（业务可预期）"]
ValErr[ValidationError
400]
NotFound[NotFoundError
404]
PermErr[PermissionDeniedError
403]
Conflict[ConflictError
409]
BizErr[BusinessError
400]
end
subgraph Infra["基础设施错误（非预期）"]
DBErr[DatabaseError
500]
UpstreamErr[UpstreamServiceError
502]
TimeoutErr[TimeoutError
504]
InternalErr[InternalError
500]
end
subgraph Contract["契约错误"]
ProtoErr[ContractViolationError
500]
SerialErr[SerializationError
400]
end
```
**统一错误基类**（每语言一份，从 proto 生成）：
- TS：`ApplicationError` 基类 + 子类
- Go：`AppError` struct + 错误码常量
- Python：`AppError` 异常基类 + 子类
**错误码规范**：`{服务前缀}_{错误类型}_{资源}`，如 `IAM_PERM_USER`、`CORE_EDU_VAL_EXAM`。错误码在 proto 中定义，三端共享。
#### 5.1.2 响应信封（统一跨服务）
所有 HTTP/GraphQL/gRPC 响应统一信封：
```typescript
interface Result {
success: boolean
data?: T
error?: {
code: string // IAM_PERM_USER
message: string // 用户可读消息（i18n key）
details?: unknown // 字段级错误详情
traceId: string // 链路追踪 ID
}
}
```
- gRPC 用 `google.rpc.Status` + `details` 承载业务错误
- HTTP/Gateway 层做 gRPC Status → HTTP 状态码映射
- BFF/GraphQL 用 `union` 类型表达错误
### 5.2 可观测性三支柱
P1 即建立基础，每阶段强化：
| 支柱 | P1 基础 | P6 硬化 |
| ----------- | ---------------------------------------------------- | ---------------------------- |
| **Logs** | 结构化 JSON 日志（pino/winston/zap）+ `traceId` 注入 | Loki 集中查询 + 日志保留策略 |
| **Metrics** | Prometheus client 暴露 `/metrics`（QPS/延迟/错误率） | Grafana 仪表盘 + 告警规则 |
| **Traces** | OpenTelemetry SDK 注入 trace（Gateway→服务→DB） | Jaeger 全链路追踪 + 采样策略 |
**P1 最小可观测集**（不引入完整栈，但 SDK 注入到位）：
- 每服务结构化日志，含 `traceId`/`spanId`/`userId`/`service`
- 每服务暴露 `/metrics` endpoint
- OpenTelemetry SDK 初始化，trace 上下文跨服务传播（W3C TraceContext header）
**P6 引入完整后端**：Loki + Grafana + Jaeger + Prometheus，通过 docker-compose 起齐。
### 5.3 安全架构
#### 5.3.1 认证链路
```mermaid
sequenceDiagram
participant C as Client
participant GW as API Gateway
participant IAM as IAM 服务
participant Svc as 业务服务
participant DB as MySQL
C->>IAM: 登录(credentials + 2FA)
IAM->>DB: 验证密码 + 2FA
IAM->>DB: 查角色 + 权限 + 视口
IAM->>IAM: 签发 JWT(RS256)
IAM-->>C: JWT + refreshToken
C->>GW: 请求 + JWT
GW->>GW: 公钥验签 JWT
GW->>GW: 检查路由权限位图
alt 权限不足
GW-->>C: 403
else 通过
GW->>Svc: 转发 + 注入 x-user-context
Svc->>Svc: requirePermission(perm)
Svc->>DB: 执行(带 DataScope 过滤)
end
```
**关键安全决策**：
- JWT 用 RS256（非对称），IAM 私钥签发，Gateway/服务用公钥校验，无需调 IAM
- JWT payload：`{ userId, roles, permissions(bitmap), dataScope, exp }`
- Token TTL：access 15min / refresh 7day，refresh 用 Redis 黑名单失效
- 破坏性操作独立权限点（如 `AUDIT_LOG_PURGE` ≠ `AUDIT_LOG_READ`，沿用旧项目规则）
#### 5.3.2 数据范围过滤（DataScope）
沿用旧项目 6 级 DataScope，扩展为 IAM 服务统一解析：
| 类型 | 适用角色 | 数据范围 |
| --------------- | --------------------- | -------- |
| `all` | admin | 全部 |
| `grade_managed` | grade_head / 教导主任 | 管辖年级 |
| `class_taught` | teacher / 教研组长 | 所教班级 |
| `class_members` | student | 所在班级 |
| `children` | parent | 关联孩子 |
| `owned` | 所有角色 | 自己创建 |
DataScope 由 IAM 解析后注入 JWT，业务服务读取后下推到 SQL WHERE 条件。
#### 5.3.3 其他安全约束
- 服务间通信：P1-P5 用明文 gRPC（内网信任），P6 引入 mTLS
- 环境变量：用 `@t3-oss/env-nextjs`（TS）+ `viper`（Go）+ `pydantic-settings`（Python）校验
- 密钥管理：P1-P5 用 `.env` + docker secrets，P6 引入 Vault
- SQL 注入：ORM 参数化查询（Drizzle/GORM/SQLAlchemy），禁止字符串拼接
- XSS：微前端用 React 默认转义 + CSP header
- 速率限制：P1 Gateway 基础限流，P6 引入 Envoy 全局限流
### 5.4 测试策略
#### 5.4.1 测试金字塔
```mermaid
graph TB
subgraph E2E["E2E 测试（< 10%）"]
Playwright[Playwright
关键用户旅程]
end
subgraph Integ["集成测试（30%）"]
Contract[契约测试
Pact + proto]
Service[服务集成
Testcontainers]
end
subgraph Unit["单元测试（60%）"]
Domain[领域逻辑
纯函数]
Handler[Handler/Controller]
end
Unit --> Integ --> E2E
```
#### 5.4.2 各阶段测试要求
| 阶段 | 单元测试 | 集成测试 | E2E |
| ---- | --------------------------- | ---------------------- | -------------- |
| P1 | arch-scan 工具链 | classes 切片契约测试 | 浏览器创建班级 |
| P2 | IAM 权限解析逻辑 | IAM→Gateway 契约 | 登录流程 |
| P3 | 批改业务逻辑 + Outbox relay | CoreEdu→Kafka 事件契约 | 考试全生命周期 |
| P4 | 知识图谱查询 + 学情分析 | CDC 链路验证 | 学情诊断展示 |
| P5 | Push 连接管理 + AI Prompt | Msg→Push 事件契约 | 广播 + AI 对话 |
| P6 | - | 全链路压测 | 灾备演练 |
#### 5.4.3 覆盖率门槛
| 层级 | 覆盖率要求 |
| ----------------------- | ---------- |
| 领域逻辑（纯函数） | ≥ 80% |
| 服务 Handler/Controller | ≥ 60% |
| 基础设施代码 | ≥ 40% |
| 整体 | ≥ 60% |
CI 在 lint → test 后强制检查覆盖率，低于门槛阻断合并。
#### 5.4.4 契约测试（关键）
服务间通信用 proto 契约，**契约测试是集成测试核心**：
- `packages/shared-proto/` 用 `buf breaking` 检测 breaking change
- 消费端驱动契约测试（Pact）：消费端定义期望，提供端验证
- P3 起每事件类型有契约测试（`homework.graded` 事件的 schema 验证）
### 5.5 i18n 策略
沿用旧项目 next-intl 模式，扩展到多服务：
- 前端：next-intl（微前端共享翻译资源包）
- 后端错误消息：错误码 → i18n key 映射，前端翻译
- BFF/服务不返回翻译后文本，返回 i18n key + 参数
### 5.6 配置管理
**三层配置**：
1. **环境变量**（`.env` / docker secrets）：基础设施连接、密钥
2. **配置文件**（`config/{env}.yaml`）：业务参数（限流阈值、功能开关静态默认）
3. **配置中心**（Consul，P6 启用）：运行时热更新参数
每服务启动时合并三层：默认值 < 配置文件 < 环境变量 < 配置中心（P6）。
---
## 6. 文档体系与 arch.db 多语言扩展
### 6.1 文档体系全景
```mermaid
graph TB
subgraph Design["架构设计文档（设计意图）"]
Doc004[004_architecture_impact_map.md
多服务版架构设计意图]
Doc0010[0010_architecture.md
理想蓝图（迁移）]
end
subgraph Code["代码结构文档（arch.db）"]
ArchDB[arch.db
多语言代码元数据]
ArchScan[arch-scan
TS+Go+Python 扫描器]
ArchQuery[arch-query
违规检测/依赖查询]
end
subgraph Module["模块文档（服务级）"]
ModuleReadme[docs/modules/{service}/README.md
8 章模板]
end
subgraph Experience["经验文档"]
KnownIssues[known-issues.md
索引式场景→技术映射]
WorkLog[工作经验日志
50 条上限]
end
subgraph Standards["规范文档"]
Coding[coding-standards.md
多语言编码规范]
GitWF[git-workflow.md
分支/提交规范]
ProjectRules[project_rules.md
AI 工作强制流程]
end
subgraph Planning["规划文档"]
Roadmap[roadmap/
tech-debt/decoupling/pending]
Specs[superpowers/specs/
设计 spec]
end
Design --> Code
Code --> Module
Module --> Experience
Standards --> Code
Planning --> Design
```
**文档分层原则**（与旧项目一致）：
- **设计意图**（004）与**代码现状**（arch.db）分离互补
- **模块文档**（README）是服务级入口
- **经验文档**（known-issues）是索引式速查
- **规范文档**强制 AI 与人类工作流程
### 6.2 004 架构设计文档（多服务版）
移植旧 004 模板，扩展为多服务架构。目录结构：
```
004_architecture_impact_map.md
├─ 1. 项目概览（系统边界 + 规模指标）
├─ 2. 技术栈选型（按语言分节：Go/TS/Python）
├─ 3. 分层架构（Client → Edge → Service → Bus → Storage → Infra）
├─ 4. 服务依赖全景图（mermaid + 依赖深度统计）
├─ 5. 认证与权限架构（IAM + RS256 JWT + 视口 4 层模型 + DataScope）
├─ 6. 数据访问与缓存架构（CQRS + Outbox + CDC + 双轨读）
├─ 7. 事件驱动架构（Kafka topic 清单 + 事件 schema 约定）
├─ 8. 跨服务协作机制（gRPC 契约 + Outbox 事件 + Temporal 编排）
├─ 9. 核心业务流程（考试全生命周期等，跨服务 sequence diagram）
├─ 10. 可观测性架构（Logs/Metrics/Traces 三支柱）
├─ 11. API 与实时通信（Gateway 路由 + SSE + Push Gateway）
├─ 12. 架构约束与设计原则（多语言版硬性约束）
├─ 13. 架构决策记录（ADR）
└─ 14. 附录（arch.db 查询入口 + 关键参数影响链）
```
**与旧 004 的差异**：
- 第 3 章从"三层架构"扩展为"六层架构"（Client/Edge/Service/Bus/Storage/Infra）
- 新增第 7 章"事件驱动架构"（旧项目无此章）
- 第 8 章从"跨模块协作"扩展为"跨服务协作"（含 gRPC 契约 + Temporal 编排）
- 新增第 10 章"可观测性架构"
### 6.3 模块 README 8 章模板（多服务版）
沿用旧项目 8 章模板，适配微服务特性。每个服务一份 README：
```
docs/modules/{service}/README.md
├─ 1. 模块职责（一句话 + 边界）
├─ 2. 技术栈（语言/框架/依赖）
├─ 3. 架构图（mermaid graph TB：服务内部组件）
├─ 4. 核心流程图（mermaid sequenceDiagram：关键业务流程）
├─ 5. 对外契约（proto 文件 + gRPC 方法清单 + 事件 topic）
├─ 6. 依赖关系（上游依赖服务 + 下游被依赖 + 数据库/中间件）
├─ 7. 架构约束（服务特有约束 + 横切关注点落地方式）
└─ 8. 架构决策（服务特有 ADR + 黄金模板复用清单）
```
**黄金模板服务（classes）README 是范本**，后续服务复制后修改第 1/3/4/5/6 章，第 2/7/8 章大部分复用。
### 6.4 arch.db 多语言扩展（关键改造）
旧 arch-scan 仅支持 TS。新扫描器扩展支持 Go + Python，统一写入 arch.db。
#### 6.4.1 arch.db schema 扩展
```sql
-- 新增 language 字段
ALTER TABLE symbols ADD COLUMN language TEXT; -- 'ts' | 'go' | 'python'
ALTER TABLE modules ADD COLUMN language TEXT;
-- 新增 service 字段（微服务标识）
ALTER TABLE modules ADD COLUMN service TEXT; -- 'api-gateway' | 'iam' | 'core-edu' | ...
-- 新增 contract 字段（proto 契约）
CREATE TABLE contracts (
id INTEGER PRIMARY KEY,
proto_file TEXT,
service_name TEXT,
method_name TEXT,
request_type TEXT,
response_type TEXT,
breaking_change BOOLEAN DEFAULT 0
);
-- 新增 event 字段（Kafka 事件）
CREATE TABLE events (
id INTEGER PRIMARY KEY,
topic TEXT,
event_type TEXT, -- 'domain' | 'cdc'
producer_service TEXT,
consumer_services TEXT, -- JSON array
schema_proto TEXT
);
```
#### 6.4.2 多语言扫描器架构
```
scripts/arch-scan/
├─ scanner.ts # 主入口（协调三语言扫描）
├─ scanners/
│ ├─ ts-scanner.ts # TS 扫描（沿用旧版，ts-morph）
│ ├─ go-scanner.ts # Go 扫描（tree-sitter-go）
│ └─ py-scanner.ts # Python 扫描（tree-sitter-python）
├─ proto-scanner.ts # proto 契约扫描（buf）
├─ query.ts # 查询命令（沿用旧版，扩展新表）
└─ arch.db # 统一元数据库
```
**Go 扫描方案**：用 `tree-sitter-go`（Node.js 绑定）解析 Go AST，提取函数/方法/类型/接口/import。
**Python 扫描方案**：用 `tree-sitter-python` 提取函数/类/方法/import。
#### 6.4.3 查询命令扩展
```bash
# 沿用旧命令
npm run arch:scan # 全量扫描
npm run arch:query -- sql "" # 自定义 SQL
npm run arch:query -- module # 模块依赖
npm run arch:query -- violations # 架构违规
# 新增命令
npm run arch:query -- service # 服务级依赖
npm run arch:query -- contracts # proto 契约清单
npm run arch:query -- breaking-changes # 契约 breaking change 检测
npm run arch:query -- events # Kafka 事件清单
npm run arch:query -- event-flow # 事件生产者→消费者链路
npm run arch:query -- cross-lang-deps # 跨语言调用（如 Gateway 调 TS 服务）
```
#### 6.4.4 架构违规检测规则（多语言版）
| 违规类型 | 检测方式 | 适用语言 |
| -------------------------------- | ------------------------------------ | ----------------------------------- |
| 服务间直连数据库（绕过对方 API） | 扫描 import + DB 连接配置 | TS/Go/Python |
| 契约 breaking change 未升级版本 | buf breaking + arch.db 比对 | proto |
| 事件 schema 不一致 | proto 扫描 vs 事件生产者/消费者 | proto |
| 跨服务循环依赖 | 服务依赖图环检测 | 全部 |
| 单文件超长 | 行数统计 | TS≤500/800/1000, Go≤800, Python≤800 |
| Server/Handler 缺权限校验 | 扫描 requirePermission 装饰器/中间件 | TS/Go/Python |
| 硬编码密钥/密码 | 正则扫描 | 全部 |
| 跨语言类型不一致 | proto 生成类型 vs 实际使用 | TS/Go/Python |
### 6.5 project_rules.md（多语言版）
移植旧 project_rules.md，扩展多语言/微服务规则：
```
project_rules.md
├─ 1. 架构图优先规则（arch.db 先行）
├─ 2. arch.db 元数据库规则（多语言扫描）
├─ 3. 编码规范（TS/Go/Python 分节）
│ ├─ 3.1 代码质量规则（行数/错误处理/日志）
│ ├─ 3.2 架构分层规则（服务边界/gRPC 契约）
│ ├─ 3.3 服务标准结构（黄金模板复制）
│ ├─ 3.4 TypeScript 规则（沿用旧版）
│ ├─ 3.5 Go 规则（新增：error 处理/接口设计/包结构）
│ ├─ 3.6 Python 规则（新增：类型注解/FastAPI 规范）
│ ├─ 3.7 命名规范（多语言）
│ ├─ 3.8 契约规范（proto 先行/buf 校验）
│ └─ 3.9 安全规范（JWT/DataScope/SQL 注入）
├─ 4. 提交规范（Conventional Commits + 多语言 scope）
├─ 5. 问题记录规则（known-issues 索引式）
└─ 6. AI 工作强制流程（多语言版上下文加载/执行/经验沉淀）
```
### 6.6 known-issues.md（多语言索引）
沿用旧项目索引式格式，扩展多语言/微服务分区：
```
known-issues.md
├─ 全局经验
│ ├─ Next.js 配置与运行时（旧项目迁移）
│ ├─ Go 服务开发（新增）
│ ├─ Python 服务开发（新增）
│ ├─ Docker Compose 本地基础设施（新增）
│ ├─ Kafka 事件总线（新增）
│ ├─ gRPC 契约管理（新增）
│ └─ 多语言 arch.db 扫描（新增）
├─ 模块经验
│ ├─ api-gateway（Go）
│ ├─ iam（TS）
│ ├─ classes（TS，黄金模板）
│ ├─ ...
└─ 工作经验日志（50 条上限，按时间倒序）
```
### 6.7 文档同步强制流程（与旧项目等价）
**改码必同步图**（强制）：
1. 修改源码后运行 `npm run arch:scan` 更新 arch.db
2. 若架构设计意图变化，更新 004
3. 若服务接口/事件变化，更新模块 README 第 5 章
4. 若发现新"场景→技术"映射，更新 known-issues
5. 若新加横切关注点模式，回写黄金模板
**需要同步的场景**（扩展多语言）：
- 新增/删除/重命名导出函数、组件、Hook、类型（TS/Go/Python）
- 修改函数签名（参数、返回类型）
- 修改权限点或角色-权限映射
- 新增/删除数据库表
- 新增/删除 gRPC 方法或 proto message
- 新增/删除 Kafka topic 或事件类型
- 修改服务间依赖关系
- 新增服务
### 6.8 P1 文档交付清单
P1 阶段必须交付的文档（黄金模板范本）：
| 文档 | 状态 | 来源 |
| ------------------------------------------------------------------------------- | --------------------- | --------------------- |
| `004_architecture_impact_map.md` | 多服务版骨架（14 章） | 旧 004 扩展 |
| `0010_architecture.md` | 迁移自旧仓库 | 直接复制 |
| `docs/modules/api-gateway/README.md` | 8 章完整 | 黄金范本（Go） |
| `docs/modules/classes/README.md` | 8 章完整 | 黄金范本（TS） |
| `docs/standards/coding-standards.md` | 多语言版 | 旧规范扩展 |
| `docs/standards/git-workflow.md` | 分支策略 + commitlint | 旧 CONTRIBUTING 扩展 |
| `docs/troubleshooting/known-issues.md` | 索引式骨架 | 旧模板扩展 |
| `project_rules.md` | 多语言版 | 旧 project_rules 扩展 |
| `arch.db` | 多语言扫描器 | 旧 arch-scan 扩展 |
| `LICENSE` / `CHANGELOG.md` / `CONTRIBUTING.md` / `SECURITY.md` / `.env.example` | 大仓标配 | 旧项目已有 |
---
## 7. 技术风险与缓解策略
### 7.1 人员风险
#### R1: 1 人瓶颈（高风险）
**表现**：单点故障（生病/倦怠/上下文丢失），18 个月周期长，知识遗忘风险。
**缓解**：
- **文档即记忆**：004 + 模块 README + known-issues 工作日志必须实时更新，AI 可从文档恢复上下文
- **小里程碑**：每 2-4 周一个可验证交付物，避免长周期失焦
- **黄金模板**：复制而非重写，降低单服务工作量
- **arch.db 即上下文**：每次开工先 `arch:scan` + `arch:query`，AI 快速恢复全局认知
- **分支策略**：feature 分支短生命周期（< 1 周），避免长期分支合并冲突
#### R2: AI 生成质量（中风险）
**表现**：多语言生成质量参差（Go/Python 可能弱于 TS），跨语言类型不一致，幻觉 API。
**缓解**：
- **契约先行强制**：proto 定义唯一源，AI 生成代码必须基于 proto，CI 用 buf breaking 拦截
- **黄金模板约束**：AI 复制模板而非自由生成，降低幻觉空间
- **每语言单独验证**：Go/Python 代码生成后必须 `go vet` / `ruff` + 单元测试通过
- **arch:scan 验证**：每次 AI 生成后跑 `arch:query -- violations`，拦截架构违规
- **小步生成**：单次 AI 生成不超过一个服务的一个模块，便于 review
### 7.2 技术风险
#### R3: 多语言工具链复杂度（高风险）
**表现**：3 语言 × 3 套工具链 × 3 套 CI，维护成本 3 倍。
**缓解**：
- **统一 monorepo 工具链**：pnpm workspace 统一入口，`package.json` scripts 封装多语言命令
- **共享 arch.db**：统一元数据，避免三套文档体系
- **共享契约**：proto 生成三端代码，类型一致性由工具保证
- **CI 模板复用**：三语言 CI workflow 模板化，仅改服务名
- **Dockerfile 模板**：多阶段构建模板复用
- **限制依赖**：每语言限制框架数量（TS=NestJS+Drizzle，Go=Gin+GORM，Python=FastAPI+SQLAlchemy）
#### R4: 分布式系统复杂度（高风险）
**表现**：服务发现/负载均衡/分布式事务/链路追踪/熔断降级，1 人难以驾驭。
**缓解**：
- **P1-P5 单机 Docker**：不引入 K8s，docker-compose 内网信任，简化网络
- **P6 才上 Service Mesh**：Istio 接管网络治理，业务代码无感知
- **最终一致性优先**：Outbox + 事件，避免分布式事务（2PC/Saga）
- **双轨读降级**：实时查主库 + 聚合查宽表，CH 故障降级查 MySQL
- **P3 Outbox 试点**：仅 CoreEdu 用 Outbox，验证后再推广
- **可观测先行**：P1 即注入 OTel SDK，问题可追溯
#### R5: 契约管理（中风险）
**表现**：proto breaking change 导致消费端故障，版本管理混乱。
**缓解**：
- **buf breaking CI 强制**：PR 阶段检测 breaking change，必须升版本号
- **proto 版本化**：包名带版本（`classes.v1`、`classes.v2`），新旧版本共存
- **契约测试（Pact）**：消费端驱动，黄金模板即包含 Pact 配置
- **单一契约源**：所有服务间通信必须经 proto，禁止 REST/gRPC 混用
- **事件 schema 版本化**：Kafka 事件带 `schema_version` 字段，消费端按版本处理
#### R6: 数据一致性（中风险）
**表现**：Outbox relay 故障导致事件丢失；CDC 延迟导致宽表数据滞后；Neo4j 与 MySQL 双写不一致。
**缓解**：
- **Outbox relay 高可用**：P3 单实例够用，P6 多实例 + 幂等消费
- **CDC 延迟监控**：Debezium 暴露 lag metrics，超阈值告警
- **双写避免**：Neo4j/ES 不直接双写，由消费 Kafka 事件同步，天然最终一致
- **幂等消费**：所有事件消费者必须幂等（基于 event_id 去重）
- **对账机制**：P6 引入定期对账任务（MySQL 主库 vs CH 宽表 vs Neo4j）
### 7.3 范围风险
#### R7: 范围蔓延（高风险）
**表现**：每阶段"顺便加一点"，18 个月变 24 个月。
**缓解**：
- **阶段退出标准硬约束**：每阶段退出标准必须全部满足才进入下一阶段
- **不做清单**：每阶段明确定义"不做"项，记入 spec
- **tech-debt 兜底**：发现的新需求记入 `roadmap/tech-debt.md`，不在当前阶段实现
- **月度回顾**：每月对照 spec 检查进度，偏离超 20% 触发范围调整决策
- **YAGNI 原则**：未明确要求的功能不做，即便"看起来很简单"
#### R8: 黄金模板过重（中风险）
**表现**：P1 黄金模板包含全部横切关注点，可能导致 P1 膨胀到 4-5 个月。
**缓解**：
- **P1 范围严控**：classes 服务仅 CRUD，不实现复杂业务逻辑
- **横切关注点最小实现**：P1 仅实现基础版（如限流仅固定窗口，P6 才换令牌桶）
- **可复制性验证**：P1 退出标准含"30 分钟复制跑起新服务"，若不达标先优化模板再进 P2
- **回写而非前置**：阶段特有模式（Outbox/CDC/长连接）在对应阶段实现后回写，P1 不预实现
### 7.4 基础设施风险
#### R9: Docker 本地资源（中风险）
**表现**：全量 docker-compose（MySQL+Redis+Kafka+Zookeeper+Debezium+CH+Neo4j+ES+Temporal+Consul）内存占用可能超 16GB。
**缓解**：
- **最小开发集**：`docker-compose.minimal.yml` 仅 MySQL+Redis，日常开发用
- **按阶段启服务**：P1 仅起 MySQL+Redis；P3 加 Kafka+Zookeeper；P4 加 Debezium+CH+Neo4j；P5 加 ES；P6 加 Consul+Istio
- **资源限制**：docker-compose 每服务配置 `mem_limit`，避免单服务吃满内存
- **云资源备选**：若本地跑不动，P4 起可考虑云上 dev 环境（腾讯云/阿里云 K8s dev 集群）
#### R10: P6 生产部署（高风险）
**表现**：P1-P5 本地 Docker 跑通，P6 上 K8s + Service Mesh 可能大量适配问题。
**缓解**：
- **P1 起容器化**：每服务从 P1 即 Dockerfile + docker-compose，避免 P6 重新容器化
- **P3 起健康检查**：每服务暴露 `/health` + `/metrics`，K8s 探针就绪
- **P5 起无状态化**：服务状态外置（Redis/MySQL），为 K8s 扩缩容准备
- **P6 前置验证**：P5 末尾用 minikube 或 k3s 本地验证 K8s 清单，提前暴露问题
- **P6 范围可裁剪**：若 P6 时间紧张，Service Mesh 可降级为 K8s 原生 Service + Ingress，Istio 延后
### 7.5 风险-阶段矩阵
| 风险 | P1 | P2 | P3 | P4 | P5 | P6 |
| -------------- | --- | --- | --- | --- | --- | --- |
| R1 1人瓶颈 | ◐ | ◐ | ● | ● | ● | ● |
| R2 AI 质量 | ◐ | ◐ | ◐ | ◐ | ◐ | ◐ |
| R3 多语言 | ● | ◐ | ◐ | ● | ● | ◐ |
| R4 分布式 | ○ | ○ | ● | ● | ● | ● |
| R5 契约 | ● | ◐ | ◐ | ◐ | ◐ | ◐ |
| R6 一致性 | ○ | ○ | ● | ● | ◐ | ◐ |
| R7 范围 | ◐ | ◐ | ● | ● | ● | ◐ |
| R8 模板过重 | ● | ○ | ○ | ○ | ○ | ○ |
| R9 Docker 资源 | ◐ | ◐ | ◐ | ● | ● | ● |
| R10 生产部署 | ○ | ○ | ○ | ○ | ◐ | ● |
图例：● 高风险 ◐ 中风险 ○ 低风险
**P1 重点防控**：R8（模板过重）、R3（多语言工具链）、R5（契约管理）
**P3-P5 重点防控**：R4（分布式复杂度）、R6（一致性）、R7（范围蔓延）
**P6 重点防控**：R10（生产部署）、R1（1人瓶颈累积）
### 7.6 风险监控机制
- **每阶段开始前**：对照风险-阶段矩阵，识别本阶段高风险项，制定缓解动作
- **每阶段末尾**：known-issues 工作日志记录新发现的风险与缓解经验
- **月度**：检查 R7（范围蔓延），对照 spec 进度
- **季度**：全面风险回顾，必要时调整 spec 与路线图
---
## 8. 验收标准
### 8.1 整体验收（P6 末尾）
| 维度 | 验收项 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 架构完整度 | 0010 蓝图全部组件落地（6 领域微服务[IAM/CoreEdu/Content/DataAna/Msg/AI] + 2 基础设施服务[API Gateway/Push Gateway] + 3 BFF + 4 微前端 + 5 存储 + 事件总线 + Service Mesh） |
| 文档体系 | 004 多服务版 + 8 服务 README（含 outbox-relay）+ 多语言 project_rules + arch.db 多语言扫描 + known-issues |
| 可观测性 | 全链路 trace + Grafana 仪表盘 + Loki 日志查询 |
| 安全 | RS256 JWT + DataScope 6 级 + mTLS + 限流熔断 |
| 测试 | 单元 + 集成 + 契约 + E2E 四类，覆盖率达标 |
| 可用性 | 单服务宕机不影响核心链路，99.9% 可用性压测通过 |
| 可扩展性 | 单服务可独立扩缩容（HPA 生效） |
### 8.2 各阶段验收
见第 3 节（P1）与第 4 节（P2-P6）各阶段退出标准。
---
## 9. 不在本次范围
- **数据迁移**：旧 Next.js 项目数据迁移到新系统（通过 CDC/ETL，独立项目）
- **旧系统下线**：新系统上线后旧系统的退役计划（独立决策）
- **生产环境部署**：P6 仅生产硬化与 K8s 清单，实际部署目标环境（云/自建）未定
- **用户培训**：新系统的用户培训与文档（独立项目）
- **性能压测**：仅 P6 做 99.9% 可用性基础压测，深度性能调优独立项目
- **安全审计**：仅实现安全架构，第三方安全审计独立项目
---
## 10. 实施约束
- 每阶段开始前 `git commit` 一次快照（用户要求"实施前提交备份"）
- 每阶段完成后 `git commit` + `git tag`
- 每阶段必须通过 CI（lint + test + build + arch:scan）
- 每阶段完成后更新 `docs/troubleshooting/known-issues.md` 工作经验日志
- 每阶段若架构意图变化，同步更新 `004_architecture_impact_map.md`
- 全程不改 `project_rules.md` 除非有新的强制规则
- 发现新需求一律记入 `roadmap/tech-debt.md`，不在当前阶段实现