# 更新日志

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

## 版本总览

| 版本 | 日期 | 主要内容 |
|:-----|:-----|:---------|
| 2.0.0 | 2024-04-12 | 用户 / 角色 / 菜单 / 部门 / 岗位 / 职级管理 |
| 2.1.0 | 2024-07-18 | RBAC 权限体系 + JWT 认证 + 登录安全 |
| 2.2.0 | 2024-10-05 | 系统配置 + 数据字典 + 部门树增强 |
| 2.3.0 | 2025-01-23 | 内容管理 + 富文本编辑器 + XSS 防护 |
| 2.4.0 | 2025-03-14 | 多数据库支持 + Docker 容器化部署 |
| 2.5.0 | 2025-06-09 | Vue3 + ElementPlus + TypeScript + Vite |
| 2.6.0 | 2025-09-22 | 代码生成器 + Excel 导入导出 |
| 2.7.0 | 2025-12-16 | 定时任务调度 + 操作日志 + 登录日志 |
| 2.8.0 | 2026-03-28 | IP 地理位置 + UA 解析 + 安全防护增强 |
| 2.9.0 | 2026-06-07 | 技术文档体系 + 契约测试 + 缓存优化 |
| **3.0.0** | **2026-09-01**** | **模块化分层 + Repository 层 + AOP 事务 + 数据迁移工具** |


## [3.0.0] - 2026-09-01

**模块化分层架构落地，新增 Repository 数据访问层与 AOP 事务管理，配套跨库迁移工具。**

### 新增

- **模块化分层架构**：业务模块按功能域分组（`system` / `cms` / `association`），每个模块独立包含 Router、Service、Repository、Schema 四层，职责清晰、可插拔扩展
- **Repository 数据访问层**：`BaseRepository` 提供 `find_page` / `find_list` / `first_by` / `exists_by` / `count_by` 等通用方法，业务代码与 SQLAlchemy ORM 彻底解耦
- **Service 基类模板方法**：`BaseService` 封装 page / detail / add / update / remove 标准流程 + 覆写钩子（`before_add` / `before_delete` / `_enrich_page_records` 等），新模块仅需 4 个文件 + 1 行注册即可接入
- **AOP 事务管理**：`before_request` 标记事务、`after_request` 自动提交（POST/PUT/DELETE + HTTP 200 + code=0）、`teardown_request` 异常回滚，业务代码零事务代码
- **WTForms 表单校验基类**：`BaseForm` + `validators` 声明式约束 + `validate_` 自定义校验器，唯一性校验通过 `Repository.exists_by(filters, exclude_id)` 实现
- **中间件链式处理**：登录校验（白名单机制）→ 演示模式拦截 → AOP 事务 → 操作日志自动捕获，职责单一，可插拔配置
- **契约测试体系**：路由快照、权限快照、表名快照三管齐下，自动守护接口契约
- **集成测试框架**：事务一致性验证 + 操作日志自动校验，确保核心业务流程稳定可靠
- **跨库数据迁移工具**（`scripts/migrate_db.py`）：支持 MySQL / PostgreSQL / SQL Server / SQLite / Oracle 间的全量数据迁移，含表结构同步与数据泵送
- **数据库版本化迁移**：基于 Flask-Migrate / Alembic，Schema 变更可追溯、可回滚，支持多环境发布
- **统一文件上传接口**：单一接口支持图片、文档、压缩包等全类型文件，流式校验，超限立即中断，避免内存溢出
- **文件安全防护**：扩展名白名单 + 魔术字节（Magic Number）校验 + 路径遍历防护 + 高危格式拦截（如 `.php`、`.jsp` 等）

### 优化

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

### 修复

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


## [2.9.0] - 2026-06-07

**技术文档体系全面上线，新增契约测试与缓存优化。**

### 新增

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

### 优化

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

### 修复

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


## [2.8.0] - 2026-03-28

**新增 IP 地理位置查询与 UA 解析，安全防护全面增强。**

### 新增

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

### 优化

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

### 修复

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


## [2.7.0] - 2025-12-16

**新增定时任务调度与日志审计能力。**

### 新增

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

### 优化

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

### 修复

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


## [2.6.0] - 2025-09-22

**新增代码生成器与 Excel 导入导出能力。**

### 新增

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

### 优化

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

### 修复

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


## [2.5.0] - 2025-06-09

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

### 新增

- **Vue3 升级**：前端框架从 Vue 2 升级至 Vue3.4+，全面拥抱 Composition API
- **ElementPlus**：UI 组件库升级至 ElementPlus，适配 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-14

**新增多数据库支持与 Docker 容器化部署。**

### 新增

- **多数据库支持**：通过 `DB_DRIVER` 环境变量一键切换 MySQL / PostgreSQL / SQL Server / SQLite / Oracle，业务代码零改动
- **SQLAlchemy 2.0**：升级至 SQLAlchemy 2.0+，声明式映射，统一 Core 与 ORM 接口
- **WTForms 数据校验**：声明式表单校验，`validators` 约束 + `validate_` 自定义校验器，运行时自动验证请求参数
- **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-23

**新增内容管理模块与 XSS 安全防护。**

### 新增

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

### 优化

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

### 修复

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


## [2.2.0] - 2024-10-05

**新增系统配置与数据字典管理，部门树交互增强。**

### 新增

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

### 优化

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

### 修复

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


## [2.1.0] - 2024-07-18

**新增 RBAC 权限体系与 JWT 认证，登录安全全面升级。**

### 新增

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

### 优化

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

### 修复

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


## [2.0.0] - 2024-04-12

**核心模块与基础架构。**

### 新增

- **用户管理**：用户账号管理、密码重置、启用/停用状态控制
- **角色管理**：角色 CRUD、权限节点配置
- **菜单管理**：菜单 CRUD、图标设置、动态路由生成
- **部门管理**：部门树形结构管理
- **岗位管理**：岗位信息维护
- **职级管理**：职级信息维护
- **统一响应格式**：`R.ok()` / `R.failed()` 标准化返回结构
- **Blueprint 模块化路由**：按业务域组织接口，支持独立注册与启用
- **Redis 缓存**：验证码存储、会话管理、JWT 黑名单