# Ineed-Core 模块能力地图

## 文档定位

本文档说明的是“开发者视角的能力与分层地图”，重点回答：

- 应该从哪条主链路进入框架
- `Controller -> Service -> Manager -> Repository/EntityManager` 各层分别落在哪些模块
- 当前哪些能力线是稳定推荐入口

它不是根 `pom.xml` 的完整 Maven 模块清单。

如果你要核对真实模块名、聚合层级和当前 `pom.xml` 声明，请同时阅读 [module-inventory.md](module-inventory.md)。
如果你要确认当前代码状态、测试入口和已知缺口，请同时阅读 [current-implementation-status.md](current-implementation-status.md)。

## 能力分层地图

### 共享契约与基础支撑

- `ineed-core-base`
  提供通用基础设施与共享契约，包括异常、上下文、结果模型、查询参数、AO / VO 等基础类型。
- `ineed-core-data-base`
  提供跨数据栈复用的数据基础抽象，作为数据能力的公共底座。
- `ineed-core-httpclient`
  提供 HTTP Client 请求、响应与执行器共享契约，供阻塞式和响应式实现共同复用。
- `ineed-core-socketaccess`
  提供 Socket 接入共享契约，供阻塞式和响应式实现共同复用。
- `ineed-core-context`
  提供阻塞式主链路所需的上下文支撑能力。
- `ineed-integration`
  提供内部事件、蒸馏事件、事件开关、默认事件 key 解析与 Spring 事件发布能力。
- `ineed-core-datasource`
  提供动态数据源相关支撑。当前已进入聚合模块，但 lookup key 解析仍未完成真实路由实现，因此不能把它视为已经可用的多数据源方案。
### 阻塞式业务主链路

- `ineed-core-service-cache`
  提供基于 Spring Cache 的服务缓存契约、租户隔离键、缓存成员索引和事务提交后失效协调；`ineed-core-engine` 直接依赖该模块。
- `ineed-core-engine`
  承载 `Service` / `Manager` 这一层的业务编排与标准能力接口，是当前阻塞式主路径的核心桥接层。
- `ineed-core-webmvc`
  提供阻塞式 Web API 入口，对外暴露标准 Controller 接口和统一返回模型。
- `ineed-core-data-core`
  提供 CRUD、查询、状态、排序、删除等共享数据能力支撑。
- `ineed-core-data-jpa`
  提供基于 JPA / QueryDSL 的阻塞式数据实现。
- `ineed-core-data-jdbc`
  提供基于 Spring Data JDBC 的阻塞式数据实现。
- `ineed-core-data-mybatis-flex`
  提供基于 MyBatis-Flex 的阻塞式数据实现。
- `ineed-core-data-mongodb`
  已进入当前聚合模块，提供 MongoDB 数据实现支撑；但它不是当前业务开发的优先推荐主链路。
- `ineed-core-httpclient-jdk`
  提供 JDK 阻塞式 HTTP Client 实现。
- `ineed-core-httpclient-okhttp`
  提供 OkHttp 阻塞式 HTTP Client 实现。
- `ineed-core-socketaccess-jdk`、`ineed-core-socketaccess-nio`、`ineed-core-socketaccess-netty`
  提供阻塞式 Socket 接入实现。

### 响应式扩展能力线

- `ineed-core-context-reactive`
  提供响应式链路的上下文支撑。
- `ineed-core-service-cache-reactive`
  提供基于 Reactive Redis 的响应式服务缓存、租户隔离键和响应式事务提交后失效协调；`ineed-core-engine-reactive` 直接依赖该模块。
- `ineed-core-engine-reactive`
  提供响应式 `Service` / `Manager` 编排能力。
- `ineed-core-webflux`
  提供响应式 Web API 入口。
- `ineed-core-data-core-reactive`
  提供响应式数据能力的公共支撑。
- `ineed-core-data-r2dbc`
  提供基于 R2DBC 的响应式数据实现。
- `ineed-core-httpclient-reactive`
  提供响应式 HTTP Client 执行器共享契约。
- `ineed-core-httpclient-webclient`
  提供基于 Spring WebClient 的响应式 HTTP Client 实现。
- `ineed-core-socketaccess-reactor-netty`
  提供基于 Reactor Netty 的 Socket 接入实现。

### 构建、测试与配套支撑

- `ineed-core-tests`
  聚合框架验证模块，是当前主链路回归验证的测试入口。
- `ineed-core-starters`
  当前只提供 starter 级别的依赖聚合，不包含 ineed 自定义自动配置入口。
- `ineed-core-bom`
  提供 BOM 依赖对齐能力。BOM 管理的 artifact 不完全等同于根聚合 `pom.xml` 当前声明的模块。
- `ineed-rdb-metadata`
  提供数据库元数据分析与读取支撑。

## 分层关系

