HTTP 接口

嵌一个 iframe 用不到这些接口——它们是给要自己做报表列表、自己做导出按钮、或者要把报表数据拿去别处用的宿主准备的。

约定：

• 前缀统一 /api，请求体与响应体都是 JSON（UTF-8）。
• 出错回 { "error": "一句能照着办的话" }，HTTP 状态码见各接口。
• 多租户部署时租户从请求头 X-Conch-Tenant 取，由反向代理注入，见部署与安全。
• 查看类调用一律带 version，服务端按那一版取规格；接口不接受客户端传 SQL。

报表列表

GET /api/reports

[
  {
    "id": "r260922123456",
    "title": "门店经营看板",
    "datasource": "retail",
    "updatedAt": "2026-09-22T14:03:11",
    "publishedVersion": "v3",
    "hasDraft": true
  }
]

publishedVersion 为 null 表示这张报表还没发布过，嵌出去打不开。宿主做自己的报表菜单时按这个字段过滤。

打开一张报表

GET /api/reports/{id}/view?version=v3

version 不写取当前发布版；draft 取草稿。查看页自己调的就是它。

{
  "id": "r260922123456",
  "title": "门店经营看板",
  "version": "v3",
  "mode": "dynamic",
  "publishedAt": "2026-09-22T14:10:05",
  "note": "加了退款率",
  "spec": { "version": 1, "title": "…", "params": [], "queries": {}, "nodes": [] },
  "params": { "month": "2026-08" },
  "data": null
}

字段	说明
mode	dynamic 每次打开取最新数；snapshot 数据快照，数字已固化
spec	渲染用的报表规格。SQL 正文已去掉，查询名保留
params	发布那一刻的筛选条件值，作为初始值
data	仅快照版有值：固化下来的查询结果，形状同下面的 queries

状态码	含义
404	报表不存在，或指定的版本号不存在
409	这张报表还没有发布

取数

POST /api/reports/{id}/data
Content-Type: application/json

{ "version": "v3", "params": { "month": "2026-08", "store": ["S001", "S002"] } }

{
  "queries": {
    "q_by_store": {
      "columns": ["store_name", "sales_amount"],
      "columnTypes": ["String", "Decimal"],
      "rows": [["上海徐汇店", 281033.5], ["上海浦东店", 236810.0]],
      "truncated": false,
      "elapsedMs": 42
    },
    "q_total": { "error": "字段 pay_amount 不存在" }
  }
}

• 每条查询单独成败：一条查不出来，其它照常返回，那一条带 error。
• rows 是二维数组，列顺序同 columns；日期已格式化成 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss。
• truncated 为 true 表示结果超过上限被截断（页面上限 5000 行）。
• 参数写法同链接参数，只是用真正的 JSON 类型：区间写 ["2026-01-01", "2026-03-31"]，多选写数组，不限写 null。

穿透明细

POST /api/reports/{id}/drill

{ "version": "v3", "drill": "d_store_orders",
  "args": { "store_name": "上海徐汇店" },
  "params": { "month": "2026-08" } }

{ "title": "上海徐汇店 订单明细", "queries": { "q_orders": { "columns": [], "rows": [] } } }

drill 是报表规格里声明的穿透目标 key，args 的 key 必须是该目标声明过的参数，否则整个请求回 400。穿透 SQL 在服务端按规格取，客户端传不进来。

导出

POST /api/reports/{id}/export/xlsx
POST /api/reports/{id}/export/docx

{ "version": "v3", "params": { "month": "2026-08" } }

回的是文件流，文件名在 Content-Disposition 里。带上 "drill": "d_store_orders", "args": {…} 就是导出那一层穿透明细。

• xlsx 全量数据（上限 10 万行，页面上限是 5000 行），docx 图文报告。
• PDF 没有接口：走浏览器打印，在报表页头的「导出」里选。
• 报表规格里关掉了某种格式，对应请求回 400。

版本列表

GET /api/reports/{id}/versions

[
  { "no": "v3", "time": "2026-09-22T14:10:05", "who": "本人", "note": "加了退款率",
    "mode": "dynamic", "current": true,
    "audit": { "score": 86, "grade": "excellent", "findings": 2, "highest": "low" } }
]

宿主要做「看历史版本」的下拉时用它，no 填进链接的 version。

curl 速查

BASE=https://report.example.com
ID=r260922123456

# 这张报表能不能嵌（回 409 就是还没发布）
curl -s "$BASE/api/reports/$ID/view" | head -c 300

# 按条件取数
curl -s -X POST "$BASE/api/reports/$ID/data" \
  -H 'Content-Type: application/json' \
  -d '{"version":"v3","params":{"month":"2026-08"}}'

# 导出 Excel
curl -s -X POST "$BASE/api/reports/$ID/export/xlsx" \
  -H 'Content-Type: application/json' \
  -d '{"version":"v3","params":{"month":"2026-08"}}' -OJ