实现 SourceMessage Inbox 与 AgentBus 入站闭环

docs/project/backend-development-guidelines.md

@@ -72,22 +72,63 @@ integrations
 
 - `platform` 保存部门中立能力，例如消息、证据、AI 调用审计、Operation、Receipt、审计。
 - `workflows` 保存部门业务流程，当前明确的是 `reservation`。
-- `integrations` 保存外部系统适配器，例如 OHIP、SuperAgent、AgentBus。
+- `integrations` 保存外部系统适配器，例如 OHIP、SuperAgent、AgentBus；外部协议转换类应放入具体集成模块的 `adapter` 包。
 - 平台核心不得依赖预订部专有字段。
 - 部门工作流可以依赖平台核心，平台核心不能反向依赖部门模块。
 - 外部系统 DTO、Oracle DTO、Provider DTO、领域模型和 API Response 必须分离。
 - Oracle DTO 或生成代码只能位于 `integrations.ohip`，不得进入平台领域模型。
+- 外部协议到内部命令或 DTO 的转换类使用 `Adapter`、`Converter` 等能表达适配语义的后缀，不使用 `Mapper` 命名，避免和 MyBatis Mapper 混淆。
+
+当前项目后端模块内部目录强制按以下结构组织：
+
+```text
+<module>
+├── control
+├── service
+│   └── impl
+├── domain
+├── mapper
+├── repository
+└── common
+    ├── dto
+    ├── request
+    ├── result
+    └── enums
+```
+
+中文说明：
+
+| 目录 | 中文职责 | 放置内容 |
+| --- | --- | --- |
+| `control` | HTTP 入口层 | Controller 具体实现类，只处理请求契约、参数校验和响应映射 |
+| `service` | 服务契约层 | Service 接口，只表达模块对外提供的稳定业务能力 |
+| `service.impl` | 服务实现层 | Service 实现类，负责编排事务、幂等、Repository 和外部端口 |
+| `domain` | 数据实体层 | Entity 类，字段必须有中文注释，不能与 Response 或外部 DTO 混用 |
+| `mapper` | MyBatis 访问层 | Mapper 类和语义化 Mapper 方法，Controller 与 Service 不直接跨层暴露 Mapper |
+| `repository` | 持久化封装层 | Repository 接口和具体实现，对 Service 屏蔽 Mapper 与数据库细节 |
+| `common.dto` | 通用数据载体层 | 模块内部跨层传递的 DTO、快照、草稿等数据载体 |
+| `common.request` | 请求模型层 | Controller、Service 或外部适配器输入侧的 Request、Command、Query 条件 |
+| `common.result` | 结果模型层 | Service 或 Controller 输出侧的 Result、分页结果、操作结果 |
+| `common.enums` | 模块枚举层 | 本模块稳定业务枚举、状态码和失败原因枚举 |
+
+后续生成或移动 Java 代码时必须严格遵守上述目录，不再新增 `api`、`application`、`persistence` 等同义包来承载这些职责，除非先更新本规范并说明迁移原因。已有或迁移来的 `application` 包中的 Request、Result、DTO 类，应按语义移动到对应模块的 `common.request`、`common.result`、`common.dto`。如果类职责或目录归属不明确，必须先询问再继续。
 
 ## 4. Controller / Service / Repository 规则
 
 - Controller 只做 HTTP 契约、参数校验、权限入口和响应映射。
 - Controller 不直接访问 Mapper。
 - Controller 不直接调用外部适配器。
-- Application Service 编排事务、领域对象、Repository 和外部端口。
-- Domain 对象表达稳定业务语义，不引入 HTTP、JSON、MyBatis 或外部 Provider 细节。
-- Repository 是领域侧持久化接口。
-- Infrastructure / Persistence 负责 Entity、Mapper 和数据库细节。
+- Service 接口位于 `service` 包，表达模块对外提供的稳定业务能力。
+- Service 实现类位于 `service.impl` 包，编排事务、Entity、Repository 和外部端口。
+- Request、Command、Query 条件位于 `common.request` 包。
+- Result、分页结果、操作结果位于 `common.result` 包。
+- 跨层 DTO、Snapshot、Draft 等通用数据载体位于 `common.dto` 包。
+- Entity 位于 `domain` 包，表达数据库表字段与业务含义，不与 DTO、Response 或外部 Provider DTO 混用。
+- Mapper 位于 `mapper` 包，只负责本模块数据库表访问和语义化查询方法。
+- Repository 位于 `repository` 包，负责封装 Mapper 和数据库细节，作为 Service 的持久化边界。
 - 外部调用通过端口和 Adapter 隔离，业务层不依赖厂商 SDK 或厂商 DTO。
