# 海洋项目管理系统 - 后端架构设计

## 1. 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| Web框架 | FastAPI | 高性能异步框架，自动生成API文档 |
| ORM | SQLAlchemy 2.0 | 类型安全的ORM，支持异步 |
| 数据库 | MySQL 8.0 | 关系型数据库 |
| 认证 | JWT (PyJWT) | 无状态认证 |
| 密码加密 | bcrypt | 密码哈希存储 |
| 数据验证 | Pydantic v2 | 请求/响应数据验证 |
| API文档 | FastAPI自动生成 + OpenAPI 3.1 | Swagger UI |

## 2. 系统架构

```
┌─────────────────────────────────────────┐
│         前端 (React + Ant Design)       │
└─────────────────────────────────────────┘
                    │
                    │ HTTP/HTTPS + JWT
                    ▼
┌─────────────────────────────────────────┐
│           FastAPI 应用层                │
│  ┌─────────────────────────────────┐   │
│  │   Routes (API端点)              │   │
│  ├─────────────────────────────────┤   │
│  │   Controllers (业务逻辑)         │   │
│  ├─────────────────────────────────┤   │
│  │   Services (复杂业务逻辑)       │   │
│  ├─────────────────────────────────┤   │
│  │   Models (数据模型)             │   │
│  ├─────────────────────────────────┤   │
│  │   Middleware (认证/日志/错误)   │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
                    │
                    │ SQLAlchemy ORM
                    ▼
┌─────────────────────────────────────────┐
│         MySQL 数据库                     │
│  - users (用户表)                        │
│  - projects (项目表, 60+字段)           │
└─────────────────────────────────────────┘
```

## 3. 项目目录结构

```
backend/
├── src/
│   ├── controllers/          # 控制器层
│   │   ├── auth.py
│   │   ├── users.py
│   │   └── projects.py
│   ├── services/            # 业务逻辑层
│   │   ├── auth_service.py
│   │   ├── user_service.py
│   │   └── project_service.py
│   ├── models/              # 数据模型
│   │   ├── user.py
│   │   └── project.py
│   ├── routes/              # 路由定义
│   │   ├── auth.py
│   │   ├── users.py
│   │   └── projects.py
│   ├── middleware/          # 中间件
│   │   ├── auth.py
│   │   └── logging.py
│   ├── schemas/             # Pydantic模型
│   │   ├── user.py
│   │   └── project.py
│   ├── utils/               # 工具函数
│   │   ├── password.py
│   │   └── jwt.py
│   └── dependencies.py      # 依赖注入
├── tests/                   # 测试目录
│   ├── test_auth.py
│   ├── test_users.py
│   └── test_projects.py
├── config/                  # 配置文件
│   ├── __init__.py
│   ├── database.py          # 数据库配置
│   └── settings.py          # 应用配置
├── requirements.txt         # Python依赖
├── main.py                 # FastAPI应用入口
└── README.md
```

## 4. 核心功能模块

### 4.1 认证授权模块
- JWT Token生成和验证
- 密码加密（bcrypt）
- 基于角色的权限控制（RBAC）
- Token自动刷新机制

### 4.2 用户管理模块
- 用户CRUD操作
- 用户列表查询（支持分页、筛选）
- 密码重置功能（仅管理员）

### 4.3 项目管理模块
- 项目CRUD操作
- 项目列表查询（支持复杂条件筛选）
- 项目统计功能（基础统计、分组统计、时间维度统计）
- Excel数据导入（通过脚本导入，非API）

## 5. 数据库设计

### 5.1 用户表 (users)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| password_hash | VARCHAR(255) | NOT NULL | 密码哈希 |
| real_name | VARCHAR(100) | NOT NULL | 真实姓名 |
| department | VARCHAR(50) | NOT NULL | 部门 |
| role | ENUM | NOT NULL | 角色（admin/market/other） |
| email | VARCHAR(100) | UNIQUE | 邮箱 |
| phone | VARCHAR(20) | | 电话 |
| is_active | BOOLEAN | DEFAULT TRUE | 是否激活 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |

### 5.2 项目表 (projects)

基于`docs/database-design.md`，保持单表设计，包含60+个字段：
- 基础信息：project_no, name, engineering_type, signing_date等
- 成本信息：total_cost_control, labor_cost_control, material_cost_control等
- 财务信息：contract_amount, actual_receipt_amount, actual_payment_amount等
- 质保信息：warranty_amount, warranty_expiry_date等
- 结算信息：settlement_amount, cost_settlement_amount等

**注意**：不使用status字段，数据是什么就是什么。

## 6. API设计规范

### 6.1 基础规范
- Base URL: `/api/v1`
- Content-Type: `application/json`
- 认证方式: JWT Token (Header: `Authorization: Bearer <token>`)
- 统一响应格式:
```json
{
  "success": true,
  "message": "操作成功",
  "data": {},
  "error_code": null
}
```

### 6.2 错误码设计
| 错误码 | 说明 |
|--------|------|
| 1001 | 参数验证失败 |
| 1002 | 用户名或密码错误 |
| 1003 | Token无效或过期 |
| 2001 | 资源不存在 |
| 2002 | 资源已存在 |
| 3001 | 权限不足 |
| 5000 | 服务器内部错误 |

## 7. 筛选和统计功能设计

### 7.1 组合筛选（AND条件）
支持多个字段同时筛选，所有条件必须同时满足。
示例：
- 工程类别=基建 AND 签订日期>2026-01-01 AND 合同金额>100万

### 7.2 统计功能
- **基础统计**：记录总数、字段总和、平均值等
- **分组统计**：按指定字段分组统计
- **时间维度统计**：按时间区间统计（按日/月/年）

## 8. 安全设计

### 8.1 认证安全
- 密码使用bcrypt加密存储（salt rounds=12）
- JWT Token有效期24小时
- Token存储在HttpOnly Cookie或LocalStorage

### 8.2 权限控制
- 后端基于依赖注入的权限验证
- 支持角色级别和资源级别权限控制

### 8.3 数据安全
- SQL注入防护（SQLAlchemy ORM参数化查询）
- XSS防护（FastAPI自动处理）
- 输入验证（Pydantic模型）
- 请求频率限制（可选）

## 9. 开发规范

### 9.1 代码风格
- 遵循PEP 8规范
- 使用Type Hints进行类型标注
- 函数和类添加docstring

### 9.2 提交规范
- 提交格式: `[backend] <类型>: <描述>`
- 类型: feat, fix, docs, style, refactor, test, chore

### 9.3 测试要求
- 单元测试覆盖率 > 80%
- 使用pytest测试框架
- 测试文件命名: `test_<模块名>.py`

## 10. 部署方案

### 10.1 开发环境
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 5000
```

### 10.2 生产环境
- 使用Gunicorn + Uvicorn Workers
- Nginx反向代理
- Docker容器化部署（可选）

---

**文档维护**: 后端程序员
**更新时间**: 2026-01-25