# 更新日志

:::tip 说明
更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。对于开发者，可快速掌握新功能与 API 变更，降低升级成本；对于企业，可评估版本稳定性与功能成熟度，为技术选型和升级决策提供依据。建议在升级前阅读目标版本的变更内容，确保业务代码平滑适配。
:::

## 版本总览

| 版本 | 日期 | 主要内容 |
|:-----|:-----|:---------|
| 2.0.0 | 2024-04-12 | Tornado 重构，Vue3 前后端分离奠基 |
| 2.1.0 | 2024-07-18 | RBAC 权限体系 + JWT 认证 |
| 2.2.0 | 2024-10-25 | 系统配置 + 字典增强 + 部门树 |
| 2.3.0 | 2025-01-08 | 内容管理 + XSS 防护 + 富文本 |
| 2.4.0 | 2025-03-22 | 多数据库 + SQLAlchemy 2.0 + Docker |
| 2.5.0 | 2025-06-15 | Vue3 升级 + TypeScript + Vite |
| 2.6.0 | 2025-09-03 | 代码生成器 + Excel 导入导出 |
| 2.7.0 | 2025-12-19 | 定时任务 + 操作日志 + 登录日志 |
| 2.8.0 | 2026-03-07 | 接口限流 + IP 地理 + 安全增强 |
| 2.9.0 | 2026-06-23 | 文档体系 + 契约测试 + 缓存优化 |
| **3.0.0** | **2026-09-01** | **架构重构：三层分离 + 基类体系** |


## [3.0.0] - 2026-09-01

**架构全面升级，奠定企业级框架基础。**

### 新增

- **模块化分层架构**：业务模块按功能域分组（`system` / `tool` / `module`），职责清晰、可插拔扩展
- **三层分离设计**：Endpoint（HTTP 接口层）→ Service（业务逻辑层）→ Repository（数据访问层），依赖单向传递，业务代码与框架核心完全解耦
- **基类体系**：`BaseRepository` 提供 30+ 通用数据访问方法（CRUD、分页、软删除、条件查询）；`BaseService` 封装唯一性校验、字段组装、序列化、缓存管理等通用业务逻辑。业务模块仅需 **4 个文件 + 1 行注册** 即可完成模块接入
- **Handler 生命周期 + 装饰器**：CORS 跨域、JWT 认证、RBAC 权限、操作日志通过 Handler 生命周期方法和装饰器实现，职责单一，可插拔配置
- **Repository 数据访问层全面落地**：业务代码与 SQLAlchemy ORM 彻底解耦，切换数据库或 ORM 框架对业务代码零影响
- **契约测试体系**：路由快照、权限快照、表名快照三管齐下，自动守护接口契约，避免重构引发的接口漂移
- **集成测试框架**：事务一致性验证 + 操作日志自动校验，确保核心业务流程稳定可靠
- **跨库数据迁移工具**（`scripts/migrate_db.py`）：支持 MySQL / PostgreSQL / SQL Server / SQLite / Oracle 间的全量或增量数据迁移，含表结构同步与数据泵送
- **数据库版本化迁移**：基于 Alembic，Schema 变更可追溯、可回滚，支持多环境发布
- **统一文件上传接口**：单一接口支持图片、文档、压缩包等全类型文件，流式校验，超限立即中断，避免内存溢出
- **文件安全防护**：扩展名白名单 + 魔术字节（Magic Number）校验 + 路径遍历防护 + 高危格式拦截（如 `.php`、`.jsp` 等）

### 优化

- 查询方法自动过滤软删除记录（`is_delete=True`），自动跳过空值查询条件，减少业务代码冗余
- 批量删除统一响应格式，前后端文案保持一致
- API 响应格式全面标准化（`code / msg / data`），前端解析零歧义
- 文件上传流式大小校验，超限立即中断，避免大文件耗尽服务器内存
- 配置项命名规范统一，遵循 `{模块}_{功能}_{属性}` 命名约定
- 代码生成器模板同步适配三层架构，生成代码开箱即用

### 修复

- 上传接口参数缺失时未返回明确错误提示，现已补充完整参数校验与错误文案
- Excel 导入时响应解析异常，修复数据类型映射逻辑
- 数据表字段约束冲突，修复迁移脚本中字段定义重复问题


## [2.9.0] - 2026-06-23

**文档体系与质量保障能力建设。**

### 新增

- **企业级文档体系**：127 篇技术文档，覆盖快速入门、模块开发、架构设计、运维部署、规范标准全场景
- **数据字典驱动**：字典编码自动映射显示文本，前端零配置，支持运行时刷新
- **权限缓存主动失效**：权限变更实时生效，支持版本号兜底机制，极端场景下自动降级
- **前端组件库文档化**：核心组件完整的 Props、Events、Slots 说明，含使用示例
- **API 接口速查表**：按模块分组的接口清单，含路径、方法、权限标识、请求/响应示例
- **多环境配置示例**：提供开发、测试、生产三套完整配置模板

### 优化

