feat: prepare ARR for controlled public deployment

DATABASE_PERSISTENCE_PLAN.md

@@ -0,0 +1,93 @@
+# 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. 明确生产地址、备份恢复和数据保留策略后上线。