Notebook 分析

1. 页面概览

1.1 是什么

Notebook 分析页（Notebook · 代码工作簿）是 LightFoundry 在 V5 Stage 3（B3-1）交付的分析协作闭环页面，对标 OpenFoundry notebook-service 的 Notebook / Cell / Session 三段式模型。它以「左目录、右单元格流」的布局，让分析师在一个工作簿里混合编排三类单元格：

• markdown 单元格：写说明文字（标题、结论、注释），当前版本以「纯文本 + 预览」方式展示（.md-preview 按 white-space: pre-wrap 原样排版，尚未做富文本渲染）；
• sql 单元格：写查询 SQL，点击「运行」后由后端安全翻译执行，结果以内嵌结果表格（ResultTable 组件）呈现；
• chart 单元格：选择一个引用 SQL 单元格 + 图表类型（柱状图 / 折线图 / 饼图 / 散点图），运行后基于被引用 SQL 单元格的结果集在 chart-host 上用 ECharts 渲染，并同步展示数据表。

单元格支持逐块运行（「运行」）与全量运行（「全量运行」），每次运行结果持久化到 fn_notebook_runs，可随时在「运行历史」中回看每次运行的单元格状态与行数、耗时。SQL 单元格复用 Ontology SQL 执行器（与 SQL 工作台同源），执行时自动注入 RLS/CLS 安全口径。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/foundry/notebook
• 路由名称：FoundryNotebook
• 路由标题：Notebook 分析
• 菜单位置：Foundry 左侧边栏「Notebook 分析」（FoundryLayout 菜单项）
• 源码文件：action/web/src/views/NotebookPage.vue（431 行）

2.2 认证与权限

• 需要登录：是（路由 meta.requiresAuth = true，挂 FoundryLayout）
• 登录方式：AIP 统一登录，notebookApi.js 请求拦截器自动附加 localStorage.aip_token 为 Authorization: Bearer <token>
• 页面本身无角色限制；工作簿归属当前用户（后端 owner 由 currentUserID(c) 注入）
• 数据口径：SQL 单元格执行继承当前用户的 RLS/CLS 行级 / 列级安全约束，非授权行/列不会出现在结果中
• 404 排错：访问 /foundry/notebook 出现 404 时，先确认 Foundry 后端（18081）已启动、前端路由已注册、Vite 代理 /api 指向 18081

2.3 端口与 API 前缀

• 后端端口：18081（Foundry）
• 前端 API 前缀：/api/v1（独立 notebookApi.js axios 实例，baseURL = '/api/v1'）
• 请求超时：默认 60000ms（60 秒）；运行类请求（runCell / runAll）单独放宽到 120000ms（120 秒），适合大查询

3. 界面布局

页面采用左右两栏布局（nb-layout，左侧 240px 固定，右侧自适应）：

┌───────────────┬──────────────────────────────────────────────────┐
│ 左栏：工作簿    │ 右栏：当前工作簿                                  │
│ ① 新建输入+新建 │ ② 工具栏：名称输入 + 重命名 + 全量运行            │
│ ③ 工作簿列表    │    + Markdown / + SQL / + 图表 / 运行历史         │
│    （点击切换）  │ ④ 运行历史卡片（可收起）                          │
│                │ ⑤ 单元格流：markdown / sql / chart 卡片            │
└───────────────┴──────────────────────────────────────────────────┘

各板块职责：

• ① 左栏新建区：newName 输入框（placeholder「新工作簿名称」，回车即新建）+「新建」按钮。
• ③ 左栏列表：每个工作簿显示名称与 updated_at（nb-sub），点击切换当前工作簿（openNotebook）；「删除」按钮（link-btn）逐项删除；空列表提示「暂无工作簿，先新建一个。」；当前项高亮（li.active）。
• ② 工具栏：当前工作簿名称（nbNameDraft 可编辑）+「重命名」；「全量运行」（运行中变「运行中...」并禁用）；三个添加单元格按钮（+ Markdown / + SQL / + 图表）；「运行历史」开关（显示时变「收起历史」）。
• ④ 运行历史卡片：表格展示最近 N 次运行（时间 / 创建者 / 单元格数 / 状态徽标），每次运行的状态按单元格粒度以 status-badge 显示 success/error。
• ⑤ 单元格流：按 ord 升序纵向排列的单元格卡片，每张卡片头部是类型徽标 + #ord + 最近运行结果摘要（状态 · N 行 · Xms）+ 操作按钮，正文按类型渲染。

未选择工作簿时右栏显示占位文案「从左侧选择或新建一个工作簿开始。」；空工作簿显示「空工作簿，点击上方按钮添加单元格。」

4. 交互元素详解

4.1 工作簿目录（左栏）

4.2 工具栏

4.3 单元格卡片

每张单元格卡片头部（cell-head）包含：类型徽标（ct-badge，markdown 紫 / sql 蓝 / chart 橙）、#ord 序号、最近运行结果摘要（status · row_count 行 · elapsed_ms ms，有结果才显示），右侧三个按钮：

4.4 三类单元格正文

chart 单元格配置区（chart-cfg）：

