b67e14cced
- Introduced `PROJECT_STATUS.md` to provide a comprehensive overview of the MiroFish project, detailing the current status, completed features, and future development plans. - Added multiple documentation files in the frontend directory, including detailed descriptions of the homepage functionality, startup guide, and project completion summary. - Implemented a structured approach to document the project's architecture, API integration, and user interaction processes, enhancing clarity for developers and users alike. - Included a `.gitignore` file to manage ignored files and directories in the frontend project, improving project organization and cleanliness.
303 lines
7.3 KiB
Markdown
303 lines
7.3 KiB
Markdown
# MiroFish 项目状态报告
|
|
|
|
## 项目概览
|
|
MiroFish是一个社交媒体舆论模拟系统,采用前后端分离架构。
|
|
|
|
## 完成情况
|
|
|
|
### ✅ 后端 (Flask)
|
|
- [x] RESTful API架构
|
|
- [x] 知识图谱构建(Zep)
|
|
- [x] LLM集成(OpenAI兼容接口)
|
|
- [x] 本体生成服务
|
|
- [x] 图谱构建服务
|
|
- [x] 模拟管理服务
|
|
- [x] 容错重试机制
|
|
- [x] 详细的API文档
|
|
|
|
**后端地址**: http://localhost:5001
|
|
|
|
### ✅ 前端 (Vue 3)
|
|
- [x] Vue 3 + Vite脚手架搭建
|
|
- [x] 项目目录结构规划
|
|
- [x] 首页设计完成(极简黑白线条风)
|
|
- [x] 文件上传功能(支持拖拽)
|
|
- [x] API接口封装(含重试机制)
|
|
- [x] 路由管理(Vue Router 4)
|
|
- [x] 第二页基础框架
|
|
- [x] 自动轮询任务状态
|
|
- [x] 响应式设计
|
|
|
|
**前端地址**: http://localhost:3000
|
|
|
|
## 目录结构
|
|
|
|
```
|
|
MiroFish/
|
|
├── backend/ # 后端服务
|
|
│ ├── app/
|
|
│ │ ├── api/ # API路由
|
|
│ │ ├── services/ # 业务逻辑
|
|
│ │ ├── models/ # 数据模型
|
|
│ │ └── utils/ # 工具类
|
|
│ ├── scripts/ # 模拟脚本
|
|
│ ├── uploads/ # 数据存储
|
|
│ ├── run.py # 启动入口
|
|
│ └── requirements.txt # Python依赖
|
|
│
|
|
├── frontend/ # 前端项目
|
|
│ ├── src/
|
|
│ │ ├── api/ # API接口封装
|
|
│ │ ├── assets/ # 静态资源
|
|
│ │ ├── views/ # 页面组件
|
|
│ │ ├── router/ # 路由配置
|
|
│ │ ├── App.vue # 根组件
|
|
│ │ └── main.js # 入口文件
|
|
│ ├── .env.development # 开发环境配置
|
|
│ ├── vite.config.js # Vite配置
|
|
│ └── package.json # 依赖配置
|
|
│
|
|
├── static/ # 共享静态资源
|
|
│ └── image/
|
|
│ └── MiroFish_logo_compressed.jpeg
|
|
│
|
|
├── mydoc/ # 项目文档
|
|
│ ├── MiroFish文档.md
|
|
│ └── 前端设计思路.md
|
|
│
|
|
└── .env # 环境配置(后端)
|
|
```
|
|
|
|
## 首页功能展示
|
|
|
|
### 页面元素
|
|
1. **Logo**: MiroFish品牌标识(居中展示)
|
|
2. **标语**: "上传任意报告,模拟世界即刻开始"
|
|
3. **模拟需求输入框**: 用户描述模拟需求
|
|
4. **项目名称**: 可选的项目命名
|
|
5. **文件上传区域**:
|
|
- 支持拖拽上传
|
|
- 支持点击选择
|
|
- 支持多文件
|
|
- 格式: PDF、Markdown、TXT
|
|
6. **额外说明**: 可选的补充信息
|
|
7. **开始模拟按钮**: 提交表单,调用API
|
|
|
|
### 设计风格
|
|
- **极简黑白线条风**
|
|
- 纯黑(#000000) + 纯白(#FFFFFF)
|
|
- 1-2px实线边框
|
|
- 清晰的排版和间距
|
|
- 简洁的交互动画
|
|
|
|
### 交互流程
|
|
1. 用户填写模拟需求
|
|
2. 上传相关文档
|
|
3. 点击"开始模拟"
|
|
4. 系统调用 `/api/graph/ontology/generate` 接口
|
|
5. 显示加载状态
|
|
6. 成功后跳转到处理页面 `/process/:projectId`
|
|
|
|
## 第二页功能
|
|
|
|
### 布局
|
|
- **左侧**: 实时图谱可视化
|
|
- **右侧**: Step 1 - 现实种子构建流程
|
|
|
|
### 自动化流程
|
|
1. 自动加载项目信息
|
|
2. 自动开始图谱构建
|
|
3. 轮询任务状态(每2秒)
|
|
4. 实时更新进度
|
|
5. 完成后加载图谱数据
|
|
|
|
### 流程步骤
|
|
- [x] 文档分析
|
|
- [x] 本体生成
|
|
- [x] 图谱构建
|
|
- [x] 完成
|
|
|
|
## API接口实现
|
|
|
|
### 已实现的接口调用
|
|
1. **生成本体**: `POST /api/graph/ontology/generate`
|
|
- multipart/form-data格式
|
|
- 包含文件和表单数据
|
|
- 自动重试机制
|
|
|
|
2. **构建图谱**: `POST /api/graph/build`
|
|
- 自动触发
|
|
- 返回任务ID
|
|
|
|
3. **查询任务**: `GET /api/graph/task/{taskId}`
|
|
- 轮询机制
|
|
- 每2秒查询一次
|
|
|
|
4. **获取图谱**: `GET /api/graph/data/{graphId}`
|
|
- 构建完成后加载
|
|
|
|
5. **获取项目**: `GET /api/graph/project/{projectId}`
|
|
- 页面加载时获取
|
|
|
|
## 容错机制
|
|
|
|
### 前端
|
|
- API请求自动重试(最多3次)
|
|
- 指数退避策略(1s -> 2s -> 4s)
|
|
- 超时处理(5分钟)
|
|
- 友好的错误提示
|
|
- 网络错误处理
|
|
|
|
### 后端
|
|
- Zep API调用重试
|
|
- LLM API调用重试
|
|
- 详细的日志记录
|
|
- 异常捕获和处理
|
|
|
|
## 启动步骤
|
|
|
|
### 1. 启动后端
|
|
```bash
|
|
cd /Users/guohangjiang/Desktop/MiroFish/backend
|
|
conda activate MiroFish
|
|
python run.py
|
|
```
|
|
|
|
### 2. 启动前端
|
|
```bash
|
|
cd /Users/guohangjiang/Desktop/MiroFish/frontend
|
|
npm run dev
|
|
```
|
|
|
|
### 3. 访问系统
|
|
- 前端: http://localhost:3000
|
|
- 后端: http://localhost:5001
|
|
|
|
## 技术栈
|
|
|
|
### 后端
|
|
- Flask 3.0+
|
|
- Zep Cloud SDK 2.0+
|
|
- OpenAI SDK 1.0+
|
|
- PyMuPDF (文本提取)
|
|
- Python 3.8+
|
|
|
|
### 前端
|
|
- Vue 3 (Composition API)
|
|
- Vite 7
|
|
- Vue Router 4
|
|
- Axios
|
|
|
|
## 开发环境
|
|
|
|
- **操作系统**: macOS (M系列芯片)
|
|
- **Python环境**: conda环境 MiroFish
|
|
- **Node.js**: >= 16.0.0
|
|
- **浏览器**: Chrome (推荐)
|
|
|
|
## 配置文件
|
|
|
|
### 后端 (.env)
|
|
```bash
|
|
FLASK_PORT=5001
|
|
LLM_API_KEY=your-key
|
|
LLM_BASE_URL=https://api.openai.com/v1
|
|
LLM_MODEL_NAME=gpt-4o-mini
|
|
ZEP_API_KEY=your-key
|
|
```
|
|
|
|
### 前端 (.env.development)
|
|
```bash
|
|
VITE_API_BASE_URL=http://localhost:5001
|
|
```
|
|
|
|
## 已实现的规则
|
|
|
|
✅ **API容错重试机制**: 所有远程API调用都有重试机制
|
|
✅ **RESTful风格**: 后端API采用RESTful设计
|
|
✅ **统一配置**: LLM和Zep密钥统一存储在.env文件
|
|
✅ **OpenAI格式**: LLM调用统一使用OpenAI库格式
|
|
✅ **Conda环境**: 程序运行在MiroFish环境中
|
|
✅ **前后端分离**: Vue前端 + Flask后端
|
|
|
|
## 测试建议
|
|
|
|
### 功能测试
|
|
1. [ ] 文件上传(拖拽、点击)
|
|
2. [ ] 表单验证
|
|
3. [ ] API调用
|
|
4. [ ] 页面跳转
|
|
5. [ ] 错误处理
|
|
6. [ ] 响应式布局
|
|
|
|
### 端到端测试
|
|
1. [ ] 上传PDF文档
|
|
2. [ ] 填写模拟需求
|
|
3. [ ] 提交表单
|
|
4. [ ] 观察处理流程
|
|
5. [ ] 等待图谱构建完成
|
|
|
|
## 后续开发
|
|
|
|
### 优先级高
|
|
- [ ] 图谱可视化实现(D3.js或ECharts)
|
|
- [ ] 模拟运行页面
|
|
- [ ] 结果展示页面
|
|
- [ ] Agent对话功能
|
|
|
|
### 优先级中
|
|
- [ ] 历史记录管理
|
|
- [ ] 项目列表页面
|
|
- [ ] 用户设置
|
|
- [ ] 导出功能
|
|
|
|
### 优先级低
|
|
- [ ] 数据统计分析
|
|
- [ ] 多语言支持
|
|
- [ ] 深色模式
|
|
- [ ] 移动端优化
|
|
|
|
## 项目亮点
|
|
|
|
1. **极简黑白线条风格**: 独特的视觉设计
|
|
2. **全自动化流程**: 用户只需上传文档和需求
|
|
3. **容错机制完善**: 多重重试和错误处理
|
|
4. **前后端分离**: 清晰的架构设计
|
|
5. **实时反馈**: 轮询机制实时更新状态
|
|
6. **响应式设计**: 支持多种设备
|
|
|
|
## 当前状态
|
|
|
|
🟢 **开发服务器运行中**
|
|
- 后端: 需要手动启动
|
|
- 前端: 已启动在 http://localhost:3000
|
|
|
|
✅ **首页功能完整**
|
|
- 文件上传 ✓
|
|
- 表单验证 ✓
|
|
- API调用 ✓
|
|
- 错误处理 ✓
|
|
|
|
⚠️ **待完善功能**
|
|
- 图谱可视化(第二页)
|
|
- 更多页面开发
|
|
- 完整的端到端测试
|
|
|
|
## 总结
|
|
|
|
MiroFish项目的前端脚手架已搭建完成,首页设计符合极简黑白线条风格要求,核心功能已实现:
|
|
|
|
1. ✅ 文件上传(支持拖拽)
|
|
2. ✅ 表单验证和提交
|
|
3. ✅ API接口调用
|
|
4. ✅ 路由管理
|
|
5. ✅ 错误处理
|
|
6. ✅ 响应式设计
|
|
|
|
用户可以通过首页上传文档和填写模拟需求,点击"开始模拟"后系统会调用后端的 `/api/graph/ontology/generate` 接口,成功后跳转到处理页面查看图谱构建进度。
|
|
|
|
---
|
|
|
|
**更新时间**: 2025-12-10
|
|
**版本**: v1.0.0
|
|
**状态**: 开发中 🚧
|