指标管理（Metrics）

1. 页面概览

1.1 是什么

指标管理（MetricsPage.vue，路由 /foundry/metrics）是 LightFoundry 的「指标语义层」管理界面，对标 Palantir Foundry 的 Metric 语义层能力。它把「业务指标」从物理 SQL 中解放出来：先定义实体（Entity），再在实体下声明维度（Dimension）与度量（Measure），最后把「度量 + 维度 + 过滤条件 + 口径」组合成一条指标（Metric）。查询时前端只提交指标名与参数，由后端 OOL 翻译引擎生成物理 SQL，并对用户做 RLS/CLS 安全注入后到真实数据源执行。

页面采用四个 Tab 组织全链路：指标目录（Catalog 卡片浏览口径）、实体模型（实体 + 维度/度量维护）、指标定义（指标 CRUD + 状态/版本）、指标查询（维度分组 + 过滤 + limit 结果表格）。四个 Tab 对应四套后端 API，全部走同一个 client.js axios 实例（baseURL /api/v1，Bearer aip_token）。

这是一个「深水区」页面：指标查询不是简单表格查询，而是聚合 + 维度分组 + 时间范围过滤 + 编辑态叠加的组合翻译流程。理解后端 QueryMetric 的七步翻译（取定义 → 合并筛选 → OOL 翻译 → 分页 → 编辑态叠加判定 → 执行 → 组装口径）是排查查询异常的关键。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/foundry/metrics
• 路由名称：FoundryMetrics
• 菜单位置：Foundry 左侧边栏「指标管理」（FoundryLayout 菜单「语义分析」区块）
• 源码文件：action/web/src/views/MetricsPage.vue（约 1235 行，四 Tab 一体）

2.2 认证与权限

• 需要登录：是（路由 meta.requiresAuth = true）
• 登录方式：AIP 统一登录，localStorage.aip_token 作为 Authorization: Bearer <token>；token 失效时 client.js 响应拦截器会清理 aip_token/aip_username 并跳转 /login
• 页面本身无角色限制；但查询与检索结果受后端数据安全约束：handleQueryMetric 会把当前登录用户注入 req.UserID，供 OOL 翻译做属性级只读判定（无读权限属性「禁止聚合」）与 RLS/CLS 只读注入
• 404 排错：访问 /foundry/metrics 出现 404，先确认 Foundry 后端（18081）已启动、前端路由已注册（router/index.js 第 227-231 行）

2.3 端口与 API 前缀

• 后端端口：18081（Foundry）
• API 前缀：/api/v1（action/web/src/api/client.js）
• 请求超时：30 秒（client.js 全局 timeout: 30000）

3. 界面布局

页面从上到下为：页头 → 操作结果提示条 → Tab 切换条 → 当前 Tab 内容区。

┌──────────────────────────────────────────────────────────────┐
│ ① 页头：标题「指标管理」                                       │
│ ② 操作结果提示条（alert 成功/失败，可「关闭」）                 │
│ ③ Tab 切换条：[指标目录] [实体模型] [指标定义] [指标查询]       │
│ ④ 内容区（随 Tab 切换）                                        │
│    ├─ 指标目录：指标卡片网格（grid auto-fill minmax 340px）     │
│    ├─ 实体模型：左「实体列表」(300px) + 右「实体详情」双栏        │
│    │    ├─ 新建实体表单 / 实体详情（维度表 + 度量表 + 行内编辑）  │
│    ├─ 指标定义：状态筛选 + 新建指标 + 创建/编辑表单 + 指标表格    │
│    └─ 指标查询：查询表单（指标/limit/offset/时间范围/维度/过滤） │
│         + 查询结果卡片（指标元信息 + 结果表格）                  │
└──────────────────────────────────────────────────────────────┘

各板块职责：

• ① 页头：仅标题「指标管理」，无副标题（page-header 仅 h2）。
• ② 操作结果提示条：全局唯一反馈通道，showAlert(msg, type) 驱动，type 为 alert-error / alert-success / alert-info；带「关闭」按钮清空。
• ③ Tab 条：tabs 数组顺序即展示顺序：指标目录 / 实体模型 / 指标定义 / 指标查询；点击切换 activeTab，四个 Tab 各自独立加载。
• ④ 指标目录：加载 catalog.metrics，每张卡片显示显示名/状态徽标/name/实体/v版本/口径 formula/度量标签/维度标签/描述；空列表显示「暂无指标，请先在"指标定义"中创建。」。
• ④ 实体模型：左栏实体列表可点击选中（item-selected 高亮）；右栏为新建表单或实体详情（维度表格、度量表格 + 行内添加表单）。
• ④ 指标定义：顶部「状态筛选」下拉 + 「新建指标」按钮；下方创建/编辑表单与指标列表表格（ID/名称/显示名称/实体/度量/维度/状态/版本/操作）。
• ④ 指标查询：查询表单含指标下拉、limit/offset、时间维度名、开始/结束时间、维度多选、过滤条件；下方「查询结果」卡片展示指标元信息（名称/实体/聚合/状态/formula）与结果表格。

