模块地图

受众：开发者 摘要：一页看懂项目的四层结构、"新代码放哪儿"决策图、引擎↔控制台配对，以及"加能力 / 扩展底座 / 建业务"三条扩展路径。细节见 架构总览。

四层一眼看懂

名字即层次，从下到上单向依赖、无环：

基石  spring-open-starter-common        纯 Java 原语 / 值对象 / 契约。无 Spring/DB。被所有层依赖。     包 com.springopen.starter.common.*
能力  spring-open-starter-<cap>      可插拔技术引擎：Facade/Manager/Provider。【禁】@RestController / 业务表。  包 com.springopen.starter.<cap>
底座  spring-open-core-<x>           中性运行时底座，分两族：
        ├─ 平台域：config / iam / org / money / web3 / cashier / entitlement / voucher / conversation / notification / async-task / reporting / dict / i18n / template
        └─ 运行时服务 / 控制台：file / content-safety / runtime / queue / scheduler / database-backup / websocket / audit / sqlconsole / secret
业务  spring-open-module-<biz>       业务叶子（含你自己的业务）。互不依赖，跨业务走事件 / SPI / 标量 ID。  包 com.springopen.module.<biz>

依赖方向：starter-toolkit ← common ← starters ← core-* ← modules。业务模块只能向下依赖底座 / starter / 基石；底座绝不依赖业务模块。平台域和运行时服务是职责分类，物理上都直接挂在 spring-open-core/spring-open-core-*。

"新代码放哪儿"决策图

① 只服务一个具体业务？ ───────────────────────────────→ spring-open-modules/spring-open-module-<biz>
② 多业务复用 + 有自己的表 / REST / 迁移？
     ├ 业务语义中性的平台域？ ──────────────────────────→ spring-open-core/spring-open-core-<domain>
     └ 只是某 starter 引擎的管理面 / 运行时支撑？ ─────────→ spring-open-core/spring-open-core-<cap>
③ 纯技术能力、Provider 可插拔、无业务表 / REST？ ────────→ spring-open-starters/spring-open-starter-<cap>
④ 纯 Java 原语 / 值对象 / 契约、无 Spring？ ──────────────→ spring-open-starter-common

引擎 ↔ 控制台配对（同名不是重复）

跨层同名是成对设计：starter-<cap> 是可插拔引擎（无 REST），core-<cap> 是它的运维管理面（REST + DB + 迁移，依赖该 starter）。

能力	引擎（starter，0 Controller）	控制台 / 运行时（core，REST + DB）
queue	spring-open-starter-queue	spring-open-core-queue
scheduler	spring-open-starter-scheduler	spring-open-core-scheduler
websocket	spring-open-starter-websocket	spring-open-core-websocket
approval-workflow	spring-open-starter-approval-workflow	spring-open-core-approval-workflow
observability	spring-open-starter-observability	spring-open-core-observability
document	spring-open-starter-document	spring-open-core-document
web3	spring-open-starter-web3（链上 SDK 引擎）	spring-open-core-web3（钱包 / 资金链上域）
secret	spring-open-starter-secret-sdk	spring-open-core-secret

要加一条管理 REST？加在 core-<cap>，不要加进 starter。要换底层第三方实现？写 starter-<cap> 的 Provider，不动 core。

三条扩展路径

我的业务放哪？ → spring-open-modules/spring-open-module-<biz>，包 com.springopen.module.<biz>。按需 Maven 依赖底座（core-iam / core-money / core-cashier…）与 starter；不要依赖另一个业务模块——跨业务只走事件（Outbox）/ SPI / Provider / 标量 ID。

加一个技术能力？ → 一能力一 starter：spring-open-starter-<cap>，按 Facade → Manager → ConfigResolver → Provider SPI 四层。不写 Controller / 业务表；要管理面就再配一个 core-<cap> 控制台。

不改 core 做扩展？ → 底座只暴露中性 contract / SPI / Provider / 事件 / 标量 ID。在你的业务模块里实现底座的 SPI（如收银成功回调 CashierPaymentOrderSuccessHandler）、订阅底座事件、或注册 Provider；不要 fork 底座、不要把业务字段沉进通用实体。

护栏（结构不会再腐烂）

./.ai/scripts/check modules 静态校验并在 CI 兜底：

• starter 不得含 @RestController（引擎层禁 REST）；starter 顶层包统一使用 com.springopen.starter.*，如 spring-open-starter-webmvc 对应 com.springopen.starter.webmvc.*；
• core-* 不得 import com.springopen.module.*；module-* 不得 import 另一个 module-*；
• core-* 能力模块必须直接挂在 spring-open-core/ 下，不再新增 platform / runtime 分组聚合或嵌套 core-* 模块。

当前命名基线

• 纯 Java 基石统一为 spring-open-starter-common，包名为 com.springopen.starter.common.*。
• 运行时中性 contract 统一归属 spring-open-core-runtime。
• 所有 core 模块直接平铺在 spring-open-core/spring-open-core-*，不再设 platform / runtime 物理分组层。
• 跨核能力归属各自 owning core，不设 core-integrations；配置、IAM、Knowledge 和 Plugin 也均有独立 owning module。

当前事实以 Maven 聚合结构、ADR-045、架构总览 和本页为准；历史迁移过程从 Git 历史追溯。