工程脚手架：Spring Boot 基座 + DolphinScheduler/Flowable 接线（可独立运行）

[JIAQIA]

背景

为 platform-common 建立可独立开发 / 编译 / 调试 / 运行的 Spring Boot 工程脚手架——平台横切公共能力（作业调度 / 工作流引擎 / 统一元数据）的基座。注意职责边界：不做租户生命周期/开通（那是 control-plane）。

依赖：主仓 libs-java HashMatrixData/hashmatrix#1；starter-tenant 契约在此与 libs-java 对齐。

任务清单（DoD）

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

• Maven 工程：<parent> + import BOM（Maven 坐标引用）；只 clone 本仓即可 mvn package
• Spring Boot 分层骨架；统一返回 / 异常 / 日志（starter-web、starter-audit）
• 多租户：starter-tenant 透传，公共能力租户感知、不做跨租户默认共享
• 调度接线：DolphinScheduler 可起（不建业务作业）
• 工作流接线：Flowable 可起
• 健康检查 / 可观测：Actuator + OpenTelemetry；业务库 PostgreSQL 连通

测试与 Mock

• 复用 starter-test；Mock 数据脱敏（acme/tenant-demo）
• 单测 + 集成切片（Testcontainers 起 PG）

本地独立运行/调试

• docker-compose.local.yml（PG + 可选 DolphinScheduler/Flowable 依赖）；Dockerfile；/actuator/health 通过

交付汇入

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

约束

• 🔴 红线见 CLAUDE.md（公开仓，禁甲方信息，示例脱敏）。
• 不做租户开通/配额/生命周期（control-plane）；不做单一分系统业务逻辑。

验收

只 clone 本仓 → mvn package 通过 → docker-compose up → 启动 /actuator/health 200 → 单测+集成测试绿。

[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 无需降级。

[uniquehole]

🔧 工程脚手架已开 draft PR：#2（Closes #1）

本次范围（buildable-core）：Maven 基座（<parent> + import hashmatrix-bom，坐标引用，只 clone 本仓即可构建）+ Spring Boot 分层骨架（统一返回/异常、租户感知透传、审计/可观测 starter 接线）+ Actuator 健康探针 + PostgreSQL 连通 + 单测/Testcontainers 集成切片 + docker-compose.local.yml + Dockerfile + 契约块入 CLAUDE.md。

依赖门控：依赖 pin 到 libs-java v0.2.0（含 starter-audit / starter-observability）。v0.2.0 发布到 GitHub Packages 前，mvn package 无法解析 parent/bom/audit/observability，CI 预期红——故 PR 暂为 draft；v0.2.0 就绪后转 ready 即绿，无需改本仓代码。

有意推迟到后续 pass：DolphinScheduler / Flowable 深度接线、CI workflow、主仓 deploy/charts/platform-common Helm 占位（HashMatrixData/hashmatrix#2）。

隔离上下文 code-reviewer 子代理审查：APPROVE，零阻塞项；红线合规（无甲方信息/IP/凭据）。