4. 交互元素详解

4.1 全局元素

4.2 指标目录 Tab

4.3 实体模型 Tab

4.4 指标定义 Tab

4.5 指标查询 Tab

5. 后端关联

5.1 API 客户端

action/web/src/api/client.js：

• baseURL：/api/v1（Vite 开发服务器代理到 Foundry 后端 18081）
• timeout：30000
• 请求拦截器：从 localStorage.getItem('aip_token') 取 token，有则注入 Authorization: Bearer <token>
• 响应拦截器：401 时移除 aip_token/aip_username，路径非 /login 则跳转 /login
• 导出：apiClient（默认导出），MetricsPage 通过 import apiClient from '../api/client.js' 使用，无独立 API 文件

5.2 端点表

5.3 响应结构

统一成功包装 {code: 0, data: ...}（server 包 okData）；失败包装 {code, error}（errorResponse，code 为错误码、status 对应 HTTP 状态码）。

指标目录 GET /metrics/catalog：

{
  "code": 0,
  "data": {
    "metrics": [
      {
        "name": "revenue",
        "display_name": "营收",
        "entity": "sales_entity",
        "entity_id": 1,
        "metric_type": "simple",
        "measures": ["revenue_measure"],
        "dimensions": ["order_date", "region"],
        "formula": "SUM(amount)",
        "synonyms": "收入,销售额",
        "data_source_id": 1,
        "owner": "zhangsan",
        "version": 2,
        "status": "active"
      }
    ]
  }
}

实体详情 GET /metrics/entities/:id：

{
  "code": 0,
  "data": {
    "entity": { "id": 1, "name": "sales_entity", "display_name": "销售实体", "object_type_id": 3, "base_table": "orders", "data_source_id": 1, "primary_time_dimension": "order_date" },
    "dimensions": [ { "name": "order_date", "display_name": "下单日期", "source_property": "order_date", "time_grain": "day", "is_time_dimension": true } ],
    "measures": [ { "name": "revenue_measure", "display_name": "营收度量", "expression": "SUM(amount)", "agg_type": "sum", "type": "simple" } ]
  }
}

指标查询 POST /metrics/query：

{
  "code": 0,
  "data": {
    "columns": ["order_date", "metric"],
    "rows": [["2026-08-01", 12500.5]],
    "metric": {
      "name": "revenue",
      "display_name": "营收",
      "entity": "sales_entity",
      "formula": "SUM(amount)",
      "agg_type": "sum",
      "type": "simple",
      "metric_type": "simple",
      "dimensions": ["order_date"],
      "status": "active",
      "edited_overlay": false,
      "edit_overlay": ""
    }
  }
}

5.4 关联模块表

5.5 关键机制

• 指标状态机：draft → active → deprecated。DELETE 即软删（置 deprecated），查询时 deprecated 指标直接拒绝：「metric ... 已停用（deprecated），不可查询」。
• 版本机制：创建时可用 version 指定初始版本（默认 1）；PUT 更新后版本自动 +1（前端提示「指标更新成功（版本已自动 +1）」），目录卡片与列表展示 v<version>。
• QueryMetric 翻译流程（深水区核心）：① 按 api_name 取指标定义 + 度量 + 实体（deprecated 拒绝）；② 合并「默认筛选（def.Filters）」+「请求筛选（req.Filters）」；③ 时间范围落到实体 primary_time_dimension（或请求指定）的 time_grain 时间维度，start→>=、end→<= 追加过滤；④ 分组维度校验：必须是实体维度且在该指标允许维度内，映射到 source_property；⑤ OOL 翻译聚合表达式——simple 走 agg(measure.expression)，ratio/derived 拆分子分母两个聚合表达式按 (num)/(den) 拼装，cumulative 走 SUM(...) OVER (ORDER BY 时间维度 ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)；⑥ 追加 LIMIT/OFFSET；⑦ 执行（真实数据源经注入 runner 或连接器）。
• 编辑态聚合叠加（B1-5）：仅 simple 指标且注入了编辑态读取器、对象存在涉及度量/维度字段的未提交编辑时，回退行级查询（行上限 OverlayRowLimit）+ 内存聚合，保证聚合值与行级一致；超行上限返回未叠加值并标注 edit_overlay="approximate"；ratio/derived/cumulative 本版不叠加（edited_overlay=false 诚实标注）。
• 安全注入：handleQueryMetric 注入当前用户到 req.UserID，OOL 翻译做属性级只读判定（无读权限属性禁止聚合）与 RLS/CLS 只读注入；查询执行经参数化 SQL。
• 额度与分页：limit/offset 由前端传默认 100/0，后端仅 limit>0 时拼接 LIMIT ?、offset>0 时拼接 OFFSET ?。

