NEX Docus 文档管理平台

一个轻量级、高性能的团队协作文档管理平台

---

✨ 特性

• 🚀 高性能: 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          # 应用入口
│
├── frontend/            # 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. 初始化数据库

mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql

2. 启动后端

cd backend
source venv/bin/activate
pip install -r requirements.txt
python main.py

后端将运行在 http://localhost:8000

3. 启动前端

cd frontend
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

---

🔒 安全特性

• ✅ 密码加密: 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. 在 frontend/src/api/ 封装 API 请求
2. 在 frontend/src/pages/ 创建页面组件
3. 在 frontend/src/App.jsx 添加路由
4. 使用 Zustand 管理全局状态

---

📝 文档

• 技术方案文档 - 完整的技术设计方案
• 数据库设计 - 数据库表结构设计
• 快速启动指南 - 5分钟快速上手
• 实施计划 - 分阶段实施计划

---

🔄 版本历史

v1.0.0 (2023-12-20)

• ✅ 完整的用户认证系统
• ✅ 项目管理功能
• ✅ Markdown 文档编辑
• ✅ 文件系统管理
• ✅ 权限控制体系
• ✅ 团队协作功能

---

📄 许可证

Copyright © 2023 Mula.liu

---

🙏 致谢

感谢以下开源项目：

• FastAPI
• React
• Ant Design
• SQLAlchemy
• Vite

---

Made with ❤️ by Mula.liu