13 KiB

Raw Blame History

AI思维导图系统API接口文档

📋 概述

本文档描述了AI思维导图系统的RESTful API接口，包括思维导图管理、节点操作和AI服务等核心功能。

🔧 基础信息

Base URL: http://127.0.0.1:8000/api
Content-Type: application/json
数据格式: 遵循MindElixir规范

📊 数据格式规范

MindElixir节点格式

{
  "id": "string",            // 唯一标识符，必填
  "topic": "string",         // 节点标题，必填
  "data": {
    "des": "string"          // 节点描述，可选
  },
  "children": [ /* Node[] */ ], // 子节点数组，必填
  "mindmapId": "string"      // 思维导图ID，可选
}

完整思维导图数据格式

{
  "nodeData": {
    "id": "string",          // 根节点ID
    "topic": "string",       // 根节点标题
    "data": {
      "des": "string"        // 根节点描述
    },
    "children": [ /* Node[] */ ] // 子节点数组
  }
}

数据库节点格式

{
  "id": "string",            // 节点ID
  "isRoot": boolean,         // 是否为根节点
  "parentId": "string",      // 父节点ID
  "childrenCount": number,   // 子节点数量
  "depth": number,           // 节点深度
  "title": "string",         // 节点标题
  "des": "string",           // 节点描述
  "createDate": "datetime",  // 创建时间
  "updateDate": "datetime",  // 更新时间
  "delete": boolean          // 是否删除
}

🗺️ 思维导图管理接口

获取思维导图

接口： GET /api/mindMaps/{id}

描述： 根据ID获取思维导图的完整数据，返回MindElixir格式的树形结构

路径参数：

id (integer): 思维导图ID

请求示例：

GET /api/mindMaps/1

响应示例：

{
  "nodeData": {
    "id": "root",
    "topic": "数字教育平台设计要点",
    "data": {
      "des": "思维导图的根节点"
    },
    "children": [
      {
        "id": "node-1",
        "topic": "用户体验设计",
        "data": {
          "des": "用户体验设计的重要性"
        },
        "children": [
          {
            "id": "node-1-1",
            "topic": "界面交互设计",
            "data": {
              "des": "核心功能入口应控制在3次点击内可达"
            },
            "children": []
          }
        ]
      }
    ]
  }
}

错误响应：

{
  "detail": "mindMap not found"
}

创建思维导图

接口： POST /api/mindMaps

描述： 创建新的思维导图，支持传入初始数据或创建空思维导图

请求体：

{
  "title": "新的思维导图",    // 可选，思维导图名称
  "data": {                 // 可选，初始思维导图数据
    "topic": "根节点标题",
    "data": {
      "des": "根节点描述"
    },
    "children": []
  }
}

请求示例：

POST /api/mindMaps
Content-Type: application/json

{
  "title": "AI技术发展",
  "data": {
    "topic": "AI技术发展",
    "data": {
      "des": "人工智能技术发展历程"
    },
    "children": []
  }
}

响应示例：

{
  "id": 1,
  "title": "AI技术发展",
  "nodeData": {
    "id": "root",
    "topic": "AI技术发展",
    "data": {
      "des": "人工智能技术发展历程"
    },
    "children": []
  }
}

🔗 节点操作接口

批量添加节点

接口： POST /api/mindMaps/addNodes

描述： 向指定思维导图中批量添加节点，支持添加子节点和兄弟节点

请求体：

{
  "mindMapId": 1,              // 思维导图ID
  "nodes": [                   // 节点数组
    {
      "title": "子节点1",       // 节点标题
      "des": "节点描述",        // 节点描述
      "parentId": "parent-id", // 父节点ID
      "isRoot": false          // 是否为根节点
    }
  ]
}

请求示例：

POST /api/mindMaps/addNodes
Content-Type: application/json

{
  "mindMapId": 1,
  "nodes": [
    {
      "title": "机器学习",
      "des": "机器学习算法和应用",
      "parentId": "root"
    },
    {
      "title": "深度学习",
      "des": "深度学习技术发展",
      "parentId": "root"
    }
  ]
}

响应示例：

{
  "success": true,
  "message": "成功创建 2 个节点",
  "data": {
    "mindMapId": "1",
    "nodes": [
      {
        "id": "node-1",
        "isRoot": false,
        "parentId": "root",
        "childrenCount": 0,
        "depth": 1,
        "title": "机器学习",
        "des": "机器学习算法和应用",
        "createDate": "2023-07-01T10:30:00Z",
        "updateDate": "2023-07-01T10:30:00Z",
        "delete": false
      },
      {
        "id": "node-2",
        "isRoot": false,
        "parentId": "root",
        "childrenCount": 0,
        "depth": 1,
        "title": "深度学习",
        "des": "深度学习技术发展",
        "createDate": "2023-07-01T10:30:00Z",
        "updateDate": "2023-07-01T10:30:00Z",
        "delete": false
      }
    ]
  }
}

