1.6 更新日志

说明

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

版本总览

版本	日期	主要内容
5.0.0	2026-10-01	正式稳定版发布
4.9.0	2026-06-18	OAuth2 认证与令牌管理
4.8.0	2026-04-06	安全加固与防护增强
4.7.0	2026-01-13	扩展业务模块
4.6.0	2025-11-25	数据处理与文件管理
4.5.0	2025-09-16	代码生成器增强
4.4.0	2025-08-07	性能优化与缓存策略
4.3.0	2025-06-21	Excel 导入导出
4.2.0	2025-05-09	操作日志与审计增强
4.1.0	2025-03-28	服务层抽离与注解体系
4.0.0	2025-02-14	架构重构：声明式 CRUD 体系
3.9.0	2024-12-22	代码生成器
3.8.0	2024-10-17	多租户架构与数据隔离
3.7.0	2024-09-03	定时任务调度系统
3.6.0	2024-07-26	通知公告与友情链接
3.5.0	2024-06-11	内容管理（文章/分类）
3.4.0	2024-04-19	字典与配置管理系统
3.3.0	2024-03-05	部门菜单与数据权限控制
3.2.0	2024-01-23	用户管理与 RBAC 权限体系
3.1.0	2023-12-08	JWT 双令牌认证与登录体系
3.0.0	2023-10-12	项目初始化，基础架构框架搭建

[5.0.0] - 2026-10-01

正式稳定版发布，全面完善文档、安全加固与生产环境适配。

新增

• 自动参数校验：Service 层配置验证请求类后，add/update 自动调用 FormRequest 校验，覆盖所有 CRUD 入口（含导入），全模块验证器覆盖率 100%
• 项目文档体系：VitePress 开发者文档站点全面改版，覆盖快速入门、模块开发、架构设计、运维部署全场景
• 多数据库初始化脚本：MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五套完整建表脚本（document/ 按数据库类型分组，已做对应 SQL 语法适配）
• 生产环境部署指南：Docker 容器化支持，提供 Dockerfile + docker-compose.yml 一键部署（Nginx + PHP-FPM + MySQL + Redis 四容器编排）
• 系统健康检查接口：/up 健康路由，运行状态监控，服务可用性实时检测
• 跨库迁移工具：php artisan db:migrate 数据结构与数据跨数据库迁移

优化

• IP 归属地查询：基于 zoujingli/ip2region（v3.0+）composer 包，支持 IPv4/IPv6，自动加载内置数据库
• 新增 ProxyMiddleware 全局中间件：部署在 CDN / 负载均衡后面时，自动从 X-Forwarded-For / X-Real-IP 头提取真实客户端 IP，通过 .env 的 TRUSTED_PROXIES 配置受信代理
• 角色模块多租户改造：角色表新增 tenant_id 字段，角色数据按租户隔离，RoleService 改为继承 BaseTenantService
• 全模块稳定性测试与边界条件覆盖
• 错误提示信息统一规范化，提升用户友好度
• 日志输出格式标准化，便于日志采集与分析
• 依赖包版本锁定（composer.lock），确保生产环境一致性
• 接口限流策略优化，防止恶意请求

修复

• JWT 密钥强制从环境变量读取，禁止硬编码，启动时 fail-close 校验（不足 32 字符拒绝启动）
• 敏感配置项统一迁移至 .env 文件
• CORS 配置支持环境变量动态指定允许域名

[4.9.0] - 2026-06-18

OAuth2 认证与令牌管理增强。

新增

• OAuth2 完整认证流程：Token 签发 / 刷新 / 吊销 / 检测，兼容标准 OAuth2 协议（AuthController::token / removeToken / checkToken）
• 令牌 Redis 黑名单机制：登出后令牌即时失效，防止令牌被盗用
• 密码强度校验策略：长度、复杂度、常见密码库校验
• 登录日志增强：增加 IP 归属地与浏览器信息记录

优化

