docs: record controller bootstrap delivery

docs/configuration/reference.md

@@ -10,8 +10,15 @@
 go run ./deploy/tools/configcheck deploy/config/local.yaml
 ```
 
-规划中的生产入口为 `proxy-controller -config CONFIG_FILE`；该命令完成实现和
+Controller 入口已实现，源码运行方式为：
-进程级测试前，不作为当前可执行能力。
+
+```powershell
+go run ./cmd/proxy-controller -config CONFIG_FILE
+```
+
+配置路径优先使用 `-config`，未提供时读取 `PROXY_POOL_CONFIG`。该入口已装配
+PostgreSQL 管理面迁移、Redis 活动池、Distribution/Admin 独立监听与优雅停机；
+Provider 自动补池、Metrics 探针和完整部署拓扑仍在后续实施范围。
 
 所有时间值使用 Go duration，例如 `500ms`、`30s`、`5m`。示例中的
 `${TOKEN}`、`${PASSWORD}`、`${POSTGRES_URL}` 等由加载器从同名环境变量
@@ -28,6 +35,10 @@ go run ./deploy/tools/configcheck deploy/config/local.yaml
 新配置任何一步失败时保留旧快照。删除或禁用 Upstream 只停止新 Fetch 和新
 分配，已有连接进入 Drain，不强制中断。
 
+当前 Controller 启动时使用同一份不可变快照完成存储、入口和提取策略装配。
+Admin 重载会原子提交新配置、审计并发布到配置 Store；监听地址、存储连接和
+已构造的安全/提取策略尚未自动重建，这些字段变更后需要重启 Controller。
+
 ## 2. 根结构
 
 ```yaml

docs/design/project-structure.md

@@ -13,7 +13,7 @@ proxy-pool/
 │   ├── config/              # 严格配置解析和校验
 │   ├── domain/              # 无传输、无存储依赖的领域模型
 │   ├── gateway/             # snapshot、dispatch、server、transport
-│   ├── controller/          # provider、pool、routing、extraction、health、runtime
+│   ├── controller/          # provider、pool、extraction、operations、runtime、bootstrap
 │   ├── adapters/            # PostgreSQL、Redis、Provider API、内存适配
 │   └── platform/            # HTTP、安全、日志、指标、停机和进程装配
 ├── api/                     # OpenAPI 与 Protobuf 契约

docs/development/implementation-plan.md

@@ -37,7 +37,7 @@ internal/
   domain/extraction/{extraction.go,store.go}
   domain/client/client.go
   gateway/{server,dispatch,snapshot,transport}/
-  controller/{provider,pool,routing,extraction,health,distribution}/
+  controller/{provider,pool,routing,extraction,health,distribution,operations,runtime,bootstrap}/
   adapters/{memory,postgres,redis,providerapi}/
   platform/{logging,metrics,shutdown}/
 api/{openapi,proto}/
@@ -196,14 +196,20 @@ Admin/Distribution 必需依赖。共享 `platform/httpserver` 与
 Repeatable Read 快照、`SKIP LOCKED`、原子 ACK、审计/Outbox 故障回滚和数据边界。
 Admin `ApplicationService` 已将 mutation、权威管理快照、低基数运行态
 聚合与配置重载接到同一公用 seam；严格文件加载、脱敏管理摘要及原子配置发布
-已通过失败路径和并发测试。生产命令入口及其连接池/迁移启动装配仍待实现。
+已通过失败路径和并发测试。`cmd/proxy-controller` 与公用 `controller/bootstrap`
+已完成配置单次加载、PostgreSQL 连接/迁移、Redis 活动池、状态聚合、
+Distribution/Admin 服务构造、错误合并和资源关闭；Provider 调度、Metrics 探针
+及完整 HTTP 进程端到端测试仍待实现。双存储 bootstrap 已通过 PostgreSQL 18 +
+Redis 8.2 组合 fixture，覆盖迁移、启动配置提交、Readiness 与 Admin Status。
 
 已新增公用 `domain/activitypool` 契约及并发安全内存参考实现，Provider
 Reconciler 通过 `UpsertFetched` 写入带供应商 TTL 和分配安全余量的批次；已覆盖
 `usableUntil` 向 Worker Snapshot 的传播与 Gateway 本地截止过滤、
 重复刷新、过期淘汰、独占提取、短期幂等及 Worker ownership 互斥。生产 Redis
 Adapter 已通过真实 Redis 8.2 运行同一套公用契约；原子 Lua 覆盖提取、所有权和
-有界清理。Redis Sentinel/故障转移验证与代表性多节点压测仍待实施。
+有界清理。新增低基数 StateInventory Hash，五类写脚本在同一原子边界维护状态
+计数，读取不扫描 Proxy 明细；过期清理积压或负计数时 fail-closed。Redis
+Sentinel/故障转移验证与代表性多节点压测仍待实施。
 
 ## Task 11: Checker and Health Reducer
 

docs/operations/runbook.md

