# TH Hotel Simple 项目上下文

## 1. 产品目标

TH Hotel Simple 是一个前后端分离的酒店业务协同项目。

当前核心目标是把来自 AgentBus、SuperAgent 和后续酒店系统的业务输入，沉淀为可追溯、可查询、可人工复核的结构化数据，为酒店预订、任务处理、邮件原文读取、外部 AI 协作和后续 PMS / OHIP 集成打基础。

## 2. 当前系统组成

| 目录 | 中文说明 |
| --- | --- |
| `client/` | 前端应用。负责页面展示、人工操作、调试入口和调用本项目后端。前端不直接访问 AgentBus、SuperAgent、OHIP、数据库或任何 Secret。 |
| `server/` | 后端 Spring Boot 服务。负责数据库、业务规则、外部系统适配、权限、安全脱敏、审计和接口契约。 |
| `mcp-server/` | SuperAgent MCP 方案入口指针。当前不单独部署 MCP 服务，MCP 运行时代码内嵌在 `server/`。 |
| `docs/` | 项目文档、需求、架构边界、导入资料、可复用规范和第三方契约。 |

## 3. 技术栈

### 后端

- Java 17，语法和编译 release 均按 17。
- Spring Boot 3.5.15。
- Maven Wrapper。
- MyBatis-Plus 3.5.16。
- Flyway。
- MySQL，测试场景可使用 H2 MySQL Mode 或 test-mysql profile。
- Spring Validation、springdoc-openapi、Angus Mail、Aliyun OSS、Apache POI。

### 前端

- Vue 3.5。
- TypeScript 6。
- Vite 8。
- Pinia 3。
- PrimeVue 4、PrimeIcons 7。
- Vue Router 5、Vue I18n 11。
- Vitest 4、ESLint 10、vue-tsc 3。
- Node.js >= 22.13.0。

## 4. 当前业务领域

- SourceMessage：外部消息来源事实，当前主要承接 AgentBus 邮件 JSON。
- Email / Message Conversation：邮件和邮件会话，用于历史邮件查询、正文读取和会话级任务查询。
- Reservation Case / Task：预订相关订单、任务卡、人工复核和任务结果。
- Reservation Order Task / Card：M002 V4 后续采用的订单任务与多卡模型；一封来源邮件可按 `order_ref` 形成多个订单任务，每个订单任务下包含来源邮件展示卡、Basic Information 卡和若干业务卡。
- Room Information Card：V4 订单任务中由 New Booking、Update Booking 或 Cancel Booking 触发的房型信息卡；它展示订单房型、日期、早餐、晚数和 Group 状态等可确认业务信息。
- Review Required Card：V4 订单任务中需要人工复核的原业务卡状态；用户仍在原卡片内检查和修正业务字段，完成后确认卡片，不另建独立复核任务卡。
- Reservation Account：预订业务中的公司、旅行社或客户账户，不是系统登录账号；它用于订单级 Basic Information，并影响可用 Rate Code 范围。
- Rate Code Applicability：Rate Code 的业务适用范围；当前已确认先按 Reservation Account + booking type（GROUP / FIT）确定候选，不把全酒店 Rate Code 当成所有 Account 通用。
- Rooming List Task Card：V4 订单任务中的 Rooming List 事项确认卡，表示当前来源消息包含需要人工处理的房表事项；它不同于独立的 Rooming List Excel 生成工具。
- Payment Attachment Preview：Payment 卡中的付款凭证附件展示能力；业务事实仍是 `attachment_ids[]` 关联，图片可缩略图和大图预览，非图片统一文件列表和下载，附件外链必须走 SourceMessage 原文权限链路。
- Source Message Notification：M002 V4 的 S10 纯通知模型；只表示来源邮件需要被查看和确认已处理，不形成订单任务或业务卡。
- Identity / Access / Hotel / Menu：登录、用户、角色、权限、酒店授权和动态菜单底座。
- Debug EML：受控调试入口，用于上传 EML 并触发 SuperAgent 调试链路。
- Manual Invoice：手工开票生成能力，包含 Excel 模板、PDF 转换和 OSS 输出。

## 5. 外部系统与边界

| 外部系统 | 当前定位 | 契约入口 |
| --- | --- | --- |
| AgentBus | 消息入口适配器。实时入口必须先落 SourceMessage Inbox。 | `docs/project/integrations/superagent-agentbus-project-integration-guide.md` |
| SuperAgent | 外部 AI / Agent 能力提供方。返回内容只能作为建议、证据或审计结果。 | `docs/project/integrations/superagent-api-contract.md` |
| SuperAgent MCP | SuperAgent 调用本项目能力的 MCP 映射，当前内嵌在后端服务。 | `docs/project/integrations/superagent-mcp/README.md` |
| Aliyun OSS | 调试 EML、附件或生成文件的对象存储。 | 相关配置和安全边界见项目文档与后端配置 |
| OHIP / PMS | 后续酒店系统集成方向。当前不允许前端直接访问。 | 后续 Spec / ADR 明确 |

## 6. 当前开发方向

当前项目正在从普通项目文档结构，逐步落地 AI-NSES 文档入口：

- `AGENTS.md` 规定 Agent 如何工作。
- `CONTEXT.md` 说明项目长期背景。
- `PROJECT_STATE.md` 记录当前阶段状态。
- `docs/project/README.md` 作为当前项目专属文档索引。
- `docs/import/reusable/` 保存可迁移到其他项目的通用规范。

业务开发仍以 `docs/project/requirements/` 和 `docs/project/integrations/` 下的当前有效文档为准。

## 7. 新 Agent 阅读顺序

1. `AGENTS.md`
2. `CONTEXT.md`
3. `PROJECT_STATE.md`
4. `README.md`
5. `docs/project/README.md`
6. 与当前任务相关的需求、接口、安全、前后端协作或集成文档

涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须额外阅读 `docs/project/security-access-control-boundary.md`。