看板与工作台

看板和报表是 Semantic 里的应用，这种应用叫工作台（Workshop 模块）。工作台只存定义：页面、分区、组件和变量。数据在打开时按看的人的权限从本体现算，没有人打开时不计算，也不同步。

快速上手

先列出本体里的工作台。再预演保存一份定义。最后取一页的数据。

$ aidc semantic applications list --ontology cell-demo
v3     云费用看板（最新 v3，人保存；替代 0 个旧页面）
  ri.aidc.workshop.cell-demo.module.cloud-costs
$ 

$ aidc semantic applications save --ontology cell-demo --file cloud-costs.json --dry-run
校验通过：将保存为 v4
$ 

$ aidc semantic applications evaluate ri.aidc.workshop.cell-demo.module.cloud-costs --page overview --filters '{"vendorFilter":{"vendor":"AWS"}}'
v3 · 总览
  filters [filterList]
  kpi [metricCard] 合计（美元）=1842.31
  byVendor [chartXY] 1 个类目
  byMonth [pivotTable]
$ 

为什么只存定义

看板不需要整页 HTML。工作台只存定义，因此有这些好处：

• 数据跟着权限走。看的人读不到某个类型，对应的组件显示「没有权限或数据不存在」，不会泄露数据。
• 数据在打开时才取。自动刷新缺省开启。最短间隔缺省为 10 秒。设置 settings.autoRefresh.enabled: false 才会关闭。
• 没有人打开，就不计算，也不同步数据源。

定义的结构

定义是一个 JSON 对象。它的顶层字段如下：

分区（sections）决定组件怎么排。分区有这些字段：

• layout：子内容的排列方式。可以是 columns、rows、flow 或 loop。loop 遍历一个结构数组变量，每一项显示一次。
• widgets：这一层的组件。
• sections：嵌套的子分区。分区最深 4 层。
• flex：和同级分区的宽或高的比例，范围是 0.1 到 12。

每一层最多 12 个分区。一页最多 60 个组件。

组件

下表列出全部组件，以及它们在定义里的 type。

变量

变量保存对象集、数值、字符串和日期。组件通过变量取数。

日历区间用日期变量来做。relativeDateRange 按指定时间单位计算相对区间，不对齐日历。下面的变量取本月 1 日，按北京时间：

{ "id": "monthStart", "type": "timestamp", "transformation": { "startOf": "month", "timeZoneId": "Asia/Shanghai" } }

在对象集过滤里，用 "{{monthStart}}" 引用日期变量。

{ "type": "gte", "field": "createdAt", "value": "{{monthStart}}" }

SQL 变量的写法见 SQL 与数据库。

保存与校验

保存一份定义，会建一个新版本。没有这个工作台时，保存会新建它。--dry-run 只校验，不保存。校验会检查类型、属性和变量引用，并且按你的权限检查。

下面是云费用看板的定义。文件的字段和 API 的请求体一致：

{
  "apiName": "cloud-costs",
  "displayName": "云费用看板",
  "definition": {
    "header": { "title": "云费用看板" },
    "settings": { "autoRefresh": { "enabled": true, "minimumSecondsBetweenRefresh": 60 } },
    "variables": [
      { "id": "vendorFilter", "type": "objectSetFilter", "objectType": "cloudCost" },
      { "id": "costs", "type": "objectSet", "objectSet": { "type": "base", "objectType": "cloudCost" }, "filters": ["vendorFilter"] },
      { "id": "totalUsd", "type": "numeric", "aggregation": { "objectSet": "costs", "metric": { "type": "sum", "field": "costUsd" } } }
    ],
    "pages": [
      {
        "id": "overview",
        "title": "总览",
        "sections": [
          { "widgets": [ { "id": "filters", "type": "filterList", "objectSet": "costs", "output": "vendorFilter", "filters": [ { "property": "vendor", "kind": "select" } ] } ] },
          { "widgets": [ { "id": "kpi", "type": "metricCard", "metrics": [ { "label": "合计（美元）", "variable": "totalUsd" } ] } ] },
          { "layout": "columns", "sections": [
            { "widgets": [ { "id": "byVendor", "type": "chartXY", "chart": "bar", "objectSet": "costs", "groupBy": { "type": "exact", "field": "vendor" }, "metric": { "type": "sum", "field": "costUsd" } } ] },
            { "widgets": [ { "id": "byMonth", "type": "pivotTable", "objectSet": "costs", "rows": [ { "type": "exact", "field": "month" } ], "metrics": [ { "label": "美元", "metric": { "type": "sum", "field": "costUsd" } } ], "totals": true } ] }
          ] }
        ]
      }
    ]
  }
}

