feat: 定义 v1alpha1 API 合同

docs/api-reference.md

@@ -17,7 +17,10 @@
 - Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不超过 241 个字符，确保派生的
   `<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes DNS subdomain 的
   253 字符限制。
-- 默认值由 CRD defaulting 提供；需要读取旧值的校验由 CEL 或 webhook 完成。
+- port、TLS mode、deletion policy 等固定默认值由 CRD defaulting 提供。database、
+  loginRole、Secret 名称等依赖其他字段的值是 controller 语义默认值：字段保持省略，
+  controller 计算 effective value 并通过 status/受管资源展示，不引入 mutating webhook。
+- 需要读取旧值或跨字段的校验由 CEL 或 controller 完成。
 - `status` 由 controller 独占写入，禁止出现密码、Token、管理用户名或完整连接串。
 - 两个 Kind 都只承诺一个 `Ready` Condition；调用方不得依赖内部协调阶段。
 
@@ -91,6 +94,8 @@ Tenant 不声明 OpenBao mount 或 path。controller 使用部署级 mount/base
 | --- | --- | --- |
 | `status.observedGeneration` | int64 | 最近完成有结论协调的 generation |
 | `status.phase` | enum | controller 状态机的权威 checkpoint |
+| `status.database` | string | 应用语义默认值后的实际 database 名称 |
+| `status.loginRole` | string | 应用语义默认值后的实际 owner/login role 名称 |
 | `status.databaseOID` | uint32 | 回读的 database OID，仅供诊断 |
 | `status.credential.secretRef.name` | string | 同 namespace 目标 Secret 名称 |
 | `status.credential.openBaoURL` | string | 完整 KV v2 API URL，不含认证信息 |

docs/specification.md

@@ -131,6 +131,12 @@ Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不得超过 241
 派生的 ExternalSecret/Secret 默认名称
 `<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes 253 字符限制。
 
+固定默认值由 CRD defaulting 写入。依赖 `metadata.name` 或 `instanceRef` 的 database、
+login role、ExternalSecret/Secret 名称属于 controller 语义默认值：省略字段不会被 admission
+回写，controller 必须始终计算同一个 effective value，并通过 status 的 database、
+loginRole、credential reference 以及实际资源展示。
+v1alpha1 不为此引入 mutating webhook。
+
 database 和 role 名称必须作为 PostgreSQL identifier 参数安全引用，禁止通过字符串
 拼接执行。名称校验必须拒绝空字符串、NUL 和超过 PostgreSQL identifier 长度限制的
 值，并统一限制为小写字母、数字和下划线。