187 lines
6.8 KiB
Markdown
187 lines
6.8 KiB
Markdown
# 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。
|