签入版本

2026-09-16 13:28:20 +08:00
parent 6cd5e80de0
commit c97d87847f
410 changed files with 68726 additions and 0 deletions
@@ -0,0 +1,133 @@
+# 技术选型说明
+
+本章详细阐述系统各技术组件的选型理由与版本约束说明，旨在帮助开发者理解技术选型的依据与权衡。
+
+## 后端框架选型
+
+### Tornado
+
+:::tip 为什么选择 Tornado？
+Tornado 是 Python 生态中成熟的异步 Web 框架，基于自有事件循环实现非阻塞 I/O。对于后台管理系统这类以 CRUD 为主的场景，Tornado 的轻量灵活和稳定可靠使其成为理想选择。
+:::
+
+| 特性 | 说明 |
+|:---|:---|
+| **原生异步** | 基于自有事件循环，`async/await` 一等公民，充分利用 I/O 等待时间 |
+| **请求校验** | Pydantic v2 声明式校验，Service 层自动执行 |
+| **类型安全** | 全链路类型提示，IDE 补全完善 |
+| **轻量灵活** | 核心概念少，无强依赖，学习曲线平缓 |
+| **稳定可靠** | 成熟的生产级框架，广泛应用于高并发场景 |
+
+### 选择 Tornado 的核心理由
+
+1. **原生异步**：后台管理系统需要处理并发请求（文件上传、批量操作、定时任务），Tornado 的原生异步模型能充分利用 I/O 等待时间
+2. **Pydantic 校验**：声明式的数据校验，减少参数校验代码量
+3. **SQLAlchemy 解耦**：ORM 不与框架强绑定，支持多数据库驱动切换（MySQL / PostgreSQL / SQL Server / SQLite / Oracle）
+4. **轻量灵活**：无强依赖，核心概念少，易于理解和扩展
+5. **稳定可靠**：经过多年生产验证的成熟框架
+
+## ORM 选型
+
+### SQLAlchemy 2.0
+
+:::tip 为什么选择 SQLAlchemy？
+SQLAlchemy 是 Python 生态中最成熟、功能最完备的 ORM 框架，2.0 版本统一了 Core 和 ORM 的 API 风格，同时保持了对多种数据库方言的原生支持。
+:::
+
+| 特性 | 说明 |
+|:---|:---|
+| **声明式模型** | 基于 `declarative_base()` 定义模型类，字段与数据库列一一映射 |
+| **多数据库方言** | 通过 `DB_DRIVER` 切换 MySQL / PostgreSQL / SQL Server / SQLite / Oracle |
+| **会话管理** | `scoped_session` + thread-local 实现请求级会话隔离 |
+| **连接池** | 内置连接池（`QueuePool`），支持 `POOL_SIZE` / `MAX_OVERFLOW` 配置 |
+| **软删除** | 通过 `is_delete` 字段 + Repository 基类自动过滤实现 |
+| **读写分离** | 支持写引擎 + 读引擎分离，通过 `READ_DATABASE_URL` 配置 |
+
+版本约束：`SQLAlchemy >= 2.0.51`
+
+## 请求校验选型
+
+### Pydantic v2
+
+| 特性 | 说明 |
+|:---|:---|
+| **声明式校验** | 通过 `BaseModel` + `Field(...)` 声明字段约束，自动校验 |
+| **自定义验证器** | `@field_validator` 支持复杂的业务校验逻辑 |
+| **高性能** | v2 核心用 Rust 重写，校验速度较 v1 提升 5-50 倍 |
+| **错误聚合** | Service 层 `validate()` 方法将校验错误提取为统一提示 |
+
+版本约束：`pydantic >= 2.13.4`
+
+## 前端技术栈
+
+### Vue3 + Vite + ElementPlus
+
+| 组件 | 版本 | 选型理由 |
+|:---|:---|:---|
+| **Vue3** | 3.x | Composition API、更好的 TypeScript 支持 |
+| **Vite** | 5.x | 极速 HMR、ESM 原生支持、开箱即用的 TypeScript 支持 |
+| **ElementPlus** | 2.x | Vue3 生态最成熟的 UI 组件库，企业级后台管理系统首选 |
+| **Pinia** | 2.x | Vue3 官方推荐的状态管理方案，替代 Vuex |
+| **Vue Router** | 4.x | Vue3 官方路由，支持动态路由、路由守卫 |
+| **Axios** | 1.x | HTTP 客户端，支持请求/响应拦截器、取消请求 |
+
+## 缓存与消息中间件
+
+### Redis
+
+:::tip Redis 在系统中的角色
+Redis 在系统中承担多个关键职责：JWT 令牌黑名单、登录失败锁定、数据字典缓存、权限缓存等。采用同步客户端（`redis`）与全站同步 DB/Redis 调用风格一致。
+:::
+
+| 用途 | 数据结构 | 过期策略 |
+|:---|:---|:---|
+| JWT 黑名单 | String | 等于 Token 剩余有效期 |
+| 登录失败锁 | String | 指定锁定时长 |
+| 数据字典缓存 | String (JSON) | TTL 可配置 |
+| 权限列表缓存 | String (JSON) | 变更时主动失效（按版本号） |
+
+版本约束：`redis >= 5.0.0`（同步客户端）
+
+## 定时任务
+
+### APScheduler
+
+| 特性 | 说明 |
+|:---|:---|
+| **调度策略** | 支持 Cron、Interval、Date 三种触发器 |
+| **持久化** | 任务定义存储在数据库，重启后自动恢复 |
+| **日志记录** | 每次执行记录到 `tornado_job_log` 表 |
+
+## 密码安全
+
+### bcrypt 双盐方案
+
+| 特性 | 说明 |
+|:---|:---|
+| **双盐机制** | 系统生成随机盐 + bcrypt 自带盐，双重保护 |
+| **自动升级** | 登录时检测旧版无盐哈希，自动升级为双盐方案 |
+| **安全存储** | 盐值存储在用户表 `salt` 字段，哈希存储在 `password` 字段 |
+
+## 其他关键依赖
+
+| 依赖 | 用途 |
+|:---|:---|
+| `PyJWT` | JWT 令牌签发与验证（HS256 算法），`src/core/jwt.py` |
+| `bcrypt` | 密码哈希（带随机盐），`src/core/password.py` |
+| `openpyxl` | Excel 导入导出 |
+| `Pillow` | 验证码图片生成，`src/common/utils/captcha.py` |
+| `python-dotenv` | `.env` 配置文件加载 |
+| `alembic` | 数据库迁移，`migrations/` 目录 |
+| `APScheduler` | 定时任务调度，`src/modules/job/scheduler.py` |
+| `bleach` | 富文本 XSS 清洗，`src/common/utils/rich_text.py` |
+| `ip2region` | IP 地理位置解析，`src/common/utils/ip2region.py` |
+
+## 版本锁定策略
+
+:::warning 版本管理
+所有依赖版本在 `pyproject.toml` 中锁定（Poetry 管理），`requirements.txt` 为 UTF-8 降级副本。生产环境建议使用 `poetry export` 生成精确版本锁文件。
+:::
+
+## 总结
+
+项目的技术选型以「高性能、类型安全、可扩展」为核心原则。Tornado + SQLAlchemy 2.0 + Pydantic v2 构成后端铁三角，Vue3 + Vite + ElementPlus 提供现代化前端体验，Redis 承担缓存与中间件职责。各组件版本经过充分测试验证，形成稳定的技术底座。选型时优先考虑组件的独立性和可替换性，避免强耦合，为未来的架构演进预留空间。