proxy-pool/docs/requirements/traceability.md

需求追踪矩阵

本文将 对话内容.md 的演进讨论压缩为最终可验收需求。后出现的明确修订 覆盖早期方案，尤其是 Distribution 的 Lease 设计。

架构

ID	最终需求	来源	验证证据
ARCH-001	数据面 Worker 与控制面 Controller 分离	1-70	包、协议和部署拓扑已分离；Controller 已运行 Worker Register/Watch/ACK/Runtime gRPC，并发布无凭据 Proxy/Gateway Routing 完整快照，Gateway 已有会话客户端组件；Gateway/Checker/Loadgen 构建产物及 Gateway Routing 运行时消费待实现
ARCH-002	热路径只做认证、本地路由和网络转发	1-70, 380-430	Snapshot/Dispatch 及依赖边界已验证；完整 Gateway 进程与代表性性能剖析待完成
ARCH-003	Gateway、Distribution、Admin、Metrics 独立入口	8904-8958	Controller 命令已装配 Distribution/Admin/Metrics 三个独立监听及联动停机；Gateway 生产入口待装配
ARCH-004	Controller 集中 Provider 获取与切换	1403-1580	Redis Leader、动态 Provider Supervisor 与 Bootstrap 生产装配已完成；Admin disable/reload 驱动取消替换，多副本按权威 HMAC 指纹和 revision 栅栏收敛并拒绝旧配置换主；Routing 切换到 Drain 的编排待完成
ARCH-005	100k QPS 峰值使用多 Worker 集群	当前会话	未验证设计目标；待代表性集群负载报告

Routing 与 Upstream

ID	最终需求	来源	验证证据
ROUTE-001	Routing 自上而下匹配，首条命中停止	3534-3798, 5825-6467	rule.go 与不可变/首命中单测
ROUTE-002	Routing 与 Upstream 生命周期解耦	3534-3798	包依赖与配置模型
ROUTE-003	支持 sequential、random、roundRobin、weighted、leastConnections	5825-6467	五种领域策略及单测已完成；配置到 Gateway/Distribution 运行链的接线待完成
ROUTE-004	Sequential 连续空结果达到阈值后原子切换一次	5295-5824, 6520-6617	进程内 RoutingCursor 版本 CAS 与 100 并发测试已完成；持久化恢复和跨实例 CAS 待完成
ROUTE-005	空计数属于 Upstream，当前选择属于 Routing	8442-8529	共享 UpstreamEmptyState 双 Routing 测试
ROUTE-006	旧 Upstream 已有 Proxy 继续耗尽，不因切换直接丢弃	6618-6641	通用 ownership Drain/ACK 原语已测试；Routing 切换到 Drain 的编排待完成
ROUTE-007	无可用 Upstream 时显式 reject、wait 或 direct，默认 reject	5075-5294, 6743-6760	三种动作的配置校验已完成；Gateway 当前仅返回 503，默认化及 wait/direct 运行时待完成

Provider 与补池

ID	最终需求	来源	验证证据
FETCH-001	每个 Provider 有独立 requestInterval、maxInFlight、timeout 和 retry	968-2394	provider/reconciler_test.go
FETCH-002	大量缺池信号合并为 singleflight/容量 1 通知	2067-2136, 8808-8849	coalesce.Signal 与 100 并发通知测试
FETCH-003	错误使用指数退避和抖动，429 尊重 Retry-After	1601-1831, 8808-8856	provider/reconciler_test.go 与 providerapi/http_adapter_test.go
FETCH-004	Provider 获取由单逻辑 Leader 执行	1403-1580	Redis Coordinator 已通过真实 Redis 双实例互斥、epoch 接管、全局间隔/在途 Permit 与 generation 重建测试；生产 Supervisor/bootstrap 已通过 Admin disable 和 Provider HTTP 到隔离 Redis 库存的组合 fixture
FETCH-005	Empty 与 Error 分开；只有合法候选为零时 Empty++	8442-8529	fetch_result_test.go 分类矩阵
FETCH-006	重复候选不当作 Empty，记录独立指标	8442-8480	DuplicateOnly 分类与 Provider 测试
FETCH-007	模板限制响应大小、执行时间、函数集和外部访问	8808-8856	providerapi/template_parser_test.go 输入、输出、候选、超时、递归与函数白名单测试
FETCH-008	pool.maxSize 与 fetch.maxTotal 语义分离	9190-9280	本地 FetchBudget 仅约束当前库存；Redis Permit 原子维护累计与 pending 额度，并通过换主、取消、幂等和过期保守结算测试

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	固定 Max 下打包 CAS、1,000 并发不超卖、退役 Proxy 停止新预留及零计数历史运行态回收已完成；动态降容和完整生命周期证据待完成
CAP-002	补池依据 Available Slots，不只看 Proxy 数量	1203-1402, 8530-8597	AvailableSlots、显式 minimum/target 水位、pending 槽位和迟滞 Reconciler 已测试；Worker session/ACK/sequence/TTL/ownership fence、基础 Snapshot 流及 Gateway 会话组件已通过内存、Redis 8.2 和 gRPC 测试；权威 payload、目标健康和 Gateway reserve 策略仍待完成
CAP-003	pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected	3001-3533, 6642-6680	FetchBudget 100 并发额度预占测试
CAP-004	TTL safety margin 内禁止新分配	173-220, 6728-6741	时钟测试
CAP-005	多 Worker 不在热路径访问 Redis 计数	1403-1467	Gateway 包依赖审计、Snapshot/Dispatch 测试