当前标准开发主路径仍然是：

`Controller -> Service -> Manager -> Repository/EntityManager`

对应到当前代码树，可以理解为：

- `Controller`
  主要位于 `ineed-core-webmvc`，负责对外暴露 API、参数校验、权限注解和统一返回。
- `Service`
  主要位于 `ineed-core-engine`，负责事务边界和业务编排。
- `Manager`
  主要位于 `ineed-core-engine` 的接口层，并由 `ineed-core-data-core` 与各数据栈实现共同承接具体能力。
- `Repository/EntityManager`
  主要位于 `ineed-core-data-jpa`、`ineed-core-data-jdbc`、`ineed-core-data-mybatis-flex` 等具体数据模块中。

响应式对等链路使用 `ineed-core-webflux`、`ineed-core-engine-reactive`、`ineed-core-data-core-reactive` 和 `ineed-core-data-r2dbc`。它们用于维护 reactive 能力线。业务开发验收应先保证阻塞式主链路成立；如果需求或公共能力要求同步响应式，则在阻塞式基线成立后继续补齐 `webflux / r2dbc` 对等能力。

服务缓存同样按运行时分开：阻塞式链路使用 `ineed-core-service-cache`，响应式链路使用 `ineed-core-service-cache-reactive`。两者保留相同的服务缓存概念与注解名称，但拥有独立实现和依赖图，不能把其中一套作为另一套的运行时依赖。

## 对外开发常用入口

### Web 层入口

- `ineed-core-webmvc`
  当前对外开发最常用的 Web 入口，适合标准阻塞式业务 API。
- `ineed-core-webflux`
  响应式入口，当前可以作为能力认知参考，但不是当前推荐主路径。

### Service / Manager 入口

- `ineed-core-engine`
  当前标准 `Service` / `Manager` 能力入口所在模块，是业务主路径的桥接中心。

### 数据栈入口

- `ineed-core-data-jpa`
  当前稳定的 JPA 数据实现。
- `ineed-core-data-jdbc`
  当前稳定的 JDBC 数据实现。
- `ineed-core-data-mybatis-flex`
  当前稳定的 MyBatis-Flex 数据实现。

### 模块声明入口

如果要确认“这些模块在当前仓库里是否真实存在、由哪个聚合 `pom.xml` 声明”，不要只看本文档，应继续看 [module-inventory.md](module-inventory.md)。

## 当前稳定能力边界

四条关系型业务路径都有当前源码与框架测试入口；适用范围与执行证据见[运行时矩阵](../concepts/runtime-matrix.md)。不要把“声明模块”“通过契约测试”和“真实数据库/应用完成验收”混为同一状态。

新业务模块、公共能力和代码生成任务，如果需求没有明确限定范围，应按[业务骨架](../project-development/business-module-layout-guide.md)评估并对齐目标技术栈。MongoDB、未聚合的 Elasticsearch 和动态数据源能力另按已知边界处理。

特别说明：

- `ineed-core-datasource` 已接入聚合，但动态 lookup key 仍是占位实现。
- `ineed-core-service-cache` 与 `ineed-core-service-cache-reactive` 已分别进入阻塞式、响应式聚合和 BOM；选择模块时必须与 `engine` / `engine-reactive` 运行时一致。
- `ineed-core-data-elasticsearch` 目录存在，但在 `ineed-core-modules/pom.xml` 中仍处于注释状态。
- `ineed-core-starters/ineed-starter-druid` 是依赖聚合 starter，不是框架自动配置 starter。

## 关键接口锚点

- `ineed-core-modules/ineed-core-webmvc/src/main/java/com/ineed/core/webmvc/support/crud/ICreateController.java`
  标准创建入口，对外暴露保存 API，并在 Web 层完成参数校验和统一返回。
- `ineed-core-modules/ineed-core-webmvc/src/main/java/com/ineed/core/webmvc/support/search/ISearchController.java`
  标准查询入口，把 `CommonParameters` 和查询对象组装为 `QueryParameters` 后交给 Service。
- `ineed-core-modules/ineed-core-engine/src/main/java/com/ineed/core/service/crud/ICreateService.java`
  创建服务入口，负责把 create 请求桥接到对应的 Manager。
- `ineed-core-modules/ineed-core-engine/src/main/java/com/ineed/core/service/search/ISearchService.java`
  查询服务入口，负责承接查询请求并转发到搜索 Manager。
- `ineed-core-modules/ineed-core-engine/src/main/java/com/ineed/core/manager/crud/ICreateManager.java`
  创建能力的 Manager 契约，是业务创建逻辑的主要落点之一。
- `ineed-core-modules/ineed-core-engine/src/main/java/com/ineed/core/manager/search/ISearchManager.java`
  查询能力的 Manager 契约，是标准 query 实现的核心入口。

> 最后核验：2026-09-19