2 changed files with 39 additions and 407 deletions
--- a/README.md
+++ b/README.md
@ -1,206 +1,58 @@
 # Proxy Pool
-## 项目定位
+面向多供应商代理资源的集中管理与高并发转发平台。系统同时提供：
-面向多供应商动态代理资源的集中控制、独占提取与高并发转发平台。
+- **Gateway**：系统选择上游代理并代转发 HTTP 与 HTTPS CONNECT。
 - **Distribution API**：把真实代理一次性、独占地发放给调用方。
 - **Admin API**：查询、启停、切换和配置重载。
 - **Controller / Checker**：管理供应商获取、健康、容量、状态与数据面快照。
-Proxy Pool 将供应商接入、短 TTL 代理活动池和管理状态集中到 Controller，
+> 当前仓库交付的是从 `对话内容.md` 全量重建的设计基线、机器契约、
-同时提供三类边界清晰的访问方式。集群 `100,000 QPS` 是设计目标，尚未经过
+> 项目骨架和关键并发领域实现。100,000 QPS 是集群设计目标，尚需在目标
-代表性环境的负载测试证明。
+> 网络和代理规模下完成压测证明。
-## 项目背景
+## 快速导航
 不同代理供应商的响应格式、鉴权方式、计费方式和代理存活时间并不一致；部分
 代理只有几十秒有效期。系统还需要同时处理容量预留、健康状态、路由切换、
 一次性提取和高并发转发。
 Proxy Pool 用 Controller 协调这些变化，并让 Gateway 数据面只消费节点内存中的
 不可变快照，避免在转发热路径查询 PostgreSQL、Redis 或 Provider API。
 ## 使用方式
 - **Gateway**：调用方连接平台，由平台选择上游代理并转发 HTTP 或 HTTPS
  CONNECT。当前已有传输、调度和保护链组件，命令进程与控制面快照客户端待装配。
 - **Distribution**：调用方按条件提取真实代理；成功提取即独占消费，不支持归还、
  续租或状态查询。
 - **Admin**：运维人员查询状态、启停 Upstream、切换 Routing，并触发严格配置
  重载。Admin 与 Distribution 已由 Controller 运行在独立监听器上。
 ## 核心能力
 - **严格配置**：配置版本 1、YAML 未知字段拒绝、Secret 引用解析、公开监听保护、
  引用和容量边界校验。
 - **Provider 获取与协调**：Provider HTTP Client、响应上限、模板解析、分布式
  Leader/请求额度、退避和补池 Supervisor 已接入 Controller。
 - **Redis 活动池**：短 TTL Proxy Upsert、去重、健康更新、Worker ownership、
  库存、过期清理、Distribution 幂等与分布式限流均使用原子操作或有界流程。
 - **Distribution**：支持 `partial` / `allOrNothing`、TTL 与健康过滤、Gateway
  库存预留，以及 `AVAILABLE -> EXTRACTED` 的一次性独占提取。
 - **Controller 入口**：`proxy-controller` 已装配 Distribution、Admin、Metrics、
  PostgreSQL 迁移与 Redis 活动池，并支持联动优雅停机。
 - **PostgreSQL 管理面**：持久化配置版本、Upstream/Routing 管理状态、Admin
  审计与 Outbox；不保存 Proxy 明细或逐次提取记录。
 - **Gateway 组件**：HTTP 正向代理、HTTPS CONNECT、双向 Tunnel、重试、超时、
  目的地址保护、本地快照存储和容量调度已有实现与定向测试，但尚无
  `proxy-gateway` 命令和控制面客户端。
 - **安全边界**：Gateway、Distribution 与 Admin 使用各自的认证语义，并支持
  CIDR、可信代理、严格请求解析和敏感信息最小化。
 ## 架构概览
 ```mermaid
 flowchart LR
    Client[调用方] -->|HTTP / CONNECT| Gateway[Gateway<br/>进程待装配]
    Client -->|独占提取| Distribution[Distribution]
    Operator[运维人员] -->|管理操作| Admin[Admin]
    subgraph CP[proxy-controller 已运行]
        Distribution --> Controller[Controller]
        Admin --> Controller
    end
    Controller -->|Fetch| Provider[Provider API]
    Controller --> Redis[(Redis)]
    Controller --> PostgreSQL[(PostgreSQL)]
    Checker[Checker<br/>健康链待闭环] -. Observation .-> Controller
    Controller -. Snapshot 链待闭环 .-> Gateway
 ```
 - **PostgreSQL** 只保存管理面状态，不保存 Proxy 明细或逐次提取记录。
 - **Redis** 保存短 TTL Proxy 活动池、Provider 协调、Distribution 幂等与分布式
  限流等可重建的短期状态。
 - **Gateway 热路径** 只读取节点内存，不查询 PostgreSQL、Redis 或 Provider API。
 ## 当前完成度
 截至 **2026-07-30**，实施计划检查项为 **52 / 74（70.3%）**。详情见
 [实施计划](docs/development/implementation-plan.md)和
 [交付完成度审计](docs/requirements/completion-audit.md)。
 - **已完成**：严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子
  提取与限流、Controller 的 Admin/Distribution/Metrics 监听，以及 PostgreSQL
  管理状态。
 - **部分完成**：Gateway 传输与调度组件、Snapshot 本地存储、Worker ownership
  与运行态领域组件、Docker Compose/Kubernetes 静态部署清单和 protobuf 契约。
 - **待完成**：WorkerControlPlane gRPC session/snapshot/ACK 闭环、Checker 调度与
  健康状态链、Gateway 进程与快照客户端、完整 Routing 运行链，以及 loadgen 和
  代表性集群压测。
 检查项数量不等于生产就绪度。静态部署清单与 protobuf descriptor 验证也不代表
 端到端拓扑已经完成；`100,000 QPS` 仍只是待验证的集群设计目标。
 ## 快速开始
 前置条件为 Go 1.26、PowerShell，以及用于 fixture 测试的 Docker。先在当前
 PowerShell 会话设置本地占位凭据；这些值仅用于本地验证：
 ```powershell
 $env:PROXY_POOL_GATEWAY_PASSWORD = "LOCAL_GATEWAY_PASSWORD"
 $env:PROXY_POOL_EXTRACT_TOKEN = "LOCAL_EXTRACT_TOKEN"
 $env:PROXY_POOL_ADMIN_TOKEN = "LOCAL_ADMIN_TOKEN"
 $env:PROVIDER_A_TOKEN = "LOCAL_PROVIDER_A_TOKEN"
 $env:PROVIDER_B_TOKEN = "LOCAL_PROVIDER_B_TOKEN"
 $env:PROXY_POOL_CONFIG_FINGERPRINT_KEY = "LOCAL_HIGH_ENTROPY_KEY_AT_LEAST_32_BYTES"
 ```
 `PROXY_POOL_CONFIG_FINGERPRINT_KEY` 在 Admin 启用时必须至少为 32 字节，并与业务
 Secret 分离管理。
 校验配置并执行仓库验证：
 ```powershell
 go run ./deploy/tools/configcheck deploy/config/local.yaml
 ./scripts/verify.ps1
 ```
 Redis、PostgreSQL 和 Controller fixture 脚本会使用 Docker 启动隔离依赖：
 ```powershell
 ./scripts/test-redis.ps1
 ./scripts/test-postgres.ps1
 ./scripts/test-controller.ps1
 ```
 PostgreSQL 与 Redis 是 Controller 的启动依赖。当前可运行的 Controller 入口如下，
 将 `CONFIG_FILE` 替换为实际配置路径，并确保其中的 PostgreSQL 与 Redis 地址可从
 进程所在网络访问：
 ```powershell
 go run ./cmd/proxy-controller -config CONFIG_FILE
 ```
 [`deploy/config/local.yaml`](deploy/config/local.yaml) 面向 Compose 网络，默认使用
 服务名 `postgres` 和 `redis`；它可直接用于配置校验，但宿主机执行 `go run` 时需要
 改用宿主机可达的存储地址。
 本地配置中的 `.invalid` Provider URL 是故障演示占位，不会提供真实代理。
 当前仓库没有 Gateway、Checker 或 loadgen 命令，因此不提供对应启动命令。
 ## 关键配置与入口
 - [本地配置](deploy/config/local.yaml)与
  [完整配置参考](docs/configuration/reference.md)
 - [Distribution API](docs/api/distribution.md)：默认本地入口
  `http://127.0.0.1:8081`
 - [Admin API](docs/api/admin.md)：默认本地入口 `http://127.0.0.1:8082`
 - Controller Metrics：默认本地入口 `http://127.0.0.1:9090`，提供 `/livez`、
  `/readyz` 和 `/metrics`
 - [控制面协议](docs/api/control-plane.md)：Worker/Checker 的 protobuf 契约；
  gRPC 运行链尚未闭环
 - [运维手册](docs/operations/runbook.md)：依赖、探针、发布边界与故障处置
 ## 核心不变量
 1. Gateway 热路径只读节点内存，不访问 PostgreSQL、Redis 或 Provider API。
 2. Proxy 容量使用 `Reserved -> Active` 原子转换，禁止超卖。
 3. Distribution 成功时原子执行 `AVAILABLE -> EXTRACTED`；提取后不归还、不续租。
 4. `pool.maxSize` 是当前未提取库存硬上限；`fetch.maxTotal` 是 Redis generation
   内的累计获取停止阈值。
 5. CONNECT 向客户端提交 `200` 后不透明重放。
 6. 公开监听必须有认证或 CIDR 访问保护。
 7. PostgreSQL 只保存管理面状态；Proxy 明细只存在于 Redis 短 TTL 活动池和节点
   内存，Redis 中的短期状态可由 Provider 重建。
 ## 路线图
 - **P0 - Worker 控制面闭环**：Worker session、Snapshot ledger、ACK、运行态接收、
  ownership 索引，以及 Gateway 快照客户端。
 - **P0 - Checker 健康链**：Checker 调度、实际探测、Observation reducer，以及
  `FETCHED -> AVAILABLE / SUSPECT / UNHEALTHY` 状态链。
 - **P1 - Gateway 与 Routing**：`proxy-gateway` 命令、五种 Routing 策略、
  `onUnavailable`、动态容量调整和 Drain 闭环。
 - **P1 - 可观测与部署**：低基数业务指标、完整 Compose/Kubernetes 进程拓扑，
  以及故障转移和恢复演练。
 - **P2 - 容量证明**：`proxy-loadgen`、HTTP/CONNECT/Extract 分场景压测，以及
  可复现的代表性 `100,000 QPS` 集群报告。
 ## 文档导航
 **设计与需求**
 - [产品设计](docs/design/product-design.md)
 - [总体架构](docs/design/architecture.md)
 - [项目结构](docs/design/project-structure.md)
 - [需求追踪](docs/requirements/traceability.md)