@@ -18,9 +18,11 @@
 
 ## 2. 本地拓扑模板
 
-当前仓库交付设计、契约、部署拓扑和关键领域实现；`cmd/proxy-*` 的完整运行时
+`cmd/proxy-controller` 已完成配置单次加载、PostgreSQL 迁移、Redis 活动池、
-装配属于 `implementation-plan.md` 后续任务。此处 Compose/Kubernetes 资产用于
+Distribution/Admin 服务和有界停机装配。Provider 自动补池、Metrics 探针，
-评审网络、资源、探针和依赖关系，当前只执行静态渲染，不把模板写成可运行服务。
+以及 Gateway/Checker/Loadgen 三个进程仍属于 `implementation-plan.md` 后续任务。
+因此 Compose/Kubernetes 资产当前仍用于评审网络、资源、探针和依赖关系，不能
+视为完整可运行拓扑。
 
 ### 2.1 前置条件
 
@@ -60,6 +62,10 @@ tmpfs。`ApplyMigrations` 在同一物理连接上执行仓库内嵌的幂等前
 每个契约创建唯一 Schema，结束时只删除该 Schema 和临时 Compose 项目。该脚本
 禁止指向开发或生产数据库。
 
+`.\scripts\test-controller.ps1` 同时启动两个隔离 fixture，验证 Controller
+bootstrap 的迁移、启动配置提交、Redis Readiness 与 Admin Status。脚本不启动
+部署模板中的 Controller 容器，也不连接开发或生产存储。
+
 目标拓扑入口：
 
 - Gateway：`127.0.0.1:8080`

docs/requirements/completion-audit.md

@@ -76,12 +76,13 @@ CI 已配置 Linux race job。PostgreSQL 18 和 Redis 8.2 的隔离 Adapter fixt
 
 以下已有设计、接口或部署位置，但尚无端到端生产实现：
 
-1. `cmd/proxy-gateway/controller/checker/loadgen` 进程装配。
+1. `cmd/proxy-gateway/checker/loadgen` 进程装配；`proxy-controller` 已完成
+   Admin/Distribution 与 PostgreSQL/Redis 启动装配，但 Provider/Metrics 链未闭环。
 2. Gateway 进程装配、生产连接池调优与代表性流量压测。
 3. Provider 分布式 singleflight/Leader、长期凭据回收和累计额度执行器。
-4. PostgreSQL 连接池、迁移和 pgx Adapter 的生产命令启动装配，以及可选聚合指标；
+4. Controller 的 PostgreSQL 连接池、迁移和 pgx Adapter 启动装配已完成；
-   Schema、领域 seam、Memory/pgx Adapter、真实 PostgreSQL 18 契约和 Admin
+   公用 bootstrap 已通过 PostgreSQL 18 + Redis 8.2 双存储集成，可选聚合指标和
-   应用层接线已经完成。
+   完整 HTTP 进程部署验证仍待实现。
 5. Redis Provider Leader、分布式速率与 Client 限制、Worker 心跳和自动重建；
    TTL 活动池、原子提取和 Worker ownership 已完成。
 6. Worker 网络快照流；Redis ownership drain/ACK/过期回收已完成。

docs/requirements/traceability.md

@@ -7,9 +7,9 @@
 
 | ID | 最终需求 | 来源 | 验证证据 |
 |---|---|---|---|
-| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；四个 `cmd/proxy-*` 构建产物待实现 |
+| ARCH-001 | 数据面 Worker 与控制面 Controller 分离 | 1-70 | 包、协议和部署拓扑已分离；Controller 命令已实现，Gateway/Checker/Loadgen 构建产物待实现 |
 | ARCH-002 | 热路径只做认证、本地路由和网络转发 | 1-70, 380-430 | Snapshot/Dispatch 及依赖边界已验证；完整 Gateway 进程与代表性性能剖析待完成 |
-| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Distribution/Admin 独立监听已测试；Gateway/Metrics 生产入口待装配 |
+| ARCH-003 | Gateway、Distribution、Admin、Metrics 独立入口 | 8904-8958 | Controller 命令已装配 Distribution/Admin 独立监听；Gateway/Metrics 生产入口待装配 |
 | ARCH-004 | Controller 集中 Provider 获取与切换 | 1403-1580 | 单进程 Reconciler、合并通知和切换领域契约已完成；分布式 Leader 与运行装配待完成 |
 | ARCH-005 | 100k QPS 峰值使用多 Worker 集群 | 当前会话 | 未验证设计目标；待代表性集群负载报告 |
 

docs/testing/strategy.md

@@ -50,6 +50,12 @@ go build ./...
 该 fixture 使用唯一命名空间，不执行 `FLUSHDB`，并关闭 AOF、RDB 与数据卷；
 测试结束后按命名空间清理活动池、所有权和幂等键。
 
+Controller 的 PostgreSQL + Redis 启动组合测试使用：
+
+```powershell
+.\scripts\test-controller.ps1
+```
+
 单条测试命令超时 60 秒。依赖真实等待的用例必须改为 fake clock；集成和
 soak 测试单独标记，不混入快速单测。
 

