# ARR 自动取数交付与生产启用说明

更新日期：2026-10-08。状态：**代码收尾完成，本机已连接生产酒店57106；目标主机部署和完整报表业务验收仍需执行。**
本机10月7日任务已保存生成成功结果，38间房；该状态不代表已逐项核对实际日报文件及月报内容。
早期沙箱/模拟检查是历史验证，不替代生产业务验收。生产连接、修复和本机验证记录见[本次任务](../.project-docs/30-worklog/tasks/20261008-production-review-9e7b.md)。

当前处理器为4.4.0。目标数据库需按顺序具备019、020和021，Web与处理器必须一起发布。
用户已确认两条输入路径都排除已取消预订和PM房型；完整原始数据仍保留，不要求被排除记录补房号。
已有未处理任务接续必须备份并显式记录新旧规则身份，不能复用旧身份直接运行新规则；已发布结果不自动重新处理。

## 完成的产品流程

选择一天 → 从 OHIP 获取到店预订和关联资料 → 如有阻塞字段则人工核对 → 按共用规则筛选、去重、定价 → 如缺价则人工核对价格 → 生成并下载日报 → 入库后自动更新月报。

- 自动入口覆盖15个业务字段、8个查询接口；Trace按约定不获取。
- 直接处理接口数据，不生成中间XML；原人工XML上传入口保留。
- 日期选择、运行中预选、任务状态、重复提交保护和原任务恢复已实现；取数进度按预订笔数显示，最终完整性核对通过才显示100%。
- “需处理日期”保留不同日期的字段/价格待处理任务；统一在“人工核对”中完成。取数已完成不等于报表已生成。
- 旧任务在已验证的来源解释/排除规则下清空整张字段清单时自动继续，重启可恢复原请求；清单仍有人工核对项或缺价时保留相应确认步骤，历史决定完整留痕。
- 缺少定价资料进入原有价格复核；影响处理的必需字段缺失或存在无法确定的候选时提示异常。
- 本机模拟已覆盖日报、复核、入库、月报、报表下载及断线恢复；用户确认日期交互验收通过。

字段：[对接表](../ARR_OHIP_FIELD_MAPPING.md)。产品使用：[直接数据入口](../arr_web/DIRECT_DATA_ENTRY.md)。

## 正式启用必须完成的配置

| 项目 | 当前边界及启用要求 |
|---|---|
| 酒店与平台 | 当前本机已连接生产酒店57106。目标部署仍须核对平台实际路由和授权；本地hotel-id仅校验返回酒店，不能把沙箱接口切成生产接口。 |
| 应用身份 | 当前客户端固定平台`https://ohip.nianxx.cn`及应用`caller_zloxalzsQ9pYsztt`。如生产改用其他平台或新应用，需适配并验证固定身份配置；替换一份不同身份的密钥文件会被拒绝。 |
| 读取权限 | 目标应用须覆盖预订、档案、团队、房间历史及套餐8个操作；现有配置需求包含reservations.read、profiles.read、blocks.read、configuration.read。保留平台已授其他权限，不盲目覆盖权限集。 |
| 数据库 | 在已具备018的目标库上按顺序应用019、020、021。本机已升级至021；既有迁移及运行配置要求隔离库名`booking_test`。若目标使用其他库名，先适配和验证数据库边界，不能直接删除保护或假设已有兼容。 |
| 自动取数入口 | 标准启动器支持三个OHIP参数，现有基础Compose尚未传入，部署时须明确加入。仅按基础Compose启动会保留原处理入口而不启用自动取数。 |
| 凭据和持久数据 | 挂载正式凭据目录，并为任务/原始数据配置仓库外的持久目录。目录0700、凭据文件0600，属主为实际运行用户；容器须按容器UID准备属主。凭据只读挂载，任务目录可写，不能放临时目录或镜像内。 |
| 月报与报表存储 | 复用正确配置的数据库和OSS，独立月报worker须由进程管理器持续运行。网页可访问、Web健康检查成功不等于月报worker已启动。 |

固定平台/应用身份和数据库名称均保留原有边界。本次代码推送不部署目标主机、不修改平台路由、不重新查询或生成报表。

## 启动对照

沿用[部署说明](README.md)的登录、数据库、OSS和HTTPS配置，为Web添加以下三个参数：

```text
--ohip-hotel-id <平台实际返回的正式酒店ID>
--ohip-credential-file <容器或主机内的正式凭据文件绝对路径>
--ohip-state-root <仓库外的私有持久目录绝对路径>
```

三个参数必须一起提供，并保留`--enable-processing`。Compose部署需同时更新Web的command与凭据/状态目录挂载；仅在环境文件填写变量不会被当前启动器自动读取。
新正式环境使用新任务目录，不能复制沙箱队列、原数据或未完成任务；目录绑定酒店、平台、应用及处理规则。

月报另按部署说明运行`python -m monthly_reports.worker --output-root /app/outputs/monthly_reports`并配置持续监管。
`--enable-monthly-generation`是另一个手动生成入口，不替代自动月报worker。

数据库升级文件为`database/019_ohip_data_source.sql`、`database/020_daily_cancelled_exclusion.sql`、`database/021_daily_pm_exclusion.sql`，各有对应`.down.sql`。
先检查现有版本、备份和副本验证，再在正式启用窗口按顺序升级；已有相应来源/排除事实时回退会被保护机制拒绝。

## 有真实数据后的首日验收

以下是目标部署后的验收步骤，本次推送不发起查询：

1. 选一个有到店记录的日期，确认来自正确酒店、范围完整，15字段的空值/缺失/候选状态符合实际。
2. 完成需要的字段及价格核对；人工价格允许明确填写0，空白不能当0。核对日报记录、金额以及已确认的取消/PM排除规则。
3. 确认月报自动更新，页面能够下载日报及月报，文件内容和汇总一致。
4. 确认刷新/断线后能恢复原任务，重复继续不会重复入库。

完成这些检查后，才可把状态更新为“生产验收通过”。真实字段缺失、名称多候选、历史换房或生产取数规模可能需要依据实际返回继续适配。

## 收尾检查与已知验证范围

- 2026-09-18直接处理验收：220项相关检查及5项JS检查，包含独立本机PostgreSQL和模拟页面全流程，详见[记录](../.project-docs/50-evidence/topics/2026-09-18-arr-direct-processing.md)。
- 2026-09-18日期修复：9项JS与27项Python检查、用户原页面实点和用户确认，详见[记录](../.project-docs/50-evidence/topics/2026-09-18-arr-calendar-selection.md)。
- 2026-09-18收尾：2项部署入口检查通过，标准启动帮助确认三个OHIP参数可用。
- 最新功能验证：取数进度118项后端、84项JavaScript及13项静态UI检查通过，实际本机9月15日显示85/85笔且人工核对仍保留。取消/PM、字段/价格核对、日报/月报和迁移的既有验证及边界见本次任务记录。
- 当前处理器`.zip`及`.skill`已随4.4.0更新，两包SHA-256均为`aac23951ca72cc6878b617cddaaa5dffd9dc6fe2dee1c9036db61c880118a134`；压缩包内工作簿与原版一致。
- 本机没有Docker命令，本次未构建或启动生产镜像；正式主机部署验证待执行。
- `.zip/.skill`是处理器包，完整Web交付还包含项目源码、数据库019至021及运行配置，不能只上传处理器包来启用自动下载。