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