业务故事站
P4 Gotham

图谱入门：从一张图看懂关系网络

打开图工作台浏览玄武集团的 10 节点 8 边关系网络，点击高亮邻居、手动补节点补边、看全图统计——看完这 4 个故事，你就能把散在卷宗里的"谁和谁有关"变成一张看得懂的关系网。

情报分析员 经侦侦查员 节点与边 邻居高亮 图统计 手动建图 共 4 个故事

能 / 不能速览

✅ 这个主题能做
  • 打开图工作台浏览全量节点，person / org / ship 三类分色渲染
  • 点击节点高亮邻居，理解 member_of / transferred_to / operates 等关系
  • 手动新增节点、新增边补充情报，幂等 upsert、改动自动落盘
  • 页内「图谱元素管理」可直接删除节点 / 边：二次确认（展示 RID / 关系），节点删除级联清理关联边，403（无权限）/ 404（已不存在）分开提示
  • 默认中心节点可配：3 度展开与最短路径起点读取页内配置（未配置回退 graph:person:zhy），一键恢复默认；路径终点记忆上次使用值
  • 子图查询结果表分页展示：条数档 50 / 100 / 200 / 全部 + 上 / 下一页 + 「显示第 X-Y 条，共 N 条」
  • 查看全图统计（/graph/stats）与单节点详情（/graph/nodes/:id）
  • SVG 力导向图：点击高亮、拖拽平移、搜索过滤、实体详情面板
⛔ 这个主题做不了
  • 图分析（expand / path / centrality / community）仅 admin 角色可执行，普通账号会 403
  • /graph/stats 只有节点、边总数，没有按类型分布的统计，需前端本地聚合
  • 图存储默认是自研磁盘实现（内存邻接表 + JSON 落盘）；Neo4j 可选后端已在代码中就绪，但需在配置 gotham.graph.mode=neo4j 时启用
  • 删除节点会级联删除相关边，误删需谨慎；大图虚拟化渲染属后续能力

适用角色

本主题面向两类角色：

  • 情报分析员：核心使用者，把散落线索组织成关系网，用图发现问题、汇报结论。
  • 经侦 / 侦查员：浏览关系网络、点击邻居、补充新情报，为案件侦查提供线索。

图分析类能力由管理员（admin 角色）执行；普通分析员以浏览、补点、补边为主。

能力速览（能做什么）

图工作台

自研 SVG 力导向图：10 节点 8 边一目了然，person / org / ship 分色，点击高亮邻居、拖拽平移；默认展开的中心节点可在页内配置（本地保存、可恢复默认）。

节点与边 CRUD

新增 / 查询 / 删除节点与边，幂等 upsert；边按 source+type+target+direction 派生稳定 ID；删除在页内「图谱元素管理」完成，二次确认并区分 403（无权限）/ 404（已不存在）。

邻居高亮

点击节点即时高亮直接关联方，深度可调（默认 1 跳），非关联节点置灰淡化。

全图统计

/graph/stats 返回节点与边总数，/graph/nodes/:id 返回单节点完整属性。

界面操作指引（不写代码怎么用）

下面按「打开哪个页面 → 点哪里 → 填什么 → 看到什么」的顺序给出完整操作路径，业务用户照做即可。每步末尾的「API 等价」是给工程师对照用的，可以忽略。

1 打开「情报工作台」看图 Gotham 控制台 → 情报工作台（/gotham）
  • 怎么做：左侧边栏第一项点「情报工作台」，页面加载即展示玄武集团关系网。
  • 会看到：页头统计芯片「节点 10 / 边 8」，520px 高的 SVG 画布上 person 蓝 / org 橙 / ship 绿三色节点与带箭头连线。

API 等价：GET /api/v1/graph/stats、GET /api/v1/graph/nodes

2 点击节点高亮邻居 情报工作台 → 图谱可视化画布
  • 怎么做：鼠标点一下「玄武集团」节点；想看别的区域可按住画布拖拽平移。
  • 会看到：玄武集团的直接关联方（张远、李四、天河贸易）高亮，其余节点自动置灰（dimmed）。

API 等价：GET /api/v1/graph/nodes/graph:org:xuanwu/neighbors（加 ?depth=2 看两跳）

3 补一条情报：新增节点与边 情报工作台 → 新增节点 / 边
  • 怎么做：左侧表单填 type=person、label=陈强，properties 里写 region=华南，提交；再在右侧表单填 source、target、type=associated_with、direction=bidirectional。
  • 会看到：提交后新节点 / 边并入画布并重排布局，页头统计从 10 节点 8 边变为 11 节点 9 边。

API 等价：POST /api/v1/graph/nodes、POST /api/v1/graph/edges