aidc semantic applications save --ontology cell-demo --file cloud-costs.json --dry-run   # 先校验
aidc semantic applications save --ontology cell-demo --file cloud-costs.json             # 保存为新版本

• apiName 小写字母开头，只能用小写字母、数字和连字符，长度是 2 到 63 个字符。
• 定义的大小最多 256 KB。
• 智能体保存时，加 --as-agent <智能体 id>。版本会记为智能体保存。
• --publish 保存后同时发布。能不能发布，见下文「版本与发布」。

取一页的数据

evaluate 取一页的数据。每个组件返回一份结果。智能体用这个接口使用工作台，界面也用它。

请求体的字段如下：

• page：页面的 id。
• filters：筛选变量的值。外层的键是筛选变量的 id，里层是属性和值。值可以是文本，也可以是 { "from": "…", "to": "…" } 区间。
• version：要看的版本号。
• tablePages：对象表格的页码，从 0 开始。

curl -X POST "https://www.ai-dc.ai/api/v1/workshop/modules/ri.aidc.workshop.cell-demo.module.cloud-costs/evaluate" \
  -H "Authorization: Bearer $AIDC_API_KEY" -H "Content-Type: application/json" \
  -d '{"page":"overview","filters":{"vendorFilter":{"vendor":"AWS"}}}'

版本与发布

每次保存是一个新版本。用户看到的是已发布的版本。谁能发布，由组织的审批策略决定。

aidc semantic applications versions ri.aidc.workshop.cell-demo.module.cloud-costs      # 列出版本
aidc semantic applications publish ri.aidc.workshop.cell-demo.module.cloud-costs 4      # 发布 v4

$ aidc semantic applications publish ri.aidc.workshop.cell-demo.module.cloud-costs 4
云费用看板：用户现在看到 v4
$ 

每次发布都写进审计日志。

权限

看板的权限分四个方面：版本、数据、自动刷新和公开访问。

• 版本：成员只能看到已发布的版本。开发者可以看草稿，也可以看任一版本。
• 数据：数据按类型判断。看的人读不到某个类型，组件显示「没有权限或数据不存在」，不显示数据。
• 自动刷新：自动刷新只注册页面上能读的对象集。objectSets 可以指定注册哪些对象集变量。
• 公开访问：应用或组织的 Applications 设为 Open to Internet 后，应用的发布版不用登录就能只读。只能读到这个应用用到的类型。嵌在应用里的 widget set 一起放行，也是只读。
• Loop 报告的全屏链接：/semantic/<组织>/objects/loopReport/<slug>?embedded=true&media=html 跟随组织的 Applications 的开放程度。改回 Group，同一个链接就要登录。

工作台也是资源。谁能看它、怎样分享它，见 访问与安全。

网页地址与分享

工作台的网页地址是 https://www.ai-dc.ai/semantic/<组织>/applications/<apiName>。筛选、翻页和切换页面的状态都在网址里。把网址发给别人，对方打开看到的是自己权限下的数据。

命令行

这一节列出工作台的命令。

全部参数见 参考 · 访问、自动化与用量。

API

工作台调用下面这些端点。凭证是开发者 Key 或应用票据。

限制

下表列出工作台的上限。

常见错误

按错误或现象查。

下一步

• 访问与安全：谁能看到看板里的数据。
• 定义本体：看板读的 Object Type 和 Action。
• 自动化：数据变化后，自动运行工作流。
• SQL 与数据库：SQL 变量的写法。
• 参考 · 访问、自动化与用量：全部看板命令。