# ARR 已接接口与实际传参确认单

核对日期：2026-10-08。依据当前调用代码、已保存的公开契约和2026-10-07到店日的生产响应捕获。
已在本机离线重放176次已捕获读取，识别58条预订；本轮说明更新不发起OHIP请求、不读取密钥、不改变真实任务。
生产请求兼容和字段识别已核对，10月7日正式日报仍待业务字段值确认，尚未通过生产报表验收。

## 页面输入与参数来源

用户只选择**报表日期D**，例如`2026-09-15`。页面提交到ARR自身的请求为：

```text
POST /api/arr-downloads
```

```json
{
  "report_date": "2026-09-15",
  "request_id": "<系统生成并保存的32位任务编号>"
}
```

任务编号用于ARR内部防重复和恢复，不作为下面8个OHIP接口的业务参数。继续原任务时调用ARR自身的
`POST /api/arr-downloads/{request_id}/retry`，正文`{}`，沿用原日期；预选下一日期不改变已提交任务。

| 代号 | 含义 | 来源 |
|---|---|---|
| D | 报表日期/到店日期 | 页面当前选值；初始建议值为曼谷日历昨天，用户可以改选，后台不再次减一天 |
| R | 预订内部ID | 列表返回的`reservationIdList`中`type=Reservation`的ID；不是显示给客人的确认号 |
| P | 档案内部ID | 预订中关联的`profileIdList`、`type=Profile`；姓名查询使用唯一主客的档案ID |
| B | 团队内部ID | 预订到店日资料中`blockIdList`、`type=Block`；不是团队代码 |
| C | 套餐代码 | 预订详情的`reservationPackages[].packageCode` |
| E | 离店日期 | 同一笔预订的离店日期，经检查不早于D |

## 共同连接设置

- 平台地址：`https://ohip.nianxx.cn`。
- 当前应用：`Wyndham-ARR2.0-Codex`，应用ID`caller_zloxalzsQ9pYsztt`；预期酒店由实例配置提供。
- 每个请求携带`X-API-Key`，值由私有凭据文件提供；本文不包含密钥。
- 同时携带`Accept: application/json`与`Content-Type: application/json`。
- 当前请求没有单独传`hotelId`或`x-hotelid`；酒店由平台路由确定，ARR核对返回酒店与配置一致。应用ID也不作为单独请求头传出。
- 酒店核对值来自当前实例配置。2026-09-18历史沙箱记录使用`OHIPSB02`，不能据此认定生产实例酒店；生产环境沿用已批准的绑定配置。
- 下列8项均为查询，不修改Oracle订单。POST在此用于查询条件提交。

## 1. 到店预订列表 — searchHotelReservations

用途：找到D当天到店的预订，为后续逐笔查详情提供R。

`POST /api/v1/reservations/searches`，正文：

```json
{
  "arrivalStartDate": "2026-09-15",
  "arrivalEndDate": "2026-09-15",
  "limit": 100,
  "offset": 0
}
```

- 两个日期都等于D；按到店日期查询，不是D当天所有在住或离店客人。
- 每页100条，后续`offset`为100、200……；读取平台分页结果决定何时结束。
- 结构化入口不传可选`orderBy`和`sortOrder`：生产核对中带排序参数的请求被拒绝，省略后成功。历史候选捕获入口保留其原请求。
- 生产默认排序规则尚未证实。每页按接口返回顺序保留，沿用`source_sequence`；不另行重排或提前去重。
- 所有详情和补查结束后，重新查询同样的完整列表，逐项检查内容与顺序。每轮还验证唯一预订身份、重复ID、总数、页数和末页完整性；这不是一个额外接口，也不构成原子快照。
- 当前未显式传预订状态、分房状态、费率代码、市场代码或公司筛选条件。**不传状态不等于已经确认平台默认包含全部状态**。
- ARR不在查询阶段应用后续费率白名单和业务去重。

## 2. 预订详情 — getReservation

用途：取得确认号、入住/离店日期、人数、房间数、房型、费率、备注、档案/团队/套餐关联资料，并优先从详情确定房号等字段。

`GET /api/v1/reservations/{R}`，无正文，查询参数`fetchInstructions`重复传7项：

```text
Reservation
Comments
DailySummary
RateInfoDetails
Packages
InventoryItems
Shares
```

即`?fetchInstructions=Reservation&fetchInstructions=Comments&...`，不是逗号拼成一个值。
每笔预订调用；不传日期参数，收到详情后在程序中选出D适用的日资料。`Traces`明确不请求。
备注请求为`Comments`，当前没有额外传“GEN”或“包含内部备注”的开关；返回后由程序提取GEN备注，内部备注不被主动排除。

## 3. 指定日有效房价 — searchRateInfo

用途：取得这笔预订在D的有效价格。

`POST /api/v1/reservations/rate-info/searches`，正文：

```json
{
  "id": "R123",
  "type": "Reservation",
  "summaryInfo": false,
  "detailDate": "2026-09-15"
}
```

`id=R`，`detailDate=D`；每笔预订调用，不是按确认号查询。当前自动数据入口使用POST的`searchRateInfo`，未使用GET的`getRateInfo`。
不传币种或指定价格数值；从返回数据取有效价及币种并核对，隐藏/缺失价格不当成零。

## 4. 主客姓名摘要 — getProfiles

用途：取得唯一主客的完整显示姓名，并与预订中的姓名组成核对。

`GET /api/v1/profiles`，无正文，查询参数：

```text
profileIds=P456
summaryInfo=true
limit=1
offset=0
```

