sql-to-business-logic

SQL 转业务逻辑翻译器

使用场景

• 利益相关者询问“这条查询具体计算的是什么？”
• 为非技术读者编写查询库或 dbt 模型的文档
• 将查询逻辑与业务需求进行对比，检查查询是否正确
• 帮助新分析师熟悉现有 SQL 模式
• 在重构之前翻译缺少文档的旧查询

流程

1. 获取查询和上下文——取得 SQL 和它要回答的业务问题。同时收集架构说明（关键表和列在业务层面代表什么）。
2. 翻译 FROM/JOIN 结构——用通俗语言说明组合了哪些数据源以及使用了哪种连接类型（内连接只保留匹配项；左连接保留左侧的所有行）。指出连接类型是否似乎与所述用途不一致。
3. 翻译 WHERE 筛选条件——将每个筛选条件列为通俗易懂的业务规则（例如，status = 'completed' →“仅包含已付款并已履约的订单”）。
4. 解释 GROUP BY 和聚合——说明每种聚合的计算内容和计算粒度。使用 scripts/sql_explainer.py 自动完成第一轮结构解析。
5. 总结输出列——说明每个输出列的业务含义和任何边界情况（空值、舍入、货币单位）。
6. 标记问题并编写验证问题——识别潜在问题（空值的隐式传播、意外扩增行数、硬编码日期）。生成 3–5 个需要查询作者确认的问题。使用 assets/query_documentation_template.md 记录完整翻译。

此技能所需的输入

• 完整的 SQL 查询（从 SELECT 到 ORDER BY）
• 查询旨在回答的业务问题
• 表和列的说明（或数据目录条目）
• 关键状态值、日期处理或货币相关的任何业务规则
• 预期输出：谁会阅读结果，以及用于什么决策

输出

• scripts/sql_explainer.py——解析 SQL 查询并生成结构化的通俗说明
• assets/query_documentation_template.md——填写完整翻译，涵盖用途、分步逻辑、输出列、业务规则和验证问题
• 可选：查询逻辑的流程图表示