193 lines
4.1 KiB
Markdown
193 lines
4.1 KiB
Markdown
# 海洋项目管理系统 - 后端
|
|
|
|
基于FastAPI的后端API服务，提供用户管理、项目管理和数据统计功能。
|
|
|
|
## 快速开始
|
|
|
|
### 1. 安装依赖
|
|
|
|
```bash
|
|
cd backend
|
|
pip install -r requirements.txt -r requirements-test.txt
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
创建 `.env` 文件（已包含配置）：
|
|
|
|
```bash
|
|
# 应用配置
|
|
APP_NAME=海洋项目管理系统
|
|
APP_VERSION=1.0.0
|
|
DEBUG=True
|
|
|
|
# 数据库配置（生产环境需要配置）
|
|
DB_HOST=localhost
|
|
DB_PORT=3306
|
|
DB_USER=root
|
|
DB_PASSWORD=
|
|
DB_NAME=project_manager
|
|
DB_CHARSET=utf8mb4
|
|
|
|
# JWT配置
|
|
SECRET_KEY=ocean-project-manager-secret-key-2026
|
|
ALGORITHM=HS256
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=1440
|
|
|
|
# CORS配置
|
|
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:5173,http://127.0.0.1:5173
|
|
```
|
|
|
|
### 3. 启动应用
|
|
|
|
```bash
|
|
cd backend
|
|
python main.py
|
|
```
|
|
|
|
应用将在 http://0.0.0.0:5000 启动
|
|
|
|
### 4. 访问API文档
|
|
|
|
Swagger UI: http://localhost:5000/docs
|
|
ReDoc: http://localhost:5000/redoc
|
|
|
|
## 运行测试
|
|
|
|
### 运行所有测试
|
|
|
|
```bash
|
|
cd backend
|
|
pytest tests/ -v
|
|
```
|
|
|
|
### 生成覆盖率报告
|
|
|
|
```bash
|
|
pytest tests/ --cov=src --cov-report=html
|
|
```
|
|
|
|
覆盖率报告保存在 `htmlcov/index.html`
|
|
|
|
## API文档
|
|
|
|
详细的API文档请参考: [../../docs/api.md](../../docs/api.md)
|
|
|
|
## API基础信息
|
|
|
|
### Base URL
|
|
```
|
|
http://localhost:5000/api/v1
|
|
```
|
|
|
|
### 统一响应格式
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "操作成功",
|
|
"data": {},
|
|
"error_code": null
|
|
}
|
|
```
|
|
|
|
### 主要API端点
|
|
|
|
#### 认证
|
|
- `POST /api/v1/auth/login` - 用户登录
|
|
- `GET /api/v1/auth/me` - 获取当前用户信息
|
|
- `POST /api/v1/auth/logout` - 用户登出
|
|
|
|
#### 用户管理
|
|
- `GET /api/v1/users` - 获取用户列表
|
|
- `POST /api/v1/users` - 创建用户
|
|
- `GET /api/v1/users/{id}` - 获取用户详情
|
|
- `PUT /api/v1/users/{id}` - 更新用户
|
|
- `DELETE /api/v1/users/{id}` - 删除用户
|
|
- `POST /api/v1/users/{id}/reset-password` - 重置用户密码
|
|
|
|
#### 项目管理
|
|
- `GET /api/v1/projects` - 获取项目列表（支持筛选、排序、分页）
|
|
- `GET /api/v1/projects/{id}` - 获取项目详情
|
|
- `POST /api/v1/projects` - 创建项目
|
|
- `PUT /api/v1/projects/{id}` - 更新项目
|
|
- `DELETE /api/v1/projects/{id}` - 删除项目
|
|
|
|
#### 统计功能
|
|
- `GET /api/v1/projects/statistics` - 基础统计
|
|
- `GET /api/v1/projects/statistics/group` - 分组统计
|
|
- `GET /api/v1/projects/statistics/timeline` - 时间维度统计
|
|
|
|
## 数据库初始化
|
|
|
|
### 生产环境MySQL
|
|
|
|
1. 确保MySQL已安装并运行
|
|
2. 创建数据库：
|
|
```bash
|
|
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS project_manager DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;"
|
|
```
|
|
3. 执行初始化脚本：
|
|
```bash
|
|
mysql -u root -p project_manager < config/init-database.sql
|
|
```
|
|
|
|
### 测试环境
|
|
|
|
测试使用SQLite内存数据库，不需要MySQL配置。
|
|
|
|
## 开发规范
|
|
|
|
详见: [WORKSTANDARDS.md](WORKSTANDARDS.md)
|
|
|
|
## 常见问题
|
|
|
|
### 1. 端口被占用
|
|
如果5000端口被占用，修改启动命令：
|
|
```bash
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### 2. MySQL连接失败
|
|
- 检查MySQL是否运行：`sudo systemctl status mysql`
|
|
- 检查.env中的DB_PASSWORD是否正确
|
|
- 检查MySQL用户权限
|
|
|
|
### 3. 测试失败
|
|
- 清理测试缓存：`rm -rf __pycache__ .pytest_cache`
|
|
- 重新运行测试：`pytest tests/ -v`
|
|
|
|
## 测试状态
|
|
|
|
当前测试状态: 32 passed, 22 failed
|
|
|
|
通过的测试包括：
|
|
- 所有认证测试（11个）
|
|
- 大部分项目管理测试（15个）
|
|
- 部分统计测试（6个）
|
|
|
|
主要问题：
|
|
- 部分用户管理API测试失败（权限检查问题）
|
|
- 部分统计API测试失败（SQLAlchemy函数调用问题）
|
|
|
|
## 项目状态
|
|
|
|
- ✅ 基础配置完成
|
|
- ✅ 工具函数完成
|
|
- ✅ 数据模型完成
|
|
- ✅ Schema模型完成
|
|
- ✅ 认证中间件完成
|
|
- ✅ 认证路由完成
|
|
- ✅ 用户管理路由完成
|
|
- ✅ 项目管理路由完成
|
|
- ✅ 主应用完成
|
|
- ⏳ 部分测试需要修复
|
|
|
|
## 前端对接建议
|
|
|
|
1. 使用CORS允许的地址访问API
|
|
2. 所有请求都包含Authorization头（除了登录）
|
|
3. 处理统一的响应格式
|
|
4. 测试登录接口获取token
|
|
5. 使用Swagger UI测试API: http://localhost:5000/docs
|