Refactor code structure for improved readability and maintainability

2026-05-14 18:09:15 +08:00
parent 10d04c4083
commit 35cd927d02
105 changed files with 9043 additions and 7720 deletions
--- a/QUICK_DEPLOY.md
+++ b/QUICK_DEPLOY.md
@@ -71,11 +71,11 @@ docker ps

 ## 三、安装Python依赖

-### 方式A：使用快速启动脚本（推荐）
+### 方式A：使用统一初始化脚本（推荐）

 ```bash
-chmod +x quick_start.sh
-./quick_start.sh
+chmod +x dev.sh
+./dev.sh setup
 ```

 脚本自动完成：
@@ -91,7 +91,7 @@ python3 -m venv .venv
 source .venv/bin/activate

 # 安装依赖
-pip install -r requirements.txt
+pip install -r backend/requirements.txt
 ```

 ---
@@ -115,39 +115,42 @@ python -c "from modelscope import snapshot_download; snapshot_download('Xorbits/

 ## 五、启动服务

-### 整合启动脚本（推荐）
+### 统一命令入口（推荐）

 ```bash
 # 赋予脚本执行权限
-chmod +x start_all.sh stop_all.sh restart_all.sh status.sh
+chmod +x dev.sh

 # 启动所有服务（API + 前端）
-./start_all.sh
+./dev.sh start

 # 查看服务状态
-./status.sh
+./dev.sh status

 # 重启所有服务
-./restart_all.sh
+./dev.sh restart

 # 停止所有服务
-./stop_all.sh
+./dev.sh stop
 ```

 ### 单独启动（可选）

 ```bash
 # 仅启动API服务（前台运行，可调试）
-./start_api.sh
+./dev.sh start api --foreground

 # 仅启动API服务（后台运行）
-./start_api_background.sh
+./dev.sh start api

 # 仅停止API服务
-./stop_api.sh
+./dev.sh stop api

-# 仅启动前端服务
-./start_frontend.sh
+# 仅启动前端服务（Vite 开发模式）
+./dev.sh start frontend --mode dev
+
+# 仅启动前端服务（静态构建模式）
+./dev.sh start frontend --mode static
 ```

 ---
@@ -161,9 +164,9 @@ chmod +x start_all.sh stop_all.sh restart_all.sh status.sh
 | **API服务** | http://localhost:8000 |
 | **API文档** | http://localhost:8000/docs |
 | **健康检查** | http://localhost:8000/health |
-| **前端测试页面** | http://localhost:3000 |
+| **前端测试页面** | http://localhost:5173 |

-> 注意：前端测试页面通过 `http://localhost:3000` 访问，自动连接到API服务。
+> 注意：前端默认通过 `http://localhost:5173` 访问，自动代理到 API 服务。

 ---

@@ -221,24 +224,46 @@ curl -X POST http://localhost:8000/api/v1/agent/chat \

 | 操作 | 命令 |
 |------|------|
-| **启动所有服务** | `./start_all.sh` |
-| **停止所有服务** | `./stop_all.sh` |
-| **重启所有服务** | `./restart_all.sh` |
-| **查看服务状态** | `./status.sh` |
+| **启动所有服务** | `./dev.sh start` |
+| **停止所有服务** | `./dev.sh stop` |
+| **重启所有服务** | `./dev.sh restart` |
+| **查看服务状态** | `./dev.sh status` |
 | 查看API日志 | `tail -f logs/api.log` |
 | 查看前端日志 | `tail -f logs/frontend.log` |
-| 环境初始化 | `./quick_start.sh` |
+| 环境初始化 | `./dev.sh setup` |
+| 前台调试 API | `./dev.sh start api --foreground` |
+| 静态模式启动前端 | `./dev.sh start frontend --mode static` |
 | 重启Docker | `cd docker && docker-compose restart` |
 | 下载嵌入模型 | `./download_model.sh` |

 ---

