SQL 工作台（Ontology SQL Workbench）

1. 页面概览

1.1 是什么

SQL 工作台是 LightFoundry 提供的一块「对象名直查的受限只读 SQL」查询界面（V5 Stage 1 B1-4 交付）。用户可以用业务对象名（api_name / object_ 前缀 / 物理表名）直接编写 SELECT 语句，由后端将其翻译为真实的物理 SQL 再执行，从而：

• 不需要知道物理库的表名与列名：FROM orders 会被后端解析成真实的物理表（或对应数据源表），amount 会被映射为物理列。
• 天然获得安全闸门：执行前自动注入 RLS（行级安全）与 CLS（列级安全），非授权的行与列不会出现在结果中；只读强制、标识符白名单、LIMIT 钳制全部由后端保证，前端无法绕过。
• 能看到「翻译」过程：通过「翻译预览」Tab，用户可以查看对象 SQL 被翻译成的物理参数化 SQL、绑定参数、生效的 LIMIT 与安全注入状态，便于审计口径。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/foundry/sql
• 路由名称：FoundrySqlWorkbench
• 菜单位置：Foundry 左侧边栏「SQL 工作台」（FoundryLayout 菜单第 9 项）
• 源码文件：action/web/src/views/SqlWorkbenchPage.vue（352 行）

2.2 认证与权限

• 需要登录：是（路由 meta.requiresAuth = true）
• 登录方式：AIP 统一登录，localStorage.aip_token 作为 Bearer Token
• 页面本身无角色限制，但查询结果受后端 RLS/CLS 约束：普通用户只能看到自己被授权的行与列；RLS/CLS 配置在「数据打标 / 安全治理」等页面完成。
• 404 排错：若访问 /foundry/sql 出现 404，先确认 Foundry 后端（端口 18081）已启动且前端路由已注册。

2.3 端口与 API 前缀

• 后端端口：18081（Foundry）
• 前端 API 前缀：/api/v1（queryApi.js，独立 axios 实例，不是 client.js）
• 请求超时：默认 60 秒；执行查询（execute）单独放宽到 120 秒，适合大表查询。

3. 界面布局

页面纵向分为 6 个板块（从上到下）：

┌──────────────────────────────────────────────────────────────┐
│ ① 页头：标题「SQL 工作台」+ 一句话说明                         │
│ ② 操作结果提示条（alert，成功后绿色 / 失败后红色，可关闭）       │
│ ③ 查询编辑卡片                                                │
│    ├─ 对象下拉（点击注入模板）        ── LIMIT 输入框（可空）  │
│    ├─ Ontology SQL 多行编辑框（textarea）                      │
│    └─ [▶ 运行查询] [翻译预览] [导出 CSV] 三个按钮              │
│ ④ Tab 切换（有结果或翻译后才出现）：[查询结果] [翻译预览]      │
│ ⑤ 查询结果卡片（结果表格 + 元信息注记 + 编辑态叠加高亮）        │
│ ⑥ 翻译预览卡片（物理 SQL + 翻译元信息表 + 绑定参数）           │
└──────────────────────────────────────────────────────────────┘

各板块职责：

• ① 页头：说明本页能力边界（受限只读 SQL）。
• ② 提示条：页面内唯一的消息反馈区，展示查询/翻译的成功或失败信息。
• ③ 查询编辑：所有查询入口。对象下拉用于快速注入模板 SQL，LIMIT 可覆盖默认值。
• ④ Tab 切换：仅当存在查询结果或翻译结果时才出现，避免空 Tab 干扰。
• ⑤ 查询结果：结果表格、行数/耗时、安全注记、编辑态叠加列高亮。
• ⑥ 翻译预览：物理参数化 SQL 与翻译元信息（对象、物理表、列、LIMIT、RLS/CLS、叠加注记），是排查「查询结果不对」的第一现场。

4. 交互元素详解

4.1 对象下拉（点击注入模板）

交互效果：选中任意对象后，编辑器被覆盖注入为模板 SQL：

SELECT *
FROM {api_name}
LIMIT 100

注入后下拉框自身 value 立即重置为空（e.target.value = ''），避免重复选中同一项不触发 change 事件。

4.2 LIMIT 输入框（可空）

4.3 Ontology SQL 编辑框

编辑器占位提示里给出的经典示例：SELECT name, amount FROM orders LIMIT 10。

4.4 三个操作按钮

• 三个按钮在 busy 状态下均禁用；运行/翻译按钮在 SQL 为空时禁用。
• 按钮文案在运行中变为「执行中...」。

4.5 Tab 切换

• 出现条件：translated 非空 或 result.columns.length > 0（即至少有一种结果）。
• 两个 Tab：查询结果（默认）与 翻译预览。
• 切换仅改前端 activeTab，不发请求。

4.6 查询结果卡片

• 标题：结果（N 行，X ms）；若存在编辑态叠加字段，右侧追加绿色 tag：编辑态叠加: field1, field2。
• 元信息注记（metaNote，蓝色条）：按优先级拼接——RLS 已注入 / CLS 已注入 / 安全注入未生效（security_note）/ 编辑态叠加注记（overlay_note）。
• 表格：首行为列名，单元格 null 显示为 NULL；被编辑态叠加覆盖的列以绿色高亮（edited-cell 类）区分。
• 空态：无结果时显示「尚无结果：编写 SQL 后点击"运行查询"」。