4 在「图谱元素管理」里删除元素 情报工作台 → 图谱元素管理
  • 怎么做：在节点或边列表对应行点「删除」，弹出二次确认弹窗（展示 RID 与标签 / 关系），点确认。
  • 会看到：删除成功刷新列表与统计；删除节点会级联清掉它的关联边；无权限提示 403、已不存在提示 404。

API 等价：DELETE /api/v1/graph/nodes/:id、DELETE /api/v1/graph/edges/:id

5 设置「默认中心节点」 情报工作台 → 默认中心节点
  • 怎么做：在配置卡输入中心节点 rid（如 graph:org:xuanwu），点「保存」；想还原就点「恢复默认」。
  • 会看到：当前生效 rid 实时显示，刷新后默认 3 度展开与最短路径起点从该节点起算；清除后回退 graph:person:zhy。

API 等价：页面本地配置（localStorage），生效时触发 GET /api/v1/analysis/graph/expand

6 子图过滤并翻页看结果 情报工作台 → 图分析 → 子图过滤
  • 怎么做：填 types / rootIds / depth 点「子图过滤」，结果表下方按 50 / 100 / 200 / 全部 档位切换，点「上一页 / 下一页」。
  • 会看到：表底提示「显示第 X-Y 条，共 N 条」；翻页只改变渲染的行数，数据本身是一次性返回的。

API 等价：GET /api/v1/analysis/graph/subgraph（admin-only）

提示：图分析（展开 / 最短路径 / 中心度 / 社群 / 子图过滤）仅 admin 角色可用，普通账号会收到 403；删除节点会级联删边且没有回收站，误删不可恢复；图谱后端没有字段编辑端点，要改节点 / 边属性只能删除后重建。

调整指南（怎么调整）

  • 改邻居范围：/graph/nodes/:id/neighbors 支持 depth 参数（默认 1），想看得更远传 2 或 3。
  • 补情报：新增边前先确认 source / target 节点已存在，否则返回悬挂边 409；ID 不填系统自动生成 graph:{type}:{uid}。
  • 改展示：用搜索框按 label / type 过滤，拖拽调整布局；属性面板逐条看 name / region / organization / classification。
  • 改统计口径：节点 / 边总数以图存储 Count 为准；类型分布需前端对节点列表本地聚合。
  • 改权限：图分析能力挂在 admin 角色下，非 admin 需找管理员执行或授权。

做得好的场景

图谱入门阶段 Gotham 最省事的地方：
  • 零门槛看图：打开就是关系网，不用写任何查询语句，节点、边、属性全在画面上。
  • 秒级高亮：点一个节点，直接关联方立刻高亮，替代以前翻几份卷宗对关联的半天功夫。
  • 改动自动落盘：补节点补边即时写入 temp/gotham_graph.json，重启不丢。
  • 演示数据就绪：启动即 seed 玄武集团关系网，随时可练手。

限制与不足

以下是明确的边界，使用前先知道：
  • 存储自研默认：默认图存储为内存邻接表 + JSON 全量落盘，单机容量受内存限制（演示级轻松，TB 级是硬上限）；Neo4j 为可选后端，需配置 gotham.graph.mode=neo4j 启用，演示环境默认未启用。
  • 统计很简单：/graph/stats 只有总数，类型分布、度数分布要靠前端本地算。
  • 删除很危险：删除节点级联删除全部相关边，且无回收站，误删不可恢复。
  • 无字段编辑：图谱后端只有 POST（幂等 upsert）与 DELETE，没有 PUT / PATCH 更新端点，页内无法修改节点 / 边属性，改属性只能删除后重建。
  • 子图分页是渲染层：/analysis/graph/subgraph 只接受 types / root_ids / depth / properties 四个参数，没有 limit，一次返回全部命中节点与边；表格分页只影响渲染的行数，不影响数据完整性。
  • 分析要权限：图算法是管理能力，非 admin 一律 403，浏览角色用不了。

场景故事

故事 1 周警官第一次打开图工作台，玄武集团的关系网络直接呈现在眼前
场景：浏览图谱 角色：情报分析员 耗时：约 3 分钟
背景
周警官是市公安局经侦大队的情报分析员，负责排查玄武集团涉诈线索。2026 年 8 月 16 日，队长让他"先把这伙人的关系网摸出来"。他打开 Gotham 图工作台（/gotham），演示数据已 seed 好 10 个节点、8 条边，类型覆盖 person（人）、org（组织）、ship（船舶）。
传统做法对比
以前要在几十页通话记录、转账流水、工商信息里手工对名字，画一张人物关系图要一整天，还经常漏掉跨部门的关联。现在打开页面就是一张 SVG 力导向图，10 个节点 8 条边直接呈现在眼前。
角色
周警官（情报分析员，登录 admin / admin1，端口 18083），只读浏览即可完成本步。
操作步骤
  1. 登录 Gotham（http://127.0.0.1:18083），进入图工作台 /gotham
  2. 看右上角统计面板：10 个节点、8 条边
  3. 对照图例确认三类节点颜色：person / org / ship
  4. 点开玄武集团节点，看属性：name=玄武集团、region=华北、classification=secret
