diff --git a/README.md b/README.md
index 08037db..f01f21f 100644
--- a/README.md
+++ b/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 增加更细的接口表格和请求/响应样例
+- 继续补一张“前后端交互时序图”
+- 把整个项目的文档风格统一成一套模板
diff --git a/backend/README.md b/backend/README.md
index aefdf3a..d71096c 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,279 +1,538 @@
-# 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
+```
+
+---
+
+## 十、当前实现特点
+
+### 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
+- 后续扩展点在哪里