图谱映射

1. 页面概览

图谱映射页（GraphMappingPage.vue）是 LightGotham V5 Stage 4 图谱域（B4-1）的「行级图谱化导入」配置与执行入口：它把一个多源接入的数据源表，按配置的行级映射规则（节点类型、节点 ID 列、属性列、外键边规则、时间列）批量转化为图节点与边，落库到 Gotham 图存储。页面先列数据源并探测各源图谱映射是否已配置，选中 database 型源后提供「自动建议（读 schema + 外键探测）」一键回填表单、「保存配置」（一源一映射 upsert）、「执行图谱化」（任务化提交 + 每秒轮询 GET /tasks/:id 展示任务进度与结果，勾选先融合导入时另经 SSE 追踪本次导入批次进度）。

一句话总结：图谱映射页把"表数据 → 图数据"变成可视化配置、任务化执行、进度可查的标准操作。

2. 访问入口

• 路由 path /gotham/graph-mapping、name GothamGraphMapping、meta.title「图谱映射」、requiresAuth 为真，挂在 GothamLayout 子路由；侧边栏入口见 GothamLayout.vue 菜单「图谱映射」。前端源码 action/web/src/views/gotham/GraphMappingPage.vue（653 行），API 客户端 action/web/src/api/graphMappingApi.js。
• 认证：aip_token + gotham_refresh_token（gothamClient 401 自动刷新）；本页接口挂在 protected 组，任意登录用户可操作。
• 端口 18083，API 前缀 /gotham-api/v1。

3. 界面布局

