filesend/README.md

# 文件领取管理系统 (FileSend)

一个现代化的文件管理与领取系统，支持用户注册、文件上传、文件领取、管理员管理等功能。系统采用前后端分离架构，提供完整的文件生命周期管理。

## 🌟 项目亮点

- **现代化架构**: 前后端分离，RESTful API设计
- **权限管理**: 基于角色的访问控制（RBAC）
- **文件安全**: 文件加密存储，访问权限控制
- **用户体验**: 响应式设计，支持移动端
- **扩展性强**: 模块化设计，易于扩展

## 🚀 功能特性

### 用户端功能
- ✅ 用户注册与登录（JWT认证）
- ✅ 查看可领取文件列表
- ✅ 每日文件领取配额管理
- ✅ 文件下载与预览
- ✅ 个人资料管理
- ✅ 分类筛选与搜索
- ✅ 文件领取历史记录

### 管理端功能
- ✅ 用户管理（创建、编辑、删除、激活/停用）
- ✅ 文件上传与管理（支持批量上传）
- ✅ 分类管理（支持层级分类）
- ✅ 权限管理（用户分类权限控制）
- ✅ 文件状态管理（可领取/已领取/过期）
- ✅ 数据统计分析（图表展示）
- ✅ 系统配置管理
- ✅ 操作日志记录

### 系统特性
- 📊 实时数据统计
- 🔒 文件访问权限控制
- 📱 响应式设计
- 🔄 文件状态自动管理
- 📧 邮件通知（可扩展）
- 🗂️ 文件分类管理

## 🛠️ 技术栈

### 后端技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| **Flask** | 2.3.x | Web框架 |
| **SQLAlchemy** | 2.0.x | ORM数据库工具 |
| **Flask-JWT-Extended** | 4.5.x | JWT身份验证 |
| **Flask-CORS** | 4.0.x | 跨域支持 |
| **Flask-Mail** | 0.9.x | 邮件服务 |
| **Werkzeug** | 2.3.x | WSGI工具集 |
| **MySQL** | 8.0+ | 主数据库 |
| **Redis** | 7.0+ | 缓存与会话存储 |

### 前端技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| **React** | 18.2.x | 前端框架 |
| **React Router** | 6.8.x | 路由管理 |
| **Axios** | 1.4.x | HTTP客户端 |
| **Bootstrap** | 5.3.x | UI框架 |
| **React Bootstrap** | 2.8.x | React组件库 |
| **Chart.js** | 4.3.x | 图表库 |
| **React Icons** | 4.10.x | 图标库 |

## 📋 系统要求

### 最低配置
- **操作系统**: Windows 10 / Ubuntu 20.04 / macOS 10.15
- **内存**: 4GB RAM
- **存储**: 10GB 可用空间
- **网络**: 稳定的互联网连接

### 推荐配置
- **操作系统**: Windows 11 / Ubuntu 22.04 / macOS 12+
- **内存**: 8GB RAM
- **存储**: 50GB 可用空间（用于文件存储）
- **网络**: 高速宽带连接

### 软件依赖
- **Python**: 3.8+
- **Node.js**: 16+
- **MySQL**: 8.0+
- **Redis**: 7.0+
- **Git**: 最新版本

## 🚀 快速开始

### 方法一：Docker部署（推荐）

#### 1. 克隆项目
```bash
git clone <repository-url>
cd filesend
```

#### 2. 环境配置
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置文件
nano .env  # 或使用其他编辑器
```

#### 3. Docker部署
```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

#### 4. 初始化数据库
```bash
# 进入后端容器
docker-compose exec backend bash

# 初始化数据库
python -m flask db init
python -m flask db migrate -m "Initial migration"
python -m flask db upgrade

# 创建管理员账户
python -m flask create-admin
```

### 方法二：传统部署

#### 1. 环境准备

**安装Python依赖**
```bash
# 创建虚拟环境
python -m venv venv

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

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

**安装Node.js依赖**
```bash
cd frontend
npm install
```

**安装数据库**
```bash
# MySQL安装（Ubuntu）
sudo apt update
sudo apt install mysql-server

# Redis安装（Ubuntu）
sudo apt install redis-server

