# Interactive Mindmap

基于 `Next.js 14`、`FastAPI` 和 `SQLite` 的思维导图项目。

当前项目的实际使用方式是：

- 腾讯云智能体工作流生成思维导图 JSON
- 后端 `POST /api/mindmaps` 保存脑图并返回访问链接
- 前端通过 `/mindmap/[id]` 展示脑图
- 在脑图详情页中，双击节点可打开右侧聊天面板，继续通过腾讯云智能体进行对话

## 当前功能

- 保存思维导图 JSON，并生成可访问链接
- 展示思维导图详情页
- 支持节点展开/收缩
- 支持在详情页中对节点发起对话
- 后端代理腾讯云智能体 SSE 接口

## 项目结构

```text
mindmap/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── models.py
│   │   ├── schemas.py
│   │   └── routers/
│   │       ├── chat.py
│   │       └── mindmaps.py
│   ├── data/
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── app/
│   │   ├── page.tsx
│   │   └── mindmap/
│   │       └── [id]/page.tsx
│   ├── components/
│   │   ├── ChatPanel.tsx
│   │   ├── MarkdownMessage.tsx
│   │   ├── MindmapCanvas.tsx
│   │   └── MindmapNodeCard.tsx
│   ├── lib/
│   │   ├── api.ts
│   │   ├── tencentSse.ts
│   │   └── treeToGraph.ts
│   ├── types/
│   │   └── mindmap.ts
│   └── package.json
├── mind_prompt.md
├── 宝塔面板部署指南.md
└── 腾讯云工作流说明.md
```

## 页面说明

### 首页 `/`

当前首页是项目说明页，不负责直接创建脑图。

### 思维导图详情页 `/mindmap/[id]`

该页面会：

- 从后端读取指定 `unique_id` 的脑图数据
- 渲染交互式脑图
- 双击节点后打开右侧聊天面板
- 聊天面板通过 `/api/chat` 与腾讯云智能体交互

## 后端接口

### `GET /`

健康检查接口。

返回：

```json
{"message":"Interactive Mindmap API is running"}
```

### `POST /api/mindmaps`

创建并保存思维导图。

请求体：

```json
{
  "session_id": "session_001",
  "mindmap_json": {
    "id": "node_0",
    "label": "主题",
    "parent_id": null,
    "level": 0,
    "is_leaf": false,
    "children": []
  }
}
```

返回中会包含：

- `unique_id`
- `title`
- `url`
- `tree`

### `GET /api/mindmaps/{unique_id}`

读取指定脑图详情。

### `POST /api/chat`

后端代理腾讯云智能体 SSE 接口。

请求体：

```json
{
  "session_id": "session_001",
  "content": "帮我解释一下这个节点",
  "visitor_biz_id": "default_visitor"
}
```

返回：

- `text/event-stream`

## 环境变量

## 后端 `backend/.env`

复制：

```bash
cp backend/.env.example backend/.env
```

实际使用的变量名是：

```env
BOT_APP_KEY=your-app-key
FRONTEND_BASE_URL=http://localhost:3000
```

说明：

- `BOT_APP_KEY`：腾讯云智能体平台 AppKey
- `FRONTEND_BASE_URL`：后端返回脑图链接时使用的前端基地址

注意：当前代码读取的是 `BOT_APP_KEY`，不是 `TENCENT_BOT_APP_KEY`。

## 前端 `frontend/.env.production`

如果前后端分端口直连，推荐写成：

```env
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```

如果后面切到统一入口反向代理，可以改成：

```env
NEXT_PUBLIC_API_BASE_URL=
```

## 本地开发

## 启动后端

```bash
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

默认地址：

```text
http://127.0.0.1:8000
```

## 启动前端

```bash
cd frontend
npm install
npm run dev
```

默认地址：

```text
http://127.0.0.1:3000
```

## 生产构建

```bash
cd frontend
npm ci
rm -rf .next
npm run build
npm run start -- -p 3000
```

## 测试一条脑图创建链路

后端启动后，可以直接调用：

```bash
curl -X POST http://127.0.0.1:8000/api/mindmaps \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "test-session",
    "mindmap_json": {
      "id": "node_0",
      "label": "测试主题",
      "parent_id": null,
      "level": 0,
      "is_leaf": false,
      "children": [
        {
          "id": "node_1",
          "label": "测试子节点",
          "parent_id": "node_0",
          "level": 1,
          "is_leaf": true,
          "children": []
        }
      ]
    }
  }'
```

成功后会返回一个 `url`，打开即可查看脑图详情页。

## 腾讯云智能体接入说明

当前项目更适合由腾讯云工作流或插件来创建脑图，而不是由前端首页直接生成。

建议查看：

- [mind_prompt.md](./mind_prompt.md)
- [腾讯云工作流说明.md](./腾讯云工作流说明.md)

如果你走当前工作流方案，关键链路是：

```text
开始
-> 大模型生成内容
-> 大模型整理 JSON
-> 大模型检查 JSON
-> 变量转换(JSON 反序列化)
-> 插件调用 /api/mindmaps
-> 回复脑图链接
```

## 部署说明

当前实际部署文档见：

- [宝塔面板部署指南.md](./宝塔面板部署指南.md)

当前推荐部署方式与实际落地一致：

- 前端放在宝塔 `Node 项目`
- 后端放在宝塔 `Python 项目`
- 通过公网 IP + `3000/8000` 直接访问

## 已知注意事项

### 1. `frontend/lib` 不能被 `.gitignore` 误伤

根目录 `.gitignore` 如果写成：

```gitignore
lib/
```

会把 `frontend/lib/` 一起忽略掉，导致服务器缺少：

- `frontend/lib/api.ts`
- `frontend/lib/tencentSse.ts`
- `frontend/lib/treeToGraph.ts`

正确写法应该是：

```gitignore
/lib/
/lib64/
```

### 2. 前端接口地址改动后必须重建

只要改了：

- `NEXT_PUBLIC_API_BASE_URL`

就必须重新执行：

```bash
cd frontend
rm -rf .next
npm run build
```

### 3. 后端返回链接依赖 `FRONTEND_BASE_URL`

如果这个值不对，后端返回的 `url` 就会不对。