- [架构决策记录](docs/adr/README.md)
+- [交付完成度审计](docs/requirements/completion-audit.md)
 **开发与 API**
 - [开发指南](docs/development/guide.md)
 - [实施计划](docs/development/implementation-plan.md)
 - [配置参考](docs/configuration/reference.md)
 - [Distribution API](docs/api/distribution.md)
 - [Admin API](docs/api/admin.md)
 - [控制面协议](docs/api/control-plane.md)
-
+- [安全模型](docs/security/security-model.md)
-**部署与运维**
+- [测试策略](docs/testing/strategy.md)
 - [本地配置](deploy/config/local.yaml)
 - [运维手册](docs/operations/runbook.md)
 - [生产就绪检查](docs/operations/production-readiness.md)
 - [安全模型](docs/security/security-model.md)
-**审计与测试**
+## 本地验证
- [交付完成度审计](docs/requirements/completion-audit.md)
+```powershell
- [测试策略](docs/testing/strategy.md)
+go mod tidy
- [详细测试策略](docs/testing/test-strategy.md)
+go test ./...
- [故障注入](docs/testing/failure-injection.md)
+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` 是 Redis generation
   内的累计获取停止阈值。
 5. CONNECT 向客户端提交 200 后不透明重放。
 6. 公开监听必须有认证或 CIDR 访问保护。
