# 集成测试与部署验证阶段（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`