# TH Hotel Simple

TH Hotel Simple 是一个前后端分离的酒店业务协同项目。当前后端优先建设平台级 SourceMessage Inbox，用于接收 AgentBus 邮件来源事实，并为后续 AI 识别、人工复核、Case / Task 流程提供可追溯输入。

## 目录说明

```text
client/
后续前端应用目录。前端只调用本项目后端，不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。

server/
后端 Spring Boot 服务目录。后端负责数据库、外部系统适配、业务规则、安全脱敏和审计边界。

mcp-server/
SuperAgent MCP 方案入口指针。当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`，对外资料包位于 `docs/project/integrations/superagent-mcp/`。

docs/
项目文档、可复用规范、当前项目需求和外部系统接入记录。当前项目文档总索引见 `docs/project/README.md`。
```

## 后端命令

```bash
cd server
./mvnw test
./mvnw verify
./mvnw spring-boot:run
```

中文说明：

- `./mvnw test`：运行后端单元测试和 Spring 集成测试。
- `./mvnw verify`：运行 Maven verify 阶段，用于提交前完整检查。
- `./mvnw spring-boot:run`：本地启动后端服务，默认端口为 `8080`。

## 前端命令

```bash
cd client
pnpm install
pnpm dev
pnpm typecheck
pnpm test
pnpm lint
pnpm build
```

中文说明：

- `pnpm install`：安装前端依赖。
- `pnpm dev`：启动本地 Vite 开发服务，默认地址为 `http://127.0.0.1:5174`。
- `pnpm typecheck`：运行 Vue / TypeScript 类型检查。
- `pnpm test`：运行前端单元测试。
- `pnpm lint`：运行 ESLint 检查。
- `pnpm build`：执行类型检查并构建生产产物。

本地联调指定后端示例：

```bash
VITE_API_PROXY_TARGET=http://127.0.0.1:8080 pnpm --dir client dev
```

中文说明：Reservation 查询默认不再依赖前端环境变量传 `hotel_id`。单酒店阶段后端从 `platform_hotel` 唯一 `ACTIVE` 酒店解析系统酒店；登录后前端可按 `/api/auth/me` 的当前选中酒店传可选 `hotel_id`，后端仍会校验访问权限。`VITE_RESERVATION_HOTEL_ID` 仅保留为本地夹具或临时覆盖，不作为生产业务事实来源。

Debug EML 上传到 SuperAgent 调试页面为隐藏入口，不放在普通业务菜单中：

```text
http://127.0.0.1:5174/debug/eml-superagent
```

中文说明：该页面只用于 dev/test 受控调试。Debug 上传口令必须由调试人员在页面手动输入，不能写入 `VITE_*`、源码、localStorage、sessionStorage、URL、错误上报或普通日志。

## SuperAgent MCP

当前 MCP 采用后端内嵌方式，不需要额外部署独立服务。启用示例：

```bash
cd server
MCP_ENABLED=true MCP_AUTH_TOKEN=test-token MCP_ENABLE_SUBMIT_TASK_RESULTS=false ./mvnw spring-boot:run
```

中文说明：SuperAgent 通过 `POST /mcp` 调用 5 个 MCP tools。写入工具由 `MCP_ENABLE_SUBMIT_TASK_RESULTS`
单独控制，生产启用前需要单独确认。MCP 单次请求体默认限制为 10MB，可通过 `MCP_MAX_BODY_BYTES`
调整。

### 测试数据库配置

默认 `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，以及具体业务页面展示位置。