212 lines
11 KiB
Markdown
212 lines
11 KiB
Markdown
# 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)。
|