工程脚手架：Connector SPI 多模块 + Flink/SeaTunnel 作业骨架（可独立运行）

[JIAQIA]

背景

为 data-foundation 建立可独立开发 / 编译 / 调试 / 运行的工程脚手架——数据底座（流批采集 + 湖仓 + 统一计算 + Connector SPI）。核心是把 Connector SPI 的"加插件不动主干"骨架先立起来（信创刚需收敛点）。

依赖：主仓 libs-java HashMatrixData/hashmatrix#1；设计见架构 03-技术选型 / 04-工程与部署。

任务清单（DoD）

Maven 多模块（独立可构建运行）

• connector-spi/：定义 SPI 接口（连接 / 元数据扫描 / 读写）
• connector-jdbc/：标准 JDBC 参考实现（PostgreSQL/MySQL）
• connector-dialect-*/：达梦 / 人大金仓 / OceanBase 方言插件占位（新增数据库 = 加一个插件 jar，不改主干）
• ingest/：Flink + Flink-CDC（流）/ SeaTunnel（批）作业骨架（本地 mini-cluster 可跑）
• app/：服务骨架，<parent> + import BOM + starter-tenant（Maven 坐标引用）；只 clone 本仓即可 mvn package

多租户与配额

• 采集 / 计算 / 湖仓按租户隔离 catalog/database（Doris/Paimon per-tenant）；作业受租户配额约束

测试与 Mock

• 复用 starter-test；Connector SPI 契约测试（参考实现）；Mock 数据脱敏（acme/tenant-demo）
• Flink 作业本地集成测试（Testcontainers / mini-cluster）

本地独立运行/调试

• docker-compose.local.yml（PG + MinIO + 可选 Doris/Kafka）；Dockerfile；健康检查通过

交付汇入

• Helm 子 chart 占位到主仓 deploy/charts/data-foundation → 关联 deploy：Helm umbrella + values 分层 + per-tenant 模板 + ESO hashmatrix#2
• CI：多模块构建 + 测试 + 镜像

边界

• 数据采集（本仓·主链路·搬行数据）≠ 元数据采集（governance·旁路·取结构）（AD-15）：二者共用 Connector SPI + 数据源统一管理，连接器只实现一次。

约束

• 🔴 红线见 CLAUDE.md（公开仓，禁甲方信息，示例脱敏）。

验收

只 clone 本仓 → mvn package（多模块）通过 → connector-jdbc 契约测试绿 → docker-compose up + Flink 样例本地跑通。

[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`、`icd/governance-metadata`

**如何查阅（随时拉最新，勿存本地副本）**：
- 在 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 无需降级。