# 交付完成度审计

本文区分设计证据、机器契约、已运行验证和后续实施，防止把架构目标描述成
已完成产品。

## 1. 本次已交付

### 设计与开发文档

- 全量需求追踪、覆盖关系和统一领域语言。
- 产品设计、总体架构、项目结构、四项 ADR。
- 开发、配置、Distribution/Admin API、控制面协议、安全、测试、运维文档。
- 20 个配置场景和 35 张 Mermaid 架构/流程/状态/故障图。

### 机器契约

- Distribution OpenAPI：一次性独占提取、partial/allOrNothing、幂等键、
  Redis TTL 活动池原子语义、TTL/健康过滤结果与标准错误。
- Admin OpenAPI：状态、Upstream 启停、Routing 切换和配置重载。
- 两份 OpenAPI 已进入 Go/CI 结构门禁，覆盖本地引用闭合、operationId、响应和
  security scheme；完整标准工具验证仍待补齐。
- Protobuf：Worker 注册、全量/增量 Snapshot、`usable_until`、ACK、运行态/
  结果上报、Checker 任务与 Observation。

### 核心参考实现

- `CFG-*`：YAML v4 未知字段拒绝、监听保护、引用/上限/认证边界校验，21 份
  配置持续测试。
- `PROXY-* / CAP-*`：唯一键、TTL 优先级、状态迁移与 Active/Reserved 打包
  原子计数；1,000 goroutine 不超卖，以及 Cancel、重复终结、错误顺序、并发
  Commit/Cancel/Release 计数守恒测试。
- `ROUTE-001 / ROUTE-004`：首条命中规则与进程内 Concurrent Sequential 单次
  切换；策略运行时接线、持久化恢复和跨实例 CAS 尚未完成。
- `FETCH-005 / FETCH-006`：Valid、Empty、DuplicateOnly、Error 分类。
- `DIST-001..003 / DIST-006..007`：内存活动池参考实现验证独占提取、满足模式、
  TTL、健康时效与 Gateway 保留量；1,000 并发不重复。
- `OPS-001`：完整 Snapshot 目标、epoch/version、校验和验证及原子替换。
- `CAP-001 / GW 热路径边界`：本地 Dispatch 条件过滤与原子容量预留。
- `GW-*`：HTTP 正向代理、HTTPS CONNECT、双向 Tunnel、超时、重试、保护链与
  优雅停机 Handler 已实现并通过定向测试。
- `PROVIDER-*`：Provider HTTP Client、严格响应上限、模板解析安全边界、凭据
  引用 Store 与 Reconciler Adapter 已实现。
- `DIST/Admin HTTP`：严格 JSON、Request ID、Problem 响应及 Distribution/Admin
  Handler 已实现；共享认证、CIDR、可信代理、Client ID 与本地准入保护链已接入，
  Controller Runtime 已将二者装配到独立监听器并支持联动优雅停机。
- `Redis Activity Adapter`：真实 Redis 8.2 已覆盖 Provider Upsert、健康更新、
  原子独占提取、短期幂等、Worker ownership、库存和有界过期清理，Memory/Redis
  运行同一公用契约。
- `PostgreSQL 管理面基础`：已定义 `adminstate` 事务 seam、并发安全 MemoryStore、
  公用契约、100 并发 Routing CAS、租约 Outbox 和只含六张管理表的 Schema；
  Admin Handler 已向 mutation 传播 Actor/SourceIP。Admin ApplicationService 已
  完成管理 mutation 映射、权威/运行态 Status 聚合、严格配置加载和持久化成功后
  的原子发布；边界测试禁止其依赖 Redis Extract 或 Proxy 明细包。

## 2. 已执行验证

```text
go test ./...                  PASS
go vet ./...                   PASS
go build ./...                 PASS
protoc descriptor compilation PASS
docker compose config         PASS
kubectl kustomize             PASS
configuration examples        21/21 PASS
Mermaid blocks                35
```

Windows 环境为 `CGO_ENABLED=0` 且没有 C 编译器，`go test -race` 在本机未执行；
CI 已配置 Linux race job。Docker/Kubernetes 仅完成静态验证，没有把目标拓扑
作为已运行系统。

## 3. 后续实现范围

以下已有设计、接口或部署位置，但尚无端到端生产实现：

1. `cmd/proxy-gateway/controller/checker/loadgen` 进程装配。
2. Gateway 进程装配、生产连接池调优与代表性流量压测。
3. Provider 分布式 singleflight/Leader、长期凭据回收和累计额度执行器。
4. PostgreSQL pgx 管理面 Adapter、真实 PostgreSQL 18 公用契约、Admin 应用层
   接线和可选聚合指标；Schema/领域 seam/Memory 参考实现已经完成。
5. Redis Provider Leader、分布式速率与 Client 限制、Worker 心跳和自动重建；
   TTL 活动池、原子提取和 Worker ownership 已完成。
6. Worker 网络快照流；Redis ownership drain/ACK/过期回收已完成。
7. Checker 调度、探测器和健康 reducer。
8. Admin/Distribution 细粒度授权、分布式限流和审计查询。
9. 真实 Compose/Kubernetes 集成、故障演练和代表性集群负载测试。
10. 将五种 Routing 策略和 `onUnavailable` 接入 Gateway/Distribution 运行链，
    补齐 Sequential 持久化恢复、跨实例 CAS 和 disabled candidate 语义。
11. 补齐 Proxy Capacity 动态降容契约、Reservation 全生命周期观测及短 TTL
    Proxy 运行态排空回收。

## 4. 容量结论

100,000 QPS 是集群设计输入，不是本次验证结果。只有实现上述运行时，并在
记录协议比例、代理 RTT、连接复用、Worker 规格、故障域、CPU/RSS/FD、延迟
分位数和错误率的环境中通过持续压测后，才能声明已验证容量。