+---------------------------------------------------------------+
| Gotham 行级图谱化   [刷新]                                     |
+---------------------------------------------------------------+
| [alert 操作结果提示条（可关闭）]                               |
+---------------------------------------------------------------+
| [数据源列表（N）]  ID|名称|显示名|来源类型|图谱映射|操作       |
|   每行：[配置图谱映射]（仅 database 型可点）                    |
+---------------------------------------------------------------+
| [图谱映射配置 —— 数据源 #id「名称」（connector=xxx）]（选中后）|
|  table_name* / node_type* / node_id_col* / node_label_col      |
|  time_col / chunk_size / enabled                               |
|  [自动建议（读 schema + 外键探测）] [清除建议]                  |
|  属性列 prop_cols（勾选列 / JSON 兜底）                         |
|  外键边规则 edge_rules  [+ 添加边规则]（行内增删）              |
|  [保存配置] [执行图谱化]  ☑先融合导入（include_ingest）         |
+---------------------------------------------------------------+
| [图谱化任务 #id（提交后）]  状态 / 进度条% / 消息 / 结果 / 错误  |
|   导入批次：Batch #id + 状态徽标 / 批次进度条 + 已处理/总数(失败) |
+---------------------------------------------------------------+

• 页头：标题 +「刷新」（重载数据源与配置状态）。
• 数据源列表：全部接入源，标记来源类型与图谱映射已配置/未配置/未知。
• 映射配置表单：仅在选中 database 型源后出现，含基础映射字段、自动建议、属性列、边规则。
• 任务进度卡片：提交「执行图谱化」后展示任务状态、进度条、消息、结果与错误；勾选「先融合导入」时额外展示导入批次进度（批次号、状态徽标、processed/total 进度条与失败数）。

4. 交互元素

5. 后端关联

关键机制

映射模型：GraphMappingRequest 字段 table_name / node_label_col / node_id_col / node_type / prop_cols（{属性名:列名}） / time_col / edge_rules[] / chunk_size / enabled；边规则 EdgeRule{type, from_col, to_table, to_column, to_node_type} 描述本表外键列指向目标节点类型；time_col 把行时间写入边属性 occurrence_time（时序分析页依赖）。

任务化执行：POST map-to-graph 提交 gotham_graph_mapping 类型任务；include_ingest=true 时先在同一任务内同步执行融合导入（进度并入 5%~35%），再执行行级图谱化（keyset 分页拉行 → UpsertNode/UpsertEdge 幂等）。任务结果 GraphMappingResult 含 nodes_imported / edges_created / edges_skipped（悬挂边跳过数）。

任务状态机：queued → running → success / failed（可 cancelled）；前端把 success/failed/cancelled 视为终态并停止轮询，success 时读取结果提示「节点 N，边 M（跳过 K）」并刷新数据源列表，failed 时展示 task.error。

自动建议：mappingSuggest 读源表 schema 全列（供勾选）+ 外键探测，返回 columns / prop_cols / edge_rules 建议，前端「保存配置」后才落库。

导入批次进度（SSE）：GET /ingestion/batches/:id/progress 是 SSE（text/event-stream），事件体为 ProgressEvent{batch_id, processed, total, status}（fusion/progress.go:17-22），status ∈ running|paused|completed|failed；事件不含失败数（failed 数取自 GET /ingestion/batches/:id 的 failed_records，页面在订阅期与流结束时各刷新一次）。因 EventSource 无法带 Authorization 头，前端用 fetch + ReadableStream 读流并按 \n\n 切帧解析 data: 行（与本仓库多源接入页同一写法）。

批次定位策略：map-to-graph 只返回 task、不返回 batch_id，故页面在提交前记下该源已有批次的最大 id 作基线，提交后 30s 内每秒拉 GET /ingestion/batches?source_id= 找 id 更大的新批次（避免误挂历史批次）；命中后停探测并订阅 SSE，未命中（如 include_ingest=false 或任务提前失败）则停止探测、不下发无谓请求。

6. 权限与安全

• 认证：JWT Bearer；401 由 gothamClient 拦截器用 refresh token 换新后重放，刷新失败跳登录页。
• 角色：本页接口挂 protected 组（未加 admin 门禁），任何登录用户可配置与执行；但接口作用于已接入数据源，需用户有数据源接入权限（多源接入页创建）。
• 写操作防护：映射保存前有必填校验（table_name/node_id_col/node_type）与 JSON/边规则校验；任务执行记录操作者（currentUserID）。

7. 常见问题与排错

7.1 数据源列表为空

• 现象：表格显示「暂无数据源（请先在『多源接入』页创建）」。
• 原因：Gotham 未接入任何数据源。
• 处理：先到多源接入页（ingestion）创建数据源；确认 GET /ingestion/sources 有返回。

7.2 「配置图谱映射」点击无反应

• 现象：非 database 型源按钮禁用，提示「仅 database 型数据源支持行级图谱化」。
• 原因：页面只支持 database 型源行级图谱化。
• 处理：改用 database 型数据源。

7.3 「执行图谱化」后进度卡住

• 现象：任务卡片状态停在 queued/running，进度条不动。
• 原因：GET /tasks/:id 轮询路由已在 Gotham 后端注册可用（platform/task.RegisterRoutes，server.go:537），此时多为任务确在 queued/running 但执行较慢，或后端进程未启动导致轮询失败。
• 处理：查看 DevTools Network 确认轮询 GET /tasks/:id 返回状态码与 status 是否推进（200 且在变化属正常）；确认后端已挂 /tasks/:id 路由且 taskMgr 注入；重启后端使 taskMgr.Restore 恢复任务。

7.4 自动建议失败

• 现象：提示「自动建议失败：...」。
• 原因：未填 table_name（前端拦截）、表不存在或连接器不支持 schema 读取。
• 处理：先填正确的源表名；在数据源页测试连接；确认连接器类型已放行。

7.5 勾选「先融合导入」后看不到批次进度条

• 现象：任务进度条在走，但「导入批次」行长期停在「等待本次融合导入批次创建…」。
• 原因：批次由任务执行器在导入开始时才创建（graph_mapping.go:511）；若超过 30s 未出现（如任务在导入前即失败），页面停止探测且不再显示批次行。也可能是本次未勾选「先融合导入」（此时显示的是「无导入批次进度」的说明文案）。
• 处理：确认勾选「先融合导入」；查看 Network 中 GET /ingestion/batches?source_id= 是否有新批次、/ingestion/batches/:id/progress 是否 200 且有 data: 帧。

7.6 批次进度条到 100% 但任务仍未结束

• 现象：导入批次行显示 completed，上方任务仍在 running。
• 原因：include_ingest=true 时同一任务在导入完成后还要继续执行图谱化（graph_mapping.go:519），而批次进度只反映导入阶段。
• 处理：属预期行为；以任务进度条（GET /tasks/:id）为整体终态依据。

8. 已知缺陷与边界