# api-gateway 下一步工作与上下游依赖（Next Steps v2）

> 模块：api-gateway（L3 网关层，Go/Gin，端口 8080）
> 负责人：ai01
> 更新日期：2026-07-14（v2：admin P0 + BFF 路径重写 + Docker 修复 + 本地验证通过）
> 关联文档：
>
> - [nextstep.md v1](./nextstep.md)
> - [api-gateway_contract.md](../../../docs/architecture/issues/contracts/api-gateway_contract.md)
> - [admin-portal_contract.md](../../../docs/architecture/issues/contracts/admin-portal_contract.md) §2.3
> - [student-portal_contract.md](../../../docs/architecture/issues/contracts/student-portal_contract.md) §2.3
> - [parent-bff nextstep-v2.md](../../parent-bff/docs/nextstep-v2.md)（ARB-022 §24.4 ISSUE-003 方案 A）
>
> v2 生成原因：上游 4 个 portal + 3 个 BFF 完成 v2 工作后，重新核查 api-gateway 是否满足全部上下游依赖。

---

## 1. v2 核查总结

### 1.1 核查范围

并行核查了 7 个上游模块的 nextstep-v2.md：

| 模块           | 负责人 | 文档位置                                                                                    | v2 对 api-gateway 的要求                         | 核查结果  |
| -------------- | ------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------ | --------- |
| admin-portal   | ai16   | [apps/admin-portal/docs/nextstep-v2.md](../../../apps/admin-portal/docs/nextstep-v2.md)     | `/api/admin/graphql` 路由 + AdminRoleMiddleware  | ✅ 已完成 |
| teacher-portal | ai13   | [apps/teacher-portal/nextstep-v2.md](../../../apps/teacher-portal/nextstep-v2.md)           | `/api/v1/teacher/*` 反向代理                     | ✅ 已完成 |
| student-portal | ai14   | [apps/student-portal/docs/nextstep-v2.md](../../../apps/student-portal/docs/nextstep-v2.md) | `/api/v1/student/*` 反向代理 + 路径重写          | ✅ 已完成 |
| parent-portal  | ai15   | [apps/parent-portal/docs/nextstep-v2.md](../../../apps/parent-portal/docs/nextstep-v2.md)   | Docker 构建修复                                  | ✅ 已完成 |
| teacher-bff    | ai03   | [services/teacher-bff/docs/nextstep-v2.md](../../teacher-bff/docs/nextstep-v2.md)           | `/api/v1/teacher/*` + `/api/admin/graphql` 代理  | ✅ 已完成 |
| student-bff    | ai04   | [services/student-bff/docs/nextstep-v2.md](../../student-bff/docs/nextstep-v2.md)           | `/api/v1/student/*` 路径重写剥离 /api/v1/student | ✅ 已完成 |
| parent-bff     | ai04   | [services/parent-bff/docs/nextstep-v2.md](../../parent-bff/docs/nextstep-v2.md)             | `/api/v1/parent/*` 路径重写剥离 /api/v1/parent   | ✅ 已完成 |

### 1.2 v2 关键发现

**admin-portal v2 核查发现**：v1 声称已完成的工作（admin 路由、AdminRoleMiddleware、NewProxyRewrite、registerBffProxy）在代码中**实际缺失**（可能被回滚）。v2 重新实现并验证通过。

**parent-bff v2 核查发现**：parent-bff GraphQL 端点路径采用 ARB-022 §24.4 ISSUE-003 方案 A（双 /v1 前缀），即 `/api/v1/parent/v1/graphql` → 剥离 `/api/v1/parent` → `/v1/graphql`。api-gateway 的 `registerBffProxy` 已支持此路径重写。

### 1.3 本地 Docker 验证结果（2026-07-14 v2）

测试环境：本地 Docker（edu/api-gateway:test 容器，DEV_MODE=true，端口 18080→8080）

```
镜像：edu/api-gateway:test（golang:1.25-alpine builder + alpine:3.20 runner）
容器：edu-api-gateway-test（DEV_MODE=true, PORT=8080）
```

