wyndham-ARR/DATABASE_CONVERSATION_HANDOFF.md

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 查原始预订房型汇总：

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'));

查月报数据源：

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;

查渠道明细：

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 日表源：

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：

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。正确入口：

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. 可复制到另一个对话

这是 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 并做恢复演练；不能默认“地址不变、清空测试数据”就等于生产上线。