13 KiB

Raw Blame History

后台配置 SQL 驱动的经营分析方案

1. 目标

本方案满足你明确提出的目标：

统计定义在后台管理配置
H5 端直接按配置展示
取数 SQL 也可以在后台管理配置
后续口径变化时，尽量不改前端代码
同时兼顾 PC 端与 H5 / 企业微信端

这套方案的核心思想是：

前端不写死报表
后台管理端维护报表定义
后端读取配置 SQL 执行
H5 / PC 统一走配置渲染

2. 结论先说

这个方案是可行的，但建议不要做“完全无限制的任意 SQL 执行”，而要做：

后台可配置 SQL
后端受控执行 SQL
带参数模板
带权限注入
带版本管理
带审核发布

也就是说，不是直接把数据库裸露给后台管理员，而是做一个“可配置 SQL 报表平台”。

3. 适合你的整体架构

建议拆成 4 个部分：

3.1 报表定义后台

给管理员使用，用于配置：

报表名称
适用端
筛选条件
图表类型
指标字段
维度字段
SQL 模板
参数说明
发布版本

3.2 报表执行引擎

后端新增一个报表引擎服务，职责是：

读取报表配置
校验参数
替换 SQL 模板变量
自动追加权限条件
执行 SQL
返回统一结果结构

3.3 H5 / PC 动态渲染层

前端不再写死每个图表，而是：

先请求报表页面配置
再请求每个组件的数据
根据配置渲染 KPI、柱状图、折线图、饼图、表格

3.4 配置治理层

用于保证 SQL 配置安全可控：

草稿/已发布版本
审核流
执行日志
回滚版本
性能限制

4. 最推荐的实现模式

你要的是“SQL 可配置”，这里推荐两个级别。

4.1 级别一：SQL 模板可配置

这是最推荐的。

后台配置的不是完全自由 SQL，而是带占位符的模板 SQL，例如：

select
  owner_user_id as ownerUserId,
  sum(amount) as actualAmount
from crm_opportunity
where status = 'won'
  and won_at between ${startDate} and ${endDate}
  ${dataScopeClause}
  ${orgFilterClause}
group by owner_user_id
order by actualAmount desc

特点：

可配灵活
后端可控
容易注入权限
易于参数校验

4.2 级别二：完全自由 SQL

不建议默认开放。

如果一定要支持，也建议：

仅超级管理员可用
仅允许 select
禁止 update/delete/insert/drop
禁止多语句
禁止访问敏感表
强制走只读数据源
强制超时和行数限制

5. 业务上如何满足“销售完成业绩”和“区域业绩”

这两个场景很适合做成后台配置化报表。

5.1 销售完成业绩

建议报表结构：

KPI：
- 销售目标
- 实际完成
- 完成率
- 同比/环比
图表：
- 销售排行
- 趋势图
- 部门分布
明细：
- 销售员、目标值、完成值、完成率、区域、趋势

5.2 区域业绩

建议报表结构：

KPI：
- 区域目标
- 区域实际
- 区域完成率
图表：
- 区域排名
- 区域趋势
- 区域构成
明细：
- 大区、省区、城市、销售数、目标、实际、完成率

这两类都可以通过后台 SQL 配置实现。

6. 推荐的数据模型

建议新增以下表。

6.1 `analytics_report`

存报表主定义。

建议字段：

id
report_code
report_name
report_category
description
status
terminal_scope
default_time_granularity
visible
created_by
updated_by
created_at
updated_at

说明：

terminal_scope 用于区分 pc / h5 / both

6.2 `analytics_report_version`

存报表版本。

建议字段：

id
report_id
version_no
version_status
change_log
published_by
published_at
config_json
created_at

说明：

一个报表允许多个版本
H5 默认读已发布版本

6.3 `analytics_widget`

存一个报表下的组件定义。

建议字段：

