feat: prepare ARR for controlled public deployment

DATABASE_CONVERSATION_HANDOFF.md

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