shiyuyun/Wyndham-RSVN-0918
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Wyndham-RSVN-0918/CONTEXT.md
鲨鱼辣椒 31849411a8
Some checks failed
verify / booking-verify (push) Has been cancelled
Details
建立5178独立项目基线
2026-09-08 15:03:45 +08:00

9.0 KiB
Raw Permalink 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 24.x 与 pnpm 11.x（项目文件 client/.node-version、client/package.json 固定验证基线）。

4. 当前业务领域

  • SourceMessage：外部消息来源事实，当前主要承接 AgentBus 邮件 JSON。
  • Email / Message Conversation：邮件和邮件会话，用于历史邮件查询、正文读取和会话级任务查询。
  • Reservation Case / Task：预订相关订单、任务卡、人工复核和任务结果。
  • Reservation Order Task / Card：M002 V4 后续采用的订单任务与多卡模型；一封来源邮件可按 order_ref 形成多个订单任务，每个订单任务下包含来源邮件展示卡、Basic Information 卡和若干业务卡。
  • Booking Email Intake：M012 普通员工预订邮件入口；可上传.eml。Layer3读取完整有序邮件History正文但不读取History附件；Layer5 Booking Agent消费包含Current、完整有序History正文和Layer3/4的受控canonical投影。Parsing现使用compact交接和同一Provider run续接：4分钟只提示仍在处理，默认15分钟总上限，断线/重启按已保存session/run恢复；Booking V2 durable已实现Layer3/4先提交、事务外外呼、Candidate独立提交和Layer6恢复。默认/production仍关闭，当前V12真实续接结果待新回放。
  • Room Information Card：V4 可定位订单任务的房型与日期区块；New / Update / Cancel 直接生成生命周期 Room，只有 Trace / Rooming List / Payment 的订单任务补一张共享 current-only companion Room，因此六类订单事件均具备 Basic + Room。
  • Review Required Card：V4 订单任务中需要人工复核的原业务卡状态；用户仍在原卡片内检查和修正业务字段，完成后确认卡片，不另建独立复核任务卡。
  • Reservation Account：预订业务中的公司、旅行社或客户账户，不是系统登录账号；它用于订单级 Basic Information，并派生 Market / Source。
  • Rate/Room Directory Foundation：rate-room-v20260810保存207条来源映射、10个canonical Roomtype、21个基础Rate Code和40个历史alias；schema v3 authority保存48条有效房型规则及2条删除记录。rate-room-effective-mapping-v20260812.1固化213条有效候选行/163场景。typed Layer4已接独立Roomtype/Rate早餐套餐、同Tour Code聚合、QBD公司级缺价、普通LIAN TAI 4/5目录、套房继承；Parsing最终handoff和当前附件Rooming List typed resolver均已接线，Layer5/6消费已完成。
  • Room Type Catalog：当前生成目录的稳定业务集合为 RM2、RM3、RM4、SU1、SU2、SU3、SU6、UG1、UG2、UG3，暂不按 Account 限制可用房型。历史六代码口径仅是 M002 第一阶段记录。
  • Rate Code Applicability：当前生成目录包含 21 个基础 Rate Code；40 个历史组合码只用于兼容输入，不是新输出。第一阶段暂不按 Reservation Account 或 booking type 限制候选；缺价默认已由Layer4按公司白名单实现，仅Q.B.D → GRPA1，普通LianTai保持null；Layer3不填充。
  • Rooming List Task Card：V4 订单任务中的 Rooming List 事项确认卡，表示当前来源消息包含需要人工处理的房表事项；它不同于独立的 Rooming List Excel 生成工具。
  • Rooming List Excel Generation：独立的 Reservation 运营工具，用于把旅行团名单 Excel 转成酒店 / PMS 可导入的 Rooming List Excel；CP2 已实现从来源名单 旅游日期 派生入住 / 离店日期，由系统按分房结果计算成人数，前端目标默认值区域只保留付款方式和国籍；CP3 已实现第二种 英文姓 + 英文名 名单样式，CP4 已实现第三种单列 英文名 名单样式，无旅游日期来源样式均由用户补充入住 / 离店日期。
  • 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 能力提供方。Parser Recovery 与 Booking Business 使用独立外部应用/token，只共享 transport；返回内容只能作为建议、证据或审计结果。 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 明确
PostgreSQL Booking runtime M012 新主线可在显式开关和部署 Secret 下使用独立 datasource/Flyway，只写 th_hotel_booking；默认 profile 仍为 H2，不建立跨库事务。 server/src/main/resources/db/booking-postgresql/migration/

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/ 下的当前有效文档为准。

预订邮件识别到人工确认的当前基线见 docs/project/requirements/M012-booking-email-confirmation-e2e-v01.md；Layer5离线验收见 docs/project/requirements/booking-business-agent-v1-offline-acceptance-report.md。本期固定渠道仅包括QBD与LIANTAI。Layer3 CP0–CP4、compact handoff、同一Provider run续接、final handoff、Rooming List resolver、Layer4、Booking Agent V2 durable runtime、Layer6恢复及可信V4投影代码已完成；测试PostgreSQL当前为V13，本地H2为V34。默认/production仍关闭；V12 Parsing续接、Booking RC6及完整AgentBus链仍需真实新回放，production另行批准。Rooming List全业务与PMS/Opera继续后置。

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

7. 新 Agent 阅读顺序

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

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