4.7 翻译预览卡片

limit_mode 取值（前端 limitModeLabel 映射）：

5. 后端关联

5.1 依赖的 API 客户端

action/web/src/api/queryApi.js（独立 axios 实例）：

• baseURL: '/api/v1'，Content-Type: application/json
• 请求拦截器：localStorage.aip_token → Authorization: Bearer <token>
• 响应拦截器：401 时清空 aip_token / aip_username 并跳转 /login
• 导出三个函数：listObjects / translateOntologySQL / executeOntologySQL

5.2 调用的后端端点

5.3 响应结构

translate 成功（{code:0, data:{...}}）：

{
  "code": 0,
  "data": {
    "physical_sql": "SELECT \"order_id\", \"amount\" FROM \"orders\" WHERE \"amount\" > ? ORDER BY \"amount\" DESC LIMIT 50",
    "args": ["100"],
    "meta": {
      "objects": ["order"],
      "base_tables": ["orders"],
      "columns": ["order_id", "amount"],
      "limit_applied": 50,
      "limit_mode": "user",
      "rls_injected": true,
      "cls_injected": false,
      "security_note": "",
      "overlay_note": ""
    }
  }
}

execute 成功（{code:0, data:{...}}）：

{
  "code": 0,
  "data": {
    "columns": ["order_id", "amount"],
    "rows": [["O-1001", "259.00"]],
    "edited_fields": ["amount"],
    "row_count": 1,
    "elapsed_ms": 12,
    "meta": { "limit_applied": 50, "limit_mode": "user", "rls_injected": true, "cls_injected": false }
  }
}

失败（统一错误结构）：{ "code": "<错误码>", "error": "<错误详情>" }，HTTP 状态码由后端 ierr 错误映射（如 400/403/500）。

5.4 关联的后端模块与服务

5.5 后端强制安全口径

6. 核心流程详解

6.1 一次完整查询的主流程

页面加载
  └─ onMounted(fetchObjects)
       └─ GET /ontology/objects?status=merged → 填充对象下拉（失败仅 console.warn，不阻断）

用户操作
  1. 可选：选择对象下拉 → 注入模板 SQL `SELECT * FROM {name} LIMIT 100`
  2. 编辑 SQL（可改 LIMIT 输入框）
  3. 点击「▶ 运行查询」
       ├─ busy=true，按钮禁用，文案「执行中...」
       ├─ POST /ontology/sql/execute {sql, limit}
       │    ├─ 后端：校验只读/单语句/白名单 → 翻译 → RLS/CLS 注入 → LIMIT 钳制 → 执行 → 叠加编辑态
       │    └─ 返回 columns/rows/edited_fields/elapsed_ms/meta
       ├─ 前端：计算 editedColumns 下标集合，拼 metaNote，切「查询结果」Tab
       └─ busy=false，alert 绿色「查询完成：N 行（LIMIT X）」

6.2 翻译预览流程

点击「翻译预览」
  ├─ POST /ontology/sql/translate {sql}（不执行，纯翻译回显）
  └─ 切「翻译预览」Tab：物理 SQL / 元信息表 / 绑定参数

翻译与执行共用同一套翻译逻辑，因此「先翻译、后执行」可预判结果是否合规（如 RLS 是否注入、LIMIT 是否被钳制）。

6.3 编辑态叠加（Edited Fields）机制

• 后端在返回结果前，会探测 ontology_edits 表中当前对象类型是否存在未合入的草稿修改（编辑态叠加层）。
• 叠加逻辑在分页/排序之后对返回行生效（LIMIT/ORDER 后叠加），保证编辑值不会因分页而错位。
• 前端将 edited_fields 映射为列下标（editedColumns Set），对命中列做绿色高亮；标题区显示「编辑态叠加: 字段名」。
• 注意：叠加的是展示层结果，row_count 仍是物理行数。

6.4 CSV 导出流程（纯前端）

点击「导出 CSV」（需已有结果）
  ├─ 取当前 result.columns + result.rows（仅当前结果页，不做后端分页）
  ├─ 每个单元格转字符串；含逗号/引号/换行时用双引号包裹并转义（""）
  ├─ 首行 BOM \uFEFF + 表头 + 数据行，\n 连接
  └─ Blob(text/csv;charset=utf-8) → URL.createObjectURL → <a download> 触发下载
     文件名：query_result_YYYY-MM-DD-HH-mm-ss.csv

7. 权限与安全

7.1 认证

• 使用 aip_token（JWT）Bearer 认证；401 会自动清理登录态并跳转 /login。
• 后端 authMiddleware 从 token 解出 user_id 注入 gin 上下文，供 RLS/CLS 使用。

7.2 数据级安全（查询阶段生效）

