# 1.6 更新日志

:::tip 说明
更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。对于开发者，可快速掌握新功能与 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`）
- 软删除全局查询范围自动过滤
- 审计字段模型事件自动写入