From 80c6ba1ea89f8860e6c3dc901ef1917e151107cf Mon Sep 17 00:00:00 2001 From: youfak Date: Wed, 29 Jul 2026 20:56:40 +0800 Subject: [PATCH] docs: correct project completion evidence --- docs/development/implementation-plan.md | 12 ++++++------ docs/requirements/completion-audit.md | 7 ++++++- docs/requirements/traceability.md | 8 ++++---- findings.md | 23 +++++++++++++++++++++++ progress.md | 13 +++++++++++++ task_plan.md | 4 ++++ 6 files changed, 56 insertions(+), 11 deletions(-) diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index 475805c..6fb6fa9 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -210,11 +210,11 @@ Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆 **Files:** `api/openapi/proxy-pool.yaml`, `api/proto/controlplane/v1/controlplane.proto`, `docs/api/*.md` -- [ ] Specify Distribution/Admin REST schemas, status codes, authentication, examples, +- [x] Specify Distribution/Admin REST schemas, status codes, authentication, examples, and idempotency behavior. -- [ ] Specify Worker register, snapshot, delta, ACK, report, heartbeat, ownership drain, +- [x] Specify Worker register, snapshot, delta, ACK, report, heartbeat, ownership drain, and resync messages. -- [ ] Validate OpenAPI and compile protobuf descriptors in CI. +- [x] Validate OpenAPI and compile protobuf descriptors in CI. ## Task 13: Deployment and Observability @@ -232,10 +232,10 @@ Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆 **Files:** `docs/**`, `examples/**`, `diagrams/**` -- [ ] Complete README navigation, design document, developer guide, configuration +- [x] Complete README navigation, design document, developer guide, configuration reference, API guide, deployment guide, security model, testing guide, and roadmap. -- [ ] Provide at least 20 validated configuration examples. -- [ ] Provide at least 30 Mermaid architecture, flow, sequence, state, and failure diagrams. +- [x] Provide at least 20 validated configuration examples. +- [x] Provide at least 30 Mermaid architecture, flow, sequence, state, and failure diagrams. - [ ] Generate `proxy-pool-docs-v1.0.zip` from versioned documentation assets. ## Task 15: Completion Audit diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index 18921e0..a78df82 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -26,7 +26,8 @@ 配置持续测试。 - `PROXY-* / CAP-*`：唯一键、TTL 优先级、状态迁移与 Active/Reserved 打包 原子计数；1,000 goroutine 不超卖测试。 -- `ROUTE-001 / ROUTE-004`：首条命中规则与 Concurrent Sequential 单次切换。 +- `ROUTE-001 / ROUTE-004`：首条命中规则与进程内 Concurrent Sequential 单次 + 切换；策略运行时接线、持久化恢复和跨实例 CAS 尚未完成。 - `FETCH-005 / FETCH-006`：Valid、Empty、DuplicateOnly、Error 分类。 - `DIST-001..003 / DIST-006..007`：内存活动池参考实现验证独占提取、满足模式、 TTL、健康时效与 Gateway 保留量；1,000 并发不重复。 @@ -80,6 +81,10 @@ CI 已配置 Linux race job。Docker/Kubernetes 仅完成静态验证，没有 7. Checker 调度、探测器和健康 reducer。 8. Admin/Distribution 细粒度授权、分布式限流和审计查询。 9. 真实 Compose/Kubernetes 集成、故障演练和代表性集群负载测试。 +10. 将五种 Routing 策略和 `onUnavailable` 接入 Gateway/Distribution 运行链， + 补齐 Sequential 持久化恢复、跨实例 CAS 和 disabled candidate 语义。 +11. 补齐 Proxy Capacity 动态降容契约、Reservation 全生命周期观测及短 TTL + Proxy 运行态排空回收。 ## 4. 容量结论 diff --git a/docs/requirements/traceability.md b/docs/requirements/traceability.md index 6f8b80a..2081322 100644 --- a/docs/requirements/traceability.md +++ b/docs/requirements/traceability.md @@ -19,11 +19,11 @@ |---|---|---|---| | ROUTE-001 | Routing 自上而下匹配，首条命中停止 | 3534-3798, 5825-6467 | `rule.go` 与不可变/首命中单测 | | ROUTE-002 | Routing 与 Upstream 生命周期解耦 | 3534-3798 | 包依赖与配置模型 | -| ROUTE-003 | 支持 sequential、random、roundRobin、weighted、leastConnections | 5825-6467 | `strategy_test.go`、`routing_test.go` | -| ROUTE-004 | Sequential 连续空结果达到阈值后原子切换一次 | 5295-5824, 6520-6617 | `RoutingCursor` 版本 CAS 与 100 并发测试 | +| ROUTE-003 | 支持 sequential、random、roundRobin、weighted、leastConnections | 5825-6467 | 五种领域策略及单测已完成；配置到 Gateway/Distribution 运行链的接线待完成 | +| ROUTE-004 | Sequential 连续空结果达到阈值后原子切换一次 | 5295-5824, 6520-6617 | 进程内 `RoutingCursor` 版本 CAS 与 100 并发测试已完成；持久化恢复和跨实例 CAS 待完成 | | ROUTE-005 | 空计数属于 Upstream，当前选择属于 Routing | 8442-8529 | 共享 `UpstreamEmptyState` 双 Routing 测试 | | ROUTE-006 | 旧 Upstream 已有 Proxy 继续耗尽，不因切换直接丢弃 | 6618-6641 | Drain 测试 | -| ROUTE-007 | 无可用 Upstream 时显式 reject、wait 或 direct，默认 reject | 5075-5294, 6743-6760 | 配置默认值与端到端测试 | +| ROUTE-007 | 无可用 Upstream 时显式 reject、wait 或 direct，默认 reject | 5075-5294, 6743-6760 | 三种动作的配置校验已完成；Gateway 当前仅返回 503，默认化及 wait/direct 运行时待完成 | ## Provider 与补池 @@ -45,7 +45,7 @@ | PROXY-001 | Proxy 保存协议、地址、凭据引用、来源、TTL、健康、容量和标签 | 71-105, 8605-8678 | Domain 类型与序列化测试 | | PROXY-002 | 唯一键包含 scheme、host、port、username、credentialVersion | 6655-6727, 8605-8678 | 去重单测 | | PROXY-003 | TTL 来源优先级明确并统一 UTC | 681-747, 8655-8678 | TTL 表驱动测试 | -| CAP-001 | Gateway 分配使用 Reserved -> Active 原子转换 | 1203-1467, 8530-8597 | 高并发竞态测试 | +| CAP-001 | Gateway 分配使用 Reserved -> Active 原子转换 | 1203-1467, 8530-8597 | 固定 Max 下打包 CAS 与 1,000 并发不超卖已完成；动态降容和完整生命周期证据待完成 | | CAP-002 | 补池依据 Available Slots，不只看 Proxy 数量 | 1203-1402, 8530-8597 | `Inventory.AvailableSlots` 与 Pool Reconciler 测试 | | CAP-003 | pool.maxSize 包括 FETCHED/CHECKING/AVAILABLE/SUSPECT/DRAINING 与 pending expected | 3001-3533, 6642-6680 | `FetchBudget` 100 并发额度预占测试 | | CAP-004 | TTL safety margin 内禁止新分配 | 173-220, 6728-6741 | 时钟测试 | diff --git a/findings.md b/findings.md index 94eefef..59af8b9 100644 --- a/findings.md +++ b/findings.md @@ -105,3 +105,26 @@ Routing 自上而下匹配，首条命中停止；支持 Gateway 与 Extract 两 - PostgreSQL 管理面基础文档已提交为 `7951c29`。 - 推送远端时返回 `Authentication failed`；没有重复相同失败操作，本地提交保持 完整，待 Git 凭据恢复后同步。 + +## Routing/Sequential 验收审计（2026-07-29） + +- 五种 Routing 策略已有独立领域实现和单测，但 `Rule` 未携带 Strategy/ + OnUnavailable，Gateway 仍把全部 Upstream 交给一个全局轮询 Dispatcher；配置 + 策略尚未影响真实请求链。 +- `onUnavailable` 已严格校验 reject/wait/direct，但 Gateway 无候选时统一返回 + 503；wait/direct 和默认 reject 尚未形成运行时闭环。 +- Sequential 当前版本 CAS 只在单进程内生效，构造时总从第一个 Upstream 开始； + PostgreSQL 管理态尚未接入游标恢复和跨实例 CAS。 +- 单 Upstream Sequential、默认 endBehavior、disabled candidate 的最终语义与 + 现有代码/需求存在差异，进入设计确认项，不在测试中固化未确认行为。 + +## Proxy Capacity 验收审计（2026-07-29） + +- 每个 Proxy ID 已有独立打包原子计数，固定 Max 下 1,000 并发不会超卖；这满足 + 当前 Gateway 热路径的基本预留不变量。 +- Reservation 缺少 Cancel、重复终结、错误顺序和并发 Commit/Cancel 的完整领域 + 测试，Gateway 也会忽略 Release/Cancel 错误，尚无低基数不变量观测 seam。 +- `SetMax` 与 counters 分离更新；降到当前占用以下时会出现 overcommitted 状态， + 需要先确定“拒绝降容”或“允许排空”的正式契约。 +- Snapshot Store 永久保留见过的 Proxy ID 对应 Capacity；短 TTL、高换 IP 场景下 + 需要排空后回收，避免运行态注册表长期增长。 diff --git a/progress.md b/progress.md index 052f496..ca0e69d 100644 --- a/progress.md +++ b/progress.md @@ -2,6 +2,19 @@ ## 2026-07-29 +- 已复核 `implementation-plan.md` 的验收项：机器契约、OpenAPI/Protobuf 验证、 + 完整文档导航、20 份配置示例和 35 张 Mermaid 图已有仓库及验证证据，修正 + 6 个滞后勾选；当前为 48/73，约 66%。 +- 正在并行审计 Routing/Sequential 与 Proxy Capacity 的剩余边界；本轮只收敛 + 已确认公共接口和既有需求，不把 Checker、pgx 或 100,000 QPS 目标提前记为完成。 +- Routing 审计确认五种策略尚未进入真实请求链、`onUnavailable` 只有配置校验、 + Sequential 仅有进程内 CAS；Capacity 审计确认固定 Max 不超卖，但动态降容、 + Reservation 完整生命周期观测和短 TTL 运行态回收待完成。追踪矩阵已降级为 + 准确的“已完成证据 + 待办”描述。 +- 定向执行 Proxy、Routing、Config、Gateway Dispatch/Server 测试，全部通过； + 该结果只证明现有行为基线，不替代上述缺失运行链的验收。 +- 一次组合检索因包含不存在的 `config` 路径返回退出码 1；有效输出已保留， + 后续检索改用实际目录 `internal/config`，未重复原命令。 - 已实现共享 `httpapi`、`httpsecurity` 与 `httpserver`，统一严格 JSON、Problem、 Request ID、认证、可信代理、Client ID、准入、多监听器生命周期和优雅停机。 - Distribution/Admin Handler 已装配到独立监听器；Gateway 配置认证统一复用 diff --git a/task_plan.md b/task_plan.md index 55fb277..21e315c 100644 --- a/task_plan.md +++ b/task_plan.md @@ -31,6 +31,8 @@ 11. [进行中] 实现 PostgreSQL 管理面；ADR、领域事务契约、MemoryStore、公用 契约、六表 Schema、Admin Actor 传播、应用服务和原子配置发布已完成，pgx Adapter/集成测试待完成 +12. [进行中] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界； + 机器契约和文档类滞后勾选已按仓库证据校正 ## 串并行关系 @@ -53,3 +55,5 @@ 目标运行拓扑。 - `cmd/proxy-*`、PostgreSQL 管理面 Adapter、Provider Leader/分布式限流、 Checker 运行时、Redis 故障转移验证与代表性集群压测属于后续实施范围。 +- `implementation-plan.md` 当前按 73 个验收项统计；已校正为 48 项完成， + 验收项完成率约 66%，不等同于生产就绪度。