94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 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. 明确生产地址、备份恢复和数据保留策略后上线。
|