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

## 📋 概述

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

## 🔧 基础信息

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

## 📊 数据格式规范

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

### 完整思维导图数据格式
```json
{
  "nodeData": {
    "id": "string",          // 根节点ID
    "topic": "string",       // 根节点标题
    "data": {
      "des": "string"        // 根节点描述
    },
    "children": [ /* Node[] */ ] // 子节点数组
  }
}
```

### 数据库节点格式
```json
{
  "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

**请求示例：**
```bash
GET /api/mindMaps/1
```

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

**错误响应：**
```json
{
  "detail": "mindMap not found"
}
```

### 创建思维导图

**接口：** `POST /api/mindMaps`

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

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

**请求示例：**
```bash
POST /api/mindMaps
Content-Type: application/json

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

**响应示例：**
```json
{
  "id": 1,
  "title": "AI技术发展",
  "nodeData": {
    "id": "root",
    "topic": "AI技术发展",
    "data": {
      "des": "人工智能技术发展历程"
    },
    "children": []
  }
}
```

## 🔗 节点操作接口

### 批量添加节点

**接口：** `POST /api/mindMaps/addNodes`

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

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

**请求示例：**
```bash
POST /api/mindMaps/addNodes
Content-Type: application/json

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

**响应示例：**
```json
{
  "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
      }
    ]
  }
}
```

**错误响应：**
```json
{
  "detail": "mindMapId is required"
}
```

### 更新节点

**接口：** `PATCH /api/mindMaps/updateNode`

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

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

**请求示例：**
```bash
PATCH /api/mindMaps/updateNode
Content-Type: application/json

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

**响应示例：**
```json
{
  "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"]
}
```

**错误响应：**
```json
{
  "detail": "id is required"
}
```

### 批量删除节点

**接口：** `DELETE /api/mindMaps/deleteNodes`

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

**请求体：**
```json
{
  "nodeIds": ["node_123", "node_456", "node_789"]  // 要删除的节点ID数组
}
```

**请求示例：**
```bash
DELETE /api/mindMaps/deleteNodes
Content-Type: application/json

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

**响应示例：**
```json
{
  "success": true,
  "message": "节点删除成功",
  "data": {
    "deletedCount": 5,
    "deletedNodeIds": ["node-1", "node-2", "node-1-1", "node-1-2", "node-2-1"]
  }
}
```

**错误响应：**
```json
{
  "detail": "nodeIds is required"
}
```

## 🤖 AI服务接口

### AI生成Markdown

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

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

**请求体：**
```json
{
  "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密钥
}
```

**请求示例：**
```bash
POST /api/ai/generate-markdown
Content-Type: application/json

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

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

**错误响应：**
```json
{
  "error": "用户提示词不能为空",
  "success": false
}
```

## 📊 数据格式转换说明

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

**前端MindElixir期望格式：**
```json
{
  "nodeData": {
    "id": "root",
    "topic": "根节点标题",
    "data": {
      "des": "节点描述"
    },
    "children": [
      {
        "id": "child-1",
        "topic": "子节点标题",
        "data": {
          "des": "子节点描述"
        },
        "children": []
      }
    ]
  }
}
```

**后端数据库存储格式：**
```json
{
  "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` | 节点唯一标识 |

### 数据转换规则

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

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

## 📝 示例思维导图结构

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

## 🔧 错误码说明

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

## 📚 使用示例

### 完整工作流程示例

1. **创建思维导图**
```bash
POST /api/mindMaps
{
  "title": "AI技术发展"
}
```

2. **添加节点**
```bash
POST /api/mindMaps/addNodes
{
  "mindMapId": 1,
  "nodes": [
    {
      "title": "机器学习",
      "des": "机器学习算法和应用",
      "parentId": "root"
    }
  ]
}
```

3. **更新节点**
```bash
PATCH /api/mindMaps/updateNode
{
  "id": "node-1",
  "newTitle": "机器学习算法",
  "newDes": "包括监督学习、无监督学习等"
}
```


4. **获取完整数据**
```bash
GET /api/mindMaps/1
```

## 🚀 快速开始

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

## 📞 技术支持

如有问题，请查看：
- 项目README文档
- 代码注释和示例
- 错误日志和调试信息

## 初始化Git仓库并上传

### 1. 初始化Git仓库

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

### 2. 创建.gitignore文件

```bash
<code_block_to_apply_changes_from>
```

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

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

### 4. 添加远程仓库

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

### 5. 添加所有文件到Git

```bash
git add .
```

### 6. 提交更改

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

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

### 7. 设置主分支并推送

```bash
git branch -M main
git push -u origin main
```

## 如果推送时遇到认证问题

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

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

## 验证步骤

推送完成后，你可以：

1. **检查Git状态**：
   ```bash
   git status
   ```

2. **查看远程仓库**：
   ```bash
   git remote -v
   ```

3. **访问仓库网站**：
   打开 [http://test-www.writebug.com:3000/lixinran/MindMap](http://test-www.writebug.com:3000/lixinran/MindMap) 查看是否能看到项目文件

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