- 登录锁定策略：按 IP 与用户名组合统计失败次数，避免单一维度误锁
- 会话管理：异常时自动回滚事务，防止数据库连接泄露
- Token 续签：过期前 5 分钟自动刷新，用户无感知续期
- 代码生成器：生成代码风格与手写代码一致，缩进与命名规范完全统一

### 修复

- 权限缓存刷新延迟，变更后最长 3 秒生效
- Token 续签并发竞态，添加分布式锁保护
- 代码生成器遗漏唯一性校验声明，现已自动生成


## [2.8.0] - 2026-03-07

**安全防护与可观测性增强。**

### 新增

- **IP 地理位置查询**：基于离线 GeoIP 数据库，服务启动时加载内存，查询零延迟，无外部 API 依赖
- **User-Agent 解析**：自动识别客户端操作系统类型与版本、浏览器名称与版本
- **接口限流**：基于 Redis 滑动窗口的按 IP 限流策略，支持按接口独立配置阈值，防刷防滥用
- **操作日志自动记录**：所有写操作（POST / PUT / DELETE）自动捕获请求参数与响应结果，无需手动埋点
- **验证码防刷**：按 IP 频率控制，单 IP 每分钟最多获取 5 次验证码，超限拒绝生成

### 优化

- JWT 认证增强：支持令牌主动刷新与黑名单机制，登出后令牌立即失效
- 权限校验：管理员账号（`is_superuser=True`）自动放行所有权限校验
- 会话管理：请求级事务自动提交与回滚，异常时自动回滚，无需手动处理
- 文件上传安全：扩展名白名单与流式大小校验双重防护

### 修复

- 令牌刷新后旧令牌未加入黑名单，现已修复
- 大文件上传超时，调整 Nginx 与 Tornado 超时参数
- 并发请求会话泄露，修复会话绑定逻辑


## [2.7.0] - 2025-12-19

**定时任务与日志审计能力上线。**

### 新增

- **定时任务调度**：支持 Cron 表达式、固定间隔、指定时间三种触发方式，基于 APScheduler 实现
- **任务执行日志**：完整记录每次执行的开始时间、结束时间、执行状态、耗时、错误详情
- **登录日志**：记录所有登录与退出行为，含 IP 地址、地理位置、设备信息、登录结果
- **数据字典缓存**：Redis 缓存加速字典查询，支持手动刷新与变更自动失效
- **权限列表缓存**：变更时主动失效，保障权限数据实时性

### 优化

- 定时任务分布式锁：多实例部署时基于 Redis 分布式锁避免任务重复执行
- 字典查询：支持按编码直接获取字典项列表，无需逐条查询
- 系统配置：运行时动态修改，无需重启服务生效

### 修复

- 定时任务夏令时偏移，修复 Cron 表达式在夏令时切换日的执行偏差
- 字典项排序不生效，修复排序字段映射错误
- 配置值包含特殊字符时序列化异常，已修复


## [2.6.0] - 2025-09-03

**代码生成能力上线，开发效率大幅提升。**

### 新增

- **代码生成器（CLI）**：根据数据库表结构一键生成 Model、Repository、Service、Endpoint 及前端页面完整代码
- **代码生成器（Web UI）**：可视化操作界面，支持单表生成与批量生成
- **自定义模板引擎**：基于 Jinja2，支持自定义生成代码风格与目录结构
- **Excel 导入导出**：支持模板下载、数据校验、错误行跳过与错误详情导出
- **文件模板管理**：支持模板文件上传、版本管理与在线编辑

### 优化

- 代码生成器自动注册路由与权限节点，生成即用
- 生成代码自动适配分层架构（Endpoint / Service / Repository）
- Excel 导入数据校验增强：支持必填、唯一性、长度、正则表达式等多种校验规则

### 修复

- 生成代码唯一性校验遗漏字段，已补全
- Excel 导出日期格式不一致（如 `2025-09-01` 与 `09/01/2025`），现已统一为 `YYYY-MM-DD HH:mm:ss`
- 模板渲染中文乱码，统一文件编码为 UTF-8


## [2.5.0] - 2025-06-15

**前端技术栈全面升级至 Vue3 生态。**

### 新增

- **Vue3 升级**：前端框架从 Vue 2 升级至 Vue3.4+，全面拥抱 Composition API
- **ElementPlus**：UI 组件库适配 Vue3 生态
- **Pinia 状态管理**：替代 Vuex，更轻量、更灵活、TypeScript 支持更完善
- **TypeScript 类型安全**：全量类型定义，IDE 智能提示与编译时类型检查
- **Vite 构建工具**：替代 Webpack，开发服务器毫秒级启动，HMR 即时生效

### 优化

- 构建速度：Vite 开发服务器启动时间 < 500ms，热更新 < 100ms
- 代码规范：ESLint + Prettier + Stylelint 统一代码风格
- 组件体系：可插拔架构重构，按需加载，首屏加载体积减少 40%

### 修复

- 热更新偶尔失效，修复 HMR 边界条件
- TypeScript 类型定义不完整，补全 200+ 类型声明
- 部分组件样式在 Vue3 下兼容性问题，已修复


## [2.4.0] - 2025-03-22

**多数据库与企业级部署能力增强。**

