docs: 明确凭据路径与 Secret 命名

docs/specification.md

@@ -127,6 +127,10 @@ Tenant 的 namespace 用于 Kubernetes RBAC 和身份识别，不代表 PostgreS
 | login role | `metadata.name` | 同一 Instance 全局唯一 |
 | deletion policy | `Retain` | `Retain` 或 `Delete` |
 
+Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不得超过 241 个字符，确保
+派生的 ExternalSecret/Secret 默认名称
+`<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes 253 字符限制。
+
 database 和 role 名称必须作为 PostgreSQL identifier 参数安全引用，禁止通过字符串
 拼接执行。名称校验必须拒绝空字符串、NUL 和超过 PostgreSQL identifier 长度限制的
 值，并统一限制为小写字母、数字和下划线。
@@ -169,9 +173,11 @@ mount-relative path。controller 对该路径只需要读取权限。
 
 ### 8.3 租户凭据
 
-Tenant 不声明凭据 path。controller 根据部署级 KV mount、base path 和 Tenant identity
-推导唯一的 mount-relative path。推导结果禁止以 `/` 开头，禁止包含空路径段、`.`、
-`..`，也禁止把 KV v2 HTTP API 的 `data` 或 `metadata` 层编码进路径。
+Tenant 不声明凭据 path。controller 根据部署级 KV mount、base path 和 Tenant 的
+namespace/name 推导唯一的 mount-relative path。base path 来自 controller 启动参数
+`--openbao-tenant-base-path`，默认 `postgresql-tenants`。最终路径为
+`<base-path>/<namespace>/<metadata.name>`。推导结果禁止以 `/` 开头，禁止包含空路径段、
+`.`、`..`，也禁止把 KV v2 HTTP API 的 `data` 或 `metadata` 层编码进路径。
 
 新 Tenant 的凭据建立顺序必须可从任意中断点恢复：
 
@@ -216,8 +222,11 @@ sslmode
 ### 8.4 凭据输出与 ExternalSecret
 
 controller 必须根据部署级 base path 推导 Tenant 的 KV path，Tenant 不能选择 mount 或
-任意远端路径。Tenant 可以指定目标 Kubernetes Secret 名称；省略时默认为
-`<tenant-name>-postgresql`。
+任意远端路径。ExternalSecret 固定命名为
+`<instanceRef>-<metadata.name>-postgresql`。Tenant 可以通过
+`spec.credential.secretName` 指定目标 Kubernetes Secret 名称；省略时使用同一默认名。
+自定义名称只需是合法 Kubernetes Secret 名称，不限制命名内容；两者均与 Tenant 位于
+同一 namespace。
 
 controller 必须创建同 namespace ExternalSecret，从固定的 ClusterSecretStore 读取七个
 原子字段。ExternalSecret 及目标 Secret 的名称通过 Tenant status 暴露。controller
@@ -457,8 +466,9 @@ v1alpha1 至少必须提供：
 - v1alpha1 不接管任意现有资源，但必须提供并演练 dump/restore 迁移路径。
 - v1alpha1 同时实现默认 `Retain` 和显式 `Delete`；Delete 必须有 finalizer、所有权验证
   和完整清理路径。
-- OpenBao KV v2 mount 和 base path 是 controller 部署配置，mount 默认 `kv`；Tenant
-  不能选择 mount 或任意远端 path，controller 根据 Tenant identity 推导记录路径。
+- OpenBao KV v2 mount 和 base path 是 controller 部署配置，mount 默认 `kv`，base path
+  由 `--openbao-tenant-base-path` 配置并默认 `postgresql-tenants`；Tenant 不能选择 mount
+  或任意远端 path，controller 根据 namespace/name 推导记录路径。
 - 租户 KV 记录固定写入 `username/password/database/host/hostaddr/port/sslmode` 七个
   原子字段；
   controller 不生成连接 URI，应用负责映射和拼装自身配置。
@@ -493,7 +503,8 @@ checkpoint；PostgreSQL registry 只承担所有权、安装身份和保留状
 - 增加 controller 部署级 OpenBao KV mount 和 TLS 配置；
 - 增加部署级 OpenBao consumer address、ClusterSecretStore 和 KV base path 配置；
 - 删除独立 `ownerRole` 字段，使 login role 成为 database owner；
-- 为 Instance 增加 `hostaddr`，为 Tenant 增加目标 Secret 配置及凭据输出 status；
+- 为 Instance 增加 `hostaddr`，为 Tenant 增加目标 Secret 配置及 Secret/Bao URL 输出
+  status；
 - 按已确认的 identifier 合同收紧校验；
 - 增加 PostgreSQL controller registry，记录基于 UID 的所有权、安装身份和保留状态；
 - 修正凭据 type 中遗留的 rotation 注释；