• JWT access_token 有效期可配置化（JWT_ACCESS_TTL，默认 2 小时）
• refresh_token 续签逻辑优化，支持滑动过期
• 验证码生成算法升级，增加干扰线与噪点
• 登录失败次数限制与账户锁定机制

[4.8.0] - 2026-04-06

安全加固与防护增强。

新增

• XSS 防护增强：富文本内容过滤策略优化，白名单机制
• CORS 配置增强：支持环境变量动态指定允许域名，凭证模式兼容
• 演示模式增强：#[DemoAllow] 注解精细化控制，指定接口放行（DemoMiddleware）

优化

• 敏感配置项统一迁移至 .env 文件，禁止硬编码
• 请求参数统一校验，FormRequest 空参数与类型错误提前拦截
• 异常信息脱敏，生产环境（APP_DEBUG=false）不暴露文件路径与行号

修复

• 修复并发请求下会话数据串扰问题
• 修复文件上传超大文件未中断导致内存溢出
• 修复特殊字符参数未转义导致的解析异常

[4.7.0] - 2026-01-13

扩展业务模块，覆盖更多管理场景。

新增

• 岗位管理模块：岗位信息维护与部门关联（PositionController / PositionService）
• 系统参数管理模块：系统参数与业务参数分类管理（ParamController / ParamService）
• 职级管理模块：职级信息维护与排序，支持 Excel 导入导出（LevelController / LevelService）
• 城市行政区划模块：城市树形结构与模糊搜索（CityController / CityService）

优化

• 参数管理支持缓存策略，高频参数请求级缓存
• 城市数据支持树形结构展示与模糊搜索
• 岗位与部门关联查询优化
• 字段校验统一规范化（新增对应 FormRequest）

[4.6.0] - 2025-11-25

数据处理能力与文件管理全面增强。

新增

• 文件模板管理模块：模板文件上传、版本管理与在线编辑（FileTemplateController / FileTemplateService）
• 富文本占位符机制：[IMG_URL] 占位符，入库替换、出库还原域名，迁移无感知
• 文件字段自动迁移：临时文件自动迁移至正式目录，自动去除域名前缀（HasFileProcessing Trait）
• 批量导出分批查询：支持逐批处理，避免大数据量内存溢出

优化

• 全局辅助函数文件处理链路优化（save_file / get_file_url 等）
• 文件上传 MIME 类型真实检测（finfo），不信任客户端声明
• 上传目录自动按日期分目录，避免单目录文件过多
• 图片字段与文件字段处理逻辑分离，支持不同校验策略

[4.5.0] - 2025-09-16

代码生成器功能增强与模板优化。

新增

• 批量生成：支持多表批量生成代码，一次操作完成多模块搭建
• 代码预览：生成前可查看所有文件内容，确认无误后再写入
• 字典自动生成：从字段注释中提取枚举值，自动生成字典数据
• 路由与菜单自动生成：生成代码时自动注册 routes/api.php 路由与菜单权限节点

优化

• 模板渲染引擎优化，变量替换更精准（resources/templates/ 后端 4 套 + 前端 ui/ui2 模板）
• 字段属性自动分析（图片字段、富文本字段、筛选字段、模糊搜索字段）
• 生成文件冲突检测，已存在文件提示跳过或覆盖
• 多数据库驱动适配优化（PostgreSQL / SQL Server / SQLite）

[4.4.0] - 2025-08-07

性能优化与缓存策略升级。

新增

• 查询参数自动转换：驼峰转下划线自动转换（API_CAMEL_SNAKE_CONVERT），前后端命名风格无感适配
• 动态排序：排序字段支持前端动态指定（排序白名单内生效）
• 返回字段过滤：前端通过 fields 参数指定需要的字段，减少数据传输量
• 分批查询回调：支持逐批回调处理，适合大数据量导出

优化

