480 lines
24 KiB
Markdown
480 lines
24 KiB
Markdown
# 后端技术架构文档
|
||
|
||
## 文档信息
|
||
- **文档版本**: V1.0
|
||
- **创建日期**: 2026-01-26
|
||
- **文档类型**: 后端技术架构文档
|
||
|
||
---
|
||
|
||
## 1. 技术选型
|
||
|
||
| 分类 | 技术 | 版本 | 选型理由 |
|
||
|------|------|------|----------|
|
||
| 后端框架 | 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依赖管理和打包工具 |
|
||
| 数据库迁移 | Alembic | 1.12.0+ | SQLAlchemy的数据库迁移工具 |
|
||
| 测试框架 | Pytest | 7.4.0+ | Python最流行的测试框架 |
|
||
| 异步支持 | asyncio | - | Python内置的异步IO库 |
|
||
|
||
---
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 路由层 (API) │
|
||
│ (Router) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 业务逻辑层 (Service) │
|
||
│ (Service) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 数据访问层 (Model) │
|
||
│ (ORM Model) │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 数据层 │
|
||
│ (MySQL) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 核心模块
|
||
|
||
| 模块名称 | 主要职责 | 文件路径 | 依赖关系 |
|
||
|---------|---------|---------|----------|
|
||
| 认证模块 | 用户登录、退出、认证 | app/api/auth.py | 依赖用户模型、JWT |
|
||
| 用户模块 | 用户管理、权限管理 | app/api/user.py | 依赖用户模型、认证模块 |
|
||
| 项目模块 | 项目管理、创建、编辑 | app/api/project.py | 依赖项目模型、历史记录模块 |
|
||
| 历史记录模块 | 项目修改历史记录 | app/api/history.py | 依赖历史记录模型 |
|
||
| 统计模块 | 项目统计、数据分析 | app/api/statistics.py | 依赖项目模型 |
|
||
| 系统模块 | 系统配置、操作日志 | app/api/system.py | 依赖日志模型 |
|
||
|
||
### 2.3 数据流
|
||
|
||
1. **请求处理流程**：
|
||
- 客户端发送请求到API路由
|
||
- 路由层验证请求参数和用户权限
|
||
- 调用服务层处理业务逻辑
|
||
- 服务层调用数据访问层操作数据库
|
||
- 数据访问层返回数据给服务层
|
||
- 服务层处理数据并返回给路由层
|
||
- 路由层返回响应给客户端
|
||
|
||
2. **项目创建流程**：
|
||
- 验证用户权限（必须是市场部或管理员）
|
||
- 生成项目编号
|
||
- 创建项目记录
|
||
- 创建项目成员记录
|
||
- 创建项目里程碑记录
|
||
- 创建项目风险记录
|
||
- 创建项目历史记录
|
||
|
||
3. **项目编辑流程**：
|
||
- 验证用户权限
|
||
- 获取项目当前信息
|
||
- 对比修改前后的数据
|
||
- 更新项目记录
|
||
- 更新相关表数据
|
||
- 创建项目历史记录
|
||
|
||
---
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
├── app/ # 应用代码
|
||
│ ├── api/ # API路由
|
||
│ │ ├── auth.py # 认证API
|
||
│ │ ├── user.py # 用户API
|
||
│ │ ├── project.py # 项目API
|
||
│ │ ├── history.py # 历史记录API
|
||
│ │ ├── statistics.py # 统计API
|
||
│ │ ├── system.py # 系统API
|
||
│ │ └── __init__.py # 导出API
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── __init__.py # 导出模型
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ ├── project.py # 项目模型
|
||
│ │ ├── member.py # 成员模型
|
||
│ │ ├── milestone.py # 里程碑模型
|
||
│ │ ├── risk.py # 风险模型
|
||
│ │ ├── history.py # 历史记录模型
|
||
│ │ └── log.py # 日志模型
|
||
│ ├── schemas/ # Pydantic模式
|
||
│ │ ├── __init__.py # 导出模式
|
||
│ │ ├── auth.py # 认证模式
|
||
│ │ ├── user.py # 用户模式
|
||
│ │ ├── project.py # 项目模式
|
||
│ │ ├── history.py # 历史记录模式
|
||
│ │ ├── statistics.py # 统计模式
|
||
│ │ ├── system.py # 系统模式
|
||
│ │ └── common.py # 通用模式
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── __init__.py # 导出服务
|
||
│ │ ├── auth_service.py # 认证服务
|
||
│ │ ├── user_service.py # 用户服务
|
||
│ │ ├── project_service.py # 项目服务
|
||
│ │ ├── history_service.py # 历史记录服务
|
||
│ │ ├── statistics_service.py # 统计服务
|
||
│ │ └── system_service.py # 系统服务
|
||
│ ├── database/ # 数据库配置
|
||
│ │ ├── __init__.py # 导出配置
|
||
│ │ ├── config.py # 数据库配置
|
||
│ │ └── session.py # 数据库会话
|
||
│ ├── common/ # 公共模块
|
||
│ │ ├── __init__.py # 导出公共模块
|
||
│ │ ├── constants.py # 常量定义
|
||
│ │ ├── utils.py # 工具函数
|
||
│ │ ├── dependencies.py # 依赖注入
|
||
│ │ └── exceptions.py # 异常处理
|
||
│ ├── config.py # 应用配置
|
||
│ └── main.py # 应用入口
|
||
├── tests/ # 测试代码
|
||
│ ├── __init__.py # 测试初始化
|
||
│ ├── test_auth.py # 认证测试
|
||
│ ├── test_user.py # 用户测试
|
||
│ ├── test_project.py # 项目测试
|
||
│ ├── test_history.py # 历史记录测试
|
||
│ ├── test_statistics.py # 统计测试
|
||
│ └── conftest.py # 测试配置
|
||
├── alembic/ # 数据库迁移
|
||
│ ├── versions/ # 迁移版本
|
||
│ ├── env.py # 迁移环境
|
||
│ └── script.py.mako # 迁移脚本模板
|
||
├── pyproject.toml # Poetry配置
|
||
├── poetry.lock # Poetry锁文件
|
||
├── requirements.txt # 依赖列表
|
||
├── README.md # 项目说明
|
||
├── .env.example # 环境变量示例
|
||
└── .gitignore # Git忽略文件
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 核心类与函数
|
||
|
||
### 4.1 认证模块
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `AuthRouter.login()` | 用户登录 | LoginRequest 登录请求 | `AuthResponse` | `HTTPException` | app/api/auth.py |
|
||
| `AuthRouter.logout()` | 用户退出 | 无 | `BaseResponse` | `HTTPException` | app/api/auth.py |
|
||
| `AuthRouter.get_user_info()` | 获取用户信息 | 无 | `UserInfoResponse` | `HTTPException` | app/api/auth.py |
|
||
| `AuthService.authenticate()` | 认证用户 | str username, str password | `AuthResponse` | `AuthenticationException` | app/services/auth_service.py |
|
||
| `AuthService.create_token()` | 创建Token | str user_id | `str` Token | `Exception` | app/services/auth_service.py |
|
||
| `AuthService.verify_token()` | 验证Token | str token | `dict` Token载荷 | `JWTError` | app/services/auth_service.py |
|
||
|
||
### 4.2 用户模块
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `UserRouter.create()` | 创建用户 | UserCreate 用户创建请求 | `BaseResponse` | `HTTPException` | app/api/user.py |
|
||
| `UserRouter.update()` | 更新用户 | str id, UserUpdate 用户更新请求 | `BaseResponse` | `HTTPException` | app/api/user.py |
|
||
| `UserRouter.delete()` | 删除用户 | str id | `BaseResponse` | `HTTPException` | app/api/user.py |
|
||
| `UserRouter.list()` | 获取用户列表 | UserQuery 查询参数 | `PageResponse[User]` | `HTTPException` | app/api/user.py |
|
||
| `UserRouter.reset_password()` | 重置密码 | str id, PasswordReset 密码重置请求 | `BaseResponse` | `HTTPException` | app/api/user.py |
|
||
| `UserService.create_user()` | 创建用户 | UserCreate 用户创建请求 | `User` | `ServiceException` | app/services/user_service.py |
|
||
| `UserService.update_user()` | 更新用户 | str id, UserUpdate 用户更新请求 | `User` | `ServiceException` | app/services/user_service.py |
|
||
| `UserService.delete_user()` | 删除用户 | str id | `bool` | `ServiceException` | app/services/user_service.py |
|
||
| `UserService.get_user_list()` | 获取用户列表 | UserQuery 查询参数 | `List[User]` | `ServiceException` | app/services/user_service.py |
|
||
| `UserService.reset_password()` | 重置密码 | str id, str password | `bool` | `ServiceException` | app/services/user_service.py |
|
||
|
||
### 4.3 项目模块
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `ProjectRouter.create()` | 创建项目 | ProjectCreate 项目创建请求 | `BaseResponse` | `HTTPException` | app/api/project.py |
|
||
| `ProjectRouter.update()` | 更新项目 | str id, ProjectUpdate 项目更新请求 | `BaseResponse` | `HTTPException` | app/api/project.py |
|
||
| `ProjectRouter.delete()` | 删除项目 | str id | `BaseResponse` | `HTTPException` | app/api/project.py |
|
||
| `ProjectRouter.list()` | 获取项目列表 | ProjectQuery 查询参数 | `PageResponse[Project]` | `HTTPException` | app/api/project.py |
|
||
| `ProjectRouter.detail()` | 获取项目详情 | str id | `ProjectDetailResponse` | `HTTPException` | app/api/project.py |
|
||
| `ProjectService.create_project()` | 创建项目 | ProjectCreate 项目创建请求, str username | `Project` | `ServiceException` | app/services/project_service.py |
|
||
| `ProjectService.update_project()` | 更新项目 | str id, ProjectUpdate 项目更新请求, str username | `Project` | `ServiceException` | app/services/project_service.py |
|
||
| `ProjectService.delete_project()` | 删除项目 | str id | `bool` | `ServiceException` | app/services/project_service.py |
|
||
| `ProjectService.get_project_list()` | 获取项目列表 | ProjectQuery 查询参数 | `List[Project]` | `ServiceException` | app/services/project_service.py |
|
||
| `ProjectService.get_project_detail()` | 获取项目详情 | str id | `ProjectDetail` | `ServiceException` | app/services/project_service.py |
|
||
|
||
### 4.4 历史记录模块
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `HistoryRouter.list()` | 获取项目历史 | str project_id, HistoryQuery 查询参数 | `PageResponse[ProjectHistory]` | `HTTPException` | app/api/history.py |
|
||
| `HistoryService.record_history()` | 记录历史 | str project_id, str operation_type, str operator, dict changes | `ProjectHistory` | `ServiceException` | app/services/history_service.py |
|
||
| `HistoryService.get_project_history()` | 获取项目历史 | str project_id, HistoryQuery 查询参数 | `List[ProjectHistory]` | `ServiceException` | app/services/history_service.py |
|
||
|
||
### 4.5 统计模块
|
||
|
||
| 类/函数名 | 说明 | 参数（类型/含义） | 成功返回结构/类型 | 失败返回结构/类型 | 所属文件/模块 |
|
||
|-----------|------|-----------------|-----------------|-----------------|--------------|
|
||
| `StatisticsRouter.filter()` | 筛选项目 | ProjectFilter 筛选条件 | `PageResponse[Project]` | `HTTPException` | app/api/statistics.py |
|
||
| `StatisticsRouter.statistics()` | 统计项目 | StatisticsRequest 统计请求 | `StatisticsResponse` | `HTTPException` | app/api/statistics.py |
|
||
| `StatisticsService.filter_projects()` | 筛选项目 | ProjectFilter 筛选条件 | `List[Project]` | `ServiceException` | app/services/statistics_service.py |
|
||
| `StatisticsService.get_project_statistics()` | 获取项目统计 | StatisticsRequest 统计请求 | `StatisticsResult` | `ServiceException` | app/services/statistics_service.py |
|
||
|
||
---
|
||
|
||
## 5. 数据库设计
|
||
|
||
### 5.1 数据库表结构
|
||
|
||
详细的数据库表结构见《数据库设计文档》。
|
||
|
||
### 5.2 数据模型关系
|
||
|
||
```
|
||
User (用户)
|
||
|
|
||
| 1
|
||
|
|
||
| N
|
||
|
|
||
OperationLog (操作日志)
|
||
|
||
Project (项目)
|
||
|
|
||
| 1
|
||
|
|
||
| N
|
||
|
|
||
+-- ProjectMember (项目成员)
|
||
|
|
||
| 1
|
||
|
|
||
| N
|
||
|
|
||
+-- ProjectMilestone (项目里程碑)
|
||
|
|
||
| 1
|
||
|
|
||
| N
|
||
|
|
||
+-- ProjectRisk (项目风险)
|
||
|
|
||
| 1
|
||
|
|
||
| N
|
||
|
|
||
+-- ProjectHistory (项目历史)
|
||
```
|
||
|
||
### 5.3 数据库连接配置
|
||
|
||
- **开发环境**：使用本地MySQL数据库
|
||
- **测试环境**：使用测试MySQL数据库
|
||
- **生产环境**：使用生产MySQL数据库
|
||
|
||
---
|
||
|
||
## 6. API设计
|
||
|
||
### 6.1 认证API
|
||
|
||
| API路径 | 方法 | 模块/文件 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|----------|--------------|------------------|
|
||
| `/api/auth/login` | `POST` | `app/api/auth.py` | 用户登录 | `{"username": "admin", "password": "123456"}` | `{"code": 200, "data": {"token": "...", "userInfo": {...}}, "message": "登录成功"}` |
|
||
| `/api/auth/logout` | `POST` | `app/api/auth.py` | 用户退出 | N/A | `{"code": 200, "message": "退出成功"}` |
|
||
| `/api/auth/userInfo` | `GET` | `app/api/auth.py` | 获取用户信息 | N/A | `{"code": 200, "data": {"userId": "...", "username": "...", "realName": "...", "department": "...", "role": "..."}}` |
|
||
|
||
### 6.2 用户API
|
||
|
||
| API路径 | 方法 | 模块/文件 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|----------|--------------|------------------|
|
||
| `/api/user` | `GET` | `app/api/user.py` | 获取用户列表 | N/A (Query参数: page, size, username, department, role) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/user` | `POST` | `app/api/user.py` | 创建用户 | `{"username": "test", "password": "123456", "realName": "测试用户", "department": "技术部", "role": "OTHER"}` | `{"code": 200, "message": "创建成功"}` |
|
||
| `/api/user/{id}` | `PUT` | `app/api/user.py` | 更新用户 | `{"realName": "测试用户1", "department": "市场部", "role": "MARKETING"}` | `{"code": 200, "message": "更新成功"}` |
|
||
| `/api/user/{id}` | `DELETE` | `app/api/user.py` | 删除用户 | N/A | `{"code": 200, "message": "删除成功"}` |
|
||
| `/api/user/resetPassword/{id}` | `PUT` | `app/api/user.py` | 重置密码 | `{"password": "123456"}` | `{"code": 200, "message": "密码重置成功"}` |
|
||
|
||
### 6.3 项目API
|
||
|
||
| API路径 | 方法 | 模块/文件 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|----------|--------------|------------------|
|
||
| `/api/project` | `GET` | `app/api/project.py` | 获取项目列表 | N/A (Query参数: page, size, projectName, status, leader) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/project` | `POST` | `app/api/project.py` | 创建项目 | `{"projectName": "测试项目", "status": "NOT_STARTED", "leader": "张三", ...}` | `{"code": 200, "data": {"projectId": "..."}, "message": "创建成功"}` |
|
||
| `/api/project/{id}` | `GET` | `app/api/project.py` | 获取项目详情 | N/A | `{"code": 200, "data": {...}, "message": "查询成功"}` |
|
||
| `/api/project/{id}` | `PUT` | `app/api/project.py` | 更新项目 | `{"projectName": "测试项目1", "status": "IN_PROGRESS", ...}` | `{"code": 200, "message": "更新成功"}` |
|
||
| `/api/project/{id}` | `DELETE` | `app/api/project.py` | 删除项目 | N/A | `{"code": 200, "message": "删除成功"}` |
|
||
|
||
### 6.4 历史记录API
|
||
|
||
| API路径 | 方法 | 模块/文件 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|----------|--------------|------------------|
|
||
| `/api/history/{projectId}` | `GET` | `app/api/history.py` | 获取项目历史 | N/A (Query参数: page, size, operator, startDate, endDate) | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
|
||
### 6.5 统计API
|
||
|
||
| API路径 | 方法 | 模块/文件 | 功能描述 | 请求体 (JSON) | 成功响应 (200 OK) |
|
||
|---------|------|-----------|----------|--------------|------------------|
|
||
| `/api/statistics/filter` | `POST` | `app/api/statistics.py` | 筛选项目 | `{"projectNo": "PRJ2025001", "projectName": "测试", "status": "IN_PROGRESS", ...}` | `{"code": 200, "data": [{...}], "total": 10, "message": "查询成功"}` |
|
||
| `/api/statistics/statistics` | `POST` | `app/api/statistics.py` | 统计项目 | `{"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 开发环境部署
|
||
|
||
1. 克隆代码库: `git clone <repository-url>`
|
||
2. 安装依赖: `poetry install` 或 `pip install -r requirements.txt`
|
||
3. 配置环境变量: 复制 `.env.example` 为 `.env` 并修改配置
|
||
4. 初始化数据库: `alembic upgrade head`
|
||
5. 启动应用: `uvicorn app.main:app --reload`
|
||
6. 访问: `http://localhost:8000`
|
||
7. API文档: `http://localhost:8000/docs`
|
||
|
||
### 8.2 生产环境部署
|
||
|
||
1. 克隆代码库: `git clone <repository-url>`
|
||
2. 安装依赖: `poetry install --no-dev` 或 `pip install -r requirements.txt`
|
||
3. 配置环境变量: 复制 `.env.example` 为 `.env` 并修改配置
|
||
4. 初始化数据库: `alembic upgrade head`
|
||
5. 构建应用: 无需构建，直接运行
|
||
6. 启动应用: `gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker`
|
||
7. 配置 Nginx 反向代理
|
||
|
||
### 8.3 集成方案
|
||
|
||
- **前端与后端集成**: 通过 RESTful API 进行数据交互
|
||
- **数据库集成**: 使用 SQLAlchemy ORM 操作数据库
|
||
- **日志集成**: 使用 Python logging 模块记录系统日志
|
||
- **监控集成**: 可集成 Prometheus + Grafana 监控系统性能
|
||
|
||
---
|
||
|
||
## 9. 性能优化
|
||
|
||
### 9.1 代码优化
|
||
|
||
- **异步处理**: 使用 FastAPI 的异步特性，提高并发处理能力
|
||
- **批量操作**: 对批量数据操作使用批量处理，减少数据库交互次数
|
||
- **缓存**: 对热点数据使用内存缓存，减少数据库查询
|
||
- **分页查询**: 使用分页查询，避免一次性加载大量数据
|
||
|
||
### 9.2 数据库优化
|
||
|
||
- **索引优化**: 为常用查询字段创建索引，提高查询性能
|
||
- **连接池**: 使用 SQLAlchemy 的连接池，提高数据库连接效率
|
||
- **查询优化**: 使用 SQLAlchemy 的 lazy loading 和 eager loading 优化查询
|
||
- **数据库配置**: 优化 MySQL 配置参数，提高数据库性能
|
||
|
||
### 9.3 部署优化
|
||
|
||
- **负载均衡**: 对多实例部署使用负载均衡
|
||
- **水平扩展**: 根据业务需求进行水平扩展
|
||
- **资源限制**: 合理设置应用的资源限制（CPU、内存等）
|
||
|
||
---
|
||
|
||
## 10. 监控与维护
|
||
|
||
### 10.1 系统监控
|
||
|
||
- **应用监控**: 监控应用的运行状态、CPU、内存使用情况
|
||
- **数据库监控**: 监控数据库的连接数、查询性能、存储空间
|
||
- **API监控**: 监控 API 的响应时间、调用次数、错误率
|
||
- **日志监控**: 监控系统日志，及时发现异常情况
|
||
|
||
### 10.2 故障处理
|
||
|
||
- **故障定位**: 通过日志和监控工具定位故障原因
|
||
- **故障恢复**: 制定故障恢复方案，确保系统快速恢复
|
||
- **故障预防**: 定期进行系统检查，预防故障发生
|
||
|
||
### 10.3 系统维护
|
||
|
||
- **定期更新**: 定期更新依赖库和框架版本，修复安全漏洞
|
||
- **数据备份**: 定期备份数据库，防止数据丢失
|
||
- **性能调优**: 定期分析系统性能，进行性能调优
|
||
- **文档更新**: 及时更新系统文档，保持文档与系统同步
|
||
|
||
---
|
||
|
||
## 11. 开发规范
|
||
|
||
### 11.1 代码规范
|
||
|
||
- **代码风格**: 遵循 PEP 8 规范
|
||
- **命名规范**:
|
||
- 类名: 大驼峰命名法 (PascalCase)
|
||
- 函数名: 小驼峰命名法 (camelCase)
|
||
- 变量名: 小写下划线分隔 (snake_case)
|
||
- 常量名: 全大写下划线分隔 (SNAKE_CASE)
|
||
- **注释规范**: 为所有公共函数和类添加文档字符串
|
||
- **导入规范**: 分组导入，按标准库、第三方库、本地模块顺序
|
||
|
||
### 11.2 版本控制
|
||
|
||
- **分支管理**: 使用 Git Flow 分支管理策略
|
||
- **提交规范**: 提交信息使用英文，格式为 `[类型]: 描述`
|
||
- **版本号**: 使用语义化版本号 (Semantic Versioning)
|
||
|
||
### 11.3 测试规范
|
||
|
||
- **测试覆盖率**: 核心功能测试覆盖率不低于 80%
|
||
- **测试类型**: 单元测试、集成测试、端到端测试
|
||
- **测试框架**: 使用 Pytest 进行测试
|
||
|
||
---
|
||
|
||
## 12. 附录
|
||
|
||
### 12.1 技术选型对比
|
||
|
||
| 技术 | 对比方案 | 最终选择理由 |
|
||
|------|----------|--------------|
|
||
| 后端框架 | FastAPI vs Flask vs Django | FastAPI 高性能，自动生成API文档，支持异步 |
|
||
| ORM框架 | SQLAlchemy vs Django ORM | SQLAlchemy 灵活强大，支持多种数据库 |
|
||
| 数据库 | MySQL vs PostgreSQL | MySQL 社区活跃，生态成熟，适合企业级应用 |
|
||
| 认证 | JWT vs Session | JWT 无状态，便于水平扩展 |
|
||
| 构建工具 | Poetry vs pip | Poetry 提供更好的依赖管理和版本控制 |
|
||
|
||
### 12.2 常用命令
|
||
|
||
- **安装依赖**: `poetry install` 或 `pip install -r requirements.txt`
|
||
- **添加依赖**: `poetry add <package>` 或 `pip install <package>`
|
||
- **启动开发服务器**: `uvicorn app.main:app --reload`
|
||
- **运行测试**: `pytest`
|
||
- **生成数据库迁移**: `alembic revision --autogenerate -m "描述"`
|
||
- **执行数据库迁移**: `alembic upgrade head`
|
||
|
||
### 12.3 变更记录
|
||
|
||
| 版本 | 日期 | 修改人 | 修改内容 |
|
||
|------|------|--------|----------|
|
||
| V1.0 | 2026-01-26 | - | 初始版本创建 |
|