即`GET /api/v1/profiles?profileIds=P456&summaryInfo=true&limit=1&offset=0`。
每次只查已关联主客的一个精确档案ID；不按姓名模糊搜索、不查询全部住客或陪同人。
相同档案的同类查询可在本次采集中复用。严格核对返回`operation_id=getProfiles`、酒店、Oracle请求编号、
唯一档案ID、单条完整结果及姓名组成，再保留完整显示姓名原文。
生产核对中的`searchProfiles` POST不可用；结构化入口改用已验证的GET，旧POST姓名探针保留给历史流程。

## 5. 档案详情补查 — getProfile

用途：预订内主客姓名结构不完整，或关联档案未嵌入公司名称时，补取已知档案。

`GET /api/v1/profiles/{P}`，**无额外查询参数、无正文**。

不是每笔必调；公司/旅行社/Source/Group关联按原角色保留，最终公司名称仅从Company/TravelAgent中取。
存在多个不同公司/旅行社名称时保留多候选异常，当前不擅自规定优先级。

## 6. 团队代码补查 — getBlock

用途：预订已明确关联团队B，但没有可直接使用的团队代码时补查。

`GET /api/v1/blocks/{B}?fetchInstructions=Block`，无正文。

已有明确且一致的团队代码时不补查；没有团队关联不凭空查团队。明确代码冲突不会被补查静默覆盖。

## 7. 房间和换房历史补查 — getRoomCalendar

用途：详情仍无法确定房号时，取得D的房间资料，再在本地按R匹配需要补查的预订。

`GET /api/v1/reservations/room-calendar`，首个请求的查询参数：

```text
startDate=D
endDate=D
includeRoomMoveHistory=true
showRoomMoveSegments=true
```

- 首个请求不传`pageIndex`和`recordsPerPage`。
- 若返回尚未完整，后续增加`pageIndex=上一页返回的pageIndex+1`、`recordsPerPage=返回的每页条数`，其余条件不变。
- **没有向该接口传预订ID或房号筛选**，程序读取返回的房间集合后按R匹配；不是每一笔缺房号都重新查一遍全酒店。
- 已有明确房号或明确为空的记录不触发这项补查；历史有多个不同房号且无法唯一确定时保留异常。
- `roomCalendar={}`表示本次没有取得可用房间集合，不证明该预订在D没有房号；缺口进入字段完善，房号不能确认为空。

## 8. 套餐详情补查 — getPackage

用途：预订已有套餐代码C，但未给出`scheduleList`时补齐套餐适用资料。

`GET /api/v1/reservations/{R}/packages`，查询参数：

```text
productCode=C
reservationTimeSpanStartDate=D
reservationTimeSpanEndDate=E
fetchInstructions=Primary
fetchInstructions=Schedule
```

无正文；`fetchInstructions`重复传两项。起止日期覆盖该预订入住到离店，**这一项的结束日期是E，不是D**。
有多个需补查的套餐时逐个代码查询；已有`scheduleList`（包括明确空列表）时不调用补查。

## 调用次数和无数据行为

8个指8种接口，不是每次下载只发8次请求。列表需要分页并在末尾复查；详情、房价、姓名按预订/档案查询；其余按条件补查。
当前本机默认每页100条、最多100页/10000笔预订，单次采集最多25000次HTTP尝试；单请求超时25秒，符合条件的暂时失败最多尝试3次。
这些是本地处理上限，只有各接口表中列出的分页值会作为查询参数传出。
如果列表没有任何预订，当前程序以`empty_source_requires_review`结束采集，不自动生成零条日报。

## 字段完善与价格复核

列表完整取得后，`reservationBlock`、`reservationPackages`、`reservationProfiles`等原生可选字段省略，
以及未能唯一确定房号等情况，保留原始观察与缺口；未经人工确认不补成空值，也不按Cancelled/NoShow状态丢弃预订。
后台`DataFieldReviews`按同一冻结处理器的白名单和字段验证规则识别阻塞项，任务进入`needs_data_review`。
业务人员填写缺失值；只有原规则允许为空的团队代码、预订备注、套餐和房型可明确“确认无此项”，公司与房号仍须有效值。

全部阻塞项确认后，冻结带操作者、版本、原值及改值的派生来源，原捕获不改写。
原请求自动继续共用筛选、去重、定价和独立校验；若此后缺少pureprice，才进入既有`needs_review`价格复核。
价格复核完成或无需复核时，沿用原Finance日报提交与月报自动更新链路。字段完善和价格复核是前后两步。
操作入口见[直接数据入口说明](arr_web/DIRECT_DATA_ENTRY.md)，人工XML上传继续保留。

## 本次请确认的业务范围

| 项目 | 当前实现 |
|---|---|
| 日期范围 | 所选日到店；详情日价/房间历史针对所选日，套餐针对完整入住期间 |
| 客人范围 | 姓名使用唯一主客档案，不逐一查陪同人姓名 |
| 取数与加工 | 先取数据，再使用原白名单、去重和定价规则；不请求XML，不获取Trace |
| 状态覆盖 | 没有显式传全部预订/分房状态，需要核对平台默认范围，不能把这一点算作全状态验收通过 |
| 备注覆盖 | 请求Comments后提取GEN并保留内部备注；已识别实际响应，业务所需备注是否完整仍待确认 |
| 公司与房号冲突 | 保留异常，不自行选择公司优先级或随意选一个换房房号 |

本轮只调整结构化入口的可选排序和姓名摘要请求兼容，保留原取数范围及处理规则。
参数样例中的R123/P456/B789/PKG1是虚构标识。已完成的生产捕获离线重放不等于10月7日业务字段确认或日报验收完成。

实现依据：[请求封装](integrations/ohip/data_client.py)、[调用与补查条件](integrations/ohip/arr_data.py)、
[预订查询及连接](integrations/ohip/collect_arr_source.py)、[房价请求](integrations/ohip/rate_info.py)、[姓名摘要请求](integrations/ohip/profile_summary.py)。