P4 Gotham

图分析：让关系网自己开口说话

展开、路径、中心度、社群——四件套图算法帮你从玄武集团的关系网里回答四个问题：关联能蔓延多远、资金最短怎么走、谁是关键枢纽、谁和谁其实是一伙的。看完这 4 个故事，你就能把"感觉有关"变成"算法佐证"。

反洗钱分析师情报研判专家 BFS 展开最短路径中心度社群发现 PageRank 共 5 个故事

能 / 不能速览

✅ 这个主题能做

1-3 度 BFS 展开（/analysis/graph/expand），节点按层记录 levels，limit 硬上限 1000
最短路径（/analysis/graph/path）：无权 BFS 求跳数最短路径，不可达返回 distance=-1
中心度（/analysis/graph/centrality）：degree 三口径 + Brandes 介数近似（归一化 0-1）
社群发现（/analysis/graph/community）：union-find 连通分量 + Louvain 简化版，输出模块度
PageRank（/analysis/graph/pagerank）影响力排序、紧密中心度（closeness）传播中心、标签传播（label-propagation）分群、强连通分量（scc）环结构分析
结果在图上高亮展示，配合实体详情面板逐条研判

⛔ 这个主题做不了

图分析是管理能力：仅 admin 角色可执行，非 admin 返回 403
展开 depth 只支持 1-3，limit 超过 1000 返回 GOTHAM_EXPAND_LIMIT_EXCEEDED（拒绝不截断）
Louvain 是简化版：maxIter=10、社区数上限 50，复杂网络的划分与标准 Louvain 可能有差异
介数中心度在节点超过 500 时按度权重采样近似（sampled 字段），不是全量精确值

适用角色

本主题面向两类角色：

反洗钱分析师：核心使用者，用展开看关联蔓延、用路径看资金链路、用中心度找关键枢纽。
情报研判专家：用社群发现圈定可疑团伙，把算法结果与业务情报交叉印证。

图分析接口挂在 admin 角色下，执行前请确认当前账号具备管理员权限；结果只是算法建议，最终研判仍需人工把关。

能力速览（能做什么）

1-3 度展开

从任意节点出发 BFS 按层蔓延，返回中心节点、展开节点、涉及的边与 levels 层级，直接看清关联能蔓延多远。

最短路径

无权 BFS 求跳数最短路径，返回路径节点、边与跳数；目标不可达时 distance=-1 并附提示，而不是报错。

中心度

degree 三口径（总度 / 入度 / 出度）降序输出；介数中心度用 Brandes 采样近似，归一化 0-1，Top-K 展示枢纽节点。

社群发现

union-find 求连通分量，再对每个连通分量跑简化 Louvain（模块度增益贪心 + 网络折叠），输出社区与模块度 Q。

PageRank 与紧密中心度

PageRank 按有向关系传播影响力（阻尼 0.85），找出"被重要节点关联者"；紧密中心度用 BFS 平均最短路径衡量传播中心，分数归一化 0-1。

标签传播与强连通分量

标签传播（异步更新、邻居众数标签）适合超大规模图快速分群；Tarjan 强连通分量识别有向环结构（资金环、依赖环），分量按 scc0..sccN 命名。

调整指南（怎么调整）

改展开范围：expand 传 depth=1/2/3 控制层数，limit 控制最多返回多少节点（建议先 50 后逐步调大）；limit 超 1000 会被拒绝。
改路径口径：/analysis/graph/path 用无权 BFS（跳数最短）；有权 Dijkstra（按边 weight 权重）已在算法库实现并通过单测，但当前未挂 HTTP 路由，需要按转账金额找最短路可向开发提需求扩展。
改中心度：kind=degree 看三口径度数；kind=betweenness 看介数；node 参数可限定只看某个节点。
改社群理解：先看连通分量（谁根本连不上），再在分量内部看 Louvain 划分；模块度 Q 越接近 1 说明划分越"聚得紧"。

做得好的场景

图分析四件套最擅长把"关系"变成"证据链"：

