实现 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 要避免返回过宽字段。

docs/import/reusable/backend-development-guidelines.md

@@ -33,13 +33,19 @@ server/src/main/java/<base_package>
 ├── config
 ├── modules
 │   └── <business-domain>
-│       ├── controller
+│       ├── control
 │       ├── service
 │       ├── service/impl
 │       ├── domain
 │       ├── mapper
-│       └── repository
+│       ├── repository
+│       └── common
+│           ├── dto
+│           ├── request
+│           ├── result
+│           └── enums
 ├── integrations
+│   └── <capability>/<provider>/adapter
 └── support
 ```
 
@@ -52,6 +58,8 @@ server/src/main/java/<base_package>
 - 跨模块调用优先通过 Service、Port、API 契约或事件完成。
 - 禁止直接访问其他模块的 Mapper、Entity 或内部实现。
 - 外部系统通过 `integrations` 或 Adapter 隔离，业务层只依赖稳定端口。
+- 外部协议适配类放在具体集成模块的 `adapter` 包，例如 `integrations.<capability>.<provider>.adapter`。
+- 外部协议转换类使用 `Adapter`、`Converter` 等后缀，不使用 `Mapper` 命名，避免和 MyBatis Mapper 混淆。
 - 外部 DTO、数据库 Entity、领域对象和 API Response 必须分离。
 - 公共代码只有在出现真实重复和稳定语义后再抽取。
 
@@ -64,6 +72,11 @@ server/src/main/java/<base_package>
 - Repository 是领域侧持久化接口。
 - Mapper / Entity / SQL 属于持久化细节，不应向上泄漏到 API 层。
 - 外部调用通过 Port / Adapter 隔离，业务层不依赖厂商 SDK 或厂商 DTO。
+- Request、Command、Query 条件建议放在模块内 `common.request`。
+- Result、分页结果、操作结果建议放在模块内 `common.result`。
+- 跨层 DTO、Snapshot、Draft 等通用数据载体建议放在模块内 `common.dto`。
+- 枚举、状态码和失败原因建议放在模块内 `common.enums`。
+- 生成或迁移代码前应先阅读项目规范并查看同模块既有代码习惯；目录归属、类名后缀或依赖方向不明确时，先询问再实现。
 
 ## 5. 数据建模规则
 
@@ -128,6 +141,8 @@ Secret 只能通过环境变量、本地 `.env` 或部署平台 Secret 注入。
 
 - 架构文档、设计文档、目录结构、数据模型、字段映射和接口示例必须优先使用中文说明业务含义。
 - 领域对象、应用服务、外部适配器、Controller、配置属性和复杂参数对象应说明业务含义、边界或调用约束。
+- Mapper 中 ORM 自带继承方法不强制补中文注释；不要为了重命名 `selectById`、`insert`、`updateById` 等自带方法而写薄包装。自定义语义化查询、写入、更新方法应根据业务复杂度合理补充中文注释。
+- Entity 字段建议有中文注释，说明字段业务含义、来源、代码值范围或安全限制。
 - 复杂流程、幂等键、并发控制、事务边界、错误转换、外部字段映射和安全脱敏逻辑必须说明原因。
 - 注释不得只复述类名、方法名或字段名。
 - 不得用“TODO 待完善”替代真实说明。
@@ -164,11 +179,15 @@ cd server
 - 修改接口前确认领域模型、字段映射、前端影响和测试范围。
 - 不修改与当前任务无关的用户变更。
 - 修改后运行项目已配置的检查命令。
+- 生成或迁移代码前先参考当前项目代码规范和既有代码习惯；如果目录归属或命名不确定，先确认再继续。
 - Git commit message 使用中文，清楚说明本次提交的业务或技术变更。
 
 ## 13. 后端提交前检查清单
 
 - [ ] Controller 是否没有直接访问 Mapper 或外部 Adapter？
+- [ ] Request、Result、DTO 是否按语义放在 request、result、dto 目录，而不是混在 Service 或临时 application 包？
+- [ ] 外部协议适配类是否放在 integrations 的 adapter 包，并避免使用 Mapper 命名混淆 ORM Mapper？
+- [ ] Mapper 是否没有为了 ORM 自带继承方法写薄 default 包装？
 - [ ] 外部 DTO 是否没有进入领域模型？
 - [ ] DTO、Entity、Domain、Response 是否没有混用？
 - [ ] 跨模块调用是否通过稳定接口完成？