# 启动服务
sudo systemctl start mysql
sudo systemctl start redis-server
```

#### 2. 数据库配置

**创建数据库**
```sql
-- 登录MySQL
mysql -u root -p

-- 创建数据库
CREATE DATABASE filesend CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户并授权
CREATE USER 'filesend'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON filesend.* TO 'filesend'@'localhost';
FLUSH PRIVILEGES;
```

**配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env

# 编辑配置文件，设置数据库连接信息
nano .env
```

#### 3. 启动服务

**启动后端服务**
```bash
cd backend

# 初始化数据库
python -m flask db init
python -m flask db migrate -m "Initial migration"
python -m flask db upgrade

# 创建管理员账户
python -m flask create-admin

# 启动开发服务器
python run.py
```

**启动前端服务**
```bash
cd frontend

# 启动开发服务器
npm start

# 或构建生产版本
npm run build
```

## ⚙️ 配置说明

### 环境变量配置

#### 基础配置
```bash
# 应用配置
FLASK_ENV=production
FLASK_DEBUG=False
SECRET_KEY=your-secret-key-here

# 数据库配置
DATABASE_URL=mysql+pymysql://username:password@localhost:3306/filesend
SQLALCHEMY_DATABASE_URI=mysql+pymysql://username:password@localhost:3306/filesend

# Redis配置
REDIS_URL=redis://localhost:6379/0

# 文件存储配置
UPLOAD_FOLDER=backend/app/uploads
MAX_CONTENT_LENGTH=16777216  # 16MB
```

#### 邮件配置（可选）
```bash
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
```

#### JWT配置
```bash
JWT_SECRET_KEY=your-jwt-secret-key
JWT_ACCESS_TOKEN_EXPIRES=3600  # 1小时
JWT_REFRESH_TOKEN_EXPIRES=86400  # 24小时
```

### Nginx配置（生产环境）

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/filesend/frontend/build;
        index index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    # API代理
    location /api/ {
        proxy_pass http://127.0.0.1:5000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 文件上传
    client_max_body_size 50M;
}
```

## 📊 数据库初始化

### 创建管理员账户
```bash
# 使用Flask命令创建管理员
python -m flask create-admin

# 按提示输入管理员信息
# 用户名: admin
# 邮箱: admin@example.com
# 密码: (设置安全密码)
```

### 初始化分类数据
```bash
# 运行初始化脚本
python -m flask init-categories

# 或手动添加分类
python -m flask shell
>>> from app.models import Category
>>> category = Category(name="文档", description="各类文档文件")
>>> category.save()
```

## 🔧 开发指南

### 项目结构
```
filesend/
├── backend/                    # 后端代码
│   ├── app/
│   │   ├── __init__.py        # 应用初始化
│   │   ├── models.py          # 数据模型
│   │   ├── routes/            # API路由
│   │   │   ├── auth.py        # 认证相关
│   │   │   ├── admin.py       # 管理端API
│   │   │   ├── user.py        # 用户端API
│   │   │   └── files.py       # 文件相关API
│   │   └── uploads/           # 文件存储目录
│   ├── requirements.txt       # Python依赖
│   └── run.py                # 启动脚本
├── frontend/                  # 前端代码
│   ├── src/
│   │   ├── components/        # 通用组件
│   │   ├── pages/            # 页面组件
│   │   ├── services/         # API服务
│   │   └── utils/            # 工具函数
│   ├── package.json          # Node.js依赖
│   └── nginx.conf            # Nginx配置
├── config/                   # 配置文件
├── logs/                     # 日志文件
└── docker-compose.yml        # Docker配置
```

### 开发环境设置

#### 后端开发
```bash
# 安装开发依赖
pip install -r requirements.txt
pip install pytest pytest-cov black flake8

# 代码格式化
black .

# 代码检查
flake8 .

# 运行测试
pytest
```

#### 前端开发
```bash
# 安装开发依赖
npm install
npm install --save-dev @testing-library/react

# 启动开发服务器
npm start

# 运行测试
npm test

# 构建生产版本
npm run build
```

## 📚 API文档

### 认证相关
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/logout` - 用户登出
- `POST /api/auth/refresh` - 刷新令牌

