save code

2026-01-26 12:29:56 +08:00
parent 4408f41d81
commit 40d2f3f6ac
13 changed files with 4891 additions and 124 deletions
@@ -0,0 +1,634 @@
+# 项目管理系统技术架构文档
+
+## 文档信息
+- **文档版本**: 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 |