更新日志

说明

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

版本总览

版本	日期	主要内容
2.0.0	2024-04-12	FastAPI 重构，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 行注册 即可完成模块接入
• 中间件链式处理：CORS → Redis 上下文注入 → 滑动窗口限流 → 数据库会话管理 → 操作日志自动捕获，职责单一，可插拔配置
• 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 与 Uvicorn 超时参数
• 并发请求会话泄露，修复会话绑定逻辑

[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

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

新增

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

架构特性

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