# NEX Docus Backend

NEX Docus 后端服务 - 基于 FastAPI 构建的高性能文档管理平台。

## 技术栈

- **框架**: FastAPI 0.109+
- **数据库**: MySQL 5.7.5+ (通过 SQLAlchemy 2.0 异步 ORM)
- **缓存**: Redis
- **认证**: JWT (python-jose)
- **密码加密**: bcrypt (passlib)
- **文件处理**: aiofiles (异步文件 I/O)

## 项目结构

```
backend/
├── app/
│   ├── api/
│   │   └── v1/          # API 路由（v1 版本）
│   │       ├── auth.py      # 用户认证
│   │       ├── projects.py  # 项目管理
│   │       └── files.py     # 文件系统
│   ├── core/            # 核心配置
│   │   ├── config.py        # 应用配置
│   │   ├── database.py      # 数据库连接
│   │   ├── security.py      # 安全工具
│   │   └── deps.py          # 依赖注入
│   ├── models/          # 数据库模型
│   ├── schemas/         # Pydantic Schemas
│   ├── services/        # 业务逻辑
│   ├── middleware/      # 中间件
│   └── utils/           # 工具函数
├── scripts/             # 脚本文件
│   ├── init_database.sql    # 数据库初始化 SQL
│   └── init_db.py           # 数据库初始化 Python 脚本
├── tests/               # 测试文件
├── main.py              # 应用入口
├── requirements.txt     # 依赖包
└── .env                 # 环境配置

```

## 快速开始

### 1. 安装依赖

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

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

### 2. 配置环境变量

编辑 `.env` 文件，配置数据库连接等信息。

### 3. 初始化数据库

```bash
# 方式一：使用 SQL 脚本（推荐）
mysql -h10.100.51.51 -uroot -pUnis@321 < scripts/init_database.sql

# 方式二：使用 Python 脚本（仅创建表结构）
python scripts/init_db.py
```

### 4. 启动服务

```bash
# 开发模式（自动重载）
python main.py

# 或使用 uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

服务启动后，访问：
- API 文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

## API 接口

### 认证相关 (`/api/v1/auth`)

- `POST /register` - 用户注册
- `POST /login` - 用户登录
- `GET /me` - 获取当前用户信息
- `POST /change-password` - 修改密码

### 项目管理 (`/api/v1/projects`)

- `GET /` - 获取我的项目列表
- `POST /` - 创建新项目
- `GET /{project_id}` - 获取项目详情
- `PUT /{project_id}` - 更新项目信息
- `DELETE /{project_id}` - 删除项目（归档）
- `GET /{project_id}/members` - 获取项目成员
- `POST /{project_id}/members` - 添加项目成员

### 文件系统 (`/api/v1/files`)

- `GET /{project_id}/tree` - 获取项目目录树
- `GET /{project_id}/file?path=xxx` - 获取文件内容
- `POST /{project_id}/file` - 保存文件内容
- `POST /{project_id}/file/operate` - 文件操作（重命名/删除/创建）
- `POST /{project_id}/upload` - 上传文件（图片/附件）
- `GET /{project_id}/assets/{subfolder}/{filename}` - 获取资源文件

## 默认账号

初始化数据库后，会创建默认管理员账号：

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

**⚠️ 生产环境请立即修改默认密码！**

## 开发指南

### 代码风格

遵循 PEP 8 代码规范。

### 添加新的 API 端点

1. 在 `app/api/v1/` 下创建新的路由文件
2. 在 `app/api/v1/__init__.py` 中注册路由
3. 在 `app/schemas/` 中定义 Pydantic Schema
4. 在 `app/services/` 中实现业务逻辑

### 数据库迁移

使用 Alembic 进行数据库迁移：

```bash
# 生成迁移脚本
alembic revision --autogenerate -m "描述"

# 执行迁移
alembic upgrade head
```

## 安全说明

1. **路径安全**: 所有文件系统操作都经过路径安全检查，防止路径穿越攻击
2. **认证鉴权**: 使用 JWT Token 认证，所有需要登录的接口都受保护
3. **权限控制**: 实现了项目级别的权限控制（owner/admin/editor/viewer）
4. **密码加密**: 使用 bcrypt 加密存储密码
5. **SQL 注入**: 使用 SQLAlchemy ORM，自动防止 SQL 注入

## 许可证

Copyright © 2023 Mula.liu