229 lines
8.0 KiB
Markdown
229 lines
8.0 KiB
Markdown
# 海洋项目管理系统 - 后端架构设计
|
||
|
||
## 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
|