th-hotel-simple/PROJECT_STATE.md

TH Hotel Simple 项目当前状态

项	内容
最近更新	2026-07-21
当前分支	feature/huangting
当前阶段	M002 V4 入站、多卡模型、持久化基线、入站写入、查询接口、卡片确认、复核解阻、目录校验、订单详情 V4 总览、DB 目录、Lookup API、前端 lookup 接入、目录管理后台 CP1 前后端、订单列表 V4 继续处理入口 / open count 收口、V4 业务审计查询、停止旧任务双写、Debug EML V4 profile 对齐、Room Information 后端展示模型与前端业务化展示、V4 任务详情 smoke 修复、Rooming List 确认自动 DEF 后端联动、Room Information 复核 pointer 与任务详情安全边界修复、Room Information 复核 pointer 运行时规则收口、复核 pointer 部署证明与运行时 trace、Account + booking type 过滤 Rate Code 文档口径、Payment 附件预览后端安全摘要、Rooming List 事项确认卡文档口径，以及 V4 复核态卡片交互和字段白名单文档口径
当前重点	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 字段策略。复核 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 原始响应等敏感字段。Rooming List 卡确认时已实现 Group 自动置 DEF：如同订单存在可更新的已确认 Room Information 快照，后端会覆盖其 group_booking_status=DEF 并写 V4_ROOMING_LIST_AUTO_DEF 审计；刷新任务详情时 display_payload 和 confirmed_payload 均以 DEF 后的确认快照为准；当前订单详情 order_overview 不返回 Group Booking Status 字段；如没有可更新投影，Rooming List 确认仍成功，只写安全审计提示，不临时创建不完整 Room Information。已确认 Rate Code 下一阶段按 Reservation Account + booking_type（GROUP / FIT）过滤和校验，不按全酒店 Rate Code 全量展示；Payment 卡已在 display_payload.payment_attachments[] 返回付款凭证附件安全摘要，字段只包含附件 ID、文件名、类型、大小、是否图片、是否理论可预览 / 下载和可选 external_media_id，attachment_ids[] 第一版仍只读，前端只展示并确认卡片，不增删或替换附件集合，附件缩略图、大图和非图片下载真实 URL 仍走 SourceMessage 原文权限链路；已确认 Rooming List 任务卡第一版只做事项确认，不做名单解析、附件预览、Excel 生成或 PMS 导入，用户点击“确认卡片”表示已人工处理该 Rooming List 事项；已确认 REVIEW_REQUIRED 仍是原业务卡复核态，页面按钮统一叫“确认卡片”，复核态允许编辑当前卡 fields[] 白名单内业务字段，问题字段红字提示。后续可继续做测试机 V4 smoke 复测、Payment 前端联动、Rooming List 前端轻量卡展示、Account 范围 Rate Code lookup、真实 PMS / OPERA / OHIP 同步或 SuperAgent 目录供给方案。

1. 当前 Checkpoint

• 名称：M002-V4-payment-attachment-preview-backend
• 状态：In Progress，正在实现 Payment 卡付款凭证附件安全摘要。
• 目标：GET /api/reservation/order-tasks/{orderTaskId} 对 V4 Payment 卡返回 display_payload.payment_attachments[] 安全摘要，attachment_ids[] 保持只读，确认接口不接受前端替换附件集合。
• 边界：本 checkpoint 不做前端、不返回附件 URL / 签名 URL / OSS URL、不做 Payment 附件编辑、不做付款状态、不做 Rate Code lookup、不做 PMS / OPERA / OHIP、不推进 M011。
• 联调备注：Payment 缩略图、大图预览和非图片下载真实 URL 仍必须通过 GET /api/source-messages/{sourceMessageId}/conversation 在 SOURCE_MESSAGE_READ + SOURCE_MESSAGE_ORIGINAL_READ 权限下读取；V4 task detail 本身只返回附件 ID、文件名、类型、大小、图片标记、预览 / 下载可用性和可选 external_media_id。

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 契约和安全边界文档为准。

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，需要更新本文件，避免项目状态继续沉淀在聊天记录里。
• M010 Rooming List Excel 生成后端 CP1 和前端 V1 已实现：前端 /reservation/rooming-lists/new 上传来源名单和手工字段，后端同步生成 .xlsx 直接下载，第一版不落库、不上传 OSS。
• 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；Room Information 后端展示模型和前端业务化展示第一版已完成；Rooming List 确认触发 Group Booking Status 自动置 DEF 已完成；Payment 附件安全摘要后端已完成。Account + booking type 过滤 Rate Code 仍是待补齐缺口；Payment 前端缩略图 / 下载联动、真实 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

• 后续如继续做 M002 V4，可优先进行测试机联调，或推进真实 PMS / OPERA / OHIP 目录同步和 workflow_reservation_catalog_sync_run checkpoint。
• 后续新增重要功能时，优先在 docs/project/requirements/ 或未来 docs/specs/ 中形成 Spec，再实现代码。
• M010 后续如需预览、历史记录、OSS 下载、订单 / 任务预填或客户字段目录化，再单独开前后端 checkpoint。
• M011 CP4 暂不推进；当前停留在 CP3 边界，只增强 SuperAgent 输入，不直接落订单、任务或长期解析历史。后续如确实需要运营查询或长期追踪，再单独设计 Excel 解析批次 / 行级持久化表。

6. 文档同步提醒

每次 Feature 完成后检查：

• Domain 是否需要更新。
• Architecture 是否需要更新。
• Workflow 是否需要更新。
• ADR 是否需要新增。
• Spec 或需求文档是否需要更新状态。
• PROJECT_STATE.md 是否需要更新。
• 接口、安全、权限、审计和酒店隔离文档是否需要同步。

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

No documentation changes required.