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,620 @@
+# 海洋项目管理系统 - 技术架构文档
+
+## 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