# ARR 数据持久化实施方案（MVP v1）

更新时间：2026-07-28  
状态：已执行；当前事实以 `database/008_arr_mvp_v1_rebuild.sql` 和 `database/APPLIED_MIGRATIONS.md` 为准。

## 1. 目标

让以下数据可以安全、幂等、可追溯地落入 PostgreSQL，并支撑普通程序生成后续报表：

- 预订附件/MD 的 Group Code、Type of Room、No. of Rooms、来源 worksheet/row；
- 预订 Agent 的完整行级结构化输出和可查询 room items；
- Opera 日报 structured-result 中全部 source records/outcome；
- 日报不可变版本、同日 current 指针和渠道指标；
- 月报、渠道明细、渠道 BI 和每 10 日公司报表所需的只读投影。

## 2. 权威边界

- Skill 决定过滤、去重、公司识别、定价和结构化结果。
- ARR 后端重新校验工件哈希、JSON Schema、计数、duplicate lineage、日期/晚数和总价公式。
- PostgreSQL 只接受 ARR 验收结果，并用 FK、唯一键、check 和触发器防止坏状态。
- 普通报表程序只读 PostgreSQL，不回读 XML 推导另一套事实。

## 3. 写入事务

### Opera 日报成功

1. 注册/锁定 processing run 与 attempt；
2. 验证同一 delivery key 和 envelope hash 的幂等性；
3. 登记源 XML、日报、result JSON、structured-result JSON 工件；
4. 写入不可变 daily version；
5. 写入全部 outcome records 和 duplicate lineage；
6. 精确查询 booking Group Code 命中数；
7. 写入渠道顺序和行数；
8. 将旧版本标记 superseded，并把新版本标记 active；
9. 最后切换 `current_daily_versions`；
10. 写 delivery/outbox 并提交。

任一步失败都回滚整个事务。可判定业务失败保存 rejected 审计，但不切 current。

### 预订来源导入

1. 登记源工件和 source batch；
2. 逐行写 source row，不按 Group Code 合并；
3. 保存 Agent 行级 JSON 与解析版本；
4. 写一个或多个 room items；
5. 验证 room item 数量合计等于来源行 No. of Rooms；
6. 切换该来源行 current parse；
7. 复核行数、worksheet 数和 Group Code 基线后提交。

## 4. 幂等和并发

- 工件以 kind + SHA-256 和对象存储身份去重。
- run key、attempt idempotency key、delivery key 和 envelope hash 都有唯一约束。
- 同 source/date/processor/rule 复用既有版本；同日新源创建下一不可变版本。
- 写事务使用 SERIALIZABLE、业务范围 advisory lock、lock/statement timeout 和有限瞬态重试。
- 只有完整新版本成功后才切 current，因此业务查询不会看到半成品。

## 5. 查询模型

- 月报：`finance.v_monthly_report_rows` 或 `monthly_reports` repository。
- 渠道明细：`finance.v_channel_details`。
- 渠道 BI：`channel_analytics` 对 current facts 和 daily channel metrics 聚合。
- 公司 10 日表：`finance.v_company_report_source` 或 `company_reports` repository。
- Booking Room：`booking.v_group_booking_rooms`。
- 处理追溯：`finance.v_daily_processing_audit`。

业务查询不得直接把全部 `daily_records` 当正式数据；必须使用 current + retained 视图。

## 6. 数据与报表生命周期

- PostgreSQL 长期保存已验收的事实和审计版本。
- OSS 保存原始/输出工件；数据库只保存 identity 和 lineage。
- 月报/渠道/公司报表文件由程序生成，可在 OSS/受控目录保留，但不重复保存其行数据。
- 本轮没有自动清理策略。生产保留期、归档和删除策略须另行确认。

## 7. 已完成验收

- 008 真实数据库整事务回滚探针；
- 重建前完整逻辑备份和 manifest 校验；
- MD 867 行、348 Group Code、122 个重复 Group Code 的不合并导入；
- structured-result 的 retained/duplicate/excluded 落库；
- 固定总价公式和 non-retained 隔离；
- 幂等复跑、SERIALIZABLE retry、current 切换和失败不泄漏；
- 月报、渠道、公司、BI 与 Web read paths 的真实只读验收；
- 自动化测试通过。

## 8. 后续实施顺序

1. 创建最小权限 writer/reader 角色；
2. 接正式私有 OSS 和 Secret；
3. 接真实 SuperAgent 文件与回调协议；
4. 用非隐私/脱敏数据做端到端预生产验收；
5. 明确生产地址、备份恢复和数据保留策略后上线。