From 313bae87bf039209ad85bddc6fb85b235f98f4ee Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Tue, 7 Jul 2026 21:34:15 +0800 Subject: [PATCH] docs(spec): add enterprise microservices architecture upgrade design --- ...croservices-architecture-upgrade-design.md | 1289 +++++++++++++++++ 1 file changed, 1289 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-07-enterprise-microservices-architecture-upgrade-design.md diff --git a/docs/superpowers/specs/2026-07-07-enterprise-microservices-architecture-upgrade-design.md b/docs/superpowers/specs/2026-07-07-enterprise-microservices-architecture-upgrade-design.md new file mode 100644 index 0000000..b5f9e26 --- /dev/null +++ b/docs/superpowers/specs/2026-07-07-enterprise-microservices-architecture-upgrade-design.md @@ -0,0 +1,1289 @@ +# 企业级微服务架构升级设计 + +> 日期: 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`，不在当前阶段实现