模块地图

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

四层一眼看懂

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

text

基石  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-*。

"新代码放哪儿"决策图

text

① 只服务一个具体业务？ ───────────────────────────────→ 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-* 模块。

命名迁移中

ADR-045 选定的目标命名正在分档落地，当前仓库仍有历史名，等价关系如下：

当前名	目标名	说明
~~`spring-open-starter-core`~~ / ~~`spring-open-common`~~	`spring-open-starter-common` ✅	基石位于 `spring-open-starters/spring-open-starter-common`，不是自动装配 starter；包名已统一为 `com.springopen.starter.common.*`
~~`spring-open-core-support`~~	`spring-open-core-runtime` ✅	B2 已完成（包 `com.springopen.core.support`→`com.springopen.core.runtime`，408 引用）："support" 易误读为客服（客服是 `spring-open-module-chat`）；当前 Runtime 仅保留开放 API contract、演示数据清理等运行时支撑，通知已拆入 `spring-open-core-notification`，文件 / 媒体资产已拆入 `spring-open-core-file`，异步任务 / CSV 导出已拆入 `spring-open-core-async-task`，Outbox / 补偿 / Webhook 已拆入 `spring-open-core-outbox`，内容安全已拆入 `spring-open-core-content-safety`，报表已拆入 `spring-open-core-reporting`，风控限额已拆入 `spring-open-core-risk`
`spring-open-core/*` 平铺	`spring-open-core/spring-open-core-*` ✅	B4 最终口径：去掉 platform / runtime 分组层，避免 `spring-open-core-runtime-services` 等扭曲命名；职责族只在文档中标注
~~`spring-open-core-integrations`~~	已删除 ✅	B1 已完成：跨核桥接迁回 owning core（money/audit/cashier/conversation/queue/scheduler，用户关系通知入 core-runtime），核心运行时改由 application 显式声明
`spring-open-core-system`（历史巨石）	`spring-open-core-config` ✅ + `spring-open-core-iam` ✅ + `spring-open-core-knowledge` ✅ + `spring-open-core-plugin` ✅ + 历史模块已删除 ✅	C 档主线已完成：配置、身份、Knowledge、Plugin 和运行时 / 业务卫星均拆到真实 owning module，业务不再通过 `core-system` 获取运行时 contract

历史迁移计划已归档到 .ai/tasks/archive/2026/06/2026-06-05-module-governance-v2-plan.md。当前模块事实以 ADR-045、本页和 .ai/architecture.md 为准。

模块地图 ​

四层一眼看懂 ​

"新代码放哪儿"决策图 ​

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

三条扩展路径 ​

护栏（结构不会再腐烂） ​