docs/testing/test-strategy.md

@@ -108,6 +108,16 @@ Routing CAS、Repeatable Read 快照、审计分页、Routing no-op、`SKIP LOCK
 数据卷。静态与 `information_schema` 双重检查证明只存在六张管理表，且没有
 Proxy、凭据、逐次提取、Worker ownership 或幂等明细列。
 
+Controller bootstrap 的双存储组合验证命令是：
+
+```powershell
+.\scripts\test-controller.ps1
+```
+
+该 fixture 同时启动 PostgreSQL 18 与 Redis 8.2，验证迁移、启动配置提交、
+Redis Readiness 和 Admin Status；HTTP Runner 使用测试 Adapter，避免占用业务
+监听端口。测试数据仅存在于隔离 Compose 项目和 PostgreSQL tmpfs。
+
 Admin 应用层测试覆盖 typed-nil 依赖、Actor/SourceIP 映射、Routing CAS 错误、
 权威管理快照与低基数运行态聚合、未知字段拒绝、主配置/Secret 文件 I/O 分类、
 持久化失败不发布、幂等重放发布、脱敏管理摘要和原子配置 Store 并发读写。静态

progress.md

@@ -2,6 +2,24 @@
 
 ## 2026-07-30
 
+- 新增 `cmd/proxy-controller` 与公用 `controller/bootstrap.Run`；配置只加载一次，
+  同一快照用于存储连接、PostgreSQL 管理态提交和 HTTP Runtime 构造，避免启动
+  期间二次读取产生配置撕裂。
+- Bootstrap 已封装 PostgreSQL Ping/迁移/pgx Adapter、Redis Ping/活动池、
+  Distribution/Admin 服务构造、运行错误与关闭错误合并；`main` 仅处理
+  `-config`、`PROXY_POOL_CONFIG`、信号上下文和退出码。
+- 活动池新增公用 `StateInventoryReader`；Memory/Redis 使用同一契约，Redis
+  通过低基数 Hash 和五个原子 Lua 维护七类状态计数，不扫描 Proxy 明细。
+- 新增 `controller/operations.Reader`，把当前配置中的 Upstream 与活动状态映射到
+  Admin Status；Worker/Snapshot 与 Provider 统计尚无来源时保持空/零，不用
+  `Managed` 冒充 `Available`。
+- Redis 状态读取在有界过期清理仍有积压或检测到负计数时 fail-closed，避免
+  Admin 返回包含失效代理或损坏计数的成功响应。
+- 本轮全仓 `go test -count=1 -timeout 60s ./...`、`go vet ./...`、
+  `go build ./cmd/proxy-controller` 与 `git diff --check` 通过；新加的 Redis
+  backlog/负计数场景也已通过真实 Redis 8.2 fixture。
+- 新增 `test-controller.ps1` 双存储 fixture；真实 PostgreSQL 18 + Redis 8.2 已
+  通过迁移、启动配置提交、Redis Readiness 与 Admin Status 组合验证。
 - 固定 `github.com/jackc/pgx/v5 v5.6.0`，实现封装在 `adminstate.Store` 后的
   PostgreSQL 深适配器；配置、Upstream、Routing mutation 在同一事务中提交
   revision、管理状态、审计与 Outbox，数据库错误不泄漏 DSN、SQL 或参数。

task_plan.md

@@ -33,6 +33,9 @@
     和真实 PostgreSQL 18 集成测试已完成
 12. [进行中] 复核验收清单并收敛既有 Routing/Sequential 与 Proxy 容量边界；
     机器契约和文档类滞后勾选已按仓库证据校正
+13. [进行中] 落地 `proxy-controller` 进程装配；配置单次加载、PostgreSQL 迁移、
+    Redis 活动池、低基数状态聚合、Distribution/Admin 启动与关闭已完成，
+    双存储 bootstrap 集成已通过，Provider/Metrics 与完整 HTTP 进程链仍待实现
 
 ## 串并行关系
 
@@ -53,7 +56,8 @@
 
 - Docker Compose 配置与 Kubernetes Kustomize 已完成静态渲染验证；Redis 8.2
   与 PostgreSQL 18 的隔离 Adapter fixture 已运行，完整目标运行拓扑尚未启动。
-- `cmd/proxy-*`、PostgreSQL 管理面 Adapter、Provider Leader/分布式限流、
+- `cmd/proxy-controller` 已实现 Admin/Distribution 与双存储启动装配；Gateway、
-  Checker 运行时、Redis 故障转移验证与代表性集群压测属于后续实施范围。
+  Checker、Loadgen、Provider Leader/分布式限流、Metrics、Redis 故障转移验证与
+  代表性集群压测属于后续实施范围。
 - `implementation-plan.md` 当前按 73 个验收项统计；已校正为 51 项完成，
   验收项完成率约 69.9%，不等同于生产就绪度。