关联蔓延可视化：3 度展开几秒钟画出一个子网，替代人工逐层推关联。
资金链路还原：最短路径把"张远怎么触达一艘船"这样的问题变成一条可回放的节点链。
关键节点排序：degree / 介数两张榜单直接给出"谁是网络枢纽"，不用猜。
团伙轮廓初判：连通分量 + Louvain 自动圈出"谁和谁其实是一伙的"，辅助侦查聚焦。

限制与不足

以下是明确的边界，使用前先知道：

仅管理员可用：四个分析接口全部挂在 admin 角色下，非 admin 一律 403。
深度与上限：expand 只支持 1-3 度，limit 硬上限 1000，超限直接报错不截断。
简化版算法：Louvain 是简化实现（迭代 10 轮、社区上限 50）；介数在节点超 500 时为采样近似。
路径接口口径：当前 HTTP 层暴露的是无权 BFS（跳数最短），有权 Dijkstra 仅在算法库中就绪，未挂路由。

场景故事

故事 1 苏分析师对玄武集团做 3 度展开，看关联能蔓延多远

场景：BFS 展开角色：反洗钱分析师耗时：约 3 分钟

背景: 苏分析师是反洗钱中心的分析师。2026 年 8 月 17 日，她要对玄武集团做一次深度关联排查，第一个问题就是"以玄武集团为圆心，关联到底能蔓延多远"。她用管理员账号在图上选中玄武集团，跑一次 3 度展开。

传统做法对比: 以前要一层层人工推关联：先查玄武集团直接关系人，再查这些人的关系人……每推一层都要重新翻材料，推三层往往要一两天，还容易漏边。现在一键展开，1 秒出结果。

角色: 苏分析师（反洗钱分析师，需 admin 角色——图分析接口仅管理员可执行）。

操作步骤

在图工作台选中玄武集团（graph:org:xuanwu）
调用展开接口：/analysis/graph/expand?node=graph:org:xuanwu&depth=3&limit=50
查看结果视图：中心节点、展开节点、edges、levels
按 levels 逐层核对谁在第几层

系统响应

返回 GraphView 结构示例：

{
  "center": { "id": "graph:org:xuanwu", "type": "org", "label": "玄武集团" },
  "nodes": [ /* 中心 + 展开节点 */ ],
  "edges": [ /* 涉及的边，按边 ID 去重 */ ],
  "levels": {
    "graph:org:xuanwu": 0,
    "graph:person:zhy": 1, "graph:person:lisi": 1, "graph:org:tianhe": 1,
    "graph:person:zhaomin": 2, "graph:ship:taihe": 2
  }
}

3 度展开共命中 6 个节点、6 条边。

结果洞察: 3 度展开后，节点集中在玄武集团、张远、李四、天河贸易、赵敏、泰和轮 6 个实体上，第 1 层是两名成员和天河贸易，第 2 层才出现赵敏和泰和轮；而青龙航运、吴刚、远航号、王敏完全没有出现在结果里——说明它们与玄武集团不在同一个连通分量，是另一个独立圈子。

调整建议: 先 depth=1 看直接关系，再逐步加深到 2、3；limit 按需从 50 调大，但别超过 1000；配合中心度结果看展开后哪些节点反复出现。

动手试一试: 输入内容：node=graph:org:xuanwu、depth=2、limit=50。预期结果：返回 6 个节点（张远、李四、天河贸易在第 1 层，赵敏、泰和轮在第 2 层）；再把 depth 改成 3，结果集不增长——因为第 3 层没有新节点。

限制提示: depth 只支持 1-3，传 4 会返回校验错误；limit 超过 1000 或展开中触及上限，返回 GOTHAM_EXPAND_LIMIT_EXCEEDED（拒绝而非静默截断）；展开是连通分量内的遍历，跨分量的节点永远不会出现。

故事 2 查"张远到泰和轮"最短路径，资金链路的每一跳都有据可查

场景：最短路径角色：反洗钱分析师耗时：约 3 分钟

背景: 苏分析师想验证一个判断：核心人物张远和泰和轮这条船到底有没有关系、隔了几跳。她用最短路径接口从张远（graph:person:zhy）查到泰和轮（graph:ship:taihe）。

