233 lines
26 KiB
Markdown
233 lines
26 KiB
Markdown
# ARR 业务要素与平台 API 对应表
|
||
|
||
2026-09-17后续：已把严格取值器串成逐笔候选准备，16列分别记录取值或缺口；139笔全保留，
|
||
73笔房号/134笔日价/115笔费率代码可取，显示与报表口径仍未验收。按钮后台已有显式v3与姓名上限支持，
|
||
237项范围测试通过，未启用正式接线。[完成记录](../../.project-docs/50-evidence/topics/2026-09-17-arr-offline-preparation-and-v3-executor.md)。
|
||
|
||
2026-09-17补充：姓名不是完整主体采集的强制依赖。新增[独立补充路径](profile-supplement.md)复用完整v2，
|
||
查询失败只形成姓名缺口，恢复只补缺失；旧v3交错查询及历史失败记录不改。仍是候选字段，未验收完整ARR。
|
||
|
||
2026-09-17更新：v3姓名候选已接入字段证据、独立Profile身份关联和同源XML原文/去空格观察；
|
||
19新用例/198范围测试通过。旧139笔证据不变，真实失败批次仍拒绝完整导出；未关闭业务验收项。
|
||
用户已将503诊断转给平台，本轮未新增接口调用，后续全部独立完成、不创建子智能体。
|
||
[本轮证据](../../.project-docs/50-evidence/topics/2026-09-17-arr-named-field-evidence.md)。
|
||
|
||
2026-09-16，接口讨论稿。主干候选为 `searchHotelReservations → getReservation + searchRateInfo + searchProfiles → 完整批次校验 → 确定性适配 → 既有 ARR 处理链`。
|
||
前三项操作在`reservations.read`，姓名摘要在已批准的`profiles.read`内。最初只读联调已取得 OHIPSB02 / 2026-09-15 的139个候选预订及全部详情，
|
||
身份与分页检查通过。XML输出层已实现，最终API来源映射未完成，也未提交 Finance。优先以[实测证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-api-live-probe.md)
|
||
和[聚合结果](arr-api-probe-results-20260916.json)解释下列规范候选；官方示例不能替代实际返回。
|
||
|
||
2026-09-16后续：已完成[采集及本地档案核验](README.md)与[同源验收清单](arr-api-acceptance-matrix.md)。
|
||
用户随后已通知日价接口补齐。当前样本的完整显示名未返回、费率段全为单日、重复候选可能影响结果；详见[聚合核验](arr-api-capture-audit-20260916.json)。
|
||
|
||
最新推进：catalog0.7.0提供推荐POST **searchRateInfo / detail.totalRateAmount**，其定义就是指定预订及日期的有效价；
|
||
GET getRateInfo为已弃用的兼容入口。5笔/11次只读验证通过，详见[发布证据](../../.project-docs/50-evidence/topics/2026-09-16-rate-info-publication.md)。
|
||
日价已接入v2整批采集/归档/回放/本地批次管理；XML有效价同源对应仍待验收。
|
||
[平台补充清单](rate-info-platform-request.md)保留此前需求历史。
|
||
|
||
最新显示字段核对：[聚合结果](arr-display-contract-20260916.json)及[证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-display-contract.md)。
|
||
原57106 XML公司列为65条`T- `、6条`C- `、1条空；不能直接把API纯名称认作同一展示字段。
|
||
对照器新增角色前缀和到店日人数的独立假设，共42项观察，40项工具测试/87项相关回归通过。
|
||
|
||
用户给出的 Opera 操作用于定义业务条件。当前工作不再推进页面点击、计划报表或 SFTP；没有原生 XML 下载操作不阻止研究 API 数据获取。
|
||
|
||
来源适配基础层已实现：[逐笔字段证据](source_facts.py)及[独立验证](validate_source_facts.py)覆盖完整139笔候选，
|
||
保留16列的原始出处、类型、缺失/空值、多值及上下文。16新测试/140相关测试通过；851原件未变。
|
||
它不选择最终字段或输出XML，全部业务就绪标记仍false；[证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-source-field-evidence.md)。
|
||
|
||
最终输出格式也已具备：[arr_xml.py](arr_xml.py)将明确选定的有序行生成处理XML，独立解析器验证字段/列表。
|
||
原生样本72行投影的处理结果与原基准一致，但API的最终取值/行选择仍未实现。官方新增证据保留Source角色，
|
||
明确排序可配置；旧版共享/组合房数量说明使numberOfUnits直映需进一步验收。
|
||
[实现与官方依据](../../.project-docs/50-evidence/topics/2026-09-16-arr-xml-output-boundary.md)。
|
||
|
||
## 1. 实际需要调用的接口
|
||
|
||
| 阶段 | Operation ID / Edge 请求 | 请求与返回 |
|
||
|---|---|---|
|
||
| 取得候选预订集合 | `searchHotelReservations` / `POST /api/v1/reservations/searches` | JSON 请求体直接放 `arrivalStartDate`、`arrivalEndDate`、`limit`、`offset` 等；不是 query，也没有自行添加的 `criteria` 外层。记录在 `data.reservations.reservationInfo[]` |
|
||
| 补齐每笔资料 | `getReservation` / `GET /api/v1/reservations/{reservationID}` | `fetchInstructions` 为重复的 query 键；详情在 `data.reservations.reservation[]`，必须按预订身份匹配，不能无条件拿数组第一项 |
|
||
| 读取指定日有效价 | `searchRateInfo` / `POST /api/v1/reservations/rate-info/searches` | `{id:内部Reservation ID,type:Reservation,summaryInfo:false,detailDate:系统指定日}`；使用 `data.detail.totalRateAmount` 和 `detail.revenue.currencyCode`，无重新报价参数 |
|
||
| 读取主客姓名摘要 | `searchProfiles` / `POST /api/v1/profiles/searches` | `{profileIds:[详情中唯一主客内部Profile ID],summaryInfo:true,limit:1,offset:0}`；身份/组成相符后原样保存`profile.formerName.fullName`；姓名缺口独立诊断，不能自行拼接 |
|
||
|
||
运行时使用 ARR 独立应用的 `X-API-Key`；CLI 管理授权和读取目录。Oracle 酒店上下文由 Edge 提供，客户端必须核对响应的
|
||
`hotel_id`。请求不能通过随意新增 `hotelId` 来切换酒店。响应外层还有 `operation_id`、`oracle_request_id`；它与 CLI
|
||
目录响应的 `ok/status/request_id/data` 封装不是一回事。
|
||
|
||
详情试验请求使用 `Reservation`、`Comments`、`Traces`、`DailySummary`、`RateInfoDetails`、`Packages`、`InventoryItems`、`Shares`。
|
||
这些均存在于该操作枚举，返回块完整性仍待实测。`GuestComments` 不是此次预订备注要求的自动替代项。
|
||
搜索接口的 fetch 枚举不含 `Comments/Traces`，不能只取列表便假定取得完整备注。
|
||
|
||
有 N 个独立预订、P 页搜索时，v2基本请求数为2P+2N：两轮完整搜索、每笔详情与日价；重试另计。
|
||
v3另加U个不同主客档案的摘要请求，重复档案只读一次、逐预订核验。当前139预订对应112档案，正常为394次请求；
|
||
v3采集/重放/批次复用已完成并通过217项范围测试，原3份摘要离线通过；随后用户获准的一轮实测共23次请求，
|
||
5个姓名成功、第6个连续3次503后停止，未得到完整日候选。[最新实测回执](named-day-live-result-20260916.json)。
|
||
[版本化姓名采集证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-named-day-capture.md)。
|
||
跨页重复在采集校验时拒绝，不能直接消掉再宣布完整。候选集合/次序不能被当成已经验证的报告行粒度/顺序。
|
||
|
||
## 2. 报表条件怎样落到请求
|
||
|
||
| 用户要素 | 契约中已存在的入口 | 调用决策与待验证处 |
|
||
|---|---|---|
|
||
| 系统传入 From Date / To Date（当前均为T-1） | `arrivalStartDate` / `arrivalEndDate`，格式 date | 上游计算并传入明确日期，ARR只校验并原样使用；当前要求两值相等。固定进批次，同日用于 `searchRateInfo.detailDate`；不在ARR按时钟/时区重算或改为营业日 |
|
||
| ALL Reservations | 不增加公司/旅行社/来源/Group/Block关联子集筛选 | 旧版官方报表说明把这个选项放在关联资料筛选，不能直接等同所有状态；当前Cloud的状态纳入范围仍独立核对 |
|
||
| 报告状态范围 | `reservationStatuses`；`actualArrivals`、`expectedArrivals`、`dayOfArrivalCancels`；`searchType` | 本批省略状态与显式全枚举返回相同139ID；单独CheckedOut准确返回2条。仍不能据此认定这就是报表ALL |
|
||
| ALL Room Assignment | `roomAssignedOnly` / `roomUnassignedOnly` | 基线均省略，已覆盖74已分房+65未分房。单侧筛选实测需要两个参数成对true/false；只传任一true未生效 |
|
||
| ALL CODES | 各代码子集筛选 | 基线不加代码限制，完整采集后才执行现有费率白名单。`ALL` 不是已定义的通用字面值 |
|
||
| 00:00–23:59 | `expectedArrivalStartTime` / `expectedArrivalEndTime`，规范格式 date-time、酒店时区 | 本批带+07:00返回0，无时区本地格式返回12，排除90缺ETA和37仅日期记录。先保留完整日期候选，不能直接把该时间过滤当作报表等价规则 |
|
||
| Room Number | 详情 `roomStay.currentRoomInfo.roomId`、费率段 `roomId` | 前者明确为当前房号，不能未经验证当作历史到店日报的房号；未分房记录不能预先排除 |
|
||
| Notes / Resv. - GEN | `Comments`；`comment.type`、`notificationLocation`、`text.value` | **实测为type=GEN + notificationLocation=RESERVATION**，含内部备注。官方示例恰好反向，应以真实配置/同源比对为准 |
|
||
| Include Internal Notes | `comment.internal` | 保留选定类别中的内部及外部备注，不只取 true；`confidential` 是另一字段。需要证实接口权限和 fetch 返回完整 |
|
||
| XML | 现有处理器输入格式 | API 返回 JSON。原始响应需要保存；是否转换为兼容 XML 或增加正式 JSON 来源契约，须在语义验证后确定 |
|
||
|
||
状态筛选的契约枚举为 `Cancelled/CheckedOut/CheckedIn/DueIn/DueOut/InHouse/NoShow/WaitList`。
|
||
它们不是手工 XML 的 `CKIN/CKOT` 编码；报表的状态纳入范围仍须逐类验证。
|
||
响应自身又使用另一套 `pMS_ResStatusType`，包含 Reserved、InHouse、Waitlisted 等，不能直接拿请求枚举作响应或 XML 转换表。
|
||
|
||
七类 ALL CODES 对应的现有筛选名称为：Room Type 用 `roomType`（单数名、数组），会员用 `membershipTypes`，
|
||
费率用 `ratePlanCodes`，库存用 `inventoryItems`，来源/市场用 `sourceCodes/marketCodes`；Preferences 没有统一 `preferences`
|
||
搜索字段，只有 roomSpecials、roomFeatures 等细分条件。因此基线省略这些子集条件，而不构造不存在的参数。
|
||
|
||
### 备注为什么必须单独验证
|
||
|
||
官方 `getReservation` 的 200 响应示例给出 `comment.type=RESERVATION`、`notificationLocation=GEN`、`internal=false`。
|
||
schema 将 type 和 notificationLocation 都定义为字符串，未固定二者的取值关系。后续实测表明该示例组合不适合当前测试数据：
|
||
30条GEN备注实际为type=GEN/location=RESERVATION，其中3条internal=true。因此撤回按示例方向推断当前映射的候选；正式酒店配置仍须同源比对。
|
||
用户 XML 中 58 条备注为 `CAS/GENERAL`，且没有内部备注标记；这个 XML 本身不足以证明内部备注返回完整。
|
||
用户现已明确确认准确文件`res_detail_71054429.XML`及页面选择`Resv. - GEN`；该文件与前份逐字节相同。
|
||
故在这一确认样本中，页面选择与XML内部元数据同时成立，不能把它们直接当成相互矛盾的同一个编码字段。
|
||
文件/页面确认已关闭，不再向用户求证；API仍按已有GEN/RESERVATION候选核对，不改成CAS。
|
||
[确认记录](../../.project-docs/50-evidence/topics/2026-09-16-confirmed-native-arr-notes.md)区分样本事实与未完成的同源API验收。
|
||
|
||
现有处理器取报表顺序中的**第一条非空预订备注**，整段规范化后作为 Group Code。API 数组顺序、类别过滤、空白文本处理和
|
||
多条备注的先后都可能改变结果。不能拼接所有备注、改取最后一条或用 Block Code 填补。
|
||
|
||
## 3. 现有处理器 16 个来源字段
|
||
|
||
下面路径相对于单笔详情对象 `data.reservations.reservation[]`；`[]` 表示需要明确选择或展开的集合，不表示直接取第一项。
|
||
“结构存在”仅指固定版本 schema 含该字段；不表示每笔都返回，也不表示与报表同义。
|
||
|
||
| ARR 来源字段 | 已核对的详情字段或候选 | 必须解决的语义 |
|
||
|---|---|---|
|
||
| `BLOCK_CODE` | 到店日`roomStay.roomRates[].reservationBlock.blockIdList[]`中`type=BlockCode`的`id`；与搜索层同结构比较 | 9/17原件复查发现26笔已有显式代码，与同一`type=Block`身份一起两层一致；已接严格选择器。113笔缺整个Block对象仍为缺口。`blockName`/Block ID不作代码，`reservationBlock.blockCode`仍不存在；报表同源对应待验收 |
|
||
| `ADULTS` | `roomStay.guestCounts.adults`及到店日`roomRates[].guestCounts.adults` | 当前139笔两层均有效且相同；共享房/多房的计数层级仍待验收，缺其中一层不自动补位 |
|
||
| `CHILDREN`（XML `CF_CHILDREN`） | `roomStay.guestCounts.children`及到店日`roomRates[].guestCounts.children` | 当前139笔两层相同；是否与报表儿童合计口径一致仍需同源证据 |
|
||
| `COMPANY_NAME` | `reservationProfiles.reservationProfile[].profile.company.companyName`，附 `reservationProfileType`；到店日stayProfiles另比 | 原XML为带T-/C-前缀的显示值。角色选择/多角色组合/前缀生成是不同问题；对照器只测独立假设，不硬编码Company优先或删除API名称中的原有前缀 |
|
||
| `CONFIRMATION_NO` | `reservationIdList[].id` 及 `type` | 分清内部 Reservation ID、Confirmation 及外部引用；详情请求用内部身份，展示列取正确确认号 |
|
||
| `DISP_ROOM_NO` | `roomStay.currentRoomInfo.roomId`；`roomStay.roomRates[].roomId` | 当前/历史、换房、未分房及报表显示格式 |
|
||
| `EFFECTIVE_RATE_AMOUNT` | 已发布 `searchRateInfo` 的 `data.detail.totalRateAmount`；指定系统传入日为detailDate | getReservation未返回effectiveRate。9笔搜索价匹配次日费率，7笔total-base等于当日包价；不能任取搜索/base/total替代。已集成v2采集；同源报告对应仍待验收 |
|
||
| `FULL_NAME` | `reservationGuests[].primary`；`.profileInfo.profile.customer.personName[]` | 主客、姓名类型、顺序、标点和本地化显示；surname 存在不等于 FULL_NAME 已恢复 |
|
||
| `RES_COMMENT` | `comments[].comment.text.value`，附 type/location/internal | 选定类型内第一条非空备注及稳定顺序，见上一节 |
|
||
| `TRACE_TEXT` | 当前用户明确不需要 | 本次API适配输出空Trace列表；不再等待部门/日期/解决状态/顺序映射。已有档案和原生XML继续保留真实Trace，不篡改历史或改人工解析器 |
|
||
| `NO_OF_ROOMS` | `roomStay.roomRates[].numberOfUnits` | 分段重复不能相加；共享、多房、拆单与源行粒度 |
|
||
| `PRODUCTS` | `reservationPackages[].packageCode`，保留source、packageGroup及scheduleList上下文 | 已有22笔/30项，8笔双包价，30项均覆盖到店日且实际reservationDate=consumptionDate；仍不足以确定报表多值范围/顺序/拼接，不套用其他OXI转换表的逗号规则 |
|
||
| `RATE_CODE` | `roomStay.roomRates[].ratePlanCode` | 到店日对应费率段，保留原值用于审计，既有白名单在采集之后执行 |
|
||
| `ROOM_CATEGORY_LABEL` | 搜索`roomStay.roomType`、详情`currentRoomInfo.roomType`和到店日`roomRates[].roomType` | Oracle官方将ROOM_CATEGORY_LABEL对应为Room Type；139笔三层代码一致，已接严格取值，不读roomTypeCharged/描述，也不新增字典查询。房型变更导致三层冲突的历史选段另待证 |
|
||
| `ARRIVAL`（XML `TRUNC_BEGIN`） | `roomStay.arrivalDate` | 单一到店自然日，历史变更及 ETA 不应悄悄改日期 |
|
||
| `DEPARTURE`（XML `TRUNC_END`） | `roomStay.departureDate` | 离店日期和修改时点，不用实际退房时刻替换 |
|
||
|
||
`totalType.amountBeforeTax` 的官方说明仍包含 Tax Inclusive 税，只排除 exclusive 税；`amountBeforeAnyTax` 才排除全部税。
|
||
因此不能仅凭字段名把 beforeTax 简称“未税价”，更不能默认它等于报告有效价。
|
||
|
||
其余三列继续由现有规则产生：`NIGHTS=DEPARTURE-ARRIVAL`，`REAL PRICE` 依固定价格规则/人工复核，
|
||
`TOTAL PRICE=REAL PRICE×NO_OF_ROOMS×NIGHTS`。OHIP 返回价格不能替代财务固定计价。
|
||
|
||
可选源列为 BLOCK_CODE、PRODUCTS、ROOM_CATEGORY_LABEL、RES_COMMENT、TRACE_TEXT。其余列对白名单内候选行有校验要求；
|
||
“可空”不是已证明 API 无需提供的意思。真实空值与请求没取到字段必须分开记录。尤其备注虽可空，仍影响下游公司报表关联。
|
||
|
||
姓名还有可直接比对的搜索摘要路径 `data.reservations.reservationInfo[].reservationGuest.fullName`，官方定义为完整显示名，
|
||
应与详情主客姓名并存核对，避免先自行拼接。人数和公司关联也有费率日期段对应字段；不同层级发生差异时不能静默选首项。
|
||
|
||
## 4. 分页、排序和完整一天
|
||
|
||
分页元数据在 `data.reservations`：`offset/limit/count/totalResults/totalPages/hasMore`。
|
||
Oracle 描述说 hasMore 缺省表示已全部返回；这只能作为该契约的结束信号，仍须同时检查实际行数、总数、警告和过滤范围。
|
||
schema 中单个 reservationInfo 数组上限 4000 不是已证明服务可接受的 `limit` 最大值。
|
||
本轮limit100可用；返回offset按请求limit前进，末页39条仍从100返回200。生产分页不能把返回offset误认作当前页起点。
|
||
|
||
建议采集控制如下，待测试后固化为程序契约：
|
||
|
||
1. 校验上游传入的起止日期有效且相等，固定环境、酒店、该到店日、参数、规则版本和开始时间，保存每页原始响应及分页元数据。重试沿用已固定日期，不重新计算T-1。
|
||
2. 明确请求 offset；结合服务返回 offset/limit/count 验证下一页位置，不依据页号推断。hasMore 为 true 却无行/不前进即停止并标记不完整。
|
||
3. 核对计数、身份、跨页重复、缺页和搜索警告；详情全部成功且必需块已取得后才可进入完整批次候选。
|
||
4. 显式 `orderBy` 仅能提供契约支持的排序。即使使用 ConfirmationNo，也未证明唯一或符合报表顺序；分页与逐笔请求期间的修改可能导致漂移。
|
||
5. 当前契约未发现快照 token 或服务端一致快照保证；二次查集合能发现部分变动，不能证明原子快照。需要限定采集时段并定义变化时重采/不提交策略。
|
||
6. 既有去重按房号+到店日保留源第一条。没有重复的单个样本无法证明顺序等价；需要专门覆盖重复、共享、多房和多备注/Trace案例。
|
||
|
||
任何页/详情失败不得把已拿到的部分数据提交为整日版本。空搜索结果、零白名单结果也不能直接用来清空 Finance；现有处理链对此不接受。
|
||
瞬时读失败用有界退避并遵守 Retry-After；恢复采集与主动重跑日版本是不同动作。
|
||
|
||
## 5. 接入现有处理链需要补的能力
|
||
|
||
`ProgrammaticUploadCoordinator.submit(filename, bytes)` 当前先验证 XML，再保存不可变 `source_xml`、运行固定处理器、独立验证、提交 Finance/outbox。
|
||
它没有接受 JSON 的入口；直接将 API JSON 当 XML 上传不会形成完整对接。
|
||
|
||
后续实现需保存一份可重放的采集清单，至少包括：环境/酒店/日历日/时区，参数与代码契约版本，页号/offset及响应摘要，
|
||
内部预订身份与详情对应关系，来源顺序，采集起止时点，API request ID，缺失/警告/重试记录，原始响应 SHA-256，完整性判断及适配器版本。
|
||
含客人和备注的原始响应应沿用私有源材料管理；日志和研究结论只保留必要诊断，不输出正文。
|
||
|
||
有两种待讨论的接法：
|
||
|
||
- 兼容 XML 适配：保存 API 原件和映射清单，再确定性生成派生 XML，明确标记其来源；不能冒充 Opera 原生导出。现有 XML 重放可保留，但还需独立验证 API→派生字段映射。
|
||
- 正式 JSON 来源适配：给处理/独立校验增加版本化来源契约。改动较大，需要同步来源角色、字段证据和重放设计。
|
||
|
||
仅重放派生 XML 能证明后段处理一致，不能单独证明适配器没有漏行或选错字段。无论选哪条，固定计价、审核、完整日替换和独立校验继续沿用。
|
||
新 `submit` 会产生新 job；自动采集必须设计批次身份和恢复规则，不能把网络重试变成反复创建日版本。
|
||
|
||
## 6. 下一轮验证与扩展接口的触发条件
|
||
|
||
最新22:21复验已恢复：原3人POST摘要均200，身份与姓名组成一致且fullName非空；nameType未返回、GET未重试。
|
||
见[成功回执](profile-summary-recovery-second-20260916.json)。关闭503阻碍，保留批量采集与同源显示验收。
|
||
getRoomCalendar本轮目录复查仍404，历史房号缺口未关闭。下面21:55记录为此前失败历史。
|
||
|
||
2026-09-16北京时间21:55，收到可能修复的反馈后，原3位姓名样本中的第一位复验仍为503/ohip_unavailable，
|
||
响应与平台审计一致。单次客户端请求、40秒上限，未继续另2人或GET；[最新回执](profile-summary-recovery-20260916.json)。
|
||
|
||
后续已收敛[最小平台支持需求](arr-platform-next-actions.md)：修复现有姓名摘要503；对2笔已退房、零晚且非pseudo
|
||
但没有返回房号的记录核验历史房号来源，建议提供getRoomCalendar只读封装或等价按预订来源。
|
||
原XML10笔CKOT全部有显示房号和相同LAST_ROOM，但来自另一酒店，不能用于逐笔证明算法。
|
||
GuestLastStay/profile.lastRoom缺当前预订绑定，不能作为自动回退。公司列暂不加接口，等待同源角色/显示证据。
|
||
[收敛依据](../../.project-docs/50-evidence/topics/2026-09-16-arr-minimum-platform-followup.md)。
|
||
|
||
最新已实现房号三处一致及指定关联角色的内部ID/原名两层一致检查；10新/133测试通过。
|
||
实际73笔房号可取，1笔仅当前/搜索房号、65笔三处未返回；24笔Group虽含不同外部ID，内部ID/名称一致。
|
||
没有公司角色优先级/显示格式/历史房号政策，也没有把字段拒绝变成整批业务门槛。
|
||
Oracle getRoomCalendar有换房历史/分段读取参数，但平台精确目录查询404；先评估是否确实必要，不直接要求补接口。
|
||
[具体证据与候选](../../.project-docs/50-evidence/topics/2026-09-16-arr-room-profile-selection.md)。
|
||
|
||
已有可复用实现：[source_fields.py](source_fields.py)提供确认号、到离店日、严格单日段费率代码及绑定的原始日价
|
||
选择，并按用户范围返回空Trace；不创建完整报表或选定其余显示规则。[本轮证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-direct-field-selection.md)。
|
||
|
||
后续已新增明确GEN/RESERVATION原文列表、预订/到店日两层一致人数、到店日原始numberOfUnits选择。
|
||
保留全部备注及API顺序，含内部备注；房数不累加、不默认。123项相关测试及139笔离线独立比较通过。
|
||
1笔多GEN备注对首条/Group Code敏感，API顺序仍未当作报告顺序；原始房数不等于已验明共享房报表口径。
|
||
[备注与人数证据](../../.project-docs/50-evidence/topics/2026-09-16-arr-note-count-selection.md)。
|
||
|
||
本轮已在已知测试环境 OHIPSB02 完成两个接口的一日全量候选采集，139详情均验证身份，原始JSON已私有保存，未提交 Finance。
|
||
收尾两页重查未发现ID、顺序或搜索记录变化；该观测不提供原子快照保证。当前手工样本属于 hotel57106，
|
||
不能与测试环境逐笔比较；最终等价验收需要同环境、同酒店、同日期、尽可能同数据时点的报告与 API 样本。
|
||
|
||
优先验收：日期/状态/分房/ETA 完整集合 → 多页与重试 → 全详情返回 → 备注类型/内部/顺序 → 公司角色/有效价/币种 →
|
||
多房共享、换房、重复顺序 → 16 来源字段及派生计价结果。不能只比较最终总金额。
|
||
|
||
| 可能增补接口 | 仅在什么情况下需要 |
|
||
|---|---|
|
||
| `searchRateInfo`（GET getRateInfo为兼容入口） | 已发布并接入v2，当前catalog0.7.0再次确认；已有reservations.read足够，不再请求平台补齐 |
|
||
| `getBlock` / `blocks.read` | 仅当现有响应缺少typed BlockCode、但有可绑定Block ID且确需补查时考虑。现有26笔已含代码，不需额外查询；113笔缺对象不能通过猜ID补查。详情返回路径为`data.blocks.blockInfo[].block.blockDetails.blockCode`，仍须绑定身份；不用于Group Code |
|
||
| `getProfile` / `profiles.read` | 详情里的正确公司角色只返回 ID、没有满足要求的公司名时 |
|
||
| `searchProfiles` / `getProfiles` / `profiles.read` | 已获授权，v3按唯一主客Profile ID取summaryInfo=true并核对身份/姓名组成，保留`profileSummaries.profileInfo[].profile.formerName.fullName`原文。原3人恢复样本通过；最新全日实测触及6档案，5个姓名成功、第6个3次503后停批。GET未复验，nameType未返回不伪造；同源报表显示仍待验收 |
|
||
| `getRoomTypes` / `hotel.read` | 当前139笔已有三层一致房型代码，结合官方ROOM_CATEGORY_LABEL定义已接入取值，不需查询描述或扩大hotel.read权限；不得用字典掩盖历史房型冲突 |
|
||
|
||
日价封装缺口已关闭。profiles.read已按用户批准追加，仅做3位主客摘要试查；getBlock/hotel.read仍未加入权限。
|
||
[摘要查询当前503定位材料](profile-summary-platform-check.md)。不能据已获档案读取权限推定公司显示规则。
|
||
应按能力组评估实际扩展范围，避免为了可选字段一次开通无关业务操作。
|
||
当前不需要财务账单 API 或异步住宿日汇总来替换已有计价/到店口径。
|
||
|
||
## 7. 证据与可检查材料
|
||
|
||
- [无凭证的研究请求示例](arr-api-request-examples.json)：初始模板，后续实测见聚合结果；特别是带时区ETA模板未取得预期数据，不能用作生产筛选。
|
||
- [用户业务要求](../../.project-docs/40-domain/arr-source-report-contract.md)、[现有来源字段契约](../../arr-opera-daily-ingest/references/field-contracts.md)。
|
||
- 平台两项操作在 2026-09-16T07:07:21Z 回读，catalog 0.6.0；请求 ID 分别为 `a9df12e3-83cc-42c4-a797-688467f7c708`、`e70955dc-8d7f-4064-a307-c18103e5da6f`。
|
||
- 固定提交的 [Oracle rsv.json](https://github.com/oracle/hospitality-api-docs/blob/dd631fbd5d0fce74a7dbdf96b43f07ce587211f2/rest-api-specs/property/v1/rsv.json)，版本 26.3.0.0；schema 和官方例子不是本酒店实测数据。
|
||
- Block 补充路径取自同一固定提交的 [blk.json](https://github.com/oracle/hospitality-api-docs/blob/dd631fbd5d0fce74a7dbdf96b43f07ce587211f2/rest-api-specs/property/v1/blk.json)。
|
||
- [本轮校验记录](../../.project-docs/50-evidence/topics/2026-09-16-arr-api-field-mapping.md)记录结构校验和证据边界。
|