4.2 KiB
4.2 KiB
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 日报成功
- 注册/锁定 processing run 与 attempt；
- 验证同一 delivery key 和 envelope hash 的幂等性；
- 登记源 XML、日报、result JSON、structured-result JSON 工件；
- 写入不可变 daily version；
- 写入全部 outcome records 和 duplicate lineage；
- 精确查询 booking Group Code 命中数；
- 写入渠道顺序和行数；
- 将旧版本标记 superseded，并把新版本标记 active；
- 最后切换
current_daily_versions； - 写 delivery/outbox 并提交。
任一步失败都回滚整个事务。可判定业务失败保存 rejected 审计，但不切 current。
预订来源导入
- 登记源工件和 source batch；
- 逐行写 source row，不按 Group Code 合并；
- 保存 Agent 行级 JSON 与解析版本；
- 写一个或多个 room items；
- 验证 room item 数量合计等于来源行 No. of Rooms；
- 切换该来源行 current parse；
- 复核行数、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_reportsrepository。 - 渠道明细：
finance.v_channel_details。 - 渠道 BI：
channel_analytics对 current facts 和 daily channel metrics 聚合。 - 公司 10 日表：
finance.v_company_report_source或company_reportsrepository。 - 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. 后续实施顺序
- 创建最小权限 writer/reader 角色；
- 接正式私有 OSS 和 Secret；
- 接真实 SuperAgent 文件与回调协议；
- 用非隐私/脱敏数据做端到端预生产验收；
- 明确生产地址、备份恢复和数据保留策略后上线。