--- a/docs/superpowers/plans/2026-07-30-readme-refresh.md
+++ b/docs/superpowers/plans/2026-07-30-readme-refresh.md
@ -1,220 +0,0 @@
 # README Refresh Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** 将根目录 README 更新为与当前代码、测试证据和实施计划一致的工程首页，使读者能准确理解用途、架构、完成度、启动方式与后续路线。
 **Architecture:** README 只汇总稳定事实并链接到 `docs/` 权威文档。内容按“背景与入口、能力与架构、进度与启动、约束与路线图”组织，明确 Controller 已可运行、Gateway/Checker 控制链尚未闭环，并保持 Gateway 热路径与 PostgreSQL/Redis 的数据边界。
 **Tech Stack:** Markdown、Mermaid、Go 文档链接测试、现有 PowerShell 验证脚本、Go CLI。
 ---
 ### Task 1: 重写工程首页
 **Files:**
 - Modify: `README.md`
 - Reference: `docs/superpowers/specs/2026-07-30-readme-refresh-design.md`
 - Reference: `docs/development/implementation-plan.md`
 - Reference: `docs/requirements/completion-audit.md`
 - Test: `docs/docs_test.go`
 - [x] **Step 1: 记录文档基线**
 Run: `go test -count=1 -timeout 60s ./docs`
 Expected: PASS，证明修改前的相对链接基线有效。
 - [x] **Step 2: 写入标题、背景与三类使用方式**
 将旧的“设计基线、项目骨架”定位替换为以下事实：
 ```markdown
 # Proxy Pool
 面向多供应商动态代理资源的集中控制、独占提取与高并发转发平台。
 ## 项目背景
 不同代理供应商的响应格式、鉴权方式、计费方式和代理存活时间并不一致；部分
 代理只有几十秒有效期。Proxy Pool 将供应商适配、短 TTL 活动池、容量分配、
 健康状态和路由控制集中到 Controller，同时让 Gateway 数据面只消费内存快照，
 避免在转发热路径查询 PostgreSQL、Redis 或供应商 API。
 ## 使用方式
 - **Gateway**：调用方连接平台，由平台选择上游代理并转发 HTTP 或 HTTPS CONNECT。
 - **Distribution**：调用方按条件提取真实代理；成功提取即独占消费，不支持归还或续租。
 - **Admin**：运维人员查询状态、启停上游、切换路由并触发严格配置重载。
 ```
 - [x] **Step 3: 写入能力清单与架构图**
 能力清单必须区分当前已落地的配置校验、Provider 获取协调、Redis 活动池、
 Distribution 原子提取、Controller HTTP 入口、PostgreSQL 管理状态、Gateway
 传输/调度领域组件，以及仍需闭环的进程装配。
 架构图使用以下节点与数据流：
 ```mermaid
 flowchart LR
    Client -->|HTTP / CONNECT| Gateway
    Client -->|独占提取| Distribution
    Operator -->|管理操作| Admin
    Gateway -.内存快照.-> Controller
    Distribution --> Controller
    Admin --> Controller
    Controller --> Provider
    Controller --> Redis
    Controller --> PostgreSQL
    Checker -.待闭环.-> Controller
 ```
 图后必须说明：PostgreSQL 只保存管理面状态；Redis 保存短 TTL 代理活动池、
 协调状态和分布式短期状态；Gateway 热路径只访问节点内存。
 - [x] **Step 4: 写入完成度快照**
 使用固定统计日期 `2026-07-30`，展示：
 ```markdown
 实施计划检查项：**52 / 74（70.3%）**。
 ```
 同时列出三类状态：
 - 已完成：严格配置、Provider 获取与协调、Redis 活动池、Distribution 原子提取
  与限流、Admin/Distribution/Metrics Controller 监听、PostgreSQL 管理状态。
 - 部分完成：Gateway 传输与调度领域组件、Snapshot 本地存储、Worker ownership
  与运行态领域组件、部署清单。
 - 待完成：WorkerControlPlane gRPC 会话与 ACK 闭环、Checker 健康链、Gateway
  进程与快照客户端、完整路由运行链、代表性集群压测。
 紧邻完成度说明：数量进度不等于生产就绪度；100,000 QPS 是集群设计目标，
 尚无代表性环境压测报告。
 - [x] **Step 5: 写入快速开始与真实入口**
 快速开始只包含仓库真实可执行的命令：
 ```powershell
 $env:PROXY_POOL_GATEWAY_PASSWORD = "LOCAL_GATEWAY_PASSWORD"
 $env:PROXY_POOL_EXTRACT_TOKEN = "LOCAL_EXTRACT_TOKEN"
 $env:PROXY_POOL_ADMIN_TOKEN = "LOCAL_ADMIN_TOKEN"
 $env:PROVIDER_A_TOKEN = "LOCAL_PROVIDER_A_TOKEN"
 $env:PROVIDER_B_TOKEN = "LOCAL_PROVIDER_B_TOKEN"
 $env:PROXY_POOL_CONFIG_FINGERPRINT_KEY = "LOCAL_HIGH_ENTROPY_KEY_AT_LEAST_32_BYTES"
 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 deploy/config/local.yaml
 ```
 正文说明 PostgreSQL 与 Redis 是 Controller 启动依赖，fixture 脚本使用 Docker，
 Admin 启用时 `PROXY_POOL_CONFIG_FINGERPRINT_KEY` 至少 32 字节。不得加入当前
 不存在的 Gateway、Checker 或负载生成器启动命令。
 - [x] **Step 6: 写入配置入口、不变量、路线图与文档导航**
 关键入口链接至少包括：
 - `deploy/config/local.yaml`
 - `docs/configuration/reference.md`
 - `docs/api/distribution.md`
 - `docs/api/admin.md`
 - `docs/api/control-plane.md`
 - `docs/operations/runbook.md`
 核心不变量保留容量原子转换、Distribution 独占提取、库存硬上限、CONNECT 200
 后不重放、公开监听保护，并新增 PostgreSQL 不保存代理明细的明确边界。
 路线图必须按以下优先级呈现：
 - P0：Worker 注册/session、Snapshot ledger、ACK、运行态、ownership 索引与
  Gateway 快照客户端。
 - P0：Checker 调度、实际探测、Observation reducer 与健康状态运行链。
 - P1：Gateway 命令装配、五种路由策略、不可用策略、动态降容与 Drain。
 - P1：低基数指标、完整 Compose/Kubernetes 拓扑、故障转移与恢复演练。
 - P2：负载生成器、HTTP/CONNECT/Extract 分场景压测与 100,000 QPS 集群报告。
 文档导航分成“设计与需求”“开发与 API”“部署与运维”“审计与测试”四组。
 - [x] **Step 7: 验证 README 链接与格式**
 Run: `go test -count=1 -timeout 60s ./docs`
 Expected: PASS。
 Run: `git diff --check`
 Expected: 无输出，退出码为 0。
 ### Task 2: 核验命令、状态口径与质量门禁
 **Files:**
 - Verify: `README.md`
 - Verify: `deploy/config/local.yaml`
 - Verify: `docs/development/implementation-plan.md`
 - Verify: `docs/requirements/completion-audit.md`
 - [x] **Step 1: 验证本地配置命令**
 在当前 PowerShell 进程设置 README 中列出的本地环境变量，然后运行：
 ```powershell
 go run ./deploy/tools/configcheck deploy/config/local.yaml
 ```
 Expected: 配置校验成功，退出码为 0。
 - [x] **Step 2: 核对完成度与进程入口**
 Run: `(rg "^- \[[xX ]\]" docs/development/implementation-plan.md | Measure-Object).Count`
 Expected: `74`。
 Run: `(rg "^- \[[xX]\]" docs/development/implementation-plan.md | Measure-Object).Count`
 Expected: `52`。
 Run: `Get-ChildItem cmd -Directory | Select-Object -ExpandProperty Name`
 Expected: 仅输出 `proxy-controller`。
 - [x] **Step 3: 扫描失实表述与临时标记**
 确认 README 没有把 100,000 QPS、gRPC descriptor、静态部署清单或局部 Gateway
 组件表述成已经完成的生产能力，并确认不包含 Secret 实值和代理明细样例。
 - [x] **Step 4: 执行仓库质量门禁**
 Run: `go test -count=1 -timeout 60s ./...`
 Expected: PASS。
 Run: `go vet ./...`
 Expected: PASS。
 Run: `go build ./...`
 Expected: PASS。
 Run: `git diff --check`
 Expected: 无输出，退出码为 0。
 - [ ] **Step 5: 提交并推送**
 Run: `git add README.md docs/superpowers/plans/2026-07-30-readme-refresh.md`
 Run: `git commit -m "docs: refresh project README"`
 Expected: 提交仅包含 README 与实施计划。
 Run: `git push origin build/proxy-pool-architecture`
 Expected: 远端分支更新成功，本地与远端 ahead/behind 均为 0。