proxy-pool/docs/superpowers/specs/2026-07-30-readme-refresh-design.md

README 首页重写设计

1. 目标

将根目录 README.md 从早期的“设计基线与项目骨架”说明，更新为与当前代码 一致的工程首页。README 必须让首次访问者在几分钟内回答以下问题：

1. Proxy Pool 解决什么问题，为什么区分 Gateway 与 Distribution。
2. 当前已经实现和验证了哪些能力。
3. 哪些模块仍是局部实现、协议或部署占位，不能视为生产完成。
4. 如何验证、配置并启动当前可运行的 Controller。
5. 后续实现按什么优先级推进。

README 不承担完整设计文档职责；细节继续链接到 docs/ 中的权威文档。

2. 目标读者

• 评估项目能力和成熟度的技术负责人。
• 部署、维护 Controller 与存储依赖的开发者和 SRE。
• 需要理解模块边界、测试入口和后续任务的贡献者。

内容优先级依次为：事实准确、快速定位、可执行、简洁。README 不采用营销页 结构，也不宣称未经代表性压测证明的 100,000 QPS 能力。

3. 内容结构

README 按以下顺序组织：

1. 项目名称与一句话定位：多供应商动态代理的集中控制、独占提取和高并发 转发平台。
2. 项目背景：说明供应商响应格式、短 TTL、容量、健康、路由和高并发数据面 隔离问题。
3. 使用方式：明确 Gateway 是平台代转发，Distribution 是一次性独占发放， Admin 是管理入口。
4. 核心能力：按配置、Provider、活动池、Distribution、Gateway、Admin、 存储与安全列出已经落地的能力。
5. 架构概览：使用一张紧凑 Mermaid 图展示 Client、Gateway、Controller、 Checker、PostgreSQL、Redis 和 Provider 的关系，并重申 Gateway 热路径边界。
6. 当前完成度：展示实施计划 52/74、约 70.3% 的快照，同时分别列出 已完成、部分完成和待完成模块。标注统计日期，并链接实施计划，避免把数量 完成度等同于生产就绪度。
7. 快速开始：列出 Go、PostgreSQL、Redis、Docker 等前置条件，提供配置校验、 全量验证、Redis/PostgreSQL/Controller fixture 和当前 Controller 启动命令。
8. 关键配置与入口：链接配置样例、Distribution/Admin API、Metrics 探针和 Secret 要求，不在 README 复制长配置。
9. 核心不变量：保留并完善热路径、容量、独占提取、数据边界、CONNECT 重试和公开监听保护规则。
10. 路线图：按 P0/P1/P2 展示 WorkerControlPlane/Snapshot、Checker/健康链、 Gateway 进程装配、Routing 运行链、观测部署和代表性集群压测。
11. 文档导航：按设计、开发/API、部署运维、审计测试分组，避免单一长列表。

4. 状态表达规则

• 已完成：生产代码存在，并至少有单元、契约或真实依赖集成证据。
• 部分完成：领域内核、Handler、协议或部署清单存在，但进程装配或端到端链路 尚未闭环。
• 待完成：只有计划、配置字段、协议定义或部署占位。
• 100,000 QPS 始终表述为集群设计目标，直到存在可复现的代表性负载报告。
• 不把 Docker Compose/Kubernetes 静态配置验证描述为完整生产部署验证。
• 不把 protobuf descriptor 编译描述为 gRPC 服务端已经实现。
• PostgreSQL 只描述管理面数据；Proxy 明细、Worker 运行态和短期幂等仍属于 Redis 或节点内存。

5. 快速开始边界

README 只提供仓库当前真实可执行的命令：

• go run ./deploy/tools/configcheck deploy/config/local.yaml
• ./scripts/verify.ps1
• ./scripts/test-redis.ps1
• ./scripts/test-postgres.ps1
• ./scripts/test-controller.ps1
• go run ./cmd/proxy-controller -config CONFIG_FILE

启动示例必须说明 PostgreSQL、Redis、配置中引用的环境变量，以及 Admin 启用时 至少 32 字节的 PROXY_POOL_CONFIG_FINGERPRINT_KEY。README 不提供不存在的 proxy-gateway、proxy-checker 或 proxy-loadgen 启动命令。

6. 路线图

• P0，控制面闭环：Worker 注册/session、Snapshot ledger、ACK、运行态接收、 Worker 维度 ownership 索引和 Gateway 快照客户端。
• P0，健康链：Checker 调度、实际探测、Observation reducer、目标健康隔离和 FETCHED 到 AVAILABLE/SUSPECT/UNHEALTHY 的运行链。
• P1，数据面进程：proxy-gateway 命令装配、Routing 五策略和 onUnavailable 运行时、动态降容与 Drain 闭环。
• P1，可观测与部署：低基数业务指标、完整 Compose/Kubernetes 进程拓扑、 故障转移和恢复演练。
• P2，容量证明：proxy-loadgen、HTTP/CONNECT/Extract 分场景压测和 100,000 QPS 集群报告。

7. 验收标准

1. README 中的命令和路径均指向仓库中的真实目标。
2. README 相对链接通过 go test ./docs。
3. README 中的配置文件通过现有配置示例测试和 configcheck。
4. 已完成/部分完成/待完成状态与实施计划、完成度审计和代码现状一致。
5. 全文不包含未完成占位标记、虚假生产就绪声明、Secret 值或代理明细示例。
6. 文档修改通过 git diff --check 和全量 go test ./...。

8. 非目标

• 不在本次修改中实现新的运行时功能。
• 不重写 docs/ 下已有的详细设计、API 或运维文档。
• 不生成营销图片、徽章、发布包或未经验证的性能图表。
• 不改变配置、API、存储 Schema 或部署行为。