跳到主要内容

看板

网关前缀：${API_BASE}/metadata/dashboards/...

Dashboard 配置读取与维护：支持 DB(jsonb) 与类路径回退。后端控制器：DashboardController（/api/v1/dashboards）。

保存/更新看板配置（按 code upsert）​

  • POST /dashboards
  • 权限：admin / tenant:admin
  • 说明：根据配置中的 code 字段进行保存或更新（upsert）。请求体字段为 config，其值是完整的看板配置 JSON 字符串。
  • 请求头：
    • Authorization: Bearer <token>
    • Content-Type: application/json
    • X-Tenant-Id: <tenantId>（可选，多租户场景建议传入）
  • 配置参考：ai-daas-metadata-service/src/main/resources/dashboards/analytics.json
    • 示例结构（节选）：
{
  "code": "analytics",
  "title": "经营驾驶舱",
  "grid": { "cols": 12, "rowHeight": 40, "gutter": 12 },
  "widgets": [
    { "id": "kpi_revenue_30d", "type": "kpi", "title": "近30天营收" },
    { "id": "trend_revenue_30d", "type": "chart", "title": "营收（近30天）" }
  ]
}
  • 调用示例（简化写法，手动转义）：
curl -X POST "${API_BASE}/metadata/dashboards" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenantId>" \
  -d '{
    "config": "{ \"code\": \"analytics\", \"title\": \"经营驾驶舱\", \"grid\": { \"cols\": 12 }, \"widgets\": [] }"
  }'
  • 调用示例（推荐写法，自动将文件内容转为字符串）：
curl -X POST "${API_BASE}/metadata/dashboards" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenantId>" \
  --data "{\"config\": \"$(jq -Rs . < ai-daas-metadata-service/src/main/resources/dashboards/analytics.json)\"}"
  • 响应示例：
{
  "success": true,
  "message": "Dashboard saved",
  "data": {
    "id": "<id>",
    "code": "analytics",
    "title": "经营驾驶舱",
    "config": "{ ... }",  
    "tenantId": "<tenantId>",
    "createdAt": "2024-10-01T12:00:00Z",
    "updatedAt": "2024-10-01T12:00:00Z"
  }
}

注：返回体中的 data.config 为 JSON 字符串（服务端以字符串形式存储并返回，已 pretty 格式化）。

通过 code 更新（PUT 可选）​

  • PUT /dashboards/{code}
  • 权限：admin / tenant:admin
  • 说明：按路径参数 code 进行保存/更新，体为 DashboardDto，其中 config 是完整 JSON 字符串。
  • 示例：
curl -X PUT "${API_BASE}/metadata/dashboards/analytics" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: <tenantId>" \
  -d "{ \"config\": \"{
  "code": "analytics",
  "title": "经营驾驶舱",
  "grid": { "cols": 12, "rowHeight": 40, "gutter": 12 },
  "widgets": [
    {
      "id": "kpi_revenue_30d",
      "type": "kpi",
      "title": "近30天营收",
      "grid": { "x": 0, "y": 0, "w": 3, "h": 2 },
      "style": { "unit": "￥", "valueFormat": ",0.00" },
      "dataSource": { "type": "view", "viewId": "metric.revenue_30d" }
    },
    {
      "id": "trend_revenue_30d",
      "type": "chart",
      "title": "营收（近30天）",
      "grid": { "x": 3, "y": 0, "w": 6, "h": 6 },
      "chart": { "kind": "line", "xField": "date", "yField": "amount", "area": true, "smooth": true },
      "dataSource": { "type": "view", "viewId": "view.revenue_by_day" }
    },
    {
      "id": "top5_customers",
      "type": "chart",
      "title": "Top5 客户营收",
      "grid": { "x": 9, "y": 0, "w": 3, "h": 6 },
      "chart": { "kind": "bar", "categoryField": "customer", "valueField": "amount", "orientation": "horizontal", "limit": 5, "sort": "-value" },
      "dataSource": { "type": "view", "viewId": "view.revenue_by_customer" }
    },
    {
      "id": "table_orders",
      "type": "table",
      "title": "订单明细表（示例）",
      "grid": { "x": 0, "y": 6, "w": 12, "h": 6 },
      "table": {
        "columns": [
          { "key": "order_id", "title": "订单", "width": 100, "align": "left" },
          { "key": "customer", "title": "客户", "width": 160, "align": "left" },
          { "key": "date", "title": "日期", "width": 120, "align": "center" },
          { "key": "amount", "title": "金额", "width": 120, "align": "right" }
        ],
        "rowHeight": 32,
        "autoScroll": true,
        "scroll": { "step": 1, "interval": 16, "pauseMs": 1200 }
      },
      "dataSource": { "type": "view", "viewId": "view.orders_recent" }
    }
  ]
}\" }"

按 code 读取看板配置​

  • GET /dashboards/by-code/{code}
  • 权限：admin / tenant:admin / read
  • 请求头：
    • Authorization: Bearer <token>
    • X-Tenant-Id: <tenantId>（可选）
  • 示例：
curl -X GET "${API_BASE}/metadata/dashboards/by-code/analytics" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: <tenantId>"
  • 响应示例：
{
  "success": true,
  "message": "Dashboard found",
  "data": {
    "id": "<id>",
    "code": "analytics",
    "title": "经营驾驶舱",
    "config": "{ ... }"
  }
}

备注与补充：

  • 也支持 PUT /dashboards/{code} 保存/更新（效果同 POST，体为 DashboardDto，其中 config 为 JSON 字符串）。推荐统一使用 POST。
  • 服务端控制器参考：ai-daas-metadata-service/src/main/java/com/aidaas/metadata/controller/DashboardController.java#L36-44（按 code 读取），保存接口见同文件 @PostMapping/@PutMapping。
  • 完整配置样例参见：ai-daas-metadata-service/src/main/resources/dashboards/analytics.json

按 ID 读取看板配置​

  • GET /dashboards/{id}
  • 权限：admin / tenant:admin / read

分页查询看板列表​

  • GET /dashboards?page=1&pageSize=20
  • 权限：admin / tenant:admin / read
  • 返回：ApiResponse<PageResponse<DashboardDto>>

配置结构说明（基于 analytics.json）​

  • code：看板唯一标识（必填）。
  • title：看板显示标题。
  • grid：布局配置（cols 列数、rowHeight 行高、gutter 间距）。
  • widgets：组件列表，每项包含：
    • id：组件唯一标识
    • type：kpi | chart | table
    • title：组件标题
    • grid：组件在网格中的位置与尺寸（x、y、w、h）
    • style/chart/table：按类型的显示与图表/表格配置
    • dataSource：数据来源（如 { "type": "view", "viewId": "view.revenue_by_day" }）