319 lines
5.9 KiB
Markdown
319 lines
5.9 KiB
Markdown
# 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` 就会不对。
|