# 海洋项目管理系统 - 后端

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