控制平面服务初始化：租户开通编排（Helm SDK + K8s client）

[JIAQIA]

背景

多租户控制平面服务实现。设计见主仓 docs/00-主仓初始化-spec.md §2.3 与架构 05-多租户与控制平面。

核心定位：控制平面是一等 K8s 编排者，经 Helm SDK + Kubernetes client 命令式开通租户，生产期不依赖 Git/Argo。

任务清单（DoD）

工程基座（独立可构建运行）

• Spring Boot 服务骨架（<parent> + import BOM，Maven 坐标引用，见 libs-java：platform-parent + BOM + starter-tenant，发布 GitHub Packages hashmatrix#1）；只 clone 本仓即可 mvn package
• 本地独立运行/调试：docker-compose.local.yml 起依赖（PostgreSQL + Keycloak，K8s 用 kind/可 mock）；Dockerfile；/actuator/health 通过
• 复用主仓 starter-test（JUnit5 + Testcontainers）；Mock 数据脱敏（acme/tenant-demo）

控制平面业务

• 租户目录持久化（PostgreSQL）+ 状态机（registered→approving→provisioning→active→suspended→deleted）
• 开通流程：自助注册 → 审批门控 → 自动 provision
• Keycloak Admin API 集成：建 Organization + 管理员（+ 可选联邦客户 AD）
• K8s 编排：Helm SDK/CLI 包装 + Kubernetes Java client（建 namespace / ResourceQuota / NetworkPolicy / 服务实例）
• 数据开通：schema/db(PG) + Doris/Paimon catalog/database
• External Secrets Operator 注入租户 secrets
• 配额：ResourceQuota + 业务配额（用户数/数据量/作业数）硬限；metering 计费仅预留接口
• 单测 + 集成测试（开通时序端到端）

约束

• 🔴 红线见 CLAUDE.md（公开仓，禁甲方信息，示例脱敏）。
• 租户 provision 不耦合 Git/Argo；Argo 仅用于平台基座（可选）。
• 运营管理 UI 是 webui 的 apps/admin（管理平面），本仓只提供 API。

DoD

测试集群上 provision 一个 tenant-demo 全链路（身份 + namespace + schema/db + 服务实例 + secrets）打通。

[JIAQIA]

📦 公共依赖 libs-java 0.1.0 已发布 — 接入方式

主仓公共 Java 依赖（hashmatrix-platform-parent + hashmatrix-bom + starter-*）已发布到 GitHub Packages（见 Release libs-java-v0.1.0）。本仓脚手架请按 Maven 坐标接入——不依赖 submodule 路径，只 clone 本子仓即可构建（前提是能访问制品仓）。

1. <parent> + import BOM

<parent>
  <groupId>io.hashmatrix</groupId>
  <artifactId>hashmatrix-platform-parent</artifactId>
  <version>0.1.0</version>
  <relativePath/>           <!-- 留空：从制品仓解析，不依赖路径 -->
</parent>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.hashmatrix</groupId>
      <artifactId>hashmatrix-bom</artifactId>
      <version>0.1.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

2. 取用公共能力（依赖不写版本号，由 BOM 钉死）

<dependencies>
  <dependency><groupId>io.hashmatrix</groupId><artifactId>hashmatrix-starter-tenant</artifactId></dependency>
  <dependency><groupId>io.hashmatrix</groupId><artifactId>hashmatrix-starter-web</artifactId></dependency>
  <dependency>
    <groupId>io.hashmatrix</groupId><artifactId>hashmatrix-starter-test</artifactId><scope>test</scope>
  </dependency>
</dependencies>

• starter-tenant：TenantContextHolder.requireTenantId() 取当前租户（网关注入 X-Tenant-* 头自动透传，架构 05 §5）。
• starter-web：返回 ApiResponse.ok(data)；抛 BusinessException(status, code, msg)，由 GlobalExceptionHandler 统一转换。
• starter-test：JUnit5 + AssertJ + Mockito + Testcontainers + 脱敏 fixtures（MockTenants / MockData）。

3. 访问制品仓（一次性配置）

GitHub Packages Maven 拉取也需鉴权：~/.m2/settings.xml 配置带 read:packages 的 PAT（server id=github），并声明指向 https://maven.pkg.github.com/HashMatrixData/hashmatrix 的 repository。完整片段见 libs-java/README · 访问制品仓。

