huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3438d4daec77c310810a1e6a1f7d812505fbd0e1
th-hotel-simple/CONTEXT.md

5.4 KiB
Raw Blame History

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。