# 发给平台同事：ARR 财务报表接口核验与原需求更正

## 2026-09-18 更正：四个候选操作尚不能作为封装需求

**最新业务要求：输出不限 XML。** 优先解决系统稳定取得 Oracle 按既定日期及选项生成的 ARR 原报表。其他格式只要保留后续处理所需内容，也可评估采用；具体可选格式以该报表实际支持为准。收到真实文件后再评估解析适配，当前不开发转换或替代生成方案。原始参数表中的 XML 要求已按此放宽，其余业务参数不变。

**撤回原文中“请补 4 个候选操作、可以先封装并实测”的开发建议。** `getAPIVersion`、`getServerInfo`、`runJob`、`getJobInfo` 确实存在于 Oracle 官方文档，但属于 Oracle Reports Web Service。当前尚无证据证明 OPERA Cloud 的本酒店 ARR 可以通过该服务运行。不能用封装完成或本地模拟通过弥补这项缺失。

此前需求把“官方有这种能力”提前推进成了“本项目应当封装它”，这一接口选型由 ARR 项目侧负责纠正，不要求平台同事重复查公开资料，也不要求用户先提供 WSDL 才继续研究。

### 重新核对官方资料后的结果

| 我们要完成的事 | Oracle 已核实的接口或说明 | 当前结论 |
| --- | --- | --- |
| 找到报表及其配置 | `getReports`：GET `/rep/config/v1/reports`；`getAllReports`：GET `/rep/config/v1/allReports` | OPERA 官方接口；平台已有相关读取能力，测试环境已找到 `res_detail` |
| 读取接口公开的参数定义 | `getReportParameters`：GET `/rep/config/v1/reportParameters` | OPERA 官方接口；目标报表仍返回空参数，不能由此推定日期和选项可以省略 |
| 新建或修改保存的报表配置 | `postGenericReports`、`changeGenericReports`：POST / PUT `/rep/config/v1/genericReports` | 保存配置，不是启动生成；不列为当前新增封装需求 |
| 系统提交日期、选项并启动 ARR | 本次核对的 OPERA 报表配置模块没有此操作；通用 Oracle Reports 的 `runJob` 只作为研究线索保留 | **仍未找到已证实适用于 OPERA Cloud ARR 的公开入口，暂不能给平台一份确定的生成接口清单** |
| 查询生成状态、取得文件 | 通用 Oracle Reports 提供 `getJobInfo`，但同样缺少本环境适用证据；其官方说明明确 Web Service 不返回报表原件 | 本批优先查清生成入口，取回文件随后核对 |

本次直接核对的官方 REPCFG 定义标记为 `26.3.0.0`，共 12 个操作；包含报表配置、参数、文本、统计配置及服务状态，没有报表运行操作。这是该公开模块的核验结论，不能扩展为“Oracle 所有产品和环境都没有生成接口”。

