8.0 KiB
8.0 KiB
海洋项目管理系统 - 后端架构设计
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） |
| 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>) - 统一响应格式:
{
"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 开发环境
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