635 lines
31 KiB
Markdown
635 lines
31 KiB
Markdown
# 项目管理系统技术架构文档
|
||
|
||
## 文档信息
|
||
- **文档版本**: V2.0
|
||
- **创建日期**: 2026-01-26
|
||
- **文档类型**: 技术架构文档
|
||
|
||
---
|
||
|
||
## 1. 技术架构概述
|
||
|
||
### 1.1 架构风格
|
||
本项目采用BS（Browser/Server）架构，即浏览器/服务器架构。前端通过浏览器访问系统，后端通过服务器提供服务，数据存储在数据库中。由于系统并发量较小，采用直接操作数据库的方式，无需引入缓存层。
|
||
|
||
### 1.2 技术选型
|
||
|
||
| 分类 | 技术 | 版本 | 选型理由 |
|
||
|------|------|------|----------|
|
||
| 前端框架 | Vue 3 | 3.3.0+ | 轻量级、响应式、组件化开发，适合构建现代化Web应用 |
|
||
| 状态管理 | Pinia | 2.1.0+ | Vue 3官方推荐的状态管理库，比Vuex更轻量、更易用 |
|
||
| UI组件库 | Element Plus | 2.4.0+ | 基于Vue 3的企业级UI组件库，组件丰富，文档完善 |
|
||
| 前端路由 | Vue Router | 4.2.0+ | Vue官方路由库，支持嵌套路由、动态路由等 |
|
||
| 网络请求 | Axios | 1.6.0+ | 轻量级HTTP客户端，支持拦截器、取消请求等特性 |
|
||
| 后端框架 | FastAPI | 0.104.0+ | 高性能Python Web框架，自动生成API文档，支持异步 |
|
||
| ORM框架 | SQLAlchemy | 2.0.0+ | Python最流行的ORM框架，支持多种数据库 |
|
||
| 数据库驱动 | PyMySQL | 1.1.0+ | 纯Python实现的MySQL客户端 |
|
||
| 数据库 | MySQL | 8.0+ | 关系型数据库，稳定可靠，适合企业级应用 |
|
||
| 认证 | JWT | 2.8.0+ | JSON Web Token，用于用户认证和授权 |
|
||
| 密码加密 | Passlib | 1.7.4+ | 密码哈希库，支持多种加密算法 |
|
||
| 数据验证 | Pydantic | 2.5.0+ | 数据验证和设置库，与FastAPI完美集成 |
|
||
| API文档 | Swagger | - | FastAPI自动生成，提供交互式API文档 |
|
||
| 构建工具 | Poetry | 1.7.0+ | Python依赖管理和打包工具 |
|
||
| 版本控制 | Git | 2.40.0+ | 分布式版本控制系统，便于团队协作开发 |
|
||
|
||
---
|
||
|
||
## 2. 系统架构设计
|
||
|
||
### 2.1 架构分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 前端层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ 视图层 │ │ 业务逻辑层 │ │ 数据层 │ │
|
||
│ │ (Vue组件) │ │ (Pinia Store) │ │ (Axios) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ API网关 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 后端层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ 路由层 │ │ 服务层 │ │ 数据访问层 │ │
|
||
│ │ (Router) │ │ (Service) │ │ (Model) │ │
|
||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 数据层 │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||
│ │ MySQL数据库 │ │ 文件存储 │ │
|
||
│ └─────────────────┘ └─────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 核心流程图
|
||
|
||
#### 2.2.1 用户登录流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 前端 as 浏览器
|
||
participant 后端 as FastAPI服务
|
||
participant 数据库 as MySQL
|
||
|
||
前端->>后端: POST /api/auth/login (username, password)
|
||
后端->>数据库: 查询用户信息
|
||
alt 用户存在且密码正确
|
||
数据库-->>后端: 返回用户信息
|
||
后端->>后端: 生成JWT Token
|
||
后端-->>前端: 200 OK { "token": "...", "userInfo": {...} }
|
||
else 用户不存在或密码错误
|
||
数据库-->>后端: 返回空
|
||
后端-->>前端: 401 Unauthorized { "message": "用户名或密码错误" }
|
||
end
|
||
```
|
||
|
||
#### 2.2.2 项目创建流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 前端 as 浏览器
|
||
participant 后端 as FastAPI服务
|
||
participant 数据库 as MySQL
|
||
|
||
前端->>后端: POST /api/project (项目信息)
|
||
后端->>后端: 验证用户权限
|
||
alt 有权限
|
||
后端->>后端: 生成项目编号
|
||
后端->>数据库: 创建项目记录
|
||
后端->>数据库: 创建项目成员记录
|
||
后端->>数据库: 创建项目里程碑记录
|
||
后端->>数据库: 创建项目风险记录
|
||
后端->>数据库: 创建项目历史记录
|
||
后端-->>前端: 200 OK { "message": "项目创建成功", "projectId": "..." }
|
||
else 无权限
|
||
后端-->>前端: 403 Forbidden { "message": "您没有创建项目的权限" }
|
||
end
|
||
```
|
||
|
||
#### 2.2.3 项目编辑流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 前端 as 浏览器
|
||
participant 后端 as FastAPI服务
|
||
participant 数据库 as MySQL
|
||
|
||
前端->>后端: PUT /api/project/{id} (修改后的项目信息)
|
||
后端->>后端: 验证用户权限
|
||
alt 有权限
|
||
后端->>数据库: 查询项目信息
|
||
数据库-->>后端: 返回项目信息
|
||
后端->>后端: 对比修改前后的数据
|
||
后端->>数据库: 更新项目信息
|
||
后端->>数据库: 更新相关表数据
|
||
后端->>数据库: 创建项目历史记录
|
||
后端-->>前端: 200 OK { "message": "项目更新成功" }
|
||
else 无权限
|
||
后端-->>前端: 403 Forbidden { "message": "您没有编辑项目的权限" }
|
||
end
|
||
```
|
||
|
||
### 2.3 模块划分
|
||
|
||
#### 2.3.1 前端模块
|
||
|
||
| 模块名称 | 主要功能 | 对应文件路径 |
|
||
|---------|---------|------------|
|
||
| 登录模块 | 用户登录、退出登录 | src/views/login/ |
|
||
| 首页模块 | 系统首页、项目概览 | src/views/home/ |
|
||
| 用户管理模块 | 用户列表、创建用户、编辑用户 | src/views/user/ |
|
||
| 项目管理模块 | 项目列表、创建项目、编辑项目 | src/views/project/ |
|
||
| 项目详情模块 | 项目详细信息、修改历史 | src/views/project/detail/ |
|
||
| 项目统计模块 | 项目筛选、统计分析 | src/views/project/statistics/ |
|
||
| 系统设置模块 | 系统配置、个人设置 | src/views/settings/ |
|
||
|
||
#### 2.3.2 后端模块
|
||
|
||
| 模块名称 | 主要功能 | 对应包路径 |
|
||
|---------|---------|-----------|
|
||
| 认证模块 | 用户认证、授权 | app.api.auth |
|
||
| 用户模块 | 用户管理、权限管理 | app.api.user |
|
||
| 项目模块 | 项目管理、项目编辑 | app.api.project |
|
||
| 历史记录模块 | 项目修改历史 | app.api.history |
|
||
| 统计模块 | 项目统计、数据分析 | app.api.statistics |
|
||
| 系统模块 | 系统配置、操作日志 | app.api.system |
|
||
| 数据模型 | 数据库模型定义 | app.models |
|
||
| 数据库会话 | 数据库连接管理 | app.database |
|
||
| 公共模块 | 工具类、常量定义 | app.common |
|
||
|
||
---
|
||
|
||
## 3. 目录结构
|
||
|
||
### 3.1 前端目录结构
|
||
|
||
```
|
||
├── public/ # 静态资源
|
||
│ ├── favicon.ico # 网站图标
|
||
│ └── index.html # HTML模板
|
||
├── src/ # 源代码
|
||
│ ├── assets/ # 资源文件
|
||
│ │ ├── css/ # 样式文件
|
||
│ │ ├── images/ # 图片文件
|
||
│ │ └── icons/ # 图标文件
|
||
│ ├── components/ # 公共组件
|
||
│ ├── views/ # 页面组件
|
||
│ │ ├── login/ # 登录页面
|
||
│ │ ├── home/ # 首页
|
||
│ │ ├── user/ # 用户管理
|
||
│ │ ├── project/ # 项目管理
|
||
│ │ └── settings/ # 系统设置
|
||
│ ├── router/ # 路由配置
|
||
│ ├── store/ # 状态管理
|
||
│ ├── api/ # API请求
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── constants/ # 常量定义
|
||
│ ├── hooks/ # 自定义Hooks
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.js # 入口文件
|
||
├── .env # 环境变量
|
||
├── .env.development # 开发环境变量
|
||
├── .env.production # 生产环境变量
|
||
├── vite.config.js # Vite配置
|
||
├── package.json # 项目依赖
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
### 3.2 后端目录结构
|
||
|
||
```
|
||
├── app/ # 应用代码
|
||
│ ├── api/ # API路由
|
||
│ │ ├── auth.py # 认证API
|
||
│ │ ├── user.py # 用户API
|
||
│ │ ├── project.py # 项目API
|
||
│ │ ├── history.py # 历史记录API
|
||
│ │ ├── statistics.py # 统计API
|
||
│ │ └── system.py # 系统API
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── project.py # 项目模型
|
||
│ │ ├── member.py # 成员模型
|
||
│ │ ├── milestone.py # 里程碑模型
|
||
│ │ ├── risk.py # 风险模型
|
||
│ │ ├── history.py # 历史记录模型
|
||
│ │ └── log.py # 日志模型
|
||
│ ├── schemas/ # Pydantic模式
|
||
│ │ ├── auth.py # 认证模式
|
||
│ │ ├── user.py # 用户模式
|
||
│ │ ├── project.py # 项目模式
|
||
│ │ └── common.py # 通用模式
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── auth_service.py # 认证服务
|
||
│ │ ├── user_service.py # 用户服务
|
||
│ │ ├── project_service.py # 项目服务
|
||
│ │ ├── history_service.py # 历史记录服务
|
||
│ │ └── statistics_service.py # 统计服务
|
||
│ ├── database/ # 数据库配置
|
||
│ │ ├── config.py # 数据库配置
|
||
│ │ └── session.py # 数据库会话
|
||
│ ├── common/ # 公共模块
|
||
│ │ ├── constants.py # 常量定义
|
||
│ │ ├── utils.py # 工具函数
|
||
│ │ ├── dependencies.py # 依赖注入
|
||
│ │ └── exceptions.py # 异常处理
|
||
│ ├── config.py # 应用配置
|
||
│ └── main.py # 应用入口
|
||
├── tests/ # 测试代码
|
||
│ ├── test_auth.py # 认证测试
|
||
│ ├── test_user.py # 用户测试
|
||
│ └── test_project.py # 项目测试
|
||
├── alembic/ # 数据库迁移
|
||
│ ├── versions/ # 迁移版本
|
||
│ └── env.py # 迁移环境
|
||
├── pyproject.toml # Poetry配置
|
||
├── poetry.lock # Poetry锁文件
|
||
├── requirements.txt # 依赖列表
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 关键类与函数设计
|
||
|
||
### 4.1 前端关键类与函数
|
||
|
||
#### 4.1.1 认证相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `login()` | 用户登录 | username: String 用户名<br>password: String 密码 | `{ token: String, userInfo: Object }` | `{ code: Number, message: String }` | src/api/auth.js |
|
||
| `logout()` | 用户退出 | 无 | `{ code: 200, message: String }` | `{ code: Number, message: String }` | src/api/auth.js |
|
||
| `getUserInfo()` | 获取用户信息 | 无 | `{ userInfo: Object }` | `{ code: Number, message: String }` | src/api/auth.js |
|
||
|
||
#### 4.1.2 项目相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `createProject()` | 创建项目 | project: Object 项目信息 | `{ code: 200, message: String, projectId: String }` | `{ code: Number, message: String }` | src/api/project.js |
|
||
| `updateProject()` | 更新项目 | id: String 项目ID<br>project: Object 项目信息 | `{ code: 200, message: String }` | `{ code: Number, message: String }` | src/api/project.js |
|
||
| `getProjectList()` | 获取项目列表 | params: Object 查询参数 | `{ code: 200, data: Array, total: Number }` | `{ code: Number, message: String }` | src/api/project.js |
|
||
| `getProjectDetail()` | 获取项目详情 | id: String 项目ID | `{ code: 200, data: Object }` | `{ code: Number, message: String }` | src/api/project.js |
|
||
| `getProjectHistory()` | 获取项目历史 | id: String 项目ID<br>params: Object 查询参数 | `{ code: 200, data: Array, total: Number }` | `{ code: Number, message: String }` | src/api/project.js |
|
||
|
||
#### 4.1.3 用户相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `createUser()` | 创建用户 | user: Object 用户信息 | `{ code: 200, message: String }` | `{ code: Number, message: String }` | src/api/user.js |
|
||
| `updateUser()` | 更新用户 | id: String 用户ID<br>user: Object 用户信息 | `{ code: 200, message: String }` | `{ code: Number, message: String }` | src/api/user.js |
|
||
| `getUserList()` | 获取用户列表 | params: Object 查询参数 | `{ code: 200, data: Array, total: Number }` | `{ code: Number, message: String }` | src/api/user.js |
|
||
| `resetPassword()` | 重置密码 | id: String 用户ID<br>password: String 新密码 | `{ code: 200, message: String }` | `{ code: Number, message: String }` | src/api/user.js |
|
||
|
||
### 4.2 后端关键类与函数
|
||
|
||
#### 4.2.1 认证相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `AuthRouter.login()` | 用户登录 | LoginRequest 登录请求 | `AuthResponse` | `HTTPException` | app.api.auth |
|
||
| `AuthRouter.logout()` | 用户退出 | 无 | `BaseResponse` | `HTTPException` | app.api.auth |
|
||
| `AuthService.authenticate()` | 认证用户 | str username, str password | `AuthResponse` | `AuthenticationException` | app.services.auth_service |
|
||
| `AuthService.create_token()` | 创建Token | str user_id | `str` Token | `Exception` | app.services.auth_service |
|
||
|
||
#### 4.2.2 项目相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `ProjectRouter.create()` | 创建项目 | ProjectRequest 项目请求 | `BaseResponse` | `HTTPException` | app.api.project |
|
||
| `ProjectRouter.update()` | 更新项目 | str id, ProjectRequest 项目请求 | `BaseResponse` | `HTTPException` | app.api.project |
|
||
| `ProjectRouter.list()` | 获取项目列表 | ProjectQuery 查询参数 | `PageResponse[Project]` | `HTTPException` | app.api.project |
|
||
| `ProjectRouter.detail()` | 获取项目详情 | str id | `BaseResponse[ProjectDetail]` | `HTTPException` | app.api.project |
|
||
| `ProjectService.create_project()` | 创建项目 | ProjectRequest 项目请求, str username | `str` 项目ID | `ServiceException` | app.services.project_service |
|
||
| `ProjectService.update_project()` | 更新项目 | str id, ProjectRequest 项目请求, str username | `None` | `ServiceException` | app.services.project_service |
|
||
|
||
#### 4.2.3 历史记录相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `HistoryRouter.list()` | 获取项目历史 | str project_id, HistoryQuery 查询参数 | `PageResponse[ProjectHistory]` | `HTTPException` | app.api.history |
|
||
| `HistoryService.record_history()` | 记录历史 | str project_id, str operation_type, str operator, dict changes | `None` | `ServiceException` | app.services.history_service |
|
||
|
||
#### 4.2.4 统计相关
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `StatisticsRouter.filter()` | 筛选项目 | ProjectFilter 筛选条件 | `PageResponse[Project]` | `HTTPException` | app.api.statistics |
|
||
| `StatisticsRouter.statistics()` | 统计项目 | StatisticsRequest 统计请求 | `BaseResponse[StatisticsResult]` | `HTTPException` | app.api.statistics |
|
||
| `StatisticsService.get_project_statistics()` | 获取项目统计 | StatisticsRequest 统计请求 | `StatisticsResult` | `ServiceException` | app.services.statistics_service |
|
||
|
||
---
|
||
|
||
## 5. 数据库与数据结构设计
|
||
|
||
### 5.1 数据库表结构
|
||
|
||
详细的数据库表结构见《数据库设计文档》。
|
||
|
||
### 5.2 数据传输对象 (DTOs)
|
||
|
||
#### 5.2.1 前端DTOs
|
||
|
||
##### 登录请求
|
||
```javascript
|
||
{
|
||
username: String, // 用户名
|
||
password: String // 密码
|
||
}
|
||
```
|
||
|
||
##### 项目请求
|
||
```javascript
|
||
{
|
||
projectName: String, // 项目名称
|
||
status: String, // 项目状态
|
||
leader: String, // 负责人
|
||
phone: String, // 联系电话
|
||
email: String, // 邮箱
|
||
background: String, // 项目背景
|
||
goal: String, // 项目目标
|
||
scope: String, // 项目范围
|
||
startDate: String, // 开始日期
|
||
plannedEndDate: String, // 预计结束日期
|
||
actualEndDate: String, // 实际结束日期
|
||
totalBudget: Number, // 总预算
|
||
usedBudget: Number, // 已使用预算
|
||
members: [ // 项目成员
|
||
{
|
||
name: String, // 姓名
|
||
role: String, // 角色
|
||
department: String // 部门
|
||
}
|
||
],
|
||
milestones: [ // 项目里程碑
|
||
{
|
||
name: String, // 名称
|
||
plannedDate: String, // 计划日期
|
||
actualDate: String, // 实际日期
|
||
status: String // 状态
|
||
}
|
||
],
|
||
risks: [ // 项目风险
|
||
{
|
||
description: String, // 描述
|
||
level: String, // 等级
|
||
measure: String // 应对措施
|
||
}
|
||
],
|
||
remarks: String // 备注
|
||
}
|
||
```
|
||
|
||
#### 5.2.2 后端DTOs (Pydantic Models)
|
||
|
||
##### 登录请求
|
||
```python
|
||
from pydantic import BaseModel
|
||
|
||
class LoginRequest(BaseModel):
|
||
username: str # 用户名
|
||
password: str # 密码
|
||
```
|
||
|
||
##### 项目请求
|
||
```python
|
||
from pydantic import BaseModel
|
||
from typing import List, Optional
|
||
from datetime import date
|
||
from decimal import Decimal
|
||
|
||
class MemberRequest(BaseModel):
|
||
name: str # 姓名
|
||
role: str # 角色
|
||
department: str # 部门
|
||
|
||
class MilestoneRequest(BaseModel):
|
||
name: str # 名称
|
||
planned_date: date # 计划日期
|
||
actual_date: Optional[date] = None # 实际日期
|
||
status: str # 状态
|
||
|
||
class RiskRequest(BaseModel):
|
||
description: str # 描述
|
||
level: str # 等级
|
||
measure: str # 应对措施
|
||
|
||
class ProjectRequest(BaseModel):
|
||
project_name: str # 项目名称
|
||
status: str # 项目状态
|
||
leader: str # 负责人
|
||
phone: Optional[str] = None # 联系电话
|
||
email: Optional[str] = None # 邮箱
|
||
background: Optional[str] = None # 项目背景
|
||
goal: Optional[str] = None # 项目目标
|
||
scope: Optional[str] = None # 项目范围
|
||
start_date: date # 开始日期
|
||
planned_end_date: date # 预计结束日期
|
||
actual_end_date: Optional[date] = None # 实际结束日期
|
||
total_budget: Decimal # 总预算
|
||
used_budget: Decimal = Decimal('0.00') # 已使用预算
|
||
members: List[MemberRequest] = [] # 项目成员
|
||
milestones: List[MilestoneRequest] = [] # 项目里程碑
|
||
risks: List[RiskRequest] = [] # 项目风险
|
||
remarks: Optional[str] = None # 备注
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 接口设计
|
||
|
||
### 6.1 认证接口
|
||
|
||
| API路径 | 方法 | 模块/文件 | 类型 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|------|----------|--------------|------------------|
|
||
| `/api/auth/login` | `POST` | `app.api.auth` | `Router` | 用户登录 | `{"username": "admin", "password": "123456"}` | `{"code": 200, "data": {"token": "...", "userInfo": {...}}, "message": "登录成功"}` |
|
||
| `/api/auth/logout` | `POST` | `app.api.auth` | `Router` | 用户退出 | N/A | `{"code": 200, "message": "退出成功"}` |
|
||
| `/api/auth/userInfo` | `GET` | `app.api.auth` | `Router` | 获取用户信息 | N/A | `{"code": 200, "data": {"userId": "...", "username": "...", "realName": "...", "department": "...", "role": "..."}}` |
|
||
|
||
### 6.2 用户接口
|
||
|
||
| API路径 | 方法 | 模块/文件 | 类型 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|------|----------|--------------|------------------|
|
||
| `/api/user` | `GET` | `app.api.user` | `Router` | 获取用户列表 | N/A (Query参数: page, size, username, department, role) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/user` | `POST` | `app.api.user` | `Router` | 创建用户 | `{"username": "test", "password": "123456", "realName": "测试用户", "department": "技术部", "role": "OTHER"}` | `{"code": 200, "message": "创建成功"}` |
|
||
| `/api/user/{id}` | `PUT` | `app.api.user` | `Router` | 更新用户 | `{"realName": "测试用户1", "department": "市场部", "role": "MARKETING"}` | `{"code": 200, "message": "更新成功"}` |
|
||
| `/api/user/{id}` | `DELETE` | `app.api.user` | `Router` | 删除用户 | N/A | `{"code": 200, "message": "删除成功"}` |
|
||
| `/api/user/resetPassword/{id}` | `PUT` | `app.api.user` | `Router` | 重置密码 | `{"password": "123456"}` | `{"code": 200, "message": "密码重置成功"}` |
|
||
|
||
### 6.3 项目接口
|
||
|
||
| API路径 | 方法 | 模块/文件 | 类型 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|------|----------|--------------|------------------|
|
||
| `/api/project` | `GET` | `app.api.project` | `Router` | 获取项目列表 | N/A (Query参数: page, size, projectName, status, leader) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/project` | `POST` | `app.api.project` | `Router` | 创建项目 | `{"projectName": "测试项目", "status": "NOT_STARTED", "leader": "张三", ...}` | `{"code": 200, "data": {"projectId": "..."}, "message": "创建成功"}` |
|
||
| `/api/project/{id}` | `GET` | `app.api.project` | `Router` | 获取项目详情 | N/A | `{"code": 200, "data": {...}, "message": "查询成功"}` |
|
||
| `/api/project/{id}` | `PUT` | `app.api.project` | `Router` | 更新项目 | `{"projectName": "测试项目1", "status": "IN_PROGRESS", ...}` | `{"code": 200, "message": "更新成功"}` |
|
||
| `/api/project/{id}` | `DELETE` | `app.api.project` | `Router` | 删除项目 | N/A | `{"code": 200, "message": "删除成功"}` |
|
||
|
||
### 6.4 历史记录接口
|
||
|
||
| API路径 | 方法 | 模块/文件 | 类型 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|------|----------|--------------|------------------|
|
||
| `/api/history/{projectId}` | `GET` | `app.api.history` | `Router` | 获取项目历史 | N/A (Query参数: page, size, operator, startDate, endDate) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
|
||
### 6.5 统计接口
|
||
|
||
| API路径 | 方法 | 模块/文件 | 类型 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|------|----------|--------------|------------------|
|
||
| `/api/statistics/filter` | `POST` | `app.api.statistics` | `Router` | 筛选项目 | `{"projectNo": "PRJ2025001", "projectName": "测试", "status": "IN_PROGRESS", ...}` | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/statistics/statistics` | `POST` | `app.api.statistics` | `Router` | 统计项目 | `{"dimension": "status", "startDate": "2025-01-01", "endDate": "2025-12-31"}` | `{"code": 200, "data": {...}, "message": "统计成功"}` |
|
||
|
||
---
|
||
|
||
## 7. 安全设计
|
||
|
||
### 7.1 认证与授权
|
||
|
||
- **认证方式**: JWT (JSON Web Token) 认证
|
||
- **授权方式**: 基于角色的访问控制 (RBAC)
|
||
- **密码加密**: 使用 Passlib 的 bcrypt 算法加密存储密码
|
||
- **会话管理**: JWT Token 存储在前端 localStorage 中，后端验证 Token 签名和有效期
|
||
|
||
### 7.2 接口安全
|
||
|
||
- **统一认证拦截**: 所有接口（除登录接口外）都需要验证 Token
|
||
- **权限验证**: 基于用户角色和权限进行接口访问控制
|
||
- **请求参数验证**: 使用 Pydantic 验证请求参数的合法性
|
||
- **防止SQL注入**: 使用 SQLAlchemy 的参数化查询，避免SQL注入
|
||
- **防止XSS攻击**: 前端使用 v-html 时进行转义，后端对输入进行过滤
|
||
- **防止CSRF攻击**: 使用 Token 验证，确保请求来自合法来源
|
||
|
||
### 7.3 数据安全
|
||
|
||
- **敏感数据加密**: 敏感数据（如密码）加密存储
|
||
- **数据备份**: 定期备份数据库，防止数据丢失
|
||
- **数据恢复**: 制定数据恢复计划，确保数据可恢复
|
||
- **日志审计**: 记录用户操作日志，便于追溯操作行为
|
||
|
||
---
|
||
|
||
## 8. 部署与集成方案
|
||
|
||
### 8.1 开发环境部署
|
||
|
||
#### 8.1.1 前端部署
|
||
1. 克隆代码库: `git clone <repository-url>`
|
||
2. 安装依赖: `npm install`
|
||
3. 启动开发服务器: `npm run dev`
|
||
4. 访问: `http://localhost:5173`
|
||
|
||
#### 8.1.2 后端部署
|
||
1. 克隆代码库: `git clone <repository-url>`
|
||
2. 安装依赖: `poetry install` 或 `pip install -r requirements.txt`
|
||
3. 配置数据库连接 (config.py)
|
||
4. 初始化数据库: `alembic upgrade head`
|
||
5. 启动应用: `uvicorn app.main:app --reload`
|
||
6. 访问: `http://localhost:8000`
|
||
7. API文档: `http://localhost:8000/docs`
|
||
|
||
### 8.2 生产环境部署
|
||
|
||
#### 8.2.1 前端部署
|
||
1. 构建生产版本: `npm run build`
|
||
2. 将构建产物复制到 Nginx 静态目录
|
||
3. 配置 Nginx 反向代理
|
||
|
||
#### 8.2.2 后端部署
|
||
1. 安装依赖: `poetry install --no-dev` 或 `pip install -r requirements.txt`
|
||
2. 配置环境变量和数据库连接
|
||
3. 使用 Gunicorn 启动应用: `gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker`
|
||
4. 配置 Nginx 反向代理
|
||
|
||
### 8.3 集成方案
|
||
|
||
- **前端与后端集成**: 通过 RESTful API 进行数据交互
|
||
- **数据库集成**: 使用 SQLAlchemy ORM 操作数据库
|
||
- **日志集成**: 使用 Python logging 模块记录系统日志
|
||
- **监控集成**: 可集成 Prometheus + Grafana 监控系统性能
|
||
|
||
---
|
||
|
||
## 9. 性能优化策略
|
||
|
||
### 9.1 前端优化
|
||
|
||
- **代码分割**: 使用 Vue 的路由懒加载，减少初始加载时间
|
||
- **组件缓存**: 使用 keep-alive 缓存频繁访问的组件
|
||
- **图片优化**: 使用适当尺寸的图片，压缩图片大小
|
||
- **网络请求优化**: 使用 Axios 拦截器，统一处理请求和响应
|
||
- **减少 DOM 操作**: 使用虚拟列表处理大数据渲染
|
||
|
||
### 9.2 后端优化
|
||
|
||
- **数据库索引**: 为常用查询字段创建索引，提高查询性能
|
||
- **连接池**: 使用 SQLAlchemy 的连接池，提高数据库连接效率
|
||
- **异步处理**: FastAPI 支持异步处理，提高系统响应速度
|
||
- **批量操作**: 对批量数据操作使用批量处理，减少数据库交互次数
|
||
- **查询优化**: 使用 SQLAlchemy 的 lazy loading 和 eager loading 优化查询
|
||
|
||
### 9.3 数据库优化
|
||
|
||
- **表结构优化**: 合理设计表结构，避免冗余字段
|
||
- **SQL优化**: 优化 SQL 查询语句，避免全表扫描
|
||
- **定期清理**: 定期清理历史数据，避免数据量过大
|
||
- **数据库配置**: 优化 MySQL 配置参数，提高数据库性能
|
||
|
||
---
|
||
|
||
## 10. 监控与维护
|
||
|
||
### 10.1 系统监控
|
||
|
||
- **应用监控**: 监控应用的运行状态、CPU、内存使用情况
|
||
- **数据库监控**: 监控数据库的连接数、查询性能、存储空间
|
||
- **API监控**: 监控 API 的响应时间、调用次数、错误率
|
||
- **日志监控**: 监控系统日志，及时发现异常情况
|
||
|
||
### 10.2 故障处理
|
||
|
||
- **故障定位**: 通过日志和监控工具定位故障原因
|
||
- **故障恢复**: 制定故障恢复方案，确保系统快速恢复
|
||
- **故障预防**: 定期进行系统检查，预防故障发生
|
||
|
||
### 10.3 系统维护
|
||
|
||
- **定期更新**: 定期更新依赖库和框架版本，修复安全漏洞
|
||
- **数据备份**: 定期备份数据库，防止数据丢失
|
||
- **性能调优**: 定期分析系统性能，进行性能调优
|
||
- **文档更新**: 及时更新系统文档，保持文档与系统同步
|
||
|
||
---
|
||
|
||
## 11. 附录
|
||
|
||
### 11.1 技术选型对比
|
||
|
||
| 技术 | 对比方案 | 最终选择理由 |
|
||
|------|----------|--------------|
|
||
| 前端框架 | Vue 3 vs React | Vue 3 学习曲线平缓，文档完善，适合快速开发 |
|
||
| 后端框架 | FastAPI vs Flask vs Django | FastAPI 高性能，自动生成API文档，支持异步 |
|
||
| 数据库 | MySQL vs PostgreSQL | MySQL 社区活跃，生态成熟，适合企业级应用 |
|
||
| ORM框架 | SQLAlchemy vs Django ORM | SQLAlchemy 灵活强大，支持多种数据库 |
|
||
|
||
### 11.2 开发规范
|
||
|
||
#### 前端开发规范
|
||
- 组件命名: 大驼峰命名法 (PascalCase)
|
||
- 变量命名: 小驼峰命名法 (camelCase)
|
||
- 常量命名: 全大写下划线分隔 (SNAKE_CASE)
|
||
- 代码风格: 遵循 ESLint 规范
|
||
|
||
#### 后端开发规范
|
||
- 类命名: 大驼峰命名法 (PascalCase)
|
||
- 函数命名: 小驼峰命名法 (camelCase)
|
||
- 变量命名: 小写下划线分隔 (snake_case)
|
||
- 常量命名: 全大写下划线分隔 (SNAKE_CASE)
|
||
- 代码风格: 遵循 PEP 8 规范
|
||
|
||
### 11.3 变更记录
|
||
|
||
| 版本 | 日期 | 修改人 | 修改内容 |
|
||
|------|------|--------|----------|
|
||
| V1.0 | 2026-01-26 | - | 初始版本创建 |
|
||
| V2.0 | 2026-01-26 | - | 后端改为Python FastAPI，去掉Redis |
|