fix: 修复一系列问题并生成swagger一键脚本

CLAUDE.md

@@ -1,82 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-This is a knowledge graph visualization system with a Go backend providing REST APIs and a React frontend using AntV G6 for interactive graph rendering. The system stores graph data in Neo4j and provides nodes, edges, and relationship visualization.
-
-## Architecture
-
-### Backend (`/backend`)
-- **Entry point**: `main.go` - Sets up Gin router, initializes Neo4j connection, registers handlers
-- **Handlers** (`/handlers`): HTTP request handlers for `/api/graph`, `/api/search`, `/api/nodes/:id`, `/api/nodes/:id/neighbors`
-- **Services** (`/services`): Business logic layer. `Neo4jService` queries Neo4j and converts results to domain models
-- **Models** (`/models`): Domain models (`Node`, `Edge`, `GraphData`) and API response types
-- **Neo4j client** (`/neo4j`): Connection wrapper using `github.com/neo4j/neo4j-go-driver/v5`
-- **Config** (`/config`): Configuration loading from `.env` with CORS and server settings
-
-**Important**: Neo4j connection config is in `backend/config/.env` which contains credentials. The service queries Neo4j by executing Cypher queries and converting results to JSON.
-
-### Frontend (`/frontend`)
-- **React 19 + TypeScript + Vite** build system
-- **State management**: Zustand stores (`graphStore.ts`, `layoutStore.ts`)
-- **Graph visualization**: AntV G6 v5 for force-directed layout and interactive graphs
-- **Styling**: Tailwind CSS v4 + HeroUI components
-- **API client**: Axios (`services/graphApi.ts`)
-
-**Key frontend components**:
-- `KnowledgeGraph.tsx` - Main page that wires up search, graph view, and node panel
-- `GraphView/index.tsx` - G6 graph rendering with node selection, highlighting
-- `NodePanel/index.tsx` - Sidebar showing selected node details
-- `SearchBar/index.tsx` - Search input with node autocomplete
-
-## Common Commands
-
-### Backend
-```bash
-cd backend
-go run main.go              # Start dev server on :3001
-swag init -g main.go        # Regenerate Swagger docs
-```
-
-### Frontend
-```bash
-cd frontend
-npm run dev                 # Start dev server on :5173
-npm run build               # Production build
-npm run lint                # Lint code
-```
-
-### API Endpoints
-- `GET /health` - Health check
-- `GET /api/graph` - Get all graph data (nodes + edges)
-- `GET /api/graph/stats` - Graph statistics
-- `GET /api/search?q=query` - Search nodes by label, ID, or type
-- `GET /api/nodes/:id` - Get node by ID
-- `GET /api/nodes/:id/neighbors` - Get node neighbors and related edges
-- `GET /swagger/*` - Swagger UI documentation
-
-## Data Flow
-
-1. Frontend fetches graph data via `/api/graph`
-2. Graph data is stored in `graphStore` (Zustand)
-3. `GraphView` renders with G6 force-directed layout
-4. Node clicks highlight connected nodes and trigger `NodePanel` updates
-5. Search queries `/api/search` and selects matching nodes
-
-## Neo4j Queries
-
-The backend uses these Cypher query patterns:
-- All nodes: `MATCH (n) RETURN n`
-- All edges: `MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r`
-- Node by ID: `MATCH (n {id: $id}) RETURN n`
-- Search: `MATCH (n) WHERE toLower(n.label) CONTAINS toLower($query) OR ... RETURN n`
-- Neighbors: `MATCH ({id: $id})-[r]-(m) RETURN m, r, startNode(r).id AS source, endNode(r).id AS target`
-
-## File Conventions
-
-- Backend handlers follow `*_handler.go` naming
-- Swagger annotations in handlers with `@Summary`, `@Router`, etc.
-- Frontend types in `types/graph.ts` shared between components
-- Graph styling utilities in `utils/graphStyle.ts`

README.md

@@ -1,277 +1,426 @@
 # knowledge-graph-agent
 
-🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术
+知识图谱驱动的学习辅助对话智能体项目。
+
+这个项目的目标不是单纯做一个聊天机器人，而是把“知识图谱”“对话”“记忆”“检索”“自动化”组合成一个可演进的智能体系统：
+
+- 以知识图谱作为核心数据结构
+- 以图谱查询作为对话上下文补充
+- 以图谱编辑作为知识沉淀方式
+- 以后续的记忆、自省、任务编排作为增强方向
 
 ---
 
-## MVP 开发任务清单
+## 一、项目目标
 
-### 技术栈
+### 1.1 解决什么问题
 
-**后端**
+传统问答系统通常只有“输入文本 -> 生成回答”的链路，缺少可追溯、可扩展、可持续积累的知识结构。
 
-- 语言: Go 1.26.1
-- 框架: Gin 1.12.0
-- 数据库: Neo4j 5.x
-- AI 服务: 硅基流动 OpenAI Completion
+本项目希望补上这几个部分：
 
-**前端**
+- 把知识拆成节点和边，形成图谱
+- 让用户可以查询、编辑、扩展知识
+- 让对话不仅依赖模型参数，还能依赖图谱上下文
+- 为后续的记忆层、自省层、任务层预留架构
 
-- 框架: React 19.2.4 + TypeScript 5.9.3
-- 图谱可视化: AntV G6 5.1.0
-- 状态管理: Zustand 5.0.12
-- 样式: Tailwind CSS 4.2.2
-- HTTP 客户端: Axios 1.14.0
+### 1.2 核心能力
+
+当前设计中的核心能力包括：
+
+1. 图谱查询
+   - 查询整图
+   - 查询节点详情
+   - 查询邻居关系
+   - 搜索节点
+   - 获取统计信息
+
+2. 图谱编辑
+   - 创建节点
+   - 更新节点
+   - 删除节点
+   - 创建边
+   - 删除边
+
+3. 对话增强
+   - 基于图谱检索上下文
+   - 为 LLM 提供简化图数据
+   - 为后续 Chat API 预留能力
+
+4. 后续扩展
+   - 层级记忆
+   - 自省反馈
+   - CoT 推理增强
+   - 邮件自动化
+   - 定时任务
 
 ---
 
-## 阶段一： Neo4j 数据库集成
+## 二、整体架构
 
-### 1.1 环境搭建
+### 2.1 总体分层
 
-- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
-  - 使用服务器提供的数据库实例
-  - 验证服务运行状态
-  - 配置基础认证（用户名/密码）
-  - 记录连接信息（bolt://47.121.181.112:7687）
-- [ ] 选择并安装 Go Neo4j 客户端库
-  - 评估候选库（如 github.com/neo4j/neo4j-go-driver）
-  - 添加到 go.mod
-  - 运行 `go mod tidy`
+```mermaid
+flowchart TB
+  subgraph UI[用户 / 前端]
+    User[用户]
+    Web[Web 前端]
+  end
 
-- [ ] 配置数据库连接字符串
-  - 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
-  - 在 `main.go` 中读取并验证连接
-  - 实现简单的健康检查接口（GET /db/health）
+  subgraph API[后端 API 层]
+    Router[Gin Router]
+    GH[GraphHandler]
+    NH[NodeHandler]
+    SH[SearchHandler]
+    CRUD[NodeCRUDHandler / EdgeCRUDHandler]
+  end
 
-### 1.2 数据模型设计与迁移
+  subgraph APP[业务服务层]
+    GS[GraphService Interface]
+    GQ[graph_queries.go]
+    GC[graph_crud.go]
+    GSIMPLE[graph_simple.go]
+    UTL[neo4j_utils.go]
+  end
 
-- [ ] 设计 Neo4j 节点与边的属性模型
-  - 节点标签（例如：Concept、Tool、Application）
-  - 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
-  - 关系类型：RELATIONSHIP、DEPENDENCY等
-  - 关系属性：id、label、type、properties、style（JSON）
+  subgraph INFRA[基础设施层]
+    Driver[Neo4j Driver]
+    Neo4j[(Neo4j 5.x)]
+  end
 
-- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
-  - 读取现有 `data.json`
-  - 创建 Neo4j 节点（批量 CREATE）
-  - 创建 Neo4j 关系（批量 CREATE）
-  - 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
-  - 输出迁移统计（节点数、边数）
+  User --> Web
+  Web --> Router
+  Router --> GH
+  Router --> NH
+  Router --> SH
+  Router --> CRUD
 
-- [ ] 执行迁移并验证数据完整性
-  - 运行迁移脚本
-  - 在 Neo4j Browser 中执行 Cypher 验证：
-    - `MATCH (n) RETURN count(n) AS totalNodes`
-    - `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
-  - 对比原始 JSON 的统计
+  GH --> GS
+  NH --> GS
+  SH --> GS
+  CRUD --> GS
 
-### 1.3 Neo4j 数据服务层
+  GS --> GQ
+  GS --> GC
+  GS --> GSIMPLE
+  GQ --> UTL
+  GC --> UTL
+  GSIMPLE --> UTL
 
-- [ ] 创建 `services/neo4j_service.go`
-  - 实现 `NewNeo4jService(uri, username, password)`
-  - 实现基础 CRUD 接口：
-    - `GetAllNodes() ([]Node, error)`
-    - `GetAllEdges() ([]Edge, error)`
-    - `GetNodeByID(id string) (Node, error)`
-    - `GetNeighbors(nodeID string) (nodes []Node, edges []Edge, error)`
-    - `SearchNodes(query string) ([]Node, error)`
+  GQ --> Driver
+  GC --> Driver
+  GSIMPLE --> Driver
+  Driver --> Neo4j
+```
 
-- [ ] 在 `services/data_service.go` 中切换数据源
-  - 移除 JSON 文件加载逻辑
-  - 注入 `Neo4jService` 依赖
-  - 更新现有方法委托给 Neo4j 查询：
-    - `GetGraphData()`
-    - `GetNodeByID()`
-    - `GetNeighbors()`
-    - `SearchNodes()`
-    - `GetStats()`
+### 2.2 请求流转方式
 
-- [ ] 添加并发安全与连接池管理
-  - 使用 Neo4j 驱动会话管理
-  - 确保连接池合理设置
-  - 添加重试机制（简单指数退避）
+一次典型请求的流转如下：
 
-### 1.4 API 验证与测试
+1. 用户在前端发起请求
+2. Gin Router 根据路径分发到对应 handler
+3. Handler 解析参数并调用 service
+4. Service 执行 Neo4j 查询或写入
+5. Neo4j 返回记录后，Service 转换成 API 模型
+6. Handler 将结果返回给前端
 
-- [ ] 后端单元测试
-  - 为 `neo4j_service.go` 编写测试
-  - Mock Neo4j 驱动（如有工具支持）或使用集成测试
-  - 测试搜索与邻居查询
+这个流程的重点是：
 
-- [ ] API 契约测试
-  - 使用 Postman 或 curl 验证：
-    - GET /api/graph
-    - GET /api/nodes/:id
-    - GET /api/nodes/:id/neighbors
-    - GET /api/search?q=query
-
-- [ ] 前端兼容性验证
-  - 服务端无需修改即可兼容现有前端
-  - 验证图谱渲染、搜索、节点详情、邻居加载
+- HTTP 细节停留在 Handler
+- 业务逻辑停留在 Service
+- 数据访问细节停留在 Neo4j driver 和工具函数中
 
 ---
 
-## 阶段二：图谱构建功能增强
+## 三、技术栈
 
-### 2.1 后端 CRUD API
+### 3.1 后端
 
-- [ ] 创建节点 API
-  - POST /api/nodes
-  - 请求体：`{label, type, properties, x, y, style}`
-  - 实现：调用 Neo4j CREATE 节点
-  - 返回：新建节点的完整信息
+- Go 1.26.1
+- Gin 1.12.0
+- Neo4j 5.x
+- Swagger / Swaggo
+- CORS 中间件
 
-- [ ] 更新节点 API
-  - PUT /api/nodes/:id
-  - 请求体：`{label, type, properties, x, y, style}`
-  - 实现：调用 Neo4j SET 更新指定节点属性
-  - 返回：更新后节点
-  - 错误处理：节点不存在返回 404
+### 3.2 前端
 
-- [ ] 删除节点 API
-  - DELETE /api/nodes/:id
-  - 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
-  - 返回：204 No Content 或 404
+- React 19.2.4
+- TypeScript 5.9.3
+- AntV G6 5.1.0
+- Zustand 5.0.12
+- Tailwind CSS 4.2.2
+- Axios 1.14.0
 
-- [ ] 创建边（关系）API
-  - POST /api/edges
-  - 请求体：`{source, target, label, type, properties, style}`
-  - 实现：使用 Cypher MATCH + CREATE 创建关系
-  - 返回：新建边的完整信息
-  - 验证 source 和 target 节点是否存在
+### 3.3 外部能力
 
-- [ ] 更新边 API
-  - PUT /api/edges/:id
-  - 请求体：`{label, type, properties, style}`
-  - 实现：使用 Cypher 找到边并 SET 属性
-  - 返回：更新后边
-
-- [ ] 删除边 API
-  - DELETE /api/edges/:id
-  - 实现：Cypher DELETE 关系
-  - 返回：204 No Content 或 404
-
-### 2.2 批量操作 API
-
-- [ ] 批量创建节点 API
-  - POST /api/nodes/batch
-  - 请求体：`{nodes: [...]}`
-  - 实现：事务批量创建，任一失败则全部回滚
-  - 返回：成功与失败清单
-
-- [ ] 批量创建边 API
-  - POST /api/edges/batch
-  - 请求体：`{edges: [...]}`
-  - 实现：事务批量创建边
-  - 返回：创建成功数量与失败清单
-
-### 2.3 前端编辑界面
-
-- [ ] 新增编辑状态与管理
-  - 在 `graphStore.ts` 中添加 `editingNode` 与 `editingEdge`
-  - 添加方法：`startEditingNode(node)`、`startEditingEdge(edge)`、`cancelEditing()`、`saveNode/Edge()`
-
-- [ ] 节点编辑 Dialog 组件
-  - 表单字段：label、type、properties（JSON 编辑器）、x、y、style（JSON 编辑器）
-  - 用于新建与更新节点
-  - 集成到节点详情面板或右键菜单
-
-- [ ] 边编辑 Dialog 组件
-  - 表单字段：label、type、properties、style
-  - 用于新建与更新边
-  - 集成到边点击交互或右键菜单
-
-- [ ] 增强图谱视图交互
-  - 支持从工具栏拖拽创建节点
-  - 支持通过连线工具创建边（点击两个节点）
-  - 实时回显编辑结果
-
-### 2.4 数据持久化与刷新
-
-- [ ] 前端自动刷新机制
-  - CRUD 操作后自动调用 `loadGraphData()` 刷新图谱
-  - 优化：对于增量更新，避免全量重绘
-
-- [ ] 添加撤销与重做
-  - 维护操作历史栈
-  - 提供 Undo/Redo 方法与按钮
+- Neo4j 数据库：存储图谱节点和关系
+- 硅基流动 OpenAI Completion：后续用于对话和推理增强
 
 ---
 
-## 阶段三：智能对话基础功能
+## 四、仓库结构
 
-### 3.1 AI 客户端封装
+```mermaid
+flowchart TD
+  Repo[knowledge-graph-agent/] --> RootReadme[README.md]
+  Repo --> Backend[backend/]
 
-- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
-- [ ] 创建 `services/ai_service.go`
-  - 方法：`NewAIService(apiKey, baseURL)`
-  - 核心方法：`ChatCompletion(messages []Message) (string, error)`
-  - 实现：调用硅基流动 OpenAI Completion 接口
-  - 添加请求超时与错误处理
+  Backend --> BackendReadme[README.md]
+  Backend --> Cmd[cmd/server/]
+  Backend --> Docs[docs/]
+  Backend --> Internal[internal/]
 
-- [ ] 请求与响应模型定义
-  - `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
-  - 统一错误类型与包装
+  Cmd --> Main[main.go]
 
-### 3.2 对话 API
+  Internal --> Config[config/]
+  Internal --> Handler[handler/]
+  Internal --> Model[model/]
+  Internal --> Repository[repository/neo4j/]
+  Internal --> Service[service/]
 
-- [ ] 对话会话管理
-  - 创建 `services/conversation_service.go`
-  - 维护会话上下文（最近 N 条消息）
-  - 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
+  Handler --> GH[graph_handler.go]
+  Handler --> NH[node_handler.go]
+  Handler --> SH[search_handler.go]
+  Handler --> CRUD[crud_handler.go]
 
-- [ ] 创建对话 API
-  - POST /api/chat
-  - 请求体：`{message, sessionId?}`
-  - 实现：
-    1. 创建或获取会话
-    2. 添加用户消息到历史
-    3. 调用 `AIService.ChatCompletion`
-    4. 保存 AI 回复到历史
-    5. 返回 AI 回复
-  - 支持流式返回（如平台支持）
-
-### 3.3 图谱查询与对话集成
-
-- [ ] 知识检索策略
-  - 在 `neo4j_service.go` 中添加：
-    - `SearchNodesByKeywords(keywords []string) ([]Node, error)`
-    - `GetRelevantContext(nodeID string, depth int) ([]Node, []Edge, error)`
-  - 支持根据消息关键词检索相关节点
-
-- [ ] 上下文增强生成
-  - 在对话前步骤：
-    - 提取消息中的关键实体或关键词
-    - 检索图谱中的相关节点与关系
-    - 将检索结果作为系统提示或上下文注入到对话请求
-  - 输出格式：自然语言摘要或结构化 JSON（根据需求）
-
-- [ ] 优化 AI 提示词
-  - 设计 System Prompt：介绍图谱助手角色与能力
-  - 提供示例对话
-
-### 3.4 前端对话界面
-
-- [ ] 创建 Chat 组件
-  - 消息列表（用户消息与 AI 消息）
-  - 输入框与发送按钮
-  - 显示加载状态
-
-- [ ] 集成到图谱页面
-  - 在 `KnowledgeGraph.tsx` 中添加 Chat 组件
-  - 配置布局（侧边或底部面板）
-
-- [ ] 增强交互
-  - 支持快捷键发送（Enter）
-  - 显示会话历史切换（可选）
-  - 消息支持 Markdown 渲染
+  Service --> IF[interface.go]
+  Service --> Q[graph_queries.go]
+  Service --> C[graph_crud.go]
+  Service --> S[graph_simple.go]
+  Service --> U[neo4j_utils.go]
+```
 
 ---
 
-## 后续增强阶段（非 MVP）
+## 五、后端模块说明
 
+如果你只看后端，建议优先阅读 `backend/README.md`。
+
+这里先给一个简化理解：
+
+### 5.1 Handler 层做什么
+
+- 接收 HTTP 请求
+- 解析参数
+- 调用 service
+- 返回 JSON
+
+### 5.2 Service 层做什么
+
+- 执行业务逻辑
+- 组织 Cypher 查询
+- 将 Neo4j 结果转换为 API 模型
+- 处理图数据、图编辑、搜索、统计等能力
+
+### 5.3 Repository / Driver 层做什么
+
+- 初始化 Neo4j 连接
+- 提供驱动实例
+- 负责和数据库建立底层通信
+
+### 5.4 Model 层做什么
+
+- 定义节点、边、图数据、请求、响应模型
+- 统一前后端传输格式
+
+---
+
+## 六、后端当前能力
+
+### 6.1 图查询
+
+- 获取整图
+- 获取节点详情
+- 获取节点邻居
+- 获取图统计
+- 获取简化图数据
+- 搜索节点
+
+### 6.2 图编辑
+
+- 创建节点
+- 更新节点
+- 删除节点
+- 创建边
+- 删除边
+
+### 6.3 对话准备能力
+
+- 简化图数据适合输入给 LLM
+- 图谱检索可作为上下文增强来源
+- 后续可扩展会话与记忆能力
+
+---
+
+## 七、主要 API 设计
+
+### 7.1 基础接口
+
+- `GET /health`
+  - 健康检查
+- `GET /api/graph`
+  - 获取完整图数据
+- `GET /api/graph/stats`
+  - 获取图统计
+- `GET /api/graph/simpleJson`
+  - 获取简化图数据
+- `GET /api/search?q=xxx`
+  - 搜索节点
+- `GET /api/nodes/:id`
+  - 获取节点详情
+- `GET /api/nodes/:id/neighbors`
+  - 获取邻居
+
+### 7.2 CRUD 接口
+
+- `POST /api/nodes`
+- `PUT /api/nodes/:id`
+- `DELETE /api/nodes/:id`
+- `POST /api/edges`
+- `DELETE /api/edges/:id`
+
+### 7.3 API 响应风格
+
+当前后端倾向于：
+
+- 成功时返回模型对象或结果对象
+- 失败时返回统一错误结构
+- 使用 JSON 作为默认响应格式
+
+---
+
+## 八、数据模型设计
+
+### 8.1 节点
+
+节点对象通常包含：
+
+- `id`
+- `label`
+- `type`
+- `x`
+- `y`
+- `style`
+- `properties`
+
+### 8.2 边
+
+边对象通常包含：
+
+- `id`
+- `source`
+- `target`
+- `label`
+- `type`
+- `style`
+- `properties`
+
+### 8.3 简化图数据
+
+为了服务 LLM 和摘要场景，后端还提供简化图结构：
+
+- `SimpleNode`
+  - 仅保留最核心字段
+- `SimpleEdge`
+  - 仅保留最核心字段
+
+---
+
+## 九、当前开发状态
+
+> 这里保留的是产品与实现层面的任务视图，不是严格的发布计划。
+
+### 9.1 已落地的方向
+
+- Neo4j 接入
+- 图查询 API
+- 节点 / 边 CRUD API
+- 简化图数据输出
+- Swagger 文档
+- 服务层拆分与工具抽取
+
+### 9.2 后续计划中的能力
+
+- 批量创建节点 / 边
+- 更细粒度的错误码
+- 服务测试与 handler 测试
+- 对话 API
+- 图谱上下文检索
 - 记忆与自省系统
+
+---
+
+## 十、文档关系图
+
+```mermaid
+flowchart LR
+  RootDoc[README.md] --> BackendDoc[backend/README.md]
+  RootDoc --> ProjectGoals[项目目标与全局结构]
+  BackendDoc --> BackendArch[后端架构与 API 细节]
+  BackendDoc --> BackendModels[数据模型与模块拆分]
+```
+
+---
+
+## 十一、如何开始理解这个项目
+
+推荐阅读顺序：
+
+1. `README.md`：先看整体目标和仓库结构
+2. `backend/README.md`：再看后端架构和 API
+3. `backend/cmd/server/main.go`：理解启动入口
+4. `backend/internal/handler/`：理解 HTTP 层
+5. `backend/internal/service/`：理解业务层
+
+如果你的关注点是前端图谱交互，那么可以先看：
+
+- 图数据 API
+- 简化图数据结构
+- 节点 / 边 CRUD 接口
+
+如果你的关注点是后续 LLM 增强，那么可以先看：
+
+- `GetSimpleGraphData()`
+- 图谱搜索接口
+- 未来的对话上下文注入逻辑
+
+---
+
+## 十二、未来扩展方向
+
+### 12.1 记忆与自省
+
+- 会话记忆
+- 长短期记忆分层
+- 反馈驱动的自我修正
+
+### 12.2 自动化能力
+
 - 邮件自动化
 - 定时任务
-- CoT 推理增强
+- 触发式工作流
+
+### 12.3 推理增强
+
+- CoT 提示增强
+- 图谱检索增强生成
+- 多轮上下文压缩
+
+### 12.4 工程化增强
+
+- 批量操作 API
+- 权限控制
+- 审计日志
+- 测试覆盖率提升
+- 统一错误码与响应规范
+
+---
+
+## 十三、补充说明
+
+如果你后面希望我继续整理，我可以直接帮你做下面任一项：
+
+- 把根目录 README 再改成“项目介绍版”或“开发指南版”
+- 给后端 README 增加更细的接口表格和请求/响应样例
+- 继续补一张“前后端交互时序图”
+- 把整个项目的文档风格统一成一套模板

backend/README.md

@@ -1,279 +1,559 @@
-# knowledge-graph-agent
+# knowledge-graph-backend
 
-🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术
+知识图谱后端服务，基于 Go + Gin + Neo4j 构建，面向图谱查询、图谱编辑、搜索、统计与对话增强能力提供统一 API。
 
