需求追踪矩阵
本文将 对话内容.md 的演进讨论压缩为最终可验收需求。后出现的明确修订
覆盖早期方案，尤其是 Distribution 的 Lease 设计。
架构
| ID |
最终需求 |
来源 |
验证证据 |
| ARCH-001 |
数据面 Worker 与控制面 Controller 分离 |
1-70 |
进程结构、架构图、构建产物 |
| ARCH-002 |
热路径只做认证、本地路由和网络转发 |
1-70, 380-430 |
依赖规则、测试、性能剖析 |
| ARCH-003 |
Gateway、Distribution、Admin、Metrics 独立入口 |
8904-8958 |
配置、监听装配、端口测试 |
| ARCH-004 |
Controller 集中 Provider 获取与切换 |
1403-1580 |
Leader、singleflight、集成测试 |
| ARCH-005 |
100k QPS 峰值使用多 Worker 集群 |
当前会话 |
容量公式、负载场景、部署清单 |
Routing 与 Upstream
| ID |
最终需求 |
来源 |
验证证据 |
| ROUTE-001 |
Routing 自上而下匹配，首条命中停止 |
3534-3798, 5825-6467 |
路由单测 |
| ROUTE-002 |
Routing 与 Upstream 生命周期解耦 |
3534-3798 |
包依赖与配置模型 |
| ROUTE-003 |
支持 sequential、random、roundRobin、weighted、leastConnections |
5825-6467 |
策略契约测试 |
| ROUTE-004 |
Sequential 连续空结果达到阈值后原子切换一次 |
5295-5824, 6520-6617 |
并发切换测试 |
| ROUTE-005 |
空计数属于 Upstream，当前选择属于 Routing |
8442-8529 |
状态模型与多 Routing 测试 |
| ROUTE-006 |
旧 Upstream 已有 Proxy 继续耗尽，不因切换直接丢弃 |
6618-6641 |
Drain 测试 |
| ROUTE-007 |
无可用 Upstream 时显式 reject、wait 或 direct，默认 reject |
5075-5294, 6743-6760 |
配置默认值与端到端测试 |
Provider 与补池
| ID |
最终需求 |
来源 |
验证证据 |
| FETCH-001 |
每个 Provider 有独立 requestInterval、maxInFlight、timeout 和 retry |
968-2394 |
Fetcher 单测 |
| FETCH-002 |
大量缺池信号合并为 singleflight/容量 1 通知 |
2067-2136, 8808-8849 |
100 并发请求测试 |
| FETCH-003 |
错误使用指数退避和抖动，429 尊重 Retry-After |
1601-1831, 8808-8856 |
时钟驱动测试 |
| FETCH-004 |
Provider 获取由单逻辑 Leader 执行 |
1403-1580 |
多实例锁测试 |
| FETCH-005 |
Empty 与 Error 分开；只有合法候选为零时 Empty++ |
8442-8529 |
分类表驱动测试 |
| FETCH-006 |
重复候选不当作 Empty，记录独立指标 |
8442-8480 |
去重测试 |
| FETCH-007 |
模板限制响应大小、执行时间、函数集和外部访问 |
8808-8856 |
安全测试 |
| FETCH-008 |
pool.maxSize 与 fetch.maxTotal 语义分离 |
9190-9280 |
配置校验与计数测试 |
Proxy 生命周期与容量
| ID |
最终需求 |
来源 |
验证证据 |
| PROXY-001 |
Proxy 保存协议、地址、凭据引用、来源、TTL、健康、容量和标签 |
71-105, 8605-8678 |
Domain 类型与序列化测试 |
| PROXY-002 |
唯一键包含 scheme、host、port、username、credentialVersion |
6655-6727, 8605-8678 |
去重单测 |
| PROXY-003 |
TTL 来源优先级明确并统一 UTC |
681-747, 8655-8678 |
TTL 表驱动测试 |
| CAP-001 |
Gateway 分配使用 Reserved -> Active 原子转换 |
1203-1467, 8530-8597 |
高并发竞态测试 |
| CAP-002 |
补池依据 Available Slots，不只看 Proxy 数量 |
1203-1402, 8530-8597 |
容量单测 |
| CAP-003 |
pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected |
3001-3533, 6642-6680 |
并发 fetch 上限测试 |
| CAP-004 |
TTL safety margin 内禁止新分配 |
173-220, 6728-6741 |
时钟测试 |
| CAP-005 |
多 Worker 不在热路径访问 Redis 计数 |
1403-1467 |
依赖审计与压测 |
Gateway
| ID |
最终需求 |
来源 |
验证证据 |
| GW-001 |
支持 HTTP 与 HTTPS CONNECT，SOCKS5 保留扩展接口 |
1-70 |
协议端到端测试 |
| GW-002 |
GET/HEAD 可配置安全重试，非幂等方法默认不重试 |
2600-2654, 8737-8807 |
Retry 表驱动测试 |
| GW-003 |
CONNECT 建立后不得透明重放 |
221-300 |
隧道故障测试 |
| GW-004 |
Client 认证可关闭，但访问控制、身份识别和限流独立 |
8112-8441 |
配置矩阵测试 |
| GW-005 |
防私网、回环、链路本地、元数据地址和 DNS Rebinding |
8904-8931 |
目的地址策略测试 |
Distribution
| ID |
最终需求 |
来源 |
验证证据 |
| DIST-001 |
API 提取固定为一次性独占发放，不使用 Lease |
9083-9404 |
Domain 状态机与 API 测试 |
| DIST-002 |
AVAILABLE -> EXTRACTED 必须原子完成后才能返回 |
9083-9189 |
并发提取测试 |
| DIST-003 |
支持 partial 与 allOrNothing，默认 partial |
9190-9215 |
API 契约测试 |
| DIST-004 |
保存审计记录，不提供释放接口 |
9216-9252 |
Repository 测试与 OpenAPI |
| DIST-005 |
返回 expiresAt 与 remainingTtlSeconds |
9334-9360 |
响应测试 |
| DIST-006 |
提取前校验 minRemainingTTL 与 maxHealthCheckAge |
9334-9369 |
过滤测试 |
| DIST-007 |
reserveForGateway 防止 Extract 清空共享池 |
9281-9333 |
共享池测试 |
| DIST-008 |
提取认证可关闭，关闭后仍有来源识别与全局限制 |
8112-8441 |
安全配置测试 |
健康、安全、运维与测试
| ID |
最终需求 |
来源 |
验证证据 |
| HEALTH-001 |
全局健康与 Routing/目标健康分离 |
221-270, 8679-8708 |
健康 reducer 测试 |
| HEALTH-002 |
健康调度有 jitter、maxInFlight 和分级频率 |
8679-8736 |
调度测试 |
| HEALTH-003 |
失败分级 SUSPECT -> UNHEALTHY -> REMOVE |
8679-8736 |
状态机测试 |
| SEC-001 |
API 认证与 Proxy 认证分离，Secret 统一脱敏 |
7528-8111, 8904-8945 |
配置类型与日志测试 |
| SEC-002 |
非回环监听无保护时严格模式启动失败 |
8112-8441 |
配置校验测试 |
| OPS-001 |
配置校验后构建不可变快照并原子替换 |
8959-8999 |
热更新并发测试 |
| OPS-002 |
优雅停机停止新请求/Fetch，等待现有流量后超时关闭 |
8981-9000 |
进程测试 |
| OBS-001 |
指标禁止 Proxy IP、session、Client、完整 URL 高基数标签 |
9001-9029 |
指标描述符测试 |
| TEST-001 |
覆盖对话中列出的 11 个关键并发与故障场景 |
9030-9082 |
CI 测试清单 |
