268 lines
6.0 KiB
Markdown
268 lines
6.0 KiB
Markdown
# NEX Docus 文档管理平台
|
||
|
||
<div align="center">
|
||
|
||
一个轻量级、高性能的团队协作文档管理平台
|
||
|
||
[](LICENSE)
|
||
[](https://www.python.org/)
|
||
[](https://reactjs.org/)
|
||
[](https://fastapi.tiangolo.com/)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## ✨ 特性
|
||
|
||
- 🚀 **高性能**: FastAPI 异步后端 + React 18 前端
|
||
- 📁 **文件存储**: 数据库管理权限 + 文件系统存储内容
|
||
- 🔐 **权限控制**: 完整的 RBAC 权限体系
|
||
- 📝 **Markdown 编辑**: 实时预览、图片上传
|
||
- 👥 **团队协作**: 项目成员管理、角色分配
|
||
- 🌲 **目录树**: 无限层级目录支持
|
||
- 💾 **数据安全**: 文件即真理、易于备份和迁移
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 后端技术栈
|
||
- **框架**: FastAPI (Python 3.9+)
|
||
- **ORM**: SQLAlchemy 2.0 (异步)
|
||
- **数据库**: MySQL 5.7.5+
|
||
- **缓存**: Redis
|
||
- **认证**: JWT (PyJWT)
|
||
- **文件**: aiofiles (异步 I/O)
|
||
|
||
### 前端技术栈
|
||
- **框架**: React 18
|
||
- **构建工具**: Vite
|
||
- **UI 组件**: Ant Design 5
|
||
- **路由**: React Router v6
|
||
- **状态管理**: Zustand
|
||
- **Markdown**: @uiw/react-md-editor
|
||
- **样式**: Tailwind CSS
|
||
|
||
---
|
||
|
||
## 📦 项目结构
|
||
|
||
```
|
||
NEX Docus/
|
||
├── backend/ # FastAPI 后端服务
|
||
│ ├── app/
|
||
│ │ ├── api/v1/ # API 路由（v1）
|
||
│ │ ├── core/ # 核心配置
|
||
│ │ ├── models/ # 数据库模型
|
||
│ │ ├── schemas/ # Pydantic Schemas
|
||
│ │ ├── services/ # 业务逻辑服务
|
||
│ │ └── middleware/ # 中间件
|
||
│ ├── scripts/ # 初始化脚本
|
||
│ └── main.py # 应用入口
|
||
│
|
||
├── forntend/ # React 前端应用
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 封装
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ └── utils/ # 工具函数
|
||
│ └── package.json
|
||
│
|
||
├── DATABASE.md # 数据库设计文档
|
||
├── PROJECT.md # 技术方案文档
|
||
├── QUICKSTART.md # 快速启动指南
|
||
└── IMPLEMENTATION_PLAN.md # 实施计划
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Python 3.9.6+
|
||
- Node.js 16+
|
||
- MySQL 5.7.5+
|
||
- Redis (最新版)
|
||
|
||
### 1. 初始化数据库
|
||
|
||
```bash
|
||
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql
|
||
```
|
||
|
||
### 2. 启动后端
|
||
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python main.py
|
||
```
|
||
|
||
后端将运行在 http://localhost:8000
|
||
|
||
### 3. 启动前端
|
||
|
||
```bash
|
||
cd forntend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
前端将运行在 http://localhost:5173
|
||
|
||
### 4. 登录使用
|
||
|
||
- **用户名**: `admin`
|
||
- **密码**: `admin123`
|
||
|
||
---
|
||
|
||
## 📖 核心功能
|
||
|
||
### 用户认证
|
||
- ✅ 用户注册/登录
|
||
- ✅ JWT Token 认证
|
||
- ✅ 密码加密存储
|
||
- ✅ 权限角色管理
|
||
|
||
### 项目管理
|
||
- ✅ 创建/编辑/删除项目
|
||
- ✅ 项目成员管理
|
||
- ✅ 访问权限控制
|
||
- ✅ 项目归档
|
||
|
||
### 文档编辑
|
||
- ✅ Markdown 实时预览
|
||
- ✅ 无限层级目录
|
||
- ✅ 文件/文件夹操作
|
||
- ✅ 图片/附件上传
|
||
- ✅ 自动保存
|
||
|
||
---
|
||
|
||
## 🗂️ 数据库设计
|
||
|
||
### 核心表结构
|
||
|
||
- `users` - 用户表
|
||
- `roles` - 角色表
|
||
- `user_roles` - 用户角色关联
|
||
- `system_menus` - 系统菜单
|
||
- `role_menus` - 角色菜单授权
|
||
- `projects` - 项目表
|
||
- `project_members` - 项目成员
|
||
- `document_meta` - 文档元数据（可选）
|
||
- `operation_logs` - 操作日志
|
||
|
||
详细设计请查看 [DATABASE.md](DATABASE.md)
|
||
|
||
---
|
||
|
||
## 🔒 安全特性
|
||
|
||
- ✅ **密码加密**: bcrypt 加密存储
|
||
- ✅ **JWT 认证**: 访问令牌机制
|
||
- ✅ **路径安全**: 防止路径穿越攻击
|
||
- ✅ **权限校验**: 基于角色的访问控制
|
||
- ✅ **SQL 注入防护**: ORM 自动防护
|
||
- ✅ **CORS 配置**: 跨域请求控制
|
||
|
||
---
|
||
|
||
## 📋 API 文档
|
||
|
||
启动后端后访问：
|
||
|
||
- **Swagger UI**: http://localhost:8000/docs
|
||
- **ReDoc**: http://localhost:8000/redoc
|
||
|
||
### 主要接口
|
||
|
||
**认证**
|
||
- `POST /api/v1/auth/register` - 注册
|
||
- `POST /api/v1/auth/login` - 登录
|
||
- `GET /api/v1/auth/me` - 获取当前用户
|
||
|
||
**项目**
|
||
- `GET /api/v1/projects/` - 项目列表
|
||
- `POST /api/v1/projects/` - 创建项目
|
||
- `GET /api/v1/projects/{id}` - 项目详情
|
||
- `PUT /api/v1/projects/{id}` - 更新项目
|
||
- `DELETE /api/v1/projects/{id}` - 删除项目
|
||
|
||
**文件**
|
||
- `GET /api/v1/files/{project_id}/tree` - 目录树
|
||
- `GET /api/v1/files/{project_id}/file` - 文件内容
|
||
- `POST /api/v1/files/{project_id}/file` - 保存文件
|
||
- `POST /api/v1/files/{project_id}/upload` - 上传文件
|
||
|
||
---
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 后端开发
|
||
|
||
1. 添加新的数据模型到 `backend/app/models/`
|
||
2. 定义 Pydantic Schema 到 `backend/app/schemas/`
|
||
3. 在 `backend/app/api/v1/` 创建路由
|
||
4. 实现业务逻辑到 `backend/app/services/`
|
||
|
||
### 前端开发
|
||
|
||
1. 在 `forntend/src/api/` 封装 API 请求
|
||
2. 在 `forntend/src/pages/` 创建页面组件
|
||
3. 在 `forntend/src/App.jsx` 添加路由
|
||
4. 使用 Zustand 管理全局状态
|
||
|
||
---
|
||
|
||
## 📝 文档
|
||
|
||
- [技术方案文档](PROJECT.md) - 完整的技术设计方案
|
||
- [数据库设计](DATABASE.md) - 数据库表结构设计
|
||
- [快速启动指南](QUICKSTART.md) - 5分钟快速上手
|
||
- [实施计划](IMPLEMENTATION_PLAN.md) - 分阶段实施计划
|
||
|
||
---
|
||
|
||
## 🔄 版本历史
|
||
|
||
### v1.0.0 (2023-12-20)
|
||
|
||
- ✅ 完整的用户认证系统
|
||
- ✅ 项目管理功能
|
||
- ✅ Markdown 文档编辑
|
||
- ✅ 文件系统管理
|
||
- ✅ 权限控制体系
|
||
- ✅ 团队协作功能
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
Copyright © 2023 Mula.liu
|
||
|
||
---
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下开源项目：
|
||
|
||
- [FastAPI](https://fastapi.tiangolo.com/)
|
||
- [React](https://reactjs.org/)
|
||
- [Ant Design](https://ant.design/)
|
||
- [SQLAlchemy](https://www.sqlalchemy.org/)
|
||
- [Vite](https://vitejs.dev/)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Made with ❤️ by Mula.liu**
|
||
|
||
</div>
|