> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/di-liu-pian-shi-jian-xiang-mu/build-visualization-ui.md).

# 构建可视化界面

可视化界面的目标是让读者从图谱结果快速进入证据。界面不需要复杂，但必须支持探索、过滤、下钻和跳转。

最小系统的可视化可以先围绕三个视图：图谱视图、影响面视图和热点视图。它们分别服务代码理解、变更验证和治理判断。

## 设计原则

实践项目的 UI 不应该追求炫酷。它应该遵循几个原则：

* 默认展示与当前问题相关的子图，而不是全量图。
* 节点和边要能解释来源。
* 图上每个节点都能跳回源码或报告。
* 复杂信息先摘要，再下钻。
* 支持过滤，避免图变成一团线。

代码可视化的目标是证据，不是装饰。

## 图谱视图

图谱视图用于展示代码结构和关系。

最小视图可以支持：

* 按模块展示文件和类。
* 展示类与方法的包含关系。
* 展示方法调用关系。
* 展示接口实现关系。
* 点击节点查看属性。

默认不建议展示全量方法级调用图。更好的方式是先展示模块级或文件级概览，点击后再展开局部方法调用。

## 影响面视图

影响面视图是实践项目中最重要的视图之一。

输入一次变更后，界面应该高亮：

* 变更实体。
* 受影响调用方。
* 业务入口。
* 相关测试。
* 风险节点。

影响面视图最好按路径展示，而不是只画一个网络。路径能清楚说明“为什么这个入口受影响”。

例如：

```
OrderController.cancel
  -> OrderService.cancel
     -> InventoryService.release
```

这种路径比无序网络图更适合 Review。

## 热点视图

热点视图用于治理和重构。它可以结合复杂度、变更频率、覆盖率和运行时指标。

常见表达方式包括：

* 文件热力图。
* 模块风险列表。
* 变更频率时间线。
* 高风险节点排行。

第一版可以先用列表或表格，不必强行画复杂热力图。关键是把排序依据展示清楚。

## 节点详情

点击节点后，应该展示：

* 节点名称和类型。
* 源码路径和行号。
* 所属模块。
* 调用方和被调用方数量。
* 相关测试。
* 变更次数。
* 风险提示。
* 数据来源。

节点详情是从图回到证据的入口。

## 跳转源码

每个代码节点都应该能跳转到源码位置。即使只是生成一个形如 `path:line` 的链接，也比只展示名称更有用。

如果未来集成 IDE 或 Web 编辑器，可以进一步支持直接打开文件、定位行号、展示上下文代码片段。

## 过滤和下钻

过滤能力包括：

* 按节点类型过滤。
* 按关系类型过滤。
* 按调用深度过滤。
* 按模块过滤。
* 按风险等级过滤。
* 隐藏低置信度边。

下钻能力包括：

* 模块 -> 文件。
* 文件 -> 类。
* 类 -> 方法。
* 方法 -> 调用路径。
* 影响路径 -> 测试和 Trace。

过滤和下钻决定了图能否在真实项目中使用。

## 报告优先于复杂 UI

如果资源有限，可以先生成 Markdown 报告，再做前端 UI。很多工程场景中，一份结构清晰、能跳转源码的影响面报告，价值高于复杂图形界面。

实践项目可以先输出：

* `graph.json`
* `impact-report.md`
* `impact-report.json`

再逐步增加可视化页面。

## 小结

可视化界面应该围绕证据设计。图谱视图帮助理解结构，影响面视图帮助验证变更，热点视图帮助治理风险。

下一章会把图谱能力开放给 AI Agent，让 Agent 也能查询这些结构化事实。