内网/信创交付：制品镜像到内网 Nexus/Artifactory，子仓指向私服或用 -Pxinchuang —— 见同 README「内网/信创交付」。

4. 验证「只 clone 子仓可构建」

mvn -q -DskipTests package

版本演进 & 🔴 红线

升级 = 改 BOM import 一行版本号（全模块同版本）。公开仓：POM/源码/示例不得含甲方信息，示例一律脱敏占位（acme / tenant-demo）。

关联主仓 #1（已交付）。接入遇阻可在此回帖。

[JIAQIA]

🔗 请把「契约」块加入本仓 CLAUDE.md（脚手架项）

平台已建立契约治理（主仓 contracts/）。为让本仓在 Claude Code/工程师工作时感知契约并随时查阅，请把下面块加入本仓 CLAUDE.md（producer/consumer 已按本仓填好，取自 contracts/registry.yaml）：

## 🔗 契约（Contracts）—— 跨子系统集成

本项目经**契约**与其它子系统集成。契约的**单一事实源在主仓** `HashMatrixData/hashmatrix` 的 `contracts/`：
- 索引（机器可读）`contracts/registry.yaml` · 规范 `contracts/CONVENTIONS.md` · 设计 `docs/architecture/06-契约治理.md`
- 在线：https://github.com/HashMatrixData/hashmatrix/tree/main/contracts

**铁律**：先改契约、再改实现；加法兼容默认放行，破坏性走 MAJOR + 弃用期双跑 + 通知消费方；消费方一律 tolerant reader。

**本仓契约**：
- producer：暂无
- consumer：`icd/tenant-context-headers`

**如何查阅（随时拉最新，勿存本地副本）**：
- 在 superproject（`hashmatrix/services/<本仓>`）下：直接读 `../../contracts/`。
- 独立 clone：WebFetch `https://raw.githubusercontent.com/HashMatrixData/hashmatrix/main/contracts/registry.yaml`（公开仓免鉴权）→ 按 registry 取对应契约；或 `gh api repos/HashMatrixData/hashmatrix/contents/contracts/<path> -H "Accept: application/vnd.github.raw"`。

标准块与全仓映射见主仓 contracts/integration.md；规范见 CONVENTIONS.md §7。契约规格请实时拉取，勿在本仓存副本。

[JIAQIA]

ℹ️ 依赖缺口已补齐（2026-06-18）

此前 libs-java v0.1.0 只发了 starter-web / starter-tenant / starter-test,缺 starter-audit、starter-observability,本 issue DoD 里「复用 starter-audit / starter-observability」无法照做。

现已补源头,两个 starter 已加入 libs-java 并通过 reactor 构建(7 模块全绿、单测通过):

• hashmatrix-starter-audit(hashmatrix.audit.*):统一 AuditEvent + AuditRecorder(默认 slf4j 结构化输出);审计事件自动加盖当前租户(取自 starter-tenant 的 TenantContextHolder),可被自定义 Bean 覆盖(如投递 Kafka 审计 topic)。
• hashmatrix-starter-observability(hashmatrix.observability.*):actuator 健康探针 + /actuator/prometheus 指标出口 + 平台公共指标标签;OTel 链路走部署期 Java agent(不绑代码)。

将随 libs-java v0.2.0 发布。本仓 import hashmatrix-bom 的版本 pin 到 v0.2.0 后,按 DoD 直接复用这两个 starter —— 缺口消除,DoD 无需降级。

[uniquehole]

✅ 本仓已对齐评论3 的依赖方针（commit 8725d42，PR #2）

• import hashmatrix-bom 0.1.0 → 0.2.0
• 复用 starter-audit / starter-observability
• actuator exposure 增加 prometheus（observability 指标出口）

⚠️ 前置依赖：当前本地 libs-java 检出仍为 0.1.0，无这两个 starter、无 0.2.0 制品；在 v0.2.0 正式发布（或本地 mvn install） 前，本仓 mvn package 会因解析不到 BOM 0.2.0 而失败，属预期（前瞻式提交，已在 README 标注）。v0.2.0 落地后即自动转绿。