wyndham-ARR/DATA_PROCESSING_HANDOFF.md

ARR 数据处理与数据库交接

更新时间：2026-07-28
适用：另一个对话继续训练/调试日报 Skill、月报程序或公司 10 日报表程序。

1. 最终处理链

用户上传 Opera XML
  → ARR 存入私有 OSS
  → SuperAgent 获取 XML
  → Agent 调用 arr-opera-daily-ingest
  → Skill 生成日报 XLSX、result.json、structured-result.json
  → ARR 获取正式工件并建立 DeliveryEnvelope
  → ARR 独立重验 Schema、哈希、计数、公式和语义
  → arr_ingestion 单事务写 PostgreSQL
  → 普通程序查询 current + retained 事实
      ├─ 生成月报
      ├─ 生成/查询渠道明细与 BI
      └─ 结合预订 room items 生成每 10 日公司用房表

Agent/Skill 不连接 PostgreSQL，不生成数据库 SQL，也不负责月报累计。

2. 权威实现

日报 Skill 源目录：arr-opera-daily-ingest/

SuperAgent 平台安装包：arr-opera-daily-ingest.skill

主要契约：

• references/business-rules.md
• references/field-contracts.md
• references/error-contract.md
• references/structured-output.md
• references/structured-result.schema.json
• references/codex-result.schema.json
• references/价格对照.xlsx

ARR 验收/落库：

• arr_ingestion/contracts.py
• arr_ingestion/validation.py
• arr_ingestion/service.py
• arr_ingestion/postgres.py
• database/008_arr_mvp_v1_rebuild.sql

预订行解析合同：

• database/contracts/booking-row-parse-result.schema.json
• booking_ingestion/

不要在 Agent Prompt、数据库 repository、看板或报表程序复制第二套白名单、定价、去重或渠道识别规则。

3. 日报 structured-result 入库字段

每个 source record 保存：

• 血缘：source_sequence、source_location、可选 worksheet/row；
• 处理：outcome、decision_codes、duplicate_of_source_sequence；
• 日报业务字段：BLOCK_CODE、ADULTS、CHILDREN、COMPANY_NAME、CONFIRMATION_NO、DISP_ROOM_NO、EFFECTIVE_RATE_AMOUNT、FULL_NAME、RES_COMMENT、TRACE_TEXT、NO_OF_ROOMS、PRODUCTS、RATE_CODE、ROOM_CATEGORY_LABEL、ARRIVAL、DEPARTURE、NIGHTS、REAL PRICE、TOTAL PRICE；
• 规范化/定价：company_key、group_code_key、normalized_rate_code、kb_amount、channel_key、pricing_method；
• 预订查询结果：booking_source_match_status 和 booking_source_match_count。

outcome 只能是：

• retained
• excluded_rate_code
• duplicate
• validation_failed
• price_unmatched

全部 outcome 都落 finance.daily_records。只有 current 日版本中的 retained 进入 finance.v_active_daily_facts 和业务报表。

固定公式：

TOTAL PRICE = REAL PRICE × NO_OF_ROOMS × NIGHTS

例如 1800 × 2 × 3 = 10800。ARR 入库前重算，PostgreSQL check constraint 再验证。渠道明细的 Total Booking Price 直接使用这一个日报行的 total_price。

4. 预订数据职责

预订原表/MD 最低字段：

• GROUP_CODE
• TYPE OF ROOM
• NO_OF_ROOMS
• 来源 worksheet/row

Agent 可把一条组合文本拆成多个 room item，例如：

G1 | (【U-TWN12】1,【U-DBL12】2) | 3

数据库必须同时保留：

• 原始一行 type_of_room_raw 和总房数 3；
• 一个行级完整 result_json；
• 两个 room items：U-TWN × 1、U-DBL × 2。

来源行不能按 Group Code 合并。同一 Group Code 多行在查询时聚合，原行仍可追溯。

Finance 与预订的唯一关联：

upper(trim(XML.RES_COMMENT)) = booking.group_code_key

预订只提供 Booking Room；住宿日期、晚数、实际房数和价格使用 Finance 日报事实。

5. 月报与渠道明细

月报 20 列来自 finance.v_monthly_report_rows/monthly_reports：

ARRIVAL, DEPARTURE, NIGHTS, ADULTS, CHILDREN, BLOCK_CODE,
NO_OF_ROOMS, COMPANY_NAME, CONFIRMATION_NO, DISP_ROOM_NO,
RATE_AMOUNT, FULL_NAME, RES_COMMENT, TRACE_TEXT, PRODUCTS,
RATE_CODE, ROOM_CATEGORY, Real Price, Booking Room, TOTAL PRICE

其中：

• RATE_AMOUNT = effective_rate_amount
• ROOM_CATEGORY = room_category_label
• Booking Room 来自预订 Group Code 查询
• TOTAL PRICE 直接来自日报

渠道明细来自 finance.v_channel_details，字段包括 ARRIVAL、DEPARTURE、NIGHTS、BLOCK_CODE、RES_COMMENT、Booking Room、Total Booking Price。它不是同 Group Code 汇总表。

公司 10 日表由 company_reports 读取 Finance 日期/金额与 Booking Room，再按程序规则生成文件。数据库不保存这些派生行。

6. 数据库位置与查询

• 目标：<ARR_DB_HOST>:5432/booking_test（远程测试库）
• 本机受控配置：/path/to/private/booking-test-db.env
• 旧 <LEGACY_DB_HOST>:5433/booking_test 和 booking-test-lan-db.env 只作临时回退，不再接收新写入

应用 DSN 环境变量：

• ARR_DATABASE_URL
• MONTHLY_REPORT_DATABASE_URL（可回退 ARR）
• COMPANY_REPORT_DATABASE_URL（可回退 ARR）
• DASHBOARD_DATABASE_URL（可回退 ARR）

常用只读入口：

• booking.v_group_booking_rooms
• finance.v_active_daily_facts
• finance.v_monthly_report_rows
• finance.v_channel_details
• finance.v_company_report_source
• finance.v_daily_processing_audit

7. 当前测试数据

预订 fixture：867 条来源行，348 个 Group Code；没有合并重复行。

Finance fixture：2026-07-27 三条合成 source record，retained/duplicate/excluded 各一条。正式业务视图只有一条 retained；LT260720GAA 查询得到 DBL × 1，日报总价 5400。

这些只用于验证流程，不能当真实业务底数。

8. 给数据处理对话的提示词

请先完整读取 DATA_PROCESSING_HANDOFF.md、
DATABASE_CONVERSATION_HANDOFF.md 和日报 Skill 的 SKILL.md/契约文件。

日报 Skill 只生成日报、result.json、structured-result.json；月报、渠道明细和公司 10 日表由普通程序查询 PostgreSQL 生成。
测试库是 <ARR_DB_HOST>:5432/booking_test，受控配置为
/path/to/private/booking-test-db.env。

只读查询使用 booking/finance 视图。Agent 不得直接写库；structured-result 必须由 ARR 后端经
arr_ingestion 独立验收后事务落库。不要输出数据库密码、OSS 凭据或真实住客字段。

9. 生产缺口

数据库/程序读路径已验收；真实生产仍缺最小权限账号、正式私有 OSS provider、SuperAgent 文件获取与回调验签，以及生产级共享幂等/恢复演练。