docs(docs): 更新 issue 仲裁状态 + 生成集成测试阶段规划
- 14 个 issue.md 状态字段更新为"已裁决" - 对应 coord.md ARB-001~022 章节 - 共 104 处状态字段更新 - 新增 integration-test-phase.md - 集成测试与部署验证阶段(P7)规划 - 6 个批次任务分解 - 8 条核心 E2E 链路定义 - 验收标准和退出标准 Coord-AI
This commit is contained in:
SpecialX
160
docs/architecture/roadmap/integration-test-phase.md
Normal file
160
docs/architecture/roadmap/integration-test-phase.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 集成测试与部署验证阶段（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`
|
||||
Reference in New Issue
Block a user