• 数据权限查询缓存（角色权限缓存，Menu/RoleMenu Observer 失效）
• 字典数据请求级缓存 + Cache 两级缓存，同一请求内不重复查询
• 系统参数请求级缓存，减少数据库查询
• 表字段列表静态缓存，同一请求内只查一次

[4.3.0] - 2025-06-21

Excel 导入导出功能上线。

新增

• Excel 导入：支持原始数组导入与表头映射导入两种模式（ExcelService::import / importWithMap）
• Excel 导出：一次性导出，适合中小数据量（ExcelService::export）
• 大数据量分批导出：分批查询 + 流式写入，避免内存溢出
• 表头映射导入：自动按表头关联字段名，无需手动映射列号

优化

• 导出文件统一保存至临时目录，自动清理过期文件
• 导入数据空行自动过滤
• PhpSpreadsheet 依赖升级至 ^2.0
• 导入导出异常统一捕获，返回友好错误信息

[4.2.0] - 2025-05-09

操作日志与审计体系全面增强。

新增

• 30 种操作类型常量：#[OperationLog] 注解支持新增/修改/删除/查询/导入/导出/审批/驳回/执行/暂停/恢复等全场景
• 日志描述占位符：支持 {param} 占位符，自动替换为请求参数值（如 删除用户ID:{id} → 删除用户ID:123）
• 智能记录策略：写操作（POST/PUT/DELETE）始终记录，读操作按类型选择性记录
• 登录日志独立模块：记录登录/登出/失败，含失败原因与 IP 信息

优化

• LogOperation 中间件日志写入失败静默处理，不影响主业务（terminable 阶段落库）
• 操作日志排除列表可配置化
• OperationLog 模型增加操作类型名称自动翻译
• 日志记录增加耗时统计（请求开始到响应完成）

[4.1.0] - 2025-03-28

服务层抽离与 PHP 8 注解体系。

新增

• #[Permission] 权限注解：控制器方法级权限校验，auth.jwt 中间件反射统一鉴权，声明即生效
• #[OperationLog] 操作日志注解：自动记录操作日志，无需手动埋点
• #[DemoAllow] 演示模式注解：演示模式下指定接口放行
• PasswordService：密码加密服务（bcrypt，成本因子 12）
• RequestInfoService：请求信息提取服务（IP / User-Agent / 地理位置）

优化

• 权限码统一命名规范：sys:{模块名}:{操作}（如 sys:user:add）
• 超级管理员（uid=1）权限校验直接放行
• 注解支持类级回退（Permission 注解可标注在类上）

[4.0.0] - 2025-02-14

架构重构 — 声明式 CRUD 体系，大幅减少重复代码。

新增

• 声明式属性配置：BaseService 通过配置 pageLikeFields / pageEqFields / pageOrderBy / uniqueFields 等属性，自动完成查询构建、排序、唯一性校验
• 生命周期钩子体系：beforeAdd / afterAdd / beforeUpdate / afterUpdate / beforeDelete / afterDelete，业务逻辑按需注入，DB 事务由基类统一管理
• 6 个 Service Trait：HasCrudOperations / HasQueryScopes / HasFileProcessing / HasDataScope / HasSerializeMaps / HasUniqueCheck 组合复用
• 文件字段自动处理：配置 fileFields 后自动迁移临时文件、补全域名
• 富文本字段自动处理：配置 contentFields 后自动处理临时文件与占位符
• 枚举显示名自动翻译：配置 serializeMaps 后自动补 {字段名}Text 字段
• 唯一性校验机制：配置 uniqueFields 后自动校验

优化

• Controller 基类提供 _page / _list / _treeList / _detail / _add / _update / _delete / _batchDelete 通用方法
• 子类控制器代码量减少 70%+，只需配置属性 + 调用父类方法
• HasAuditColumns 审计字段自动写入（create_user / create_time / update_user / update_time）
• SoftDeleteFlagScope 软删除全局查询范围自动过滤已删除数据

修复

