139 lines
12 KiB
Markdown
139 lines
12 KiB
Markdown
# ARR 源报表下载要求
|
||
|
||
2026-09-18方向更新：用户明确保留人工XML入口，自动入口改为按日期查询OHIP业务数据、直接按相同业务规则处理，
|
||
不再以取得或重建XML为前提。当前15字段取数程序已完成本机检查，按用户要求未验证实际订单；
|
||
参见[字段对应](../../ARR_OHIP_FIELD_MAPPING.md)和[数据入口](../../integrations/ohip/DATA_SOURCE.md)。
|
||
本文件的原生报表/XML显示约定保留为人工入口与历史背景；单日输入、字段含义和既有业务规则继续适用。
|
||
|
||
状态：用户明确提供的业务要求，2026-09-16。描述 Opera 中应取得的源报表及内容，不把界面点击顺序定义为接口调用顺序。
|
||
接口实现及定时调度尚未完成；本文件不是已运行下载任务的证明。
|
||
|
||
用户随后再次明确：页面步骤仅用于说明业务筛选和数据要素，应去平台查找对应接口，不采用模拟点击下载。
|
||
XML为手工样本与现有处理入口格式，不构成“必须存在原生报表下载API才可继续研究”的限制。
|
||
|
||
## 当前沙箱与验收边界
|
||
|
||
2026-09-17用户再次强调当前是测试沙箱OHIPSB02。酒店57106的手工XML是目标报表参考，
|
||
不能要求沙箱返回与正式酒店相同的客人、房间或历史记录。应分开记录接口调用结果、响应字段覆盖和业务样本覆盖。
|
||
房间日历HTTP200但缺room集合只证明这次没有取得该数据，不足以判定平台故障，也不等于已证明空房间历史；
|
||
可能涉及沙箱数据、查询条件或接口处理，根因未定。503则仍是实际调用失败。
|
||
缺少某种沙箱业务样本不应阻断其他接口开发与合成端到端测试；同源真实报表等价留待有适当数据时验收。
|
||
合成/沙箱链路测试与完整实际ARR输出分别标识，不能提前宣布用户的完整ARR按钮里程碑已达成。
|
||
|
||
## 报表与参数
|
||
|
||
界面入口为 `Report → Manage Report`，使用 `Report Name=ARR` 查找，选择 `Report=Arrivals: Detailed`，编辑参数。
|
||
`ARR` 按用户提供的查找值记录；它不是已经核实的 API 报表实例 ID。
|
||
Oracle 官方将该报表的内部名称标为 `res_detail`，与本项目 XML 根 `RES_DETAIL` 对应。
|
||
|
||
| 操作要素 | 用户指定值 |
|
||
|---|---|
|
||
| Report Name | `ARR` |
|
||
| Report | `Arrivals: Detailed` |
|
||
| Reservations | `ALL Reservations` |
|
||
| Room Assignment | `ALL Reservations` |
|
||
| From Date | 由上游系统传入明确日期；当前业务规则为 `T-1`，T 为今日日期 |
|
||
| To Date | 由上游系统传入明确日期；当前业务规则为 `T-1`，T 为今日日期 |
|
||
| 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 - From | `00:00` |
|
||
| Arrival Time - To | `23:59` |
|
||
| Display / Room Number | 勾选 |
|
||
| Display / Notes | 勾选 |
|
||
| Include Internal Notes | 勾选 |
|
||
| Note Types | `Resv. - GEN` |
|
||
| Traces | 用户随后明确“不需要”；本次接口来源输出不包含Trace内容 |
|
||
| Download As | `XML` |
|
||
| 最终动作 | 下载所选报表的 XML 文件 |
|
||
|
||
## 内容边界
|
||
|
||
- 用户随后提供`res_detail_71054429.XML`并明确确认文件准确、页面Note Types选择`Resv. - GEN`。
|
||
新文件与前份`res_detail_71050118.XML`逐字节相同；本样本XML内58条备注标为`RES_COMMENT_TYPE=CAS`、
|
||
`RES_COMMENT_DESCRIPTION=GENERAL`。这是页面标签与导出内部字段在该确认样本中的对应事实，
|
||
不能据此怀疑用户选择、要求再次确认，或将其他环境API筛选改成CAS。用户业务范围继续为Resv.-GEN及其内部备注；
|
||
同源API对应由接口实现核验。[确认记录](../50-evidence/topics/2026-09-16-confirmed-native-arr-notes.md)。
|
||
|
||
- 一次取得前一个日历日的到店明细，起止日期相同；不能解释为滚动过去 24 小时、住宿日汇总或查询当天预订。
|
||
- 用户补充明确：From Date、To Date 由上游系统传给本流程。上游负责按其“今日日期”计算 T-1 并传入明确日期；
|
||
ARR 采集/适配程序直接使用收到的值，不自行读取当前日期、减一天或按本机/酒店时区重新计算。
|
||
这替代此前“拟由 ARR 按 Asia/Bangkok 计算自然日”的实现假设，也不能将输入改为 Opera 营业日。
|
||
- 当前仍为单日任务：两日期必须存在、为有效日期且相同，随后原样映射为 `arrivalStartDate`、`arrivalEndDate`，
|
||
同一日用于价格查询 `detailDate`。缺少或不一致时拒绝本次单日任务，不补默认昨日或擅自选其中一天；
|
||
不用执行时的今日日期反向限制已经传入的日期，以免延迟执行或重试时改动来源范围。
|
||
- 用户本次明确统一 From Date = To Date = 有效价查询日期 = `2026-09-15`。该日期是本次输入，不是永久写死的运行规则。
|
||
- 批次固定系统传入日期，分页、详情、日价、归档和重试保持一致。v2采集入口显式接收必填的
|
||
`from_date/to_date/rate_date`（CLI为 `--from-date/--to-date/--rate-date`），校验三者有效且相等。
|
||
v1兼容入口仍使用必填 `arrival_date`；后台下载执行器的生产接线尚未完成。
|
||
- 用户指定的是报表的 `ALL Reservations` 原有语义。取消、No-show、已到店、未到店及空 ETA 在此报表中的
|
||
实际纳入规则须由报表契约/样本核实，不能直接假定对应 API 的所有状态枚举或默认搜索。
|
||
- Room Assignment 保持 ALL，不主动缩为“仅已分房”；七个 `ALL CODES` 选项均不增加业务子集筛选。
|
||
- 源报表 Rate Code=ALL；ARR 当前处理器的费率白名单在接收完整源文件后执行，不提前替代源报表选择条件。
|
||
- Notes 仅选择 `Resv. - GEN`，同时包含该范围的内部备注；“包含内部”不表示“仅内部”或“所有备注类型”。
|
||
- 房号必须在所选报表输出中显示；此选项不等于要求源报表只包含有房号的预订。
|
||
- 用户随后明确“Trace不需要”：接口来源适配生成的`SourceRow.traces`应为明确空元组，保持兼容XML结构但不输出Trace内容；
|
||
不再要求用户提供Trace部门、日期或解决状态。已有原生XML中的31条Trace是历史输入事实，不需重导出；通用序列化器及
|
||
人工XML处理器仍如实保留/读取各自输入，不因此重写历史原件或更改人工上传规则。既有v2档案含Traces fetch，
|
||
保留其固定契约用于回放；未来采集若移除该fetch，须另行版本化，不修改旧归档或伪称它们未取Trace。
|
||
- 用户对“Sort Order”未理解，未提供排序选项；不能把此答复当成房号升序或任意顺序的许可。已解释为记录排列方式。
|
||
当前确认样本没有房号+到店日重复组，排序不改变其去重赢家；不向用户重复索要无法说明用途的配置。
|
||
后续若重复记录的不同内容使顺序影响结果，应展示具体业务差异再核对，不能靠静默删行或自选优先级解决。
|
||
- 用户未指定其他 Display 选项、排序/分组、定时执行时点、历史补跑和空日策略，不自行把它们
|
||
声称为用户确认的值。接口实现须保留与原报表等价的行顺序，因为现有处理器去重保留源顺序第一条。
|
||
|
||
## 与现有处理链的衔接
|
||
|
||
### 手动 Web 日期入口（2026-09-16 新增）
|
||
|
||
用户确认 Daily Report 的 Upload ARR.XML 左侧增加自动下载卡片，操作员只能选一天。所选日期 D 明确传给
|
||
下游：From Date=D、To Date=D；既不是日期区间，也不固定覆盖用户选择为 T-1。页面初始建议昨天、可修改，
|
||
仅属于表单预填；提交必须有明确有效日期，下载执行与重试不自行推算或补默认值。
|
||
Web 卡片/API/任务边界已在本地实现，真实来源执行器仍未接入；[接入说明](../../arr_web/ARR_DOWNLOAD_HANDOFF.md)。
|
||
其他上游系统仍按前文契约提供两个明确日期，本入口没有扩大到多日任务或新增定时调度。
|
||
|
||
|
||
取得完整、有效的原报表 XML 后，手工入口使用现有 `ProgrammaticUploadCoordinator.submit(filename, bytes)`。
|
||
自动采集路径须沿用已冻结批次/交付身份重试；不得每次重试直接调用会新建UUID的手工submit。
|
||
目前独立的冻结交接原型已具备这些语义，正式执行器尚未接入。
|
||
原件保存、独立重放、字段校验、白名单、去重、价格复核、Finance 与月报触发继续沿用现有流程。
|
||
XML 入口契约见 [field-contracts.md](../../arr-opera-daily-ingest/references/field-contracts.md)。
|
||
|
||
现有处理器对有效白名单行要求房号，并读取第一条非空 `RES_COMMENT`；`TRACE_TEXT` 可空。这是代码现状，
|
||
不会改变用户要求的全量下载。若完整原报表出现未分房的白名单行，应按实际校验结果处理并另行核对需求，
|
||
不能通过下载前丢弃该行使任务“通过”。Trace现已明确不需要，按上述接口输出范围处理；不改既有人工XML解析器。
|
||
|
||
按上述业务参数研究平台接口：既检查是否有整份报告获取能力，也检查预订查询/详情组合能否覆盖所需数据。
|
||
若平台返回预订JSON，须核对完整性、语义和结果等价性，再讨论可重放适配；尚未选择重建XML或修改处理器。
|
||
不能因未找到原生XML接口便转向让用户操作页面或配置计划报表/SFTP。方向纠正见
|
||
[接口研究范围](../50-evidence/topics/2026-09-16-arr-api-scope-correction.md)。
|
||
|
||
## 官方补充证据（不替代用户选项）
|
||
|
||
Cloud23.4明确原RES_DETAIL不显示已解决/完成的Trace；其API候选为resolveInfo.resolvedOn/resolvedBy。
|
||
Cloud24.3明确排除InSession GDS，不能泛化成其他状态规则。报告显示名称ARR可以对应自定义筛选/排序实例，
|
||
故采集ConfirmationNo升序不能视为原报告顺序。这些事实及来源见[来源对照核验](../50-evidence/topics/2026-09-16-arr-source-comparison.md)。
|
||
用户目前不能访问OHIPSB02进行同源导出；比较工具已就绪，正式酒店57106样本仅保留既有处理基准用途。
|
||
|
||
## 来源
|
||
|
||
- 用户在本任务 2026-09-16 提供的 ARR Report 操作与参数清单，为本文件权威业务输入。
|
||
- 用户随后补充：From Date / To Date 的 T-1 由系统传入；此补充决定日期计算责任与输入边界。
|
||
- [Oracle Arrivals Reports](https://docs.oracle.com/cd/F34189_01/doc.201/f42091/c_reports_arrival.htm)：
|
||
佐证 `Arrivals: Detailed` 的内部名称为 `res_detail` 及到店明细用途；不用于补造用户未指定的选项。
|
||
- API 候选、参数映射和未验证处见 [接口研究](../50-evidence/topics/2026-09-16-ohip-interface-review.md)。
|
||
|
||
详细的业务要素、16来源字段与完整日/重放要求已收录于[API对应表](../../integrations/ohip/arr-api-mapping.md)。
|
||
该表分开记录结构事实与待实测语义，未变更本页用户要求或现有处理规则。
|
||
|
||
后续[OHIPSB02实测](../50-evidence/topics/2026-09-16-arr-api-live-probe.md)确认搜索/详情可取得完整日期候选，但
|
||
空ETA、状态纳入、价格和来源顺序尚未与报告同源验证；不把测试结果改变为本页新增的用户业务规则。
|
||
|
||
## Direct data entry — 2026-09-18
|
||
|
||
2026-09-18 implementation: DirectARRSource now feeds the existing date button, direct processor and validator, review, Finance and monthly flow. XML source-equivalence gates only govern the old CapturedARRSource path. Local synthetic acceptance does not certify actual platform fields; user expressly skipped actual sandbox fetching. See ADR-007 and direct-data-entry evidence.
|