xsl/xsl_node
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
884b9f47a2ce936a49f6c9f7010eb8bce626d32b
xsl_node/backend/docs/后端技术架构文档.md
T
Your Name 40d2f3f6ac save code
2026-01-26 12:29:56 +08:00

24 KiB
Raw Blame History

后端技术架构文档

文档信息

  • 文档版本: 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 - 初始版本创建
Reference in New Issue View Git Blame Copy Permalink