系统响应
统计接口返回结构示例：
{
  "code": 0,
  "data": { "nodes": 10, "edges": 8 }
}
节点列表接口返回 id / type / label / properties，前端按 type 分色渲染。
结果洞察
一眼看清 8 条边的构成：4 条 member_of（成员关系）、1 条 transferred_to（玄武→天河，金额 500000）、1 条 shipped_to、1 条 operates、1 条 associated_with。张远、李四都挂在玄武集团下，玄武集团是图上唯一 classification=secret 的节点，在界面里以机密色区分。
调整建议
先用搜索框按 label 过滤快速定位（如输入"玄武"），再拖拽平移调整布局；想看某条边的属性，直接点边查看 amount / weight。
动手试一试
登录：admin / admin1，端口 18083。页面路径：/gotham 图工作台。预期结果：页面上出现 10 个节点 8 条边，玄武集团为 org 色且带 secret 密级标记，统计面板显示 nodes=10、edges=8。
限制提示
默认图存储是自研磁盘实现（内存邻接表 + JSON 落盘），单机容量受内存限制；Neo4j 可选后端需配置启用（演示默认 disk）；大图虚拟化渲染属后续能力，演示级规模完全够用。
故事 2 点击玄武集团高亮邻居，member_of / transferred_to 关系当场浮出水面
场景：邻居高亮 角色：情报分析员 耗时：约 2 分钟
背景
周警官想快速确认"玄武集团到底直接关联谁"。他直接在图上点击玄武集团节点，希望系统把它的直接关联方全部高亮出来。
传统做法对比
以前要人工翻开户资料、股权结构、资金流水，把"谁是玄武集团的人、谁和它有资金往来"逐个对一遍，两三份卷宗往往要耗上半天。现在点一下鼠标，直接关联方全部高亮。
角色
周警官（情报分析员，只读浏览权限即可）。
操作步骤
  1. 在图工作台上点击玄武集团节点
  2. 观察高亮结果：非直接关联节点自动置灰（dimmed）
  3. 对照高亮节点类型：张远、李四（person）、天河贸易（org）
  4. 查看边类型：member_of（成员）、transferred_to（资金划转，amount=500000）
系统响应
前端调用邻居接口：
GET /graph/nodes/graph:org:xuanwu/neighbors
返回可达节点列表（节点对象含 id/type/label/properties）：张远、李四、天河贸易。边类型（member_of / transferred_to 及其 weight、amount 属性）由前端按图上可视化结果展示——邻居接口本身只返回节点。
结果洞察
玄武集团直接关联 3 个节点：2 名内部成员 + 1 家贸易公司，并且有一条 50 万的大额转账边直通天河贸易。周警官在笔记本上记下："玄武→天河 50 万，资金链路第一环锁定。"
调整建议
邻居接口支持 depth 参数（默认 1），想一次看两跳，可在调用时传 depth=2；先 1 跳看清直接关系，再配合图分析 expand 看多跳蔓延。
动手试一试
输入内容：id=graph:org:xuanwu、depth=2。预期结果：2 跳内可达节点包含张远、李四、天河贸易、赵敏、泰和轮（天河的下游），比 1 跳多出泰和轮与赵敏。
限制提示
/graph/nodes/:id/neighbors 返回的是可达节点列表，不含边属性；要看边本身（如 amount、weight），需使用图分析的 expand 展开视图。
故事 3 补一条情报：给图里新增"陈强"节点和一条 associated_with 边
场景：手动建图 角色：情报分析员 耗时：约 4 分钟
背景
2026 年 8 月 15 日华南航线异常事件后，周警官掌握一条新线索：天河贸易的财务赵敏近期频繁与一个叫"陈强"的人接触。他要立刻把这条情报补进图里，先建 person 节点"陈强"，再建一条与赵敏的双向关联边。
传统做法对比
以前要改 Excel 关系表、重新导出、群发邮件同步，版本一多就乱，改到一半还会有人用旧表。现在在页面里新建节点、新建边，改动即时落盘，谁都能看到最新版。
角色
周警官（情报分析员，具备图写权限；新增边需要 source / target 节点都已存在）。
操作步骤
  1. 在图工作台点"新增节点"，填 type=person、label=陈强，properties 里写 region=华南
  2. 保存后系统自动生成节点 ID：graph:person:{uid}
  3. 点"新增边"，source 填新节点 ID、target 填 graph:person:zhaomin
  4. 边类型填 associated_with，direction 填 bidirectional，weight 填 1，提交