• 「选择引用的 SQL 单元格」下拉：v-model="cell.chartConfigCellId"，选项为 #ord + SQL 前 30 字符（来源 sqlCells 计算属性，仅当前工作簿中 cell_type === 'sql' 的单元格）。
• 图表类型下拉：bar（柱状图）/ line（折线图）/ pie（饼图）/ scatter（散点图）。
• 运行后若有结果列，在 .chart-host[data-cell="id"]（高 260px）用 ECharts 渲染，tooltip 轴触发、x 轴取第 0 列、y 轴取第 1 列；饼图半径 60%；同时下方展示数据表。

4.5 运行历史表格

5. 后端关联

5.1 API 客户端

• 文件：action/web/src/api/notebookApi.js
• baseURL: '/api/v1'，默认 timeout: 60000，请求头 Content-Type: application/json
• 请求拦截器：附加 aip_token Bearer；响应拦截器：401 清 token 并跳登录
• 导出函数：listNotebooks / createNotebook / getNotebook / updateNotebook / deleteNotebook、listCells / addCell / updateCell / deleteCell、runCell（120s）/ runAll（120s）/ listRuns

5.2 端点表（前缀 /api/v1，均挂 protected）

5.3 响应结构（JSON 示例）

工作簿详情 GET /notebooks/:id：

{ "code": 0, "data": {
  "notebook": { "id": "...", "rid": "notebook://foundry/...", "name": "销售分析",
                "description": "", "owner": "550e8400-...",
                "created_at": "...", "updated_at": "..." },
  "cells": [
    { "id": "...", "notebook_id": "...", "ord": 1, "cell_type": "markdown",
      "content": "# 标题", "created_at": "...", "updated_at": "..." },
    { "id": "...", "ord": 2, "cell_type": "sql",
      "content": "SELECT name, amount FROM order WHERE amount > 100 LIMIT 10" },
    { "id": "...", "ord": 3, "cell_type": "chart",
      "chart_config": "{ \"cell_id\": \"...\", \"chart_type\": \"bar\" }" }
  ]
} }

单格运行 POST /notebooks/:id/cells/:cid/run：

{ "code": 0, "data": {
  "status": "success", "elapsed_ms": 42, "row_count": 10,
  "columns": ["name", "amount"], "rows": [["张三", 1200], ["李四", 980]]
} }

全量运行 POST /notebooks/:id/run：

{ "code": 0, "data": {
  "id": "run-uuid", "notebook_id": "...", "created_by": "550e8400-...",
  "cell_results": {
    "cell-id-2": { "status": "success", "elapsed_ms": 40, "row_count": 10,
                   "columns": [...], "rows": [...] },
    "cell-id-3": { "status": "success", "elapsed_ms": 1, "row_count": 10,
                   "columns": [...], "rows": [...], "chart_type": "bar", "source_cell": "cell-id-2" }
  }
} }

5.4 关联模块

5.5 关键机制

• 单元格排序：fn_cells.ord 决定执行顺序，ListCells 按 ord 升序返回。
• chart 单元格不重算：chart 单元格依赖其引用的 SQL 单元格结果集「渲染配置（不重算）」——RunAll 内以同批顺序执行的内存结果传递；独立 RunCell 回退到最近一次 run 的缓存结果，均不重新执行被引用 SQL 单元格。
• 运行记录：RunAll 顺序执行全部单元格并落 fn_notebook_runs，cell_results 为 {cell_id: CellResult} JSON；CellResult 含 status(success|error)、elapsed_ms、row_count，chart 单元格附 chart_type / source_cell。
• 单格运行：POST .../cells/:cid/run 由 RunCell 执行，chart 单元格回退缓存，返回单格 CellResult。
• 错误容错：Results() / ParseSnapshot() 对非法 JSON 返回空结构不报错（历史数据容错）。

6. 核心流程详解

6.1 新建工作簿主流程

1. 左栏输入新名称（或直接回车）→ 点「新建」。
2. 调 createNotebook({name, description: ''}) → 提示「工作簿已创建」→ fetchNotebooks() 刷新列表 → openNotebook(data.data) 自动打开。
3. 打开后 getNotebook 拉详情，将每个单元格的 chart_config JSON 解析为 chartConfigCellId / chartType（前端编辑态字段），并 loadRuns() 加载运行历史。

6.2 添加与编辑单元格流程

1. 点「+ Markdown / + SQL / + 图表」→ handleAddCell(type)：
   • 构造默认 content（markdown # 新说明、sql SELECT * FROM 、chart 空）；
   • chart 单元格默认 chart_config = { cell_id: sqlCells[0]?.id || '', chart_type: 'bar' }；
   • 调 addCell 后将新单元格 push 进本地 current.cells，再调 refreshCells() 与后端对齐。
2. 编辑单元格内容（textarea 双向绑定 cell.content），点「保存」调 updateCell。
3. 点「运行」单格：先 saveCell(cell) 保存当前编辑，再 runCell，结果写入 cellResults[cell.id]，chart 单元格 nextTick 后 renderChart。

6.3 全量运行流程

