# 海洋项目管理系统 - 技术架构文档

## 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