report-sql

本技能由老板亲授，定义 report-service 的 SQL 模板协议与变量规范。

Variables

report-service 变量遵循唯一、精确、零容错原则：

✅ 合法语法

#@option.where.<field>#

🔑 当前支持字段

⚠️ 严禁写法（运行时直接失败）

• #@name#, #name#, @name@ → 无命名空间；
• #@option.name#（缺 .where）→ 路径错误；
• s.name, b.status → 别名+字段，非变量；
• 变量内含空格、换行、注释 → 破坏字面匹配。

📌 拼接原则

变量只提供值，表别名由 FROM 子句决定：

• 若 FROM sale s → 写 s.name = #@option.where.name#；
• 若 FROM blog b → 写 b.title LIKE CONCAT('%', #@option.where.name#, '%')；
• 变量本身永远不带 s. 或 b. 前缀。

✅ 新增：${...} 块级变量语法（2026-03-23 补充）

用于包裹条件片段，典型形式：

${
 AND `corpId` = '#@option.where.corpId#' }

${
 AND `creatorId` = '#@option.where.creatorId#' }

规则说明

• ${...} 是完整 SQL 片段容器，内部可含任意合法 SQL（含换行、缩进、注释）；
• ${...} 内部仍使用 #@option.where.xxx# 注入具体值；
• ${...} 块整体按需渲染：若块内所有 #@...# 均有值，则整个块保留；若任一 #@...# 为空/未传，则整块被剔除（空安全）；
• 不支持嵌套 ${...}；
• ${...} 外不可加额外空格或符号（如 ${...} 或 AND ${...} —— AND 必须写在块内）。

✅ 新增：模糊匹配常用块（2026-03-23 补充）

用于 LIKE 模糊查询，典型形式：

${
 AND `name` LIKE '%#@option.where.name#%' }

使用说明

• %...% 包裹确保前后通配；
• 该块同样遵循 ${...} 空安全规则：若 #@option.where.name# 未传值，整块自动剔除；
• 如需左匹配（xxx%）或右匹配（%xxx），请显式写出对应 % 符号。

✅ 新增：时间范围查询常用块（2026-03-23 补充）

用于 createdAt 等时间字段的开闭区间查询，典型形式：

${
 AND `createdAt` >= '#@option.where.createdAt[0]#'
 AND `createdAt` < '#@option.where.createdAt[1]#' }

使用说明

• [0] / [1] 表示数组索引，要求传入长度为 2 的时间字符串数组（如 ["2026-03-01 00:00:00", "2026-03-02 00:00:00"]）；
• 语义为 >= start AND < end，实现标准左闭右开区间；
• 该块同样遵循 ${...} 空安全：任一索引值缺失 → 整块剔除。

✅ 新增：多值循环块语法（2026-03-23 补充）

用于生成 IN 或多条件 OR 逻辑，典型形式：

[email protected] ->
 OR {
 AND [state = '#@item#'] }

使用说明

• [email protected] -> 声明待遍历的数组变量（如 ['draft','published']）；
• #@item# 在循环中自动替换为当前数组元素；
• OR { ... } 是协议级语法糖：引擎会将每个 { ... } 块内容作为原子条件，用 OR 连接，并自动包裹外层括号 (... OR ...)，最终与块外固定条件组合（如 AND (...)），确保 SQL 语义清晰、结构合法；
• 此机制保证生成的 SQL 永远合法（避免 AND/OR 优先级错误）；
• 该语法天然防 SQL 注入（值经模板引擎安全转义）；
• 若 @option.where.state 为空数组或未传，整段被剔除。

🔁 进阶说明：括号语义与等价性

$@... -> OR { ... } 生成的 SQL 自动为每个 { ... } 块添加括号，例如：

[email protected] ->
 OR {
 AND state = 'finished' AND [type = '#@item#'] }

解析为：

( state = 'finished' AND type = 'sale' )
OR ( state = 'finished' AND type = 'refund' )

此形式在逻辑上 完全等价于：

state = 'finished' AND type IN ('sale', 'refund')

或：

AND state = 'finished' AND ( (type = 'sale') OR (type = 'refund') )