4.0 KiB
独立姓名补充
searchProfiles不是Opera原生ARR下载的固定前置接口。当前已取得的完整v2归档含搜索、详情和有效价，
不依赖它。旧v3把姓名查询插在逐笔详情/日价之间，查询失败会停止该次v3；这一行为是旧采集实现，
不能解释成Oracle要求所有报表都必须查询客人档案。
本地新增profile_supplement.py，用于先完成v2主体、再独立补姓名。 这是当前候选数据工具的可执行路径，尚未接入Web运行服务或作为ARR业务验收通过的适配器。
采集与恢复
- 先验证完整v2归档的外部SHA256、所有原件及协议重放。任何不一致都在读取凭据/发请求之前拒绝。
- 只按该归档的唯一主客Profile ID读取摘要，不重新请求预订搜索、详情或价格。
- 同一档案只读一次，逐笔核对主客姓名组成。连续3次暂时故障后停止该次所有新增姓名请求；403也立即停止。 当前失败及后续未查询分别标记，已经缓存的姓名仍可用于后续同档案预订。身份/酒店/响应契约错误仍使补充失败。
- 每次补充写入新私有目录，固定原始主体摘要、日期、先前补充摘要、响应原件和逐行诊断。
有缺口的状态是
name_gaps，全部候选取得是complete_name_candidates；两者都不代表完整ARR。 - 恢复时提供按顺序排列的已固定补充目录与摘要。离线重放整个链，复用验证过的非空姓名， 只对剩余档案发新请求。HTTP200但姓名缺失/无效的响应不会被永久缓存；已有姓名也逐预订重核组成。
max_profiles约束本次新增的不同档案查询数，每档案最多3次HTTP尝试；它不等于本次姓名有效行数。
未正常写完manifest的进程中断目录不参与复用，必须另建补充尝试；完整主体仍可复用。
姓名可能在主体采集之后读取，结果保留来源和时间证据，不声明原子快照。链最多100个完整尝试。
没有后台自动重试、定时监控或运行接线；平台仍503时不据此发起新的实测。
示例中的目录和SHA256由后台已有任务传入，不是财务操作员需要填写的内容。读取使用消费应用凭据。
.venv/bin/python -m integrations.ohip.profile_supplement \
--capture-dir /private/complete-v2 \
--capture-sha256 <主体manifest的SHA256> \
--output-dir /private/names-attempt-1 \
--max-profiles 112 \
--credential-file /private/application-credential.json
下一次改用全新--output-dir，追加--previous /private/names-attempt-1 <姓名manifest的SHA256>。
存在多次历史时依顺序重复--previous；不允许换主体、缺少祖先、改日期、乱序或重复摘要。
所有姓名已可复用时不会发网络请求，CLI也不会读取凭据。
字段准备
prepare_arr_source.prepare(..., name_supplements=[(directory, sha256), ...])以及CLI的
--profile-supplement DIRECTORY SHA256可将验证过的补充接入完整v2字段准备。
当前字段准备统一使用arr-source-preparation/v4，携带姓名补充时保留完整补充摘要列表。
v3新增typed BlockCode，v4增加三层一致房型代码；历史准备产物不重写，旧字段证据契约仍兼容。
FULL_NAME保留返回原文或具体缺口，行数和业务验收标志保持原样。
补充不作为旧v3捕获、旧字段证据或Finance交付文件冒充使用。
姓名直接取值的证据边界
2026-09-17离线核对：139条搜索均无reservationGuest.fullName，详情有139个surname、134个givenName、
2个middleName和8个title。既有5份全日成功响应都符合“surname, givenName”，但均没有中间名/缺名字情形。
另3份已固定边界响应显示：中间名案例没有把middleName拼入fullName；缺givenName案例只显示surname。
这是摘要字段的观察，不是同酒店原生ARR显示规则的证明。暂不把任意拼接升级为正式姓名映射。
准确原生XML来自酒店57106，API归档来自OHIPSB02；仍不能据此宣称报表等价。