10 KiB
正式取消／类型转换接入与 FIT TA 查证
2026-09-18 新证据：官方数据字典已明确 TA 对应类型 TA_RECORD_LOCATOR 的外部参考号。这更新下文“externalReferences 无等价证据”的旧结论；OHIP 对该特殊类型的写读支持仍待直接证据，正式守卫不变，无需先要求平台新增封装。
日期：2026-09-17。此文覆盖之前“正式取消/转换尚未装配”的状态。本地代码接入不等于真实酒店已启用或验收；没有更新运行服务、办理现有任务、修改凭证权限或写入 Oracle。
当前可交付范围
| 业务 | 正式入口代码 | 当前限制 |
|---|---|---|
| 源 Allotment 取消 | 已接入 CANCEL_ALLOTMENT，查询 Block → 查关联客人 → 查允许的下一状态 → 更新状态 → 精确查回 |
部署须提供酒店真实取消规则；有关联客人或查询不完整时停止 |
| FIT → GROUP | 已接入 UPDATE 的类型识别；完整检查最终 GROUP 新建参数后，逐笔取消旧 FIT，再创建 Block、保存房量并核验 | 需显式开启类型转换；真实环境尚未验收 |
| GROUP → FIT | 编排入口已有，但正式入口仍在任何查询/取消之前阻断 | FIT TA 的真实写入、详情读取字段没有权威证据 |
| 同类型 GROUP 修改 | 仍走原 UPDATE，只改已确认范围，不要求新建用的 Rate/Note，不取消重建 | 既有日期/房量策略仍须验证 |
| FIT NEW / UPDATE | 原守卫保留 | 同一 FIT TA 缺口，不因配置标志而放行 |
邮件 Excel 仍用于解析/原件查看；本流程不读写酒店 Attachments。
需要哪些接口和参数
沿用平台 0.11.0 已发布契约，无新增消费端公共 HTTP 入口。这里的 searchHotelReservations 是平台实际 Operation ID，不能写成 searchReservations。
| 用途 | 平台方法与路径 | Oracle 参数／结果 |
|---|---|---|
| 找旧团队 | POST /api/v1/blocks/searches (searchBlocks) |
hotelId、blockName=Tour、onlyPickupBlocks=false；完整分页后精确 getBlock |
| 找旧 FIT | POST /api/v1/reservations/searches (searchHotelReservations) |
taRecordLocatorList=[Tour]、searchType=Any、similaritySearch=false；完整分页后逐笔 getReservation |
| 核实团队无关联客人 | 同一 Reservation 搜索 | blockIdList=[BlockId]；严格要求完整结果且零条，不能静默连带取消客人 |
| 下一状态 | GET /api/v1/blocks/next-status (getNextBlockStatus) |
query currentStatus；返回必须包含配置的取消状态 |
| 取消团队 | PUT /api/v1/blocks/{id}/status (putBlockStatus) |
verificationOnly=false；changeBlockStatus 内 hotelId、Block id、currentBlockStatus、newBlockStatus、cancellationDetails.cancellationCode.code；HTTP 200 |
| 取消 FIT | POST /api/v1/reservations/{id}/cancellations (postCancelReservation) |
verificationOnly=false、reason.code、单一 hotelId/Reservation id；HTTP 201 |
| 新 GROUP | 原 postBlock、getBlock、putBlockAllocation、getBlockRoomRateGrid |
复用现有完整新建/房量/查询链，不另造简化新建入口 |
取消的成功依据是当前精确详情返回取消状态。写入结果未知时不重发；详情仍未查实则停止新建。Block 取消不使用 override 或自动取消关联预订。
接入与恢复边界
OhipBookingRuntimeFactory已按部署策略装配OhipBookingChangeExecutionAdapter和持久取消调用日志，使用现有确认、数据源、租约和 worker。- 首次类型转换把真实旧对象绑定与最终 NEW 准备检查点一起保存；不会留下只有酒店 scope、没有配置检查点的半成品。
- 原绑定、配置摘要、目标 NEW 路由、取消原因/状态均受续办核验。每次取消前重验最终 NEW 参数及检查点；配置变化会停止。
- 双类型搜索只排除精确详情已证明取消的历史对象。转换留下的旧记录不会阻挡同 Tour 后续普通修改；两种类型仍有当前对象时停止，交人工核对。未知/其他状态不擅自当不存在。
- 单独源 Allotment 取消保留已取消对象查询，支持原确认的恢复与完成核验；输入不要求编造 Account、Rate 或房量。
- 参数准备成功不能保证 Oracle 随后一定接受新建。取消已成功而新建失败时，保留已取消事实及同次确认的调用记录，由原续办处理，不能另造确认或自动恢复旧预订。
- 默认仍为 Pending；旧清单不自动开启取消/转换，配置也不授予应用权限。新增代码不迁移或重跑旧含附件任务。
2026-09-18 接续：已扩查全部 45 个 Property v1 模块，并补齐独立模拟参数；同类型 FIT 取消历史、Guest 准备顺序及无附件 GROUP UPDATE 的修复见最新交付。此处真实 FIT TA 未决结论不变。
FIT TA 的准确结论
业务含义已经明确：TA Record Locator 填 Tour Code／Block Name。问题是 Oracle REST 的写入与详情读回位置，目前不能把“有同名搜索条件”当作已确认写入字段。
本轮重新验证 Oracle 官方仓库 HEAD 仍为 4bd129b455bc5e3ab0f900ac47983611e58659b4，Property RSV 26.3.0.0，完整文件树未截断；再检查 RSV schema、两个官方 Property Postman 集合及 Data API 定义：
| 证据 | 能证明什么 | 不能证明什么 |
|---|---|---|
官方 RSV schema 中 taRecordLocatorList |
可以按 TA 搜索 | 未找到 Reservation 创建/修改/精确详情的对应属性或等价映射 |
| 官方 Property Postman 与 工作流样例 | 可核实已有请求形状 | 两份全文未检出 taRecordLocator / TA Record Locator，不能给出 TA 写入样例 |
| BookingsReservation GraphQL | 报表层存在 TA 字段 | 不是 Property REST 写入或 getReservation 的字段证明 |
| TA Record Locator 控制、26.2 保护字段说明 | 页面输入/搜索受酒店控制，可被设为保护字段 | 不提供 REST JSON 路径 |
locators[].locatorText 在官方定义中是 Guest Locator，recordLocator 搜索项是 GDS Record Locator；customReference 和通用 reservationIdList 尚无明确 TA 映射。2026-09-18 新数据字典证据已将 externalReferences 收窄为 TA_RECORD_LOCATOR 类型这一具体候选；其 REST 可写性、详情返回和保护行为仍待核实，不直接把候选或模拟字段填进正式请求。
结论是公开证据仍不足，并非认定 Oracle 永远不支持。 平台包好接口后，这个字段契约缺口仍需补齐；不能简单要求平台同事再做相同公开搜索。
后续操作由用户完成
本轮提供 取消配置模板，未替换任何运行清单。它是完整示例，包含占位值，不能原样启用。原 四流程模板 保持兼容。
-
启用取消前，酒店提供真实 Reservation 取消原因、Block 取消原因、Block 取消状态、允许的原状态；两种原因分别配置，不能默认相同。管理员核实本应用所需
blocks.read/write、reservations.read；FIT→GROUP 另需reservations.write及对应已发布操作。只启用 Block 取消时不必额外授予 FIT 取消权限。 -
cancellationPolicy保存上述值与核验记录verificationRef；CANCEL_ALLOTMENTroute 允许单独取消。typeConversionsEnabled默认 false，完成目标 NEW/UPDATE 路由验证后才设 true。设置 true 仍不放开 GROUP→FIT。 -
FIT 字段建议把以下问题交 Oracle 支持／接口负责人，要求新证据，而不是重复公开检索：
请确认目标 OPERA Cloud 版本 Stay Details → TA Record Locator 的正式 OHIP 接口：postReservation / putReservation 的准确 JSON Pointer、getReservation 的读回 Pointer 与必要 fetchInstructions；若应使用其他接口，请提供 Operation ID、请求/响应样例及版本依据。该值是旅行社 Tour Code，不是 GDS Record Locator、Guest Locator 或普通 External Reference。还请说明 TA_RECORD_LOCATOR 与 Reservation Protection 控制对写入的影响。
若手头已有 TA 有值的测试 FIT，可先只读查询该 Reservation，交付脱敏的字段结构与已知 TA 值用于定位返回字段；这只能补读回证据，仍须官方依据或受控测试证明写入。不得提交 Cookie、Token 或完整客人资料。
-
字段证据和真实配置齐备后，再由用户更新运行服务，在明确测试酒店/数据上验收。上传 EML、确认/续办、重启、数据准备和酒店修改均由用户操作。当前没有这些操作的完成记录。
本地验证
正式 Factory → Runtime → Worker → JDBC 日志 → localhost 酒店替身已覆盖：单独取消、FIT→GROUP、GROUP→FIT 提前阻断、同类型普通修改、已取消旧记录过滤、配置/权限缺失、配置中途变化、关联客人/不完整查询/下一状态禁止、未知取消不重发、取消回执丢失后精确查询恢复、重启不重复新建。全部使用临时 H2 与合成数据，绝非真实酒店验收。
最终检查数量和日志见测试证据。