20 KiB
发给平台同事：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 接口定义、Oracle Reports Web Service 操作说明、OPERA Cloud 生成报表使用说明。最后一份说明证明页面可以生成、下载报表，不是外部系统调用接口的说明。
业务目标、已确认参数、同酒店两部门的分工不变。目前没有新增一项“已证实适用、可以直接封装”的 ARR 生成接口。后续只有找到适用入口及明确请求、返回说明，或取得可验证的现有服务证据，才重新发布具体封装清单；不以咨询 Oracle 作为默认前置条件，不采用页面点击或业务数据拼装来替代。
后续只读核验：计划报表确实覆盖 ARR，但调用入口仍缺
- Oracle 26.1 的官方演示文字稿直接以 Arrivals: Detailed 为例，演示设置报表参数、日期、周期和投递目标。因此“原生 ARR 可以自动生成”有明确的产品依据，不只是通用报表产品的推测。
- 26.1 计划报表说明列出固定日期或动态日期、单次或重复执行，以及 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 封装平台。
这次请补 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 程序处理、验证、入库 → 下游日报/月报。
本批交付集中在：
- 平台能够调用候选报表服务。
- 平台能够提交一次报表生成请求并保留任务编号。
- 平台能够查询该任务的生成结果。
本批不要求下载文件、接 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 路径。官方服务地址形式为：
{实际 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、四个操作的定义及返回示例。
平台侧建议的路由形状
以下仅是本次建议，尚未发布，也不是 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 和参数配置的说明。
6. 封装时需要保持的行为
- 保留真实上游结果。 HTTP 成功不等于报表生成成功；返回任务编号、Oracle 原始任务状态、SOAP Fault/业务错误、平台请求编号，方便定位到同一次调用。
- 提交与完成分开。
runJob返回排队或运行中，只能显示“已提交/生成中”；getJobInfo确认成功后才显示“生成完成”。 - 未知结果不重复创建。 提交超时或丢回执时保留原调用身份及已知任务编号，按已有机制核查；没有任务编号时标为待核查，不自动重新提交。
- 错误不能伪装成空结果。 地址未配置、连接失败、登录/权限失败、报表不存在、参数错误分别保留证据。某个地址返回 404，也不能扩展成“Oracle 所有环境都没有此接口”。
- 本地模拟与真实上游分开标记。 模拟服务返回的任务编号只能证明本地调用流程，不能证明 Oracle 接受了 ARR。相同请求在两类环境中的结果要能区分。
- 沿用应用隔离和现有调用记录。 请交付这四项操作对应的能力组。运行报表是提交动作，不能直接推定现有
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：报表配置接口定义。它证明报表配置/参数读取能力，不能据此认定具备生成能力。
RWWebService文档证明四个候选操作存在；它没有证明当前 OPERA Cloud 租户开放这些操作。这一点通过上述测试核实，不作为停止封装研究的理由。- 本文是供转发的财务部本批需求，不代表已发送消息、已修改平台权限、已启动 Oracle 任务或已变更现有运行环境。