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，并派生 Market / Source。
Room Type Catalog：预订业务可选房型代码目录；第一阶段已确认稳定业务集合为 RM2、RM3、RM4、SU1、SU2、SU3，暂不按 Account 限制可用房型。
Rate Code Applicability：Rate Code 的业务适用范围；第一阶段暂不按 Reservation Account 或 booking type 限制候选，Rate Code 先作为当前酒店级目录校验。未来如需求方明确 Account 专属候选，再单独建立适用关系。
Rooming List Task Card：V4 订单任务中的 Rooming List 事项确认卡，表示当前来源消息包含需要人工处理的房表事项；它不同于独立的 Rooming List Excel 生成工具。
Rooming List Excel Generation：独立的 Reservation 运营工具，用于把旅行团名单 Excel 转成酒店 / PMS 可导入的 Rooming List Excel；CP2 已实现从来源名单 旅游日期 派生入住 / 离店日期，由系统按分房结果计算成人数，前端目标默认值区域只保留付款方式和国籍。
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/project/ai-nses-project-overlay.md 记录本项目在 AI-NSES 之上的需求门禁、V4 核心概念守门、需求追踪和 agent 交接规则。
docs/import/reusable/ 保存可迁移到其他项目的通用规范。

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

新增重要 V4 需求时，应先按项目级 Overlay 形成或更新模板化 Spec / Change Request，再安排后端、前端或测试 agent 开工；现有 M002 V4 大文档继续作为字段、接口、安全和实现契约。

7. 新 Agent 阅读顺序

AGENTS.md
CONTEXT.md
PROJECT_STATE.md
README.md
docs/project/README.md
docs/project/ai-nses-project-overlay.md
与当前任务相关的需求、接口、安全、前后端协作或集成文档

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

6.4 KiB Raw Blame History Unescape Escape