传统做法对比: 以前要从通话、资金、物流数据里拼出一条"张远→公司→公司→船"的链路，往往靠经验拼凑，跳数对不对、中间有没有绕路都说不清。现在算法直接给出跳数最少的路径。

角色: 苏分析师（反洗钱分析师，需 admin 角色）。

操作步骤

调用路径接口：/analysis/graph/path?from=graph:person:zhy&to=graph:ship:taihe
查看返回的 path（节点 ID 序列）、nodes、edges、distance
再试一次不可达组合：from=graph:person:zhy&to=graph:org:qinglong

系统响应

第一条返回：

{
  "path": ["graph:person:zhy", "graph:org:xuanwu", "graph:org:tianhe", "graph:ship:taihe"],
  "nodes": [ /* 张远、玄武集团、天河贸易、泰和轮 */ ],
  "edges": [ /* member_of、transferred_to、shipped_to */ ],
  "distance": 3
}

第二条不可达返回：{"distance": -1, "hint": "目标节点不可达（无路径）"}，不视为错误。

结果洞察: 张远到泰和轮最短 3 跳：张远 →(member_of) 玄武集团 →(transferred_to, 50 万) 天河贸易 →(shipped_to) 泰和轮。整条链路与"玄武出钱、天河发货、泰和轮承运"的业务判断完全吻合；而张远到青龙航运返回 distance=-1，说明两伙人之间目前没有已知连线，线索排查可以围绕"这条缺失的边"展开。

调整建议: 跳数最短不等于金额路径，边的 weight 属性（如转账金额归一化倒数）用于有权最短路；有权 Dijkstra 已在算法库实现并通过单测，若业务需要按 weight 找最短路，可推动路由扩展。

动手试一试: 输入内容：from=graph:person:zhy&to=graph:ship:taihe。预期结果：返回 distance=3 的 4 节点路径；再输入 from=graph:person:zhy&to=graph:org:qinglong，预期 distance=-1 并带"目标节点不可达"提示。

限制提示: 当前 /analysis/graph/path 为无权 BFS（跳数最短）；路径节点数有 100 的防环回硬上限；不可达返回 distance=-1 与 hint，不是错误，调用时注意区分。

故事 3 中心度分析：谁是这张网里的关键枢纽

场景：中心度角色：反洗钱分析师耗时：约 4 分钟

背景: 苏分析师要给线索排查排序：先盯谁？她用中心度分析对整个网络打分，看 degree 榜单找出"谁的关系最多"，再看介数榜单找出"谁最常出现在别人的最短路径上"。

传统做法对比: 以前判断"谁重要"靠办案经验拍脑袋，公说公有理。现在用度数（关联边数）和介数（桥梁作用）两个客观指标给节点排序，争议直接看数据。

角色: 苏分析师（反洗钱分析师，需 admin 角色）。

操作步骤

调用中心度接口：/analysis/graph/centrality?kind=degree
查看 DegreeCentrality 列表（node_id / degree / in_degree / out_degree）
再调用：/analysis/graph/centrality?kind=betweenness
对比两张榜单，圈定候选枢纽节点

系统响应

degree 返回降序榜单：

{
  "kind": "degree",
  "degree": [
    { "node_id": "graph:org:tianhe", "degree": 3, "in_degree": 2, "out_degree": 1 },
    { "node_id": "graph:org:xuanwu", "degree": 3, "in_degree": 2, "out_degree": 1 },
    { "node_id": "graph:person:zhy", "degree": 3, "in_degree": 1, "out_degree": 2 },
    { "node_id": "graph:person:lisi", "degree": 3, "in_degree": 1, "out_degree": 2 }
  ],
  "top_k": 20
}

betweenness 返回归一化 0-1 分数与 sampled 字段。

结果洞察: degree 榜首是天河贸易、玄武集团、张远、李四（各 3 度）；介数榜单上，天河贸易与玄武集团分数靠前——天河贸易同时承接玄武的 50 万转账、向泰和轮发货、还有财务赵敏挂靠，是典型的"桥梁+资金出口"枢纽。结论：盯住天河贸易，等于同时盯住了资金流与货流。

