26 KiB
ARR 业务要素与平台 API 对应表
2026-09-17后续：已把严格取值器串成逐笔候选准备，16列分别记录取值或缺口；139笔全保留， 73笔房号/134笔日价/115笔费率代码可取，显示与报表口径仍未验收。按钮后台已有显式v3与姓名上限支持， 237项范围测试通过，未启用正式接线。完成记录。
2026-09-17补充：姓名不是完整主体采集的强制依赖。新增独立补充路径复用完整v2， 查询失败只形成姓名缺口，恢复只补缺失；旧v3交错查询及历史失败记录不改。仍是候选字段，未验收完整ARR。
2026-09-17更新：v3姓名候选已接入字段证据、独立Profile身份关联和同源XML原文/去空格观察； 19新用例/198范围测试通过。旧139笔证据不变，真实失败批次仍拒绝完整导出；未关闭业务验收项。 用户已将503诊断转给平台，本轮未新增接口调用，后续全部独立完成、不创建子智能体。 本轮证据。
2026-09-16，接口讨论稿。主干候选为 searchHotelReservations → getReservation + searchRateInfo + searchProfiles → 完整批次校验 → 确定性适配 → 既有 ARR 处理链。
前三项操作在reservations.read，姓名摘要在已批准的profiles.read内。最初只读联调已取得 OHIPSB02 / 2026-09-15 的139个候选预订及全部详情，
身份与分页检查通过。XML输出层已实现，最终API来源映射未完成，也未提交 Finance。优先以实测证据
和聚合结果解释下列规范候选；官方示例不能替代实际返回。
2026-09-16后续：已完成采集及本地档案核验与同源验收清单。 用户随后已通知日价接口补齐。当前样本的完整显示名未返回、费率段全为单日、重复候选可能影响结果；详见聚合核验。
最新推进：catalog0.7.0提供推荐POST searchRateInfo / detail.totalRateAmount，其定义就是指定预订及日期的有效价； GET getRateInfo为已弃用的兼容入口。5笔/11次只读验证通过，详见发布证据。 日价已接入v2整批采集/归档/回放/本地批次管理；XML有效价同源对应仍待验收。 平台补充清单保留此前需求历史。
最新显示字段核对：聚合结果及证据。
原57106 XML公司列为65条T- 、6条C- 、1条空；不能直接把API纯名称认作同一展示字段。
对照器新增角色前缀和到店日人数的独立假设，共42项观察，40项工具测试/87项相关回归通过。
用户给出的 Opera 操作用于定义业务条件。当前工作不再推进页面点击、计划报表或 SFTP；没有原生 XML 下载操作不阻止研究 API 数据获取。
来源适配基础层已实现：逐笔字段证据及独立验证覆盖完整139笔候选， 保留16列的原始出处、类型、缺失/空值、多值及上下文。16新测试/140相关测试通过；851原件未变。 它不选择最终字段或输出XML，全部业务就绪标记仍false；证据。
最终输出格式也已具备：arr_xml.py将明确选定的有序行生成处理XML，独立解析器验证字段/列表。 原生样本72行投影的处理结果与原基准一致，但API的最终取值/行选择仍未实现。官方新增证据保留Source角色， 明确排序可配置；旧版共享/组合房数量说明使numberOfUnits直映需进一步验收。 实现与官方依据。
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后停止，未得到完整日候选。最新实测回执。 版本化姓名采集证据。 跨页重复在采集校验时拒绝，不能直接消掉再宣布完整。候选集合/次序不能被当成已经验证的报告行粒度/顺序。
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。
确认记录区分样本事实与未完成的同源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误认作当前页起点。
建议采集控制如下，待测试后固化为程序契约：
- 校验上游传入的起止日期有效且相等，固定环境、酒店、该到店日、参数、规则版本和开始时间，保存每页原始响应及分页元数据。重试沿用已固定日期，不重新计算T-1。
- 明确请求 offset；结合服务返回 offset/limit/count 验证下一页位置，不依据页号推断。hasMore 为 true 却无行/不前进即停止并标记不完整。
- 核对计数、身份、跨页重复、缺页和搜索警告；详情全部成功且必需块已取得后才可进入完整批次候选。
- 显式
orderBy仅能提供契约支持的排序。即使使用 ConfirmationNo，也未证明唯一或符合报表顺序；分页与逐笔请求期间的修改可能导致漂移。 - 当前契约未发现快照 token 或服务端一致快照保证；二次查集合能发现部分变动，不能证明原子快照。需要限定采集时段并定义变化时重采/不提交策略。
- 既有去重按房号+到店日保留源第一条。没有重复的单个样本无法证明顺序等价；需要专门覆盖重复、共享、多房和多备注/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未重试。 见成功回执。关闭503阻碍，保留批量采集与同源显示验收。 getRoomCalendar本轮目录复查仍404，历史房号缺口未关闭。下面21:55记录为此前失败历史。
2026-09-16北京时间21:55，收到可能修复的反馈后，原3位姓名样本中的第一位复验仍为503/ohip_unavailable， 响应与平台审计一致。单次客户端请求、40秒上限，未继续另2人或GET；最新回执。
后续已收敛最小平台支持需求：修复现有姓名摘要503；对2笔已退房、零晚且非pseudo 但没有返回房号的记录核验历史房号来源，建议提供getRoomCalendar只读封装或等价按预订来源。 原XML10笔CKOT全部有显示房号和相同LAST_ROOM，但来自另一酒店，不能用于逐笔证明算法。 GuestLastStay/profile.lastRoom缺当前预订绑定，不能作为自动回退。公司列暂不加接口，等待同源角色/显示证据。 收敛依据。
最新已实现房号三处一致及指定关联角色的内部ID/原名两层一致检查；10新/133测试通过。 实际73笔房号可取，1笔仅当前/搜索房号、65笔三处未返回；24笔Group虽含不同外部ID，内部ID/名称一致。 没有公司角色优先级/显示格式/历史房号政策，也没有把字段拒绝变成整批业务门槛。 Oracle getRoomCalendar有换房历史/分段读取参数，但平台精确目录查询404；先评估是否确实必要，不直接要求补接口。 具体证据与候选。
已有可复用实现：source_fields.py提供确认号、到离店日、严格单日段费率代码及绑定的原始日价 选择，并按用户范围返回空Trace；不创建完整报表或选定其余显示规则。本轮证据。
后续已新增明确GEN/RESERVATION原文列表、预订/到店日两层一致人数、到店日原始numberOfUnits选择。 保留全部备注及API顺序，含内部备注；房数不累加、不默认。123项相关测试及139笔离线独立比较通过。 1笔多GEN备注对首条/Group Code敏感，API顺序仍未当作报告顺序；原始房数不等于已验明共享房报表口径。 备注与人数证据。
本轮已在已知测试环境 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定位材料。不能据已获档案读取权限推定公司显示规则。 应按能力组评估实际扩展范围，避免为了可选字段一次开通无关业务操作。 当前不需要财务账单 API 或异步住宿日汇总来替换已有计价/到店口径。
7. 证据与可检查材料
- 无凭证的研究请求示例：初始模板，后续实测见聚合结果；特别是带时区ETA模板未取得预期数据，不能用作生产筛选。
- 用户业务要求、现有来源字段契约。
- 平台两项操作在 2026-09-16T07:07:21Z 回读，catalog 0.6.0；请求 ID 分别为
a9df12e3-83cc-42c4-a797-688467f7c708、e70955dc-8d7f-4064-a307-c18103e5da6f。 - 固定提交的 Oracle rsv.json，版本 26.3.0.0；schema 和官方例子不是本酒店实测数据。
- Block 补充路径取自同一固定提交的 blk.json。
- 本轮校验记录记录结构校验和证据边界。