# ARR1 历史文档 — ARR 数据处理与数据库交接

> 当前行为请以 ARR2.0 根目录 README、ADR-004 和 current-state 项目记忆为准。

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

## 1. 最终处理链

```text
用户上传 Opera XML
  → ARR 存入 OSS，仅将 committed 源 XML 设为 public-read
  → ARR 在 PROGRAM_INPUT v3 写入无签名公网 HTTPS URL
  → SuperAgent 用 fetch_oss_file 原样获取 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` 和业务报表。

固定公式：

```text
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，例如：

```text
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 与预订的唯一关联：

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

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

## 5. 月报与渠道明细

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

```text
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. 给数据处理对话的提示词

```text
请先完整读取 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. 生产缺口

数据库/程序读路径已验收；真实生产仍缺最小权限账号、public-read 源 XML 的保留期/访问日志控制、SuperAgent `.xml`/`application/xml` 获取验收与回调验签，以及生产级共享幂等/恢复演练。`fetch_oss_file` 使用 ARR 生成的公网 URL，不配置 OSS Provider；暂存与处理输出对象仍为 private。