id
report_version_id
widget_code
widget_name
widget_type
title
subtitle
layout_json
props_json
data_source_id
sort_order
visible

6.4 `analytics_data_source`

存数据源定义，也就是 SQL 配置核心。

建议字段：

id
source_code
source_name
source_type
dataset_code
query_sql
count_sql
parameter_schema_json
result_schema_json
timeout_ms
max_rows
cache_ttl_seconds
enabled
created_at
updated_at

6.5 `analytics_filter_def`

存筛选器定义。

建议字段：

id
report_version_id
filter_code
filter_name
filter_type
data_type
default_value_json
options_source_type
options_source_config
sort_order
visible

6.6 `analytics_sql_publish_log`

存 SQL 发布日志。

建议字段：

id
data_source_id
version_no
old_sql
new_sql
change_summary
operator_id
created_at

6.7 `analytics_query_log`

存执行日志。

建议字段：

id
report_code
widget_code
data_source_id
request_user_id
request_params_json
final_sql_preview
duration_ms
row_count
success
error_message
created_at

7. 配置中心怎么设计

后台建议做成 5 个页面。

7.1 报表管理

配置：

报表基本信息
展示端
菜单归属
是否发布

7.2 页面布局管理

配置：

KPI 卡片
图表组件
表格组件
H5 是否显示
PC 是否显示
顺序与显隐

7.3 SQL 数据源管理

配置：

SQL 模板
参数定义
字段映射
结果预览
缓存策略
执行限制

7.4 筛选器管理

配置：

时间筛选
区域筛选
销售筛选
部门筛选
自定义枚举

7.5 发布与回滚

配置：

草稿
预览
发布
回滚历史版本

8. SQL 配置方式建议

这是关键设计点。

8.1 SQL 模板结构

建议使用模板 SQL，不要直接存“拼好的最终 SQL”。

示例：

select
  region_code as regionCode,
  region_name as regionName,
  sum(actual_amount) as actualAmount,
  sum(target_amount) as targetAmount,
  case when sum(target_amount) = 0 then 0
       else round(sum(actual_amount) / sum(target_amount) * 100, 2)
  end as completionRate
from analytics_sales_performance_fact
where stat_date between ${startDate} and ${endDate}
  ${orgFilterClause}
  ${regionFilterClause}
  ${salesFilterClause}
  ${dataScopeClause}
group by region_code, region_name
order by actualAmount desc
limit ${limit}

8.2 参数定义

每条 SQL 必须配参数定义。

示例：

[
  { "name": "startDate", "type": "date", "required": true },
  { "name": "endDate", "type": "date", "required": true },
  { "name": "orgId", "type": "long", "required": false },
  { "name": "regionCode", "type": "string", "required": false },
  { "name": "salesUserId", "type": "long", "required": false },
  { "name": "limit", "type": "int", "required": false, "defaultValue": 50 }
]

8.3 建议支持的占位符

后端统一支持如下占位符：

${startDate}
${endDate}
${limit}
${offset}
${dataScopeClause}
${orgFilterClause}
${regionFilterClause}
${salesFilterClause}

8.4 动态条件注入方式

例如 regionCode 为空时，不拼条件；有值时自动生成：

and region_code = :regionCode

不建议把这种逻辑写死在前端。

9. 前端展示怎么实现

虽然 SQL 在后台配置，但前端还是要有统一协议。

9.1 H5 与 PC 共用配置协议

前端请求：

页面定义
筛选器定义
Widget 定义
Widget 数据

支持以下组件：

kpi
line
bar
stack-bar
pie
table
rank-list

9.3 H5 展示规则

建议在配置里加上：

showOnPc
showOnH5
h5SortOrder
pcSortOrder
h5ChartType
pcChartType

这样同一个报表可以：

PC 显示表格 + 图表
H5 只显示 KPI + Top10

9.4 H5 页面渲染流程

获取报表定义
获取筛选项定义
渲染页面骨架
请求组件数据
渲染图表

