# 技术选型说明

本章详细阐述系统各技术组件的选型理由、与同类主流方案的对比分析，以及版本约束说明，旨在帮助开发者理解技术选型的依据与权衡，确保团队在技术决策上达成共识，并为后续的技术演进提供参考依据。

## 后端框架选型

### Flask

:::tip 为什么选择 Flask？
Flask 是 Python 生态中最轻量、最灵活的 Web 框架，基于 WSGI 同步模型，成熟稳定，易于调试和部署。对于后台管理系统这类以 CRUD 为主的场景，Flask 的简洁性和可扩展性表现优异。
:::

| 特性 | 说明 |
|:---|:---|
| **轻量灵活** | 核心概念少，学习曲线平缓，易于上手 |
| **成熟稳定** | 基于 WSGI 同步模型，经过长期验证，稳定可靠 |
| **扩展丰富** | Flask 扩展生态完善，支持各种功能扩展 |
| **蓝图机制** | Blueprint 实现模块化路由组织，便于大型项目管理 |
| **中间件支持** | 支持请求/响应钩子，便于实现认证、日志等横切关注点 |
| **多数据库支持** | 通过 SQLAlchemy ORM 支持多种数据库方言 |
| **易于部署** | WSGI 标准，支持 Gunicorn、uWSGI 等多种服务器 |

### 选择 Flask 的核心理由

1. **成熟稳定**：Flask 是 Python Web 框架中最成熟的选择之一，社区活跃，文档完善
2. **轻量灵活**：核心简洁，不强制绑定特定组件，便于根据项目需求定制
3. **蓝图机制**：Blueprint 实现模块化路由组织，便于大型项目管理
4. **同步模型**：同步编程模型更易于理解和调试，适合后台管理系统场景
5. **易于部署**：WSGI 标准，支持多种部署方式，生产环境部署简单

## ORM 选型

### SQLAlchemy 2.0

:::tip 为什么选择 SQLAlchemy？
SQLAlchemy 是 Python 生态中最成熟、功能最完备的 ORM 框架，2.0 版本统一了 Core 和 ORM 的 API 风格，同时保持了对多种数据库方言的原生支持。
:::

| 特性 | 说明 |
|:---|:---|
| **声明式模型** | 基于 `declarative_base()` 定义模型类，字段与数据库列一一映射 |
| **多数据库方言** | 通过 `DB_DRIVER` 切换 MySQL / PostgreSQL / SQL Server / SQLite / Oracle |
| **会话管理** | `db.session` + Flask 请求级会话隔离（AOP 事务中间件自动管理） |
| **连接池** | 内置连接池（`QueuePool`），支持连接池配置 |
| **软删除** | 通过 `is_delete` 字段 + Repository 基类自动过滤实现 |
| **事务控制** | AOP 中间件自动 commit/rollback，业务代码无需手动管理 |

版本约束：`SQLAlchemy >= 2.0.51`

## 请求校验选型

### WTForms

| 特性 | 说明 |
|:---|:---|
| **声明式校验** | 通过 `BaseForm` + `validators` 声明字段约束，自动校验 |
| **自定义验证器** | `validate_` 方法支持复杂的业务校验逻辑（如唯一性检查） |
| **错误聚合** | 自动收集所有校验错误，返回统一错误信息 |
| **易于集成** | 与 Flask 无缝集成，社区支持完善 |
| **类型安全** | 支持各种字段类型：StringField、IntegerField、SelectField 等 |

版本约束：`WTForms >= 3.0.0`

## 前端技术栈

### Vue3 + Vite + ElementPlus

| 组件 | 版本 | 选型理由 |
|:---|:---|:---|
| **Vue3** | 3.x | Composition API、更好的 TypeScript 支持、Teleport/Suspense 等新特性 |
| **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 令牌黑名单、登录失败锁定、请求限流计数、数据字典缓存、权限缓存等。采用同步客户端与 Flask 的同步模型无缝集成。
:::

| 用途 | 数据结构 | 过期策略 |
|:---|:---|:---|
| JWT 黑名单 | String | 等于 Token 剩余有效期 |
| 登录失败锁 | String | 指定锁定时长 |
| 滑动窗口限流 | String (Lua) | 2 倍窗口时长 |
| 数据字典缓存 | String (JSON) | TTL 可配置 |
| 权限列表缓存 | String (JSON) | 变更时主动失效 |

