酒店 SaaS 报表服务架构设计文档

本文档记录了酒店 SaaS 系统下报表服务的架构设计讨论过程，包含技术选型、数据流转、架构图等完整方案。

一、讨论背景

在酒店 SaaS 系统背景下，需要设计一个报表服务，覆盖运营报表、财务报表和管理看板三类场景。本文档通过多轮讨论，确定了完整的技术选型和服务数据流转架构。

二、架构决策讨论过程

问题 1：报表服务的业务定位与边界

在酒店 SaaS 系统中，“报表服务”可以覆盖很广的范围。常见定位有以下几种：

决策：覆盖 A 运营报表 + B 财务报表 + C 管理看板。D（合规导出）可作为独立的导出模块挂在报表服务之下。

问题 2：数据源 —— 报表服务从哪些系统取数？

现有系统状况：

• 已有 SaaS 系统，数据库是 MySQL
• 分布式微服务架构
• 多租户，数据隔离主要靠逻辑租户 ID（tenant_id）
• 部分表已做分表处理

决策：报表服务从现有 MySQL 微服务取数，核心数据源为 PMS（物业管理系统）+ 账务系统，BI 看板还可能需要 CRM 数据。

问题 3：数据接入策略 —— 报表服务如何从业务 MySQL 获取数据？

可选方案对比：

决策：方案 C（CDC + 流式同步）。直查会拖垮生产，批量 ETL 既有压力又延迟大，事件驱动改造成本太高。

问题 4：消息中间件现状 —— 是否已有 Kafka？

现有系统暂无消息中间件（如 Kafka/RocketMQ）。

讨论了 Flink CDC 是否必须依赖 MQ 中间件：

Flink CDC 直连方案的优势

1. 无需引入 Kafka：对”暂无中间件”的情况，直接省掉一整个组件层
2. 一站式计算：Flink CDC 不只是搬运数据，还能在流上做聚合、维度关联、多表合并——对报表服务非常关键
3. YAML 作业定义（Flink SQL CDC）：写几行 SQL 就能完成”读 MySQL binlog → 转换 → 写入 OLAP”
4. Exactly-Once 语义：保证报表数据的精确性

加 Kafka 的潜在优势

1. 多消费者复用
2. 故障缓冲（OLAP 宕机时不丢数据）
3. 重算/回溯能力
4. 解耦

决策：第一阶段先用 Flink CDC 直连方案上线，架构上预留 Kafka 接入点。当第二个消费者出现时，再引入 Kafka。暂不引入 Kafka。

问题 5：OLAP 存储层选型

核心候选：

决策：Apache Doris。

问题 6：Doris 表模型选型 —— 三类报表需要不同的表模型

Doris 有三种核心表模型：

决策：分层建模 ODS→DWD→DWS→ADS，Doris 分区策略为时间分区 + tenant_id 分桶。

1
Flink CDC →  ODS层（Duplicate明细模型，全量原始数据）
2
                ↓
3
          DWD层（Unique模型，订单/账务等可变数据按主键upsert）
4
                ↓
5
          DWS层（Aggregate模型，按租户+日期+门店维度预聚合）
6
                ↓
7
          ADS层（应用层，直接对接报表查询）

问题 7：报表服务的 API 层架构 —— 如何对接前端？

7a：报表服务技术栈

决策：沿用现有微服务技术栈 Spring Boot 3.5 + JDK 21。

7b：报表查询模式 —— 三类报表需要不同的服务能力

决策：双路径设计 + 引入 Redis 缓存。

1
┌─→ 同步查询路径 ──→ Doris DWS/ADS ──→ 返回JSON
2
前端请求 → 报表服务API ──┤
3
                        └─→ 异步任务路径 ──→ 任务队列 ──→ 生成报表文件(PDF/Excel) ──→ 下载

• Redis 缓存热点看板结果（TTL 5分钟），兼做异步任务状态存储。

问题 8：分层之间的转换在哪里做？—— Flink 还是 Doris？

决策：方案 C（混合）。

• Flink 做 ODS→DWD 实时转换（分表合并、字段清洗、upsert）
• Spring Boot @Scheduled 定时触发 Doris SQL 做 DWD→DWS 聚合

问题 9：异步报表生成机制 + 文件存储

9a：异步任务触发方式（无 Kafka 的替代方案）

决策：方案 C（Redis Stream + Redisson）。

9b：文件存储位置

决策：使用现有云 OSS。

问题 10：报表定义模型 —— 硬编码还是元数据驱动？

决策：方案 C（半元数据驱动），并需要可视化报表配置管理后台。

元数据驱动的核心数据模型

1
report_definition（报表定义表）
2
├── id, tenant_id, report_name, report_type(A/B/C)
3
├── data_source（指向哪个Doris表/视图）
4
├── query_template（SQL模板，带变量占位符如 ${date_range}）
5
├── dimensions（维度JSON：门店、日期、渠道...）
6
├── metrics（指标JSON：入住率、RevPAR、营收...）
7
├── chart_type（柱图/折线/表格/饼图）
8
├── cache_ttl（缓存时长，秒）
9
└── is_async（是否异步生成文件）

