# 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)。