ocean_project_manager/backend

海洋项目管理系统 - 后端

基于FastAPI的后端API服务，提供用户管理、项目管理和数据统计功能。

快速开始

1. 安装依赖

cd backend
pip install -r requirements.txt -r requirements-test.txt

2. 配置环境变量

创建 .env 文件（已包含配置）：

# 应用配置
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. 启动应用

cd backend
python main.py

应用将在 http://0.0.0.0:8188 启动

4. 访问API文档

Swagger UI: http://localhost:8188/docs ReDoc: http://localhost:5000/redoc

运行测试

运行所有测试

cd backend
pytest tests/ -v

生成覆盖率报告

pytest tests/ --cov=src --cov-report=html

覆盖率报告保存在 htmlcov/index.html

API文档

详细的API文档请参考: ../../docs/api.md

API基础信息

Base URL

http://localhost:5000/api/v1

统一响应格式

{
  "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. 创建数据库：

mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS project_manager DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;"

3. 执行初始化脚本：

mysql -u root -p project_manager < config/init-database.sql

测试环境

测试使用SQLite内存数据库，不需要MySQL配置。

开发规范

详见: WORKSTANDARDS.md

常见问题

1. 端口被占用

如果5000端口被占用，修改启动命令：

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