版本约束：`redis >= 5.0.0`

## 定时任务

### APScheduler

| 特性 | 说明 |
|:---|:---|
| **调度策略** | 支持 Cron、Interval、Date 三种触发器 |
| **持久化** | 任务定义存储在数据库，重启后自动恢复 |
| **分布式锁** | 通过 Redis 实现多实例互斥，避免重复执行 |
| **日志记录** | 每次执行记录到 `flask_job_log` 表 |

### Cron 表达式格式

项目支持 **5 字段**和 **6 字段**两种 Cron 表达式，6 字段首字段为秒：

| 字段 | 5 字段格式 | 6 字段格式 | 允许值 | 允许的特殊字符 |
|:----|:----|:----|:----|:----|
| 秒 | - | 第 1 位 | 0-59 | `, - * /` |
| 分钟 | 第 1 位 | 第 2 位 | 0-59 | `, - * /` |
| 小时 | 第 2 位 | 第 3 位 | 0-23 | `, - * /` |
| 日 | 第 3 位 | 第 4 位 | 1-31 | `, - * / ? L W` |
| 月 | 第 4 位 | 第 5 位 | 1-12 | `, - * /` |
| 星期 | 第 5 位 | 第 6 位 | 0-7（0 和 7 均为周日） | `, - * / ? L #` |

### 特殊字符说明

| 字符 | 含义 | 示例 |
|:----|:----|:----|
| `*` | 所有值 | `* * * * *` = 每分钟 |
| `?` | 不指定（用于日和星期互斥） | `0 0 0 * * ?` = 每天 0 点，星期不指定 |
| `-` | 范围 | `1-5` = 1 到 5 |
| `,` | 列举 | `1,3,5` = 1、3、5 |
| `/` | 步长 | `*/5` = 每隔 5 个单位 |
| `L` | 最后（Last） | `L` 在日字段 = 月末；`5L` 在星期字段 = 最后一个周五 |
| `W` | 最近工作日（Weekday） | `15W` = 离 15 号最近的工作日 |
| `#` | 第几个星期几 | `6#3` = 第 3 个周五（6=周五） |

### 常用 Cron 表达式示例

**基础频率**

| 表达式 | 说明 |
|:----|:----|
| `* * * * *` | 每分钟执行 |
| `*/5 * * * *` | 每 5 分钟执行 |
| `0 * * * *` | 每小时整点执行 |
| `0 */2 * * *` | 每 2 小时执行 |
| `0 0 * * *` | 每天凌晨 0 点执行 |
| `0 0 */1 * *` | 每天凌晨 0 点（同上） |

**每天定时**

| 表达式 | 说明 |
|:----|:----|
| `0 8 * * *` | 每天早上 8:00 |
| `0 12 * * *` | 每天中午 12:00 |
| `0 18 * * *` | 每天下午 18:00 |
| `0 0 * * *` | 每天凌晨 0:00 |
| `30 9 * * *` | 每天早上 9:30 |
| `0 9,18 * * *` | 每天 9:00 和 18:00（上下班提醒） |
| `0 8-18 * * *` | 每天 8:00 到 18:00 整点（工作时间每小时） |

**每周定时**

| 表达式 | 说明 |
|:----|:----|
| `0 0 * * 0` | 每周日凌晨 0:00 |
| `0 9 * * 1` | 每周一早上 9:00 |
| `0 9 * * 1-5` | 工作日（周一到周五）早上 9:00 |
| `0 9 * * 1,3,5` | 周一、周三、周五早上 9:00 |
| `0 0 * * 6L` | 每月最后一个周六凌晨 0:00 |

**每月定时**

| 表达式 | 说明 |
|:----|:----|
| `0 0 1 * *` | 每月 1 号凌晨 0:00 |
| `0 0 15 * *` | 每月 15 号凌晨 0:00 |
| `0 0 L * *` | 每月最后一天凌晨 0:00 |
| `0 9 1,15 * *` | 每月 1 号和 15 号早上 9:00 |
| `0 0 1 1,4,7,10 *` | 每季度首月 1 号凌晨（季度报表） |

