97 lines
11 KiB
Markdown
97 lines
11 KiB
Markdown
# 发给平台同事：酒店预订流程需补的 Oracle 接口
|
||
|
||
> **发布已确认（2026-09-17 后续复测）**：原地址成功返回目录及 OpenAPI **0.11.0／184 项**，下方 5 核心 + 3 建议只读均已发布，无需重复封装。下文 0.10.0 缺项说明保留为需求交付时的历史基线。真实酒店调用尚未验证，连接仍间歇失败且 /readyz 返回过 503；消费端发现的路由、取消 201、待回查响应适配差异已本地修正；酒店附件执行依赖也已移除，运行服务尚未加载。见[实现交付](ohip-published-contract-no-attachments-20260917.md)。见[最新核验](../../../.project-docs/50-evidence/topics/2026-09-17-platform-published-check.md)。
|
||
|
||
核对日期：2026-09-17。范围为 GROUP/FIT 新建、修改、类型转换及源 Allotment 取消，不含加床、真实酒店操作或邮件发送。
|
||
|
||
**最新业务范围（用户已取消酒店附件上传）**：GROUP/FIT 不再向 Oracle Attachments 上传或替换邮件 Excel；本轮不要求附件上传、清单、下载、删除接口，也不再追查附件 linkType。邮件 Excel 的接收、查看和业务解析继续保留。GROUP Block Name 与 GROUP/FIT TA Record Locator 仍按 Tour Code 填写。
|
||
|
||
**同日字段证据补充**：公开研究由消费项目 Agent 完成，见[公开证据复核](ohip-public-field-evidence-20260917.md)。FIT Note 已有 schema + 官方 Postman 支持 `comments[]`，GROUP 日期已有官方样例支持 `YYYY-MM-DD`。附件研究保留为历史依据，已退出当前需求。当前未关闭的字段证据主要是 FIT TA 写读路径，不再要求平台同事重复查同一套资料。
|
||
|
||
平台公开目录本次为 **0.10.0、176 项**。下方 5 个核心操作在 Oracle 原生契约中存在，但本次公开目录未列出。如平台已有未发布实现，请核实发布与目录暴露，不必重复开发。接口存在、应用授权和真实酒店业务验证分别验收。
|
||
|
||
Oracle 依据：Property API **26.3.0.0**，官方仓库 main 当前提交 `4bd129b455bc5e3ab0f900ac47983611e58659b4`；已比对下述模块及官方 Postman 样例与该提交一致。
|
||
|
||
## 一、请优先补这 5 个核心接口
|
||
|
||
以下路径全部是 **Oracle 原生路径**，不是平台 REST 路径。
|
||
|
||
| # | Operation ID | 方法与 Oracle 路径 | 当前业务用途 | 原生成功状态 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 1 | `postProfile` | POST `/crm/v1/profiles` | FIT 先创建一次 Guest，全部关联预订共用实际 Profile ID | 201 |
|
||
| 2 | `putBlockAllocation` | PUT `/blk/v1/hotels/{hotelId}/blocks/{blockId}/allocation` | GROUP 新建/修改的完整逐晚房型房数 | 200 |
|
||
| 3 | `getNextBlockStatus` | GET `/blk/v1/blocks/status` | 按 Block 当前状态查询可转换状态 | 200 / 204 |
|
||
| 4 | `putBlockStatus` | PUT `/blk/v1/hotels/{hotelId}/blocks/{blockId}/status` | 取消原 GROUP 或源 Allotment | 200 |
|
||
| 5 | `postCancelReservation` | POST `/rsv/v1/hotels/{hotelId}/reservations/{reservationId}/cancellations` | FIT→GROUP 前逐笔取消原 Reservation | 201 |
|
||
|
||
来源：[CRM](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/crm.json)、[BLK](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/blk.json)、[RSV](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/rsv.json)。
|
||
|
||
### 入参与回查要求
|
||
|
||
| 操作 | 必须能表达的参数/行为 | 写后或查询结果核对 |
|
||
| --- | --- | --- |
|
||
| `postProfile` | 原生根 `profileDetails`；`profileType=Guest`、`registeredProperty`、`customer.personName[].surname`、`addresses.addressInfo[].address.country.code`；姓名原值，Country=CN | 返回实际 Profile ID，再用已有 `getProfile` 查姓名/Country/类型；不能用姓名充当 ID |
|
||
| `putBlockAllocation` | `criteria.hotelId`、`blockId.id/type`、`allocationRoomTypes[].roomType`、`allocationGridDates[].allocation=INITIAL/ACTUAL`、`roomAllocationInfo[].start/end`、`inventory.onePerson/twoPerson/threePerson/fourPerson`；支持零值、逐晚不同数量及多个房型 | 已有 `getBlockRoomRateGrid` 回查完整日期/房型范围；查询类别枚举是 `Initial/Actual`，大小写与写入不同；保留分页/完整性信息 |
|
||
| `getNextBlockStatus` | query `hotelId`、`currentStatus`；可选 `includeCateringStatus` | 返回下一状态集合及原生属性；不能把配置目录当作已经验证了本次状态转换 |
|
||
| `putBlockStatus` | `changeBlockStatus.hotelId`、`blockId.id/type`、`currentBlockStatus`、`newBlockStatus`、`cancellationDetails.cancellationCode.code`；根 `verificationOnly=false` | 已有 `getBlock` 查实际状态；拒绝擅自开启 cancelAllPMReservations、overbookAll 等扩大作用范围的字段 |
|
||
| `postCancelReservation` | `reservations[]` 每次仅一个实际目标，内含 `hotelId`、`reservationIdList[].id/type`；`reason.code`（可选 description）；`verificationOnly=false` | 已有 `getReservation` 查取消状态，保留实际取消回执；部分原预订未取消时，不进入最终类型新建 |
|
||
|
||
GROUP 房量输入是绝对目标数量，不能被封装成“增减量”。`putBlock` 不能替代 Room Grid 写入；参考 [Oracle Room Grid 更新指南](https://docs.oracle.com/en/industries/hospitality/integration-platform/maeig/t_update_room_and_rate_grid.htm)。
|
||
|
||
### 建议保持的消费端路由形状
|
||
|
||
以下为本项目候选适配使用的路径，**不是声称平台已发布**。平台如采用不同路由或 envelope，请同时提供明确契约供消费端调整。
|
||
|
||
- `postProfile`：POST `/api/v1/profiles`。
|
||
- `putBlockAllocation`：PUT `/api/v1/blocks/{id}/allocation`。
|
||
- 取消：GET `/api/v1/blocks/{id}/next-status?currentStatus=...`；PUT `/api/v1/blocks/{id}/status`；POST `/api/v1/reservations/{id}/cancellations`。
|
||
|
||
已有确认写入 envelope、case/task/confirmation、酒店校验、幂等键和逐调用记录应继续沿用。
|
||
|
||
平台需同时提供更新后的 catalog/OpenAPI、query 白名单、请求/返回组件、能力组及读回操作。写入超时或回执丢失保留未知状态并查询核对，不能自动重发创建/取消；回查失败也不能抹去已知写入事实。保留原生状态码与空结果语义，尤其 FIT 取消原生是 201，不统一当作 200。
|
||
|
||
## 二、建议顺带补的 3 个只读接口
|
||
|
||
| 操作 | 原生路径/关键参数 | 用途与优先级 |
|
||
| --- | --- | --- |
|
||
| `getBlockPMReservations` | GET `/blk/v1/hotels/{hotelId}/blocks/{blockId}/postingMaster/reservations`，可选 `postingmaster` | 取消前单独识别 Posting Master，避免只查普通住客而漏掉 PM；建议随取消接口一起补 |
|
||
| `getOperaSettings` | GET `/ent/config/v1/settings`，query `hotelId`、`cROCode`、`parameterNameWildCard` | 获取影响房量分列、TA 等行为的实际 OPERA Controls；只读，不要求封装设置写入 |
|
||
| `getProfileRelationships` | GET `/crm/v1/profiles/{profileId}/relationships`，query `relationshipPrimaryProfile` | Contact 的 PrimaryAccountInfo 不足时读取准确关联；已有主账户查询足够时可暂缓。也可选择扩展已有 getProfile 的 Relationship fetch，提供可靠关系读法即可 |
|
||
|
||
来源：[Posting Master 官方流程](https://docs.oracle.com/en/industries/hospitality/integration-platform/maeig/t_create_block_posting_master.htm)、[ENT Config](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/entcfg.json)、CRM/BLK 契约。
|
||
|
||
`putBlockShift`（PUT `/blk/v1/hotels/{hotelId}/blocks/{blockId}/shifts`）仅作后备：它是整体移期，会涉及已有房格及相关日期；先核实普通日期更新对本次改期场景是否足够，不列为当前必包接口。FIT 增加另一房型也不直接等同 split，暂不额外要求拆分接口。
|
||
|
||
## 三、以下接口已有，不要重复包
|
||
|
||
`postBlock/putBlock/getBlock/searchBlocks`、`postReservation/putReservation/getReservation/searchHotelReservations`、`getBlockRoomRateGrid`、`getProfiles/searchProfiles/getProfile`、`getReservationAttachments` 已列入公开目录。
|
||
|
||
`getCancellationCodes`（FIT 取消原因）、`getBlockCancellationReasons`、`getBlockStatusCodes`、`getNextBlockStatusCodes` 也已有。注意 `getNextBlockStatusCodes` 是配置查询，参数为 configuredOnly/blockStatusCodes；它与业务 `getNextBlockStatus` 的 currentStatus 查询并非同一操作。
|
||
|
||
## 四、还需一起解决的字段和样例缺口
|
||
|
||
### A. FIT TA Record Locator（技术侧向 Oracle 查证）
|
||
|
||
新建/修改/查询 Reservation 接口都有，但我们仍没有可以证实的 TA 字段 JSON 路径。请提供带来源的新建请求、修改请求、详情查询响应及所需 fetchInstructions；业务值为 Tour Code。搜索 `taRecordLocatorList` 已有，不用新增一个同名搜索接口；也不能未经证据把 customReference 或 Guest locators 当成 TA。
|
||
|
||
Oracle 确认此 UI 功能受 `TA_RECORD_LOCATOR` Control 影响；26.2 还可纳入 Reservation Protection。需要同时核实目标环境是否允许编辑。该说明证明功能/控制存在，并不证明 REST 写入路径。[Oracle Control](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.1/ocsuh/c_opera_controls_reservations.htm)、[Reservation Protection 更新](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.2/oprnc/c_feature_summary.htm)。
|
||
|
||
### B. 已取消的酒店附件需求
|
||
|
||
用户明确取消把本封邮件 Excel 上传到 GROUP/FIT Attachments。以下原清单中的 5 个缺项撤回：`uploadFileAttachment`、`getFileAttachment`、`getBlockAttachments`、`deleteBlockAttachment`、`deleteReservationAttachment`。已有 `getReservationAttachments` 也不再作为本流程依赖。无需为本需求补封装、验证 linkType 或替换/删除酒店旧附件；这不要求删除平台已有通用能力。
|
||
|
||
### C. 官方 schema 与内嵌示例差异（已明确实现依据）
|
||
|
||
- FIT Note：正式 schema 与官方 Postman 新建/修改样例均支持 `comments[]`，据此实现；Swagger 内嵌 example 的 `comments.commentInfo` 保留为文档矛盾。按 ID 修改、读回原文与保留无关 Note 属下一层运行验证。
|
||
- GROUP 日期：官方指南及 Postman 支持 `YYYY-MM-DD`，据此实现；`format=date` 与 maxLength=8 的不一致保留为规范问题。缩期/移期后的房格行为仍需运行验证。
|
||
|
||
### D. 酒店参数值与权限
|
||
|
||
已有的房型、Rate、Account/Contact、GTT/X/TA/GC/BTQR/TEN/THB 业务选择不重新向员工询问。技术侧通过对应现有目录/查询核实目标酒店有效值、实际 Profile ID/关系及当前应用授权。补充取消原因、可用取消状态、allowPickup、occupancy split 的实际值；不使用本地合成值作为真实配置。
|
||
|
||
## 五、消费项目还需做的工作
|
||
|
||
平台发布并交付上面契约后，消费项目需要按最终封装接入、补齐实际字段映射并由用户操作测试。首次处理非本系统创建的旧预订，还需建立旧 Note 的可靠归属规则。这是应用接管逻辑，不能仅靠新增 Oracle 接口解决。现有候选代码仍包含附件执行及回显，需在后续实现阶段移除对应流程依赖与完成条件；本轮只修订需求和接口清单，未声称程序已改。
|
||
|
||
目前的独立模拟验证不代表目标 Oracle 验收，也不代表用户当前工作台已加载新代码。本材料只供平台同事评估/实施，未发送外部消息、未申请授权、未调用酒店业务或改动运行环境。
|