57 lines
4.0 KiB
Markdown
57 lines
4.0 KiB
Markdown
# 独立姓名补充
|
||
|
||
`searchProfiles`不是Opera原生ARR下载的固定前置接口。当前已取得的完整v2归档含搜索、详情和有效价，
|
||
不依赖它。旧v3把姓名查询插在逐笔详情/日价之间，查询失败会停止该次v3；这一行为是旧采集实现，
|
||
不能解释成Oracle要求所有报表都必须查询客人档案。
|
||
|
||
本地新增[profile_supplement.py](profile_supplement.py)，用于先完成v2主体、再独立补姓名。
|
||
这是当前候选数据工具的可执行路径，尚未接入Web运行服务或作为ARR业务验收通过的适配器。
|
||
|
||
## 采集与恢复
|
||
|
||
1. 先验证完整v2归档的外部SHA256、所有原件及协议重放。任何不一致都在读取凭据/发请求之前拒绝。
|
||
2. 只按该归档的唯一主客Profile ID读取摘要，不重新请求预订搜索、详情或价格。
|
||
3. 同一档案只读一次，逐笔核对主客姓名组成。连续3次暂时故障后停止该次所有新增姓名请求；403也立即停止。
|
||
当前失败及后续未查询分别标记，已经缓存的姓名仍可用于后续同档案预订。身份/酒店/响应契约错误仍使补充失败。
|
||
4. 每次补充写入新私有目录，固定原始主体摘要、日期、先前补充摘要、响应原件和逐行诊断。
|
||
有缺口的状态是`name_gaps`，全部候选取得是`complete_name_candidates`；两者都不代表完整ARR。
|
||
5. 恢复时提供按顺序排列的已固定补充目录与摘要。离线重放整个链，复用验证过的非空姓名，
|
||
只对剩余档案发新请求。HTTP200但姓名缺失/无效的响应不会被永久缓存；已有姓名也逐预订重核组成。
|
||
|
||
`max_profiles`约束本次新增的不同档案查询数，每档案最多3次HTTP尝试；它不等于本次姓名有效行数。
|
||
未正常写完manifest的进程中断目录不参与复用，必须另建补充尝试；完整主体仍可复用。
|
||
姓名可能在主体采集之后读取，结果保留来源和时间证据，不声明原子快照。链最多100个完整尝试。
|
||
没有后台自动重试、定时监控或运行接线；平台仍503时不据此发起新的实测。
|
||
|
||
示例中的目录和SHA256由后台已有任务传入，不是财务操作员需要填写的内容。读取使用消费应用凭据。
|
||
|
||
```sh
|
||
.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；仍不能据此宣称报表等价。
|