系统响应
创建节点返回 201 与完整节点对象：
{
  "code": 0,
  "data": {
    "id": "graph:person:6f8a...",
    "type": "person",
    "label": "陈强",
    "properties": { "region": "华南" },
    "created_at": "...", "updated_at": "..."
  }
}
创建边返回 201，边 ID 为按幂等键派生的 e_ 开头稳定 ID。
结果洞察
图统计从 10 节点 8 边变成 11 节点 9 边；陈强与赵敏建立双向关联，重启服务后数据仍然保留（已落盘 temp/gotham_graph.json）。周警官的线索第一次进入系统化的关系网。
调整建议
边属性可以带备注或 weight 表达关联强度；节点 ID 不填会自动生成，填了则按填写的 ID 幂等 upsert（同 ID 重复提交是更新不是新建）。
动手试一试
操作：新增 person 节点 label=陈强；新增边 source=新节点、target=graph:person:zhaomin、type=associated_with、direction=bidirectional。预期结果：节点返回 201，边返回 201；全图统计变为 nodes=11、edges=9。
限制提示
新增边时 source / target 两端节点必须已存在，否则返回 409 GOTHAM_GRAPH_REFERENCE_VIOLATION（悬挂边防护）；节点 type 字段必填，缺失返回 400；删除节点会级联删边且无回收站。
故事 4 给队长汇报：节点检索 + 全图统计支撑"玄武集团网络规模"结论
场景：全图统计 角色：情报分析员 耗时：约 5 分钟
背景
次日晨会，队长要周警官口头汇报"玄武集团关系网络的规模与构成"。他需要一组站得住脚的数字：多少个节点、多少条边、三类节点各多少、谁是机密级。
传统做法对比
以前要在 Excel 里手工数人、数公司、数船，稍不留神就数错，汇报时还要再对一遍原始材料，半小时起步。现在直接看统计面板和节点列表，数字张口就来。
角色
周警官（情报分析员，只读权限即可）。
操作步骤
  1. 打开图工作台右上角统计面板（/graph/stats）
  2. 查看节点列表，按 type 本地筛选 person / org / ship
  3. 逐条核对关键节点的 classification 字段
  4. 记录汇总数据并写进汇报材料
系统响应
统计接口返回：
{ "code": 0, "data": { "nodes": 10, "edges": 8 } }
节点列表返回每个节点的 id / type / label / properties，可直接按 type 与 classification 本地聚合。
结果洞察
网络构成为 5 个 person、3 个 org、2 个 ship；玄武集团是唯一 classification=secret 的节点。周警官汇报："演示网络共 10 节点 8 边，5 人 3 组织 2 船，核心组织玄武集团为机密级，与其直接关联的是两名成员和天河贸易。"
调整建议
单节点详情用 /graph/nodes/:id 精查（如补节点后确认 graph:person:{uid} 的属性）；统计口径以图存储 Count 为准，改动节点后数字即时刷新。
动手试一试
操作：删除一个你新建的测试节点，再刷新统计面板。预期结果：nodes / edges 数字随之下降——级联删除生效，正好提醒你删除不可恢复。
限制提示
/graph/stats 只返回节点与边的总数，没有按类型分布的统计；类型分布、度数分布需要在前端对节点列表本地聚合；删除节点级联删边后统计立刻变化，删前请三思。

常见问题

图里的数据是真实的吗？

是演示 seed 数据（玄武集团、张远、天河贸易、泰和轮等），每次启动幂等 seed，用于练习浏览、高亮、补点补边。你在图里的新增节点与边会持久落盘，重启不丢。

为什么有的节点是灰色的？

点击某个节点后，系统只高亮它的直接邻居（默认 1 跳），其余节点置灰（dimmed），方便你把注意力集中在"谁和谁直接有关"。调大 depth 后置灰范围会扩大。

我能用图分析（展开、最短路径、中心度）吗？

图分析接口挂在 admin 角色下，只有管理员能执行；普通分析员会收到 403。需要分析能力时请管理员操作，或由管理员授权。

节点 ID 可以自己指定吗？

可以。填了 ID 按幂等 upsert（同 ID 重复提交是更新）；不填则由系统生成 graph:{type}:{uid}。注意新增边时两端节点必须已存在，否则会报悬挂边 409。

图数据存在哪里？

默认存在自研磁盘图存储里（内存邻接表 + JSON 快照落盘，默认 temp/gotham_graph.json），每次变更写盘、启动加载。Neo4j 是可选后端（配置 gotham.graph.mode=neo4j 启用），演示环境默认用 disk 单机方案，大图规模受内存限制。

主题小结

一句话：图谱入门就三件事——打开图看全局、点节点看邻居、补点补边记新情报。记住几个边界：统计只有总数、分析只有管理员能用、存储是自研磁盘图（未接图数据库）、删节点会级联删边、节点 / 边无字段编辑端点（改属性只能删除重建）、子图分页只是渲染层。看图、建图这一层，10 分钟就能上手。