code_visualize/docs/设计文档.md

# 代码分析可视化工具 · 设计文档

> 面向 AI 生成的「大锅饭」代码，帮助开发者快速掌握有哪些模块、模块间关系如何，颗粒度到函数级；聚焦宏观流程打通，不做具体实现的 bug 排查。以流程图为核心展示，抽象出一套标准化报告数据结构，任何项目按此结构产出报告均可在工具内展示。

---

## 一、产品概述
- 1.1 背景与问题（AI 大锅饭代码难以掌握全貌）
- 1.2 目标用户与典型使用场景
- 1.3 核心价值主张
- 1.4 范围与非目标（只讲宏观模块与流程，不做 bug 检测 / 代码质量评审）
- 1.5 术语表

## 二、核心设计理念
- 2.1 以流程图为核心的展示范式
- 2.2 模块 → 函数 两级颗粒度
- 2.3 报告即数据（标准化数据结构驱动展示）
- 2.4 项目无关性（跨语言 / 跨框架 / 跨规模）

## 三、标准化代码报告数据结构（核心 Schema）

### 3.0 设计原则

- **聚焦原汁原味的逻辑**：核心是函数以及函数之间的调用关系，不纠结语言特性。
- **不区分语言细节**：class / struct / interface 统一抽象成「容器 Container」，只负责持有函数与字段；不处理继承、可见性、抽象等语法概念。
- **扁平存储 + ID 引用**：所有实体平铺存放，用 `id` 互相引用（如容器用 `functionIds` 持有函数，函数用 `ownerId` 回指容器），便于图渲染、跨模块跳转与下钻。
- **统一边模型**：调用、导入、引用、触发、数据流等所有关系归一为一种 `Edge`，作为关系的唯一真相源；函数上不再冗余存调用列表。
- **来源可追溯**：每个实体/边带 `provenance`，区分「AST 确定的结构」与「AI 推断的解读」（尤其业务流程）。

### 3.1 基础通用类型

```ts
type Id = string;

// 实体/边的来源：ast=语法确定, resolved=引用解析, ai=模型推断, manual=人工
type Provenance = "ast" | "resolved" | "ai" | "manual";

interface SourceLocation {
  file: string;        // 相对仓库根的路径
  startLine: number;
  endLine: number;
  startCol?: number;
  endCol?: number;
}

// 所有实体的公共字段
interface BaseEntity {
  id: Id;
  name: string;
  qualifiedName?: string;              // 完全限定名，如 server/TaskRepo.create
  location?: SourceLocation;
  language?: string;
  provenance: Provenance;
  confidence?: number;                 // 0~1，启发式解析时使用
  summary?: string;                    // 一句话职责（可由 AI 生成）
  tags?: string[];
  extra?: Record<string, unknown>;     // 场景/语言专属扩展位
}
```

### 3.2 模块 Module

模块 = 目录 / 包 / 逻辑分组，可嵌套成树，是宏观视图的分层单位。

```ts
interface Module extends BaseEntity {
  kind: "module";
  parentId?: Id;
  childModuleIds: Id[];
  fileIds: Id[];
  path?: string;
}
```

### 3.3 文件 File

```ts
interface CodeFile extends BaseEntity {
  kind: "file";
  moduleId: Id;
  path: string;
  loc?: number;                        // 行数
  containerIds: Id[];                  // 本文件定义的容器（类/结构等）
  functionIds: Id[];                   // 本文件的顶层函数
}
```

### 3.4 容器 Container（类 / 结构 等的统一抽象）

不区分 class / struct / interface，只作为函数与字段的持有者。

```ts
interface Container extends BaseEntity {
  kind: "container";
  fileId: Id;
  moduleId?: Id;
  functionIds: Id[];                   // ← 持有的函数（方法）
  fieldIds: Id[];                      // ← 持有的字段/属性
}
```

### 3.5 函数 Function（核心）

顶层函数与容器方法统一用一个结构；是否为方法由 `ownerId` 区分。函数之间的调用关系不存在这里，而是统一走 `Edge`。

```ts
interface Func extends BaseEntity {
  kind: "function";
  fileId: Id;
  ownerId?: Id;          // 若为方法，指向所属容器；顶层函数留空
  moduleId?: Id;
  signature?: string;    // 原始签名文本
  params: Param[];
  returnType?: string;
  isEntry?: boolean;     // 是否入口点（main / 路由处理器 / 事件回调）
  interactions?: Interaction[];  // ← 该函数的跨边界交互（前后端协议 / 数据库）
  loc?: number;
}

interface Param {
  name: string;
  typeRef?: string;      // 声明类型（文本即可，不强求解析）
  optional?: boolean;
  defaultValue?: string;
}
```

#### 跨边界交互 Interaction

理解宏观逻辑的关键，往往不在于「函数调了谁」，而在于它**越过了哪条系统边界**：前端发往后端的一次请求、后端打到数据库的一次读写。这类信息直接作为函数的属性挂在函数上，而非独立节点。外部系统清单（用到哪些数据库 / 外部服务）可由全部函数的 `interactions` 聚合派生，无需单独维护。

```ts
type InteractionKind = "api" | "db";          // 可扩展：mq / cache / rpc ...

// in  = 对外暴露 / 被外部调用（如接口处理器）
// out = 本函数主动发起（如发请求 / 查库）
type InteractionDirection = "in" | "out";

interface InteractionBase {
  id: Id;
  direction: InteractionDirection;
  provenance: Provenance;
  confidence?: number;
  summary?: string;
}

// 前后端协议交互
interface ApiInteraction extends InteractionBase {
  kind: "api";
  protocol: "http" | "ws" | "rpc" | "graphql";
  method?: string;       // GET / POST / ...（http）
  path?: string;         // 如 /api/tasks/:id
  peer?: string;         // 对端：前端页面 / 外部服务名（若可知）
}

// 数据库交互
interface DbInteraction extends InteractionBase {
  kind: "db";
  operation: "read" | "create" | "update" | "delete" | "other";
  target?: string;       // 表 / 模型 / 集合名
  engine?: string;       // postgres / mysql / mongo ...（可选）
}

type Interaction = ApiInteraction | DbInteraction;
```

