P4 Gotham

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

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

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

能 / 不能速览

✅ 这个主题能做

打开图工作台浏览全量节点，person / org / ship 三类分色渲染
点击节点高亮邻居，理解 member_of / transferred_to / operates 等关系
手动新增节点、新增边补充情报，幂等 upsert、改动自动落盘
查看全图统计（/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。

邻居高亮

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

全图统计

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

调整指南（怎么调整）

改邻居范围：/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 只有总数，类型分布、度数分布要靠前端本地算。
删除很危险：删除节点级联删除全部相关边，且无回收站，误删不可恢复。
分析要权限：图算法是管理能力，非 admin 一律 403，浏览角色用不了。

场景故事

故事 1 周警官第一次打开图工作台，玄武集团的关系网络直接呈现在眼前

场景：浏览图谱角色：情报分析员耗时：约 3 分钟

背景: 周警官是市公安局经侦大队的情报分析员，负责排查玄武集团涉诈线索。2026 年 8 月 16 日，队长让他"先把这伙人的关系网摸出来"。他打开 Gotham 图工作台（/gotham），演示数据已 seed 好 10 个节点、8 条边，类型覆盖 person（人）、org（组织）、ship（船舶）。

传统做法对比: 以前要在几十页通话记录、转账流水、工商信息里手工对名字，画一张人物关系图要一整天，还经常漏掉跨部门的关联。现在打开页面就是一张 SVG 力导向图，10 个节点 8 条边直接呈现在眼前。

角色: 周警官（情报分析员，登录 admin / admin1，端口 18083），只读浏览即可完成本步。

操作步骤

登录 Gotham（http://127.0.0.1:18083），进入图工作台 /gotham
看右上角统计面板：10 个节点、8 条边
对照图例确认三类节点颜色：person / org / ship
点开玄武集团节点，看属性：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 分钟

背景: 周警官想快速确认"玄武集团到底直接关联谁"。他直接在图上点击玄武集团节点，希望系统把它的直接关联方全部高亮出来。

传统做法对比: 以前要人工翻开户资料、股权结构、资金流水，把"谁是玄武集团的人、谁和它有资金往来"逐个对一遍，两三份卷宗往往要耗上半天。现在点一下鼠标，直接关联方全部高亮。

角色: 周警官（情报分析员，只读浏览权限即可）。

操作步骤

在图工作台上点击玄武集团节点
观察高亮结果：非直接关联节点自动置灰（dimmed）
对照高亮节点类型：张远、李四（person）、天河贸易（org）
查看边类型：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 节点都已存在）。

操作步骤

在图工作台点"新增节点"，填 type=person、label=陈强，properties 里写 region=华南
保存后系统自动生成节点 ID：graph:person:{uid}
点"新增边"，source 填新节点 ID、target 填 graph:person:zhaomin
边类型填 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 里手工数人、数公司、数船，稍不留神就数错，汇报时还要再对一遍原始材料，半小时起步。现在直接看统计面板和节点列表，数字张口就来。

角色: 周警官（情报分析员，只读权限即可）。

操作步骤

打开图工作台右上角统计面板（/graph/stats）
查看节点列表，按 type 本地筛选 person / org / ship
逐条核对关键节点的 classification 字段
记录汇总数据并写进汇报材料

系统响应

统计接口返回：

{ "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 分钟就能上手。