工程脚手架：Spring Boot 基座 + Flowable/Prometheus 接线（可独立开发/构建/运行）

[JIAQIA]

背景

为 security 建立可独立开发 / 编译 / 调试 / 运行的 Spring Boot 工程脚手架——数据安全分系统（分类分级 / 标签 / 审批 / 审计 / 资源监控）的基座。本 Issue 只做工程基座，不实现安全业务。

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

任务清单（DoD）

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

• Maven 工程：<parent> = hashmatrix-platform-parent + import BOM（Maven 坐标引用）；只 clone 本仓即可 mvn package
• Spring Boot 分层骨架（api/app/domain/infra）；统一返回 / 异常 / 日志（starter-web、starter-audit）
• 多租户：starter-tenant，权限 / 标签 / 审批租户内生效，任何查询默认带租户约束
• 工作流接线：Flowable 依赖与本地可起（不建业务流程）
• 资源监控：Prometheus 指标暴露；Actuator + OpenTelemetry
• 业务库：PostgreSQL 客户端连通

测试与 Mock（复用主仓约定）

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

本地独立运行/调试

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

交付汇入

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

边界

• 身份认证由 Keycloak / 网关负责，本仓只做授权与管控；不做治理元数据建模（governance）。
• 分类分级 / 安全标签策略归本仓；governance 仅透传权限要素+状态并应用本仓回写的标签做过滤（DG4/DG6）。

约束

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

验收

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