实现 SourceMessage Inbox 与 AgentBus 入站闭环

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 是否没有混用？
 - [ ] 跨模块调用是否通过稳定接口完成？