| 验证项                                | 状态 | 说明                                                                            |
| ------------------------------------- | ---- | ------------------------------------------------------------------------------- |
| Docker 镜像构建                       | ✅   | go.work 精简版（仅 api-gateway + shared-go）+ GOPROXY=https://goproxy.cn,direct |
| 容器启动                              | ✅   | 端口 8080，DevMode，非 root 用户                                                |
| `/healthz` 端点                       | ✅   | 200 `{"status":"ok"}`                                                           |
| `/readyz` 端点                        | ✅   | 503（下游 iam/teacher-bff 等未启动，正确报告 degraded/unhealthy）               |
| `/metrics` 端点                       | ✅   | 200 + Prometheus 格式（含 7 个业务指标）                                        |
| `/api/admin/graphql` 无 auth          | ✅   | 401 `GW_UNAUTHORIZED`（AuthMiddleware 拦截）                                    |
| `/api/admin/graphql` dev-token        | ✅   | 502（路由存在，admin 角色通过，下游 teacher-bff 不可达）                        |
| `/api/v1/teacher/graphql` dev-token   | ✅   | 502（路由存在，BFF 路径重写 /api/v1/teacher/graphql → /graphql，下游不可达）    |
| `/api/v1/parent/v1/graphql` dev-token | ✅   | 502（路由存在，路径重写 /api/v1/parent/v1/graphql → /v1/graphql，下游不可达）   |
| `go vet ./...`                        | ✅   | 零错误                                                                          |
| `go build ./...`                      | ✅   | 零错误                                                                          |
| `go test ./...`                       | ✅   | middleware + proxy 测试全部通过（13 个测试）                                    |

---

## 2. v2 完成项详情

### 2.1 admin-portal P0 阻塞项（重新实现）

**来源**：[admin-portal nextstep-v2.md](../../../apps/admin-portal/docs/nextstep-v2.md) §2.1

| #   | 工作项                         | 状态 | 实现详情                                                                                                         |
| --- | ------------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------- |
| 1   | 新增 `/api/admin/graphql` 路由 | ✅   | [main.go](../main.go) L110-129 新增 `/api/admin` 路由组，POST /api/admin/graphql 代理到 teacher-bff:3003/graphql |
| 2   | admin 角色强制校验中间件       | ✅   | [admin_role.go](../internal/middleware/admin_role.go) `AdminRoleMiddleware`，校验 x-user-roles 含 admin 角色     |
| 3   | 路径对齐契约 §2.3              | ✅   | /api/admin/graphql 为唯一入口，路径重写 /api/admin/graphql → /graphql（teacher-bff @Controller("graphql")）      |
| 4   | AdminRoleMiddleware 单元测试   | ✅   | [admin_role_test.go](../internal/middleware/admin_role_test.go) 8 个测试（含角色列表/空值/大小写）               |

**中间件链**：熔断（teacher-bff-admin）→ JWT 鉴权 → AdminRoleMiddleware → 指标 → 反向代理

### 2.2 BFF 路由路径重写修复（重新实现）

**来源**：[student-bff nextstep-v2.md](../../student-bff/docs/nextstep-v2.md) §3.1、[parent-bff nextstep-v2.md](../../parent-bff/docs/nextstep-v2.md) §3.1

**问题**：teacher-bff / student-bff 的 GraphQL 端点在 `/graphql`（`@Controller("graphql")`），parent-bff 在 `/v1/graphql`（ARB-022 §24.4 ISSUE-003 方案 A）。原代理仅剥离 `/api` 前缀，导致下游收到 `/v1/teacher/graphql` 而非 `/graphql`，返回 404。

**修复**：新增 `registerBffProxy` 函数，对 BFF 路由（teacher/student/parent）剥离 `/api/v1/{bff}` 前缀，仅转发剩余路径到下游。

| 路由                        | 路径重写               | 下游接收路径  | 下游服务         |
| --------------------------- | ---------------------- | ------------- | ---------------- |
| `/api/v1/teacher/graphql`   | 剥离 `/api/v1/teacher` | `/graphql`    | teacher-bff:3003 |
| `/api/v1/student/graphql`   | 剥离 `/api/v1/student` | `/graphql`    | student-bff:3009 |
| `/api/v1/parent/v1/graphql` | 剥离 `/api/v1/parent`  | `/v1/graphql` | parent-bff:3010  |
| `/api/admin/graphql`        | 剥离 `/api/admin`      | `/graphql`    | teacher-bff:3003 |

