docs: define Instance domain model and admin Secret boundary

docs/specification.md

@@ -4,7 +4,7 @@
 | --- | --- |
 | 状态 | Approved |
 | 目标 API | `database.ddupan.top/v1alpha1` |
-| 最后更新 | 2026-09-10 |
+| 最后更新 | 2026-09-13 |
 | 批准日期 | 2026-09-10 |
 | 规范范围 | 首次注册外部 PostgreSQL 实例并创建一个应用租户 |
 
@@ -75,7 +75,7 @@ v1alpha1 不负责：
 | controller 工作流阶段 | Kubernetes CR `status.phase` | 状态机 checkpoint；可由外部事实保守重建 |
 | 应用凭据 | OpenBao KV v2 | Kubernetes API 中不得出现明文 |
 | Kubernetes 凭据投射 | External Secrets Operator | ExternalSecret 由本 controller 管理 |
-| PostgreSQL 管理凭据 | OpenBao KV v2 | 由 `PostgreSQLInstance` 引用 |
+| PostgreSQL 管理凭据 | controller namespace 的 Kubernetes Secret | 管理员维护 ExternalSecret，由 ESO 同步；Instance 只引用 Secret |
 
 平台管理员管理 `PostgreSQLInstance`、controller 部署配置、OpenBao policy 和
 PostgreSQL 管理 role。应用或 GitOps 流程在获得 namespace RBAC 后管理
@@ -93,7 +93,7 @@ PostgreSQL 管理 role。应用或 GitOps 流程在获得 namespace RBAC 后管
 - PostgreSQL host、port 和管理连接使用的 database；
 - PostgreSQL host address，供无法解析 DNS 的消费者使用；
 - TLS mode；
-- PostgreSQL 管理凭据在 OpenBao 中的位置和字段名；
+- controller namespace 中 PostgreSQL 管理 Secret 的名称和字段名；
 - 租户允许申请的 extension 集合。
 
 实例 Ready 不代表 PostgreSQL 数据有备份或高可用，只表示 controller 当前可以安全
@@ -174,8 +174,15 @@ Token 禁止写入 Deployment、CR 或镜像。
 
 ### 8.2 管理凭据
 
-`PostgreSQLInstance` 只引用 PostgreSQL 管理用户名和密码所在的 OpenBao KV v2
-mount-relative path。controller 对该路径只需要读取权限。
+`PostgreSQLInstance` 只引用 controller 自身 namespace 中 Kubernetes Secret 的名称及
+用户名、密码字段名，不允许指定 namespace 或 Bao path。endpoint 仍由 Instance 声明。
+平台管理员维护 ExternalSecret，将 OpenBao 管理凭据同步到该 Secret；controller 只读
+Secret，不创建或修改管理 Secret、其 ExternalSecret 或上游管理凭据。
+
+Instance 管理连接不直接访问 Bao，不负责管理密码轮换。已装配的凭据仍可访问
+PostgreSQL 且满足 registry／权限要求时，Bao 或 ESO 暂时不可用不使 Instance NotReady。
+首次装配无法取得有效 Secret 时不能 Ready。Secret 内容更新如何触发连接刷新另行
+定义，本次不引入自动 PostgreSQL 密码轮换。Tenant 凭据管理仍直接依赖 Bao。
 
 ### 8.3 租户凭据
 
@@ -410,8 +417,9 @@ v1alpha1 不接管现有 database 或 role，但必须提供可重复、可回
    明文连接。
 3. PostgreSQL 管理 role 应使用满足本规格的最小权限，不应使用 PostgreSQL
    superuser；若 extension 安装需要额外权限，必须单独记录例外。
-4. OpenBao policy 必须限制为：读取已登记的管理凭据范围，以及创建/读取本 controller
-   管理的租户 KV 范围。
+4. controller 的 OpenBao policy 仅覆盖受管租户 KV 操作，不授予管理凭据路径权限。
+   管理凭据的 ESO 同步身份与应用凭据的 ESO 读取身份隔离。controller 只在自身
+   namespace 获得管理 Secret 读取权限，不因此扩大跨 namespace Secret data 访问范围。
 5. namespace 用户不得修改 cluster-scoped Instance。
 6. 所有 identifier、extension name 和引用字段必须在发起外部调用前校验。
 7. controller 不得通过 shell 或 `psql` 子进程执行用户输入。
@@ -435,7 +443,9 @@ v1alpha1 至少必须提供：
 实现 v1alpha1 第一条完整纵向切片前，测试必须覆盖：
 
 1. 有效 Instance 可以建立 TLS 管理连接并变为 Ready。
-2. PostgreSQL 或 OpenBao 暂时不可用时 Ready=False，恢复后自动变为 Ready。
+2. PostgreSQL 管理能力不可用时 Instance Ready=False，恢复后自动变为 Ready；已有
+   管理凭据可正常使用时，Bao／ESO 故障不单独影响 Instance Ready。首次装配缺少有效
+   管理 Secret 时不能 Ready；Tenant 的 Bao 操作失败按其自身依赖故障报告。
 3. 有效 Tenant 创建 database、作为 owner 的 login、grant、extension 和 OpenBao
    记录。
 4. 应用凭据可以实际连接且不能创建其他 database/role。
@@ -496,6 +506,10 @@ v1alpha1 至少必须提供：
 
 ## 17. 批准状态
 
+2026-09-13 已确认管理连接修订：Instance 引用 controller namespace 内的管理 Secret，
+管理员维护 ExternalSecret，由 ESO 同步；controller 不再从 Bao 直接读取管理凭据。
+此项是已批准行为，现有 API types 与实现尚待后续修改。
+
 具体设计决策和本文整体已于 2026-09-10 获得批准，可以进入 API reference、测试和
 实现阶段。同日确认状态机修订：两个 CR 的 `status.phase` 是 controller 工作流的权威
 checkpoint；PostgreSQL registry 只承担所有权、安装身份和保留状态。