6. 核心流程详解

6.1 从零到可查：指标建模主流程

1. 建实体：进入「实体模型」Tab → 点「新建实体」→ 填写名称（api_name）、显示名称、对象类型（可选，来自 GET /ontology/objects）、数据源 ID、基础表、主时间维度、描述 → 点「创建」。成功后自动选中新实体并加载详情。
2. 加维度：详情「维度」区点「+ 添加维度」→ 填维度名/显示名/来源属性/时间粒度；若勾选「时间维度」则粒度必填（year/quarter/month/week/day）→ 点「保存」。维度名是后续分组与多选的 key。
3. 加度量：详情「度量」区点「+ 添加度量」→ 填度量名/显示名/聚合（sum/avg/count/min/max）/类型（simple/ratio/derived/cumulative）/来源属性/表达式（如 SUM(amount)）；类型为 ratio 时补充分子（numerator）与分母（denominator）→ 点「保存」。
4. 建指标：切到「指标定义」Tab → 「新建指标」→ 填名称（api_name）、显示名、状态（默认 draft）、实体（必选，选中即加载该实体度量/维度选项）、度量（必选）、版本、owner、同义词（逗号分隔）、描述；勾选允许维度；按需追加过滤条件 → 「保存」。创建成功后列表与目录同时刷新。
5. 发版：在表单把状态改为 active 再保存（或创建时直接 active），目录卡片即展示 active 徽标。
6. 查询：切到「指标查询」Tab → 选指标 → 勾选维度 → 填 limit/offset（默认 100/0）→ 可选时间维度名与开始/结束时间 → 「查询」→ 查看结果表格与口径 formula。

6.2 指标编辑与版本流

• 编辑入口：指标列表「编辑」按钮。openMetricEdit 填充表单后 await onMetricEntityChange(true) 异步加载实体选项，再恢复原 measure/dimensions 选择。
• 编辑可改字段：display_name、description、dimensions、filters、synonyms、owner、status；name、measure_id、entity_id、version 不可改（表单中 name/version disabled）。
• 保存走 PUT /metrics/:id，后端更新版本 +1，前端提示「指标更新成功（版本已自动 +1）」，随后刷新列表与目录。

6.3 指标删除（软删）流

指标列表「删除」→ confirm('确定删除指标"xx"吗？') → DELETE /metrics/:id → 后端置 status=deprecated → 刷新列表与目录。删除后指标仍可被目录展示（带 deprecated 徽标），但查询接口直接拒绝执行。

6.4 指标查询分支语义

• 无时间范围：time_start/time_end/time_dimension 三项全空时，请求体不附带 time_range，查询不加时间过滤。
• 有时间范围：任一项填写即附带 time_range（空项补空串），后端把 start 转 >=、end 转 <= 过滤到时间维度的 source_property；time_dimension 未填时回退实体的 primary_time_dimension。若该时间维度名未定义或非时间维度，后端返回 400「时间维度 xx 未定义或非时间维度」。
• 分组维度：dimensions 勾选的维度名必须存在于实体且在该指标允许维度内，否则后端 400「维度 xx 未定义在 entity yy 中」/「维度 xx 不在指标 yy 的允许维度内」。
• 过滤条件：仅保留 field 非空的行，映射为 {field, op, value}；op 由下拉选择后端语义层算子字面量（eq/ne/not_eq/gt/gte/lt/lte/like/contains/starts_with/in/is_null，见 semantic/query.go:33-49），另设「自定义…」档保留手填入口（后端新增算子时不被锁死）；is_null 不下发 value，in 的值按逗号分隔或 JSON 数组转为数组（后端 toAnySlice 拒绝字符串，query.go:955-964）。全部经语义层白名单校验防注入，未知算子由后端拒绝（unsupported filter op %q，query.go:968）。
• 结果列兼容：columns 为数组直接渲染；为对象则取键名。行内 NULL 原样展示（前端对 query 结果未做 NULL 转换，与数据集预览页不同）。

6.5 指标类型分派

7. 权限与安全

