实现 SourceMessage Inbox 与 AgentBus 入站闭环

README.md

@@ -0,0 +1,75 @@
+# TH Hotel Simple
+
+TH Hotel Simple 是一个前后端分离的酒店业务协同项目。当前后端优先建设平台级 SourceMessage Inbox，用于接收 AgentBus 邮件来源事实，并为后续 AI 识别、人工复核、Case / Task 流程提供可追溯输入。
+
+## 目录说明
+
+```text
+client/
+后续前端应用目录。前端只调用本项目后端，不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。
+
+server/
+后端 Spring Boot 服务目录。后端负责数据库、外部系统适配、业务规则、安全脱敏和审计边界。
+
+docs/
+项目文档、可复用规范、当前项目需求和外部系统接入记录。
+```
+
+## 后端命令
+
+```bash
+cd server
+./mvnw test
+./mvnw verify
+./mvnw spring-boot:run
+```
+
+中文说明：
+
+- `./mvnw test`：运行后端单元测试和 Spring 集成测试。
+- `./mvnw verify`：运行 Maven verify 阶段，用于提交前完整检查。
+- `./mvnw spring-boot:run`：本地启动后端服务，默认端口为 `8080`。
+
+### 测试数据库配置
+
+默认 `test` profile 使用 H2 MySQL Mode，便于本地和 CI 在没有 MySQL 的情况下运行：
+
+```bash
+cd server
+./mvnw test
+```
+
+如需使用真实 MySQL 测试库，可启用 `test-mysql` profile，并通过环境变量注入连接信息：
+
+```bash
+cd server
+TH_HOTEL_TEST_DB_URL="jdbc:mysql://127.0.0.1:3306/th_hotel_test?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC" \
+TH_HOTEL_TEST_DB_USERNAME=th_hotel_test \
+TH_HOTEL_TEST_DB_PASSWORD=your-local-password \
+./mvnw test -Dspring.profiles.active=test,test-mysql
+```
+
+中文说明：`test-mysql` 仅用于连接本地或 CI 的测试库，不能填写真实酒店库、真实客户数据或生产凭证。
+
+## 当前健康检查
+
+```text
+GET /api/health
+```
+
+返回后端最小健康状态，用于本地开发、部署探活和前端连通性验证。
+
+## M001 SourceMessage Inbox
+
+当前实现 checkpoint 聚焦：
+
+- AgentBus Outlook payload 映射为平台稳定捕获命令。
+- SourceMessage Inbox 幂等落库。
+- 正文、HTML、原始 payload 和媒体 URL 分表保存。
+- 列表和普通详情接口只返回安全摘要。
+- `/api/source-messages/{id}/original` 通过受控访问 key 读取原文，并写入访问审计。
+- AgentBus WebSocket 长连接默认关闭，开启后只接收入站 frame 并写入 SourceMessage Inbox。
+- `/api/system/agentbus-probe` 返回 AgentBus 连接状态和安全计数器，不返回 Token 或原始 frame。
+- 缺少外部邮件 ID 的 payload 保存为 `FAILED`，错误摘要不暴露正文或 Secret。
+
+后续 checkpoint 再明确 SourceMessage Replay 到 MessageEvent / Evidence，以及具体业务页面展示位置。