问题 11：报表权限模型 —— 多租户 + 角色的访问控制

访问者角色

权限模型设计

1
请求 → 网关(解析JWT, 获取user_id + tenant_id + role)
2
     → 报表服务
3
         → 校验: 用户是否有权限访问该报表(report_id)?
4
         → 校验: 用户的tenant_id 是否匹配?
5
         → 校验: 用户的门店权限范围(store_ids)?
6
         → 拼SQL时强制注入 tenant_id + store_id 过滤条件
7
         → 查 Doris

决策：

1. 跨租户场景存在（集团总部管多个酒店租户），需高权限角色
2. 权限复用现有用户体系，暂不展开设计
3. SQL 模板强制注入 tenant_id 过滤防数据泄漏

关键安全约束

• SQL 模板引擎必须防注入：用户输入的参数必须走参数化查询
• Doris 查询日志：记录谁查了什么报表，满足财务审计需求
• 租户级数据行数校验：定期跑校验作业，对比 Doris 和 MySQL 的 tenant_id 数据行数

问题 12：Flink 集群部署方式

决策：

• 部署方式：方案 D（Standalone + SQL Gateway）
• 作业开发：Java DataStream API（非 SQL）

三、架构决策汇总

四、架构图

五、数据流转详解

流转 1：实时数据同步链路

1
MySQL binlog → Flink CDC (Java DataStream)
2
  → 分表合并(UNION) + 字段清洗 + tenant_id 透传
3
  → 写入 Doris ODS 层 (Duplicate模型，全量保留)
4
  → 同时写入 Doris DWD 层 (Unique模型，主键upsert保证最新状态)

流转 2：定时聚合链路

1
Spring Boot @Scheduled 定时触发
2
  → 执行 Doris SQL: INSERT INTO DWS SELECT ... FROM DWD GROUP BY tenant_id, date, store_id
3
  → DWS 层预聚合结果
4
  → 物化视图 / ADS 层

流转 3：同步报表查询链路

1
前端请求(带 tenant_id + role + store_ids)
2
  → 网关校验权限
3
  → 报表API读取报表配置(半元数据驱动)
4
  → 拼SQL模板，强制注入 tenant_id + store_id 过滤
5
  → 先查 Redis 缓存
6
  → 缓存未命中 → 查 Doris DWS/ADS
7
  → 写回缓存(TTL 5min)
8
  → 返回 JSON 给前端渲染

流转 4：异步报表生成链路

1
前端请求(大数据量报表/导出)
2
  → 报表API 创建异步任务 → 写入 Redis Stream
3
  → Redisson 消费者拉取任务
4
  → 查 Doris DWD/DWS 拿明细数据
5
  → 生成 Excel/PDF 文件
6
  → 上传到 云OSS
7
  → 更新任务状态(完成) → Redis 记录文件URL
8
  → 前端轮询任务状态 → 获取下载链接

流转 5：跨租户看板链路（集团总部）

1
集团总部用户(高权限角色)
2
  → 网关识别集团管理员角色
3
  → 报表API 跳过 tenant_id 过滤(或注入多租户ID列表)
4
  → 查 Doris DWS 跨租户聚合数据
5
  → 返回多租户对比看板

六、技术栈总览

七、Doris 建模设计

分区与分桶策略

• 分区：按时间（日/月）
• 分桶：按 tenant_id，租户级查询只扫描对应桶，性能好且天然隔离

八、报表定义模型

元数据驱动核心表结构

1
report_definition（报表定义表）
2
├── id, tenant_id, report_name, report_type(A/B/C)
3
├── data_source（指向哪个Doris表/视图）
4
├── query_template（SQL模板，带变量占位符如 ${date_range}）
5
├── dimensions（维度JSON：门店、日期、渠道...）
6
├── metrics（指标JSON：入住率、RevPAR、营收...）
7
├── chart_type（柱图/折线/表格/饼图）
8
├── cache_ttl（缓存时长，秒）
9
└── is_async（是否异步生成文件）

半元数据驱动策略

• 常用报表：硬编码（性能好、定制强）
• 自定义报表：走 DB 配置（report_definition 表），运营人员通过配置后台可视化管理

九、安全与权限设计

权限模型

• 复用现有用户权限体系（JWT + tenant_id + role）
• 报表定义表加 visible_roles 字段，标注哪些角色可见
• 门店范围：用户表有 managed_store_ids，查 Doris 时作为额外过滤条件
• 跨租户场景：集团总部高权限角色，能跨 tenant_id 查询

安全约束

1. SQL 模板引擎必须防注入：用户输入的参数（日期范围、门店 ID）必须走参数化查询
2. Doris 查询日志：记录谁查了什么报表，满足财务审计需求
3. 租户级数据行数校验：定期跑校验作业，对比 Doris 和 MySQL 的 tenant_id 数据行