+- 外部协议适配类位于对应 `integrations.<capability>.<provider>.adapter` 包，负责把外部 DTO 或 JSON 转换为内部稳定命令。
+- 生成或迁移代码前必须先阅读本规范并查看同模块既有代码习惯；如果放置目录、类名后缀或依赖方向不确定，先询问再实现。
 
 ## 5. 数据建模规则
 
@@ -177,6 +218,10 @@ groupCode
 
 - 架构文档、设计文档、目录结构、数据模型、字段映射和接口示例必须优先使用中文说明业务含义。
 - 领域对象、应用服务、外部适配器、Controller、配置属性和复杂参数对象应说明业务含义、边界或调用约束。
+- `control`、`service`、`service.impl` 中的方法必须有中文注释，说明业务动作、调用边界、幂等或安全约束。
+- `mapper` 中 MyBatis-Plus 自带继承方法不强制补中文注释；不要为了重命名 `selectById`、`insert`、`updateById` 等自带方法而写薄 default 包装。本项目自定义的语义化查询、写入、更新方法应根据业务复杂度合理补充中文注释。
+- `domain` 中 Entity 的每个字段必须有中文注释，说明字段业务含义、来源、代码值范围或安全限制。
+- `repository` 中对外暴露的方法必须有中文注释，说明持久化语义和是否返回安全字段。
 - 复杂流程、幂等键、并发控制、事务边界、错误转换、外部系统字段映射和安全脱敏逻辑必须说明原因。
 - 注释不得只复述类名、方法名或字段名。
 - 不得用“TODO 待完善”替代真实说明。
@@ -239,6 +284,8 @@ cd server
 ./mvnw -Dtest=SomeFocusedTest test
 ```
 
+默认 `test` profile 使用 H2 MySQL Mode，保证普通测试不依赖本机 MySQL。需要连接真实测试 MySQL 时，使用 `test,test-mysql` profile，并通过 `TH_HOTEL_TEST_DB_URL`、`TH_HOTEL_TEST_DB_USERNAME`、`TH_HOTEL_TEST_DB_PASSWORD` 注入测试库连接信息。测试 MySQL 只能使用本地或 CI 测试库，不得连接生产库或包含真实酒店、客户、支付数据的数据库。
+
 如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。
 
 ## 16. Git 与协作流程
@@ -254,7 +301,13 @@ cd server
 ## 17. 后端提交前检查清单
 
 - [ ] 是否遵守 platform / workflows / integrations 分层？
+- [ ] 模块内部是否遵守 `control` / `service` / `service.impl` / `domain` / `mapper` / `repository` / `common.dto` / `common.request` / `common.result` / `common.enums` 目录规则？
 - [ ] Controller 是否没有直接访问 Mapper 或外部 Adapter？
+- [ ] Request、Result、DTO 是否放在 `common.request`、`common.result`、`common.dto`，而不是混在 `service` 或临时 `application` 包？
+- [ ] `control`、`service`、`service.impl`、`repository` 方法是否有中文注释？
+- [ ] Mapper 自定义语义化方法是否按复杂度合理补充中文注释，且未为了 MyBatis-Plus 自带继承方法强行加无意义注释？
+- [ ] 外部协议适配类是否放在 `integrations.<capability>.<provider>.adapter`，并避免使用 `Mapper` 命名混淆 MyBatis Mapper？
+- [ ] Entity 字段是否有中文注释？
 - [ ] 外部 DTO 是否没有进入领域模型？
 - [ ] 写接口是否有幂等、版本或审计设计？
 - [ ] Flyway SQL 是否有规范中文注释？