依据：[Oracle 官方 REPCFG 接口定义](https://github.com/oracle/hospitality-api-docs/blob/main/rest-api-specs/property/v1/repcfg.json)、[Oracle Reports Web Service 操作说明](https://docs.oracle.com/middleware/12213/formsandreports/use-reports/pbr_webservice003.htm)、[OPERA Cloud 生成报表使用说明](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.1/ocsuh/t_generating_run_reports.htm)。最后一份说明证明页面可以生成、下载报表，不是外部系统调用接口的说明。

业务目标、已确认参数、同酒店两部门的分工不变。目前没有新增一项“已证实适用、可以直接封装”的 ARR 生成接口。后续只有找到适用入口及明确请求、返回说明，或取得可验证的现有服务证据，才重新发布具体封装清单；不以咨询 Oracle 作为默认前置条件，不采用页面点击或业务数据拼装来替代。

### 后续只读核验：计划报表确实覆盖 ARR，但调用入口仍缺

- Oracle 26.1 的[官方演示文字稿](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.1/ocsuh/cc-manage-scheduled-reports.htm)直接以 **Arrivals: Detailed** 为例，演示设置报表参数、日期、周期和投递目标。因此“原生 ARR 可以自动生成”有明确的产品依据，不只是通用报表产品的推测。
- [26.1 计划报表说明](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.1/ocsuh/t_reports_manage_scheduled_reports.htm)列出固定日期或动态日期、单次或重复执行，以及 Email、Printer、SFTP 目标；可选格式包括 PDF、HTML、RTF、XML、Delimited、Delimited Data，Excel 限部分 BI Publisher 报表。该说明没有给出外部系统提交或强制运行这些计划的 API。不能将界面中的 Run Reports 当成已发布接口。
- 经现有平台 `getOperaSettings` 只读调用：GET `/api/v1/config/opera-settings?parameterNameWildCard=REPORT`，平台和上游均返回 200；酒店 `OHIPSB02` 的 `REPORT_SCHEDULER` 值为 `Y`。请求编号：`30d7a9ad-7317-464d-a9de-f95dcdb45eff`。这只证明测试酒店已开启功能，不证明任务已经生成、投递成功或生成接口对外开放。
- 同次返回的 `REPORT_APPLICATION_SERVER_NAME` 没有 `value` 字段，未提供可验证的报表服务地址；不能据此断言服务不存在。
- 当前平台目录 `0.11.0` 按 schedule 检索返回 `getScheduledReportsExportLOV`，它的契约明确为只读选项查询，不能执行、创建计划或下载文件。目录请求编号：`7f54058e-c0fe-490f-8aa2-be1d8485e53a`；单项契约请求编号：`3b590026-030e-44ce-86ec-13bc80ea24bd`。
- 补查官方 OPERA Cloud 报表、调度及通用 Oracle Reports 服务资料后，仍未取得证明当前 OPERA Cloud ARR 可通过 `RWWebService/runJob` 外部调用的文档。其候选状态不变，不发布封装任务。

“Oracle 预设计划自动生成 → 邮件或 SFTP 接收 → 原件存 OSS → 按日期取件”可以作为有产品依据的备选，但尚未在当前环境完成生成/投递验证，也不等于当前目标中的“系统传参、立即启动”。采用前需要明确这项产品差异，本轮没有切换方案、创建计划或发送文件。

## 以下为 2026-09-17 原始方案，保留作历史记录

**以下原文中的“请封装”、建议平台路由及交付阶段均已被上面的更正取代，不能直接用于安排开发。**

日期：2026-09-17。业务方：同一家酒店的财务部；共用平台：[OHIP 封装平台](https://ohip.nianxx.cn)。

**这次请补 Oracle Reports 的 4 个候选操作：`getAPIVersion`、`getServerInfo`、`runJob`、`getJobInfo`，让 ARR 项目能通过平台在测试环境验证“提交日期和选项 → Oracle 生成 ARR”。本批先做到生成完成，文件取回、OSS 和处理链后续再接。**

这 4 个操作有 Oracle 官方说明，但尚未证实当前 OPERA Cloud 环境开放该服务、且允许运行 `res_detail`。可以先封装并实测，不把咨询 Oracle 作为开工条件；封装完成、本地模拟通过、真实 Oracle 生成成功分别记录。

## 1. 整个项目的背景和分工

我们正在为同一家酒店的两个部门接入 Oracle，两个业务项目使用同一个 OHIP 封装平台，各自保留应用、凭据和业务规则。

| 部分 | 业务目标 | 当前情况 |
| --- | --- | --- |
| 预订部 | 读取邮件及 Excel，形成确认后的 GROUP/FIT 任务，通过接口建单、改单、取消、转换类型，再查询结果 | 最近核验的平台目录为 **0.11.0／184 项**；此前所需的 5 个核心接口和 3 个建议只读接口均已发布。预订项目已完成本地适配及隔离测试，尚不等于真实酒店全流程验收 |
| 财务部 ARR | 系统提交日期和报表选项，由 Oracle 生成 ARR 原件，再接入现有财务处理链 | 人工上传原始 XML 后的处理、验证、入库和下游报表链已有；报表目录与参数读取接口已发布，原生生成入口待测试 |
| 接口平台 | 对接 Oracle，封装稳定的调用入口，提供目录、参数、权限、返回结果及错误信息 | 两个部门复用平台能力；某个接口未进入平台目录，不等于 Oracle 没有该接口 |

预订部此前的 5 个核心接口为 `postProfile`、`putBlockAllocation`、`getNextBlockStatus`、`putBlockStatus`、`postCancelReservation`；3 个建议只读接口为 `getBlockPMReservations`、`getOperaSettings`、`getProfileRelationships`。**这些已发布接口不用为本次财务需求重复封装。**

预订部已取消“把邮件 Excel 上传或替换到 Oracle 附件”的需求，邮件 Excel 的读取解析仍保留；这项变更不影响财务部将报表原件存入 OSS。

协作方式沿用预订部：

- **业务项目侧**负责理解业务、查 Oracle 公开资料、整理参数与接口对应关系、接入最终平台契约并核验结果。公开资料研究不推回给平台同事重复做。
- **平台同事**负责接口封装、上游连接配置、发布目录和 OpenAPI，交付可调用地址及实际响应。
- **用户**转交接口需求、协调发布，并按明确步骤操作上传、确认、重启等验收动作。业务参数已确定，不反复询问。
- 按“输入什么 → 调哪个接口 → 返回什么 → 实际结果如何”逐层确认，不用测试数量代替业务完成情况。

## 2. 财务部的目标和本批范围

最终流程：

**系统计算并提交具体日期和报表选项 → Oracle 生成 ARR → 接口取得 Oracle 原件 → 阿里云 OSS → 现有 ARR 程序处理、验证、入库 → 下游日报/月报。**

本批交付集中在：

1. 平台能够调用候选报表服务。
2. 平台能够提交一次报表生成请求并保留任务编号。
3. 平台能够查询该任务的生成结果。

本批不要求下载文件、接 OSS、调整财务处理器或改下载按钮。ARR 按钮继续只承担日期提交与状态展示。

财务项目后续可复用现有的原 XML 处理、独立验证、入库、OSS 存储、下游报表及任务状态框架。现有下载执行器曾走“采集业务数据 → 适配生成 XML”，不能直接作为原生下载器；Oracle 原件链路确认后，由财务项目侧替换这段执行逻辑，不要求平台同事修改 ARR 程序。

### 对此前错误方向的更正

如果之前收到过要求补齐姓名、历史房号、公司显示、套餐组合或排序映射的 ARR 说明，本次不再按这些项目推进报表重建。财务目标是让 **Oracle 运行报表**，不是查询多种业务数据后自行拼出 XML，也不采用模拟点击 OPERA 页面。

已有接口、历史代码和核验记录保留；它们不能作为“ARR 原生生成已经接通”的证明。

## 3. 测试环境与已确认的报表

| 项目 | 当前信息 |
| --- | --- |
| 财务消费应用 | `Wyndham-ARR2.0-Codex` |
| 本地阶段 | ARR 和预订项目均在测试、联调阶段，不要求先接生产酒店 |
| 已调用的 Oracle 测试酒店 | `OHIPSB02` |
| 原始 XML 样本酒店 | `57106`；与 `OHIPSB02` 不是同一数据集，不能逐笔对账 |
| 测试环境已找到的报表 | `Arrivals: Detailed`，内部名 `res_detail` |
| 测试环境报表配置编号 | `183106`，类型 `ModuleId`；这是配置编号，不能直接当作 `runJob` 的报表文件名或任务编号 |
| 报表类型与参数表单 | 返回 `Rep`、`res1`；尚未确认有名为 ARR 的独立配置实例 |
| 参数读取结果 | 对 `183106` 返回空数组；同环境另一报表可返回 11 个参数。ARR 配置及参数暴露方式待核对，空数组不作为接口不支持的结论 |

报表发现通过 `getGenericReportsLOV` 和 `getAllReports` 完成。平台已有 `getReports`、`getReportParameters` 等读取能力，无需把它们重新列为本批缺项。

本机 `8873` 是原 XML 重放，`8874` 是本机模拟及录像实例。两者不证明 Oracle 生成已接通，**本批不操作或修改 8874**。

## 4. 请封装的 4 个 Oracle 操作

这四项属于 **Oracle Reports Web Service，采用 SOAP**，不是 REPCFG 的四个 REST 路径。官方服务地址形式为：

```text
{实际 Oracle Reports WebLogic 服务地址}/reports/rwwebservice
```

请按实际服务 WSDL 确认地址、SOAP 绑定、命名空间及消息结构。不要直接将此路径拼到 OHIP 网关后，也不要把文档中的示例主机、服务器名或账户当成测试环境配置。

| # | Oracle 操作 | 业务用途 | Oracle 原生输入 | 必须保留的返回内容 |
| --- | --- | --- | --- | --- |
| 1 | `getAPIVersion()` | 检查是否连到报表服务 | 无 | Oracle 返回的版本及真实调用结果 |
| 2 | `getServerInfo(serverName, authId)` | 确认指定报表服务器可访问 | `serverName`；受保护服务器需要 `authId` | 服务器身份、版本、状态或原始错误 |
| 3 | `runJob(commandLine, synchronous)` | 指定报表及运行参数，启动一次生成 | `commandLine` 为完整运行参数；`synchronous` 控制同步/异步，联调建议采用 `false` | 本次任务编号、服务器、报表名称、状态及错误信息 |
| 4 | `getJobInfo(jobId, serverName, authId)` | 查询本次生成任务 | `jobId`、`serverName`；受保护服务器需要 `authId` | 原始任务状态、运行的报表、开始/结束信息及错误 |

`runJob` 的官方返回是任务信息，不能把返回的 SOAP/XML 消息当成 ARR 报表原件。`getJobInfo` 的状态查询也不等于文件下载。

官方依据：[服务入口与 WSDL](https://docs.oracle.com/middleware/12213/formsandreports/use-reports/pbr_webservice002.htm)、[四个操作的定义及返回示例](https://docs.oracle.com/middleware/12213/formsandreports/use-reports/pbr_webservice003.htm)。

### 平台侧建议的路由形状

以下仅是本次建议，**尚未发布，也不是 Oracle 原生路径**。平台可沿用自身命名规范，最终以交付的 OpenAPI 为准。

| 建议平台路由 | 对应 Oracle 操作 |
| --- | --- |
| GET `/api/v1/reports/runtime/version` | `getAPIVersion` |
| GET `/api/v1/reports/runtime/server` | `getServerInfo` |
| POST `/api/v1/reports/runtime/jobs` | `runJob` |
| GET `/api/v1/reports/runtime/jobs/{jobId}` | `getJobInfo` |

实际报表服务地址、服务器及凭据由平台配置管理。现有 OHIP 网关凭据是否可用于该 SOAP 服务尚未确认，需支持独立配置并用实际响应验证。凭据不进入调用结果和普通日志。

`runJob` 的参数承载方式已经明确；ARR 每个选项对应的真实参数名、可用编码及日期格式还未全部取得。请保留官方运行参数的表达能力，不先硬编码虚构的 ARR 字段；服务身份等平台配置与业务报表参数分开处理。

## 5. ARR 已确定的业务参数

这些是目标报表的运行要求，供后续映射与验收，不是要求拆成预订、客人、房号等查询接口。

| 项目 | 确定值 |
| --- | --- |
| Report Name | `ARR` |
| Report | `Arrivals: Detailed` / `res_detail` |
| Reservations | `ALL Reservations` |
| Room Assignment | `ALL Reservations` |
| From Date / To Date | 两者相同。日常由业务系统计算 T−1 后传入明确日期；生成执行器接收该日期，不自行计算昨天，也不永久固定为某次测试日期 |
| Room Type | `ALL CODES` |
| Membership Type | `ALL CODES` |
| Preferences | `ALL CODES` |
| Rate Code | `ALL CODES` |
| Inventory Items | `ALL CODES` |
| Source Code | `ALL CODES` |
| Market Code | `ALL CODES` |
| Arrival Time | `00:00–23:59` |
| Display | 勾选 `Room Number`、`Notes`、`Include Internal Notes` |
| Note Types | `Resv. - GEN` |
| Traces | 不需要 |
| 目标输出格式 | XML |
| 其他排序或选项 | 未指定的不自行增加 |

表中是 OPERA 的业务显示值；接口参数名、日期格式、ALL 的编码、复选框取值及 Note Type 编码以实际报表定义为准。不得把界面文字直接猜成可执行参数。

参考：[Oracle 对 RES_DETAIL、res1 和参数配置的说明](https://docs.oracle.com/en/industries/hospitality/opera-cloud/26.1/ocsuh/t_reports_configuring_reports.htm)。

## 6. 封装时需要保持的行为

1. **保留真实上游结果。** HTTP 成功不等于报表生成成功；返回任务编号、Oracle 原始任务状态、SOAP Fault/业务错误、平台请求编号，方便定位到同一次调用。
2. **提交与完成分开。** `runJob` 返回排队或运行中，只能显示“已提交/生成中”；`getJobInfo` 确认成功后才显示“生成完成”。
3. **未知结果不重复创建。** 提交超时或丢回执时保留原调用身份及已知任务编号，按已有机制核查；没有任务编号时标为待核查，不自动重新提交。
4. **错误不能伪装成空结果。** 地址未配置、连接失败、登录/权限失败、报表不存在、参数错误分别保留证据。某个地址返回 404，也不能扩展成“Oracle 所有环境都没有此接口”。
5. **本地模拟与真实上游分开标记。** 模拟服务返回的任务编号只能证明本地调用流程，不能证明 Oracle 接受了 ARR。相同请求在两类环境中的结果要能区分。
6. **沿用应用隔离和现有调用记录。** 请交付这四项操作对应的能力组。运行报表是提交动作，不能直接推定现有 `configuration.read` 已覆盖；本需求单不代替实际授权操作。

以上复用平台现有能力，不要求新增一套通用调度系统，也不需要封装 `killJob` 或周期计划功能。

## 7. 发布后请回传的材料

请按预订部接口交付方式提供：

- 更新后的 catalog/OpenAPI、版本、四个操作的平台路由和能力组。
- 每个操作的请求、返回结构及一份脱敏示例；Oracle 原生字段与平台封装字段分开标注。
- 当前配置连接的是本地模拟服务还是实际 Oracle；实际 Oracle 服务地址、服务器身份及鉴权方式的非秘密说明。
- 连接检查结果；若未配置或上游不可达，明确是哪项尚缺，不用模拟成功替代。
- 如已进行生成测试，提供测试酒店、提交的报表与业务日期、任务编号、最终状态及请求编号；不发送账户密码、令牌或客人明细。

平台如采用与本需求建议不同的路由、参数或返回结构，给出最终契约即可，ARR 侧负责适配。

## 8. 联调顺序和完成标准

| 阶段 | 要验证的内容 | 达到后可以怎样汇报 |
| --- | --- | --- |
| A. 封装发布 | 四个入口已发布，契约完整；本地模拟能够提交和查询任务 | “候选接口已发布，本地调用流程通过” |
| B. 实际服务连接 | 版本与服务器查询来自实际 Oracle，确认访问身份及目标环境 | “报表服务连接通过”，仍未证明 ARR 可以运行 |
| C. ARR 生成 | 使用已核实的报表运行标识、参数及明确日期，提交一次 ARR；保留任务编号并查询至结束 | 成功时汇报“指定日期的 ARR 生成任务已成功”；失败时按实际错误继续修正 |
| D. 原件与财务处理 | 取得原件、存 OSS、验证参数效果和内容，再接现有 ARR 处理链 | 后续批次；本批不宣称端到端完成 |

本轮最终要解决的是 C。若只有 A 通过，就继续针对真实上游缺项处理，不能把本地生成的样例当成 Oracle 原件。

真实服务地址、身份、报表运行标识和具体参数是测试所需输入。公开文档已有的部分由业务项目侧查证；现有配置及调用错误能验证的部分直接测试，不把咨询 Oracle 作为默认前置步骤。如果实际环境未开放该候选服务，记录证据后再决定下一条原生接口路线。

## 9. 背景依据与状态说明

- 本需求吸收了预订部任务“对接OHIP”的最新已完成交付：平台先发布明确接口，业务项目按最终契约接入，由用户按步骤验收。预订部新操作和财务部报表操作分别验证，不共享完成结论。
- 平台目录版本及预订部交付状态采用 2026-09-17 已取得的结果；后续变化以新交付为准。
- Oracle 官方 REPCFG：[报表配置接口定义](https://github.com/oracle/hospitality-api-docs/blob/4bd129b455bc5e3ab0f900ac47983611e58659b4/rest-api-specs/property/v1/repcfg.json)。它证明报表配置/参数读取能力，不能据此认定具备生成能力。
- `RWWebService` 文档证明四个候选操作存在；它没有证明当前 OPERA Cloud 租户开放这些操作。这一点通过上述测试核实，不作为停止封装研究的理由。
- 本文是供转发的财务部本批需求，不代表已发送消息、已修改平台权限、已启动 Oracle 任务或已变更现有运行环境。