djangoadmin-wiki/DjangoAdmin_Flask_EleVue/zh/changelog.md

更新日志

:::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 地理位置 + 安全防护增强
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 地理位置查询，安全防护全面增强。

新增

• IP 地理位置查询：基于离线 GeoIP 数据库，服务启动时加载内存，查询零延迟，无外部 API 依赖
• User-Agent 解析：自动识别客户端操作系统类型与版本、浏览器名称与版本
• 接口限流：基于 Redis 滑动窗口的按 IP 限流策略，支持按接口独立配置阈值，防刷防滥用
• 操作日志自动记录：所有写操作（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 黑名单