Skip to content

HTTP 接口 ​

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

约定:

  • 前缀统一 /api,请求体与响应体都是 JSON(UTF-8)。
  • 出错回 { "error": "一句能照着办的话" },HTTP 状态码见各接口。
  • 开了鉴权(auth.mode: "jwt")时,每个请求带 Authorization: Bearer <凭证>,凭证怎么来见登录身份与数据范围;没带或过期回 401,code 说明原因。
  • 没开鉴权的多租户部署,租户从请求头 X-Conch-Tenant 取,由反向代理注入,见部署与安全。
  • 查看类调用一律带 version,服务端按那一版取规格;接口不接受客户端传 SQL。

换凭证 ​

http
POST /api/auth/exchange
Authorization: Basic base64(<客户端 id>:<密钥>)

只给宿主后端调,密钥不能出现在浏览器里。请求体与返回见登录身份与数据范围。

当前身份 ​

http
GET /api/auth/me
json
{ "enabled": true, "subject": "u10086", "name": "张三", "tenant": "hospital-a", "space": null, "role": "viewer", "scopeAll": false, "expiresAt": "2026-09-23T10:38:53+00:00" }

没开鉴权时回 { "enabled": false, "tenant": "default" }。

报表列表 ​

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

publishedVersion 为 null 表示这张报表还没发布过,嵌出去打不开。宿主做自己的报表菜单时按这个字段过滤。只看报表的账号(viewer)只会列出已发布的,凭证限定了报表的只列那几张。

打开一张报表 ​

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

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

json
{
  "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
}
字段说明
modedynamic 每次打开取最新数;snapshot 数据快照,数字已固化
spec渲染用的报表规格。SQL 正文已去掉,查询名保留
params发布那一刻的筛选条件值,作为初始值
data仅快照版有值:固化下来的查询结果,形状同下面的 queries
状态码含义
404报表不存在,或指定的版本号不存在
409这张报表还没有发布

多数据源查询绑定 ​

报表的 datasource 为默认数据源。规格的 queries[*].datasource、drills[*].queries[*].datasource 可指定其他已配置数据源;省略时使用报表默认数据源。动态筛选选项沿 params[*].source.query 找到查询并使用其绑定。

/data、/drill、/export 的请求形状与版本选择规则不变,服务端逐条按绑定取数。/view 返回的查询仍去掉 SQL,并保留 datasource。调用方不能通过查看态请求临时指定其他数据库。每个源分别检查租户、启用状态和身份范围;系统范围参数不可被用户参数覆盖。旧规格无需迁移。

详见多个数据源。

取数 ​

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

{ "version": "v3", "params": { "month": "2026-08", "store": ["S001", "S002"] } }
json
{
  "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。

穿透明细 ​

http
POST /api/reports/{id}/drill

{ "version": "v3", "drill": "d_store_orders",
  "args": { "store_name": "上海徐汇店" },
  "params": { "month": "2026-08" } }
json
{ "title": "上海徐汇店 订单明细", "queries": { "q_orders": { "columns": [], "rows": [] } } }

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

导出 ​

http
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。

版本列表 ​

http
GET /api/reports/{id}/versions
json
[
  { "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 速查 ​

bash
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

提示词流程(管理员) ​

  • GET /api/prompt-workflow:返回当前快照 current 与倒序历史 history,按凭证租户隔离。
  • POST /api/prompt-workflow:提交 expectedRevision、action、note。并发修订冲突回 409,无效内容回 400。
  • action=save:同时提交 prompts,键必须为 requirements、discovery、feasibility、clarification、generation、repair;每段 1–12000 字。只保存草稿。
  • action=publish:发布服务端已保存草稿,说明必填,不接收新的编辑内容。
  • action=rollback:提交 sourceRevision,0 表示内置版本,其余需为已发布版本。回退追加新修订,同时恢复草稿。

每个版本包含 revision、publishedRevision、action、note、actor、at、draft、active;回退另有 sourceRevision。阶段含 id/name/purpose/inputs/outputs/tools/prompt。生成时固定使用生效快照;lastGenerationPromptVersion 与生成完成的 trace.promptVersion 提供版本号和内容哈希。复核候选确认时保留其原始生成版本,不因提示词发布而重新设计。

给 AI 用的纯文本索引在 /llms.txt,每篇原文在 /md/ 下。