20 KiB
20 KiB
海洋项目管理系统 - 技术架构文档
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） |
| 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 | 更新时间 |
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 索引设计
-- 项目编号索引
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 统一响应格式
{
"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文档
主要端点包括：
- 认证相关：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 开发环境
后端：
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 5000
# 服务运行在 http://localhost:5000
前端：
cd frontend
npm install
npm start
# 服务运行在 http://localhost:3000
数据库：
- 本地MySQL数据库
- 数据库名：
project_manager - 配置文件：
backend/config/.env
8.2 生产环境
推荐方案：使用Docker Compose
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:
部署命令：
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 数据库备份
# 备份
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 技术文档
13.2 产品文档
- 产品设计文档 - 产品需求文档（PRD）
13.3 其他文档
- UI设计规范 - 前端UI设计规范
- 团队协作规范 - 团队协作流程
- 数据库设计和数据初始化 - 数据初始化方案
文档维护: 技术总监、后端程序员 文档类型: 技术架构文档 最后更新: 2026-01-25