**关键文件**：

- [main.go](../main.go) L180-198 `registerBffProxy` 函数
- [proxy.go](../internal/proxy/proxy.go) L31-49 `NewProxyRewrite` 函数
- [proxy_rewrite_test.go](../internal/proxy/proxy_rewrite_test.go) 5 个测试（路径剥离/查询参数/无效URL/请求体/请求头）

### 2.3 Dockerfile 修复

**问题**：

1. go.work 引用了 push-gateway，但 Docker 构建上下文仅含 api-gateway + shared-go，导致 `go mod download` 失败
2. 容器内无法访问 proxy.golang.org，需使用国内代理

**修复**：

- 生成精简版 go.work（仅 api-gateway + shared-go）
- 设置 `GOPROXY=https://goproxy.cn,direct` + `GOSUMDB=off`
- 构建上下文改为仓库根目录（访问 packages/shared-go）

**关键文件**：[Dockerfile](../Dockerfile)

---

## 3. 上游依赖（api-gateway 依赖谁）

### 3.1 iam 服务（ai06 负责）— P0

| #   | 依赖项                             | 用途                                      | 状态 |
| --- | ---------------------------------- | ----------------------------------------- | ---- |
| 1   | `GET /.well-known/jwks.json` :3002 | RS256 公钥集（JWT 验签）                  | ✅   |
| 2   | `POST /v1/iam/login` :3002         | 用户登录（portal 登录流程经 api-gateway） | ✅   |
| 3   | `POST /v1/iam/register` :3002      | 用户注册                                  | ✅   |
| 4   | `POST /v1/iam/refresh` :3002       | Token 刷新                                | ✅   |
| 5   | `/healthz` 端点                    | /readyz 下游健康检查                      | ✅   |

**环境变量**：`IAM_SERVICE_URL=http://iam:3002`、`IAM_JWKS_URL=http://iam:3002/v1/iam/.well-known/jwks.json`

### 3.2 teacher-bff 服务（ai03 负责）— P0

| #   | 依赖项                | 用途                                      | 状态 |
| --- | --------------------- | ----------------------------------------- | ---- |
| 1   | `POST /graphql` :3003 | teacher-portal GraphQL 代理目标           | ✅   |
| 2   | `POST /graphql` :3003 | admin-portal GraphQL 代理目标（admin 域） | ✅   |
| 3   | `/healthz` 端点       | /readyz 下游健康检查                      | ✅   |

**环境变量**：`TEACHER_BFF_URL=http://teacher-bff:3003`

### 3.3 student-bff 服务（ai04 负责）— P0

| #   | 依赖项                | 用途                            | 状态 |
| --- | --------------------- | ------------------------------- | ---- |
| 1   | `POST /graphql` :3009 | student-portal GraphQL 代理目标 | ✅   |
| 2   | `/healthz` 端点       | /readyz 下游健康检查            | ✅   |

**环境变量**：`STUDENT_BFF_URL=http://student-bff:3009`

### 3.4 parent-bff 服务（ai04 负责）— P0

| #   | 依赖项                   | 用途                                                             | 状态 |
| --- | ------------------------ | ---------------------------------------------------------------- | ---- |
| 1   | `POST /v1/graphql` :3010 | parent-portal GraphQL 代理目标（ARB-022 §24.4 ISSUE-003 方案 A） | ✅   |
| 2   | `/healthz` 端点          | /readyz 下游健康检查                                             | ✅   |

**环境变量**：`PARENT_BFF_URL=http://parent-bff:3010`

### 3.5 核心业务服务（ai07/08/09/10/11/12 负责）— P1

| 服务     | 端口 | 环境变量               | 用途                          | 状态 |
| -------- | ---- | ---------------------- | ----------------------------- | ---- |
| core-edu | 3004 | `CORE_EDU_SERVICE_URL` | 考试/作业/成绩/班级路由代理   | ✅   |
| content  | 3005 | `CONTENT_SERVICE_URL`  | 教材/章节/知识点/题库路由代理 | ✅   |
| data-ana | 3006 | `DATA_ANA_SERVICE_URL` | 学情诊断/错题本/仪表盘代理    | ✅   |
| msg      | 3007 | `MSG_SERVICE_URL`      | 通知/消息路由代理             | ✅   |
| ai       | 3008 | `AI_SERVICE_URL`       | AI 聊天/生成/优化路由代理     | ✅   |