-## 九、服务状态检查
+## 九、Linux / Windows 命令对照表
+
+| 操作 | Linux / macOS | Windows |
+|------|---------------|---------|
+| 环境初始化 | `./dev.sh setup` | `dev.bat setup` |
+| 启动所有服务 | `./dev.sh start` | `dev.bat start` |
+| 停止所有服务 | `./dev.sh stop` | `dev.bat stop` |
+| 重启所有服务 | `./dev.sh restart` | `dev.bat restart` |
+| 查看服务状态 | `./dev.sh status` | `dev.bat status` |
+| 前台调试 API | `./dev.sh start api --foreground` | `dev.bat start api --foreground` |
+| 后台启动 API | `./dev.sh start api` | `dev.bat start api` |
+| 启动前端开发模式 | `./dev.sh start frontend --mode dev` | `dev.bat start frontend --mode dev` |
+| 启动前端静态模式 | `./dev.sh start frontend --mode static` | `dev.bat start frontend --mode static` |
+| 查看 API 日志 | `./dev.sh logs api --follow` | `dev.bat logs api --follow` |
+| 查看前端日志 | `./dev.sh logs frontend --follow` | `dev.bat logs frontend --follow` |
+
+> Linux / macOS 首次使用前建议先执行：`chmod +x dev.sh`
+
+---
+
+## 十、服务状态检查

 运行状态检查脚本：

 ```bash
-./status.sh
+./dev.sh status
 ```

 输出示例：
@@ -256,7 +281,7 @@ API服务:
 前端服务:
  状态:   运行中 ✓
  PID:    12346
-  地址:    http://localhost:3000
+  地址:    http://localhost:5173

 Docker服务:
  milvus:  运行中 ✓
@@ -271,7 +296,7 @@ Docker服务:

 ---

-## 十、常见问题
+## 十一、常见问题

 ### Q1: Milvus连接失败

@@ -334,49 +359,30 @@ rm -f logs/*.pid

 ---

-## 十一、目录结构
+## 十二、目录结构

-```
+```text
 Demo-glm/
-├── src/
-│   ├── api/              # FastAPI接口
-│   │   ├── main.py       # API入口
-│   │   └── routes/
-│   │       ├── documents.py    # 文档上传
-│   │       ├── knowledge.py    # 知识检索
-│   │       └── agent.py        # 智能问答
-│   ├── services/         # 核心服务
-│   │   ├── llm/          # LLM调用（Qwen/DeepSeek）
-│   │   ├── rag/          # RAG检索
-│   │   ├── agent/        # 问答Agent
-│   │   ├── parser/       # 文档解析
-│   │   ├── embedding/    # 向量嵌入（BGE-M3）
-│   │   └── storage/      # Milvus存储
-│   └── config/           # 配置管理
-├── frontend/             # 前端测试页面
-│   └── index.html        # 测试界面
-├── docker/               # Docker配置
+├── backend/
+│   ├── app/              # FastAPI 后端代码
+│   ├── requirements.txt  # Python 依赖
+│   └── main.py           # 后端启动入口
+├── frontend/             # Vite React 前端
+├── docker/               # Docker 配置
 │   └── docker-compose.yml
 ├── logs/                 # 运行日志
-│   ├── api.log
-│   └── frontend.log
-├── tests/                # 测试脚本
+├── tests/                # 根级测试脚本
 ├── .env                  # 环境配置
 ├── .env.example          # 配置模板
-├── requirements.txt      # Python依赖
-├── quick_start.sh        # 环境初始化脚本
-├── start_all.sh          # 整合启动脚本
-├── stop_all.sh           # 整合停止脚本
-├── restart_all.sh        # 重启脚本
-├── status.sh             # 状态检查脚本
-├── start_api.sh          # 单独启动API
-├── start_frontend.sh     # 单独启动前端
+├── pyproject.toml        # 根级 Python 项目配置
+├── dev.sh                # Linux/macOS 统一入口
+├── dev.bat               # Windows 统一入口
 └── QUICK_DEPLOY.md       # 本文档
 ```

 ---

-## 十二、API接口清单
+## 十三、API接口清单

 | 接口 | 路径 | 方法 | 功能 |
 |------|------|------|------|
@@ -419,4 +425,4 @@ Demo-glm/
 ## 技术支持

 - API文档：http://localhost:8000/docs
- 问题反馈：提交Issue到项目仓库
+- 问题反馈：提交Issue到项目仓库