221 lines
7.8 KiB
Markdown
221 lines
7.8 KiB
Markdown
# 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/links_test.go`
|
||
|
||
- [ ] **Step 1: 记录文档基线**
|
||
|
||
Run: `go test -count=1 -timeout 60s ./docs`
|
||
|
||
Expected: PASS，证明修改前的相对链接基线有效。
|
||
|
||
- [ ] **Step 2: 写入标题、背景与三类使用方式**
|
||
|
||
将旧的“设计基线、项目骨架”定位替换为以下事实：
|
||
|
||
```markdown
|
||
# Proxy Pool
|
||
|
||
面向多供应商动态代理资源的集中控制、独占提取与高并发转发平台。
|
||
|
||
## 项目背景
|
||
|
||
不同代理供应商的响应格式、鉴权方式、计费方式和代理存活时间并不一致；部分
|
||
代理只有几十秒有效期。Proxy Pool 将供应商适配、短 TTL 活动池、容量分配、
|
||
健康状态和路由控制集中到 Controller，同时让 Gateway 数据面只消费内存快照，
|
||
避免在转发热路径查询 PostgreSQL、Redis 或供应商 API。
|
||
|
||
## 使用方式
|
||
|
||
- **Gateway**：调用方连接平台，由平台选择上游代理并转发 HTTP 或 HTTPS CONNECT。
|
||
- **Distribution**：调用方按条件提取真实代理；成功提取即独占消费，不支持归还或续租。
|
||
- **Admin**：运维人员查询状态、启停上游、切换路由并触发严格配置重载。
|
||
```
|
||
|
||
- [ ] **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 热路径只访问节点内存。
|
||
|
||
- [ ] **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 是集群设计目标，
|
||
尚无代表性环境压测报告。
|
||
|
||
- [ ] **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 或负载生成器启动命令。
|
||
|
||
- [ ] **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”“部署与运维”“审计与测试”四组。
|
||
|
||
- [ ] **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`
|
||
|
||
- [ ] **Step 1: 验证本地配置命令**
|
||
|
||
在当前 PowerShell 进程设置 README 中列出的本地环境变量，然后运行：
|
||
|
||
```powershell
|
||
go run ./deploy/tools/configcheck deploy/config/local.yaml
|
||
```
|
||
|
||
Expected: 配置校验成功，退出码为 0。
|
||
|
||
- [ ] **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`。
|
||
|
||
- [ ] **Step 3: 扫描失实表述与临时标记**
|
||
|
||
确认 README 没有把 100,000 QPS、gRPC descriptor、静态部署清单或局部 Gateway
|
||
组件表述成已经完成的生产能力，并确认不包含 Secret 实值和代理明细样例。
|
||
|
||
- [ ] **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。
|