### 文件管理
- `GET /api/files` - 获取文件列表
- `POST /api/files/upload` - 上传文件
- `GET /api/files/<id>` - 获取文件详情
- `PUT /api/files/<id>` - 更新文件信息
- `DELETE /api/files/<id>` - 删除文件
- `POST /api/files/<id>/claim` - 领取文件

### 用户管理
- `GET /api/users` - 获取用户列表（管理员）
- `POST /api/users` - 创建用户（管理员）
- `PUT /api/users/<id>` - 更新用户信息
- `DELETE /api/users/<id>` - 删除用户

### 分类管理
- `GET /api/categories` - 获取分类列表
- `POST /api/categories` - 创建分类
- `PUT /api/categories/<id>` - 更新分类
- `DELETE /api/categories/<id>` - 删除分类

## 🐛 常见问题

### 安装问题

#### Python版本不兼容
```bash
# 检查Python版本
python --version

# 如果版本过低，使用pyenv安装新版本
pyenv install 3.10.0
pyenv global 3.10.0
```

#### MySQL连接失败
```bash
# 检查MySQL服务状态
sudo systemctl status mysql

# 重启MySQL服务
sudo systemctl restart mysql

# 检查防火墙设置
sudo ufw status
```

#### Redis连接失败
```bash
# 检查Redis服务状态
sudo systemctl status redis

# 重启Redis服务
sudo systemctl restart redis

# 测试Redis连接
redis-cli ping
```

### 运行问题

#### 端口占用
```bash
# 检查端口占用
sudo netstat -tulpn | grep :5000
sudo netstat -tulpn | grep :3000

# 终止占用进程
sudo kill -9 <PID>
```

#### 文件上传失败
```bash
# 检查上传目录权限
ls -la backend/app/uploads/
chmod 755 backend/app/uploads/

# 检查文件大小限制
# 修改backend/config.py中的MAX_CONTENT_LENGTH
```

#### 跨域问题
```bash
# 检查CORS配置
# 确保backend/app/__init__.py中已配置CORS
from flask_cors import CORS
CORS(app)
```

### 性能优化

#### 数据库优化
```sql
-- 添加索引
CREATE INDEX idx_files_status ON files(status);
CREATE INDEX idx_files_category ON files(category_id);
CREATE INDEX idx_files_created ON files(created_at);

-- 优化查询
EXPLAIN SELECT * FROM files WHERE status = 'available';
```

#### 缓存配置
```python
# 在backend/config.py中添加缓存配置
CACHE_TYPE = 'redis'
CACHE_REDIS_URL = 'redis://localhost:6379/0'
CACHE_DEFAULT_TIMEOUT = 300
```

## 🔍 监控与日志

### 日志配置
```python
# backend/config.py
import logging
from logging.handlers import RotatingFileHandler

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s %(levelname)s %(name)s %(message)s',
    handlers=[
        RotatingFileHandler('logs/filesend.log', maxBytes=10485760, backupCount=5),
        logging.StreamHandler()
    ]
)
```

### 健康检查
```bash
# 创建健康检查脚本
#!/bin/bash
# health_check.sh

# 检查后端服务
curl -f http://localhost:5000/api/health || exit 1

# 检查数据库
mysql -u filesend -p -e "SELECT 1" filesend || exit 1

# 检查Redis
redis-cli ping || exit 1

echo "All services are healthy"
```

## 📞 技术支持

### 联系方式
- **邮箱**: support@filesend.com
- **文档**: [官方文档](https://docs.filesend.com)
- **社区**: [GitHub Issues](https://github.com/your-repo/filesend/issues)

### 更新日志
查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。

## 🤝 贡献指南

### 如何贡献
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范
- 使用 [Black](https://black.readthedocs.io/) 格式化Python代码
- 使用 [ESLint](https://eslint.org/) 检查JavaScript代码
- 遵循 [PEP 8](https://pep8.org/) Python编码规范
- 遵循 [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Flask](https://flask.palletsprojects.com/) - 优秀的Python Web框架
- [React](https://react.dev/) - 现代前端框架
- [Bootstrap](https://getbootstrap.com/) - 响应式UI框架
- [MySQL](https://www.mysql.com/) - 可靠的关系型数据库
- [Redis](https://redis.io/) - 高性能缓存数据库

---

**Made with ❤️ by the FileSend Team**