错误响应：

{
  "detail": "mindMapId is required"
}

更新节点

接口： PATCH /api/mindMaps/updateNode

描述： 更新指定节点的标题、描述或父节点关系

请求体：

{
  "id": "node_123",                    // 节点ID，必填
  "newTitle": "更新后的节点标题",        // 可选，新标题
  "newDes": "更新后的节点描述内容",      // 可选，新描述
  "newParentId": "parent_node_id_123"  // 可选，新父节点ID
}

请求示例：

PATCH /api/mindMaps/updateNode
Content-Type: application/json

{
  "id": "node-1",
  "newTitle": "机器学习算法",
  "newDes": "包括监督学习、无监督学习和强化学习",
  "newParentId": "root"
}

响应示例：

{
  "success": true,
  "message": "节点更新成功",
  "data": {
    "id": "node-1",
    "isRoot": false,
    "parentId": "root",
    "childrenCount": 0,
    "depth": 1,
    "title": "机器学习算法",
    "des": "包括监督学习、无监督学习和强化学习",
    "createDate": "2023-01-01T00:00:00Z",
    "updateDate": "2023-10-05T15:30:00Z",
    "delete": false
  },
  "updatedFields": ["title", "des", "parentId"]
}

错误响应：

{
  "detail": "id is required"
}

批量删除节点

接口： DELETE /api/mindMaps/deleteNodes

描述： 批量删除节点及其所有子节点（软删除），自动更新父节点的子节点计数

请求体：

{
  "nodeIds": ["node_123", "node_456", "node_789"]  // 要删除的节点ID数组
}

请求示例：

DELETE /api/mindMaps/deleteNodes
Content-Type: application/json

{
  "nodeIds": ["node-1", "node-2"]
}

响应示例：

{
  "success": true,
  "message": "节点删除成功",
  "data": {
    "deletedCount": 5,
    "deletedNodeIds": ["node-1", "node-2", "node-1-1", "node-1-2", "node-2-1"]
  }
}

错误响应：

{
  "detail": "nodeIds is required"
}

🤖 AI服务接口

AI生成Markdown

接口： POST /api/ai/generate-markdown

描述： 调用AI服务分析文档内容，生成结构化的Markdown格式思维导图

请求体：

{
  "system_prompt": "AI系统提示词",     // 可选，自定义系统提示
  "user_prompt": "用户输入内容",       // 必填，要分析的内容
  "model": "glm-4.5",               // 可选，AI模型名称
  "base_url": "https://open.bigmodel.cn/api/paas/v4/",  // 可选，API地址
  "api_key": "your_api_key"         // 可选，API密钥
}

请求示例：

POST /api/ai/generate-markdown
Content-Type: application/json

{
  "system_prompt": "你是一位专业的文档分析专家，请将以下内容转换为结构化的Markdown格式",
  "user_prompt": "人工智能技术发展历程包括早期发展、现代发展等阶段...",
  "model": "glm-4.5"
}

响应示例：

{
  "markdown": "# 人工智能技术发展历程\n\n## 早期发展\n- 1950年代概念提出\n- 图灵测试的提出\n\n## 现代发展\n- 深度学习技术突破\n- 应用领域扩展",
  "success": true
}

错误响应：

{
  "error": "用户提示词不能为空",
  "success": false
}

📊 数据格式转换说明

前端MindElixir格式 vs 后端数据库格式

前端MindElixir期望格式：

{
  "nodeData": {
    "id": "root",
    "topic": "根节点标题",
    "data": {
      "des": "节点描述"
    },
    "children": [
      {
        "id": "child-1",
        "topic": "子节点标题",
        "data": {
          "des": "子节点描述"
        },
        "children": []
      }
    ]
  }
}

后端数据库存储格式：

{
  "id": "mindmap-123",
  "title": "思维导图标题",
  "nodes": [
    {
      "id": "node-1",
      "title": "根节点标题",
      "des": "节点描述",
      "isRoot": true,
      "parentId": null,
      "depth": 0,
      "childrenCount": 1,
      "createDate": "2023-07-01T00:00:00Z",
      "updateDate": "2023-07-01T00:00:00Z",
      "delete": false
    }
  ],
  "createDate": "2023-07-01T00:00:00Z",
  "updateDate": "2023-07-01T00:00:00Z",
  "delete": false
}

