# 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 或部署行为。