93 lines
8.5 KiB
Markdown
93 lines
8.5 KiB
Markdown
# ARR 自动取数字段对接表
|
||
|
||
核对日期：2026-10-08。
|
||
|
||
每个接口实际传什么参数、参数来源和补查条件，见[接口与传参确认单](ARR_OHIP_REQUEST_PARAMETERS.md)。
|
||
|
||
实施进展：[按日期取数入口](integrations/ohip/DATA_SOURCE.md)覆盖本表15个字段及必要关联查询。
|
||
已用2026-10-07到店日保存的真实生产响应在本机离线重放176次读取，识别58条预订，字段及原始顺序与捕获一致。
|
||
结构化列表请求省略生产拒绝的可选排序；姓名摘要改用精确ID的`getProfiles` GET。
|
||
原始缺口由新增字段完善流程先处理，随后进入共用处理、独立校验、既有缺价复核、Finance日报与自动月报流程；人工XML上传继续保留。
|
||
当前状态是“生产请求兼容和字段识别已核对，10月7日业务字段值待确认”，不表示正式日报或生产报表验收通过。
|
||
|
||
当前目标：用户选一天，系统通过 OHIP 平台取得该日到店预订所需的数据，直接交给数据处理入口，沿用现有筛选、去重、定价、复核和报表规则。人工 XML 上传入口保留。自动取数不以取得或重建 XML 为前提。
|
||
|
||
字段范围来自 [ARR XML 加工前字段清单](ARR_XML_RAW_FIELDS.md)。自动取数需要其中 15 个业务字段；Trace 沿用已确认的“不获取”。字段允许为空的规则保持不变。
|
||
|
||
## 契约与生产捕获核对
|
||
|
||
2026-09-18曾读取OHIP平台接口目录及接口说明：版本 **0.11.0，共184项操作**，历史查询编号保留在本文下方。
|
||
本轮对照保存的公开契约及生产捕获核对当前实现，不新增网络查询。58条完整采集仍有原始字段缺口：
|
||
团队代码36项、套餐16项、公司2项、房号1项。`collection_complete=true`只表示预订列表与读取完整，
|
||
`input_complete=false`表示原始输入仍未齐备；不能用补空将其改成已验收。
|
||
人工完善只列出同一冻结处理器认定会阻塞候选记录的字段，因此待确认清单不必等于全部原始缺口数量。
|
||
|
||
## 逐字段对接
|
||
|
||
| 业务字段 | 从哪里取得 | 目前已有成果 | 接下来核实什么 |
|
||
|---|---|---|---|
|
||
| 团队 Block 代码 | 预订详情中的团队资料；必要时补查团队详情 | 已识别22条有值；36条原生省略仍为缺口 | 确认代码或人工明确无此项；不把团队编号、名称或省略当成代码或空值 |
|
||
| 成人数 | 预订详情、所选日的入住资料 | 已有取值和一致性检查 | 实际样本中的共享房、多房人数含义 |
|
||
| 儿童数 | 预订详情、所选日的入住资料 | 已有取值和一致性检查 | 零儿童与字段未返回的区别 |
|
||
| 公司／旅行社名称 | 预订关联的公司、旅行社资料；必要时补查相应档案 | 已识别56条有值；2条关联资料省略仍为缺口 | 缺失或多个不同名称时人工完善；公司名称须填写有效值 |
|
||
| 预订确认号 | 预订详情 | 已有取值 | 与同一笔预订准确对应，保留原始文字 |
|
||
| 房号 | 预订详情；换房、退房等情况补查房间历史 | 已识别57条有值；1条补查返回空日历仍为缺口 | 填写与目标日期对应的有效房号；`roomCalendar={}`不能证明无房号，不能确认为空 |
|
||
| 有效房价 | 对指定预订查询指定日期的房价 | 已有独立查询和金额检查 | 返回有效房价及币种；隐藏价格、缺失价格不能作为零价 |
|
||
| 住客姓名 | 预订唯一主客资料、`getProfiles`精确GET摘要，必要时补查档案详情 | 58条姓名已识别，身份和姓名组成核对通过 | 保留摘要完整显示姓名原文；不按姓名模糊关联或自行拼接 |
|
||
| 预订备注 | 预订详情中的 GEN 预订备注，包含内部备注 | 已有提取，并保留多条内容及顺序 | 多条备注进入既有处理规则后，团号是否正确 |
|
||
| 房间数 | 所选日对应的预订入住资料 | 已有取值 | 不把不同日期重复出现的房间数累加 |
|
||
| 套餐／附加产品 | 预订详情中的套餐清单；需要补充时再查对应套餐 | 已识别42条有套餐；16条原生省略仍为缺口 | 人工确认按序套餐代码或明确无此项；套餐金额为零不能证明无套餐 |
|
||
| 费率代码 | 所选日对应的预订房价资料 | 已有取值 | 取得目标日期的代码；取得后才交由原有白名单处理 |
|
||
| 房型 | 预订详情中的房型代码 | 已有取值和一致性检查 | 房型变更时采用哪个日期对应的值；不以计价房型替换 |
|
||
| 入住日期 | 预订入住资料 | 已有取值 | 与用户选择的到店日期一致 |
|
||
| 离店日期 | 同一预订入住资料 | 已有取值 | 不早于入住日，并保留当天离店情况 |
|
||
|
||
同一接口可以提供多个字段，不需要为 15 个字段各找一个独立接口。
|
||
套餐补查接口需要已经知道套餐代码，因此应先读取预订中已有的套餐清单；它不是一次返回全部未知套餐的入口。
|
||
团队代码和房型在预订资料已经足够时，不必额外查询团队或房型资料。
|
||
|
||
## 先完善字段，再复核价格
|
||
|
||
完整取数后，`DataFieldReviews`使用当前冻结处理器本身的费率白名单和字段校验识别阻塞项。
|
||
任务进入`needs_data_review`，此时尚未创建处理job或写入Finance。费率代码自身待确认时先完善费率，
|
||
再按原规则重新识别该笔需要完善的字段；不另设筛选或定价规则。
|
||
|
||
业务人员仅能修改清单列出的异常字段。团队代码、备注、套餐和房型可人工明确“确认无此项”；
|
||
公司、房号及其他必填字段必须提供有效值。任何未返回字段在人工确认前都不会自动补空。
|
||
原始捕获保持不变，人工决定保存原值、新值、操作者和版本，全部阻塞项通过后冻结派生来源并自动继续原请求。
|
||
|
||
随后共用原白名单、原顺序去重、定价及独立校验。若缺少pureprice，进入原有`needs_review`价格复核；
|
||
完成价格复核后才提交Finance日报，并沿用原月报自动更新。字段完善处理输入事实，价格复核处理后续定价缺口，二者顺序不同。
|
||
|
||
## 接通后的判断标准
|
||
|
||
- 用户选择的日期用于查找当日到店预订，并用于取得相应日价等资料。
|
||
- 先保留完整预订及其关联资料，再交给原有规则处理；取数阶段不预先删除非白名单或重复记录。
|
||
- 每个值都能对应到同一酒店、同一预订及适用日期。原始取数结果及顺序可追溯。
|
||
- 正常为空、接口没有返回、查询失败分别记录；不能用空值或零掩盖未取得的数据。
|
||
- 公司、房价、房号等会影响结果的字段先验证业务含义。相同业务输入应得到与既有规则一致的处理结果。
|
||
- 原生 XML 是否可下载、XML 字节或显示格式是否相同，不作为新数据入口接通的前提。
|
||
|
||
## 历史公开目录查询依据（2026-09-18）
|
||
|
||
来源：[OHIP 平台接口说明](https://ohip.nianxx.cn/developer/v1/openapi)。以下是历史公开查询，无酒店业务数据、无权限修改；本轮未重新请求该地址。
|
||
|
||
| 查询 | 返回 | 查询编号 |
|
||
|---|---|---|
|
||
| 完整接口目录 | 0.11.0，184 项操作 | `9f9ee152-f97d-45ad-b672-cd3e3d1da749` |
|
||
| 完整接口说明 | 0.11.0，包含参数及返回资料说明 | `0968f5e3-dbbf-42f8-aee1-60ff9ff2d855` |
|
||
|
||
当前开发定位：[字段提取](integrations/ohip/source_fields.py)、[房价查询](integrations/ohip/rate_info.py)、
|
||
[姓名摘要](integrations/ohip/profile_summary.py)、[字段完善](arr_web/arr_data_review.py)、
|
||
[处理衔接](arr_web/arr_data_executor.py)和[房间历史检查](integrations/ohip/room_calendar_evidence.py)。
|
||
旧[接口对应资料](integrations/ohip/arr-api-mapping.md)与[姓名补查](integrations/ohip/profile_reader.py)保留历史路线。
|
||
历史资料中以“生成 XML、证明原生报表显示一致”为条件的部分，仅说明当时的路线；当前重点以本页和用户本轮明确的数据入口方向为准。
|
||
|
||
2026-09-18字段对应阶段按当时授权只做目录及本机模拟验证。2026-10-08已完成实际生产捕获的离线字段识别，
|
||
但未确认缺失业务值、未据此生成或验收10月7日正式日报。
|
||
|
||
## 2026-09-18 直接处理衔接
|
||
|
||
15字段数据直接衔接页面、日报、缺价复核和月报，不需要XML适配。备注取第一条非空，套餐按代码顺序显示，原始多值完整保留。
|
||
这段记录指当时的本机模拟验证；当前字段完善及生产捕获核对进展见本文上方和[入口说明](arr_web/DIRECT_DATA_ENTRY.md)。
|