# Proxy Pool 项目交付计划

## 目标

以 `对话内容.md` 的 9404 行完整讨论为唯一需求基线，交付设计文案、
开发文档和可编译、可测试、可扩展的 Go 项目架构。

## 需求覆盖原则

- 同一主题存在多轮修订时，以文件中最后出现的明确结论为准。
- 用户补充的集群峰值为 100,000 QPS，覆盖文档早期 10,000 并发示例。
- Extract API 固定采用一次性独占发放；早期 Lease/Release 设计作废。
- 不保留空实现、TBD、TODO 或没有接口契约的占位目录。

## 阶段

1. [已完成] 完整读取对话并识别覆盖关系
2. [已完成] 建立需求追踪矩阵与统一领域模型
3. [已完成] 编写总体设计、产品设计、项目结构和 ADR
4. [已完成] 编写开发、配置、API、测试、安全和运维文档
5. [已完成] 搭建 Go 模块、核心包、契约和部署拓扑目录
6. [已完成] 实现状态机、首条路由、Sequential、原子容量、独占提取、
   Fetch 分类、严格配置、不可变快照和本地调度参考实现
7. [已完成] 执行单元测试、静态检查、构建和静态部署/契约验证；本机因
   `CGO_ENABLED=0` 且无 C 编译器未运行 race，保留给 Linux CI
8. [已完成] 按需求矩阵逐项审计；`scripts/package-docs.ps1` 可生成带 revision 与 SHA-256
   清单的版本化文档包
9. [已完成] 将 Proxy 明细、独占提取、短期幂等和 Worker 所有权统一到
   TTL 活动池契约；PostgreSQL 退出代理数据路径
10. [已完成] 实现生产 Redis Activity Adapter、原子 Lua、公用行为契约和
    Redis 8.2 集成 fixture；本地 Redis 禁止短效代理数据持久化
11. [已完成] 实现 PostgreSQL 管理面；ADR、领域事务契约、MemoryStore、公用
    契约、六表 Schema、Admin Actor 传播、应用服务、原子配置发布、pgx Adapter
    和真实 PostgreSQL 18 集成测试已完成
12. [已完成] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界；
    机器契约和文档类滞后勾选已按仓库证据校正
13. [已完成] 落地 `proxy-controller` 进程装配；配置单次加载、PostgreSQL 迁移、
    Redis 活动池、低基数状态聚合、Distribution/Admin/Metrics 启动与关闭、
    WorkerControlPlane、Provider、Gateway/Checker/Loadgen 进程和业务指标均已完成。
    Compose mTLS 链路已具备配置、证书生成、静态清单与进程级验证；容器端到端启动
    仍受本机 Docker 镜像网络环境阻塞，留待具备镜像访问的环境复核。
14. [已完成] 收敛健康故障生命周期：将 `UNHEALTHY` 的持续时长纳入权威活动池状态，
    通过 Controller 后台的有界回收清理无 Worker ownership 的持续异常 Proxy；拥有
    Worker 的候选经 health/ownership 条件栅栏自动发起 Drain，在 ACK 与 Runtime 收尾后再处理。
15. [进行中] 收敛 Worker 发布生命周期：已完成权威 Proxy/Routing 的持续完整快照
    刷新，以及 Drain 发起时的持久化 Ticket、Worker 待绑定索引、ownership epoch 推进和
    完整排除 Snapshot 屏障绑定；已在 ACK 与 Runtime 零计数之间完成 Redis 原子自动收尾。
    配置与管理态共同决定的上游停用已接入同一 `BeginDrain` 编排：候选绑定上游 revision，
    Redis 原子复核策略、归属与 assignment epoch；两类自动 Drain 均已接入低基数
    Prometheus 指标。Admin 成功提交的 Upstream 启停、Routing 切换和配置发布现会经
    公用广播器立即刷新本进程所有 Worker 完整 Snapshot；跨 Controller 副本仍以定时刷新
    收敛。Health Scheduler 现以相同 revision 合并配置与管理态启用状态，管理态停用会停止
    该 Upstream 的新 BASIC/EGRESS/TARGET 任务，停用 Routing 仅停止其新 TARGET 任务。
    Gateway 请求生命周期直方图、Grafana 仪表盘、指标契约检查和 p99 延迟告警已完成；
    后续以真实容器、集群故障演练和代表性负载报告完成运行态验证闭环。

## 串并行关系

```text
全文解析 ─> 需求矩阵 ─> 统一设计 ─┬─> 设计/开发文档 ─┐
                                  ├─> API/配置契约 ───┼─> 集成验证
                                  └─> Go 项目架构 ────┘
```

## 测试约束

- 单条后台测试命令最长运行 60 秒。
- 核心并发代码必须执行 `go test -race`。
- 100k QPS 只能由可复现的集群压测结果证明，架构文档不得把设计容量
  写成已验证性能。

## 已知环境限制

- Docker Compose mTLS 控制面与 Kubernetes Kustomize 已完成本地与 CI 静态渲染验证；Redis 8.2
  与 PostgreSQL 18 的隔离 Adapter fixture 已运行。Docker Desktop 缺少镜像 HTTPS
  代理配置，未能在本机完成 Compose 容器端到端启动。
- Controller、Gateway、Checker、Loadgen、Provider Fleet、WorkerControlPlane、业务指标和
  Redis 故障边界均有实现与定向测试。真实容器故障转移、Kubernetes 工作负载身份 Overlay
  与代表性集群压测仍属于后续验证范围。
- `implementation-plan.md` 当前按 74 个验收项统计；验收勾选数不等同于生产就绪度。
  Compose 本地 mTLS 控制面运行链已实现并通过配置、证书、单元与构建验证；受本机 Docker
  Desktop 镜像 HTTPS 代理缺失影响，容器端到端启动仍待具备镜像网络的环境复核。