10. 后端执行引擎设计

建议新增一个 AnalyticsQueryService。

职责：

加载已发布报表版本
解析筛选条件
校验参数类型
生成最终 SQL
注入权限条件
执行查询
做缓存
记录日志

10.1 执行流程

读取报表配置
读取组件配置
读取数据源 SQL 模板
根据请求参数构造过滤条件
自动注入数据权限
生成最终 SQL
执行查询
转成统一结果结构

10.2 统一返回结构

建议：

{
  "reportCode": "sales-performance",
  "title": "销售完成业绩",
  "filters": [],
  "widgets": [
    {
      "widgetCode": "sales-rank",
      "widgetType": "bar",
      "title": "销售业绩排名",
      "columns": ["ownerName", "actualAmount"],
      "rows": []
    }
  ]
}

11. 权限与安全控制

这是这个方案能不能上线的关键。

11.1 禁止直接执行危险 SQL

必须限制：

只允许 select
禁止 insert
禁止 update
禁止 delete
禁止 drop
禁止 alter
禁止多语句执行

11.2 必须强制数据权限注入

即使后台配置 SQL，也不能信任配置人手动写权限条件。

必须由后端统一追加：

当前租户过滤
当前用户数据范围
组织权限范围

11.3 建议使用只读数据源

报表执行引擎单独使用只读数据库账号。

11.4 超时与数据量限制

每条数据源定义都要支持：

最大执行时长
最大返回行数
最大导出行数

11.5 SQL 审核

建议发布前做 SQL 检查：

关键词校验
表白名单校验
字段白名单校验
explain 成本校验

12. 针对“销售完成业绩”和“区域业绩”的配置方式

12.1 销售完成业绩推荐做法

建议先沉淀一个业绩事实层表或视图：

analytics_sales_performance_fact

字段建议：

stat_date
sales_user_id
sales_user_name
org_id
org_name
region_code
region_name
target_amount
actual_amount
won_amount
contract_amount
payment_amount
adjust_amount

好处：

前端怎么展示都行
后台 SQL 简单很多
口径变更时只改事实层生成逻辑或切换版本

12.2 区域业绩推荐做法

建议同样通过事实层统一：

客户区域
项目区域
销售归属区域

如果口径会改，可以做多个字段：

customer_region_code
project_region_code
owner_region_code

后台 SQL 通过配置选择用哪个字段聚合。

13. 推荐的“SQL 可配置”分层

为了避免后期越来越乱，建议把 SQL 分成两层。

13.1 第一层：事实层 SQL

由研发维护。

职责：

把复杂业务逻辑沉淀成事实表或视图
处理复杂口径、去重、归属、调整项

13.2 第二层：展示层 SQL

由后台管理配置。

职责：

从事实层表/视图做汇总
做 KPI、排行、趋势、区域分组

这是最适合你的方案。

原因：

真正复杂的口径不适合完全交给后台人员写
但展示层统计完全可以后台配置
H5 端可以完全动态渲染

14. 如果你坚持“所有 SQL 都后台可配”

也可以做，但我建议加 3 个保护措施。

14.1 只允许访问白名单对象

例如只允许查：

analytics_*
crm_*
work_*
部分 sys_* 维表

14.2 强制 SQL 发布审核

流程建议：

编辑草稿
测试预览
提交审核
审核通过后发布

14.3 强制版本切换

H5 / PC 永远只读“已发布版本”，不读草稿。

15. API 设计建议

15.1 后台管理端

GET /api/admin/analytics/reports
POST /api/admin/analytics/reports
PUT /api/admin/analytics/reports/{id}
GET /api/admin/analytics/reports/{id}/versions
POST /api/admin/analytics/data-sources
PUT /api/admin/analytics/data-sources/{id}
POST /api/admin/analytics/data-sources/{id}/preview
POST /api/admin/analytics/reports/{id}/publish

