101 lines
7.7 KiB
Markdown
101 lines
7.7 KiB
Markdown
# ARR 有效价读取：平台接口补充清单
|
||
|
||
**后续状态：已补齐。** 用户2026-09-16通知后，目录0.7.0提供GET getRateInfo及推荐POST searchRateInfo；
|
||
5笔测试预订/11次只读调用通过。见[发布验证](../../.project-docs/50-evidence/topics/2026-09-16-rate-info-publication.md)。
|
||
以下为补充前的历史需求；GET现已标记上游弃用，新接入优先POST，原文“未封装”不再代表当前状态。
|
||
|
||
2026-09-16。供平台开发讨论；本助手未向他人发送此文件，也没有修改平台或应用授权。
|
||
用户随后明确由其联系平台开发者补充getRateInfo，完成后通知本任务。
|
||
|
||
ARR 已在 OHIPSB02 通过 `searchHotelReservations` + `getReservation` 取得2026-09-15到店的139笔完整详情。
|
||
下一项需要验证的是**指定预订、指定日期的有效价**，不能直接使用搜索结果中的当前价格。
|
||
|
||
## 推荐补充的一个只读操作
|
||
|
||
优先封装 Oracle RSV 的 **`getRateInfo`**：
|
||
|
||
```text
|
||
GET /rsv/v1/hotels/{hotelId}/reservations/rateInfo
|
||
```
|
||
|
||
这是 Oracle 路径，不是已经存在的 Edge 路径。平台应自行确定固定包装路由，并在catalog/OpenAPI公布Operation ID、
|
||
参数白名单、响应封装、能力组和重试规则。ARR 不会绕过 Edge 直接调用 Oracle，也不会猜测平台路由。
|
||
|
||
Oracle description 指明读取预订费率资料，并限制时间跨度21天；`#/definitions/rateInfo` 包含：
|
||
|
||
| Oracle响应路径 | 规范含义与ARR用途 |
|
||
|---|---|
|
||
| `detail.totalRateAmount` | **指定预订及日期的Effective Rate**；是XML `EFFECTIVE_RATE_AMOUNT` 的直接候选，仍需同源样本验收 |
|
||
| `detail.totalPackageAmount` | 指定预订/日期的包价合计，用于解释价格差异 |
|
||
| `detail.totalTaxAmount` | 税额合计，核对税口径 |
|
||
| `detail.revenue` | 金额、税、币种等明细，按totalType解析；不凭字段名推断税内/税外 |
|
||
| `detail.packages[]` | 包价金额细项 |
|
||
| `detail.rateSuppressed` | 价格隐藏标记；不得将隐藏或缺失的金额填0后继续 |
|
||
| `warnings` | 业务警告，不能只看HTTP状态 |
|
||
|
||
如果 Edge 继续使用已知的 OHIPDocument 包装，上述路径将位于 `data.detail.*`；新接口未发布前这只是预期包装方式。
|
||
规范另有 **`searchRateInfo`**，POST `/rsv/v1/hotels/{hotelId}/reservations/rateInfo/searches`，返回同一个rateInfo结构。
|
||
目前只需选一项作为最小验证入口，不要求同时封装GET和POST。
|
||
|
||
## 最小验证请求
|
||
|
||
从本批搜索返回的内部Reservation ID选样本，不使用Confirmation No。先测试以下字段组合：
|
||
|
||
| query | 值 | 依据/限制 |
|
||
|---|---|---|
|
||
| `id` | `<内部Reservation ID>` | Oracle查询参数定义的对象ID；必须验证确实按该预订读取 |
|
||
| `type` | `Reservation` | 按已知预订身份类型构造的候选，参数本身是无枚举字符串；需平台实测 |
|
||
| `summaryInfo` | `false` | 请求detail，而不是住宿总价summary |
|
||
| `detailDate` | `2026-09-15` | 规范明确详细结果需要日期，固定为待处理到店日 |
|
||
|
||
以上参数存在且类型已离线核对，**尚未证明这一最小组合在目标Oracle环境足够**。若还需criteriaStartDate/EndDate，
|
||
应依据被查预订及请求日期补足、验证边界并遵守21天限制，不能默认为整段入住只返回一个价。
|
||
|
||
不要为了让调用通过而覆写ratePlanCode、roomType、adults/children，或使用新的报价条件替代已存预订数据。
|
||
currencyCode也是可选参数，首轮不主动转换货币；必须记录实际返回的币种依据，再与原报表核对。
|
||
|
||
可机读示例及来源标识见 [rate-info-oracle-examples.json](rate-info-oracle-examples.json)。其中没有凭证或真实预订ID。
|
||
|
||
## 为什么现在需要它
|
||
|
||
- 当前139笔详情、396个费率项均未返回规范中的`effectiveRate`。单独取RateInfoDetails/DailySummary仍未补齐。
|
||
- 9笔搜索rateAmount不同于到店日base；这9笔的搜索价全部匹配2026-09-16费率，而到店日为2026-09-15。
|
||
这证明本批搜索摘要不能直接用作昨日价格，不表示已经证明所有预订都按系统今天取价。
|
||
- 另7笔详情total与base不同；其差额全部等于2026-09-15的`computedResvPrice`包价合计，均是独立列示的包价样本。
|
||
22笔有包价的记录中还存在不同addToRate/printSeparateLine组合，不能简单把所有包价都加一次。
|
||
- 因此优先读取Oracle明确提供的“预订+日期→有效价”，再验证报告对应关系；不在ARR里猜测税/包价/折扣算法。
|
||
|
||
这些差异来自现有私有原件的本地分析，未新增或修改任何预订。金额正文、客人和公司名不进入此清单。
|
||
|
||
## 平台验收应回传什么
|
||
|
||
1. 新的catalog/OpenAPI条目：固定Operation ID/Edge路由、query或body字段及类型、能力组、同步只读语义、限流/重试行为。
|
||
2. 目标测试酒店中已存预订的日期详情响应，记录request ID、酒店、查询身份和detailDate；原始内容按私有资料交付。
|
||
3. 优先覆盖九笔跨日变价、七笔独立列示包价、addToRate组合、普通无包价，以及有适用样本时的折扣/税/共享/多房。
|
||
样本可按ARR私有索引定位，不能只用一个没有包价的成功请求代表全部口径。
|
||
4. 证明`summaryInfo=false`得到detail而非summary；缺价、rateSuppressed、无效ID/日期、超过21天和业务警告须有明确处理。
|
||
5. 核对这是读取已存预订价格的操作。不要将validateRateInfo、Refresh Rates、预订修改或重新报价写入流程混进只读接口。
|
||
|
||
平台补齐后，ARR仍需与同环境、同酒店、同预订/日期的原报告做字段比对，才可选作生产来源。
|
||
如果该API返回的Effective Rate不等于原XML列，保留差异并查清报表口径，不静默改财务定价。
|
||
|
||
## 其余接口取舍
|
||
|
||
| 操作 | 本轮结论 |
|
||
|---|---|
|
||
| searchHotelReservations / getReservation | 保留现有主干，已验证一日完整候选及详情获取 |
|
||
| getRateInfo（或searchRateInfo二选一） | 本次提出的平台新增只读封装候选；目录未提供，无法由ARR自行授权出一个不存在的操作 |
|
||
| getBlock | 9/17原件复查纠正：26笔除了Block ID，还在blockIdList中返回typed BlockCode，两层一致；已可取值，无需为这些记录补查或扩大blocks.read授权 |
|
||
| getProfile | 暂无新增依据。详情已经有角色和名字结构，本批仅有Group角色；再读同一Group Profile不能证明Company/TravelAgent/Source的报告优先级 |
|
||
| 财务账单、住宿日汇总、费率计划配置 | 不用这些结果替换固定ARR计价，也不将配置报价当成已存预订的指定日有效价 |
|
||
|
||
报告的状态/空ETA/顺序仍是业务等价验证项。这里请求的是具体读接口，不是新的页面自动化或原生XML导出工程。
|
||
|
||
## 来源与当前状态
|
||
|
||
- 2026-09-16本轮CLI回读：catalog0.6.0/111操作，`getRateInfo`、`searchRateInfo`均不存在；request ID `f90ce73e-eb4d-4168-b5cb-5274b9da6d49`。
|
||
- Oracle固定提交的 [rsv.json](https://github.com/oracle/hospitality-api-docs/blob/dd631fbd5d0fce74a7dbdf96b43f07ce587211f2/rest-api-specs/property/v1/rsv.json)：getRateInfo/searchRateInfo、rateInfo、searchRateInfoRequest。
|
||
- Oracle [Updating Reservations](https://docs.oracle.com/en/industries/hospitality/opera-cloud/25.5/ocsuh/t_managing_reservations_editing_reservation_stay_details.htm)
|
||
说明Effective Rate考虑加到房价的包价项目，支持区分rate/base与effective；不据此替代本酒店原报告验收。
|
||
- [139笔实测证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-api-live-probe.md)；[本轮语义追查](../../.project-docs/50-evidence/topics/2026-09-16-arr-api-semantics.md)。
|