th-hotel-simple/PROJECT_STATE.md

# TH Hotel Simple 项目当前状态

| 项 | 内容 |
| --- | --- |
| 最近更新 | 2026-08-08 |
| 当前分支 | `feature/booking-v01-safe-checkpoint` |
| 当前阶段 | M002 V4 入站、多卡模型、持久化基线、入站写入、查询接口、卡片确认、复核解阻、目录校验、订单详情 V4 总览、DB 目录、Lookup API、前端 lookup 接入、目录管理后台 CP1 前后端、订单列表 V4 继续处理入口 / open count 收口、V4 业务审计查询、停止旧任务双写、Debug EML V4 profile 对齐、Room Information 后端展示模型与前端业务化展示、V4 任务详情 smoke 修复、Rooming List 确认无跨卡副作用、Rooming List 前端轻量事项卡、Room Information 复核 pointer 与任务详情安全边界修复、Room Information 复核 pointer 运行时规则收口、复核 pointer 部署证明与运行时 trace、OWNER RATE Room Type / Rate Code 目录口径、Payment 附件预览后端安全摘要与前端预览接入、Trace 卡后端字段契约收口、Trace 确认态字段刷新、Rooming List 事项确认卡文档口径、V4 复核态卡片交互和字段白名单文档口径、V4 工作台 / 订单详情 / 任务详情普通酒店员工用户化展示与 polish 收口、订单事项办理页克制业务办理台视觉 polish、SuperAgent MCP 入站诊断链路第一版、AI-NSES v0.2 / TH Hotel 项目级 Overlay 文档治理规则、M002 V4 增量需求模板化 Spec 对齐，以及单卡可操作态测试数据 smoke 回填 |
| 当前重点 | M002 V4 已停止普通业务入站双写旧 `workflow_reservation_task`，V4 后新业务主线只写 V4 order task / cards / source notification；Debug EML V4 smoke 默认复用实时 AgentBus V4 Open API subject，避免误走历史 Debug V2/V3 profile。开发阶段不维护 V2/V3 旧任务兼容，测试数据可重建，生产迁移策略后续上线前单独设计。`GET /api/reservation/orders` 可返回 V4 下一步订单任务、卡片、动作类型、动作状态、V4 open 数和统一展示字段 `open_work_item_count`；旧 `open_task_count` / `next_processable_task_id` 仅作历史诊断兼容。Room Information 已完成后端稳定展示模型和前端业务化展示：`GET /api/reservation/order-tasks/{orderTaskId}` 在 `display_payload.room_information` 返回 New / Update / Cancel 的 `current_values`、`proposed_values`、`final_values`、`change_summary[]`，前端只消费该展示模型和 `fields[]`，不再从 Agent raw payload、`business_fields` 或 `target_order` 自行推导；如果卡片 payload 已经是稳定 `room_information.final_values` 结构，后端会按稳定模型归一化查询和复核；Nights、Breakfast 和 Group Booking Status 均以后端派生值为准；确认和复核写入稳定 `confirmed_payload_json.room_information.final_values`，不回写 Agent 原始 `target_order`、Adult、邮件正文或附件 URL；接口对前端暴露的 `fields[].write_target` 使用 `confirmed_payload` / `review_resolution.field_overrides` 这类安全语义，不暴露内部列名；查询侧 `fields[].editable` 和命令侧 `review-resolution` 复核 pointer 校验已共用同一套 Room Information 字段策略。Trace 卡后端契约已收口：普通事项内容字段统一为 `trace_items[].text`，不使用 `content`；`department_code` 第一版只允许 `FO`、`HSK`、`FO+HSK`，任务详情字段会返回 `options_source=reservation_v4_trace_department_fixed` 和 `fixed_options[]` 三个固定选项；`EXTRA_BED.target_room_type_code` 只校验当前酒店 Room Type 目录存在，暂不校验当前订单已有房型；确认和复核共用同一套 Trace 字段白名单，`display_payload` / `confirmed_payload` 不返回 `target_order`、邮件正文、附件 URL、raw evidence 或 AI 原始 payload。复核 pointer 拒绝前会记录 `review_pointer_policy=m002_v4_review_pointer_runtime_fix_v1`，包含 order task、card、incoming pointer、query-side editable pointers、command-side allowed pointers、validation error pointers 和 reject reason，但不记录 payload、邮件正文或附件 URL。V4 任务详情 smoke 修复已完成：页面顺序固定为 Basic Information、业务卡、SourceMessage Display；来源邮件卡位于页面底部，只通过 SourceMessage conversation 接口定位当前触发邮件并默认折叠正文；Basic Information 和普通业务卡的展示 / 确认 payload 不再返回 Agent `target_order`，普通业务卡还会移除邮件 HTML、raw evidence、附件原始 URL 和 PMS 原始响应等敏感字段；Basic Information 的 Market Code / Source Code 前端已改为可编辑字段，普通业务页不再展示字段下方 control hint、lookup 空目录提示或“只读”胶囊。Rooming List 卡确认只更新当前事项卡和订单任务派生状态，不修改 Group Booking Status、Room Information 确认快照或其他业务卡。V4 任务详情已支持 ROOMING_LIST 轻量事项卡：页面只显示 “Rooming List / 房表事项”、目标订单线索、人工处理说明和确认按钮，不展示 rows、名单明细、附件预览、导入 / 生成入口、AI payload、邮件正文或附件 URL；PENDING_CONFIRM 确认只提交 `version`，成功后完全使用后端刷新详情，不由前端自行设置 `group_booking_status=DEF`。OWNER RATE `RATECODE (2)` 已确认第一阶段 Room Type 稳定集合为 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3`，不建立 Account -> Room Type 关系；Rate Code 第一阶段暂不建立 Account 适用关系，Q.B.D 与 LIAN TAI 的 40 个规范化 Rate Code 仅作为当前酒店级 `RATE_CODE` 目录候选维护。Payment 卡已在 `display_payload.payment_attachments[]` 返回付款凭证附件安全摘要，字段只包含附件 ID、文件名、类型、大小、是否图片、是否理论可预览 / 下载和可选 `external_media_id`，前端在 V4 任务详情 Payment 卡中按当前触发 SourceMessage 的 conversation 附件匹配缩略图、大图预览和非图片下载，匹配优先 `external_media_id` / `externalMediaId`，其次 `attachment_id`，不按文件名猜测；`attachment_ids[]` 第一版仍只读，前端不增删或替换附件集合，Payment 确认只提交 `version`，不提交附件 ID、附件 URL 或完整附件对象；真实 URL 仍只来自 SourceMessage 原文权限链路，权限不足或 conversation 失败时降级展示不可预览 / 不可下载。已确认 `REVIEW_REQUIRED` 仍是原业务卡复核态，页面按钮统一叫“确认卡片”，复核态允许编辑当前卡 `fields[]` 白名单内业务字段，问题字段红字提示。后续可继续做测试机 V4 smoke 复测、OWNER RATE 目录导入、真实 PMS / OPERA / OHIP 同步或 SuperAgent 目录供给方案。 |

### 2026-08-08 M012 增量

### 2026-08-08 V0.1 安全纠偏（高优先级，覆盖上方历史叙述）

本 checkpoint 已撤销 Rooming List 确认后的自动 `DEF` / `V4_ROOMING_LIST_AUTO_DEF` 行为：确认只更新当前 Rooming List 卡和订单任务派生状态，不修改 Group Booking Status、Room Information 确认快照或其他业务卡。上方早期 M002 叙述中与此冲突的“自动 DEF”描述仅保留为历史记录，后续实施必须以 `docs/project/operations/booking-v01-security-checkpoint.md`、当前代码和后续 `contracts-v1` 为准。

同时，默认本地 profile 已改为进程内 H2；远程开发/生产数据库连接必须由环境变量或部署 Secret 注入。历史凭据轮换是部署管理员的外部前置，未取得证明前不得把 G0 标记为通过。

M012“预订邮件识别到人工确认”V0.1 已完成：新增普通员工 `.eml` 导入页和 API、固定渠道严格底色 deterministic Parser、版本化 Catalog、V4 建卡/复核/确认衔接、识别证据面板、真实样本验收和 PostgreSQL 项目专属 schema。手工导入路径的未知/歧义输入当前生成 S10/S99 来源通知，不在请求内自动调用外部 Booking Agent；PMS/Opera 执行仍不在范围。

### 2026-08-08 BR00/M012 双区块收口

V4 新 intake 已补齐订单任务双区块：只有 Trace、Rooming List 或 Payment 的订单任务会额外创建一张共享 current-only companion Room；同组已有 New、Update 或 Cancel 生命周期 Room 时不重复。查询、确认和前端展示均保留原辅助 event 类型，`proposed_values={}`、`change_summary=[]`，辅助专属卡、General/Risk、安全和权限边界不变。后端 V4 入站/查询/命令回归及前端 38 条 V4 页面测试通过。历史已落卡任务受幂等门禁保护，不自动回填。

## 1. 当前 Checkpoint

- 名称：`M012-booking-email-confirmation-e2e-v01`
- 状态：Done；三封真实外部 EML 分别创建 20 / 1 / 10 张 V4 订单任务，重复导入幂等；真实浏览器已完成“队列入口 → 导入 → 任务详情 → Basic Information 确认”。
- 目标：以 `BR00-BASELINE-1` 为唯一业务基线，打通邮件进入、固定渠道解析、业务建卡、证据/阻断展示和用户确认，不执行 PMS/Opera。
- 数据库：测试库中仅创建项目专属 `th_hotel_booking`，其他 schema 对象计数不变；当前 Spring 运行时仍保持 MySQL/H2，不暗中切换方言。
- 验证：后端 441 项通过；真实样本验收通过；前端 255 项、typecheck、build 通过；桌面和 390px 浏览器 smoke 通过。

## 2. 当前优先级

1. 先把 AI-NSES 的入口文档落地，让新 Agent 不依赖聊天记录也能理解项目。
2. 保持 `docs/project/README.md`、`CONTEXT.md`、`PROJECT_STATE.md` 三个入口之间一致。
3. 后续开发继续以当前有效的 M002 V4 字段契约、M002 V4 CP2 多卡模型设计、M002 V3 / P0.1 历史实现说明、字段控件契约、SuperAgent 契约和安全边界文档为准。
4. 后续新增重要 V4 需求时，先按 `docs/project/ai-nses-project-overlay.md` 形成或更新模板化 Spec / Change Request，并维护需求追踪表。

## 3. 已确认事实

- 本项目是前后端分离项目，根目录使用 `client/` 和 `server/`，不是 AI-NSES 示例里的通用 `src/` 单目录结构。
- 可复用规范放在 `docs/import/reusable/`，当前项目专属文档放在 `docs/project/`。
- AgentBus 是消息入口适配器，SuperAgent 是外部 AI / Agent 能力提供方，二者不能直接成为业务事实来源。
- 后端时间点按 UTC 存储和返回，页面再按酒店或用户时区展示。
- 新增 MySQL 表默认要求 `utf8mb4_bin`，避免外部 opaque id、Token、状态码和业务代码被大小写不敏感比较误判。

## 4. Known Issues

- 现有历史文档暂不按 AI-NSES 目录大搬迁，先通过索引和采用说明建立映射关系。
- `docs/import/` 下按日期导入的资料是输入材料，不等同于当前权威开发契约；当前开发应优先看 `docs/project/README.md` 标记为当前有效或权威契约的文档。
- 后续每完成一个 Feature 或 Checkpoint，需要更新本文件，避免项目状态继续沉淀在聊天记录里。
- AI-NSES v0.2 和 TH Hotel 项目级 Overlay 已落地；近期 M002 V4 新增需求已新增模板化 Spec 入口。后续新增或变更 V4 需求时必须继续维护该 Spec、后续 Change Request 或新 Spec，避免只散落在当前有效大文档中。
- M010 Rooming List Excel 生成后端 CP1 和前端 V1 已实现：前端 `/reservation/rooming-lists/new` 上传来源名单并下载后端同步生成的 `.xlsx`，第一版不落库、不上传 OSS。CP2 已实现：来源 Excel `旅游日期` 派生 Arrival / Departure，Adults 由系统按分房结果计算，目标默认值区域只保留 Payment Type / Nationality，Payment Type 默认 `BTQR` 且当前允许 `BTQR` / `CA`，Nationality 只允许 `KR` / `CN` / `TH` / `MM` / `RS` / `TW`。CP3 已实现：兼容第二种 `英文姓` + `英文名` 名单样式；CP4 已实现：兼容第三种单列 `英文名` 名单样式。无旅游日期来源样式由用户补充 Arrival / Departure，且 `23+1`、`19+1` 中领队也进入房表。
- M011 Booking Excel 附件预处理 CP1/CP2/CP3 已实现：后端可排除人员名单类 Excel，按最近 6 个月候选窗口选择实际存在的最新 3 个业务月，抽取 Booking Update / 附加费表高亮行业务 JSON；Debug EML 和 AgentBus dispatch 在各自 include 开关与总开关同时启用时，会在调用 SuperAgent 前追加 `attachment_extractions[]`。测试机 AgentBus 增强已开启；生产链路仍默认关闭，生产开启需单独确认。
- M002 V4 CP1 当前已完成入站解析和现有任务链路过渡适配；M002 V4 CP2 已完成订单任务与多卡领域模型设计；M002 V4 CP3 已完成 V4 订单任务、多卡和 S10/S99 来源通知表结构与 Repository 基线；M002 V4 CP4 已完成入站写入新模型；M002 V4 CP5 已完成前端查询接口并补齐订单详情 `v4_order_tasks[]` 时间线；M002 V4 CP6 已完成普通卡片确认和 S10/S99 来源通知 ack；M002 V4 CP7 已完成 `REVIEW_REQUIRED` 卡复核解阻和复核场景订单归属确认；M002 V4 CP8 已完成目录校验、V4 卡片 `fields[]` 字段白名单、确认写入白名单收口和嵌套业务字段目录校验；M002 V4 CP11 已完成数据库目录、初始化种子、启动补种子、Account / Room Type / Rate Code lookup API，并把 V4 入站、确认、复核目录校验切换到当前酒店数据库目录；M002 V4 CP12 已完成前端 lookup 接入第一版和 V4 订单任务时间线消费；M002 V4 CP13 目录管理后台 CP1 已完成前后端列表、新增、启用 / 停用闭环；M002 V4 CP14 已完成订单列表 V4 继续处理入口字段和前端入口消费，`GET /api/reservation/orders` 返回 V4 下一步订单任务、卡片、动作类型、动作状态、V4 open 数和统一展示计数 `open_work_item_count`，前端按 V4 优先跳转，并按 `open_work_item_count` 展示待处理数量；V4 业务审计查询已补齐订单任务审计和来源通知 ack 审计两个只读接口；订单详情已补齐并完成前端接入 V4 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`；V4 普通业务入站已停止双写旧 `workflow_reservation_task`；MCP `th_hotel_submit_task_results` 已收口为 M002 V4-only，旧 V2/V3 submit payload 返回 `MCP_SUBMIT_V4_REQUIRED`，不再影响 SuperAgent 输出契约；Room Information 后端展示模型和前端业务化展示第一版已完成；Rooming List 确认无跨卡副作用已完成，前端轻量事项确认卡也已完成；Payment 附件安全摘要后端和前端预览接入均已完成。OWNER RATE Room Type / Rate Code 目录口径已落文档；真实 PMS 同步和 SuperAgent 目录机器接口仍未完成。
- M002 V4 CP2 已确认：V4 工作台统一列表草案为 `/api/reservation/workbench-items`，业务订单任务接口新开 `/api/reservation/order-tasks/**`，S10/S99 来源通知详情草案为 `/api/reservation/source-notifications/{notificationId}`；S10/S99 使用来源通知模型，不再挂隐藏技术订单；`FIT + BOOKING_CODE` 不建 ACTIVE 唯一约束，匹配多条进人工复核；Basic Information 必须先确认；Rooming List 卡第一版只做事项确认；Account 通过数据库目录选择，Market / Source 可默认来自目录并允许前端人工覆盖提交；旧 V2/V3 任务详情和草稿确认接口后续可逐步废弃。