---

## 4. 下游依赖（谁依赖 api-gateway）

### 4.1 teacher-portal（ai13 负责）— P0

| 能力                         | 配置                                           | 状态 |
| ---------------------------- | ---------------------------------------------- | ---- |
| `/api/v1/teacher/*` 反向代理 | → teacher-bff:3003/*（剥离 /api/v1/teacher）   | ✅   |
| JWT 鉴权 + x-user-* 头注入   | AuthMiddleware 注入 x-user-id/roles/data-scope | ✅   |
| CORS 白名单                  | CORS_ORIGINS 环境变量                          | ✅   |
| 限流（IP 级令牌桶）          | 100 rps，突发 20                               | ✅   |
| 熔断（下游 5xx 触发）        | CircuitBreaker("downstream")                   | ✅   |

### 4.2 student-portal（ai14 负责）— P0

| 能力                         | 配置                                         | 状态 |
| ---------------------------- | -------------------------------------------- | ---- |
| `/api/v1/student/*` 反向代理 | → student-bff:3009/*（剥离 /api/v1/student） | ✅   |
| JWT 鉴权 + x-user-* 头注入   | AuthMiddleware                               | ✅   |

### 4.3 parent-portal（ai15 负责）— P0

| 能力                        | 配置                                       | 状态 |
| --------------------------- | ------------------------------------------ | ---- |
| `/api/v1/parent/*` 反向代理 | → parent-bff:3010/*（剥离 /api/v1/parent） | ✅   |
| JWT 鉴权 + x-user-* 头注入  | AuthMiddleware                             | ✅   |

### 4.4 admin-portal（ai16 负责）— P0

| 能力                          | 配置                                          | 状态 |
| ----------------------------- | --------------------------------------------- | ---- |
| `/api/admin/graphql` 反向代理 | → teacher-bff:3003/graphql（剥离 /api/admin） | ✅   |
| admin 角色强制校验            | AdminRoleMiddleware（x-user-roles 含 admin）  | ✅   |
| JWT 鉴权 + x-user-* 头注入    | AuthMiddleware                                | ✅   |

---

## 5. 完整路由表

### 5.1 公开路由（无需鉴权）

| 方法 | 路径       | 用途               |
| ---- | ---------- | ------------------ |
| GET  | `/healthz` | 存活探针           |
| GET  | `/readyz`  | 就绪探针（含下游） |
| GET  | `/metrics` | Prometheus 指标    |

### 5.2 API v1 路由（JWT 鉴权 + 熔断 + 指标）

| 前缀                         | 下游服务         | 路径重写             | 说明                             |
| ---------------------------- | ---------------- | -------------------- | -------------------------------- |
| `/api/v1/classes/*`          | core-edu:3004    | 剥离 /api            | 班级管理                         |
| `/api/v1/iam/*`              | iam:3002         | 剥离 /api            | 身份与访问管理                   |
| `/api/v1/teacher/*`          | teacher-bff:3003 | 剥离 /api/v1/teacher | 教师聚合层 GraphQL               |
| `/api/v1/student/*`          | student-bff:3009 | 剥离 /api/v1/student | 学生聚合层 GraphQL               |
| `/api/v1/parent/*`           | parent-bff:3010  | 剥离 /api/v1/parent  | 家长聚合层 GraphQL               |
| `/api/v1/exams/*`            | core-edu:3004    | 剥离 /api            | 考试管理                         |
| `/api/v1/homework/*`         | core-edu:3004    | 剥离 /api            | 作业管理                         |
| `/api/v1/grades/*`           | core-edu:3004    | 剥离 /api            | 成绩管理                         |
| `/api/v1/textbooks/*`        | content:3005     | 剥离 /api            | 教材管理                         |
| `/api/v1/chapters/*`         | content:3005     | 剥离 /api            | 章节管理                         |
| `/api/v1/knowledge-points/*` | content:3005     | 剥离 /api            | 知识点管理                       |
| `/api/v1/questions/*`        | content:3005     | 剥离 /api            | 题库管理                         |
| `/api/v1/notifications/*`    | msg:3007         | 剥离 /api            | 通知管理                         |
| `/api/v1/messages/*`         | msg:3007         | 剥离 /api            | 消息管理                         |
| `/api/v1/announcements/*`    | msg:3007         | 剥离 /api            | 公告管理（msg nextstep.md §2.5） |
| `/api/v1/ai/*`               | ai:3008          | 剥离 /api            | AI 服务                          |
| `/api/v1/analytics/*`        | data-ana:3006    | 剥离 /api            | 学情诊断                         |
| `/api/v1/dashboard/*`        | data-ana:3006    | 剥离 /api            | 仪表盘                           |

### 5.3 admin 路由（JWT 鉴权 + admin 角色 + 熔断 + 指标）

| 方法 | 路径                 | 下游服务         | 路径重写        | 说明                      |
| ---- | -------------------- | ---------------- | --------------- | ------------------------- |
| ANY  | `/api/admin/graphql` | teacher-bff:3003 | 剥离 /api/admin | admin-portal GraphQL 入口 |

---

## 6. 剩余工作

### 6.1 SRE AI 部署配置（P0 部署阻断）

| #   | 工作项                                                | 详情                                                                                          | 状态      |
| --- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------- |
| 1   | `infra/docker-compose.deploy.yml` 新增 student-bff    | 服务定义缺失，需新增 build context + environment + ports + networks                           | ⏳ SRE    |
| 2   | `infra/docker-compose.deploy.yml` 新增 parent-bff     | 服务定义缺失                                                                                  | ⏳ SRE    |
| 3   | `infra/docker-compose.deploy.yml` 新增 student-portal | 服务定义缺失                                                                                  | ⏳ SRE    |
| 4   | `infra/docker-compose.deploy.yml` 新增 parent-portal  | 服务定义缺失                                                                                  | ⏳ SRE    |
| 5   | api-gateway environment 补充 `STUDENT_BFF_URL`        | 当前 deploy.yml 缺失，会回退到 `http://localhost:3009`，容器内无法访问                        | ✅ 已完成 |
| 6   | api-gateway environment 补充 `PARENT_BFF_URL`         | 当前 deploy.yml 缺失，会回退到 `http://localhost:3010`，容器内无法访问                        | ✅ 已完成 |
| 7   | api-gateway environment 补充 `IAM_JWKS_URL`           | 当前 deploy.yml 缺失，生产环境 RS256 验签需要                                                 | ✅ 已完成 |
| 8   | api-gateway build context 修复为 `./repo`             | Dockerfile 需访问 packages/shared-go，原 context `./repo/services/api-gateway` 会导致构建失败 | ✅ 已完成 |
| 9   | api-gateway environment 补充 `ENV=production`         | W7 防护：config.go 要求 ENV 显式标注                                                          | ✅ 已完成 |
| 10  | api-gateway environment 补充 `CORS_ORIGINS`           | 4 个 portal 端口白名单                                                                        | ✅ 已完成 |
| 11  | 新增 `/api/v1/announcements/*` 路由                   | msg 公告 REST API 需通过 gateway 暴露（msg nextstep.md §2.5 要求）                            | ✅ 已完成 |

### 6.2 P6 硬化任务（P1）

| #   | 工作项                          | 状态 | 说明                                      |
| --- | ------------------------------- | ---- | ----------------------------------------- |
| 1   | 限流迁移到 Redis（分布式限流）  | ⏳   | 当前为单机令牌桶，待 Redis 生产部署后迁移 |
| 2   | 安全硬化（WAF 集成、CSRF 防护） | ⏳   | 待基础设施就绪后实施                      |
| 3   | DataLoader 批量查询             | ✅   | 不适用（api-gateway 仅代理，无业务逻辑）  |
| 4   | OTel trace 上报                 | ✅   | 已实现（tracer.ts）                       |
| 5   | Prometheus 指标                 | ✅   | 已实现（metrics.ts，7 个业务指标）        |

### 6.3 arch.db 同步阻塞（环境问题，非代码问题）

| #   | 工作项               | 状态 | 阻塞原因                                                                                                                                                                                                       |
| --- | -------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | `pnpm run arch:scan` | ⏳   | better-sqlite3@11.3.0 原生绑定未编译，Node v22.19.0 + Windows 环境下 node-gyp rebuild 失败：VS2026 安装损坏（`Microsoft.DesktopBridge.Common.targets` 缺少根元素）。需修复 VS2026 安装或改用预编译二进制后重跑 |

**说明**：本次代码变更（NewProxyRewrite、registerBffProxy、admin 路由组、AdminRoleMiddleware、Dockerfile）已通过 `go vet` + `go build` + `go test` + Docker 验证，仅 arch.db 同步被环境问题阻塞，不影响功能正确性。

### 6.4 端到端联调（P1）

| #   | 联调项                                            | 触发条件                         |
| --- | ------------------------------------------------- | -------------------------------- |
| 1   | api-gateway → iam JWKS 验签联调                   | iam 服务容器启动 + JWKS 端点就绪 |
| 2   | api-gateway → teacher-bff GraphQL 代理联调        | teacher-bff 服务容器启动         |
| 3   | api-gateway → student-bff GraphQL 代理联调        | student-bff 服务容器启动         |
| 4   | api-gateway → parent-bff GraphQL 代理联调         | parent-bff 服务容器启动          |
| 5   | admin-portal → api-gateway → teacher-bff 端到端   | 所有服务容器就绪后执行           |
| 6   | teacher-portal → api-gateway → teacher-bff 端到端 | 所有服务容器就绪后执行           |
| 7   | student-portal → api-gateway → student-bff 端到端 | 所有服务容器就绪后执行           |
| 8   | parent-portal → api-gateway → parent-bff 端到端   | 所有服务容器就绪后执行           |

---

## 7. 已完成项汇总

| 工作项                                      | 状态 | 验证方式                                                           |
| ------------------------------------------- | ---- | ------------------------------------------------------------------ |
| `/api/admin/graphql` 路由组                 | ✅   | Docker 验证 401/502（路由存在，鉴权+角色校验生效）                 |
| AdminRoleMiddleware（admin 角色强制校验）   | ✅   | 8 个单元测试 + Docker 验证                                         |
| NewProxyRewrite（自定义路径重写代理）       | ✅   | 5 个单元测试 + Docker 验证                                         |
| registerBffProxy（BFF 路由路径重写）        | ✅   | Docker 验证 /api/v1/teacher/graphql → 502（路径重写正确）          |
| parent-bff 双 /v1 前缀支持（ARB-022 §24.4） | ✅   | Docker 验证 /api/v1/parent/v1/graphql → 502（路径重写正确）        |
| Dockerfile 修复（go.work 精简 + GOPROXY）   | ✅   | Docker 构建成功                                                    |
| Docker 镜像构建                             | ✅   | edu/api-gateway:test（golang:1.25-alpine + alpine:3.20）           |
| Docker 容器运行验证                         | ✅   | /healthz 200 + /readyz 503 + /metrics 200 + admin/graphql 401/502  |
| go vet + go build + go test                 | ✅   | 全部通过（13 个测试）                                              |
| JWT RS256 验签（JWKS 公钥校验）             | ✅   | AuthMiddleware + shared-go/jwks.Fetcher                            |
| DevMode 旁路（dev-token）                   | ✅   | Docker 验证 dev-token 通过鉴权                                     |
| 限流（IP 级令牌桶）                         | ✅   | 100 rps，突发 20                                                   |
| 熔断（下游 5xx 触发）                       | ✅   | CircuitBreaker("downstream") + CircuitBreaker("teacher-bff-admin") |
| CORS 白名单                                 | ✅   | CORS_ORIGINS 环境变量                                              |
| 安全响应头                                  | ✅   | SecurityHeaders 中间件                                             |
| 请求体大小限制                              | ✅   | 10MB 上限                                                          |
| 请求 ID 注入                                | ✅   | X-Request-Id header                                                |
| OTel 自动埋点                               | ✅   | otelgin 中间件                                                     |
| Prometheus 指标（7 个业务指标）             | ✅   | /metrics 端点                                                      |

---

## 8. 关键文件路径

| 文件                                                                                | 用途                                                  |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [main.go](../main.go)                                                               | 入口 + 路由注册（含 admin 路由组 + registerBffProxy） |
| [internal/config/config.go](../internal/config/config.go)                           | 配置加载（含 13 个服务 URL + DevMode 防护）           |
| [internal/middleware/auth.go](../internal/middleware/auth.go)                       | JWT RS256 鉴权 + x-user-* 头注入                      |
| [internal/middleware/admin_role.go](../internal/middleware/admin_role.go)           | admin 角色强制校验中间件                              |
| [internal/middleware/admin_role_test.go](../internal/middleware/admin_role_test.go) | AdminRoleMiddleware 单元测试（8 个）                  |
| [internal/middleware/circuit-breaker.go](../internal/middleware/circuit-breaker.go) | 熔断中间件（sony/gobreaker/v2）                       |
| [internal/middleware/ratelimit.go](../internal/middleware/ratelimit.go)             | IP 级令牌桶限流                                       |
| [internal/middleware/cors.go](../internal/middleware/cors.go)                       | CORS 中间件                                           |
| [internal/proxy/proxy.go](../internal/proxy/proxy.go)                               | NewProxy + NewProxyRewrite 反向代理                   |
| [internal/proxy/proxy_rewrite_test.go](../internal/proxy/proxy_rewrite_test.go)     | NewProxyRewrite 单元测试（5 个）                      |
| [internal/observability/metrics.go](../internal/observability/metrics.go)           | Prometheus 指标（7 个业务指标）                       |
| [internal/observability/tracer.go](../internal/observability/tracer.go)             | OTel tracer 初始化                                    |
| [internal/health/health.go](../internal/health/health.go)                           | /healthz + /readyz 健康检查                           |
| [Dockerfile](../Dockerfile)                                                         | Docker 构建（go.work 精简 + GOPROXY）                 |

---

## 9. 环境变量清单（Docker 部署）

| 变量                          | 必填 | 示例值                                         | 说明                                    |
| ----------------------------- | ---- | ---------------------------------------------- | --------------------------------------- |
| `API_GATEWAY_PORT`            | 是   | `8080`                                         | HTTP 监听端口                           |
| `DEV_MODE`                    | 是   | `false`                                        | DevMode 旁路（生产必须 false，W7 防护） |
| `ENV`                         | 是   | `production`                                   | 部署环境标识                            |
| `IAM_JWKS_URL`                | 是   | `http://iam:3002/v1/iam/.well-known/jwks.json` | RS256 公钥端点                          |
| `JWT_ISSUER`                  | 否   | `next-edu-cloud`                               | JWT iss 校验                            |
| `JWT_AUDIENCE`                | 否   | `next-edu-cloud`                               | JWT aud 校验                            |
| `CORS_ORIGINS`                | 否   | `http://localhost:3000,http://localhost:4001`  | CORS 白名单                             |
| `TEACHER_BFF_URL`             | 是   | `http://teacher-bff:3003`                      | teacher-bff 地址                        |
| `STUDENT_BFF_URL`             | 是   | `http://student-bff:3009`                      | student-bff 地址                        |
| `PARENT_BFF_URL`              | 是   | `http://parent-bff:3010`                       | parent-bff 地址                         |
| `IAM_SERVICE_URL`             | 是   | `http://iam:3002`                              | iam 地址                                |
| `CORE_EDU_SERVICE_URL`        | 是   | `http://core-edu:3004`                         | core-edu 地址                           |
| `CONTENT_SERVICE_URL`         | 是   | `http://content:3005`                          | content 地址                            |
| `DATA_ANA_SERVICE_URL`        | 是   | `http://data-ana:3006`                         | data-ana 地址                           |
| `MSG_SERVICE_URL`             | 是   | `http://msg:3007`                              | msg 地址                                |
| `AI_SERVICE_URL`              | 是   | `http://ai:3008`                               | ai 地址                                 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 否   | `http://otel-collector:4318`                   | OTLP 上报端点                           |
| `LOG_LEVEL`                   | 否   | `info`                                         | 日志级别                                |

---

**本文件由 ai01 维护。api-gateway v2 全部工作已完成并通过本地 Docker 测试（DEV_MODE=true，无 mock 数据）。待 SRE AI 补充 deploy.yml 环境变量 + 下游服务容器就绪后即可端到端联调。**