Gateway

ID	最终需求	来源	验证证据
GW-001	支持 HTTP 与 HTTPS CONNECT，SOCKS5 保留扩展接口	1-70	transport_test.go、server/e2e_test.go 本地假上游测试
GW-002	GET/HEAD 可配置安全重试，非幂等方法默认不重试	2600-2654, 8737-8807	handler_test.go GET 换代理、POST 单次尝试与 407 不重试测试
GW-003	CONNECT 建立后不得透明重放	221-300	handler_test.go 200 前重试、200 后中继故障不重放、半关闭测试
GW-004	Client 认证可关闭，但访问控制、身份识别和限流独立	8112-8441	protection_test.go、bootstrap_test.go 与入口并发上限测试
GW-005	防私网、回环、链路本地、保留/元数据地址、任意 CONNECT 端口和 DNS Rebinding	8904-8931	policy/target_test.go 解析前后校验、端口白名单、混合 DNS 结果与已验证 IP 绑定测试

Distribution

ID	最终需求	来源	验证证据
DIST-001	API 提取固定为一次性独占发放，不使用 Lease	9083-9404	Domain 状态机与 API 测试
DIST-002	AVAILABLE -> EXTRACTED 必须原子完成后才能返回	9083-9189	Memory/Redis 公用契约与真实 Redis 100 轮竞态测试
DIST-003	支持 partial 与 allOrNothing，默认 partial	9190-9215	API 契约测试
DIST-004	不保存逐代理/逐次提取审计记录，不提供释放接口；仅保留短期幂等结果	9216-9252	Redis 幂等 TTL 契约、OpenAPI 与 PostgreSQL 边界审计
DIST-005	返回 expiresAt 与 remainingTtlSeconds	9334-9360	extraction/service_test.go
DIST-006	提取前校验 minRemainingTTL 与 maxHealthCheckAge	9334-9369	过滤测试
DIST-007	reserveForGateway 防止 Extract 清空共享池	9281-9333	共享池测试
DIST-008	提取认证可关闭，关闭后仍有来源识别与全局限制	8112-8441	来源身份准入、FixedWindow 单元测试及 redisadmission 双实例/并发集成测试

健康、安全、运维与测试

ID	最终需求	来源	验证证据
HEALTH-001	全局健康与 Routing/目标健康分离	221-270, 8679-8708	Protobuf/配置契约已定义；目标 Profile 与健康 Reducer 待实现
HEALTH-002	健康调度有 jitter、maxInFlight 和分级频率	8679-8736	配置校验已完成；有界调度器、抖动和分级频率测试待实现
HEALTH-003	失败分级 SUSPECT -> UNHEALTHY -> REMOVE	8679-8736	Proxy 状态迁移骨架已完成；连续失败 Reducer 与活动池原子提交待实现
SEC-001	API 认证与 Proxy 认证分离，Secret 统一脱敏	7528-8111, 8904-8945	Config 脱敏、Provider Store -> SecretRef -> Gateway Resolver 跨包测试与格式化泄漏回归测试
SEC-002	非回环监听无保护时严格模式启动失败	8112-8441	配置校验测试
OPS-001	配置校验后构建不可变快照并原子替换	8959-8999	100k 索引、版本/epoch 与并发 Apply/Acquire 测试
OPS-002	优雅停机停止新请求/Fetch，等待现有流量后超时关闭	8981-9000	Provider Run 收敛与 Handler.Shutdown HTTP 排空、Hijacked CONNECT 超时关闭测试
OPS-003	PostgreSQL 只保存管理修订、Upstream/Routing 状态、Admin 审计与 Outbox	当前会话	ADR-006、adminstate 公用契约和六表 Schema 边界测试；真实 PostgreSQL 契约待完成
OBS-001	指标禁止 Proxy IP、session、Client、完整 URL 高基数标签	9001-9029	Controller Prometheus/探针模块已实现且当前只暴露无业务标签的 Go/进程指标；低基数业务 Collector 与描述符测试待实现
TEST-001	覆盖对话中列出的 11 个关键并发与故障场景	9030-9082	测试清单；Redis 活动池由 Memory/Redis 公用契约覆盖，跨进程故障场景仍按清单推进