## 5. Next Steps

- M012 后续优先项是补齐发件人/渠道到 Account/Market/Source、价格/早餐到 Rate Code、未唯一房型等业务目录，并把固定渠道 deterministic Parser 的失败/歧义结果正式编排到 Booking Agent；这些不是 V0.1 中可安全猜测的值。
- 如需自动邮件入口完全复用 M012，同步联调 AgentBus → 本项目 SourceMessage → deterministic Parser/Booking Agent fallback；当前普通员工手工导入和既有 AgentBus → SuperAgent 是两条可运行但尚未统一编排的入口。
- 后续如继续做 M002 V4，可优先进行测试机联调，或推进真实 PMS / OPERA / OHIP 目录同步、`workflow_reservation_catalog_sync_run` checkpoint 和 SuperAgent 目录供给方案。
- SuperAgent 通过 MCP 提交时，排障优先查询 `platform_superagent_mcp_call_diagnostic`，对比 `arguments_json`、`adapted_payload_json`、`mapping_diagnostics_json` 和业务 batch / transition，判断问题来自 SuperAgent 原始参数、MCP adapter 还是业务入站层；V4-only 模式下 `mapping_diagnostics_json` 通常为空对象，若错误码为 `MCP_SUBMIT_V4_REQUIRED`，说明 SuperAgent 仍按旧 V2/V3 schema 输出；旧 V2/V3 被拒也会入本诊断表但不会进入业务写入 Service；V4 `source_message.conversation_id` 可缺省；该诊断表不作为业务事实来源，不进入普通前端接口。
- 后续新增重要功能时，优先在 `docs/project/requirements/` 或未来 `docs/specs/` 中形成 Spec，再实现代码；V4 相关需求必须按 `docs/project/ai-nses-project-overlay.md` 补核心概念守门、需求追踪表和 agent 交接边界。
- 单卡可操作态测试数据已回填；后续演示或回归如果需要重新造数，应继续使用 fresh runId，避免复用旧 SourceMessage 时间线造成阻塞误判。
- M010 CP4 第三种单列 `英文名` 名单样式兼容已完成；预览、历史记录、OSS 下载、订单 / 任务预填或客户字段目录化仍后置，需单独开前后端 checkpoint。
- M011 CP4 暂不推进；当前停留在 CP3 边界，只增强 SuperAgent 输入，不直接落订单、任务或长期解析历史。后续如确实需要运营查询或长期追踪，再单独设计 Excel 解析批次 / 行级持久化表。

## 6. 文档同步提醒

每次 Feature 完成后检查：

- Domain 是否需要更新。
- Architecture 是否需要更新。
- Workflow 是否需要更新。
- ADR 是否需要新增。
- Spec 或需求文档是否需要更新状态。
- `PROJECT_STATE.md` 是否需要更新。
- 接口、安全、权限、审计和酒店隔离文档是否需要同步。
- 需求追踪表、Change Request 和 agent handoff 是否需要更新。

如果没有文档变化，明确说明：

```text
No documentation changes required.
```