docs: design README refresh

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

@@ -0,0 +1,106 @@
+# 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 或部署行为。