diff --git a/backend/.coverage b/backend/.coverage index 50c587e4..fe63f52c 100644 Binary files a/backend/.coverage and b/backend/.coverage differ diff --git a/backend/README.md b/backend/README.md index 1d5d947c..330fe8c3 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,37 +1,192 @@ -# 后端开发目录 +# 海洋项目管理系统 - 后端 -## 目录说明 +基于FastAPI的后端API服务,提供用户管理、项目管理和数据统计功能。 -### src/ -源代码目录,包含所有后端业务逻辑代码。 +## 快速开始 -#### controllers/ -控制器层,处理HTTP请求和响应。 +### 1. 安装依赖 -#### services/ -服务层,实现业务逻辑。 +```bash +cd backend +pip install -r requirements.txt -r requirements-test.txt +``` -#### models/ -数据模型,定义数据库表结构。 +### 2. 配置环境变量 -#### routes/ -路由定义,配置API端点。 +创建 `.env` 文件(已包含配置): -#### middleware/ -中间件,处理认证、日志等横切关注点。 +```bash +# 应用配置 +APP_NAME=海洋项目管理系统 +APP_VERSION=1.0.0 +DEBUG=True -#### utils/ -工具函数,提供通用功能。 +# 数据库配置(生产环境需要配置) +DB_HOST=localhost +DB_PORT=3306 +DB_USER=root +DB_PASSWORD= +DB_NAME=project_manager +DB_CHARSET=utf8mb4 -### tests/ -测试目录,包含单元测试和集成测试。 +# JWT配置 +SECRET_KEY=ocean-project-manager-secret-key-2026 +ALGORITHM=HS256 +ACCESS_TOKEN_EXPIRE_MINUTES=1440 -### docs/ -文档目录,包含API文档和技术文档。 +# CORS配置 +CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:5173,http://127.0.0.1:5173 +``` -### config/ -配置目录,包含数据库配置、环境变量等。 +### 3. 启动应用 -## 工作规范 +```bash +cd backend +python main.py +``` -详见 [WORKSTANDARDS.md](WORKSTANDARDS.md) +应用将在 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 diff --git a/backend/__pycache__/main.cpython-310.pyc b/backend/__pycache__/main.cpython-310.pyc index 2a3a16d6..ce85d190 100644 Binary files a/backend/__pycache__/main.cpython-310.pyc and b/backend/__pycache__/main.cpython-310.pyc differ diff --git a/backend/main.py b/backend/main.py index 9c25bff4..3073fbbe 100644 --- a/backend/main.py +++ b/backend/main.py @@ -77,7 +77,8 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE @app.on_event("startup") async def startup_event(): - await init_db() + # await init_db() # 注释掉,MySQL需要配置后再启用 + pass @app.get("/")