### 3.6 字段 Field

```ts
interface Field extends BaseEntity {
  kind: "field";
  ownerId: Id;           // 所属容器
  typeRef?: string;
}
```

### 3.7 关系 Edge（统一边模型，关系的唯一真相源）

```ts
type EdgeKind =
  | "call"        // 函数调用（Call-Flow 的原子）
  | "import"      // 文件/模块导入
  | "reference"   // 一般引用/使用
  | "dataflow"    // 数据流（可选，后期）
  | "trigger";    // 触发：路由→处理器、事件→回调

interface Edge {
  id: Id;
  kind: EdgeKind;
  sourceId: Id;          // 起点实体 id
  targetId: Id;          // 终点实体 id（未解析时指向占位节点）
  provenance: Provenance;
  confidence?: number;
  label?: string;
  extra?: Record<string, unknown>;
}
```

### 3.8 流程 Flow（Call-Flow 与 Business-Flow 同结构）

```ts
interface Flow {
  id: Id;
  name: string;
  flowType: "call" | "business";   // 调用链 / 业务流程
  summary?: string;
  provenance: Provenance;          // call 多为 resolved，business 多为 ai/manual
  entryNodeId?: Id;
  steps: FlowStep[];
  edgeIds?: Id[];                  // 关联到结构层的底层调用边，支持回溯
}

interface FlowStep {
  id: Id;
  order: number;
  nodeId?: Id;                     // 指向某函数/容器/模块
  title: string;
  description?: string;
  branchLabel?: string;            // 分支条件文字
  nextStepIds: Id[];               // 支持分支/汇合
}
```

### 3.9 外部系统 ExternalSystem（由交互派生）

外部系统不再作为原始录入节点，而是由聚合全部函数的 `interactions` **派生**得到，作为报告里的物化视图供展示消费：

- `db` 交互的 `engine` / `target` 去重 → 数据库系统及其数据表清单；
- `out` 方向的 `api` 交互的 `peer` / `path` 去重 → 依赖的外部服务清单。

每个外部系统都回指与之交互的函数，保证可回溯。

```ts
type ExternalSystemKind = "database" | "service";

interface ExternalSystemBase {
  id: Id;
  kind: ExternalSystemKind;
  name: string;                 // 数据库/引擎名 或 外部服务名
  functionIds: Id[];            // 与之交互的函数（回溯来源）
  interactionCount: number;     // 交互次数
  provenance: Provenance;       // 派生结果，通常为 resolved
}

// 数据库系统
interface DatabaseSystem extends ExternalSystemBase {
  kind: "database";
  engine?: string;              // postgres / mysql / mongo ...
  tables: string[];             // 去重后的表 / 模型清单
}

// 外部服务
interface ServiceSystem extends ExternalSystemBase {
  kind: "service";
  protocol?: string;            // http / ws / rpc / graphql
  endpoints: string[];          // 去重后的 path / peer 清单
}

type ExternalSystem = DatabaseSystem | ServiceSystem;
```

### 3.10 顶层报告 Report

```ts
interface Report {
  schemaVersion: string;
  project: {
    name: string;
    root: string;
    languages: string[];
    generatedAt: string;
    generator?: string;            // 生成工具 / 版本
  };
  stats: {
    fileCount: number;
    containerCount: number;
    functionCount: number;
    edgeCount: number;
    loc?: number;
  };
  modules:    Module[];
  files:      CodeFile[];
  containers: Container[];
  functions:  Func[];
  fields:     Field[];
  edges:      Edge[];
  flows:      Flow[];
  externalSystems?: ExternalSystem[];   // 由 interactions 派生的物化视图（可选缓存）
}
```

### 3.11 持有关系总览

```mermaid
flowchart TD
    Report --> Module
    Module --> CodeFile
    CodeFile --> Container
    CodeFile --> Func
    Container -->|functionIds| Func
    Container -->|fieldIds| Field
    Func -->|interactions| Interaction
    Report -->|"call/import/..."| Edge
    Report --> Flow
    Flow -->|steps.nodeId| Func
    Edge -->|source/target| Func
```

## 四、可视化展示设计
- 4.1 整体架构图（分层视图）
- 4.2 模块关系图（依赖 / 引用）
- 4.3 流程图 · 核心视图（Call-Flow / Business-Flow 同画布切换）
- 4.4 函数级调用图（下钻视图）
- 4.5 源码目录结构树
- 4.6 数据模型 ER 图
- 4.7 交互能力（缩放 / 下钻 / 搜索 / 高亮 / 跳转 / 联动）
- 4.8 多视图切换与状态同步

## 五、报告生成与接入方式
- 5.1 手工编辑
- 5.2 AI 辅助分析生成
- 5.3 静态解析工具导入
- 5.4 报告导入 / 导出格式

## 六、软件架构与技术选型
- 6.1 整体架构
- 6.2 前端渲染方案（图形库选型）
- 6.3 数据加载与存储
- 6.4 部署形态

## 七、界面与页面结构
- 7.1 报告列表 / 项目切换
- 7.2 主画布与侧边面板
- 7.3 详情抽屉与检索

## 八、里程碑与迭代计划