# ARR 数据库专项对话交接

更新时间：2026-07-28  
用途：让其他 Codex 对话安全接手当前数据库、查询数据或继续后端接线。  
安全：本文不包含数据库密码、OSS 凭据或真实住客行值。

## 1. 当前已完成状态

远程测试 PostgreSQL 已完成 ARR 数据落库 MVP v1，并已从旧 LAN 测试库完整迁移及复验：

- 主机/端口：`<ARR_DB_HOST>:5432`
- 数据库：`booking_test`
- 当前测试用户：`<TEST_DB_OWNER>`（数据库 owner、非超级用户；仍不是生产最小权限应用账号）
- 当前受控配置：`/path/to/private/booking-test-db.env`，权限 `0600`
- schema：`ingestion`、`booking`、`finance`
- 当前迁移：`008_arr_mvp_v1_rebuild.sql`

旧 LAN 源库 `<LEGACY_DB_HOST>:5433/booking_test` 未修改、未删除，只作为临时回退；对应配置是 `/path/to/private/booking-test-lan-db.env`。后续应用和查询默认使用远程配置，不要误用旧配置写入新数据。

当前数据：

- 预订 MD：867 条来源行、348 个不同 Group Code、122 个重复 Group Code、867 个 current room items；
- Finance 合成日报：2026-07-27 共 3 条 source record，retained/duplicate/excluded 各 1；
- current 正式事实：1 行；月报、渠道明细、公司报表投影各 1 行；
- 样例 `LT260720GAA` 可查询到 `DBL × 1`；
- 总价样例：`1800 × 1 × 3 = 5400`。

## 2. 接手时按顺序读取

1. `DATABASE_CONVERSATION_HANDOFF.md`
2. `database/APPLIED_MIGRATIONS.md`
3. `database/REMOTE_MIGRATION_20260728.md`
4. `DATABASE_SCHEMA_DICTIONARY.md`
5. `DATABASE_ERD.md`
6. `DATABASE_PERSISTENCE_PLAN.md`
7. `database/008_arr_mvp_v1_rebuild.sql`
8. `.planning/arr_mvp_v1_database_rebuild/task_plan.md`（本机工作记录，不随仓库发布）
9. `.planning/arr_mvp_v1_database_rebuild/findings.md`（本机工作记录，不随仓库发布）
10. `.planning/arr_mvp_v1_database_rebuild/progress.md`（本机工作记录，不随仓库发布）

涉及日报处理时再读 `DATA_PROCESSING_HANDOFF.md`；涉及看板/API 时再读 `FRONTEND_HANDOFF.md`。

## 3. 已冻结的责任边界

- Agent/Skill 负责业务识别、过滤、去重、定价和结构化输出。
- ARR 后端负责重新校验并通过 `arr_ingestion` 单事务写库。
- Agent/SuperAgent 不得获得数据库账号，不得直接 DML。
- PostgreSQL 保存预订事实、全部日报 outcome、current 指针和工件血缘。
- 月报、渠道明细、渠道 BI 和公司 10 日表由普通程序查询数据库生成，不使用旧 `report_versions`。
- 预订只提供 Booking Room；Finance 提供日期、晚数、实际房数和金额。
- Group Code 关联只使用规范化 `RES_COMMENT`，不用 `BLOCK_CODE`。

## 4. 推荐只读查询

按 Group Code 查原始预订房型汇总：

```sql
SELECT group_code_key, booking_room, total_booking_rooms, source_row_count
FROM booking.v_group_booking_rooms
WHERE group_code_key = upper(btrim('LT260720GAA'));
```

查月报数据源：

```sql
SELECT *
FROM finance.v_monthly_report_rows
WHERE business_date BETWEEN DATE '2026-07-01' AND DATE '2026-07-31'
ORDER BY business_date, daily_record_id;
```

查渠道明细：

```sql
SELECT *
FROM finance.v_channel_details
WHERE business_date BETWEEN DATE '2026-07-01' AND DATE '2026-07-31'
ORDER BY business_date, daily_record_id;
```

查公司 10 日表源：

```sql
SELECT *
FROM finance.v_company_report_source
WHERE departure BETWEEN DATE '2026-07-01' AND DATE '2026-07-10'
ORDER BY departure, daily_record_id;
```

追溯全部 outcome：

```sql
SELECT business_date, source_sequence, outcome, decision_codes,
       duplicate_of_record_id, booking_source_match_status
FROM finance.v_daily_processing_audit
WHERE business_date = DATE '2026-07-27'
ORDER BY source_sequence;
```

普通业务查询优先使用这些视图；不要直接从 `daily_records` 忘记过滤 current/retained。

## 5. 应用连接方式

应用代码使用 DSN 环境变量，不把密码放进源码、Prompt、日志或浏览器：

- 写入：`ARR_DATABASE_URL`
- 看板：`DASHBOARD_DATABASE_URL`，缺省回退 `ARR_DATABASE_URL`
- 月报程序：`MONTHLY_REPORT_DATABASE_URL`，缺省回退 `ARR_DATABASE_URL`
- 公司报表：`COMPANY_REPORT_DATABASE_URL`，缺省回退 `ARR_DATABASE_URL`

当前本机测试可由后端安全读取 `booking-test-db.env` 并构造连接；前端 JavaScript 绝不能读取该文件。

## 6. 写入入口

日报 structured-result 不应由另一个 Agent 手写 SQL。正确入口：

```text
DeliveryEnvelope 1.0
  → arr_ingestion.validation.DeliveryValidator
  → arr_ingestion.service.IngestionService
  → arr_ingestion.postgres.PostgresIngestionRepository
```

预订行级结果使用：

- JSON Schema：`database/contracts/booking-row-parse-result.schema.json`
- fixture 导入器：`booking_ingestion/`

写入前必须确认连接的 `current_database()` 是 `booking_test`，并使用事务、幂等 key 和 hash 门禁。

## 7. 当前可恢复性

本次远程迁移前的权威完整备份位于：

`<PRIVATE_BACKUP_ROOT>/booking_test_pre_remote_migration_20260728T180747+0800`

manifest SHA-256：`db8ca84fed52123d10151b475aca31659be237c6e7d513484e4f25b1d9a89c4d`。旧 LAN 源库也保持原状，观察期内可作回退核对。

没有用户明确授权时，不执行恢复、清库、DROP、补跑 001–007 或重跑 008。

## 8. 可复制到另一个对话

```text
这是 ARR 项目的数据处理/数据库接线任务。请使用 planning-with-files，并先完整读取：
1. DATABASE_CONVERSATION_HANDOFF.md
2. database/APPLIED_MIGRATIONS.md
3. DATABASE_SCHEMA_DICTIONARY.md
4. DATABASE_ERD.md
5. DATA_PROCESSING_HANDOFF.md

目标测试库固定为 <ARR_DB_HOST>:5432/booking_test；本机受控配置是
/path/to/private/booking-test-db.env。
<LEGACY_DB_HOST>:5433/booking_test 及 booking-test-lan-db.env 仅作为临时回退，不要继续写入。

数据库 008 已执行并验收，不要重建或重导。查询请使用 booking/finance 只读视图；
写入 structured-result 必须走 arr_ingestion 的 ARR 后端重验与事务 repository，Agent 不直接写数据库。
不要输出密码、OSS 凭据或真实住客明细。
```

## 9. 生产说明

当前只是远程测试库。上线前必须单独确认生产环境、创建最小权限角色、接正式 OSS/Secret、清理合成 fixture 并做恢复演练；不能默认“地址不变、清空测试数据”就等于生产上线。