huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

实现V4 Payment附件安全摘要

Browse Source
This commit is contained in:
andy
2026-07-21 16:31:54 +07:00
parent 3438d4daec
commit 4b869a0ecd
15 changed files with 759 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md
View File

@@ -4,9 +4,9 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.8 |
| 日期 | 2026-07-20 |
| 状态 | CP2 设计已确认；CP3-CP8、CP11、CP13、CP14、V4 业务审计查询、停止 V4 普通业务双写旧任务和 Room Information 后端展示模型第一版已实现 |
| 文档版本 | 0.9 |
| 日期 | 2026-07-21 |
| 状态 | CP2 设计已确认；CP3-CP8、CP11、CP13、CP14、V4 业务审计查询、停止 V4 普通业务双写旧任务、Room Information 后端展示模型和 Payment 附件安全摘要后端第一版已实现 |
| 适用范围 | M002 V4 入站后的订单任务、多卡、状态、查询和写操作设计 |
| 不适用范围 | 真实 PMS / OPERA / OHIP、前端页面视觉稿、生产历史数据迁移 |
@@ -16,7 +16,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
截至 CP14、V4 业务审计查询、停止旧任务双写、Room Information 后端展示模型和 Rooming List 确认自动 DEF 后端联动，后端已实现本文第 10、11、12 节中的持久化和查询基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包只创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡，不再创建旧 `workflow_reservation_task`；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、订单详情 V4 订单任务时间线、V4 卡片确认接口、S10/S99 来源通知 ack 接口、V4 `REVIEW_REQUIRED` 卡复核解阻接口、V4 订单任务 / 来源通知审计查询接口、当前酒店数据库目录校验、卡片 `fields[]` 白名单、Account / Room Type / Rate Code lookup API、目录管理后台 CP1、订单列表 V4 继续处理入口字段、Room Information New / Update / Cancel 第一版业务展示模型，以及 Rooming List 确认触发 Group Booking Status 自动置 `DEF`。下一阶段已确认 Rate Code 需要按订单级 Account + `booking_type`（GROUP / FIT）过滤和校验，当前后端 CP11 实现仍是酒店级 Rate Code 目录，是待补齐缺口；Payment 卡下一阶段需要展示付款凭证附件，图片为缩略图 + 点击大图预览，非图片为文件列表 + 下载，但附件 URL 仍必须走 SourceMessage 原文权限链路；真实 PMS 同步继续后置，设计见 `M002-v4-real-catalog-lookup-api-design.md`。
截至 CP14、V4 业务审计查询、停止旧任务双写、Room Information 后端展示模型、Rooming List 确认自动 DEF 后端联动和 Payment 附件安全摘要后端第一版，后端已实现本文第 10、11、12 节中的持久化和查询基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包只创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡，不再创建旧 `workflow_reservation_task`；V4 S10/S99 创建来源通知。当前已开放 V4 工作台、订单任务列表 / 详情、来源通知详情查询接口、订单详情 V4 订单任务时间线、V4 卡片确认接口、S10/S99 来源通知 ack 接口、V4 `REVIEW_REQUIRED` 卡复核解阻接口、V4 订单任务 / 来源通知审计查询接口、当前酒店数据库目录校验、卡片 `fields[]` 白名单、Account / Room Type / Rate Code lookup API、目录管理后台 CP1、订单列表 V4 继续处理入口字段、Room Information New / Update / Cancel 第一版业务展示模型、Rooming List 确认触发 Group Booking Status 自动置 `DEF`，以及 Payment 卡 `payment_attachments[]` 安全摘要。下一阶段已确认 Rate Code 需要按订单级 Account + `booking_type`（GROUP / FIT）过滤和校验，当前后端 CP11 实现仍是酒店级 Rate Code 目录，是待补齐缺口；Payment 前端仍需基于安全摘要接入缩略图 / 文件列表交互，真实预览和下载 URL 必须走 SourceMessage 原文权限链路；真实 PMS 同步继续后置，设计见 `M002-v4-real-catalog-lookup-api-design.md`。
后续如本文与 `M002-v4-agent-callback-field-contract.md` 的字段契约冲突，以字段契约为准；如与安全边界冲突，以 `security-access-control-boundary.md` 为准。
@@ -608,7 +608,7 @@ Rooming List 卡事项确认规则：
Payment 卡附件展示规则：
- Payment 卡业务字段仍以 Agent 返回的 `attachment_ids[]` 为准，用于确认这些附件是否为当前订单付款凭证；这不代表已收款、已入账或付款状态已确认。第一版 `attachment_ids[]` 是只读业务事实，前端展示后只允许“确认卡片”，不允许用户增删、替换或重新选择附件集合。
- 后端下一阶段应在 Payment 卡 `display_payload` 中补 `payment_attachments[]` 安全摘要，由 `attachment_ids[]` 匹配当前触发 SourceMessage 的包级附件生成。建议字段为 `attachment_id`、`file_name`、`content_type`、`size_bytes`、`is_image`、`preview_available`、`download_available`，可选 `external_media_id`；不得包含 `externalUrl`、OSS URL、签名参数或附件原始二进制。
- 后端已在 Payment 卡 `display_payload.payment_attachments[]` 中返回安全摘要，由 `attachment_ids[]` 匹配当前触发 SourceMessage 的包级附件或同酒店 SourceMessage 媒体摘要生成。匹配只认包级附件 ID / `external_media_id`，不认本系统媒体表内部 row ID，也不按文件名猜测。字段为 `attachment_id`、`file_name`、`content_type`、`size_bytes`、`is_image`、`preview_available`、`download_available`，可选 `external_media_id` / `unavailable_reason_code`；不得包含 `externalUrl`、OSS URL、签名参数或附件原始二进制。
- 图片判断以 `content_type` 以 `image/` 开头为主；图片在 Payment 卡内展示缩略图，点击后打开大图预览。缩略图和大图实际 URL 不从 `GET /api/reservation/order-tasks/{orderTaskId}` 返回，前端必须在具备 `SOURCE_MESSAGE_READ + SOURCE_MESSAGE_ORIGINAL_READ` 时调用 `GET /api/source-messages/{sourceMessageId}/conversation`，定位当前 SourceMessage 后按 `external_media_id` / `attachment_id` 匹配对应附件。
- 非图片附件统一显示文件列表，至少展示文件名、类型和大小，并提供下载动作；第一版不在 Payment 卡内嵌 PDF、Word、Excel 或压缩包预览。
- 入站 `PAYMENT.attachment_ids[]` 无法匹配同包 `source_message.attachments[].id` 时，不创建用户可处理 Payment 卡，只写 `adapter_contract_error` transition 或按 S10 / 技术异常规则处理。只有 `attachment_ids[]` 已合法匹配、但用户缺少原文读取权限、会话接口失败、附件 URL 缺失或媒体预览链路暂不可用时，Payment 卡才展示安全摘要和“无法预览 / 无法下载”的状态，不应把附件 URL 或错误详情暴露给普通用户。
@@ -874,7 +874,7 @@ AI 原始 payload、邮件正文、附件 URL 和技术 trace 不应直接进入
| M002-V4-CP13 | 目录管理后台 V1 | Account / Market / Source 管理，临时 Room Type / Rate Code 管理，目录维护权限和管理审计 |
| M002-V4-CP14 | 订单列表 V4 继续处理入口 | 已完成：`GET /api/reservation/orders` 返回 V4 下一步订单任务、卡片、动作类型、动作状态和 open 数，前端可优先跳 V4 订单任务详情 |
| M002-V4-CP14.5 | Account 范围 Rate Code Lookup | 待实现：按 Account + `booking_type` 管理和查询 Rate Code 适用关系；业务卡确认 / 复核校验 Rate Code 适用性；前端在 Account 确认后加载对应 GROUP/FIT 候选 |
| M002-V4-CP14.6 | Payment 附件预览 | 待实现：Payment 卡返回付款凭证附件安全摘要；前端图片缩略图 + 大图预览，非图片文件列表 + 下载；预览 / 下载走 SourceMessage 原文权限链路 |
| M002-V4-CP14.6 | Payment 附件预览 | 后端已完成：Payment 卡返回付款凭证附件安全摘要，不返回 URL；前端待接图片缩略图 + 大图预览、非图片文件列表 + 下载；预览 / 下载走 SourceMessage 原文权限链路 |
| M002-V4-CP14.7 | Rooming List 事项确认卡 | 待实现前端轻量展示：Rooming List 卡第一版只展示事项和确认按钮，不解析名单、不预览附件、不生成 Excel、不导入 PMS |
| M002-V4-CP14.8 | Room Information 展示模型 | 已完成前后端第一版：后端返回 `display_payload.room_information` 稳定展示模型；前端按 New / Update / Cancel 业务表单展示最终值、差异、Nights、Breakfast、Group Booking Status 和本地订单投影；Adult 不显示 |
| M002-V4-CP14.9 | Rooming List 确认自动 DEF | 已完成后端第一版：确认 `ROOMING_LIST` 卡时，Group 同订单存在可更新 Room Information 确认快照则自动置 `DEF` 并写审计；Fit 不变更；无投影不造脏数据 |