Edu/docs/architecture/roadmap/integration-test-phase.md

集成测试与部署验证阶段（P7）

日期：2026-07-10 前置条件：所有模块 P2-P6 代码完成，lint/typecheck/go vet/ruff 全通过，ARB-001~022 全部已裁决 目标：从"代码完成"到"系统可用"，验证端到端功能链路

---

1. 阶段概述

15 AI 全并行开发模式下，各模块独立编码，使用 mock 桩进行本地验证。本阶段目标是将所有模块集成到真实基础设施中，验证端到端功能链路。

前置状态

检查项	状态
lint（pnpm run lint）	✅ 全通过
typecheck（pnpm run typecheck）	✅ 16 包/服务全通过
go vet（api-gateway + push-gateway）	✅ 全通过
ruff check（ai + data-ana）	✅ 全通过
proto 契约（buf lint）	✅ 通过
仲裁（ARB-001~022）	✅ 95 条全部已裁决
packages/contracts	✅ 已建立（ADMIN_* 权限点）

当前差距

• 各模块使用 mock 桩，尚未在真实 gRPC/MySQL/Redis/Kafka 环境中验证
• 服务间 gRPC 调用链路未实际跑通
• 前端与 BFF 的 GraphQL 通信未端到端验证
• Docker Compose 全量部署未验证
• 健康检查端点（/healthz + /readyz）未在容器环境验证

---

2. 阶段任务分解

批次 0：基础设施就绪

目标：确保 Docker Compose 全量基础设施可启动。

任务	验证标准
MySQL + Redis + Kafka + Neo4j + ClickHouse + ES 容器健康	docker compose up -d 全量容器 healthy
数据库 schema 初始化脚本	各服务 schema 迁移脚本可执行
Kafka topic 创建脚本	全部 topic（ARB-013 命名）可创建
Debezium CDC connector 配置	MySQL → Kafka CDC 链路通畅

批次 1：后端服务启动

目标：每个后端服务能在 Docker 环境中启动并通过健康检查。

服务	端口	验证标准
api-gateway（Go）	8080	/healthz 返回 200
push-gateway（Go）	8081	/healthz 返回 200
iam（TS/gRPC 50052）	3001	/healthz + gRPC 可连接
classes（TS）	3002	/healthz 返回 200
core-edu（TS/gRPC 50053）	3004	/healthz + gRPC 可连接
content（TS/gRPC 50054）	3005	/healthz + gRPC 可连接
msg（TS/gRPC 50056）	3006	/healthz + gRPC 可连接
data-ana（Python/gRPC 50055）	3007	/healthz + gRPC 可连接
ai（Python/gRPC 50058）	3008	/healthz + gRPC 可连接

批次 2：BFF 层启动

目标：3 个 BFF 能启动并连接下游 gRPC 服务。

服务	端口	验证标准
teacher-bff（GraphQL）	3003	/graphql Playground 可访问
student-bff（GraphQL）	3009	/graphql Playground 可访问
parent-bff（GraphQL）	3010	/graphql Playground 可访问

批次 3：前端启动

目标：4 个前端能启动并连接对应 BFF。

应用	端口	验证标准
teacher-portal	4000	登录页可访问
student-portal	4001	登录页可访问
parent-portal	4002	登录页可访问
admin-portal	4003	登录页可访问

批次 4：端到端功能验证

目标：核心业务链路端到端跑通。

链路	涉及服务	验证标准
教师登录	teacher-portal → api-gateway → iam	获取 JWT → 侧边栏按角色渲染
创建考试	teacher-portal → teacher-bff → core-edu	考试落库 → Outbox 事件 → Kafka
学生作答	student-portal → student-bff → core-edu	提交落库 → 事件发布
教师批改	teacher-portal → teacher-bff → core-edu	成绩落库 → GradeReleased 事件
学情分析	student-portal → student-bff → data-ana	ClickHouse 宽表查询 < 5s
知识图谱	teacher-portal → teacher-bff → content	Neo4j 查询秒级返回
消息推送	msg → push-gateway → WebSocket	在线学生实时收到通知
AI 辅助	teacher-portal → teacher-bff → ai	流式 SSE 正常返回

批次 5：可观测性验证

目标：三支柱（日志 + 指标 + 链路）在集成环境中可用。

检查项	验证标准
Prometheus 抓取	所有服务 /metrics 端点可抓取
Grafana 面板	核心指标面板可查看
全链路 trace	一个请求的 trace 可在 Jaeger 追踪全链路
结构化日志	所有服务日志 JSON 格式输出到 stdout

---

3. 执行策略

并行度

批次 0（基础设施） → 批次 1（后端） → 批次 2（BFF） → 批次 3（前端） → 批次 4（E2E） → 批次 5（可观测性）
     |                  |                  |                  |                  |                  |
     独立              9 服务并行         3 BFF 并行         4 前端并行         8 链路并行         独立

问题修复策略

• 发现的问题记录到 docs/troubleshooting/known-issues.md 对应模块分区
• 跨模块问题通过 docs/architecture/issues/objections/[模块名]_issue.md 提请仲裁
• coord 负责仲裁，开发 AI 在各自分支修复

风险点

风险	影响	缓解策略
gRPC proto 生成代码版本不一致	服务间调用失败	批次 1 统一 buf generate
MySQL schema 冲突	数据库初始化失败	批次 0 逐服务验证 schema
Kafka topic 命名不一致	消费者收不到事件	对照 ARB-013 统一检查
端口冲突	服务无法启动	对照 port-allocation.md 检查
前端 MF 配置不匹配	微前端加载失败	批次 3 验证 MF config

---

4. 验收标准

验收项	标准
Docker Compose 全量启动	所有容器 healthy
核心链路 E2E	8 条核心链路全部跑通
健康检查	所有服务 /healthz + /readyz 返回 200
可观测性	Prometheus + Grafana + Jaeger 数据可见
错误处理	ActionState 信封格式一致
权限校验	未授权请求返回 401/403

---

5. 退出标准

• 全量 Docker Compose 启动成功
• 8 条核心业务链路端到端跑通
• 三支柱可观测性可用
• 无阻塞性 bug
• 打 tag v0.6.0-integration