• 认证：AIP 统一登录（aip_token）。路由 requiresAuth 拦截未登录访问；401 由 client.js 拦截器清理凭证并跳转登录页。
• 数据级安全（RLS/CLS/密级）：查询执行前 OOL 翻译注入 RLS/CLS——行级可见性 + 列级可见性 + 对象级可见性在 semantic 层统一判定；QueryMetricRequest.UserID 透传当前登录用户，属性级只读判定「无读权限属性禁止聚合」。实体建模页的「数据源 ID」直连物理数据源，查询结果与安全判定均以数据源实际配置为准。
• 写操作防护：所有写操作（创建实体/维度/度量/指标、编辑、删除）均前端 busy 置位防连点；删除指标、删除列表项（数据集等）均有 confirm 二次确认；指标删除为软删（deprecated），非物理删除。
• 翻译白名单防注入：指标查询的过滤字段必须为对象属性（语义层白名单），聚合表达式仅接受 sum/avg/count/min/max 与合法字段，杜绝前端注入任意 SQL；最终执行为参数化 SQL。

8. 常见问题与排错

8.1 查询报「metric "xx" 已停用（deprecated），不可查询」

• 现象：指标查询 Tab 选了一个旧指标，点「查询」后 alert 报「查询失败：metric "xx" 已停用（deprecated），不可查询」。
• 原因：该指标曾在指标定义 Tab 被「删除」（软删 → deprecated），或状态被手动改成 deprecated；QueryMetric 对 deprecated 指标直接拒绝执行。
• 排查步骤：① 到「指标定义」Tab 把状态筛选改为 deprecated 确认该指标状态；② 若需恢复，点「编辑」把状态改回 active 保存（版本 +1）后再查询；③ 若确实废弃，删除后从指标定义重建同名指标需注意 name 唯一索引，历史名称仍被占用时后端会返回重复键错误。

8.2 查询报「时间维度 "order_date" 未定义或非时间维度」

• 现象：查询表单填了时间维度名或开始/结束时间，提交后 400「时间维度 xx 未定义或非时间维度」。
• 原因：指标查询的时间过滤必须落在「实体维度表中 is_time_dimension=true 的维度」的 source_property 上；若实体下根本没有声明时间维度、或时间维度名拼写与实体维度名不一致，即报此错。
• 排查步骤：① 到「实体模型」Tab 选中该指标对应的实体，检查「维度」表格里是否有一条 时间维度=是 且 时间粒度 非空的维度；② 若没有，点「+ 添加维度」补一条时间维度（勾选「时间维度」+ 选粒度）；③ 确认查询表单「时间维度名」填写的就是该维度 name（不是 source_property）；④ 什么都不填时间项也可查询（跳过时间过滤）。

8.3 查询结果只有一列「metric」或列结构奇怪

• 现象：结果表格只有聚合列、没有分组维度列，或列名与预期不一致。
• 原因：dimensions 分组维度未勾选（后端只聚合不分组），或 columns 为对象形态被 Object.keys 展开；另外指标定义里「维度多选」限制了该指标允许分组维度，超出会 400。
• 排查步骤：① 在「指标查询」勾选需要的维度；② 若该指标下「维度」提示「该指标暂无可用维度」，到「指标定义」编辑该指标，确认实体已含维度且维度已在指标维度多选中勾上；③ 确认选中维度名与实体维度名一致（大小写敏感）。

8.4 实体/指标保存时按钮一直「保存中...」或卡住

• 现象：点保存后按钮变「保存中...」长时间无响应，或后续操作失效。
• 原因：busy 置位后请求挂起（后端 18081 未启动/超时 30s）、或网络请求被浏览器拦截；finally 会把 busy 复位，但若进程中断则残留。
• 排查步骤：① 确认 Foundry 后端（18081）在跑：tasklist | grep 或访问 GET /api/v1/metrics/catalog；② 浏览器 DevTools Network 查看具体请求是否 pending 或 401/500；③ 401 时确认已用 AIP 账号登录（localStorage.aip_token 存在且未过期）；④ 刷新页面复位 busy 状态后重试。

8.5 指标目录为空但指标定义列表有数据

• 现象：「指标目录」Tab 显示「暂无指标」，但「指标定义」Tab 有指标列表。
• 原因：目录数据来自独立的 GET /metrics/catalog 接口（组装时依赖实体/度量解析），若实体或度量被删除、或目录请求失败，catalog.metrics 为空或加载失败被静默处理。
• 排查步骤：① 切到「指标定义」确认列表确实有数据；② 用 API 直查 GET /api/v1/metrics/catalog 看返回是否正常（metrics 数组长度）；③ 若目录报错，到「实体模型」确认指标引用的实体/度量仍存在（metric catalog 组装对缺失实体/度量会跳过该条目）；④ 点页面任意刷新（切 Tab 重进）重载目录。

9. 已知缺陷与边界

注：查询结果 NULL 原样展示的问题已于 2026-09-06 修复（formatCell 将 null/undefined/纯空白统一显示为「NULL」，与数据集预览页文案一致）。