Edu/docs/superpowers/specs/2026-07-07-enterprise-microservices-architecture-upgrade-design.md

# 企业级微服务架构升级设计

> 日期: 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<br/>Teacher/Student/Parent/Admin<br/>Module Federation]
    end

    subgraph Edge["边缘与网关层"]
        GW[API Gateway<br/>Go: 鉴权/限流/路由]
        BFF_T[Teacher BFF<br/>TS: GraphQL+DataLoader]
        BFF_S[Student BFF<br/>TS: GraphQL]
        BFF_P[Parent BFF<br/>TS: GraphQL]
    end

    subgraph Services["领域微服务层"]
        IAM[IAM 服务<br/>TS/NestJS]
        CoreEdu[CoreEdu 服务<br/>TS/NestJS]
        Content[Content 服务<br/>TS/NestJS+Neo4j]
        DataAna[DataAna 服务<br/>Python: 学情分析]
        Msg[Msg 服务<br/>TS/NestJS]
        AI[AI 网关<br/>Python: Prompt 管理]
        Push[Push Gateway<br/>Go: 长连接]
    end

    subgraph Bus["事件总线"]
        Kafka[(Kafka<br/>领域事件+CDC)]
    end

    subgraph Storage["异构存储"]
        MySQL[(MySQL/TiDB<br/>关系型主库)]
        Redis[(Redis Cluster<br/>缓存/锁/PubSub)]
        CH[(ClickHouse<br/>分析宽表)]
        Neo4j[(Neo4j<br/>知识图谱)]
        ES[(Elasticsearch<br/>全文检索)]
    end

    subgraph Infra["基础设施"]
        CDC[Debezium CDC]
        Temporal[Temporal<br/>工作流编排]
        Conf[配置中心<br/>Consul/Nacos]
        Mesh[Service Mesh<br/>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<br/>年级主任]
        R6[teaching_head<br/>教研组长]
        R7[...未来角色]
    end

    subgraph Perm["权限层（resource:action）"]
        P1[exam:create]
        P2[exam:read]
        P3[...N 个权限点]
    end

    subgraph View["视口层（UI 可见性配置）"]
        V1[L1 导航<br/>侧边栏菜单项]
        V2[L2 路由<br/>可访问路由]
        V3[L3 组件<br/>页面内组件可见性]
        V4[L4 数据<br/>DataScope 行级过滤]
    end

    Role -.->|"多对多<br/>RolePermission 表"| Perm
    Role -.->|"多对多<br/>RoleViewport 表"| View
    Perm -.->|"权限推导视口<br/>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<br/>400]
        NotFound[NotFoundError<br/>404]
        PermErr[PermissionDeniedError<br/>403]
        Conflict[ConflictError<br/>409]
        BizErr[BusinessError<br/>400]
    end

    subgraph Infra["基础设施错误（非预期）"]
        DBErr[DatabaseError<br/>500]
        UpstreamErr[UpstreamServiceError<br/>502]
        TimeoutErr[TimeoutError<br/>504]
        InternalErr[InternalError<br/>500]
    end

    subgraph Contract["契约错误"]
        ProtoErr[ContractViolationError<br/>500]
        SerialErr[SerializationError<br/>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<T> {
  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<br/>关键用户旅程]
    end
    subgraph Integ["集成测试（30%）"]
        Contract[契约测试<br/>Pact + proto]
        Service[服务集成<br/>Testcontainers]
    end
    subgraph Unit["单元测试（60%）"]
        Domain[领域逻辑<br/>纯函数]
        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<br/>多服务版架构设计意图]
        Doc0010[0010_architecture.md<br/>理想蓝图（迁移）]
    end

    subgraph Code["代码结构文档（arch.db）"]
        ArchDB[arch.db<br/>多语言代码元数据]
        ArchScan[arch-scan<br/>TS+Go+Python 扫描器]
        ArchQuery[arch-query<br/>违规检测/依赖查询]
    end

    subgraph Module["模块文档（服务级）"]
        ModuleReadme[docs/modules/{service}/README.md<br/>8 章模板]
    end

    subgraph Experience["经验文档"]
        KnownIssues[known-issues.md<br/>索引式场景→技术映射]
        WorkLog[工作经验日志<br/>50 条上限]
    end

    subgraph Standards["规范文档"]
        Coding[coding-standards.md<br/>多语言编码规范]
        GitWF[git-workflow.md<br/>分支/提交规范]
        ProjectRules[project_rules.md<br/>AI 工作强制流程]
    end

    subgraph Planning["规划文档"]
        Roadmap[roadmap/<br/>tech-debt/decoupling/pending]
        Specs[superpowers/specs/<br/>设计 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>"              # 自定义 SQL
npm run arch:query -- module <module>          # 模块依赖
npm run arch:query -- violations               # 架构违规

# 新增命令
npm run arch:query -- service <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 <event>       # 事件生产者→消费者链路
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`，不在当前阶段实现