工程脚手架：Spring Boot 基座 + Doris 取数 + DataEase 集成边界（可独立运行）

[JIAQIA]

背景

为 tools-bi 建立可独立开发 / 编译 / 调试 / 运行的工程脚手架——数据工具（BI）分系统：报表 / 自助分析 / 可视化 / 可视化编排的后端能力与集成基座。大屏与图表前端在 webui（AntV），本仓不做编辑器前端。

依赖：主仓 libs-java HashMatrixData/hashmatrix#1。

任务清单（DoD）

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

• Maven 工程：<parent> + import BOM（Maven 坐标引用）；只 clone 本仓即可 mvn package
• Spring Boot 分层骨架；统一返回 / 异常 / 日志（starter-web、starter-audit）
• 多租户：starter-tenant，BI / 大屏按租户隔离取数
• 取数接线：Doris(OLAP) 客户端连通（占位查询，不建业务报表）
• 健康检查 / 可观测：Actuator + OpenTelemetry

测试与 Mock

• 复用 starter-test；Mock 数据脱敏（acme/tenant-demo）
• 单测 + 集成切片（Testcontainers 起 Doris 或以 mock 替身）

本地独立运行/调试

• docker-compose.local.yml（Doris/或替身）；Dockerfile；/actuator/health 通过

集成边界（DataEase）

• DataEase 集成纳入（非自研报表设计器）的接入约定占位：SSO + 租户上下文透传 + 部署级品牌外框（不按租户换肤）

交付汇入

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

约束

• 🔴 红线见 CLAUDE.md（公开仓，禁甲方信息，示例脱敏）。
• 取数依赖 data-foundation（Doris）；前端在 webui。

验收

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