**秒级触发（6 字段）**

| 表达式 | 说明 |
|:----|:----|
| `*/30 * * * * *` | 每 30 秒执行 |
| `0 */5 * * * *` | 每 5 分钟整点执行（等同 5 字段 `*/5 * * * *`） |
| `0 0 9 * * *` | 每天 9:00:00 整秒执行 |
| `0 30 8 * * 1-5` | 工作日 8:30:00 执行 |
| `*/10 * 8-18 * * *` | 工作时间每 10 秒执行（高频监控） |

**业务场景示例**

| 场景 | 表达式 | 说明 |
|:----|:----|:----|
| 数据库备份 | `0 2 * * *` | 每天凌晨 2:00 备份 |
| 日志清理 | `0 3 * * 0` | 每周日凌晨 3:00 清理过期日志 |
| 月度报表 | `0 8 1 * *` | 每月 1 号早上 8:00 生成报表 |
| 心跳检测 | `*/5 * * * *` | 每 5 分钟检测服务状态 |
| 缓存刷新 | `0 */6 * * *` | 每 6 小时刷新一次缓存 |
| 工作日签到提醒 | `0 9 * * 1-5` | 工作日早上 9:00 发送提醒 |
| 订单超时检查 | `*/30 * * * *` | 每 30 秒检查超时未支付订单 |
| 定时推送 | `0 20 * * *` | 每天晚上 8:00 推送消息 |

### 常见错误

| 错误写法 | 问题 | 正确写法 |
|:----|:----|:----|
| `0 0 0 * * * *` | 7 个字段，非法 | `0 0 0 * * *`（6 字段）或 `0 0 * * *`（5 字段） |
| `0 0 * * 7` | 星期 7 超出范围 | `0 0 * * 0`（0 和 7 均为周日，但推荐用 0） |
| `0 0 32 * *` | 日 32 超出范围 | `0 0 1-31 * *` |
| `0 0 * 13 *` | 月 13 超出范围 | `0 0 * 1-12 *` |
| `*/0 * * * *` | 步长不能为 0 | `*/1 * * * *` |

## 其他关键依赖

| 依赖 | 版本 | 用途 |
|:---|:---|:---|
| `Flask` | >= 3.1.1 | Web 框架，`src/app.py` 通过 `create_app()` 创建应用 |
| `PyJWT` | >= 2.13.0 | JWT 令牌签发与验证（HS256 算法），`src/core/jwt.py` |
| `bcrypt` | >= 4.0.0 | 密码哈希（带随机盐），`src/core/password.py` |
| `openpyxl` | >= 3.1.0 | Excel 导入导出，文件上传/下载模块使用 |
| `Pillow` | >= 10.0.0 | 验证码图片生成，`src/common/utils/captcha.py` |
| `python-dotenv` | >= 1.0.0 | `.env` 配置文件加载，`config/__init__.py` 首先调用 `load_dotenv()` |
| `Flask-Migrate` | >= 4.0.0 | 数据库迁移，`migrations/` 目录，`scripts/setup_db.py` 末尾调用 `flask db stamp head` |
| `APScheduler` | >= 3.10.0 | 定时任务调度，`src/core/scheduler.py`，在 `create_app()` 中初始化 |
| `bleach` | >= 6.0.0 | 富文本 XSS 清洗，`src/common/utils/rich_text.py` 的 `sanitize_html()` |
| `Gunicorn` | >= 22.0.0 | WSGI 服务器，生产环境部署使用 |

## 版本锁定策略

:::warning 版本管理
所有依赖版本在 `requirements.txt` 中锁定最低版本（`>=x.y.z`），确保兼容性的同时允许安全补丁升级。生产环境建议使用 `pip freeze` 生成精确版本锁文件。
:::

## 总结

项目的技术选型以「稳定可靠、轻量灵活、可扩展」为核心原则。Flask + SQLAlchemy 2.0 + WTForms 构成后端铁三角，Vue3 + Vite + ElementPlus 提供现代化前端体验，Redis 承担缓存与中间件职责。各组件版本经过充分测试验证，形成稳定的技术底座。选型时优先考虑组件的独立性和可替换性，避免强耦合，为未来的架构演进预留空间。