nex_docus/QUICKSTART.md

# NEX Docus 快速启动指南

欢迎使用 NEX Docus！这是一个完整的快速启动指南，帮助你在 5 分钟内运行整个项目。

---

## 📋 前置要求

确保已安装以下软件：

- **Python**: 3.9.6+
- **Node.js**: 16+
- **MySQL**: 5.7.5+
- **Redis**: 最新稳定版
- **Git**: 最新版本

---

## 🚀 快速启动（3 步）

### Step 1: 初始化数据库

```bash
# 1. 连接到 MySQL
mysql -h10.100.51.51 -uroot -pUnis@321

# 2. 执行初始化脚本
source backend/scripts/init_database.sql

# 或使用命令行直接执行
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql
```

### Step 2: 启动后端服务

```bash
# 1. 进入后端目录
cd backend

# 2. 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate     # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动服务
python main.py
```

后端服务将在 http://localhost:8000 启动

### Step 3: 启动前端服务

```bash
# 1. 打开新终端，进入前端目录
cd forntend

# 2. 安装依赖
npm install
# 或
pnpm install

# 3. 启动开发服务器
npm run dev
```

前端应用将在 http://localhost:5173 启动

---

## 🎉 开始使用

### 1. 登录系统

访问 http://localhost:5173，使用默认管理员账号登录：

- **用户名**: `admin`
- **密码**: `admin123`

### 2. 创建项目

- 点击「创建项目」按钮
- 填写项目名称和描述
- 提交创建

### 3. 编辑文档

- 点击项目卡片进入项目
- 在左侧目录树中选择文件
- 在右侧编辑器中编辑 Markdown
- 点击「保存」按钮保存更改

---

## 📚 目录结构

```
NEX Docus/
├── backend/              # 后端服务（FastAPI）
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── models/      # 数据库模型
│   │   ├── schemas/     # Pydantic Schemas
│   │   ├── services/    # 业务逻辑
│   │   └── middleware/  # 中间件
│   ├── scripts/         # 脚本文件
│   ├── main.py          # 应用入口
│   └── requirements.txt # 依赖包
│
├── forntend/            # 前端应用（React + Vite）
│   ├── src/
│   │   ├── api/        # API 请求
│   │   ├── components/ # 通用组件
│   │   ├── pages/      # 页面组件
│   │   ├── stores/     # 状态管理
│   │   └── utils/      # 工具函数
│   ├── package.json
│   └── vite.config.js
│
├── DATABASE.md          # 数据库设计文档
├── IMPLEMENTATION_PLAN.md  # 实施计划
├── PROJECT.md           # 项目技术方案
└── DEPLOYE.md          # 部署配置
```

---

## 🔧 常见问题

### 1. 后端启动失败

**问题**: `ModuleNotFoundError: No module named 'xxx'`

**解决**:
```bash
cd backend
source venv/bin/activate
pip install -r requirements.txt
```

### 2. 数据库连接失败

**问题**: `Can't connect to MySQL server`

**解决**:
- 检查 `backend/.env` 中的数据库配置
- 确认 MySQL 服务已启动
- 测试数据库连接：
  ```bash
  mysql -h10.100.51.51 -uroot -pUnis@321 -e "SELECT 1"
  ```

### 3. 前端请求 404

**问题**: API 请求返回 404

**解决**:
- 确认后端服务已启动
- 检查 `forntend/.env` 中的 API 地址配置
- 检查浏览器控制台的网络请求

### 4. 文件上传/保存失败

**问题**: 文件操作失败

**解决**:
- 确保文件存储目录存在并有写权限：
  ```bash
  mkdir -p /data/nex_docus_store/{projects,temp}
  chmod 755 /data/nex_docus_store
  ```
- 或修改 `backend/.env` 中的存储路径为当前用户有权限的目录

---

## 📖 API 文档

启动后端服务后，访问以下地址查看 API 文档：

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

---

## 🔐 安全提醒

⚠️ **生产环境部署前请务必修改：**

1. 修改默认管理员密码
2. 修改 `backend/.env` 中的 `SECRET_KEY`
3. 配置 HTTPS
4. 限制 CORS 允许的域名
5. 配置防火墙规则

---

## 📞 技术支持

如果遇到问题，请查看：

1. **PROJECT.md** - 完整技术方案
2. **DATABASE.md** - 数据库设计文档
3. **IMPLEMENTATION_PLAN.md** - 实施计划

或联系技术负责人：Mula.liu

---

## ⚡️ 快速命令参考

```bash
# 后端
cd backend && source venv/bin/activate && python main.py

# 前端
cd forntend && npm run dev

# 数据库初始化
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql

# 查看日志
tail -f backend/logs/app.log
```

---

**祝你使用愉快！🎊**