15.2 前台 H5 / PC

GET /api/analytics/reports/{reportCode}
POST /api/analytics/reports/{reportCode}/query

16. 实施步骤建议

第一阶段

目标：

先把基础平台搭起来

内容：

报表定义表
数据源定义表
Widget 定义表
H5 动态渲染页
PC 动态渲染页
SQL 安全校验

第二阶段

目标：

上线销售完成业绩、区域业绩

内容：

销售业绩事实表
区域业绩事实表
报表管理页
SQL 配置预览
发布与回滚

第三阶段

目标：

真正进入“后台可运营”

内容：

版本对比
审核流
执行监控
性能报警
缓存策略

17. 最终建议

如果你想实现：

后台管理定义
H5 自动展示
SQL 可配置
后期口径频繁修改

那么我最推荐的是：

做一个 报表定义 + SQL 数据源 + Widget 配置 的后台管理平台
H5 与 PC 统一走动态渲染
SQL 采用“模板化 + 参数化 + 权限注入 + 发布审核”
真正复杂的业绩口径优先沉淀为事实层视图或事实表
展示层 SQL 再交给后台配置

一句话总结：

这个方案完全可以做，而且很适合你当前“口径复杂、变化频繁、H5要快速展示”的场景；但最佳实践不是裸放任意 SQL，而是做受控的后台 SQL 配置平台。

13 KiB Raw Blame History Unescape Escape

后台配置 SQL 驱动的经营分析方案

1. 目标

2. 结论先说

3. 适合你的整体架构

3.1 报表定义后台

3.2 报表执行引擎

3.3 H5 / PC 动态渲染层

3.4 配置治理层

4. 最推荐的实现模式

4.1 级别一：SQL 模板可配置

4.2 级别二：完全自由 SQL

5. 业务上如何满足“销售完成业绩”和“区域业绩”

5.1 销售完成业绩

5.2 区域业绩

6. 推荐的数据模型

6.1 analytics_report

6.2 analytics_report_version

6.3 analytics_widget

6.4 analytics_data_source

6.5 analytics_filter_def

6.6 analytics_sql_publish_log

6.7 analytics_query_log

7. 配置中心怎么设计

7.1 报表管理

7.2 页面布局管理

7.3 SQL 数据源管理

7.4 筛选器管理

7.5 发布与回滚

8. SQL 配置方式建议

8.1 SQL 模板结构

8.2 参数定义

8.3 建议支持的占位符

8.4 动态条件注入方式

9. 前端展示怎么实现

9.1 H5 与 PC 共用配置协议

9.2 Widget 类型建议

9.3 H5 展示规则

9.4 H5 页面渲染流程

10. 后端执行引擎设计

10.1 执行流程

10.2 统一返回结构

11. 权限与安全控制

11.1 禁止直接执行危险 SQL

11.2 必须强制数据权限注入

11.3 建议使用只读数据源

11.4 超时与数据量限制

11.5 SQL 审核

12. 针对“销售完成业绩”和“区域业绩”的配置方式

12.1 销售完成业绩推荐做法

12.2 区域业绩推荐做法

13. 推荐的“SQL 可配置”分层

13.1 第一层：事实层 SQL

13.2 第二层：展示层 SQL

14. 如果你坚持“所有 SQL 都后台可配”

14.1 只允许访问白名单对象

14.2 强制 SQL 发布审核

14.3 强制版本切换

15. API 设计建议

15.1 后台管理端

15.2 前台 H5 / PC

16. 实施步骤建议

第一阶段

第二阶段

第三阶段

17. 最终建议

13 KiB

Raw Blame History

6.1 `analytics_report`

6.2 `analytics_report_version`

6.3 `analytics_widget`

6.4 `analytics_data_source`

6.5 `analytics_filter_def`

6.6 `analytics_sql_publish_log`

6.7 `analytics_query_log`