save code

2026-01-25 15:05:03 +08:00
parent 29565e9dfe
commit 0895398138
23 changed files with 11859 additions and 966 deletions
@@ -0,0 +1,228 @@
+# 海洋项目管理系统 - 后端架构设计
+
+## 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