深色模式
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/mejson
{ "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/reportsjson
[
{
"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=v3version 不写取当前发布版;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
}| 字段 | 说明 |
|---|---|
mode | dynamic 每次打开取最新数;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}/versionsjson
[
{ "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 提供版本号和内容哈希。复核候选确认时保留其原始生成版本,不因提示词发布而重新设计。
