11 KiB
发给平台同事：酒店预订流程需补的 Oracle 接口
发布已确认（2026-09-17 后续复测）：原地址成功返回目录及 OpenAPI 0.11.0／184 项，下方 5 核心 + 3 建议只读均已发布，无需重复封装。下文 0.10.0 缺项说明保留为需求交付时的历史基线。真实酒店调用尚未验证，连接仍间歇失败且 /readyz 返回过 503；消费端发现的路由、取消 201、待回查响应适配差异已本地修正；酒店附件执行依赖也已移除，运行服务尚未加载。见实现交付。见最新核验。
核对日期：2026-09-17。范围为 GROUP/FIT 新建、修改、类型转换及源 Allotment 取消，不含加床、真实酒店操作或邮件发送。
最新业务范围（用户已取消酒店附件上传）：GROUP/FIT 不再向 Oracle Attachments 上传或替换邮件 Excel；本轮不要求附件上传、清单、下载、删除接口，也不再追查附件 linkType。邮件 Excel 的接收、查看和业务解析继续保留。GROUP Block Name 与 GROUP/FIT TA Record Locator 仍按 Tour Code 填写。
同日字段证据补充：公开研究由消费项目 Agent 完成，见公开证据复核。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 |
入参与回查要求
| 操作 | 必须能表达的参数/行为 | 写后或查询结果核对 |
|---|---|---|
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 更新指南。
建议保持的消费端路由形状
以下为本项目候选适配使用的路径，不是声称平台已发布。平台如采用不同路由或 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 官方流程、ENT Config、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、Reservation Protection 更新。
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 验收，也不代表用户当前工作台已加载新代码。本材料只供平台同事评估/实施，未发送外部消息、未申请授权、未调用酒店业务或改动运行环境。