docs: 完善 v1alpha1 设计与运维合同

docs/development.md

@@ -1,6 +1,6 @@
 # 开发与测试环境
 
-本项目同时依赖 Kubernetes API、PostgreSQL 和 OpenBao。日常开发不连接 homelab
+本项目同时依赖 Kubernetes API、PostgreSQL、OpenBao 和 ESO。日常开发不连接 homelab
 中的真实服务：Kubernetes 使用 envtest 或一次性 Kind，另外两个依赖使用一次性
 容器。这样既避免污染真实数据，也能把启动顺序固化为命令。
 
@@ -25,11 +25,11 @@ container 的 Docker/Dev Container 环境。
 | 层次 | Kubernetes | PostgreSQL / OpenBao | 用途 |
 | --- | --- | --- | --- |
 | 单元测试 | fake client | fake client | SQL 计划、状态转换和错误分类 |
-| controller 集成测试 | envtest | fake 或 Docker | CRD、watch、status、finalizer |
+| controller 集成测试 | envtest | fake adapter | CRD、watch、status、finalizer、ExternalSecret 对象 |
 | adapter 集成测试 | 不需要 | Docker Compose | 真实协议、权限和幂等行为 |
-| E2E | 一次性 Kind | Kind 内测试实例 | 验证容器化 controller 与完整网络路径 |
+| E2E | 一次性 Kind + ESO | Kind 内测试实例 | 凭据投射、TLS、完整网络和删除路径 |
 
-envtest 只启动 API server 和 etcd，没有 kubelet、scheduler 或 controller-manager，
+envtest 只启动 API server 和 etcd，没有 kubelet、scheduler、ESO 或 controller-manager，
 因此不能用它验证 Deployment、Pod 调度或 Service 网络。此类行为必须留给 Kind
 E2E。
 
@@ -64,7 +64,11 @@ make lint
 `make test` 会下载与 `go.mod` 中 Kubernetes minor 版本匹配的 envtest 二进制，
 启动临时 API server/etcd，测试结束后自动关闭。
 
-### 2. 启动外部依赖
+规格实现后，快速测试必须覆盖默认值/校验、Condition `observedGeneration`、两个 CR 的
+status 状态机、不可变字段、extension 只追加、registry 所有权和外部错误分类。envtest 只断言 controller 创建了正确
+的 ExternalSecret；它不能证明 ESO 已生成 Secret。
+
+### 2. 启动 PostgreSQL/OpenBao adapter 依赖
 
 只有开发 PostgreSQL/OpenBao adapter 或完整 reconcile 时才需要：
 
@@ -99,6 +103,9 @@ POSTGRES_DEV_PORT=25432 OPENBAO_DEV_PORT=28200 make dev-up
 
 后续执行 `dev-smoke` 和 controller 时必须使用相同端口变量。
 
+Compose 使用明文 PostgreSQL/OpenBao dev 模式，不覆盖生产 TLS 合同。DNS SAN、IP SAN、
+Kubernetes auth、最小 policy 和 ESO 必须在 Kind E2E fixture 中验证。
+
 ### 3. 运行针对临时依赖的测试或 controller
 
 adapter 集成测试加入后，统一通过独立 Make target 执行，不默认塞进快速单元测试。
@@ -112,7 +119,9 @@ make install
 make run
 ```
 
-此时 controller 运行在开发容器内，可以直接访问上面的回环端口。不要把包含
+此时 controller 运行在开发容器内，可以直接访问上面的回环端口。若要验证 Tenant
+Ready，专用 Kind 还必须安装 ESO、创建测试 ClusterSecretStore，并让 Kind workload
+能够访问测试 OpenBao。不要把包含
 `127.0.0.1` 端点的样例部署到 Kind 内；Pod 中的回环地址只指向 Pod 自身。
 
 ### 4. 清理
@@ -127,22 +136,24 @@ make cleanup-test-e2e
 ## E2E 顺序
 
 CI 的 E2E 与本机 `make run` 不同：controller 会作为 Pod 运行在 Kind 中。因此完整
-E2E fixture 必须把测试 PostgreSQL 和 OpenBao也部署进 Kind，并等待两者 Ready 后
+E2E fixture 必须把测试 PostgreSQL、OpenBao 和 ESO 部署进 Kind，并等待依赖 Ready 后
 再创建 `PostgreSQLInstance` 和 `PostgreSQLTenant`：
 
 ```text
 创建 Kind
   -> 安装 CRD
-  -> 部署 PostgreSQL/OpenBao fixture
-  -> 等待依赖 Ready并写入测试管理凭据
+  -> 部署 PostgreSQL/OpenBao fixture，签发含 DNS/IP SAN 的测试证书
+  -> 安装 ESO，配置 OpenBao auth/policy 和 ClusterSecretStore
+  -> 等待依赖 Ready 并写入测试管理凭据
   -> 构建并加载 controller image
   -> 部署 controller
   -> 创建 Instance
   -> 等待 Instance Ready
   -> 创建 Tenant
   -> 等待 Tenant Ready
-  -> 验证 PostgreSQL catalog 与 OpenBao KV
-  -> 删除 Tenant并验证 Retain
+  -> 验证 registry、PostgreSQL catalog、OpenBao KV、ExternalSecret 和 Secret
+  -> 分别使用 DNS host 与 IP hostaddr 登录
+  -> 删除 Tenant 并分别验证 Retain 与 Delete（含故障点重试）
   -> 删除 Kind
 ```
 
@@ -150,6 +161,18 @@ E2E fixture 必须把测试 PostgreSQL 和 OpenBao也部署进 Kind，并等待
 manager Deployment 和 metrics endpoint。上述真实依赖 fixture 应与第一个完整
 reconcile 纵向切片一起实现，不能在文档中声称已经通过。
 
+## 测试数据与泄漏检查
+
+- 只使用显眼的固定 canary 测试密码，测试后扫描日志、Event、Condition、metrics 和
+  CR dump，出现 canary 即失败。
+- 每个最终一致性阶段都注入一次中断，重启后验证密码不变且阶段只向前推进。
+- 清空、落后或伪造超前的 `status.phase` 后验证它能从外部事实保守恢复/纠正，且不会
+  跳过任何回读。
+- 为未知同名 database、role、Bao record 和伪造 COMMENT 分别构造 Conflict。
+- Delete 在每个外部删除步骤失败后重试，确认未误删非当前 UID 资源。
+- 迁移测试按 [`migration.md`](migration.md) 完整执行，不以单纯 `pg_restore` 成功代替
+  应用读写和回滚验证。
+
 ## 故障排查
 
 查看依赖状态与日志：