# 按日期获取接口数据并生成 ARR

2026-09-18：新增入口已连接页面、日报、缺价复核和原有月报流程。人工 XML 上传保留。
用户已确认页面交互，并授权配置OHIP连接；当前8875为本机OHIP沙箱入口，实际沙箱取数未验证。
接口数据直接进入共用筛选、去重、定价和报表规则，不生成中间 XML。
开发已收尾；生产启用条件、部署模板现有边界和首次数据验收见[交付说明](../deploy/OHIP_RELEASE_HANDOVER.md)。

## 使用流程

选择报表日期 → 点击“下载并处理” → 获取该日数据 → 处理并核对 → 日报进入历史，月报自动更新。
点击日期文字或右侧日历图标，再点击日历中的某一天即可选择。任务进行中仍可预选下一日期；
当前任务结束后需再次点击下载，预选不会自动提交或修改原任务。页面进度始终显示原任务的日期。
任务结果待确认时，先检查或继续按钮上标明日期的原任务，避免重复提交。
只有缺少价格时进入原有价格复核；确认后从保存的原始数据重新处理。缺字段或多个候选会报错，不会当成零价。
任务中断后“继续原任务”复用原始数据和结果，同一请求不会重复入库。历史来源显示“接口获取”。

备注使用清理表情后的第一条非空预订备注；套餐按原顺序显示套餐代码（逗号分隔，保留重复）。
完整备注、套餐明细和查询出处保留在原始数据中。Trace 不获取，旧报表对应列留空。
这是一套明确的新入口显示规则，不声明与 Oracle 原生报表的文字格式完全一致。

## 当前本机 OHIP 沙箱入口

[打开原地址](http://127.0.0.1:8875/)，沿用原账号密码。酒店OHIPSB02、平台地址、应用凭据路径已配置；
本机数据库和报表单独保存，人工XML上传保留。平台同事已补齐团队资料读取权限`blocks.read`，
2026-09-18 06:00Z核对所需权限齐全，下载按钮已启用；见[补权记录](../integrations/ohip/PLATFORM_ACCESS_REQUEST.md)。
本轮只检查权限和页面就绪状态，没有提交真实下载任务；用户选日期并点击后才会查询。

实例使用`arr_web.local_ohip`，启动只核对本机配置和凭据，不调用酒店接口。
`check-access`只读取平台开发身份、应用列表和密钥状态，不改权限、不签发密钥、不查询订单；
成功后更新本机`access.json`。已运行页面下次加载配置即可识别新权限，无需重启或重新部署。
刷新核对失败会暂停新下载，缺权时服务仍可登录，但创建/重试任务均拒绝，防止半途缺字段。
凭据、原数据、队列及报表都在仓库外的私有目录，具体位置见[本轮记录](../.project-docs/50-evidence/topics/2026-09-18-arr-ohip-activation.md)。

```sh
# 新建本机实例；沿用原登录时可额外传 --login-file /private/old-instance/login.json
.venv/bin/python -m arr_web.local_ohip init \
  --parent '/private/arr-instances' --credential-file '/private/ohip-credentials/application.json'
# 仅核对平台权限；不查询订单。需要已授权的开发身份文件。
.venv/bin/python -m arr_web.local_ohip check-access \
  --root '/private/arr-instances/ohip-sandbox-INSTANCE' --automation-file '/private/ohip-credentials/automation.json'
LC_ALL=C LANG=C .venv/bin/python -m arr_web.local_ohip serve \
  --root '/private/arr-instances/ohip-sandbox-INSTANCE' --port 8875
```

后台运行使用该实例`service.plist`，由用户会话launchd保持，不依赖对话进程；未安装开机启动项。
8873/8874未操作，原8875模拟实例已停止但完整保留，可恢复。

## 已完成的本机模拟验收（历史）

原8875模拟入口已由上述沙箱配置入口替换。历史验收使用6笔虚构订单，日期2026-09-15；
当时页面顶端明确标注“未连接 Oracle”，模拟记录未迁入新的沙箱实例。
登录信息保存在当前实例的 `login.json`，不写入仓库或日志。
本轮实例位置见[验证记录](../.project-docs/50-evidence/topics/2026-09-18-arr-direct-processing.md)。
它与8873/8874实例、原有业务数据库和对象存储完全独立。

可创建新的模拟实例（无需 OHIP 凭据）：

```sh
.venv/bin/python -m tests.direct_data_portal init
# 将上一行返回的私有目录填入下面的路径
.venv/bin/python -m tests.direct_data_portal serve --root /absolute/private/instance --port 8875
```

模拟测试使用仓库内明确标记的虚构接口响应，不代表实际沙箱取数验证。

## 正常运行配置

数据库须已应用019迁移；本轮只在独立本机测试库应用，未修改既有数据库。
该迁移允许真实的 `ohip_json` 源制品和5.0结果进入已有复核流程。
启动会先检查迁移，未具备条件时不开放下载服务。原来的月报后台程序仍须正常运行。

```sh
.venv/bin/python -m arr_web.run --enable-processing \
  --ohip-hotel-id OHIPSB02 \
  --ohip-credential-file /absolute/private/ohip-credentials.json \
  --ohip-state-root /absolute/private/arr-data-state
```

以上三个 OHIP 参数必须一起提供；数据库、对象存储、网页登录沿用现有私有配置。
凭据文件仅在实际点击获取数据时读取，不在启动时查询酒店。
私有任务目录须在仓库之外，并绑定酒店、来源类型、查询上限和处理规则；规则更换后使用新目录，
不将旧任务悄悄改绑。旧版本未完成的价格复核遵循原有“规则已变更”保护。

也支持 `DirectARRSource` 注入共享运行依赖。原有 `CapturedARRSource` 为历史 XML 模式保留，
它不再是新数据入口的前置条件。不得把模拟传输当成实际平台传输。

取数字段和八项只读操作见[数据入口说明](../integrations/ohip/DATA_SOURCE.md)。
沙箱所需权限已按上述记录核对齐全；正式环境权限和实际返回字段覆盖率仍待上线配置及有数据后的验收。
`getBlock` 等补查如无权限会明确失败，不补造空值。

## 检查

```sh
ARR_TEST_LOCAL_POSTGRES=1 .venv/bin/python -m unittest tests.test_arr_direct_data -v
```

检查覆盖6笔正常订单总额18200、缺价复核、缺字段、去重、原始数据保留、独立报表核对、
页面请求、月报公式、提交后断线恢复、来源版本隔离，以及019迁移检查和回退保护。
浏览器检查：`tests/browser/arr_direct_data.cjs`，只接受明确指定的本机模拟实例。

当前8875已交给用户会话后台服务运行，避免对话结束后登录页无法连接。仅在当前用户会话运行；
当前OHIP沙箱的停止命令为 `launchctl bootout gui/$(id -u)/com.arr.local-ohip.8875`。服务配置位于私有实例的
`service.plist`；重新加载使用 `launchctl bootstrap gui/$(id -u) /absolute/private/instance/service.plist`。
后台环境已设 `LC_ALL=C`、`LANG=C`。先停后台服务再使用前台serve命令，不同时启动两份。