Files
ocean_project_manager/docs/技术架构文档.md
T
2026-01-25 15:05:03 +08:00

621 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 海洋项目管理系统 - 技术架构文档
## 1. 技术选型
### 1.1 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| **前端** | | |
| | React + React Router | 前后端分离架构 |
| | Ant Design | 企业级UI组件 |
| | Axios | HTTP客户端 |
| | Context API | 简单状态管理 |
| **后端** | | |
| | FastAPI | 高性能异步框架,自动生成API文档 |
| | SQLAlchemy 2.0 | 类型安全的ORM,支持异步 |
| | MySQL 8.0 | 关系型数据库 |
| | JWT (PyJWT) | 无状态认证 |
| | bcrypt | 密码加密存储 |
| | Pydantic v2 | 请求/响应数据验证 |
| **开发工具** | | |
| | Create React App | 前端开发环境 |
| | pipenv | Python依赖管理 |
| | pytest | 测试框架 |
### 1.2 系统特点
- 轻量级架构,适合小并发场景
- 无需Redis缓存,降低部署复杂度
- 基于角色的权限控制(RBAC
- 前后端分离,易于维护和扩展
- 自动生成API文档(Swagger UI
## 2. 系统架构
### 2.1 整体架构图
```
┌─────────────────────────────────────────────────┐
│ 浏览器 │
│ (React + Ant Design + React Router + Axios) │
└─────────────────────────────────────────────────┘
│ HTTP/HTTPS
│ JWT Token
┌─────────────────────────────────────────────────┐
│ FastAPI 后端服务 │
│ ┌─────────────────────────────────────────┐ │
│ │ API Layer (FastAPI Routes) │ │
│ ├─────────────────────────────────────────┤ │
│ │ Controllers (业务逻辑) │ │
│ ├─────────────────────────────────────────┤ │
│ │ Services (复杂业务逻辑) │ │
│ ├─────────────────────────────────────────┤ │
│ │ Data Access (SQLAlchemy ORM) │ │
│ ├─────────────────────────────────────────┤ │
│ │ Middleware (认证/日志/错误) │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
│ SQL
┌─────────────────────────────────────────────────┐
│ MySQL 8.0 数据库 │
│ ┌─────────────────────────────────────────┐ │
│ │ users │ │
│ │ projects (60+字段) │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
```
### 2.2 分层架构
#### 2.2.1 API Layer (路由层)
- 定义API端点
- 处理HTTP请求和响应
- 参数验证
#### 2.2.2 Controllers (控制器层)
- 实现业务逻辑
- 调用Services层
- 返回响应数据
#### 2.2.3 Services (服务层)
- 实现复杂的业务逻辑
- 数据转换和处理
- 调用ORM层
#### 2.2.4 Data Access (数据访问层)
- 使用SQLAlchemy ORM
- 数据库操作
- 数据模型定义
#### 2.2.5 Middleware (中间件层)
- 认证中间件
- 日志中间件
- 错误处理中间件
## 3. 项目目录结构
```
ocean_project_manager/
├── 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 # 应用配置
│ │ ├── init-database.sql # 数据库初始化
│ │ └── import-excel-data.py # Excel导入脚本
│ ├── docs/ # API文档
│ │ └── api.md # API接口文档
│ ├── requirements.txt # Python依赖
│ ├── main.py # FastAPI应用入口
│ ├── WORKSTANDARDS.md # 后端工作规范
│ └── README.md # 后端开发说明
├── frontend/ # 前端程序员工作区
│ ├── src/ # 源代码
│ │ ├── components/ # 可复用组件
│ │ │ ├── Layout.jsx
│ │ │ ├── Header.jsx
│ │ │ └── Sidebar.jsx
│ │ ├── pages/ # 页面组件
│ │ │ ├── Login.jsx
│ │ │ ├── Dashboard.jsx
│ │ │ ├── UserList.jsx
│ │ │ ├── UserForm.jsx
│ │ │ ├── ProjectList.jsx
│ │ │ ├── ProjectForm.jsx
│ │ │ └── ProjectDetail.jsx
│ │ ├── hooks/ # 自定义Hooks
│ │ │ └── useAuth.js
│ │ ├── services/ # API服务
│ │ │ ├── api.js # Axios配置
│ │ │ ├── auth.js
│ │ │ ├── user.js
│ │ │ └── project.js
│ │ ├── utils/ # 工具函数
│ │ │ └── auth.js
│ │ ├── styles/ # 样式文件
│ │ │ └── global.css
│ │ ├── types/ # TypeScript类型定义
│ │ │ ├── user.ts
│ │ │ └── project.ts
│ │ ├── App.jsx # 根组件
│ │ └── index.js # 入口文件
│ ├── tests/ # 组件测试
│ ├── docs/ # 组件文档
│ │ └── components.md
│ ├── package.json
│ ├── WORKSTANDARDS.md # 前端工作规范
│ └── README.md # 前端开发说明
├── testing/ # 测试工程师工作区
│ ├── testcases/ # 测试用例
│ │ ├── api/ # API测试用例
│ │ ├── ui/ # UI测试用例
│ │ └── integration/ # 集成测试用例
│ ├── reports/ # 测试报告
│ ├── data/ # 测试数据
│ ├── scripts/ # 自动化测试脚本
│ ├── docs/ # 测试文档
│ ├── WORKSTANDARDS.md # 测试工作规范
│ └── README.md # 测试工作说明
└── docs/ # 项目文档
├── 产品设计文档.md # 产品需求文档(PRD)
├── 技术架构文档.md # 技术架构文档(本文档)
├── 后端架构设计.md # 后端技术架构
├── api.md # API接口文档
├── ui-design-spec.md # UI设计规范
├── TEAM-COLLABORATION.md # 团队协作规范
├── database-design.md # 数据库设计
├── database-and-data-initialization.md # 数据初始化
├── example.xls # Excel数据源
└── plans/ # 设计方案
```
## 4. 数据库设计
### 4.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 | 更新时间 |
```sql
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
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('admin', 'market', 'other') NOT NULL,
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 CURRENT_TIMESTAMP,
INDEX idx_users_username (username),
INDEX idx_users_department (department),
INDEX idx_users_role (role)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
```
### 4.2 项目表 (projects)
基于`docs/database-design.md`,包含60+个字段:
**基础信息字段:**
- project_no, power_contract_no, name, subitem_count, subitem_code
- total_investment, contract_amount, settlement_amount, total_cost_estimated
- voltage_level, engineering_type, owner_unit, owner_contact, bidding_type
**时间字段:**
- signing_date, start_date, planned_end_date, actual_end_date
- warranty_expiry_date, actual_warranty_refund_date
**成本控制字段:**
- total_cost_control, is_adjusted
- labor_cost_control, labor_cost_planned, labor_cost_paid
- material_cost_control, material_cost_payable, material_cost_actual, material_cost_paid
- other_cost_control, other_cost_payable, other_cost_actual
**财务信息字段:**
- warranty_amount, warranty_ratio
- tax_amount, profit, actual_profit
- cost_settlement_amount
**应收应付字段:**
- cumulative_progress
- receivable_amount, invoice_amount, actual_receipt_amount, receipt_completion_rate
- payable_amount, actual_payment_amount, unpaid_amount, payment_completion_rate
**结算信息字段:**
- settlement_cost_amount, settlement_labor_cost, settlement_material_cost, settlement_other_cost
- due_settlement_count, unsettlement_count
**项目管理字段:**
- project_department, project_leader, payment_method
- problems, suggestions, remarks
**注意**:项目表不使用status字段,数据本身反映了项目的真实状态。
### 4.3 索引设计
```sql
-- 项目编号索引
CREATE INDEX idx_projects_project_no ON projects(project_no);
-- 工程类别索引
CREATE INDEX idx_projects_engineering_type ON projects(engineering_type);
-- 所属项目部索引
CREATE INDEX idx_projects_project_department ON projects(project_department);
-- 创建人索引
CREATE INDEX idx_projects_created_by ON projects(created_by);
-- 签订日期索引
CREATE INDEX idx_projects_signing_date ON projects(signing_date);
-- 计划竣工日期索引
CREATE INDEX idx_projects_planned_end_date ON projects(planned_end_date);
-- 复合索引:工程类别 + 创建人
CREATE INDEX idx_projects_type_created_by ON projects(engineering_type, created_by);
```
## 5. API设计
### 5.1 API规范
- **Base URL**: `/api/v1`
- **Content-Type**: `application/json`
- **认证方式**: JWT Token(在Header中传递:`Authorization: Bearer <token>`
- **API文档地址**: `http://localhost:5000/docs` (Swagger UI)
### 5.2 统一响应格式
```json
{
"success": true,
"message": "操作成功",
"data": {},
"error_code": null
}
```
### 5.3 错误码设计
| 错误码 | 说明 | HTTP状态码 |
|--------|------|-----------|
| 1001 | 参数验证失败 | 400 |
| 1002 | 用户名或密码错误 | 401 |
| 1003 | Token无效或过期 | 401 |
| 2001 | 资源不存在 | 404 |
| 2002 | 资源已存在 | 409 |
| 3001 | 权限不足 | 403 |
| 5000 | 服务器内部错误 | 500 |
### 5.4 API端点
详细的API文档请参考:[API文档](api.md)
主要端点包括:
- 认证相关:POST /auth/login, GET /auth/me, POST /auth/logout
- 用户管理:GET /users, POST /users, PUT /users/{id}, DELETE /users/{id}
- 项目管理:GET /projects, POST /projects, PUT /projects/{id}, DELETE /projects/{id}
- 项目统计:GET /projects/statistics, GET /projects/statistics/group, GET /projects/statistics/timeline
## 6. 前端设计
### 6.1 技术栈
- React 18
- React Router 6
- Ant Design 5
- Axios
- Context API
### 6.2 组件架构
```
App
├── ProtectedRoute (路由守卫)
├── Layout (主布局)
│ ├── Header (顶部导航)
│ └── Sidebar (侧边栏)
├── Login (登录页)
└── Dashboard (仪表盘)
├── UserList (用户列表)
│ └── UserForm (用户表单)
└── ProjectList (项目列表)
├── ProjectForm (项目表单)
└── ProjectDetail (项目详情)
```
### 6.3 状态管理
使用React Context API进行状态管理:
- AuthContext: 认证状态(用户信息、Token、登录/登出)
- 可以根据需要扩展其他Context
### 6.4 API服务
使用Axios封装HTTP请求:
- 统一的baseURL配置
- 请求拦截器(自动添加Token
- 响应拦截器(统一错误处理)
- API模块化管理
## 7. 安全设计
### 7.1 认证安全
- 密码使用bcrypt加密存储(salt rounds=12
- JWT Token有效期24小时
- Token存储在LocalStorage(可改为HttpOnly Cookie
- 实现Token自动刷新机制
### 7.2 权限控制
- 后端基于依赖注入的权限验证
- 支持角色级别权限控制(admin/market/other
- 支持资源级别权限控制(如market只能编辑自己创建的项目)
- 前端路由级别的权限控制(ProtectedRoute组件)
### 7.3 数据安全
- SQL注入防护(SQLAlchemy ORM参数化查询)
- XSS防护(React自动转义)
- 输入验证(前后端双重验证:Pydantic + 前端表单验证)
- 敏感信息加密(密码哈希)
### 7.4 其他安全措施
- CORS配置(限制跨域访问)
- 请求频率限制(可选,使用slowapi)
- HTTPS部署(生产环境必须)
## 8. 部署方案
### 8.1 开发环境
**后端:**
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 5000
# 服务运行在 http://localhost:5000
```
**前端:**
```bash
cd frontend
npm install
npm start
# 服务运行在 http://localhost:3000
```
**数据库:**
- 本地MySQL数据库
- 数据库名:`project_manager`
- 配置文件:`backend/config/.env`
### 8.2 生产环境
**推荐方案:使用Docker Compose**
```yaml
version: '3.8'
services:
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: project_manager
volumes:
- mysql_data:/var/lib/mysql
ports:
- "3306:3306"
backend:
build: ./backend
ports:
- "5000:5000"
depends_on:
- mysql
environment:
DATABASE_URL: mysql+aiomysql://root:rootpassword@mysql/project_manager
SECRET_KEY: your-secret-key
frontend:
build: ./frontend
ports:
- "80:80"
depends_on:
- backend
volumes:
mysql_data:
```
**部署命令:**
```bash
docker-compose up -d
```
### 8.3 服务器要求
**最低配置:**
- CPU: 2核
- 内存: 4GB
- 硬盘: 50GB
- 系统: Ubuntu 20.04+ 或 CentOS 7+
**推荐配置:**
- CPU: 4核
- 内存: 8GB
- 硬盘: 100GB
- 系统: Ubuntu 22.04+ 或 CentOS 8+
## 9. 开发规范
### 9.1 后端开发规范
**代码风格:**
- 遵循PEP 8规范
- 使用Type Hints进行类型标注
- 函数和类添加docstring
**提交规范:**
- 提交格式: `[backend] <类型>: <描述>`
- 类型: feat, fix, docs, style, refactor, test, chore
**测试要求:**
- 单元测试覆盖率 > 80%
- 使用pytest测试框架
- 测试文件命名: `test_<模块名>.py`
### 9.2 前端开发规范
**代码风格:**
- 遵循ESLint规则
- 使用Prettier格式化代码
- 组件使用函数式组件 + Hooks
**提交规范:**
- 提交格式: `[frontend] <类型>: <描述>`
- 类型: feat, fix, style, refactor, test, chore
**测试要求:**
- 关键组件必须有测试
- 使用Jest或Vitest测试框架
- 测试文件命名: `<组件名>.test.jsx`
### 9.3 测试规范
**测试分类:**
- 单元测试:测试单个函数/组件
- 集成测试:测试模块间的交互
- 端到端测试:测试完整业务流程
**测试覆盖率:**
- 后端: > 80%
- 前端关键组件: > 70%
## 10. 性能优化
### 10.1 数据库优化
- 合理使用索引
- 查询优化(避免N+1查询)
- 使用连接池
- 定期备份和优化
### 10.2 后端优化
- 异步处理(FastAPI async/await
- 缓存(可选,Redis
- 请求限流
- 日志优化
### 10.3 前端优化
- 代码分割(React.lazy
- 图片懒加载
- 使用CDN
- Gzip压缩
## 11. 监控和日志
### 11.1 日志管理
- 后端使用Python logging模块
- 日志级别:DEBUG, INFO, WARNING, ERROR, CRITICAL
- 日志文件按日期分割
### 11.2 性能监控
- 使用APM工具(如Sentry
- 监控API响应时间
- 监控错误率
### 11.3 错误追踪
- 自动捕获和记录错误
- 发送错误告警
- 错误堆栈追踪
## 12. 备份和恢复
### 12.1 数据库备份
```bash
# 备份
mysqldump -u root -p project_manager > backup_$(date +%Y%m%d).sql
# 恢复
mysql -u root -p project_manager < backup_20260125.sql
```
### 12.2 代码备份
- 使用Git进行版本控制
- 定期推送到远程仓库
- 打标签标记重要版本
### 12.3 备份策略
- 每日自动备份数据库
- 每周备份到远程服务器
- 保留最近30天的备份
## 13. 相关文档
### 13.1 技术文档
- [后端架构设计](后端架构设计.md) - 后端技术架构详解
- [API文档](api.md) - 完整的API接口文档
- [数据库设计](database-design.md) - 数据库表结构详细设计
### 13.2 产品文档
- [产品设计文档](产品设计文档.md) - 产品需求文档(PRD
### 13.3 其他文档
- [UI设计规范](ui-design-spec.md) - 前端UI设计规范
- [团队协作规范](TEAM-COLLABORATION.md) - 团队协作流程
- [数据库设计和数据初始化](database-and-data-initialization.md) - 数据初始化方案
---
**文档维护**: 技术总监、后端程序员
**文档类型**: 技术架构文档
**最后更新**: 2026-01-25