-[Swagger 文档](http://localhost:3001/swagger/index.html)
+这份文档聚焦于后端当前已经实现的结构与运行方式，帮助你快速理解：
+
+- 请求是如何进入系统的
+- Handler / Service / Neo4j Driver 之间如何协作
+- 图数据是如何从 Neo4j 读写出来的
+- 后续扩展功能应该从哪里接入
 
 ---
 
-## MVP 开发任务清单
+## 一、系统定位
 
-### 技术栈
+当前后端主要承担以下职责：
 
-**后端**
-
-- 语言: Go 1.26.1
-- 框架: Gin 1.12.0
-- 数据库: Neo4j 5.x
-- AI 服务: 硅基流动 OpenAI Completion
-
-**前端**
-
-- 框架: React 19.2.4 + TypeScript 5.9.3
-- 图谱可视化: AntV G6 5.1.0
-- 状态管理: Zustand 5.0.12
-- 样式: Tailwind CSS 4.2.2
-- HTTP 客户端: Axios 1.14.0
+1. 对外暴露图谱相关 HTTP API
+2. 将前端请求转换为对 Neo4j 的查询或写入
+3. 统一节点、边、图数据、错误响应的格式
+4. 为后续 LLM / 对话增强能力预留简化图数据与上下文检索接口
 
 ---
 
-## 阶段一： Neo4j 数据库集成
+## 二、运行时架构
 
-### 1.1 环境搭建
+### 2.1 整体调用链
 
-- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
-  - 使用服务器提供的数据库实例
-  - 验证服务运行状态
-  - 配置基础认证（用户名/密码）
-  - 记录连接信息（bolt://47.121.181.112:7687）
-- [x] 选择并安装 Go Neo4j 客户端库
-  - 评估候选库（如 github.com/neo4j/neo4j-go-driver）
-  - 添加到 go.mod
-  - 运行 `go mod tidy`
+```mermaid
+flowchart LR
+  Client[前端 / Postman / curl] --> Router[gin.Engine]
+  Router --> Health[/GET /health/]
+  Router --> Swagger[/GET /swagger/*any/]
+  Router --> API[/GET /api/*\nPOST /api/*\nPUT /api/*\nDELETE /api/*/]
 
-- [x] 配置数据库连接字符串
-  - 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
-  - 在 `main.go` 中读取并验证连接
-  - 实现简单的健康检查接口（GET /db/health）
+  API --> GH[GraphHandler]
+  API --> NH[NodeHandler]
+  API --> SH[SearchHandler]
+  API --> CRUD[NodeCRUDHandler / EdgeCRUDHandler]
 
-### 1.2 数据模型设计与迁移
+  GH --> SVC[GraphService]
+  NH --> SVC
+  SH --> SVC
+  CRUD --> SVC
 
-- [x] 设计 Neo4j 节点与边的属性模型
-  - 节点标签（例如：Concept、Tool、Application）
-  - 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
-  - 关系类型：RELATIONSHIP、DEPENDENCY等
-  - 关系属性：id、label、type、properties、style（JSON）
+  SVC --> Q[graph_queries.go]
+  SVC --> C[graph_crud.go]
+  SVC --> X[graph_simple.go]
+  SVC --> U[neo4j_utils.go]
 
-- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
-  - 读取现有 `data.json`
-  - 创建 Neo4j 节点（批量 CREATE）
-  - 创建 Neo4j 关系（批量 CREATE）
-  - 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
-  - 输出迁移统计（节点数、边数）
+  Q --> D[Neo4j Driver]
+  C --> D
+  X --> D
+  D --> DB[(Neo4j 5.x)]
+```
 
-- [ ] 执行迁移并验证数据完整性
-  - 运行迁移脚本
-  - 在 Neo4j Browser 中执行 Cypher 验证：
-    - `MATCH (n) RETURN count(n) AS totalNodes`
-    - `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
-  - 对比原始 JSON 的统计
+### 2.2 分层职责
 
-### 1.3 Neo4j 数据服务层
+#### 路由层
 
-- [ ] 创建 `services/neo4j_service.go`
-  - 实现 `NewNeo4jService(uri, username, password)`
-  - 实现基础 CRUD 接口：
-    - `GetAllNodes() ([]Node, error)`
-    - `GetAllEdges() ([]Edge, error)`
-    - `GetNodeByID(id string) (Node, error)`
-    - `GetNeighbors(nodeID string) (nodes []Node, edges []Edge, error)`
-    - `SearchNodes(query string) ([]Node, error)`
+入口位于 `cmd/server/main.go`。
 
-- [ ] 在 `services/data_service.go` 中切换数据源
-  - 移除 JSON 文件加载逻辑
-  - 注入 `Neo4jService` 依赖
-  - 更新现有方法委托给 Neo4j 查询：
-    - `GetGraphData()`
-    - `GetNodeByID()`
-    - `GetNeighbors()`
-    - `SearchNodes()`
-    - `GetStats()`
+这一层负责：
 
-- [ ] 添加并发安全与连接池管理
-  - 使用 Neo4j 驱动会话管理
-  - 确保连接池合理设置
-  - 添加重试机制（简单指数退避）
+- 加载配置
+- 初始化 Neo4j 驱动
+- 创建 service 实例
+- 创建 handler 实例
+- 注册路由与 Swagger
+- 启动 HTTP 服务
 
-### 1.4 API 验证与测试
+#### Handler 层
 
-- [ ] 后端单元测试
-  - 为 `neo4j_service.go` 编写测试
-  - Mock Neo4j 驱动（如有工具支持）或使用集成测试
-  - 测试搜索与邻居查询
+目录：`internal/handler/`
 
-- [ ] API 契约测试
-  - 使用 Postman 或 curl 验证：
-    - GET /api/graph
-    - GET /api/nodes/:id
-    - GET /api/nodes/:id/neighbors
-    - GET /api/search?q=query
+Handler 的职责只包括：
 
-- [ ] 前端兼容性验证
-  - 服务端无需修改即可兼容现有前端
-  - 验证图谱渲染、搜索、节点详情、邻居加载
+- 读取 path / query / body 参数
+- 调用 service
+- 按统一格式返回 JSON
+- 在必要时返回错误状态码
+
+当前 handler 组成：
+
+- `graph_handler.go`
+  - `GET /api/graph`
+  - `GET /api/graph/stats`
+  - `GET /api/graph/simpleJson`
+- `node_handler.go`
+  - `GET /api/nodes/:id`
+  - `GET /api/nodes/:id/neighbors`
+- `search_handler.go`
+  - `GET /api/search?q=...`
+- `crud_handler.go`
+  - `POST /api/nodes`
+  - `PUT /api/nodes/:id`
+  - `DELETE /api/nodes/:id`
+  - `POST /api/edges`
+  - `DELETE /api/edges/:id`
+
+#### Service 层
+
+目录：`internal/service/`
+
+Service 是核心业务层，负责：
+
+- 查询图数据
+- 搜索节点
+- 获取邻居
+- 增删改节点与边
+- 对 Neo4j 结果做模型转换
+- 封装公共工具函数
+
+当前文件拆分如下：
+
+- `interface.go`
+  - 定义 `GraphService` 接口
+- `graph_queries.go`
+  - 图查询、搜索、统计、邻居、简化图数据
+- `graph_crud.go`
+  - 节点 / 边创建、更新、删除
+- `graph_simple.go`
+  - 简化图数据输出
+- `neo4j_utils.go`
+  - Neo4j 记录转换、属性提取、字段清洗、辅助函数
+
+#### Repository / Driver 层
+
+目录：`internal/repository/neo4j/`
+
+这里负责 Neo4j 驱动初始化与连接配置。
 
 ---
 
-## 阶段二：图谱构建功能增强
+## 三、模块关系图
 
-### 2.1 后端 CRUD API
+### 3.1 控制流关系
 
-- [ ] 创建节点 API
-  - POST /api/nodes
-  - 请求体：`{label, type, properties, x, y, style}`
-  - 实现：调用 Neo4j CREATE 节点
-  - 返回：新建节点的完整信息
+```mermaid
+flowchart TD
+  subgraph HTTP[HTTP API]
+    GH[GraphHandler]
+    NH[NodeHandler]
+    SH[SearchHandler]
+    CH[NodeCRUDHandler]
+    EH[EdgeCRUDHandler]
+  end
 
-- [ ] 更新节点 API
-  - PUT /api/nodes/:id
-  - 请求体：`{label, type, properties, x, y, style}`
-  - 实现：调用 Neo4j SET 更新指定节点属性
-  - 返回：更新后节点
-  - 错误处理：节点不存在返回 404
+  subgraph Domain[Service Layer]
+    GS[GraphService Interface]
+    GQ[graph_queries.go]
+    GC[graph_crud.go]
+    GSIMPLE[graph_simple.go]
+    UTIL[neo4j_utils.go]
+  end
 
-- [ ] 删除节点 API
-  - DELETE /api/nodes/:id
-  - 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
-  - 返回：204 No Content 或 404
+  subgraph Infra[Infrastructure]
+    DRIVER[Neo4j Driver]
+    DB[(Neo4j Database)]
+  end
 
-- [ ] 创建边（关系）API
-  - POST /api/edges
-  - 请求体：`{source, target, label, type, properties, style}`
-  - 实现：使用 Cypher MATCH + CREATE 创建关系
-  - 返回：新建边的完整信息
-  - 验证 source 和 target 节点是否存在
+  GH --> GS
+  NH --> GS
+  SH --> GS
+  CH --> GS
+  EH --> GS
 
-- [ ] 更新边 API
-  - PUT /api/edges/:id
-  - 请求体：`{label, type, properties, style}`
-  - 实现：使用 Cypher 找到边并 SET 属性
-  - 返回：更新后边
+  GS --> GQ
+  GS --> GC
+  GS --> GSIMPLE
+  GQ --> UTIL
+  GC --> UTIL
+  GSIMPLE --> UTIL
 
-- [ ] 删除边 API
-  - DELETE /api/edges/:id
-  - 实现：Cypher DELETE 关系
-  - 返回：204 No Content 或 404
+  GQ --> DRIVER
+  GC --> DRIVER
+  GSIMPLE --> DRIVER
+  DRIVER --> DB
+```
 
-### 2.2 批量操作 API
+### 3.2 数据结构关系
 
-- [ ] 批量创建节点 API
-  - POST /api/nodes/batch
-  - 请求体：`{nodes: [...]}`
-  - 实现：事务批量创建，任一失败则全部回滚
-  - 返回：成功与失败清单
+```mermaid
+classDiagram
+  class GraphData {
+    +[]Node nodes
+    +[]Edge edges
+  }
 
-- [ ] 批量创建边 API
-  - POST /api/edges/batch
-  - 请求体：`{edges: [...]}`
-  - 实现：事务批量创建边
-  - 返回：创建成功数量与失败清单
+  class SimpleGraphData {
+    +[]SimpleNode nodes
+    +[]SimpleEdge edges
+  }
 
-### 2.3 前端编辑界面
+  class Node {
+    +string id
+    +string label
+    +string type
+    +float64 x
+    +float64 y
+    +map style
+    +map properties
+  }
 
-- [ ] 新增编辑状态与管理
-  - 在 `graphStore.ts` 中添加 `editingNode` 与 `editingEdge`
-  - 添加方法：`startEditingNode(node)`、`startEditingEdge(edge)`、`cancelEditing()`、`saveNode/Edge()`
+  class Edge {
+    +string id
+    +string source
+    +string target
+    +string label
+    +string type
+    +map style
+    +map properties
+  }
 
-- [ ] 节点编辑 Dialog 组件
-  - 表单字段：label、type、properties（JSON 编辑器）、x、y、style（JSON 编辑器）
-  - 用于新建与更新节点
-  - 集成到节点详情面板或右键菜单
+  class GraphService {
+    +GetGraphData() GraphData
+    +GetSimpleGraphData() SimpleGraphData
+    +GetNodeByID(id) Node
+    +SearchNodes(query) []Node
+    +GetNeighbors(nodeID) NeighborResponse
+    +GetStats() map
+    +CreateNode(req) Node
+    +UpdateNode(id, req) Node
+    +DeleteNode(id) error
+    +CreateEdge(req) Edge
+    +DeleteEdge(id) error
+  }
 
-- [ ] 边编辑 Dialog 组件
-  - 表单字段：label、type、properties、style
-  - 用于新建与更新边
-  - 集成到边点击交互或右键菜单
-
-- [ ] 增强图谱视图交互
-  - 支持从工具栏拖拽创建节点
-  - 支持通过连线工具创建边（点击两个节点）
-  - 实时回显编辑结果
-
-### 2.4 数据持久化与刷新
-
-- [ ] 前端自动刷新机制
-  - CRUD 操作后自动调用 `loadGraphData()` 刷新图谱
-  - 优化：对于增量更新，避免全量重绘
-
-- [ ] 添加撤销与重做
-  - 维护操作历史栈
-  - 提供 Undo/Redo 方法与按钮
+  GraphData --> Node
+  GraphData --> Edge
+  SimpleGraphData --> Node
+  SimpleGraphData --> Edge
+  GraphService ..> GraphData
+  GraphService ..> SimpleGraphData
+  GraphService ..> Node
+  GraphService ..> Edge
+```
 
 ---
 
-## 阶段三：智能对话基础功能
+## 四、API 能力
 
-### 3.1 AI 客户端封装
+### 4.1 健康检查
 
-- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
-- [ ] 创建 `services/ai_service.go`
-  - 方法：`NewAIService(apiKey, baseURL)`
-  - 核心方法：`ChatCompletion(messages []Message) (string, error)`
-  - 实现：调用硅基流动 OpenAI Completion 接口
-  - 添加请求超时与错误处理
+- `GET /health`
 
-- [ ] 请求与响应模型定义
-  - `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
-  - 统一错误类型与包装
+用途：确认服务是否运行。
 
-### 3.2 对话 API
+返回示例：
 
-- [ ] 对话会话管理
-  - 创建 `services/conversation_service.go`
-  - 维护会话上下文（最近 N 条消息）
-  - 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
+```json
+{
+  "status": "ok",
+  "message": "Knowledge Graph API is running",
+  "version": "1.0.0"
+}
+```
 
-- [ ] 创建对话 API
-  - POST /api/chat
-  - 请求体：`{message, sessionId?}`
-  - 实现：
-    1. 创建或获取会话
-    2. 添加用户消息到历史
-    3. 调用 `AIService.ChatCompletion`
-    4. 保存 AI 回复到历史
-    5. 返回 AI 回复
-  - 支持流式返回（如平台支持）
+### 4.2 图数据查询
 
-### 3.3 图谱查询与对话集成
+- `GET /api/graph`
+  - 返回完整节点与边
+- `GET /api/graph/stats`
+  - 返回节点数、边数和分类统计
+- `GET /api/graph/simpleJson`
+  - 返回简化图数据，适合 LLM 或轻量消费端
 
-- [ ] 知识检索策略
-  - 在 `neo4j_service.go` 中添加：
-    - `SearchNodesByKeywords(keywords []string) ([]Node, error)`
-    - `GetRelevantContext(nodeID string, depth int) ([]Node, []Edge, error)`
-  - 支持根据消息关键词检索相关节点
+### 4.3 节点查询
 
-- [ ] 上下文增强生成
-  - 在对话前步骤：
-    - 提取消息中的关键实体或关键词
-    - 检索图谱中的相关节点与关系
-    - 将检索结果作为系统提示或上下文注入到对话请求
-  - 输出格式：自然语言摘要或结构化 JSON（根据需求）
+- `GET /api/nodes/:id`
+  - 获取单个节点
+- `GET /api/nodes/:id/neighbors`
+  - 获取该节点的邻居节点和相关边
 
-- [ ] 优化 AI 提示词
-  - 设计 System Prompt：介绍图谱助手角色与能力
-  - 提供示例对话
+### 4.4 搜索
 
-### 3.4 前端对话界面
+- `GET /api/search?q=xxx`
+  - 根据 `id`、`label`、`type` 模糊搜索节点
 
-- [ ] 创建 Chat 组件
-  - 消息列表（用户消息与 AI 消息）
-  - 输入框与发送按钮
-  - 显示加载状态
+### 4.5 图谱编辑
 
-- [ ] 集成到图谱页面
-  - 在 `KnowledgeGraph.tsx` 中添加 Chat 组件
-  - 配置布局（侧边或底部面板）
-
-- [ ] 增强交互
-  - 支持快捷键发送（Enter）
-  - 显示会话历史切换（可选）
-  - 消息支持 Markdown 渲染
+- `POST /api/nodes`
+- `PUT /api/nodes/:id`
+- `DELETE /api/nodes/:id`
+- `POST /api/edges`
+- `DELETE /api/edges/:id`
 
 ---
 
-## 后续增强阶段（非 MVP）
+## 五、请求与响应模型
 
-- 记忆与自省系统
-- 邮件自动化
-- 定时任务
-- CoT 推理增强
+### 5.1 节点模型
+
+节点保留以下标准字段：
+
+- `id`
+- `label`
+- `type`
+- `x`
+- `y`
+- `style`
+- `properties`
+
+其中：
+
+- `style` 适合前端可视化使用
+- `properties` 用于存放扩展字段
+
+### 5.2 边模型
+
+边保留以下标准字段：
+
+- `id`
+- `source`
+- `target`
+- `label`
+- `type`
+- `style`
+- `properties`
+
+### 5.3 统一错误响应
+
+后端使用统一的错误结构：
+
+- `error`
+- `message`
+
+这样前端可以基于同一格式做提示与状态分支处理。
+
+---
+
+## 六、Neo4j 数据映射
+
+### 6.1 节点映射原则
+
+Neo4j 节点到 API 节点模型的映射规则：
+
+- `id` → 节点唯一标识
+- `label` → 显示名称
+- `type` → 节点类型
+- `x/y/style` → 可视化信息
+- 其余字段 → 放入 `properties`
+
+### 6.2 边映射原则
+
+Neo4j 关系到 API 边模型的映射规则：
+
+- `id` → 边唯一标识
+- `label` → 边显示名称
+- `type` → 关系类型
+- `source/target` → 由起点和终点节点 ID 推导
+- 其余字段 → 放入 `properties`
+
+### 6.3 工具函数职责
+
+`neo4j_utils.go` 集中处理：
+
+- Neo4j Node / Relationship 转换
+- 通用取值函数
+- 保留字段判断
+- 字段名和关系类型清洗
+
+这样可以减少 CRUD 和查询代码里的重复逻辑。
+
+---
+
+## 七、服务拆分说明
+
+### 7.1 `graph_queries.go`
+
+负责读取类功能：
+
+- `GetGraphData()`
+- `GetNodeByID()`
+- `SearchNodes()`
+- `GetNeighbors()`
+- `GetStats()`
+
+这些方法面向“查询场景”，不修改数据库内容。
+
+### 7.2 `graph_crud.go`
+
+负责写入类功能：
+
+- `CreateNode()`
+- `UpdateNode()`
+- `DeleteNode()`
+- `CreateEdge()`
+- `DeleteEdge()`
+
+这些方法面向“编辑场景”，负责校验、写入、返回更新后的模型。
+
+### 7.3 `graph_simple.go`
+
+负责提供一个轻量版本的图数据：
+
+- `GetSimpleGraphData()`
+
+适合：
+
+- LLM 上下文注入
+- 快速摘要
+- 轻量前端消费
+
+---
+
+## 八、目录结构
+
+```mermaid
+flowchart TD
+  Root[backend/] --> Cmd[cmd/server/]
+  Root --> Docs[docs/]
+  Root --> Internal[internal/]
+  Root --> README[README.md]
+
+  Cmd --> Main[main.go]
+
+  Internal --> Config[config/]
+  Internal --> Handler[handler/]
+  Internal --> Model[model/]
+  Internal --> Repository[repository/neo4j/]
+  Internal --> Service[service/]
+
+  Handler --> GH[graph_handler.go]
+  Handler --> NH[node_handler.go]
+  Handler --> SH[search_handler.go]
+  Handler --> CRUD[crud_handler.go]
+
+  Service --> Interface[interface.go]
+  Service --> Q[graph_queries.go]
+  Service --> C[graph_crud.go]
+  Service --> Simple[graph_simple.go]
+  Service --> Utils[neo4j_utils.go]
+```
+
+---
+
+## 九、配置与启动
+
+### 9.1 常见配置项
+
+后端通常会从配置文件或环境变量中读取以下信息：
+
+- 服务端口
+- Neo4j URI
+- Neo4j 用户名
+- Neo4j 密码
+- CORS 允许源
+- 数据文件或迁移相关配置（若启用）
+
+### 9.2 启动方式
+
+在 `backend/` 目录下运行：
+
+```bash
+go run ./cmd/server
+```
+
+### 9.3 Swagger 地址
+
+启动后访问：
+
+```text
+http://localhost:3001/swagger/index.html
+```
+
+### 9.4 生成 Swagger 文档
+
+仓库根目录提供了两个脚本，方便重新生成 API 文档：
+
+- Linux / WSL / macOS：`./gen_swagger.sh`
+- Windows PowerShell：`./gen_swagger.ps1`
+
+脚本会自动切换到 `backend/` 目录，并执行：
+
+```bash
+swag init -g ./cmd/server/main.go --parseDependency --parseInternal
+```
+
+生成产物位于 `backend/docs/` 下：
+
+- `docs.go`
+- `swagger.json`
+- `swagger.yaml`
+
+如果遇到 `cannot find type definition: model.GraphData` 之类的报错，通常是 handler 文件里缺少 `internal/model` 的显式导入。
+
+---
+
+## 十、当前实现特点
+
+### 10.1 已完成的结构优化
+
+- Handler 与 Service 解耦
+- 图查询与 CRUD 拆分
+- 通用 Neo4j 工具统一收口
+- 使用统一错误结构
+- 使用 `GraphService` 接口约束业务能力
+
+### 10.2 当前行为特征
+
+- 图数据完全由 Neo4j 提供
+- 节点与边都支持扩展属性
+- 搜索同时覆盖 `id`、`label`、`type`
+- 邻居查询会返回邻居节点和边
+- 简化图数据适合 LLM 或摘要场景
+
+### 10.3 已知设计取向
+
+- 以可维护性优先，而不是一开始就追求极致抽象
+- 保留较直观的 Cypher 语句，方便调试与演进
+- 优先让 API 形状稳定，方便前端对接
+
+---
+
+## 十一、建议的下一步演进
+
+1. 补齐测试
+   - service 单元测试
+   - handler 测试
+   - Neo4j 交互测试
+
+2. 增加批量写入能力
+   - 批量创建节点
+   - 批量创建边
+
+3. 进一步规范错误语义
+   - `400 Bad Request`
+   - `404 Not Found`
+   - `409 Conflict`
+   - `500 Internal Server Error`
+
+4. 为对话增强做准备
+   - 上下文检索
+   - 相关节点提取
+   - 简化图摘要注入
+
+5. 进一步细分 service
+   - 如果后续功能继续增长，可以把查询、编辑、统计、上下文检索拆成更细粒度模块
+
+---
+
+## 十二、快速理解这套后端
+
+如果你第一次接触这个项目，可以按这个顺序看：
+
+1. `cmd/server/main.go`
+2. `internal/handler/`
+3. `internal/service/interface.go`
+4. `internal/service/graph_queries.go`
+5. `internal/service/graph_crud.go`
+6. `internal/service/neo4j_utils.go`
+
+这样能最快理解：
+
+- 请求如何流动
+- 图数据如何被读取和修改
+- 模型如何映射到 Neo4j
+- 后续扩展点在哪里

backend/cmd/server/main.go

@@ -10,7 +10,7 @@ import (
 	swaggerFiles "github.com/swaggo/files"
 	ginSwagger "github.com/swaggo/gin-swagger"
 
-	"knowledge-graph-backend/docs"
+	_ "knowledge-graph-backend/docs"
 	"knowledge-graph-backend/internal/config"
 	"knowledge-graph-backend/internal/handler"
 	neo4jClient "knowledge-graph-backend/internal/repository/neo4j"
@@ -45,7 +45,6 @@ func main() {
 
 	router.Use(cors.New(cfg.CORS.ToGinConfig()))
 
-	docs.SwaggerInfo.BasePath = "/"
 	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
 
 	// @Summary 健康检查

backend/docs/docs.go

@@ -32,7 +32,7 @@ const docTemplate = `{
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.CreateEdgeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest"
                         }
                     }
                 ],
@@ -40,31 +40,31 @@ const docTemplate = `{
                     "200": {
                         "description": "创建成功",
                         "schema": {
-                            "$ref": "#/definitions/model.EdgeResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.EdgeResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "源节点或目标节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "409": {
                         "description": "边已存在",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -90,19 +90,19 @@ const docTemplate = `{
                     "200": {
                         "description": "删除成功",
                         "schema": {
-                            "$ref": "#/definitions/model.DeleteResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse"
                         }
                     },
                     "404": {
                         "description": "边未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -119,13 +119,13 @@ const docTemplate = `{
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.GraphData"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.GraphData"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -142,13 +142,13 @@ const docTemplate = `{
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.SimpleGraphData"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -172,7 +172,7 @@ const docTemplate = `{
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -195,7 +195,7 @@ const docTemplate = `{
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.CreateNodeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest"
                         }
                     }
                 ],
@@ -203,25 +203,25 @@ const docTemplate = `{
                     "200": {
                         "description": "创建成功",
                         "schema": {
-                            "$ref": "#/definitions/model.Node"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "409": {
                         "description": "节点已存在",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -247,25 +247,25 @@ const docTemplate = `{
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.NodeResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.NodeResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -293,7 +293,7 @@ const docTemplate = `{
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.UpdateNodeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest"
                         }
                     }
                 ],
@@ -301,25 +301,25 @@ const docTemplate = `{
                     "200": {
                         "description": "更新成功",
                         "schema": {
-                            "$ref": "#/definitions/model.Node"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -343,19 +343,19 @@ const docTemplate = `{
                     "200": {
                         "description": "删除成功",
                         "schema": {
-                            "$ref": "#/definitions/model.DeleteResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -381,25 +381,25 @@ const docTemplate = `{
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.NeighborResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.NeighborResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -425,19 +425,19 @@ const docTemplate = `{
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.SearchResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.SearchResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -445,7 +445,7 @@ const docTemplate = `{
         }
     },
     "definitions": {
-        "model.CreateEdgeRequest": {
+        "knowledge-graph-backend_internal_model.CreateEdgeRequest": {
             "type": "object",
             "required": [
                 "id",
@@ -480,7 +480,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.CreateNodeRequest": {
+        "knowledge-graph-backend_internal_model.CreateNodeRequest": {
             "type": "object",
             "required": [
                 "id",
@@ -514,7 +514,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.DeleteResponse": {
+        "knowledge-graph-backend_internal_model.DeleteResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -531,7 +531,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.Edge": {
+        "knowledge-graph-backend_internal_model.Edge": {
             "type": "object",
             "properties": {
                 "id": {
@@ -559,7 +559,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.EdgeResponse": {
+        "knowledge-graph-backend_internal_model.EdgeResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -588,52 +588,54 @@ const docTemplate = `{
                 }
             }
         },
-        "model.ErrorResponse": {
+        "knowledge-graph-backend_internal_model.ErrorResponse": {
             "type": "object",
             "properties": {
                 "error": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "bad_request"
                 },
                 "message": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "invalid request"
                 }
             }
         },
-        "model.GraphData": {
+        "knowledge-graph-backend_internal_model.GraphData": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Edge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 }
             }
         },
-        "model.NeighborResponse": {
+        "knowledge-graph-backend_internal_model.NeighborResponse": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Edge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 }
             }
         },
-        "model.Node": {
+        "knowledge-graph-backend_internal_model.Node": {
             "type": "object",
             "properties": {
                 "id": {
@@ -661,7 +663,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.NodeResponse": {
+        "knowledge-graph-backend_internal_model.NodeResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -673,7 +675,7 @@ const docTemplate = `{
                 "neighbors": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 },
                 "properties": {
@@ -695,7 +697,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.SearchResponse": {
+        "knowledge-graph-backend_internal_model.SearchResponse": {
             "type": "object",
             "properties": {
                 "count": {
@@ -704,7 +706,7 @@ const docTemplate = `{
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 },
                 "query": {
@@ -712,7 +714,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.SimpleEdge": {
+        "knowledge-graph-backend_internal_model.SimpleEdge": {
             "type": "object",
             "properties": {
                 "label": {
@@ -733,24 +735,24 @@ const docTemplate = `{
                 }
             }
         },
-        "model.SimpleGraphData": {
+        "knowledge-graph-backend_internal_model.SimpleGraphData": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.SimpleEdge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleEdge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.SimpleNode"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleNode"
                     }
                 }
             }
         },
-        "model.SimpleNode": {
+        "knowledge-graph-backend_internal_model.SimpleNode": {
             "type": "object",
             "properties": {
                 "id": {
@@ -767,7 +769,7 @@ const docTemplate = `{
                 }
             }
         },
-        "model.UpdateNodeRequest": {
+        "knowledge-graph-backend_internal_model.UpdateNodeRequest": {
             "type": "object",
             "properties": {
                 "label": {

backend/docs/swagger.json

@@ -26,7 +26,7 @@
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.CreateEdgeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest"
                         }
                     }
                 ],
@@ -34,31 +34,31 @@
                     "200": {
                         "description": "创建成功",
                         "schema": {
-                            "$ref": "#/definitions/model.EdgeResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.EdgeResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "源节点或目标节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "409": {
                         "description": "边已存在",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -84,19 +84,19 @@
                     "200": {
                         "description": "删除成功",
                         "schema": {
-                            "$ref": "#/definitions/model.DeleteResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse"
                         }
                     },
                     "404": {
                         "description": "边未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -113,13 +113,13 @@
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.GraphData"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.GraphData"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -136,13 +136,13 @@
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.SimpleGraphData"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -166,7 +166,7 @@
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -189,7 +189,7 @@
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.CreateNodeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest"
                         }
                     }
                 ],
@@ -197,25 +197,25 @@
                     "200": {
                         "description": "创建成功",
                         "schema": {
-                            "$ref": "#/definitions/model.Node"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "409": {
                         "description": "节点已存在",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -241,25 +241,25 @@
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.NodeResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.NodeResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -287,7 +287,7 @@
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/model.UpdateNodeRequest"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest"
                         }
                     }
                 ],
@@ -295,25 +295,25 @@
                     "200": {
                         "description": "更新成功",
                         "schema": {
-                            "$ref": "#/definitions/model.Node"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -337,19 +337,19 @@
                     "200": {
                         "description": "删除成功",
                         "schema": {
-                            "$ref": "#/definitions/model.DeleteResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.DeleteResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -375,25 +375,25 @@
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.NeighborResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.NeighborResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "404": {
                         "description": "节点未找到",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -419,19 +419,19 @@
                     "200": {
                         "description": "成功",
                         "schema": {
-                            "$ref": "#/definitions/model.SearchResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.SearchResponse"
                         }
                     },
                     "400": {
                         "description": "请求错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     },
                     "500": {
                         "description": "内部错误",
                         "schema": {
-                            "$ref": "#/definitions/model.ErrorResponse"
+                            "$ref": "#/definitions/knowledge-graph-backend_internal_model.ErrorResponse"
                         }
                     }
                 }
@@ -439,7 +439,7 @@
         }
     },
     "definitions": {
-        "model.CreateEdgeRequest": {
+        "knowledge-graph-backend_internal_model.CreateEdgeRequest": {
             "type": "object",
             "required": [
                 "id",
@@ -474,7 +474,7 @@
                 }
             }
         },
-        "model.CreateNodeRequest": {
+        "knowledge-graph-backend_internal_model.CreateNodeRequest": {
             "type": "object",
             "required": [
                 "id",
@@ -508,7 +508,7 @@
                 }
             }
         },
-        "model.DeleteResponse": {
+        "knowledge-graph-backend_internal_model.DeleteResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -525,7 +525,7 @@
                 }
             }
         },
-        "model.Edge": {
+        "knowledge-graph-backend_internal_model.Edge": {
             "type": "object",
             "properties": {
                 "id": {
@@ -553,7 +553,7 @@
                 }
             }
         },
-        "model.EdgeResponse": {
+        "knowledge-graph-backend_internal_model.EdgeResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -582,52 +582,54 @@
                 }
             }
         },
-        "model.ErrorResponse": {
+        "knowledge-graph-backend_internal_model.ErrorResponse": {
             "type": "object",
             "properties": {
                 "error": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "bad_request"
                 },
                 "message": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "invalid request"
                 }
             }
         },
-        "model.GraphData": {
+        "knowledge-graph-backend_internal_model.GraphData": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Edge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 }
             }
         },
-        "model.NeighborResponse": {
+        "knowledge-graph-backend_internal_model.NeighborResponse": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Edge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Edge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 }
             }
         },
-        "model.Node": {
+        "knowledge-graph-backend_internal_model.Node": {
             "type": "object",
             "properties": {
                 "id": {
@@ -655,7 +657,7 @@
                 }
             }
         },
-        "model.NodeResponse": {
+        "knowledge-graph-backend_internal_model.NodeResponse": {
             "type": "object",
             "properties": {
                 "id": {
@@ -667,7 +669,7 @@
                 "neighbors": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 },
                 "properties": {
@@ -689,7 +691,7 @@
                 }
             }
         },
-        "model.SearchResponse": {
+        "knowledge-graph-backend_internal_model.SearchResponse": {
             "type": "object",
             "properties": {
                 "count": {
@@ -698,7 +700,7 @@
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.Node"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.Node"
                     }
                 },
                 "query": {
@@ -706,7 +708,7 @@
                 }
             }
         },
-        "model.SimpleEdge": {
+        "knowledge-graph-backend_internal_model.SimpleEdge": {
             "type": "object",
             "properties": {
                 "label": {
@@ -727,24 +729,24 @@
                 }
             }
         },
-        "model.SimpleGraphData": {
+        "knowledge-graph-backend_internal_model.SimpleGraphData": {
             "type": "object",
             "properties": {
                 "edges": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.SimpleEdge"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleEdge"
                     }
                 },
                 "nodes": {
                     "type": "array",
                     "items": {
-                        "$ref": "#/definitions/model.SimpleNode"
+                        "$ref": "#/definitions/knowledge-graph-backend_internal_model.SimpleNode"
                     }
                 }
             }
         },
-        "model.SimpleNode": {
+        "knowledge-graph-backend_internal_model.SimpleNode": {
             "type": "object",
             "properties": {
                 "id": {
@@ -761,7 +763,7 @@
                 }
             }
         },
-        "model.UpdateNodeRequest": {
+        "knowledge-graph-backend_internal_model.UpdateNodeRequest": {
             "type": "object",
             "properties": {
                 "label": {

backend/docs/swagger.yaml

@@ -1,6 +1,6 @@
 basePath: /
 definitions:
-  model.CreateEdgeRequest:
+  knowledge-graph-backend_internal_model.CreateEdgeRequest:
     properties:
       id:
         example: edge_123
@@ -26,7 +26,7 @@ definitions:
     - source
     - target
     type: object
-  model.CreateNodeRequest:
+  knowledge-graph-backend_internal_model.CreateNodeRequest:
     properties:
       id:
         example: node_123
@@ -51,7 +51,7 @@ definitions:
     - label
     - type
     type: object
-  model.DeleteResponse:
+  knowledge-graph-backend_internal_model.DeleteResponse:
     properties:
       id:
         example: node_123
@@ -63,7 +63,7 @@ definitions:
         example: true
         type: boolean
     type: object
-  model.Edge:
+  knowledge-graph-backend_internal_model.Edge:
     properties:
       id:
         type: string
@@ -82,7 +82,7 @@ definitions:
       type:
         type: string
     type: object
-  model.EdgeResponse:
+  knowledge-graph-backend_internal_model.EdgeResponse:
     properties:
       id:
         example: edge_123
@@ -103,36 +103,38 @@ definitions:
         example: CONTAINS
         type: string
     type: object
-  model.ErrorResponse:
+  knowledge-graph-backend_internal_model.ErrorResponse:
     properties:
       error:
+        example: bad_request
         type: string
       message:
+        example: invalid request
         type: string
     type: object
-  model.GraphData:
+  knowledge-graph-backend_internal_model.GraphData:
     properties:
       edges:
         items:
-          $ref: '#/definitions/model.Edge'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Edge'
         type: array
       nodes:
         items:
-          $ref: '#/definitions/model.Node'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         type: array
     type: object
-  model.NeighborResponse:
+  knowledge-graph-backend_internal_model.NeighborResponse:
     properties:
       edges:
         items:
-          $ref: '#/definitions/model.Edge'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Edge'
         type: array
       nodes:
         items:
-          $ref: '#/definitions/model.Node'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         type: array
     type: object
-  model.Node:
+  knowledge-graph-backend_internal_model.Node:
     properties:
       id:
         type: string
@@ -151,7 +153,7 @@ definitions:
       "y":
         type: number
     type: object
-  model.NodeResponse:
+  knowledge-graph-backend_internal_model.NodeResponse:
     properties:
       id:
         type: string
@@ -159,7 +161,7 @@ definitions:
         type: string
       neighbors:
         items:
-          $ref: '#/definitions/model.Node'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         type: array
       properties:
         additionalProperties: true
@@ -174,18 +176,18 @@ definitions:
       "y":
         type: number
     type: object
-  model.SearchResponse:
+  knowledge-graph-backend_internal_model.SearchResponse:
     properties:
       count:
         type: integer
       nodes:
         items:
-          $ref: '#/definitions/model.Node'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         type: array
       query:
         type: string
     type: object
-  model.SimpleEdge:
+  knowledge-graph-backend_internal_model.SimpleEdge:
     properties:
       label:
         example: 包含
@@ -200,18 +202,18 @@ definitions:
         example: CONTAINS
         type: string
     type: object
-  model.SimpleGraphData:
+  knowledge-graph-backend_internal_model.SimpleGraphData:
     properties:
       edges:
         items:
-          $ref: '#/definitions/model.SimpleEdge'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleEdge'
         type: array
       nodes:
         items:
-          $ref: '#/definitions/model.SimpleNode'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleNode'
         type: array
     type: object
-  model.SimpleNode:
+  knowledge-graph-backend_internal_model.SimpleNode:
     properties:
       id:
         example: "1"
@@ -223,7 +225,7 @@ definitions:
         example: 概念
         type: string
     type: object
-  model.UpdateNodeRequest:
+  knowledge-graph-backend_internal_model.UpdateNodeRequest:
     properties:
       label:
         example: 机器学习
@@ -259,30 +261,30 @@ paths:
         name: request
         required: true
         schema:
-          $ref: '#/definitions/model.CreateEdgeRequest'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.CreateEdgeRequest'
       produces:
       - application/json
       responses:
         "200":
           description: 创建成功
           schema:
-            $ref: '#/definitions/model.EdgeResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.EdgeResponse'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "404":
           description: 源节点或目标节点未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "409":
           description: 边已存在
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 创建边
   /api/edges/{id}:
     delete:
@@ -299,15 +301,15 @@ paths:
         "200":
           description: 删除成功
           schema:
-            $ref: '#/definitions/model.DeleteResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.DeleteResponse'
         "404":
           description: 边未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 删除边
   /api/graph:
     get:
@@ -318,11 +320,11 @@ paths:
         "200":
           description: 成功
           schema:
-            $ref: '#/definitions/model.GraphData'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.GraphData'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 获取图数据
   /api/graph/simpleJson:
     get:
@@ -333,11 +335,11 @@ paths:
         "200":
           description: 成功
           schema:
-            $ref: '#/definitions/model.SimpleGraphData'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.SimpleGraphData'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 获取简化图数据
   /api/graph/stats:
     get:
@@ -353,7 +355,7 @@ paths:
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 获取图统计信息
   /api/nodes:
     post:
@@ -366,26 +368,26 @@ paths:
         name: request
         required: true
         schema:
-          $ref: '#/definitions/model.CreateNodeRequest'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.CreateNodeRequest'
       produces:
       - application/json
       responses:
         "200":
           description: 创建成功
           schema:
-            $ref: '#/definitions/model.Node'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "409":
           description: 节点已存在
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 创建节点
   /api/nodes/{id}:
     delete:
@@ -402,15 +404,15 @@ paths:
         "200":
           description: 删除成功
           schema:
-            $ref: '#/definitions/model.DeleteResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.DeleteResponse'
         "404":
           description: 节点未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 删除节点
     get:
       description: 根据节点 ID 获取知识图谱中的节点详细信息
@@ -426,19 +428,19 @@ paths:
         "200":
           description: 成功
           schema:
-            $ref: '#/definitions/model.NodeResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.NodeResponse'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "404":
           description: 节点未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 获取节点详情
     put:
       consumes:
@@ -455,26 +457,26 @@ paths:
         name: request
         required: true
         schema:
-          $ref: '#/definitions/model.UpdateNodeRequest'
+          $ref: '#/definitions/knowledge-graph-backend_internal_model.UpdateNodeRequest'
       produces:
       - application/json
       responses:
         "200":
           description: 更新成功
           schema:
-            $ref: '#/definitions/model.Node'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.Node'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "404":
           description: 节点未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 更新节点
   /api/nodes/{id}/neighbors:
     get:
@@ -491,19 +493,19 @@ paths:
         "200":
           description: 成功
           schema:
-            $ref: '#/definitions/model.NeighborResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.NeighborResponse'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "404":
           description: 节点未找到
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 获取节点邻居
   /api/search:
     get:
@@ -520,14 +522,14 @@ paths:
         "200":
           description: 成功
           schema:
-            $ref: '#/definitions/model.SearchResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.SearchResponse'
         "400":
           description: 请求错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
         "500":
           description: 内部错误
           schema:
-            $ref: '#/definitions/model.ErrorResponse'
+            $ref: '#/definitions/knowledge-graph-backend_internal_model.ErrorResponse'
       summary: 搜索节点
 swagger: "2.0"

backend/internal/handler/crud_handler.go

@@ -46,23 +46,17 @@ func NewEdgeCRUDHandler(svc service.GraphService) *EdgeCRUDHandler {
 func (h *NodeCRUDHandler) CreateNode(c *gin.Context) {
 	var req model.CreateNodeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, model.ErrorResponse{
-			Error:   "invalid_request",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "invalid_request", Message: err.Error()})
 		return
 	}
 
 	node, err := h.service.CreateNode(req)
 	if err != nil {
-		c.JSON(http.StatusConflict, model.ErrorResponse{
-			Error:   "create_failed",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusConflict, model.ErrorResponse{Error: "create_failed", Message: err.Error()})
 		return
 	}
 
-	c.JSON(http.StatusOK, node)
+	c.JSON(http.StatusCreated, node)
 }
 
 // UpdateNode 更新节点
@@ -82,19 +76,13 @@ func (h *NodeCRUDHandler) UpdateNode(c *gin.Context) {
 
 	var req model.UpdateNodeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, model.ErrorResponse{
-			Error:   "invalid_request",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "invalid_request", Message: err.Error()})
 		return
 	}
 
 	node, err := h.service.UpdateNode(id, req)
 	if err != nil {
-		c.JSON(http.StatusNotFound, model.ErrorResponse{
-			Error:   "update_failed",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusNotFound, model.ErrorResponse{Error: "update_failed", Message: err.Error()})
 		return
 	}
 
@@ -113,20 +101,12 @@ func (h *NodeCRUDHandler) UpdateNode(c *gin.Context) {
 func (h *NodeCRUDHandler) DeleteNode(c *gin.Context) {
 	id := c.Param("id")
 
-	err := h.service.DeleteNode(id)
-	if err != nil {
-		c.JSON(http.StatusNotFound, model.ErrorResponse{
-			Error:   "delete_failed",
-			Message: err.Error(),
-		})
+	if err := h.service.DeleteNode(id); err != nil {
+		c.JSON(http.StatusNotFound, model.ErrorResponse{Error: "delete_failed", Message: err.Error()})
 		return
 	}
 
-	c.JSON(http.StatusOK, model.DeleteResponse{
-		Success: true,
-		Message: "节点已成功删除",
-		ID:      id,
-	})
+	c.JSON(http.StatusOK, model.DeleteResponse{Success: true, Message: "节点已成功删除", ID: id})
 }
 
 // CreateEdge 创建新边
@@ -144,33 +124,17 @@ func (h *NodeCRUDHandler) DeleteNode(c *gin.Context) {
 func (h *EdgeCRUDHandler) CreateEdge(c *gin.Context) {
 	var req model.CreateEdgeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, model.ErrorResponse{
-			Error:   "invalid_request",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "invalid_request", Message: err.Error()})
 		return
 	}
 
 	edge, err := h.service.CreateEdge(req)
 	if err != nil {
-		c.JSON(http.StatusConflict, model.ErrorResponse{
-			Error:   "create_failed",
-			Message: err.Error(),
-		})
+		c.JSON(http.StatusConflict, model.ErrorResponse{Error: "create_failed", Message: err.Error()})
 		return
 	}
 
-	// 转换为响应格式
-	response := model.EdgeResponse{
-		ID:         edge.ID,
-		Source:     edge.Source,
-		Target:     edge.Target,
-		Label:      edge.Label,
-		Type:       edge.Type,
-		Properties: edge.Properties,
-	}
-
-	c.JSON(http.StatusOK, response)
+	c.JSON(http.StatusCreated, model.EdgeResponse{ID: edge.ID, Source: edge.Source, Target: edge.Target, Label: edge.Label, Type: edge.Type, Properties: edge.Properties})
 }
 
 // DeleteEdge 删除边
@@ -185,18 +149,10 @@ func (h *EdgeCRUDHandler) CreateEdge(c *gin.Context) {
 func (h *EdgeCRUDHandler) DeleteEdge(c *gin.Context) {
 	edgeID := c.Param("id")
 
-	err := h.service.DeleteEdge(edgeID)
-	if err != nil {
-		c.JSON(http.StatusNotFound, model.ErrorResponse{
-			Error:   "delete_failed",
-			Message: err.Error(),
-		})
+	if err := h.service.DeleteEdge(edgeID); err != nil {
+		c.JSON(http.StatusNotFound, model.ErrorResponse{Error: "delete_failed", Message: err.Error()})
 		return
 	}
 
-	c.JSON(http.StatusOK, model.DeleteResponse{
-		Success: true,
-		Message: "边已成功删除",
-		ID:      edgeID,
-	})
+	c.JSON(http.StatusOK, model.DeleteResponse{Success: true, Message: "边已成功删除", ID: edgeID})
 }

backend/internal/handler/node_handler.go

@@ -4,6 +4,7 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+	"knowledge-graph-backend/internal/model"
 	"knowledge-graph-backend/internal/service"
 )
 
@@ -29,19 +30,13 @@ func NewNodeHandler(svc service.GraphService) *NodeHandler {
 func (h *NodeHandler) GetNodeByID(c *gin.Context) {
 	nodeID := c.Param("id")
 	if nodeID == "" {
-		c.JSON(http.StatusBadRequest, gin.H{
-			"error":   "Bad Request",
-			"message": "Node ID is required",
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "bad_request", Message: "Node ID is required"})
 		return
 	}
 
 	node, found := h.service.GetNodeByID(nodeID)
 	if !found {
-		c.JSON(http.StatusNotFound, gin.H{
-			"error":   "Not Found",
-			"message": "Node with ID '" + nodeID + "' not found",
-		})
+		c.JSON(http.StatusNotFound, model.ErrorResponse{Error: "not_found", Message: "Node with ID '" + nodeID + "' not found"})
 		return
 	}
 
@@ -60,19 +55,13 @@ func (h *NodeHandler) GetNodeByID(c *gin.Context) {
 func (h *NodeHandler) GetNeighbors(c *gin.Context) {
 	nodeID := c.Param("id")
 	if nodeID == "" {
-		c.JSON(http.StatusBadRequest, gin.H{
-			"error":   "Bad Request",
-			"message": "Node ID is required",
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "bad_request", Message: "Node ID is required"})
 		return
 	}
 
 	neighbors, found := h.service.GetNeighbors(nodeID)
 	if !found {
-		c.JSON(http.StatusNotFound, gin.H{
-			"error":   "Not Found",
-			"message": "Node with ID '" + nodeID + "' not found",
-		})
+		c.JSON(http.StatusNotFound, model.ErrorResponse{Error: "not_found", Message: "Node with ID '" + nodeID + "' not found"})
 		return
 	}
 

backend/internal/handler/search_handler.go

@@ -4,6 +4,7 @@ import (
 	"net/http"
 
 	"github.com/gin-gonic/gin"
+	"knowledge-graph-backend/internal/model"
 	"knowledge-graph-backend/internal/service"
 )
 
@@ -28,10 +29,7 @@ func NewSearchHandler(svc service.GraphService) *SearchHandler {
 func (h *SearchHandler) SearchNodes(c *gin.Context) {
 	query := c.Query("q")
 	if query == "" {
-		c.JSON(http.StatusBadRequest, gin.H{
-			"error":   "Bad Request",
-			"message": "Query parameter 'q' is required",
-		})
+		c.JSON(http.StatusBadRequest, model.ErrorResponse{Error: "bad_request", Message: "Query parameter 'q' is required"})
 		return
 	}
 

backend/internal/model/graph.go

@@ -83,8 +83,3 @@ type SearchResponse struct {
 	Nodes []Node `json:"nodes"`
 }
 
-// ErrorResponse represents an error response
-type ErrorResponse struct {
-	Error   string `json:"error"`
-	Message string `json:"message"`
-}

backend/internal/model/response.go

@@ -1,5 +1,11 @@
 package model
 
+// ErrorResponse represents a standardized API error response.
+type ErrorResponse struct {
+	Error   string `json:"error" example:"bad_request"`
+	Message string `json:"message" example:"invalid request"`
+}
+
 // CreateNodeRequest creates a new node
 type CreateNodeRequest struct {
 	ID         string                 `json:"id" binding:"required" example:"node_123"`

backend/internal/service/graph_crud.go

@@ -0,0 +1,195 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+
+	"knowledge-graph-backend/internal/model"
+)
+
+// CreateNode 创建新节点
+func (s *Neo4jService) CreateNode(req model.CreateNodeRequest) (model.Node, error) {
+	ctx := context.Background()
+
+	if req.ID == "" {
+		return model.Node{}, fmt.Errorf("node id is required")
+	}
+	if req.Label == "" {
+		return model.Node{}, fmt.Errorf("node label is required")
+	}
+
+	if _, found, err := s.fetchNodeByID(req.ID); err != nil {
+		return model.Node{}, err
+	} else if found {
+		return model.Node{}, fmt.Errorf("node with id %s already exists", req.ID)
+	}
+
+	props := buildNodeProps(req)
+	nodeType := sanitizeLabel(req.Type)
+	if nodeType == "" {
+		nodeType = "Node"
+	}
+
+	query := fmt.Sprintf(`
+		CREATE (n:%s)
+		SET n = $props
+		RETURN n`, nodeType)
+
+	result, err := neo4j.ExecuteQuery(ctx, s.driver, query, map[string]any{"props": props}, neo4j.EagerResultTransformer)
+	if err != nil {
+		return model.Node{}, fmt.Errorf("failed to create node: %w", err)
+	}
+	if len(result.Records) == 0 {
+		return model.Node{}, fmt.Errorf("failed to create node: no result returned")
+	}
+
+	v, _ := result.Records[0].Get("n")
+	if n, ok := v.(neo4j.Node); ok {
+		return neo4jNodeToModel(n), nil
+	}
+	return model.Node{}, fmt.Errorf("unexpected result type while creating node")
+}
+
+// UpdateNode 更新节点
+func (s *Neo4jService) UpdateNode(id string, req model.UpdateNodeRequest) (model.Node, error) {
+	ctx := context.Background()
+
+	if _, found, err := s.fetchNodeByID(id); err != nil {
+		return model.Node{}, err
+	} else if !found {
+		return model.Node{}, fmt.Errorf("node with id %s not found", id)
+	}
+
+	setClauses := []string{}
+	params := map[string]any{"id": id}
+
+	if req.Label != "" {
+		setClauses = append(setClauses, "n.label = $label")
+		params["label"] = req.Label
+	}
+	if req.Type != "" {
+		setClauses = append(setClauses, "n.type = $type")
+		params["type"] = req.Type
+	}
+	if req.X != nil {
+		setClauses = append(setClauses, "n.x = $x")
+		params["x"] = *req.X
+	}
+	if req.Y != nil {
+		setClauses = append(setClauses, "n.y = $y")
+		params["y"] = *req.Y
+	}
+
+	for key, value := range req.Properties {
+		if isReservedNodeProperty(key) {
+			continue
+		}
+		safeKey := sanitizeLabel(key)
+		setClauses = append(setClauses, fmt.Sprintf("n.%s = $%s", safeKey, safeKey))
+		params[safeKey] = value
+	}
+
+	query := `MATCH (n {id: $id})`
+	if len(setClauses) > 0 {
+		query += ` SET ` + strings.Join(setClauses, ", ")
+	}
+	query += ` RETURN n`
+
+	result, err := neo4j.ExecuteQuery(ctx, s.driver, query, params, neo4j.EagerResultTransformer)
+	if err != nil {
+		return model.Node{}, err
+	}
+	if len(result.Records) == 0 {
+		return model.Node{}, fmt.Errorf("failed to update node")
+	}
+
+	v, _ := result.Records[0].Get("n")
+	if n, ok := v.(neo4j.Node); ok {
+		return neo4jNodeToModel(n), nil
+	}
+	return model.Node{}, fmt.Errorf("unexpected result type while updating node")
+}
+
+// DeleteNode 删除节点
+func (s *Neo4jService) DeleteNode(id string) error {
+	ctx := context.Background()
+
+	if _, found, err := s.fetchNodeByID(id); err != nil {
+		return err
+	} else if !found {
+		return fmt.Errorf("node with id %s not found", id)
+	}
+
+	_, err := neo4j.ExecuteQuery(ctx, s.driver, `
+		MATCH (n {id: $id})
+		DETACH DELETE n`, map[string]any{"id": id}, neo4j.EagerResultTransformer)
+	return err
+}
+
+// CreateEdge 创建新边
+func (s *Neo4jService) CreateEdge(req model.CreateEdgeRequest) (model.Edge, error) {
+	ctx := context.Background()
+
+	if req.Source == "" || req.Target == "" {
+		return model.Edge{}, fmt.Errorf("source and target are required")
+	}
+	if _, found, err := s.fetchNodeByID(req.Source); err != nil {
+		return model.Edge{}, err
+	} else if !found {
+		return model.Edge{}, fmt.Errorf("source node with id %s not found", req.Source)
+	}
+	if _, found, err := s.fetchNodeByID(req.Target); err != nil {
+		return model.Edge{}, err
+	} else if !found {
+		return model.Edge{}, fmt.Errorf("target node with id %s not found", req.Target)
+	}
+
+	props := buildEdgeProps(req)
+	relationType := sanitizeRelationshipType(req.Type)
+	if relationType == "" {
+		relationType = "RELATED_TO"
+	}
+
+	query := fmt.Sprintf(`
+		MATCH (a {id: $source}), (b {id: $target})
+		CREATE (a)-[r:%s]->(b)
+		SET r = $props
+		RETURN r`, relationType)
+
+	params := map[string]any{
+		"source": req.Source,
+		"target": req.Target,
+		"props":  props,
+	}
+
+	result, err := neo4j.ExecuteQuery(ctx, s.driver, query, params, neo4j.EagerResultTransformer)
+	if err != nil {
+		return model.Edge{}, err
+	}
+	if len(result.Records) == 0 {
+		return model.Edge{}, fmt.Errorf("failed to create edge")
+	}
+
+	v, _ := result.Records[0].Get("r")
+	if r, ok := v.(neo4j.Relationship); ok {
+		edge := neo4jRelToModel(r)
+		edge.Source = req.Source
+		edge.Target = req.Target
+		return edge, nil
+	}
+	return model.Edge{}, fmt.Errorf("unexpected result type while creating edge")
+}
+
+// DeleteEdge 删除边
+func (s *Neo4jService) DeleteEdge(edgeID string) error {
+	ctx := context.Background()
+
+	_, err := neo4j.ExecuteQuery(ctx, s.driver, `
+		MATCH ()-[r]-()
+		WHERE r.id = $id
+		DELETE r`, map[string]any{"id": edgeID}, neo4j.EagerResultTransformer)
+	return err
+}

backend/internal/service/graph_queries.go

@@ -0,0 +1,194 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+
+	"knowledge-graph-backend/internal/model"
+)
+
+func (s *Neo4jService) GetGraphData() model.GraphData {
+	ctx := context.Background()
+	var nodes []model.Node
+	var edges []model.Edge
+
+	nodeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
+		"MATCH (n) RETURN n",
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		fmt.Printf("Error querying nodes: %v\n", err)
+		return model.GraphData{}
+	}
+	for _, record := range nodeResult.Records {
+		if v, ok := record.Get("n"); ok {
+			if n, ok := v.(neo4j.Node); ok {
+				nodes = append(nodes, neo4jNodeToModel(n))
+			}
+		}
+	}
+
+	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
+		"MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r",
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		fmt.Printf("Error querying edges: %v\n", err)
+		return model.GraphData{Nodes: nodes}
+	}
+	for _, record := range edgeResult.Records {
+		source, _ := record.Get("source")
+		target, _ := record.Get("target")
+		v, _ := record.Get("r")
+		if rel, ok := v.(neo4j.Relationship); ok {
+			edge := neo4jRelToModel(rel)
+			if s, ok := source.(string); ok {
+				edge.Source = s
+			}
+			if t, ok := target.(string); ok {
+				edge.Target = t
+			}
+			edges = append(edges, edge)
+		}
+	}
+
+	return model.GraphData{Nodes: nodes, Edges: edges}
+}
+
+func (s *Neo4jService) GetNodeByID(id string) (model.Node, bool) {
+	node, found, err := s.fetchNodeByID(id)
+	if err != nil || !found {
+		return model.Node{}, false
+	}
+	return node, true
+}
+
+func (s *Neo4jService) SearchNodes(query string) []model.Node {
+	if query == "" {
+		return []model.Node{}
+	}
+	ctx := context.Background()
+	result, err := neo4j.ExecuteQuery(ctx, s.driver,
+		`MATCH (n)
+		 WHERE toLower(n.label) CONTAINS toLower($query)
+		    OR toLower(n.id) CONTAINS toLower($query)
+		    OR (n.type IS NOT NULL AND toLower(n.type) CONTAINS toLower($query))
+		 RETURN n`,
+		map[string]any{"query": query},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		return []model.Node{}
+	}
+	var nodes []model.Node
+	for _, record := range result.Records {
+		v, _ := record.Get("n")
+		if n, ok := v.(neo4j.Node); ok {
+			nodes = append(nodes, neo4jNodeToModel(n))
+		}
+	}
+	return nodes
+}
+
+func (s *Neo4jService) GetNeighbors(nodeID string) (model.NeighborResponse, bool) {
+	ctx := context.Background()
+
+	if _, exists := s.GetNodeByID(nodeID); !exists {
+		return model.NeighborResponse{}, false
+	}
+
+	result, err := neo4j.ExecuteQuery(ctx, s.driver,
+		`MATCH ({id: $id})-[r]-(m)
+		 RETURN m, r, startNode(r).id AS source, endNode(r).id AS target`,
+		map[string]any{"id": nodeID},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		return model.NeighborResponse{Nodes: []model.Node{}, Edges: []model.Edge{}}, true
+	}
+
+	neighborMap := make(map[string]model.Node)
+	edgeMap := make(map[string]model.Edge)
+
+	for _, record := range result.Records {
+		if v, ok := record.Get("m"); ok {
+			if n, ok := v.(neo4j.Node); ok {
+				modelNode := neo4jNodeToModel(n)
+				neighborMap[modelNode.ID] = modelNode
+			}
+		}
+
+		if v, ok := record.Get("r"); ok {
+			if rel, ok := v.(neo4j.Relationship); ok {
+				edge := neo4jRelToModel(rel)
+				if source, ok := record.Get("source"); ok {
+					if s, ok := source.(string); ok {
+						edge.Source = s
+					}
+				}
+				if target, ok := record.Get("target"); ok {
+					if t, ok := target.(string); ok {
+						edge.Target = t
+					}
+				}
+				edgeMap[edge.ID] = edge
+			}
+		}
+	}
+
+	var neighborNodes []model.Node
+	for _, n := range neighborMap {
+		neighborNodes = append(neighborNodes, n)
+	}
+
+	var relatedEdges []model.Edge
+	for _, e := range edgeMap {
+		relatedEdges = append(relatedEdges, e)
+	}
+
+	return model.NeighborResponse{Nodes: neighborNodes, Edges: relatedEdges}, true
+}
+
+func (s *Neo4jService) GetStats() map[string]int {
+	ctx := context.Background()
+	result, err := neo4j.ExecuteQuery(ctx, s.driver,
+		`MATCH (n)
+		 RETURN count(n) AS totalNodes,
+		        sum(CASE WHEN n.type = '概念' THEN 1 ELSE 0 END) AS conceptNodes,
+		        sum(CASE WHEN n.type = '工具' THEN 1 ELSE 0 END) AS toolNodes,
+		        sum(CASE WHEN n.type = '应用' THEN 1 ELSE 0 END) AS applicationNodes`,
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil || len(result.Records) == 0 {
+		return map[string]int{}
+	}
+
+	record := result.Records[0]
+	totalNodes := getInt(record, "totalNodes")
+	conceptNodes := getInt(record, "conceptNodes")
+	toolNodes := getInt(record, "toolNodes")
+	applicationNodes := getInt(record, "applicationNodes")
+
+	totalEdges := 0
+	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
+		"MATCH ()-[r]->() RETURN count(r) AS totalEdges",
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err == nil && len(edgeResult.Records) > 0 {
+		totalEdges = getInt(edgeResult.Records[0], "totalEdges")
+	}
+
+	return map[string]int{
+		"totalNodes":       totalNodes,
+		"totalEdges":       totalEdges,
+		"conceptNodes":     conceptNodes,
+		"toolNodes":        toolNodes,
+		"applicationNodes": applicationNodes,
+	}
+}

backend/internal/service/graph_simple.go

@@ -0,0 +1,64 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+
+	"knowledge-graph-backend/internal/model"
+)
+
+// GetSimpleGraphData 获取简化的图数据，仅保留核心信息，适合 LLM 处理
+func (s *Neo4jService) GetSimpleGraphData() model.SimpleGraphData {
+	ctx := context.Background()
+	var nodes []model.SimpleNode
+	var edges []model.SimpleEdge
+
+	nodeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
+		"MATCH (n) RETURN n",
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		fmt.Printf("Error querying nodes: %v\n", err)
+		return model.SimpleGraphData{}
+	}
+	for _, record := range nodeResult.Records {
+		if v, ok := record.Get("n"); ok {
+			if n, ok := v.(neo4j.Node); ok {
+				props := n.Props
+				node := model.SimpleNode{ID: getStr(props, "id"), Label: getStr(props, "label"), Type: getStr(props, "type")}
+				nodes = append(nodes, node)
+			}
+		}
+	}
+
+	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
+		"MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r",
+		map[string]any{},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		fmt.Printf("Error querying edges: %v\n", err)
+		return model.SimpleGraphData{Nodes: nodes}
+	}
+	for _, record := range edgeResult.Records {
+		source, _ := record.Get("source")
+		target, _ := record.Get("target")
+		v, _ := record.Get("r")
+		if rel, ok := v.(neo4j.Relationship); ok {
+			props := rel.Props
+			edge := model.SimpleEdge{Source: getStr(props, "source"), Target: getStr(props, "target"), Type: rel.Type, Label: getStr(props, "label")}
+			if s, ok := source.(string); ok {
+				edge.Source = s
+			}
+			if t, ok := target.(string); ok {
+				edge.Target = t
+			}
+			edges = append(edges, edge)
+		}
+	}
+
+	return model.SimpleGraphData{Nodes: nodes, Edges: edges}
+}

backend/internal/service/interface.go

@@ -10,7 +10,6 @@ type GraphService interface {
 	GetNeighbors(nodeID string) (model.NeighborResponse, bool)
 	GetStats() map[string]int
 
-	// 新增增删改接口
 	CreateNode(req model.CreateNodeRequest) (model.Node, error)
 	UpdateNode(id string, req model.UpdateNodeRequest) (model.Node, error)
 	DeleteNode(id string) error

backend/internal/service/neo4j_fetch.go

@@ -0,0 +1,31 @@
+package service
+
+import (
+	"context"
+
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+
+	"knowledge-graph-backend/internal/model"
+)
+
+func (s *Neo4jService) fetchNodeByID(id string) (model.Node, bool, error) {
+	ctx := context.Background()
+	result, err := neo4j.ExecuteQuery(ctx, s.driver,
+		`MATCH (n {id: $id}) RETURN n LIMIT 1`,
+		map[string]any{"id": id},
+		neo4j.EagerResultTransformer,
+	)
+	if err != nil {
+		return model.Node{}, false, err
+	}
+	if len(result.Records) == 0 {
+		return model.Node{}, false, nil
+	}
+
+	v, _ := result.Records[0].Get("n")
+	n, ok := v.(neo4j.Node)
+	if !ok {
+		return model.Node{}, false, nil
+	}
+	return neo4jNodeToModel(n), true, nil
+}

backend/internal/service/neo4j_service.go

@@ -1,716 +1,13 @@
 package service
 
-import (
-	"context"
-	"fmt"
-	"strings"
-
-	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
-
-	"knowledge-graph-backend/internal/model"
-)
+import "github.com/neo4j/neo4j-go-driver/v5/neo4j"
 
+// Neo4jService provides graph operations backed by Neo4j.
 type Neo4jService struct {
 	driver neo4j.DriverWithContext
 }
 
+// NewNeo4jService creates a new Neo4j-backed graph service.
 func NewNeo4jService(driver neo4j.DriverWithContext) *Neo4jService {
 	return &Neo4jService{driver: driver}
 }
-
-func (s *Neo4jService) GetGraphData() model.GraphData {
-	ctx := context.Background()
-	var nodes []model.Node
-	var edges []model.Edge
-
-	nodeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH (n) RETURN n",
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		fmt.Printf("Error querying nodes: %v\n", err)
-		return model.GraphData{}
-	}
-	for _, record := range nodeResult.Records {
-		if v, ok := record.Get("n"); ok {
-			if n, ok := v.(neo4j.Node); ok {
-				nodes = append(nodes, neo4jNodeToModel(n))
-			}
-		}
-	}
-
-	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r",
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		fmt.Printf("Error querying edges: %v\n", err)
-		return model.GraphData{Nodes: nodes}
-	}
-	for _, record := range edgeResult.Records {
-		source, _ := record.Get("source")
-		target, _ := record.Get("target")
-		v, _ := record.Get("r")
-		if rel, ok := v.(neo4j.Relationship); ok {
-			edge := neo4jRelToModel(rel)
-			if s, ok := source.(string); ok {
-				edge.Source = s
-			}
-			if t, ok := target.(string); ok {
-				edge.Target = t
-			}
-			edges = append(edges, edge)
-		}
-	}
-
-	return model.GraphData{Nodes: nodes, Edges: edges}
-}
-
-func (s *Neo4jService) GetNodeByID(id string) (model.Node, bool) {
-	ctx := context.Background()
-	result, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH (n {id: $id}) RETURN n",
-		map[string]any{"id": id},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil || len(result.Records) == 0 {
-		return model.Node{}, false
-	}
-	v, _ := result.Records[0].Get("n")
-	if n, ok := v.(neo4j.Node); ok {
-		return neo4jNodeToModel(n), true
-	}
-	return model.Node{}, false
-}
-
-func (s *Neo4jService) SearchNodes(query string) []model.Node {
-	if query == "" {
-		return []model.Node{}
-	}
-	ctx := context.Background()
-	result, err := neo4j.ExecuteQuery(ctx, s.driver,
-		`MATCH (n)
-		 WHERE toLower(n.label) CONTAINS toLower($query)
-		    OR toLower(n.id) CONTAINS toLower($query)
-		    OR (n.type IS NOT NULL AND toLower(n.type) CONTAINS toLower($query))
-		 RETURN n`,
-		map[string]any{"query": query},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		return []model.Node{}
-	}
-	var nodes []model.Node
-	for _, record := range result.Records {
-		v, _ := record.Get("n")
-		if n, ok := v.(neo4j.Node); ok {
-			nodes = append(nodes, neo4jNodeToModel(n))
-		}
-	}
-	return nodes
-}
-
-func (s *Neo4jService) GetNeighbors(nodeID string) (model.NeighborResponse, bool) {
-	ctx := context.Background()
-
-	_, exists := s.GetNodeByID(nodeID)
-	if !exists {
-		return model.NeighborResponse{}, false
-	}
-
-	result, err := neo4j.ExecuteQuery(ctx, s.driver,
-		`MATCH ({id: $id})-[r]-(m)
-		 RETURN m, r, startNode(r).id AS source, endNode(r).id AS target`,
-		map[string]any{"id": nodeID},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		return model.NeighborResponse{Nodes: []model.Node{}, Edges: []model.Edge{}}, true
-	}
-
-	neighborMap := make(map[string]model.Node)
-	edgeMap := make(map[string]model.Edge)
-
-	for _, record := range result.Records {
-		if v, ok := record.Get("m"); ok {
-			if n, ok := v.(neo4j.Node); ok {
-				modelNode := neo4jNodeToModel(n)
-				neighborMap[modelNode.ID] = modelNode
-			}
-		}
-
-		if v, ok := record.Get("r"); ok {
-			if rel, ok := v.(neo4j.Relationship); ok {
-				edge := neo4jRelToModel(rel)
-				if source, ok := record.Get("source"); ok {
-					if s, ok := source.(string); ok {
-						edge.Source = s
-					}
-				}
-				if target, ok := record.Get("target"); ok {
-					if t, ok := target.(string); ok {
-						edge.Target = t
-					}
-				}
-				edgeMap[edge.ID] = edge
-			}
-		}
-	}
-
-	var neighborNodes []model.Node
-	for _, n := range neighborMap {
-		neighborNodes = append(neighborNodes, n)
-	}
-
-	var relatedEdges []model.Edge
-	for _, e := range edgeMap {
-		relatedEdges = append(relatedEdges, e)
-	}
-
-	return model.NeighborResponse{
-		Nodes: neighborNodes,
-		Edges: relatedEdges,
-	}, true
-}
-
-func (s *Neo4jService) GetStats() map[string]int {
-	ctx := context.Background()
-	result, err := neo4j.ExecuteQuery(ctx, s.driver,
-		`MATCH (n)
-		 RETURN count(n) AS totalNodes,
-		        sum(CASE WHEN n.type = '概念' THEN 1 ELSE 0 END) AS conceptNodes,
-		        sum(CASE WHEN n.type = '工具' THEN 1 ELSE 0 END) AS toolNodes,
-		        sum(CASE WHEN n.type = '应用' THEN 1 ELSE 0 END) AS applicationNodes`,
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil || len(result.Records) == 0 {
-		return map[string]int{}
-	}
-
-	record := result.Records[0]
-	totalNodes := getInt(record, "totalNodes")
-	conceptNodes := getInt(record, "conceptNodes")
-	toolNodes := getInt(record, "toolNodes")
-	applicationNodes := getInt(record, "applicationNodes")
-
-	totalEdges := 0
-	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH ()-[r]->() RETURN count(r) AS totalEdges",
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err == nil && len(edgeResult.Records) > 0 {
-		totalEdges = getInt(edgeResult.Records[0], "totalEdges")
-	}
-
-	return map[string]int{
-		"totalNodes":       totalNodes,
-		"totalEdges":       totalEdges,
-		"conceptNodes":     conceptNodes,
-		"toolNodes":        toolNodes,
-		"applicationNodes": applicationNodes,
-	}
-}
-
-// GetSimpleGraphData 获取简化的图数据，仅保留核心信息，适合 LLM 处理
-func (s *Neo4jService) GetSimpleGraphData() model.SimpleGraphData {
-	ctx := context.Background()
-	var nodes []model.SimpleNode
-	var edges []model.SimpleEdge
-
-	nodeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH (n) RETURN n",
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		fmt.Printf("Error querying nodes: %v\n", err)
-		return model.SimpleGraphData{}
-	}
-	for _, record := range nodeResult.Records {
-		if v, ok := record.Get("n"); ok {
-			if n, ok := v.(neo4j.Node); ok {
-				props := n.Props
-				node := model.SimpleNode{
-					ID:    getStr(props, "id"),
-					Label: getStr(props, "label"),
-					Type:  getStr(props, "type"),
-				}
-				nodes = append(nodes, node)
-			}
-		}
-	}
-
-	edgeResult, err := neo4j.ExecuteQuery(ctx, s.driver,
-		"MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r",
-		map[string]any{},
-		neo4j.EagerResultTransformer,
-	)
-	if err != nil {
-		fmt.Printf("Error querying edges: %v\n", err)
-		return model.SimpleGraphData{Nodes: nodes}
-	}
-	for _, record := range edgeResult.Records {
-		source, _ := record.Get("source")
-		target, _ := record.Get("target")
-		v, _ := record.Get("r")
-		if rel, ok := v.(neo4j.Relationship); ok {
-			props := rel.Props
-			edge := model.SimpleEdge{
-				Source: getStr(props, "source"),
-				Target: getStr(props, "target"),
-				Type:   rel.Type,
-				Label:  getStr(props, "label"),
-			}
-			if s, ok := source.(string); ok {
-				edge.Source = s
-			}
-			if t, ok := target.(string); ok {
-				edge.Target = t
-			}
-			edges = append(edges, edge)
-		}
-	}
-
-	return model.SimpleGraphData{Nodes: nodes, Edges: edges}
-}
-
-func neo4jNodeToModel(n neo4j.Node) model.Node {
-	props := n.Props
-	node := model.Node{
-		ID:         getStr(props, "id"),
-		Label:      getStr(props, "label"),
-		Type:       getStr(props, "type"),
-		Properties: make(map[string]interface{}),
-	}
-	if v, ok := props["x"]; ok && v != nil {
-		node.X = getFloat64(v)
-	}
-	if v, ok := props["y"]; ok && v != nil {
-		node.Y = getFloat64(v)
-	}
-	if v, ok := props["style"]; ok && v != nil {
-		if s, ok := v.(map[string]interface{}); ok {
-			node.Style = s
-		}
-	}
-	for k, v := range props {
-		switch k {
-		case "id", "label", "type", "x", "y", "style":
-		default:
-			node.Properties[k] = v
-		}
-	}
-	return node
-}
-
-func neo4jRelToModel(r neo4j.Relationship) model.Edge {
-	props := r.Props
-	edge := model.Edge{
-		ID:         getStr(props, "id"),
-		Label:      getStr(props, "label"),
-		Type:       r.Type,
-		Properties: make(map[string]interface{}),
-	}
-	if v, ok := props["style"]; ok && v != nil {
-		if s, ok := v.(map[string]interface{}); ok {
-			edge.Style = s
-		}
-	}
-	for k, v := range props {
-		switch k {
-		case "id", "label", "style":
-		default:
-			edge.Properties[k] = v
-		}
-	}
-	return edge
-}
-
-func getStr(props map[string]any, key string) string {
-	if v, ok := props[key]; ok && v != nil {
-		if s, ok := v.(string); ok {
-			return s
-		}
-	}
-	return ""
-}
-
-func getFloat64(v any) float64 {
-	switch val := v.(type) {
-	case float64:
-		return val
-	case int64:
-		return float64(val)
-	case int:
-		return float64(val)
-	}
-	return 0
-}
-
-func getInt(record *neo4j.Record, key string) int {
-	v, _ := record.Get(key)
-	switch val := v.(type) {
-	case int64:
-		return int(val)
-	case int:
-		return val
-	case float64:
-		return int(val)
-	}
-	return 0
-}
-
-// CreateNode 创建新节点
-func (s *Neo4jService) CreateNode(req model.CreateNodeRequest) (model.Node, error) {
-	ctx := context.Background()
-
-	// 检查节点是否已存在
-	checkQuery := "MATCH (n {id: $id}) RETURN n"
-	checkResult, err := neo4j.ExecuteQuery(ctx, s.driver, checkQuery,
-		map[string]any{"id": req.ID}, neo4j.EagerResultTransformer)
-	if err != nil {
-		return model.Node{}, fmt.Errorf("error checking node existence: %w", err)
-	}
-	if len(checkResult.Records) > 0 {
-		return model.Node{}, fmt.Errorf("node with id %s already exists", req.ID)
-	}
-
-	// 构建创建属性
-	props := map[string]any{
-		"id":         req.ID,
-		"label":      req.Label,
-	}
-
-	if req.Type != "" {
-		props["type"] = req.Type
-	}
-	if req.X != 0 {
-		props["x"] = req.X
-	}
-	if req.Y != 0 {
-		props["y"] = req.Y
-	}
-
-	// 合并自定义属性（避免覆盖系统属性）
-	if req.Properties != nil {
-		for k, v := range req.Properties {
-			if k != "id" && k != "label" && k != "type" && k != "x" && k != "y" {
-				props[k] = v
-			}
-		}
-	}
-
-	// 执行创建
-	nodeType := "Node"
-	if req.Type != "" {
-		nodeType = req.Type
-	}
-
-	query := fmt.Sprintf(`
-		CREATE (n:%s)
-		SET n = $props
-		RETURN n`, nodeType)
-
-	result, err := neo4j.ExecuteQuery(ctx, s.driver, query,
-		map[string]any{"props": props}, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error creating node: %v\n", err)
-		return model.Node{}, fmt.Errorf("failed to create node: %w", err)
-	}
-
-	if len(result.Records) == 0 {
-		return model.Node{}, fmt.Errorf("failed to create node: no result returned")
-	}
-
-	v, _ := result.Records[0].Get("n")
-	if n, ok := v.(neo4j.Node); ok {
-		return neo4jNodeToModel(n), nil
-	}
-
-	return model.Node{}, fmt.Errorf("unexpected result type while creating node")
-}
-
-// CreateNodeV2 创建新节点（改进版）
-func (s *Neo4jService) CreateNodeV2(req model.CreateNodeRequest) (model.Node, error) {
-	ctx := context.Background()
-
-	// 先检查节点是否已存在
-	checkQuery := "MATCH (n {id: $id}) RETURN n"
-	checkResult, err := neo4j.ExecuteQuery(ctx, s.driver, checkQuery,
-		map[string]any{"id": req.ID}, neo4j.EagerResultTransformer)
-	if err != nil {
-		return model.Node{}, err
-	}
-	if len(checkResult.Records) > 0 {
-		return model.Node{}, fmt.Errorf("node with id %s already exists", req.ID)
-	}
-
-	// 构建创建属性
-	props := map[string]any{
-		"id":         req.ID,
-		"label":      req.Label,
-	}
-
-	if req.Type != "" {
-		props["type"] = req.Type
-	}
-	if req.X != 0 {
-		props["x"] = req.X
-	}
-	if req.Y != 0 {
-		props["y"] = req.Y
-	}
-
-	// 合并自定义属性（避免覆盖系统属性）
-	if req.Properties != nil {
-		for k, v := range req.Properties {
-			if k != "id" && k != "label" && k != "type" && k != "x" && k != "y" {
-				props[k] = v
-			}
-		}
-	}
-
-	// 执行创建
-	nodeType := "Node"
-	if req.Type != "" {
-		nodeType = req.Type
-	}
-
-	query := fmt.Sprintf(`
-		CREATE (n:%s)
-		SET n = $props
-		RETURN n`, nodeType)
-
-	result, err := neo4j.ExecuteQuery(ctx, s.driver, query,
-		map[string]any{"props": props}, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error creating node: %v\n", err)
-		return model.Node{}, err
-	}
-
-	if len(result.Records) == 0 {
-		return model.Node{}, fmt.Errorf("failed to create node")
-	}
-
-	v, _ := result.Records[0].Get("n")
-	if n, ok := v.(neo4j.Node); ok {
-		return neo4jNodeToModel(n), nil
-	}
-
-	return model.Node{}, fmt.Errorf("unexpected result type while creating node")
-}
-
-// UpdateNode 更新节点
-func (s *Neo4jService) UpdateNode(id string, req model.UpdateNodeRequest) (model.Node, error) {
-	ctx := context.Background()
-
-	// 检查节点是否存在
-	_, exists := s.GetNodeByID(id)
-	if !exists {
-		return model.Node{}, fmt.Errorf("node with id %s not found", id)
-	}
-
-	// 构建更新语句
-	setClauses := []string{}
-	params := map[string]any{"id": id}
-
-	if req.Label != "" {
-		setClauses = append(setClauses, "n.label = $label")
-		params["label"] = req.Label
-	}
-
-	if req.Type != "" {
-		setClauses = append(setClauses, "n.type = $type")
-		params["type"] = req.Type
-	}
-
-	if req.X != nil {
-		setClauses = append(setClauses, "n.x = $x")
-		params["x"] = *req.X
-	}
-	if req.Y != nil {
-		setClauses = append(setClauses, "n.y = $y")
-		params["y"] = *req.Y
-	}
-
-	query := `MATCH (n {id: $id})`
-
-	// 处理自定义属性（不管是否有标准字段更新）
-	if len(req.Properties) > 0 {
-		for key, value := range req.Properties {
-			// 跳过系统属性，避免冲突
-			if key != "id" && key != "label" && key != "type" && key != "x" && key != "y" {
-				setClauses = append(setClauses, fmt.Sprintf("n.%s = $%s", key, key))
-				params[key] = value
-			}
-		}
-	}
-
-	if len(setClauses) > 0 {
-		query += ` SET ` + fmt.Sprintf("%s", strings.Join(setClauses, ", "))
-	}
-	query += ` RETURN n`
-
-	result, err := neo4j.ExecuteQuery(ctx, s.driver, query, params, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error updating node: %v\n", err)
-		return model.Node{}, err
-	}
-
-	if len(result.Records) == 0 {
-		return model.Node{}, fmt.Errorf("failed to update node")
-	}
-
-	v, _ := result.Records[0].Get("n")
-	if n, ok := v.(neo4j.Node); ok {
-		return neo4jNodeToModel(n), nil
-	}
-
-	return model.Node{}, fmt.Errorf("unexpected result type while updating node")
-}
-
-// DeleteNode 删除节点
-func (s *Neo4jService) DeleteNode(id string) error {
-	ctx := context.Background()
-
-	// 检查节点是否存在
-	_, exists := s.GetNodeByID(id)
-	if !exists {
-		return fmt.Errorf("node with id %s not found", id)
-	}
-
-	// 先删除与该节点相关的所有关系
-	deleteRelationsQuery := `
-		MATCH (n {id: $id})-[r]-(m)
-		DELETE r`
-
-	_, err := neo4j.ExecuteQuery(ctx, s.driver, deleteRelationsQuery,
-		map[string]any{"id": id}, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error deleting relations: %v\n", err)
-		// 继续尝试删除节点
-	}
-
-	// 删除节点
-	deleteNodeQuery := `
-		MATCH (n {id: $id})
-		DELETE n`
-
-	_, err = neo4j.ExecuteQuery(ctx, s.driver, deleteNodeQuery,
-		map[string]any{"id": id}, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error deleting node: %v\n", err)
-		return err
-	}
-
-	return nil
-}
-
-// CreateEdge 创建新边
-func (s *Neo4jService) CreateEdge(req model.CreateEdgeRequest) (model.Edge, error) {
-	ctx := context.Background()
-
-	// 检查源节点和目标节点是否存在
-	_, sourceExists := s.GetNodeByID(req.Source)
-	if !sourceExists {
-		return model.Edge{}, fmt.Errorf("source node with id %s not found", req.Source)
-	}
-	_, targetExists := s.GetNodeByID(req.Target)
-	if !targetExists {
-		return model.Edge{}, fmt.Errorf("target node with id %s not found", req.Target)
-	}
-
-	// 构建创建属性
-
-	// 构建创建属性
-	props := map[string]any{
-		"id":         req.ID,
-		"label":      req.Label,
-	}
-
-	// 合并自定义属性
-	if req.Properties != nil {
-		for k, v := range req.Properties {
-			if k != "id" && k != "label" {
-				props[k] = v
-			}
-		}
-	}
-
-	// 确定边类型
-	relationType := "RELATED_TO"
-	if req.Type != "" {
-		relationType = strings.ToUpper(req.Type)
-	}
-
-	// 执行创建
-	query := fmt.Sprintf(`
-		MATCH (a {id: $source}), (b {id: $target})
-		CREATE (a)-[r:%s]->(b)
-		SET r = $props
-		RETURN r`, relationType)
-
-	params := map[string]any{
-		"source":      req.Source,
-		"target":      req.Target,
-		"props":       props,
-	}
-
-	result, err := neo4j.ExecuteQuery(ctx, s.driver, query, params, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error creating edge: %v\n", err)
-		return model.Edge{}, err
-	}
-
-	if len(result.Records) == 0 {
-		return model.Edge{}, fmt.Errorf("failed to create edge")
-	}
-
-	v, _ := result.Records[0].Get("r")
-	if r, ok := v.(neo4j.Relationship); ok {
-		edge := neo4jRelToModel(r)
-		edge.Source = req.Source
-		edge.Target = req.Target
-		return edge, nil
-	}
-
-	return model.Edge{}, fmt.Errorf("unexpected result type while creating edge")
-}
-
-// DeleteEdge 删除边
-func (s *Neo4jService) DeleteEdge(edgeID string) error {
-	ctx := context.Background()
-
-	// 检查边是否存在
-	checkQuery := `
-		MATCH ()-[r]-()
-		WHERE r.id = $id
-		RETURN r`
-	checkResult, err := neo4j.ExecuteQuery(ctx, s.driver, checkQuery,
-		map[string]any{"id": edgeID}, neo4j.EagerResultTransformer)
-	if err != nil {
-		return err
-	}
-	if len(checkResult.Records) == 0 {
-		return fmt.Errorf("edge with id %s not found", edgeID)
-	}
-
-	// 删除边
-	deleteQuery := `
-		MATCH ()-[r]-()
-		WHERE r.id = $id
-		DELETE r`
-
-	_, err = neo4j.ExecuteQuery(ctx, s.driver, deleteQuery,
-		map[string]any{"id": edgeID}, neo4j.EagerResultTransformer)
-	if err != nil {
-		fmt.Printf("Error deleting edge: %v\n", err)
-		return err
-	}
-
-	return nil
-}

backend/internal/service/neo4j_utils.go

@@ -0,0 +1,174 @@
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/neo4j/neo4j-go-driver/v5/neo4j"
+
+	"knowledge-graph-backend/internal/model"
+)
+
+func neo4jNodeToModel(n neo4j.Node) model.Node {
+	props := n.Props
+	node := model.Node{
+		ID:         getStr(props, "id"),
+		Label:      getStr(props, "label"),
+		Type:       getStr(props, "type"),
+		Properties: make(map[string]interface{}),
+	}
+	if v, ok := props["x"]; ok && v != nil {
+		node.X = getFloat64(v)
+	}
+	if v, ok := props["y"]; ok && v != nil {
+		node.Y = getFloat64(v)
+	}
+	if v, ok := props["style"]; ok && v != nil {
+		if s, ok := v.(map[string]interface{}); ok {
+			node.Style = s
+		}
+	}
+	for k, v := range props {
+		switch k {
+		case "id", "label", "type", "x", "y", "style":
+		default:
+			node.Properties[k] = v
+		}
+	}
+	return node
+}
+
+func neo4jRelToModel(r neo4j.Relationship) model.Edge {
+	props := r.Props
+	edge := model.Edge{
+		ID:         getStr(props, "id"),
+		Label:      getStr(props, "label"),
+		Type:       r.Type,
+		Properties: make(map[string]interface{}),
+	}
+	if v, ok := props["style"]; ok && v != nil {
+		if s, ok := v.(map[string]interface{}); ok {
+			edge.Style = s
+		}
+	}
+	for k, v := range props {
+		switch k {
+		case "id", "label", "style":
+		default:
+			edge.Properties[k] = v
+		}
+	}
+	return edge
+}
+
+func getStr(props map[string]any, key string) string {
+	if v, ok := props[key]; ok && v != nil {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}
+
+func getFloat64(v any) float64 {
+	switch val := v.(type) {
+	case float64:
+		return val
+	case int64:
+		return float64(val)
+	case int:
+		return float64(val)
+	}
+	return 0
+}
+
+func getInt(record *neo4j.Record, key string) int {
+	v, _ := record.Get(key)
+	switch val := v.(type) {
+	case int64:
+		return int(val)
+	case int:
+		return val
+	case float64:
+		return int(val)
+	}
+	return 0
+}
+
+func buildNodeProps(req model.CreateNodeRequest) map[string]any {
+	props := map[string]any{"id": req.ID, "label": req.Label}
+	if req.Type != "" {
+		props["type"] = req.Type
+	}
+	if req.X != 0 {
+		props["x"] = req.X
+	}
+	if req.Y != 0 {
+		props["y"] = req.Y
+	}
+	for k, v := range req.Properties {
+		if isReservedNodeProperty(k) {
+			continue
+		}
+		props[k] = v
+	}
+	return props
+}
+
+func buildEdgeProps(req model.CreateEdgeRequest) map[string]any {
+	props := map[string]any{"id": req.ID, "label": req.Label}
+	for k, v := range req.Properties {
+		if isReservedEdgeProperty(k) {
+			continue
+		}
+		props[k] = v
+	}
+	return props
+}
+
+func isReservedNodeProperty(key string) bool {
+	switch key {
+	case "id", "label", "type", "x", "y", "style":
+		return true
+	default:
+		return false
+	}
+}
+
+func isReservedEdgeProperty(key string) bool {
+	switch key {
+	case "id", "label", "type", "style", "source", "target":
+		return true
+	default:
+		return false
+	}
+}
+
+func sanitizeLabel(label string) string {
+	if label == "" {
+		return ""
+	}
+	var b strings.Builder
+	for i, r := range label {
+		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '_' {
+			b.WriteRune(r)
+			continue
+		}
+		if i == 0 {
+			continue
+		}
+		b.WriteRune('_')
+	}
+	return strings.Trim(b.String(), "_")
+}
+
+func sanitizeRelationshipType(relType string) string {
+	if relType == "" {
+		return ""
+	}
+	return sanitizeLabel(strings.ToUpper(relType))
+}
+
+func wrapNotFound(entity string, id string) error {
+	return fmt.Errorf("%s with id %s not found", entity, id)
+}

gen_swagger.ps1

@@ -0,0 +1,6 @@
+$ErrorActionPreference = 'Stop'
+
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+Set-Location (Join-Path $ScriptDir 'backend')
+
+swag init -g ./cmd/server/main.go --parseDependency --parseInternal

gen_swagger.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR/backend"
+
+swag init -g ./cmd/server/main.go --parseDependency --parseInternal --output ./docs

project-architecture.svg

@@ -0,0 +1,80 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1920" height="1200" viewBox="0 0 960 600">
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#2563eb"/>
+    </marker>
+    <marker id="arrow-orange" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#ea580c"/>
+    </marker>
+    <style>
+      .title { font: 700 20px Arial, sans-serif; fill: #0f172a; }
+      .label { font: 600 14px Arial, sans-serif; fill: #0f172a; }
+      .small { font: 12px Arial, sans-serif; fill: #334155; }
+      .box { stroke: #1e293b; stroke-width: 1.5; rx: 16; ry: 16; }
+      .layer { fill: #f8fafc; stroke: #cbd5e1; stroke-dasharray: 7 5; stroke-width: 1.5; rx: 20; ry: 20; }
+    </style>
+  </defs>
+  <rect x="0" y="0" width="960" height="600" fill="#ffffff"/>
+  <text x="480" y="42" text-anchor="middle" class="title">knowledge-graph-agent 项目架构图</text>
+  <text x="480" y="66" text-anchor="middle" class="small">知识图谱 + 层级记忆 + 自省反馈 + AI 对话 + 邮件自动化</text>
+  <rect x="40" y="100" width="880" height="120" class="layer"/>
+  <text x="60" y="124" class="label">用户交互层</text>
+  <rect x="40" y="240" width="880" height="130" class="layer"/>
+  <text x="60" y="264" class="label">应用服务层</text>
+  <rect x="40" y="395" width="880" height="140" class="layer"/>
+  <text x="60" y="419" class="label">数据与外部能力层</text>
+  <rect x="90" y="145" width="220" height="48" class="box" fill="#dbeafe"/>
+  <text x="200.0" y="167" text-anchor="middle" class="label">React 前端</text>
+  <text x="200.0" y="185" text-anchor="middle" class="small">Graph UI / Chat UI</text>
+  <rect x="350" y="145" width="220" height="48" class="box" fill="#dbeafe"/>
+  <text x="460.0" y="167" text-anchor="middle" class="label">AntV G6 + Zustand</text>
+  <text x="460.0" y="185" text-anchor="middle" class="small">图谱渲染 / 状态管理</text>
+  <rect x="610" y="145" width="240" height="48" class="box" fill="#dbeafe"/>
+  <text x="730.0" y="167" text-anchor="middle" class="label">Axios + Tailwind</text>
+  <text x="730.0" y="185" text-anchor="middle" class="small">API 请求 / UI 样式</text>
+  <rect x="90" y="285" width="220" height="52" class="box" fill="#dcfce7"/>
+  <text x="200.0" y="307" text-anchor="middle" class="label">Gin API 层</text>
+  <text x="200.0" y="325" text-anchor="middle" class="small">REST 接口 / 路由 / 校验</text>
+  <rect x="350" y="285" width="220" height="52" class="box" fill="#dcfce7"/>
+  <text x="460.0" y="307" text-anchor="middle" class="label">Graph Service</text>
+  <text x="460.0" y="325" text-anchor="middle" class="small">查询 / 搜索 / 邻居 / CRUD</text>
+  <rect x="610" y="285" width="240" height="52" class="box" fill="#dcfce7"/>
+  <text x="730.0" y="307" text-anchor="middle" class="label">AI ＆ Conversation</text>
+  <text x="730.0" y="325" text-anchor="middle" class="small">Prompt / 会话 / 上下文增强</text>
+  <rect x="120" y="435" width="220" height="54" class="box" fill="#fef3c7"/>
+  <text x="230.0" y="457" text-anchor="middle" class="label">Neo4j 5.x</text>
+  <text x="230.0" y="475" text-anchor="middle" class="small">知识图谱持久化</text>
+  <rect x="390" y="435" width="220" height="54" class="box" fill="#fef3c7"/>
+  <text x="500.0" y="457" text-anchor="middle" class="label">AI Provider</text>
+  <text x="500.0" y="475" text-anchor="middle" class="small">硅基流动 OpenAI 接口</text>
+  <rect x="660" y="435" width="180" height="54" class="box" fill="#fef3c7"/>
+  <text x="750.0" y="457" text-anchor="middle" class="label">邮件自动化</text>
+  <text x="750.0" y="475" text-anchor="middle" class="small">后续增强</text>
+  <line x1="200" y1="193" x2="200" y2="285" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="154.0" y="217.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="200.0" y="231.0" text-anchor="middle" class="small">用户操作 / 查询</text>
+  <line x1="460" y1="193" x2="460" y2="285" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="414.0" y="217.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="460.0" y="231.0" text-anchor="middle" class="small">图谱浏览 / 编辑</text>
+  <line x1="730" y1="193" x2="730" y2="285" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="684.0" y="217.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="730.0" y="231.0" text-anchor="middle" class="small">提交消息 / 交互</text>
+  <line x1="240" y1="337" x2="240" y2="435" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="194.0" y="364.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="240.0" y="378.0" text-anchor="middle" class="small">读写图数据</text>
+  <line x1="460" y1="337" x2="460" y2="435" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="414.0" y="364.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="460.0" y="378.0" text-anchor="middle" class="small">检索上下文 / 记忆</text>
+  <line x1="730" y1="337" x2="520" y2="435" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <rect x="579.0" y="364.0" width="92" height="20" rx="6" ry="6" fill="#ffffff" opacity="0.96"/>
+  <text x="625.0" y="378.0" text-anchor="middle" class="small">生成回复 / 调用模型</text>
+  <path d="M 850 462 C 900 462, 900 520, 850 520" fill="none" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+  <rect x="780" y="520" width="140" height="36" rx="10" ry="10" fill="#fff7ed" stroke="#fb923c"/>
+  <text x="850" y="543" text-anchor="middle" class="small">定时任务 / 邮件</text>
+  <rect x="60" y="535" width="250" height="42" rx="10" ry="10" fill="#f8fafc" stroke="#cbd5e1"/>
+  <line x1="78" y1="556" x2="130" y2="556" stroke="#2563eb" stroke-width="2" marker-end="url(#arrow)"/>
+  <text x="146" y="561" class="small">主要请求 / 数据流</text>
+  <rect x="340" y="535" width="250" height="42" rx="10" ry="10" fill="#f8fafc" stroke="#cbd5e1"/>
+  <line x1="358" y1="556" x2="410" y2="556" stroke="#ea580c" stroke-width="2" marker-end="url(#arrow-orange)"/>
+  <text x="426" y="561" class="small">外部能力 / 触发流</text>
+</svg>