91 lines
9.7 KiB
Markdown
91 lines
9.7 KiB
Markdown
# ARR 自动取数交付与生产启用说明
|
||
|
||
更新日期：2026-10-09。状态：**本机已连接生产酒店57106，并完成022及日报版本管理升级；目标主机部署和完整报表业务验收仍需执行。**
|
||
本机10月7日任务已保存生成成功结果，38间房；该状态不代表已逐项核对实际日报文件及月报内容。
|
||
早期沙箱/模拟检查是历史验证，不替代生产业务验收。生产连接、修复和本机验证记录见[本次任务](../.project-docs/30-worklog/tasks/20261008-production-review-9e7b.md)。
|
||
|
||
当前处理器为4.4.0。目标数据库需按顺序具备019、020、021和022，Web、处理服务与月报worker必须一起发布。
|
||
用户已确认两条输入路径都排除已取消预订和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、022。022支持日报删除及月报撤下；既有迁移及运行配置要求隔离库名`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`、`database/022_daily_report_retirement.sql`，各有对应`.down.sql`。
|
||
先检查现有版本、备份和副本验证，再在正式启用窗口按顺序升级；已有相应来源/排除事实时回退会被保护机制拒绝。
|
||
|
||
## 日报版本管理升级（2026-10-09）
|
||
|
||
同一天只展示一个有效日报；新输入待核对或失败时保留原日报，成功入库后才覆盖。删除当前有效日报会原子移除当日有效指针、保留原始事实和审计、撤下受影响月报，并通过`arr.daily_scope_changed`事件重建该月剩余有效日期的月报。整月为空时撤下月报，不发布空工作簿。删除旧版本或待价格核对版本不会改变当前日报及月报；旧版本不会自动恢复。
|
||
|
||
启用前停止新任务并等现有处理停止，备份数据库、对象存储及私有任务目录；应用022后同时更新Web/处理服务/月报worker，再开放删除操作。旧worker不认识新事件，不能单独发布Web。处理服务启动时检查022的表、索引及审计保护；不满足时拒绝启用。旧本机实例的schema标记须在受控备份及实际升级后更新，不能只改标记绕过升级。
|
||
|
||
022给已有`arr_app`角色精确增加审计表SELECT/INSERT、对应sequence权限以及`finance.current_daily_versions`的DELETE，不授予原始数据、对象或Finance事实的删除权限。自定义应用角色须获得相同权限；自定义网页只读角色须另授予`SELECT ON ingestion.daily_run_retirements`（沿用已有schema USAGE），不能给它写入或DELETE权限。所有角色名按目标环境实际配置，不向PUBLIC授权。
|
||
|
||
迁移不自动删除、合并或重新处理已有报表。同日历史仍可追溯，界面按当前有效指针分组展示。已有删除审计或withdrawn月报时，022回滚会拒绝执行，须先评估恢复方案；恢复整个备份也必须连同匹配的旧代码和worker一起恢复。
|
||
|
||
本次功能仅使用独立合成数据验证删除和月报同步；本机升级保留实际报表及待办，不为验收删除用户日报或重新读取Oracle数据。
|
||
本机升级后逐表核对26张既有业务表、3个有效日报、4,896份原始捕获文件及待办均保持一致（月报新增的空withdrawn_at列不参与原列比较）。022删除审计为0；浏览器已确认9月16日按日期合并及9月13日概览一致。备份、验收及保留运行工作树的记录见[本次版本管理任务](../.project-docs/30-worklog/tasks/20261009-daily-lifecycle-7bc2.md)。
|
||
|
||
## 有真实数据后的首日验收
|
||
|
||
以下是目标部署后的验收步骤，本次推送不发起查询：
|
||
|
||
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至022及运行配置，不能只上传处理器包来启用自动下载。
|