实现 SourceMessage Inbox 与 AgentBus 入站闭环

docs/import/reusable/backend-base-structure-pagination-guidelines.md

@@ -38,25 +38,33 @@ server/src/main/java/<base-package>/
 ├── service/
 │   ├── XxxService.java
 │   └── impl/XxxServiceImpl.java
-├── api/
+├── control/
 │   └── XxxController.java
-├── dto/
-│   ├── XxxCreateRequest.java
-│   ├── XxxUpdateRequest.java
-│   └── XxxQueryRequest.java
-└── vo/
-    └── XxxResponse.java
+├── repository/
+│   └── XxxRepository.java
+└── common/
+    ├── request/
+    │   ├── XxxCreateRequest.java
+    │   ├── XxxUpdateRequest.java
+    │   └── XxxQueryRequest.java
+    ├── result/
+    │   └── XxxResult.java
+    ├── dto/
+    │   └── XxxSnapshot.java
+    └── enums/
+        └── XxxStatus.java
 ```
 
 规则：
 
 - `platform` 放通用能力。
 - `workflows` 放业务流程。
-- `integrations` 放外部系统适配器。
+- `integrations` 放外部系统适配器；外部协议适配类建议放在 `integrations/<capability>/<provider>/adapter`。
 - 平台层不得依赖具体业务流程。
 - 业务层不得直接依赖外部系统 DTO。
 - Controller 不直接访问 Mapper。
 - 前端不直接调用外部系统。
+- 外部协议到内部命令或 DTO 的转换类使用 `Adapter`、`Converter` 等后缀，不使用 `Mapper` 命名，避免和 MyBatis Mapper 混淆。
 
 ## 3. 低耦合与可维护性
 
@@ -71,6 +79,7 @@ server/src/main/java/<base-package>/
 - 跨模块调用通过 Service、Port、API 契约或事件完成，不直接访问对方 Mapper、Entity 或私有工具类。
 - Controller 只调用本模块或明确授权的应用服务，不跨层访问 Mapper 或 Adapter。
 - Mapper 只负责本聚合或本表的数据访问，不承载跨业务编排。
+- 不为了重命名 MyBatis-Plus 自带方法而在 Mapper 中写薄 default 包装；语义化查询优先放在 Repository 或确有必要的自定义 Mapper 方法中。
 - 公共能力先放在业务模块内，出现真实重复和稳定语义后再提升到 `platform`。
 - 不为少量相似代码提前抽象大而全的 `CommonService`、`CommonUtil` 或通用模型。
 - 当修改一个模块会牵动多个无关模块时，应优先检查依赖方向和接口边界。
@@ -269,6 +278,7 @@ XxxQueryRequest
 规则：
 
 - 不使用一个大而全的 `Bo` 承载所有场景。
+- Request、Command、Query 条件建议放在模块内 `common/request`。
 - 创建、更新、查询参数分开。
 - 使用 Bean Validation 做基础校验。
 - 查询对象可以包含分页、排序、时间范围等条件。
@@ -289,6 +299,7 @@ XxxQueryRequest
 - Long ID 返回给前端时按字符串处理。
 - 时间统一按 API 规范格式化。
 - 列表接口使用统一分页响应。
+- Result、分页结果、操作结果建议放在模块内 `common/result`；跨层 DTO、Snapshot、Draft 建议放在模块内 `common/dto`。
 
 ## 10. Mapper 规范
 
@@ -312,6 +323,8 @@ public interface BaseMapperPlus<M, T, V> extends BaseMapper<T> {
 - Mapper 只负责数据库访问。
 - 复杂业务判断不放在 Mapper。
 - 优先使用 MyBatis-Plus Wrapper。
+- MyBatis-Plus 自带的 `selectById`、`insert`、`updateById` 等继承方法不需要额外 default 包装。
+- 自定义 default 方法只有在表达明确业务语义且能减少真实重复时才添加，不能只是改名转调。
 - 手写 SQL 必须使用 `#{}` 参数绑定。
 - 禁止使用 `${}` 拼接业务参数。
 - 手写 SQL 要避免返回过宽字段。