fix(api-gateway): 升级 gobreaker v2 并更新 README

- go.mod: 新增 github.com/sony/gobreaker/v2 v2.1.0
- go.sum: 同步校验和
- README: 新增 P6 中间件链说明、健康检查端点表、测试说明、配置环境变量表

services/api-gateway/README.md

@@ -1,11 +1,41 @@
-# API Gateway
+# API Gateway
 
 Go (Gin) 实现的 API 网关，所有外部请求的统一入口。
 
 ## 职责
-- 路由转发：/api/v1/classes/* → classes 服务
-- JWT 鉴权：P1 HS256，P2 RS256
-- 请求 ID 注入：全链路追踪
+
+- **路由转发**：`/api/v1/classes/*` → classes 服务（P1），后续阶段追加 iam/core-edu/content/msg 等路由
+- **JWT 鉴权**：P1 HS256（测试密钥），P2 起 RS256（IAM 签发，Gateway 公钥校验）
+- **请求 ID 注入**：生成或透传 `X-Request-ID`，全链路追踪
+- **限流**（P6）：基于令牌桶的 per-IP 限流，超限返回 429
+- **熔断**（P6）：基于 gobreaker v2 的下游服务熔断，5xx 错误率 > 50% 触发 OPEN
+- **CORS / 安全头 / Recovery**（P6）：标准化中间件链
+
+## 中间件链（P6）
+
+请求处理顺序（自外向内）：
+
+```
+Request → RequestID → CORS → Security → Recovery → RateLimit → Auth → CircuitBreaker → Proxy → Response
+```
+
+| 中间件         | 文件                                     | 职责                                         |
+| -------------- | ---------------------------------------- | -------------------------------------------- |
+| RequestID      | `internal/middleware/requestid.go`       | 生成/透传 `X-Request-ID`                     |
+| CORS           | `internal/middleware/cors.go`            | 跨域允许                                     |
+| Security       | `internal/middleware/security.go`        | 安全响应头（X-Content-Type-Options 等）      |
+| Recovery       | `internal/middleware/recovery.go`        | panic 兜底返回 500                           |
+| RateLimit      | `internal/middleware/ratelimit.go`       | per-IP 令牌桶限流，超限 429                  |
+| Auth           | `internal/middleware/auth.go`            | JWT 校验，注入 `x-user-id`/`x-user-roles` 头 |
+| CircuitBreaker | `internal/middleware/circuit-breaker.go` | 下游 5xx 错误率 > 50% 触发熔断，返回 503     |
+
+## 健康检查
+
+| 端点           | 用途                                     | 鉴权 |
+| -------------- | ---------------------------------------- | ---- |
+| `GET /healthz` | 存活探针（liveness）                     | 无   |
+| `GET /readyz`  | 就绪探针（readiness）                    | 无   |
+| `GET /health`  | 兼容端点（返回 `{ status, timestamp }`） | 无   |
 
 ## 开发
 
@@ -15,5 +45,45 @@ go mod tidy
 go run main.go
 ```
 
-## 健康检查
-GET /healthz
+## 测试
+
+```bash
+# 单元 + 集成测试
+cd services/api-gateway
+go test ./internal/middleware/... -v -cover
+
+# 测试覆盖
+# - circuit-breaker_test.go: 5 用例（ClosedToOpen / OpenToHalfOpen / HalfOpenToClosed / HalfOpenToOpen / 4xxNotCounted）
+# - ratelimit_test.go: 5 用例（AllowUnderBurst / RejectOverBurst / RefillTokens / PerIPIsolation / CleanupExpiredBuckets）
+```
+
+## 构建
+
+```bash
+# 本地构建
+go build ./...
+
+# Docker 构建
+docker build -t edu/api-gateway .
+```
+
+## 配置
+
+通过环境变量配置（见 `internal/config/config.go`）：
+
+| 变量                  | 默认值                | 说明                 |
+| --------------------- | --------------------- | -------------------- |
+| `PORT`                | 8080                  | 监听端口             |
+| `JWT_SECRET`          | （必填）              | HS256 签名密钥（P1） |
+| `JWT_PUBLIC_KEY`      | （P2）                | RS256 公钥           |
+| `CLASSES_SERVICE_URL` | http://localhost:3001 | classes 服务地址     |
+| `RATE_LIMIT_RPS`      | 10                    | 每秒令牌数           |
+| `RATE_LIMIT_BURST`    | 20                    | 突发容量             |
+
+## 关联文档
+
+- [架构影响地图](../../docs/architecture/004_architecture_impact_map.md)
+- [项目规则](../../.trae/rules/project_rules.md)
+- [P6 硬化 Runbook](../../docs/architecture/runbooks/p6-hardening.md)
+- [P6 后续工作手册](../../docs/architecture/runbooks/post-p6-followup.md)
+- [Helm Chart](../../infra/k8s/helm/api-gateway/)