### 新增

- **多数据库支持**：通过 `DB_DRIVER` 环境变量一键切换 MySQL / PostgreSQL / SQL Server / SQLite / Oracle，业务代码零改动
- **SQLAlchemy 2.0**：升级至 SQLAlchemy 2.0+，声明式映射，统一 Core 与 ORM 接口
- **Pydantic v2**：校验性能提升 5-10 倍（Rust 核心重写），类型提示更丰富
- **Docker 容器化**：提供 Dockerfile + docker-compose.yml，支持一键启动完整环境

### 优化

- 数据库连接池参数可调（`POOL_SIZE` / `MAX_OVERFLOW` / `POOL_TIMEOUT`）
- 多数据库方言自动适配，分页语法差异由框架层屏蔽
- Docker 多阶段构建，最终镜像体积减小 60%

### 修复

- PostgreSQL 日期时间类型与 Python datetime 映射兼容
- SQL Server 分页查询使用 `OFFSET FETCH` 语法适配
- Oracle 大文本字段（CLOB）序列化异常，已修复


## [2.3.0] - 2025-01-08

**内容管理与 XSS 安全防护。**

### 新增

- **内容管理模块**：文章管理（分类、标签、状态流转）、公告管理（置顶、有效期）、友情链接、城市级联数据
- **富文本编辑器**：基于 WangEditor 集成，支持图片上传、视频嵌入、表格等丰富功能
- **XSS 防护**：基于 bleach 库的白名单 HTML 清洗机制，富文本内容自动过滤恶意脚本
- **文件字段自动处理**：上传文件自动迁移至目标存储，URL 自动补全
- **富文本字段自动处理**：嵌入图片自动迁移存储，内容自动 XSS 清洗

### 优化

- 文章状态流转：草稿 → 审核 → 发布 → 下架，完整生命周期管理
- 公告功能：支持置顶排序与有效期范围控制
- 文件上传：支持图片预览与裁剪功能

### 修复

- 富文本编辑器中图片路径为相对路径导致无法访问，已修复为绝对 URL
- 编辑时临时文件未清理，现已自动清理
- 批量删除时关联数据未同步删除，添加级联处理


## [2.2.0] - 2024-10-25

**系统配置与基础数据管理增强。**

### 新增

- **系统配置模块**：动态配置参数，运行时可调，修改即时生效，无需重启
- **参数管理模块**：系统参数与业务参数分类管理，支持参数分组与权限控制
- **字典模块增强**：字典项排序、启用/停用状态控制、批量导入导出
- **部门树形结构**：无限级部门树，支持拖拽排序与层级校验

### 优化

- 配置查询：支持按配置编码直接获取值，支持默认值兜底
- 字典导入导出：支持 Excel 批量导入字典项，含数据校验
- 部门排序：拖拽交互优化，实时保存排序结果

### 修复

- 字典编码重复校验遗漏，新增唯一性校验
- 部门删除时子部门未同步处理，添加级联删除选项
- 空配置值序列化异常，统一返回空字符串


## [2.1.0] - 2024-07-18

**RBAC 权限体系与认证安全上线。**

### 新增

- **RBAC 权限体系**：用户-角色-菜单三层权限模型，支持按钮级权限控制
- **JWT 认证**：无状态令牌认证，支持令牌刷新与黑名单机制
- **登录安全**：图形验证码、失败次数锁定（5 次失败锁定 15 分钟）、密码 bcrypt 加密存储
- **菜单管理**：动态路由生成，权限节点可视化配置
- **权限装饰器**：后端接口级权限拦截（`@permission_required`）
- **权限指令**：前端按钮级权限控制（`v-permission`）

### 优化

- 管理员账号（`is_superuser=True`）自动放行所有权限校验
- 权限数据缓存加速，减少数据库查询
- 令牌过期自动跳转登录页，携带 redirect URL

### 修复

- 令牌过期响应码统一为 401，前端统一拦截处理
- 权限缓存刷新延迟，变更后实时失效
- 登录锁定时间计算错误，修复时间窗口逻辑


## [2.0.0] - 2024-04-12

**Tornado 重构，前后端分离架构奠基。**

### 新增

- **Tornado 异步框架**：原生支持 async/await，轻量灵活，稳定可靠
- **SQLAlchemy ORM**：声明式模型定义，多数据库方言支持
- **Pydantic 数据校验**：声明式 Schema 校验，自动生成 API 文档与校验逻辑
- **Swagger 接口文档**：内置 Swagger UI 与 ReDoc，交互式 API 调试
- **Redis 异步客户端**：基于 redis-py + hiredis，用于缓存与会话管理
- **用户管理**：用户账号管理、密码重置、启用/停用状态控制
- **角色管理**：角色 CRUD、权限节点配置
- **菜单管理**：菜单 CRUD、图标设置、动态路由生成
- **部门管理**：部门树形结构管理
- **岗位管理**：岗位信息维护
- **职级管理**：职级信息维护

### 架构特性

- 前后端完全分离架构
- RESTful API 设计规范
- 统一响应格式与异常处理
- 异步请求全链路支持