• RLS 行级：查询自动追加基于 user_id 的守卫条件，且位于 LIMIT 之前，防止越权行进入分页结果。
• CLS 列级：未授权的列以 NULL AS col 隐藏；若结合 V5 Stage 5 的 Markings 密级，属性级安全块会合并 marking 隐藏（任一来源隐藏即隐藏）。
• 用户在翻译预览的元信息表中可确认「RLS/CLS 是否已注入」；若显示「安全注入未生效」，通常是未配置 RLS/CLS 策略（属正常配置态，不是错误）。

7.3 写操作防护

• 页面没有任何写入口；后端对 SELECT 之外的所有语句（INSERT/UPDATE/DELETE/DDL 等）直接拒绝。
• 「修改数据」必须走 Foundry 的 Action 唯一写路径（Action 测试页 / 工作流），本页只读。

8. 常见问题与排错

8.1 点击「运行查询」报错，无任何结果

现象：alert 红色「查询失败：...」，结果区空。

排查步骤：

1. 先点「翻译预览」，若翻译也失败，说明 SQL 语法或对象名有问题——查看报错 error 字段（如 invalid SQL、object not found: xxx）。
2. 若翻译成功但执行失败：确认对象状态是否 merged（草稿对象不可查询），或物理表/列是否存在。
3. 确认后端 18081 已启动：浏览器开发者工具 Network 面板看请求是否 502/404。
4. 查看 Foundry 后端日志定位服务层错误（query 包与 semantic 包）。

8.2 结果被截断，行数不对

现象：row_count 正好是 500 或 5000。

原因：LIMIT 钳制——未写 LIMIT 补默认 500，超上限钳到 5000。这是安全设计，不是 bug。

处理：在 SQL 中显式写 LIMIT N（≤5000），或观察翻译预览「生效 LIMIT（limit_mode）」字段确认实际生效值。

8.3 某些列显示为 NULL，或整列消失

现象：翻译元信息显示 CLS 已注入，列值全为 NULL。

原因：当前用户无该列权限（CLS 列级安全），或该列被 Markings 密级隐藏。

处理：

• 确认为「安全行为」而非数据问题：换管理员账号验证列数据存在。
• 需要查看列：请管理员在「数据打标 / 安全治理」中调整 CLS/密级授权。

8.4 查询结果里有绿色高亮列，数值与库里不一致

现象：某列绿色高亮，标题区有「编辑态叠加」tag。

原因：该对象存在未合入的草稿编辑（编辑态叠加层），查询结果展示的是叠加后的值。

处理：这是设计行为。若希望看到物理库原始值，需等待编辑态合入/回滚（见 Foundry 本体工作台版本状态机）。

8.5 导出 CSV 用 Excel 打开中文乱码

原因：CSV 已带 UTF-8 BOM，正常情况下 Excel 可识别；若仍乱码，多为编辑器/其它程序未按 UTF-8 读取。

处理：用 Excel「数据→自文本/CSV」导入并选择 UTF-8；或先用记事本另存为带 BOM 的 UTF-8。

8.6 想用 link 关联属性（linkName.prop）取数

现象：写 linkName.prop 报不支持。

原因：本版不支持 link 属性隐式解析。

处理：显式 JOIN 目标对象后用 别名.属性，例如：

SELECT o.amount, c.name
FROM orders o
JOIN customers c ON c.id = o.customer_id
LIMIT 100

8.7 查询执行超过 60 秒被中断

现象：请求在 60 秒左右失败。

说明：execute 端点超时放宽到 120 秒；若仍超时，多为数据量大或物理表缺索引。

处理：缩小结果集（LIMIT、加 WHERE 过滤条件）；检查物理表索引；必要时在数据管道层做预聚合。

9. 已知缺陷与边界

注：对象下拉失败静默已于 2026-09-06 修复（失败改为页面级 alert-error 提示，并说明仍可手写 SQL、「对象注入模板」暂不可用）。

注：CSV 仅导出当前已加载行且无提示的问题已于 2026-09-06 修复（导出前明确提示「仅当前已加载 N 行」；如需全量请调大 LIMIT 或按范围拆分查询）。

10.2 后端相关

• REST：action/products/foundry/query/rest.go
• 服务层：action/products/foundry/query/（translate.go、execute.go 等）
• 语义安全：action/products/foundry/semantic/（RLS/CLS 注入、edit_overlay.go）
• 契约测试：action/products/foundry/server/contract_test.go、query/translate_test.go

10.3 项目文档

• V5 总纲：action/wiki/upgrade-v5/UPGRADE-PLAN.md（B1-4 Ontology SQL 工作台）
• Stage 1 交付：action/wiki/upgrade-v5/dev-story/stage-1.md
• 变更记录：action/wiki/changelog/2026-08-29-3-v5-stage2.md（B1-4 相关章节）
• 产品矩阵：action/wiki/OVERVIEW.md
• 本系列索引：../index.md（总索引）与 index.md（Foundry 索引）

10.4 相邻页面

• 本体工作台（foundry-home.html）：对象/属性/链接定义，SQL 工作台的数据来源
• 数据源（data-sources.html）：物理表来源与元数据导入
• 数据打标（markings.html）：CLS 密级隐藏列与本页 CLS 注入的联动
• 代码仓库（coderepo.html）：SQL 宏仓库，Execute 入口的宏展开来源