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

README.md

@@ -9,9 +9,11 @@ OpenBao 凭据生命周期暴露为 Kubernetes API。
 ## 目标
 
 - 通过 `PostgreSQLInstance` 注册可管理的外部 PostgreSQL 实例。
-- 通过 namespaced `PostgreSQLTenant` 声明 database、owner、login 和扩展。
+- 通过 namespaced `PostgreSQLTenant` 声明 database、作为 owner 的 login role 和扩展。
 - 生成的密码只写入 OpenBao，不写入 CR、Event 或日志。
-- 使用 `status.conditions` 暴露持续 reconcile 的结果。
+- 通过 ExternalSecret 将七个原子连接字段投射到 Kubernetes Secret。
+- 为非 Kubernetes 消费者输出不含认证信息的 OpenBao API URL。
+- 使用 `status.phase` 展示进度，以 `status.conditions` 暴露可依赖的 reconcile 结果。
 - 默认使用 `Retain` 删除策略，避免删除 CR 时意外删除数据。
 - 允许 GitOps、Terraform、`kubectl` 和未来的 Backstage 使用同一套 API。
 
@@ -26,16 +28,19 @@ metadata:
 spec:
   instanceRef: shared
   database: netbox
-  ownerRole: netbox_owner
   loginRole: netbox
   extensions: [pg_trgm]
   credential:
-    openBaoPath: kv/k8s/netbox/database
+    secretName: netbox-postgresql
   deletionPolicy: Retain
 ```
 
-更完整的资源见 [`config/samples`](config/samples)，初始架构和安全边界见
-[`docs/architecture.md`](docs/architecture.md)。
+上例描述获批后的目标 API；`config/samples` 当前仍随旧 API 骨架保留，将在实现 API
+合同的同一改动中重新生成。系统架构见
+[`docs/architecture.md`](docs/architecture.md)。API、部署、安全、迁移和运维合同见
+[`docs/api-reference.md`](docs/api-reference.md)、
+[`docs/deployment.md`](docs/deployment.md)、[`docs/security.md`](docs/security.md)、
+[`docs/migration.md`](docs/migration.md) 和 [`docs/operations.md`](docs/operations.md)。
 
 系统已批准的规范性行为、验收标准和设计决策见
 [`docs/specification.md`](docs/specification.md)。
@@ -65,10 +70,10 @@ make run
 
 ## 路线
 
-1. 完成 CRD 校验、默认值和状态约定。
-2. 抽象 PostgreSQL 与 OpenBao client，用 fake 实现测试 reconciliation。
-3. 实现 database、owner role、login role、grant 和 extension 的幂等收敛。
-4. 实现带 finalizer 的 `Retain` / `Delete` 删除流程。
+1. 按已批准规格完成 CRD 校验、默认值和状态约定。
+2. 实现 PostgreSQL registry、OpenBao 和 ESO adapter 的测试替身及集成测试。
+3. 实现凭据、login owner、database、grant、extension 和 Secret 投射的幂等收敛。
+4. 实现并演练带 finalizer 的 `Retain` / `Delete` 删除流程和迁移 runbook。
 
 代码和 Gitea Actions 工作流预期托管在
 `git.ddupan.top/panxiao81/postgresql-tenant-operator`。