1. 点「全量运行」（handleRunAll）→ running=true，按钮变「运行中...」。
2. 调 runAll(id)：后端按 ord 顺序执行全部单元格（SQL 取数、chart 渲染配置传递），落 fn_notebook_runs。
3. 前端将 run.cell_results 整体写入 cellResults，随后 refreshCells() 对齐单元格列表，nextTick 后为每个 chart 单元格执行 renderChart，最后 loadRuns() 刷新历史并提示「全量运行完成」。

6.4 运行历史回看

1. 点工具栏「运行历史」展开面板（默认收起）。
2. loadRuns() 调 listRuns(id, limit=0) 拉取全部运行记录；每行展示时间 / 创建者 / 单元格数 / 各单元格状态徽标。
3. 单元格数取 Object.keys(run.cell_results || {}).length；状态按每个 cell 的 status 分别打徽标。

6.5 删除分支流程

• 删除单元格：confirm → deleteCell → 清 cellResults[cell.id] → refreshCells()。
• 删除工作簿：confirm → deleteNotebook → 若为当前工作簿则 current=null → 刷新列表。

7. 权限与安全

• 认证：全部端点要求 aip_token（protected 组）；401 时 notebookApi.js 响应拦截器清理 token 并跳登录。
• 归属隔离：工作簿 owner 由服务端 currentUserID(c) 注入，ListNotebooks / UpdateNotebook / DeleteNotebook 均按当前用户过滤。
• 数据级安全：SQL 单元格执行走 Ontology SQL 执行器，自动注入 RLS（行级）/ CLS（列级），未授权行/列不会进入结果集；前端无法绕过。
• 写操作防护：删除工作簿 / 删除单元格均有 window.confirm 二次确认；运行中 running 置位禁用「全量运行」与「运行」按钮防重复触发。

8. 常见问题与排错

8.1 添加 / 删除 / 全量运行时报「listCells is not defined」（已知缺陷）

• 现象：点「+ SQL」「+ 图表」「删除」或「全量运行」后，提示「添加单元格失败：listCells is not defined」「删除失败：listCells is not defined」或「全量运行失败：listCells is not defined」。
• 原因：NotebookPage.vue 的 refreshCells()（约 278-289 行）调用了 listCells，但 script 顶部 import（约 155-158 行）未导入 listCells——handleAddCell / handleDeleteCell / handleRunAll 触发时抛 ReferenceError。listCells 实际已在 notebookApi.js 中导出（GET /notebooks/:id/cells），仅组件 import 遗漏。
• 排查与规避：① 查看浏览器 Console 确认 listCells is not defined；② 规避方式：添加/删除单元格后「刷新页面」重新打开工作簿，单元格实际已写入后端（添加成功、删除成功），仅前端列表未刷新；全量运行时 cell_results 已写入内存，但图表渲染与成功提示被跳过；③ 彻底修复需在源码 import 语句补 listCells（本手册不改源码，待前后端修复）。

8.2 新建工作簿后右侧仍是空

• 现象：左栏列表有工作簿，但右侧显示「从左侧选择或新建一个工作簿开始。」
• 原因与排查：openNotebook(data.data) 依赖创建接口返回的 data.data 对象；若返回结构不符（如 data 为空），可能未正确打开。可手动点击左栏列表项切换；仍失败则检查 Network 中 GET /notebooks/:id 响应结构是否含 notebook 与 cells。

8.3 SQL 单元格运行后显示红字错误

• 现象：单元格结果区出现 error 红字（如 SQL 语法错误、表不存在、无权限）。
• 原因：SQL 经 Ontology SQL 执行器翻译执行失败；或 RLS/CLS 过滤后无可见数据。
• 排查：① 检查 SQL 是否使用对象名而非物理表名；② 对照 SQL 工作台的翻译预览确认对象/属性名；③ 确认当前用户对该对象具备查询权限；④ 查看后端日志中执行器返回的具体错误。

8.4 图表单元格不渲染

• 现象：chart 单元格运行后没有出现 ECharts 图表。
• 排查：① 确认已选择「引用的 SQL 单元格」且该 SQL 运行出数（cellResultOf(cell).columns 非空才会渲染）；② 确认图表类型为 bar/line/pie/scatter 之一；③ 若触发了 8.1 的缺陷（全量运行），先手动单格「运行」chart 单元格；④ 打开 Console 看是否有 ECharts 初始化报错（如 DOM 未挂载）。

8.5 运行历史不刷新

• 现象：运行后「运行历史」仍是旧数据。
• 排查：① loadRuns() 为静默失败（catch 无提示），检查 Network GET /notebooks/:id/runs 是否 4xx/5xx；② 确认 current.value 已设置（未打开工作簿时不加载）；③ 单格运行与全量运行都会触发 loadRuns()，若中途抛错（如 8.1）可能未执行到刷新逻辑，手动点「运行历史」收起再展开可触发一次 loadRuns。

9. 已知缺陷与边界

注：listCells 未导入缺陷已于 2026-09-06 修复（源码 import 已补 listCells），添加/删除/全量运行不再抛 ReferenceError。