63 lines
8.6 KiB
Markdown
63 lines
8.6 KiB
Markdown
# 参数接口与独立模拟验收交付
|
||
|
||
> 历史验收记录：下文为暂停TA之前的实现。当前无TA代码与新一轮47参数/3故障已完成，以[无TA交付](ohip-no-ta-local-test-20260918.md)为准；平台接口连接沙箱，现有环境更新由用户执行。
|
||
|
||
日期：2026-09-18；接续 9 月 17 日无人值守要求。上传 XML/EML、操作已有任务和更新现有服务仍由用户完成。本轮只读查证公共资料、修改本地代码并运行独立合成参数测试，没有创建子智能体。
|
||
|
||
## 参数与接口现在到哪一层
|
||
|
||
[逐参数对照表](ohip-parameter-interface-mapping-20260917.md)已更新到实际发布状态，修正 `blockProfileType` 角色字段，并去除过期“接口尚未发布”结论。公共目录有 184 个操作；消费端登记的 18 个非附件操作，其方法、路由、查询参数白名单全部匹配。
|
||
|
||
| 业务 | 参数及接口接入 | 真实环境边界 |
|
||
| --- | --- | --- |
|
||
| GROUP 新建 | Block Name/TA、日期、Account/Contact、Rate、含早、GTT/TA/GC/BTQR/TEN/THB → `postBlock/getBlock`；完整逐晚房量 → `putBlockAllocation/getBlockRoomRateGrid` | 需真实酒店代码、档案和房量控制；本轮未启用 |
|
||
| GROUP 修改 | 先按 Tour 查当前 Block；只更新日期/TA/完整房量，保留 Rate、状态、Account 等 | Initial/Actual 与人数分列独立；改期真实行为待酒店验收 |
|
||
| FIT 新建 | 姓名/CN → `postProfile/getProfile`；共享 Guest、Agent、日期/房型房数、Rate、Fixed Rate、Adult/GC/BTQR、Note → `postReservation/getReservation` | **TA 正式写读字段未获证，正式入口保持阻断** |
|
||
| FIT 修改 | `searchHotelReservations/getReservation/putReservation`；同类型有界新增房型复用实际 Guest 和创建接口，备注按历史证据定位 | 同一 TA 缺口；不能把模拟成功称为真实 Oracle 成功 |
|
||
| 源 Allotment 取消 | 查 Block、关联预订、下一状态 → `putBlockStatus` → 精确状态回查 | 酒店须提供 Block 原因和取消状态；关联客人/PM 或不完整查询继续阻止 |
|
||
| FIT→GROUP | 完整检查最终 GROUP 参数后，逐笔 `postCancelReservation`，查实取消，再复用 GROUP 新建 | 正式编排已接；仍需真实环境配置/验收 |
|
||
| GROUP→FIT | 同次确认内取消 Block 后创建 FIT 的编排和模拟链已跑通 | 因真实 FIT TA 契约未齐，正式入口在取消原团之前阻断 |
|
||
|
||
Account/Contact 和代码查询所需的 `getProfiles/getProfileRelationships/getRoomTypes/getRatePlansByHotel/getMarketCodes/getSourceCodes/getGuaranteeCodes/getPaymentMethodsLOV` 已发布；取消配置 `getCancellationCodes/getBlockCancellationReasons/getBlockStatusCodes` 及 `getOperaSettings` 也已发布。本应用业务运行使用受信的酒店映射，不会每次按名字猜档案或把配置查询自动变成权限授予。这里没有新增让平台同事重复封装的清单。
|
||
|
||
## 测试参数已补齐
|
||
|
||
模拟目录 [catalog.example.json](../../../server/src/test/local-fit-simulation/catalog.example.json) 只含合成姓名和 ID。房型/Rate 直接使用冻结目录的 **10 个房型、21 个 Rate Code**，没有复制一套选价逻辑。GRPA3 含早/BUALUANG、GRPA4 含早/LEELA 保持原已确认规则；餐厅不另造 Oracle 写入字段。
|
||
|
||
- 两个 Account 各有 Agent、关联 Contact 和同名 Company 干扰项。GROUP 必须是 Agent/AgentContact，FIT 必须是 TravelAgent 关联到 Agent；跨账户 Contact、Company 冒充 Agent、无效 Guest ID 会被模拟酒店拒绝。
|
||
- Market、Source、Reservation Type、Payment、Currency、Room Type、Rate Code 都在模拟酒店真正校验，错误请求不能改变已存对象。之前只有 Java 展示目录，现在不再仅靠显示名称判断接通。
|
||
- 新增独立模拟取消原因 `SYN-FIT-CXL`、`SYN-BLOCK-CXL`，状态 `TEN/ACT/SYN-CANCEL`、下一状态规则、`occupancy_split_enabled=false`。它们不是目标酒店真实值，不能复制到正式配置。
|
||
- Initial/Actual 两份网格独立保存，查询按 `roomAllocationCriteria` 精确筛选。未启用人数分列时总量使用 onePerson；Actual 不代表必须拆成人数列。开启分列的原生模拟校验独立覆盖，应用层仍要求明确完整四列，不能猜分配。
|
||
- 模拟 TA 专用属性 `__localSimulationTaRecordLocator` 明确保留为测试协议；正式 Adapter 没有采用这个字段。
|
||
- 已取消历史仍出现在模拟搜索里，应用必须根据精确详情过滤；不能靠模拟酒店偷偷隐藏旧记录让测试通过。
|
||
|
||
隔离参数验收不读取 Excel，也不上传 XML/EML。旧纯协议单元测试仍可不加载完整目录；**完整接口验收必须以 `--catalog` 启用严格参数目录**，缺失新 `simulation` 配置就拒绝启动。现有私有目录/运行服务没有被替换。
|
||
|
||
## 完整测试发现并修复的问题
|
||
|
||
1. GROUP UPDATE 残留“来源附件必须非空”的条件已去除，无附件也能按确认参数更新。邮件原件的接收/查看和历史附件审计不受影响。
|
||
2. 本地状态策略把 allowPickup 同时当作人数分列开关，导致 Actual 更新准备失败。现在独立读取分列配置，Initial/Actual 只决定网格类别。
|
||
3. 模拟网格查询忽略类别，Actual 查询混入 Initial 旧格。现在按请求返回真实对应类别，另一类不会被清零或改标签。
|
||
4. 同类型 FIT 的内层查询重新把已取消历史纳入目标；现在沿用外层精确识别结果，新增房型后的最终集合核验也排除详情已确认取消的旧记录。仍保留原确认、酒店、时间和租约校验。
|
||
5. GROUP→FIT 首次预检在原目标/检查点尚未由 Worker 保存时冻结 Guest 计划，触发 `GUEST_CONTEXT_CHANGED`。现在首次预检只返回准备结果，持久检查点存在后才冻结客档计划，没有放松仓库一致性校验。
|
||
|
||
保留既定拒绝边界：两笔旧 FIT 不能直接压成总共一间房并暗中取消一笔；本次把它列为预期拒绝并验证零写入。已支持的同住期、同 Guest、总数足以承接原编号的房型合并及有界新增房型继续运行。加床及其他未授权业务未扩展。
|
||
|
||
## FIT TA 官方查证结果
|
||
|
||
这轮检查了固定官方提交 `4bd129b455bc5e3ab0f900ac47983611e58659b4` 下 **全部 45 个 Property v1 模块**，不只查 RSV。BLK 文件下载重试失败后，使用已缓存文件并核实 Git blob 摘要与该提交完全一致。
|
||
|
||
- [BLK](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/blk.json) / BLK Async 有 Block 的 `reservationDetails.taRecordLocator`。
|
||
- [RSV](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/rsv.json) 的 `taRecordLocatorList` 是搜索条件；仍未找到 Reservation 创建/修改的相应属性。
|
||
- 新发现 [FOF 佣金模块](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/fof.json) `commissionDetailType.recordLocator` 描述为 TA Record locator。反向追踪到佣金查询/重算返回，未找到将其作为 Reservation TA 写入参数的接口。它不能替代 `getReservation` 的正式字段契约。
|
||
|
||
因此剩余准确缺口仍是：**FIT TA 的写入 JSON Pointer、精确读回 Pointer、所需 fetchInstructions/酒店控制及版本依据**。不是再缺一个已知待封装路径。给 Oracle/接口负责人的具体问题沿用[上一份交付](ohip-formal-cancellation-fit-ta-20260917.md)，不重复要求平台同事搜索同一套公开文档。本轮未向外部发送消息。
|
||
|
||
## 复现与运行边界
|
||
|
||
运行器：[check_parameters.py](../../../server/src/test/local-fit-simulation/check_parameters.py)。它新建专属目录、临时 PostgreSQL、随机 loopback 端口的 Go Edge 与模拟酒店、独立 H2；完成或失败后停止自己创建的进程。不会启动工作台、上传文件、访问现有 5178/8082、使用真实凭证或初始化用户的测试数据。
|
||
|
||
命令及组件限制见[模拟工具说明](../../../server/src/test/local-fit-simulation/README.md)。这是应用参数与本地 HTTP/持久日志验证；取消入口在一次性 Go 副本中使用已有测试夹具，不是拿当前线上平台或真实 Oracle 写入做验收。公开目录匹配、隔离请求成功、实际应用授权、真实酒店接收是不同的证据。
|
||
|
||
最终数量、日志、失败定位与清理记录见[本轮证据](../../../.project-docs/50-evidence/topics/2026-09-18-parameter-simulation-closure.md)。用户之后仍负责文件上传和真实环境操作；本轮不需要用户补上传文件才能完成上述测试。
|