ddh 数据分析

业务定位

面向运营、财务、供应链、业务负责人，对「消费券核销」业务（平台发券 → 用户报销 / 消费 / 帮你付 → 生成核销单）做只读取数与分析，重点支撑：券核销经营分析、商品 / SKU 销售与核销结构、供应商与客户考核、券流转（生命周期）、退款与扣款健康度。

覆盖：取数、汇总、排行、趋势、同比 / 环比、结构拆解、多维下钻。 不覆盖：写入 / 修改 / 删除；还原脱敏值；跨库 / 跨系统 JOIN；强一致实时查询（只读从库有复制延迟）；用户级个人信息追溯。

⚠️ 核心纪律

本技能不携带任何表名、字段名、状态枚举与口径。 这些系统细节由 MCP Server 在鉴权通过后按需下发。 严禁凭记忆或猜测写表名、字段名、状态值——猜错会直接报错，或算出看似合理实则错误的数字。 每一次取数任务，都必须按下面的顺序，先取口径、再取结构、最后才写 SQL。

可用工具

| 工具 | 用途 | 何时用 | |---|---|---| | getAnalysisGuide | 获取业务口径手册：实体与表关系、金额 / 状态 / 时间口径、脱敏与禁查字段、SQL 示例、SQL 生成纪律、语法约束与常见错误、输出规范 | 每次任务第一步，不传参数先看目录，再按需取章节 | | listTables | 列出可查询的表及口径说明 | 确认本次要用的表 | | describeTable | 查看表字段结构（支持逗号分隔多表一次查） | 写 SQL 之前必调 | | listMetrics | 列出预定义指标 | 需要稳定口径时 | | runMetric | 执行预定义指标，只传参数 | 有现成指标时优先用 | | queryReadonly | 执行只读 SELECT | 指标覆盖不了时才用 |

标准流程（必须按顺序，禁止跳过）

先 getAnalysisGuide：不传参数拿到章节目录，再按本次问题取需要的章节。
- 口径类问题（金额怎么算、状态怎么取、时间怎么写）→ 取口径章节，不要自己定义口径。
- 写 SQL 之前 → 取 SQL 生成纪律 与 语法约束 章节。
- 组织结论之前 → 取 输出规范 章节。
再 listTables：确认可用的表和口径说明。
再 describeTable：确认字段名、类型、注释。严禁凭猜测写字段名。
优先 listMetrics + runMetric：有现成指标就用，口径最稳。
没有指标才 queryReadonly：
- SQL 通用纪律（显式字段、LIMIT、左闭右开、GROUP BY 完整性、JOIN 去重、敏感字段）以手册 SQL 生成纪律 章节为准
- 用附带资源 scripts/build_query.py 生成 SQL，把手册里的口径作为参数传入（可自动规避常见口径错误）
- 金额、状态过滤、时间区间、逻辑删除等业务口径一律以口径章节为准
结果校验：
- 调用失败时返回结构化错误 {"error_code": "...", "retryable": true/false, "message": "...", "hint": "..."}： retryable = true 表示按 hint 修正后重试；false 表示服务侧问题，不要原样重试，如实告知用户
- truncated = true 说明被截断，需加 WHERE 或减小范围重查
- 返回为空时，先确认状态值与时间口径，而不是直接下结论"没有数据"
呈现结论：按手册 输出规范 章节组织结论、对照、拆解与排版（结论先行、口径说明、洞察要素、局限声明）。

附带资源

scripts/build_query.py（合规 SQL 生成器 / 校验器）

通用（不含任何业务库结构）的只读 SELECT 生成与校验脚本。把口径规则作为参数注入，用代码焊死"显式字段、强制 LIMIT、左闭右开、必须带指定过滤条件"等通用约束。

# 生成：按天汇总（过滤条件与金额换算按手册口径传入）
python3 scripts/build_query.py \
  --table <表名> \
  --require "<必加过滤条件，如逻辑删除过滤>" \
  --require "<必加过滤条件，如完成状态过滤>" \
  --time-field <时间字段> --start 2026-09-08 --end 2026-09-09 \
  --dimensions "<维度表达式>:<别名>" \
  --metrics "COUNT(*):cnt,SUM(<金额字段>):amount" --divide <金额字段>

# 校验：已有 SQL 是否踩坑
python3 scripts/build_query.py --lint "SELECT ... FROM ..."

生成的 SQL 直接交给 queryReadonly 执行。脚本路径相对本 skill 目录；表名、字段名、过滤条件通过参数传入，或先 getAnalysisGuide 取口径再拼参数。

接入方式（MCP 客户端配置）

服务端使用 Streamable HTTP 传输，端点为 /mcp，需在请求头携带 API Key：

{
  "mcpServers": {
    "ddh-analytics": {
      "url": "http://<mcp-server-host>:<mcp-server-port>/mcp",
      "headers": {
        "X-Api-Key": "<your-api-key>"
      }
    }
  }
}

客户端需支持 MCP 协议 2025-03-26 及以上（Streamable HTTP）
API Key 由服务端通过环境变量 DDH_MCP_API_KEY 注入（配置文件不落明文 Key），向服务提供方索取
限流：默认每个 Key 每分钟 60 次，超限返回 429