关键字段映射

前端MindElixir	后端数据库	说明
`topic`	`title`	节点标题
`data.des`	`des`	节点描述
`children`	通过`parentId`关系构建	子节点关系
`id`	`id`	节点唯一标识

数据转换规则

获取思维导图时：后端将扁平节点列表转换为MindElixir期望的树形结构
保存节点时：前端发送扁平格式，后端存储为关系型数据
过滤规则：自动过滤掉标题为"根节点标题"且没有子节点的空根节点

所有操作后端都会自动更新 depth、childrenCount。

📝 示例思维导图结构

数字教育平台设计要点
├── 用户体验设计
│   ├── 界面交互设计
│   │   └── 核心功能入口应控制在3次点击内可达
│   └── 内容架构规划
│       └── 合理的内容组织帮助用户构建知识体系
├── 互动功能开发
│   └── 学习互动设计
│       └── 平台应提供即时反馈机制
└── 数据安全保障
    └── 隐私保护措施
        ├── 个人信息和学习数据采用AES-256加密存储
        └── 实施基于角色的权限管理

🔧 错误码说明

错误码	说明	解决方案
400	请求参数错误	检查请求体格式和必填字段
404	资源不存在	确认ID是否正确
500	服务器内部错误	检查服务器日志

📚 使用示例

完整工作流程示例

创建思维导图

POST /api/mindMaps
{
  "title": "AI技术发展"
}

添加节点

POST /api/mindMaps/addNodes
{
  "mindMapId": 1,
  "nodes": [
    {
      "title": "机器学习",
      "des": "机器学习算法和应用",
      "parentId": "root"
    }
  ]
}

更新节点

PATCH /api/mindMaps/updateNode
{
  "id": "node-1",
  "newTitle": "机器学习算法",
  "newDes": "包括监督学习、无监督学习等"
}

获取完整数据

GET /api/mindMaps/1

🚀 快速开始

启动后端服务：python manage.py runserver
启动前端服务：cd frontend && npm run dev
访问前端界面：http://localhost:5173
使用API接口：http://localhost:8000/api

📞 技术支持

如有问题，请查看：

项目README文档
代码注释和示例
错误日志和调试信息

初始化Git仓库并上传

1. 初始化Git仓库

cd /Users/natalie/Documents/test/siweidaotu
git init

2. 创建.gitignore文件

<code_block_to_apply_changes_from>

3. 配置Git用户信息（如果还没有配置）

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

4. 添加远程仓库

git remote add origin http://test-www.writebug.com:3000/lixinran/MindMap.git

5. 添加所有文件到Git

git add .

6. 提交更改

git commit -m "Initial commit: AI思维导图生成器项目

- 基于Django + Vue.js的智能思维导图生成和管理系统
- 支持AI驱动的文档分析和可视化思维导图创建
- 包含完整的前后端代码和文档"

7. 设置主分支并推送

git branch -M main
git push -u origin main

如果推送时遇到认证问题

当执行 git push -u origin main 时，可能会提示输入用户名和密码：

用户名：输入你的Git账户用户名
密码：输入你的Git账户密码或访问令牌

验证步骤

推送完成后，你可以：

检查Git状态：
```
git status
```
查看远程仓库：
```
git remote -v
```
访问仓库网站：打开 http://test-www.writebug.com:3000/lixinran/MindMap 查看是否能看到项目文件

请按照这些步骤操作，如果遇到任何错误信息，请告诉我具体的错误内容。

13 KiB Raw Blame History Unescape Escape

AI思维导图系统API接口文档

📋 概述

🔧 基础信息

📊 数据格式规范

MindElixir节点格式

完整思维导图数据格式

数据库节点格式

🗺️ 思维导图管理接口

获取思维导图

创建思维导图

🔗 节点操作接口

批量添加节点

更新节点

批量删除节点

🤖 AI服务接口

AI生成Markdown

📊 数据格式转换说明

前端MindElixir格式 vs 后端数据库格式

关键字段映射

数据转换规则

📝 示例思维导图结构

🔧 错误码说明

📚 使用示例

完整工作流程示例

🚀 快速开始

📞 技术支持

初始化Git仓库并上传

1. 初始化Git仓库

2. 创建.gitignore文件

3. 配置Git用户信息（如果还没有配置）

4. 添加远程仓库

5. 添加所有文件到Git

6. 提交更改

7. 设置主分支并推送

如果推送时遇到认证问题

验证步骤

13 KiB

Raw Blame History