• 修复批量软删除未关闭全局作用域导致条件叠加的问题
• 修复富文本内容中域名替换不完整的问题
• 修复驼峰/下划线转换中数组嵌套场景的边界问题

[3.9.0] - 2024-12-22

代码生成器上线，开发效率质的飞跃。

新增

• 代码生成器模块：一键生成 Controller / Service / Model / FormRequest / 前端页面（GeneratorController / GeneratorService）
• CLI 命令：php artisan generate:code 命令行生成
• 数据表列表查询：从数据库读取所有表信息，支持按表名搜索
• 表结构分析：字段类型归一化与属性自动识别（图片、富文本、筛选项、唯一、模糊搜索）

优化

• 生成代码风格与项目现有代码保持一致
• 生成的 FormRequest 自动按字段类型生成校验规则
• 生成的 Controller 自动配置 #[Permission] 与 #[OperationLog] 注解
• 生成的菜单自动挂载到指定父菜单下（GENERATOR_PARENT_MENU_ID）

[3.8.0] - 2024-10-17

多租户架构，支持 SaaS 化部署。

新增

• 租户管理模块：租户 CRUD、用户数统计、管理员账号创建（TenantController / TenantService）
• ResolveTenant 租户中间件：从 JWT 解析用户租户，注入租户上下文
• BaseTenantService 租户隔离：自动按租户过滤查询数据，新增数据自动填充 tenant_id
• 租户状态校验：启用/禁用/过期三种状态，过期租户自动拒绝访问
• config/tenant.php 租户配置文件（默认租户 ID）

优化

• 超级管理员（tenantId=0）跳过租户隔离，创建数据代入默认租户
• 租户信息缓存，减少重复查询

[3.7.0] - 2024-09-03

定时任务调度系统，支持可视化管理。

新增

• 定时任务管理：任务 CRUD、Cron 表达式配置、启用/禁用（JobController / JobService）
• 任务执行日志：完整记录每次执行的开始时间、结束时间、执行状态、耗时、错误详情（JobLogController / JobLogService）
• Daemon 常驻进程调度器：php artisan job:daemon 后台常驻进程自动调度任务执行
• 一次性执行：php artisan job:run 配合系统 Cron 执行到期任务
• 任务操作：手动执行一次、暂停、恢复、启用/禁用

优化

• 任务防重复执行机制（同一任务同一分钟内不重复执行）
• 跨平台进程检测（Windows tasklist / Linux posix_kill）
• 任务执行异常捕获与日志记录
• Cron 表达式校验与解析

[3.6.0] - 2024-07-26

通知公告与友情链接模块。

新增

• 通知公告模块：通知 CRUD、类型管理、发布状态、排序（NoticeController / NoticeService）
• 友情链接模块：链接 CRUD、图标管理、启用/禁用（LinkController / LinkService）
• 通知类型字典：通知/公告/提醒三种类型，字典驱动
• 链接状态管理：启用/禁用状态控制

优化

• 通知内容支持富文本编辑
• 通知发布状态与排序管理
• 链接图标与描述字段扩展
• 列表查询支持状态筛选与模糊搜索

[3.5.0] - 2024-06-11

内容管理模块上线。

新增

• 文章管理模块：文章 CRUD、封面图、图集、状态管理、点击率统计（ArticleController / ArticleService）
• 文章分类模块：分类 CRUD、树形结构、多级嵌套（CategoryController / CategoryService）
• 分类树形结构：支持无限级分类嵌套（parent_id 自关联）
• 文章状态管理：正常/下架两种状态

优化

• 分类编码唯一性校验
• 文章内容支持富文本编辑器
• 文章排序与置顶功能
• 分类支持模糊搜索与树形展示

[3.4.0] - 2024-04-19

字典与配置管理，系统基础数据标准化。

新增

• 字典管理模块：字典 CRUD、字典项管理（DictController / DictItemController / DictService）
• 配置管理模块：配置 CRUD、配置项管理（ConfigController / ConfigItemController / ConfigService）
• DictCacheService 字典服务：按编码查询字典值，两级缓存（请求级 + Cache）
• ParamService 参数服务：按编码查询系统参数，请求级缓存
• 字典缓存命令：php artisan dict:clear-cache

