xsl/ocean_project_manager

Fork 0

Files

T

xsl 93a3e8565e [backend] docs: 更新README中的端口为8188

2026-01-26 15:25:20 +08:00

4.1 KiB

Raw Blame History

海洋项目管理系统 - 后端

基于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

确保MySQL已安装并运行
创建数据库：

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

执行初始化脚本：

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模型完成
✅ 认证中间件完成
✅ 认证路由完成
✅ 用户管理路由完成
✅ 项目管理路由完成
✅ 主应用完成
⏳ 部分测试需要修复

前端对接建议

使用CORS允许的地址访问API
所有请求都包含Authorization头（除了登录）
处理统一的响应格式
测试登录接口获取token
使用Swagger UI测试API: http://localhost:5000/docs

4.1 KiB Raw Blame History