调整建议: degree 适合找"关系多"的人，betweenness 适合找"卡在中间"的人，两种口径要一起看；node 参数可限定只看单个节点（如只看张远）。

动手试一试: 输入内容：kind=degree 后再试 kind=betweenness。预期结果：degree 榜单前四名均为 3 度（天河/玄武/张远/李四）；betweenness 返回 0-1 分数，天河贸易与玄武集团靠前，字段中含 sampled 表示计算方式。

限制提示: 介数中心度在节点数超过 500 时按度权重采样近似（sampled 字段），不是全量精确值；top_k 默认输出 20 条；center 图很小（10 节点）时会走全量精确计算。

故事 4 社群发现：哪几个人其实是一伙的

场景：社群发现角色：情报研判专家耗时：约 4 分钟

背景: 情报研判专家韩老师在复核苏分析师的材料，想快速确认"这 10 个节点里到底分几伙人"。他直接跑一次社群发现，用连通分量 + Louvain 简化版把网络自动分组。

传统做法对比: 以前靠人工看关系图猜"谁和谁是一伙"，遇到节点一多就分成几派意见。现在算法按结构自动分群，并给出模块度，分组结果可复核、可争论、可引用。

角色: 韩老师（情报研判专家，需 admin 角色）。

操作步骤

调用社群接口：/analysis/graph/community
查看 communities 列表（id / members / size）与 modularity
按 size 从大到小核对每个社区的成员构成
把算法分群与业务情报交叉印证

系统响应

返回结构示例：

{
  "method": "connected-components+louvain",
  "communities": [
    { "id": "c0", "members": ["graph:person:zhy", "graph:org:xuanwu", "graph:person:lisi", "…"], "size": 4 },
    { "id": "c1", "members": ["graph:person:zhaomin", "graph:org:tianhe", "graph:ship:taihe", "…"], "size": 3 },
    { "id": "c2", "members": ["graph:person:wugang", "graph:org:qinglong", "graph:ship:yuanhang"], "size": 3 },
    { "id": "c3", "members": ["graph:person:wm"], "size": 1 }
  ],
  "modularity": 0.3126
}

注：社区 id 与成员以实际返回为准。

结果洞察: 算法把网络分成约 4 个社区：玄武集团"核心圈"（张远、李四、玄武集团等）、天河贸易链路（天河、赵敏、泰和轮）、青龙航运一伙（吴刚、青龙、远航号），而王敏因为没有任何边，孤立成单节点社区——印证"她还没进入任何关系链"。模块度 0.31 说明结构有明显聚团但不极端。

调整建议: 先看连通分量（谁根本连不上），再在分量内部看 Louvain 划分；把社群结果与最短路径、中心度结合，锁定"团伙核心 + 跨团桥梁"。

动手试一试: 操作：新增一条"王敏 → 天河贸易"的边后再跑一次社区发现。预期结果：王敏从单节点社区并入天河贸易所在社区，communities 数量减少——结构变化直接反映在分群结果上。

限制提示: Louvain 为简化版（迭代上限 10、社区数上限 50，超出会合并最小社区），复杂大图的划分与标准 Louvain 可能有差异；社区是"算法建议"，业务语义（是不是真的一伙人）仍需人工研判。

故事 5 PageRank + 标签传播 + 强连通分量：谁有真实影响力、谁和谁绑死在一起

场景：影响力与环结构角色：情报研判专家耗时：约 6 分钟

背景: 韩老师要回答三个更深的问题：抛开"直接连线多少"，谁在网络里最被"重要的人"指向（PageRank）？把玄武集团网络按结构切分，谁和谁算一伙（标签传播）？有没有资金/关系环（强连通分量）？他在图分析页依次调用三个接口。

传统做法对比: 以前判断"谁是幕后核心"靠资历和直觉，争论不休；判断"谁和谁绑死"要逐对看边，10 个节点尚可、100 个节点就失控；找环更要人肉回溯，极易漏。现在三支算法各自几秒钟出结果，且全部可复核。

角色: 韩老师（情报研判专家，需 admin 角色）。

操作步骤

