# 需求文档：Fengling Gateway

**定义日期：** 2026-03-02
**核心价值：** 可靠、可扩展的 API 网关，将流量分发到后端微服务，支持零停机配置更新。

## v1 需求

初始发布版本的需求。每个需求对应一个 Roadmap 阶段。

### 配置管理

- [x] **CFG-01**：网关监听来自 fengling-console 的配置变更事件（PostgreSQL NOTIFY）
- [x] **CFG-02**：收到通知后网关无需重启即可重载配置
- [x] **CFG-03**：多实例网关通过 PostgreSQL NOTIFY 广播接收配置更新

### 多实例支持

- [x] **INST-01**：多个网关实例可以同时运行
- [x] **INST-02**：配置变更通过 NOTIFY 广播传播到所有实例
- [x] **INST-03**：使用 PostgreSQL LISTEN 订阅配置变更频道

### K8s 健康委托

- [ ] **K8S-01**：从网关注销 K8s 健康监控
- [ ] **K8S-02**：网关将服务健康检查委托给 console

### 安全修复

- [ ] **SEC-01**：移除源代码中的硬编码凭据
- [ ] **SEC-02**：实现正确的 JWT Token 验证
- [ ] **SEC-03**：为网关管理 API 端点添加认证

### 性能优化

- [ ] **PERF-01**：优化负载均衡锁竞争
- [ ] **PERF-02**：实现增量路由缓存更新

## v2 需求

延期到未来版本。已记录但不在当前 Roadmap 中。

### 可观测性

- **OBS-01**：分布式追踪集成
- **OBS-02**：网关性能自定义指标

### 测试

- **TEST-01**：RouteCache 单元测试
- **TEST-02**：JwtTransformMiddleware 单元测试
- **TEST-03**：负载均衡策略单元测试

## 范围外

| 功能 | 原因 |
|------|------|
| 直接配置网关的 UI | 由 fengling-console 处理 |
| 网关中的 K8s 服务健康检查 | 委托给 console |
| 网关中的认证逻辑 | 由 auth-service 处理 |
| 网关中的授权逻辑 | 由下游服务处理 |

## 可追溯性

哪些阶段覆盖哪些需求。Roadmap 创建时更新。

| 需求 | 阶段 | 状态 |
|------|------|------|
| CFG-01 | 阶段 1 | ✅ 已完成 |
| CFG-02 | 阶段 1 | ✅ 已完成 |
| CFG-03 | 阶段 1 | ✅ 已完成 |
| INST-01 | 阶段 1 | ✅ 已完成 |
| INST-02 | 阶段 1 | ✅ 已完成 |
| INST-03 | 阶段 1 | ✅ 已完成 |
| K8S-01 | 阶段 2 | 待处理 |
| K8S-02 | 阶段 2 | 待处理 |
| SEC-01 | 阶段 3 | 待处理 |
| SEC-02 | 阶段 3 | 待处理 |
| SEC-03 | 阶段 3 | 待处理 |
| PERF-01 | 阶段 4 | 待处理 |
| PERF-02 | 阶段 4 | 待处理 |

**覆盖率：**
- v1 需求：共 12 项
- 已映射到阶段：12 项
- 未映射：0 ✓
- 已完成：6 项（阶段 1）
- 待处理：6 项

---

**阶段 1 完成说明：**
- 现有 `PgSqlConfigChangeListener.cs` 已实现所有监听需求
- 监听频道：`gateway_config_changed`
- 包含断线重连和回退轮询机制

*需求定义：2026-03-02*
*最后更新：2026-03-02 阶段1完成后*