优化

• 字典数据按编码缓存，同一请求内不重复查询
• 配置项支持分组管理
• 字典值与显示名自动映射（Observer 变更自动失效缓存）
• 配置项支持启用/禁用状态

[3.3.0] - 2024-03-05

部门菜单与数据权限体系。

新增

• 部门管理模块：部门 CRUD、树形结构（DeptController / DeptService）
• 菜单管理模块：菜单 CRUD、目录/菜单/按钮三种类型（MenuController / MenuService）
• 数据权限控制：全部 / 本部门 / 仅本人三级数据权限
• HasDataScope 数据权限 Trait：配置数据权限字段后自动过滤
• 角色数据权限范围：data_scope 字段控制角色可见数据范围

优化

• 菜单支持目录 / 菜单 / 按钮三种类型（type 字段）
• 权限节点与菜单分离，按钮级权限控制
• 部门树形结构展示
• 数据权限缓存机制（角色权限缓存 + Observer 失效）

[3.2.0] - 2024-01-23

用户管理与角色权限体系。

新增

• 用户管理模块：用户 CRUD、密码重置、启用/禁用（UserController / UserService）
• 角色管理模块：角色 CRUD、权限节点配置（RoleController / RoleService）
• RBAC 权限模型：用户 → 角色 → 菜单 → 权限，菜单即权限体系
• 用户角色关联表：UserRole 支持一个用户多角色
• 角色菜单关联表：RoleMenu 支持一个角色多权限

优化

• 用户密码 bcrypt 加密（成本因子 12）
• 用户状态管理（启用/禁用）
• 角色支持权限节点批量分配
• 用户列表支持按角色、部门筛选

[3.1.0] - 2023-12-08

用户认证与 JWT 双令牌体系。

新增

• 用户登录接口：用户名 + 密码 + 验证码登录（AuthController::login）
• JWT 双令牌机制：access_token（默认 2 小时） + refresh_token（默认 7 天）
• JwtService 令牌服务：令牌签发 / 刷新 / 解析 / 吊销（Redis 有状态存储）
• 图形验证码：CaptchaService 生成验证码，按 IP 频率控制
• Authenticate 认证中间件（auth.jwt）：JWT 校验 + #[Permission] 鉴权 + 用户信息注入
• Cors 跨域中间件：支持配置化跨域策略

优化

• Token 从请求头 Authorization: Bearer {token} 提取
• 登录参数 FormRequest 校验
• 登录日志记录（成功/失败/原因）

[3.0.0] - 2023-10-12

项目初始化，搭建基础架构框架。

新增

• Laravel 13 框架初始化：基于 Laravel 13 + PHP 8.3 搭建前后端分离 API 项目
• 模型层基础：Eloquent 模型 + SoftDeletesByFlag（is_delete 软删除） + HasAuditColumns（审计字段自动写入）
• 控制器基类：统一响应格式（success / fail / paginate）+ 参数获取 + 通用 CRUD 快捷方法
• 服务层基类：BaseService 基础 CRUD + 软删除 + 分页查询
• 全局辅助函数库：Helpers/helpers.php（密码加密 / 文件处理 / 驼峰下划线转换 / 随机字符串）
• Result 统一响应类：success / page / fail / 语义化方法，统一 {code, ok, msg, data} 结构
• Handler 全局异常处理：异常统一捕获与 JSON 响应渲染
• 多数据库配置支持：MySQL / PostgreSQL / SQL Server / SQLite（DB_CONNECTION 切换）
• .env 环境变量配置：敏感配置与环境解耦

架构特性

• 前后端完全分离架构
• RESTful API 设计规范
• 统一响应格式（code / ok / msg / data）
• 软删除全局查询范围自动过滤
• 审计字段模型事件自动写入