调用 PageRank：/analysis/graph/pagerank?damping=0.85&top_k=5
调用标签传播：/analysis/graph/label-propagation?max_iter=20
调用强连通分量：/analysis/graph/scc
对比三张结果，结合 degree/介数榜单交叉研判

系统响应

真实返回结构（分数以实际运行为准）：

// PageRank（分数保留 6 位小数，降序）
{ "entries": [ {"node_id": "graph:org:tianhe", "score": 0.210433},
               {"node_id": "graph:org:xuanwu", "score": 0.184712},
               {"node_id": "graph:person:lisi", "score": 0.090310} ], "top_k": 5 }
// 标签传播（Method=label-propagation）
{ "method": "label-propagation", "communities": [ ... ], "modularity": 0.0 }
// 强连通分量（Tarjan）
{ "count": 9, "components": [ {"id": "scc0", "members": ["graph:person:zhy","graph:person:lisi"]}, ... ] }

演示图唯一双向边是张远↔李四的 associated_with，因此只有这两人才构成非单点强连通分量。

结果洞察: PageRank 榜首是天河贸易与玄武集团——"被重要节点指向"的影响力核心，与 degree 榜单互相印证；标签传播把网络切成本身结构上的聚团（玄武圈 / 青龙圈 / 孤立点王敏）；SCC 只检出 {张远, 李四} 一个 2 节点环（双向 associated_with），其余 8 个分量均为单节点——说明演示网络"有强指向、无资金闭环"，若日后出现资金环，SCC 会直接标出。

调整建议: PageRank 调 damping 观察收敛；标签传播适合超大规模图快速分群，想更精细用 Louvain（community）；SCC 找环前先确认边的方向语义（directed 单向 / bidirectional 双向），方向错了环就检不出。

动手试一试: 操作：调用 /analysis/graph/scc。预期结果：返回 9 个分量（演示图 10 节点，仅张远↔李四双向边构成 2 节点分量，其余单节点）；PageRank 与标签传播返回各自社区/分数结构，跨接口结果可互相印证。

限制提示: 介数/紧密中心度在节点超 500 时是采样近似；标签传播与 Louvain 都是"算法建议"，"是不是一伙人"需业务研判；SCC 只识别结构上的环，业务语义上的资金闭环仍需结合金额属性人工确认。

常见问题

为什么我调用图分析接口返回 403？

图分析（expand / path / centrality / community）是管理能力，只允许 admin 角色执行。请确认当前登录账号是 admin（登录 admin / admin1），或让管理员代为执行。

展开最多能看几层？

最多 3 度。depth 只接受 1-3，传更大值会返回校验错误；同时 limit 硬上限 1000，展开过程中节点数触及上限会报 GOTHAM_EXPAND_LIMIT_EXCEEDED，而不是静默截断。

最短路径返回 distance=-1 是出错了吗？

不是。distance=-1 表示两个节点之间没有路径（不在同一个连通分量），同时会带 hint 提示"目标节点不可达"；有路径时 distance 是跳数。业务上"查不到路径"本身就是重要线索。

中心度的介数分数是怎么算的？

介数中心度用 Brandes 算法：节点数 ≤500 时全量精确计算，超过 500 按度权重采样近似（响应里带 sampled 字段），最后归一化到 0-1 并取 Top-K（默认 20）。

社群发现和"一伙人"是一回事吗？

社群发现是结构聚类（连通分量 + Louvain），把"边连得紧"的节点分到一组，是算法建议；"是不是同一犯罪团伙"必须结合业务情报由人来判断。模块度 Q 越接近 1 说明分群越显著。

主题小结

一句话：图分析回答五类问题——展开回答"关联蔓延多远"、路径回答"最短怎么走"、中心度回答"谁是枢纽"、社群（Louvain/标签传播）回答"谁是一伙"、PageRank 与 SCC 回答"谁有真实影响力/有没有环"。10 支算法全部 Go 原生落地。注意边界：仅 admin 可用、展开限 3 度 1000 节点、Louvain 与介数都是简化 / 近似实现、路径当前为无权 BFS（有权 Dijkstra 在算法库就绪未挂路由）。算法给证据，人给结论。