92 lines
7.7 KiB
Markdown
92 lines
7.7 KiB
Markdown
# ARR 原生 XML 下载：平台接口核对清单
|
||
|
||
**适用范围更新：本文仅保留原生文件能力的历史核对。** 用户要求依据业务要素研究平台接口；
|
||
整份XML接口缺失不阻止预订搜索/详情组合研究，计划报表/SFTP分支已停止推进。
|
||
当前工作依据[业务要素与API映射](../../.project-docs/50-evidence/topics/2026-09-16-arr-api-scope-correction.md)。
|
||
|
||
2026-09-16。供 ARR 项目与 OHIP Edge 平台讨论；尚未发送给其他人，尚未实施或扩大应用权限。
|
||
|
||
## 目标
|
||
|
||
财务部需要取得与 Opera 手工导出相同的 `Arrivals: Detailed（res_detail）` 原生 XML，再进入 ARR 已有处理链。
|
||
Report Name 的查找值是 `ARR`。起止日期均为日历上的昨天，时间 00:00–23:59；预订与房间分配均选 ALL，
|
||
Room Type、Membership Type、Preferences、Rate Code、Inventory Items、Source Code、Market Code 均为 ALL CODES。
|
||
显示 Room Number 和 Notes，只选 `Resv. - GEN` 并包含该类型的内部备注。完整业务要求以
|
||
[源报表契约](../../.project-docs/40-domain/arr-source-report-contract.md)为准。
|
||
|
||
当前是同一酒店的标准测试阶段，测试酒店为 `OHIPSB02`；经 Oracle 审批后再切换酒店正式环境。
|
||
ARR 独立应用为 `Wyndham-ARR2.0-Codex`，目前仅有预订搜索和详情读取权限。本文不包含凭据。
|
||
|
||
## 已查明的接口覆盖
|
||
|
||
| 环节 | Oracle 已发布操作及完整路径 | 当前 Edge 0.6.0 | 说明 |
|
||
|---|---|---|---|
|
||
| 查找报告实例 | `getReports` — `GET /rep/config/v1/reports` | 未提供 | `name` 可作部分名称/描述查询，`hotel` 限定酒店；取得真实报告身份 |
|
||
| 另一报告检索操作 | `getAllReports` — `GET /rep/config/v1/allReports` | 未提供 | 也是报告元数据；根据实际覆盖选择，无需默认同时接入两个 |
|
||
| 读取参数定义和默认值 | `getReportParameters` — `GET /rep/config/v1/reportParameters` | 未提供 | 用已查得的报告身份读取参数，不能生成或下载报告 |
|
||
| 按本次参数生成 XML | 尚未找到可确认覆盖 `res_detail` 的公开操作 | 未提供 | 需先确认 Oracle 支持的执行入口、权限及契约 |
|
||
| 取得生成后的 XML | 尚未找到与上述执行结果相连的公开操作 | 未提供 | 需确认文件内容、文件标识、下载地址或其他正式交付方式 |
|
||
|
||
以上路径属于 Oracle 上游，不能直接当作 Edge 已有路径调用。仅补上报告检索和参数查询，仍不足以完成下载。
|
||
已检查 Oracle 当前公开 Property v1 规范的 45 个文件、3,580 个操作；没有发现原生执行/下载入口不代表
|
||
Oracle 在所有环境都不支持，也不能断言只是 Edge 漏封装。
|
||
|
||
## 平台需要确认的四项内容
|
||
|
||
1. **原生执行与取文件能力。** 本环境是否存在获支持的 `res_detail` 执行入口？请提供正式 Operation ID、
|
||
路径、方法、所属服务、鉴权要求、成功/失败样例，以及测试与正式环境可用性。如果异步生成，需同时明确
|
||
启动、状态、结果关联方式；如果同步返回文件，无需人为拆分。
|
||
2. **报告身份与参数。** 通过检索确认 `ARR` 命中的实际报告、酒店、身份、类型、参数定义和默认值。
|
||
优先补充 `getReports`（或经证实更合适的 `getAllReports`）与 `getReportParameters` 的读取能力。
|
||
如果通用参数列表没有覆盖这个报告的专用表单，请提供获支持的专用参数契约。
|
||
3. **文件交付与失败恢复。** 明确文件类型/编码、生成完成标志、大小或完整性证据、下载有效期、失败状态，
|
||
以及启动超时后如何核对既有任务，避免重复生成或将部分文件当成完整日数据。
|
||
4. **可比对测试证据。** 同一测试酒店、同一到店日、同一组选项的手工 XML 与接口 XML；同时保留参数、
|
||
报告/任务标识和生成时间。如果测试酒店缺少该报告或匹配数据，应明确缺少的配置/数据，不能把空返回视为
|
||
正式酒店口径已验收。
|
||
|
||
如果 Oracle 不提供支持的原生执行接口，请明确此限制，以及是否支持将同一原报表 XML 交付到可由平台获取的
|
||
位置。该方式也需正式契约和样例；预订 JSON 重建是另一条需要证明业务等价性的候选路线，尚未选择。
|
||
|
||
后续研究确认：Oracle官方演示支持为Arrivals: Detailed建立计划报表，标准计划报表文档支持XML和SFTP。
|
||
用户已确认酒店页面能看到计划报表入口。可以进一步核实原XML投递至受控SFTP，再由平台提供原文件读取接口的
|
||
候选路线；尚未选择此方案、建立接收位置或创建计划。具体前置条件与单次验证见
|
||
[原生XML交付验证草案](native-xml-delivery-trial.md)。
|
||
|
||
## 参数映射注意事项
|
||
|
||
- `ARR` 是搜索值，不是已证实的报告 ID。检索结果可含 `moduleId.id/type`、`reportName`、`moduleType`、
|
||
`hotel`、`formToRun`、`hasParameters`；`moduleType` 与身份字段 `moduleId.type` 不同。
|
||
- 参数查询允许 `id/idContext/type`，使用实际报告身份，不根据 UI 名称拼造 ID 或 `idContext`。
|
||
参数响应可含 `name/label/dataType/value/dateOffset/lovParam`，LOV 可能给出 `code/description`。
|
||
目前尚未取得此报告的实际参数，不能编造 `P_*` 名称、ALL 编码或把 `Resv. - GEN` 自动等同于 `GEN`。
|
||
- `dateOffset` 在 Oracle schema 中相对当前营业日。用户补充明确由上游系统传入按T-1规则确定的From/To日期，
|
||
ARR按已核实的参数格式使用传入值，不自行重算，也不能直接用 `dateOffset=-1` 代替。见源报表契约。
|
||
- 保留原报表 ALL Reservations 的含义、未分房记录和全部费率代码；现有白名单在文件取得后执行。
|
||
不为让解析通过而先删掉源报表中未分房或其他不易处理的行。
|
||
- 内部备注是在 `Resv. - GEN` 范围内一并包含；不扩大到所有备注类型，也不只保留内部备注。
|
||
用户未指定 Trace 或排序，不自行补选；应保存原报表的记录和备注顺序。
|
||
|
||
## ARR 验收边界
|
||
|
||
用户已表示可以手工导出；第一轮具体材料见 [样本导出要求](manual-export-sample-request.md)。
|
||
正式酒店手工文件可先用作结构/处理基准，不能与 OHIPSB02 标准测试数据直接作逐笔一致性结论。
|
||
|
||
已收到一份日期2026-09-15、文件内酒店代码57106的样本；72源行经现有处理器和独立校验后保留61行，
|
||
无价格待审。58条备注代码CAS、描述GENERAL，源数据含10条CKOT、多条Trace，且ROWNUM不等于文档顺序。
|
||
实际页面参数及正式/测试环境仍待确认。详见 [手工样本证据](../../.project-docs/50-evidence/topics/2026-09-16-manual-arr-xml-baseline.md)。
|
||
平台接入不能据此将 GEN 硬编码成备注类型、按 ROWNUM 重排或只取在住记录。
|
||
|
||
确认文件为完整有效的 `RES_DETAIL` XML，酒店、到店日、参数符合目标，再保存原件并交给现有处理入口。
|
||
比对原始行集合/顺序、备注、房号、公司、费率与生效价格，以及经过当前处理器后的去重结果、间夜和金额。
|
||
人工价格复核、独立验证、Finance 完整日替换和月报触发继续遵循现有规则。
|
||
|
||
没有候选行、文件不完整或任务状态不明时，不能自动清空当天 Finance。采集调度、重跑和空日策略仍需明确；
|
||
本清单不代表创建定时任务或修改酒店报告配置。
|
||
|
||
## 依据
|
||
|
||
- [Oracle REPCFG 固定版本规范](https://github.com/oracle/hospitality-api-docs/blob/dd631fbd5d0fce74a7dbdf96b43f07ce587211f2/rest-api-specs/property/v1/repcfg.json)
|
||
- [完整取证记录](../../.project-docs/50-evidence/topics/2026-09-16-native-arr-report-api-review.md)
|
||
- [Edge 实时目录](https://ohip.nianxx.cn/developer/v1/catalog)
|