# Proxy Pool

面向多供应商代理资源的集中管理与高并发转发平台。系统同时提供：

- **Gateway**：系统选择上游代理并代转发 HTTP 与 HTTPS CONNECT。
- **Distribution API**：把真实代理一次性、独占地发放给调用方。
- **Admin API**：查询、启停、切换和配置重载。
- **Controller / Checker**：管理供应商获取、健康、容量、状态与数据面快照。

> 当前仓库交付的是从 `对话内容.md` 全量重建的设计基线、机器契约、
> 项目骨架和关键并发领域实现。100,000 QPS 是集群设计目标，尚需在目标
> 网络和代理规模下完成压测证明。

## 快速导航

- [产品设计](docs/design/product-design.md)
- [总体架构](docs/design/architecture.md)
- [项目结构](docs/design/project-structure.md)
- [需求追踪](docs/requirements/traceability.md)
- [交付完成度审计](docs/requirements/completion-audit.md)
- [开发指南](docs/development/guide.md)
- [实施计划](docs/development/implementation-plan.md)
- [配置参考](docs/configuration/reference.md)
- [Distribution API](docs/api/distribution.md)
- [控制面协议](docs/api/control-plane.md)
- [安全模型](docs/security/security-model.md)
- [测试策略](docs/testing/strategy.md)
- [运维手册](docs/operations/runbook.md)
- [生产就绪检查](docs/operations/production-readiness.md)

## 本地验证

```powershell
go mod tidy
go test ./...
go vet ./...
go build ./...
```

Windows PowerShell 可运行：

```powershell
./scripts/verify.ps1
```

竞态检测需要启用 CGO 并提供可用的 C 编译器；CI 的 Linux race job 负责
执行该质量门禁。

## 不变量

1. Gateway 热路径不访问 PostgreSQL、Redis 或 Provider API。
2. Proxy 容量使用 `Reserved -> Active` 原子转换，禁止超卖。
3. Distribution 成功时原子执行 `AVAILABLE -> EXTRACTED`，不提供 Lease、
   Release 或 Renewal。
4. `pool.maxSize` 是当前未提取库存上限；`fetch.maxTotal` 是累计获取额度。
5. CONNECT 向客户端提交 200 后不透明重放。
6. 公开监听必须有认证或 CIDR 访问保护。