# 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

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

### 新增

- **自动参数校验**：Logic 层配置 `$validateClass` 后，`add`/`update` 自动调用验证器校验，覆盖所有 CRUD 入口（含导入），新增 CityValidate、TenantValidate，全模块验证器覆盖率 100%
- **项目文档体系**：文档站点全面改版，覆盖快速入门、模块开发、架构设计、运维部署全场景
- **生产环境部署指南**：Docker 容器化支持，提供 Dockerfile + docker-compose.yml 一键部署
- **系统健康检查接口**：运行状态监控，服务可用性实时检测
- **多数据库 SQL 脚本**：MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五套完整建表脚本

### 优化

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

### 修复

- JWT 密钥强制从环境变量读取，禁止硬编码
- 敏感配置项统一迁移至 `.env` 文件
- CORS 配置支持环境变量动态指定允许域名


## [4.9.0] - 2026-06-18

**OAuth2 认证与令牌管理增强。**

### 新增

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

### 优化

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


## [4.8.0] - 2026-04-06

**安全加固与防护增强。**

### 新增

- **SQL 注入防护增强**：表名拼接统一经 `validateTableName` 校验，防止注入攻击
- **XSS 防护增强**：富文本内容过滤策略优化，白名单机制
- **CORS 配置增强**：支持环境变量动态指定允许域名，凭证模式兼容
- **演示模式增强**：`#[DemoAllow]` 注解精细化控制，指定接口放行

### 优化

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

### 修复

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


## [4.7.0] - 2026-01-13

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

### 新增

- **岗位管理模块**：岗位信息维护与部门关联（PositionController / PositionLogic）
- **系统参数管理模块**：系统参数与业务参数分类管理（ParamController / ParamLogic / ParamService）
- **级别管理模块**：级别信息维护与排序（LevelController / LevelLogic）
- **城市行政区划模块**：城市树形结构与模糊搜索（CityController / CityLogic）

### 优化

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


## [4.6.0] - 2025-11-25

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

### 新增

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

### 优化

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


## [4.5.0] - 2025-09-16

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

### 新增

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

### 优化

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


## [4.4.0] - 2025-08-07

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

### 新增

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

### 优化

- 数据权限查询缓存（角色权限 1 小时缓存）
- 字典数据请求级缓存，同一请求内不重复查询
- 系统参数请求级缓存，减少数据库查询
- 表字段列表静态缓存，同一请求内只查一次


## [4.3.0] - 2025-06-21

**Excel 导入导出功能上线。**

### 新增

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

### 优化

- 导出文件统一保存至 `upload/temp/日期/` 目录，自动清理过期文件
- 导入数据空行自动过滤
- PhpSpreadsheet 依赖升级至 ^5.10
- 导入导出异常统一捕获，返回友好错误信息


## [4.2.0] - 2025-05-09

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

### 新增

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

### 优化

- LogMiddleware 日志写入失败静默处理，不影响主业务
- 操作日志排除列表可配置化（`middleware.log_except`）
- `OperationLog` 模型增加操作类型名称自动翻译
- 日志记录增加耗时统计（请求开始到响应完成）


## [4.1.0] - 2025-03-28

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

### 新增

- **`#[Permission]` 权限注解**：控制器方法级权限校验，声明即生效
- **`#[Log]` 操作日志注解**：自动记录操作日志，无需手动埋点
- **`#[DemoAllow]` 演示模式注解**：演示模式下指定接口放行
- **`AttributeService`**：统一注解读取服务，基于 PHP 8 反射
- **`PasswordService`**：密码加密服务（bcrypt 双重加盐）
- **`RequestInfoService`**：请求信息提取服务（IP / User-Agent / 地理位置）

### 优化

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


## [4.0.0] - 2025-02-14

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

### 新增

- **声明式属性配置**：`BaseLogic` 通过配置 `pageLikeFields` / `pageEqFields` / `pageOrderBy` / `uniqueFields` 等属性，自动完成查询构建、排序、唯一性校验
- **生命周期钩子体系**：`beforeAdd` / `afterAdd` / `beforeUpdate` / `afterUpdate` / `beforeDelete` / `afterDelete`，业务逻辑按需注入
- **文件字段自动处理**：配置 `fileFields` 后自动迁移临时文件、补全域名
- **富文本字段自动处理**：配置 `contentFields` 后自动处理临时文件与占位符
- **枚举显示名自动翻译**：配置 `serializeMaps` 后自动补 `{字段名}Text` 字段
- **唯一性校验机制**：配置 `uniqueFields` 后自动校验，支持全局唯一与分组唯一
- **表字段自动过滤**：前端传入非数据库字段自动忽略，安全接收全量数据

### 优化

- `BaseController` 新增 `_index` / `_list` / `_treeList` / `_detail` / `_add` / `_edit` / `_remove` / `_batchRemove` 通用方法
- 子类控制器代码量减少 70%+，只需配置属性 + 调用父类方法
- `BaseModel` 审计字段自动写入（`create_user` / `create_time` / `update_user` / `update_time`）
- 软删除全局查询范围自动过滤已删除数据

### 修复

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


## [3.9.0] - 2024-12-22

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

### 新增

- **代码生成器模块**：一键生成 Controller / Logic / Model / Validate / 前端页面（GeneratorController / GeneratorLogic / GeneratorService）
- **数据表列表查询**：从数据库读取所有表信息，支持按表名搜索
- **表结构分析**：字段类型归一化与属性自动识别（图片、富文本、筛选项、唯一、模糊搜索）
- **多数据库适配**：支持 MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五种驱动

### 优化

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


## [3.8.0] - 2024-10-17

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

### 新增

- **租户管理模块**：租户 CRUD、用户数统计、管理员账号创建（TenantController / TenantLogic）
- **`TenantMiddleware` 租户中间件**：从 JWT 解析用户租户，注入租户上下文
- **`BaseLogic` 租户隔离**：配置 `tenantScopeField` 后自动按租户过滤数据
- **租户 ID 自动填充**：新增数据时自动写入 `tenant_id`，超级管理员代入默认租户
- **租户状态校验**：启用/禁用/过期三种状态，过期租户自动拒绝访问

### 优化

- 超级管理员（`tenantId=0`）跳过租户隔离
- 租户隔离字段可配置化，不同表可指定不同隔离字段
- 租户信息缓存，减少重复查询
- `config/tenant.php` 租户配置文件


## [3.7.0] - 2024-09-03

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

### 新增

- **定时任务管理**：任务 CRUD、Cron 表达式配置、启用/禁用（JobController / JobLogic）
- **任务执行日志**：完整记录每次执行的开始时间、结束时间、执行状态、耗时、错误详情（JobLogController / JobLogLogic）
- **Daemon 常驻进程调度器**：后台常驻进程自动调度任务执行
- **任务操作**：手动执行一次、暂停、恢复、启用/禁用
- **调度器状态查询**：`daemonStatus` 接口查询 Daemon 进程运行状态与 PID

### 优化

- 任务锁文件机制（`runtime/job_daemon.lock`），防止重复调度
- 跨平台进程检测（Windows `tasklist` / Linux `posix_kill`）
- 任务执行异常捕获与日志记录
- Cron 表达式校验与解析


## [3.6.0] - 2024-07-26

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

### 新增

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

### 优化

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


## [3.5.0] - 2024-06-11

**内容管理模块上线。**

### 新增

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

### 优化

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


## [3.4.0] - 2024-04-19

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

### 新增

- **字典管理模块**：字典 CRUD、字典项管理（DictController / DictLogic / DictItemController / DictItemLogic）
- **配置管理模块**：配置 CRUD、配置项管理（ConfigController / ConfigLogic / ConfigItemController / ConfigItemLogic）
- **`DictService` 字典服务**：按编码查询字典值，请求级缓存
- **`ParamService` 参数服务**：按编码查询系统参数，请求级缓存

### 优化

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


## [3.3.0] - 2024-03-05

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

### 新增

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

### 优化

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


## [3.2.0] - 2024-01-23

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

### 新增

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

### 优化

- 用户密码 bcrypt 双重加盐加密
- 用户状态管理（启用/禁用）
- 角色支持权限节点批量分配
- 用户列表支持按角色、部门筛选


## [3.1.0] - 2023-12-08

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

### 新增

- **用户登录接口**：用户名 + 密码 + 验证码登录（`LoginController::login`）
- **JWT 双令牌机制**：`access_token`（2小时） + `refresh_token`（7天）
- **`JwtService` 令牌服务**：令牌签发 / 刷新 / 解析 / 吊销
- **图形验证码**：`CaptchaService` 生成验证码，按 IP 频率控制
- **`AuthMiddleware` 认证中间件**：JWT 校验 + 用户信息注入
- **`CorsMiddleware` 跨域中间件**：支持配置化跨域策略

### 优化

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


## [3.0.0] - 2023-10-12

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

### 新增

- **ThinkPHP 6.1.x 框架初始化**：基于 ThinkPHP 6.1.x 搭建前后端分离 API 项目
- **`BaseModel` 模型基类**：软删除（`is_delete` 字段）+ 审计字段自动写入（`create_user` / `create_time` / `update_user` / `update_time`）
- **`BaseController` 控制器基类**：统一响应格式（`success` / `fail` / `page`）+ 参数获取
- **`BaseLogic` 逻辑基类**：基础 CRUD + 软删除 + 分页查询
- **`Common` 公共函数库**：密码加密 / 文件上传 / 驼峰下划线转换 / 随机字符串
- **`Result` 统一响应类**：`success` / `fail` / `page` 三种响应格式
- **`ExceptionHandle` 全局异常处理**：统一异常捕获与错误响应
- **多数据库配置支持**：MySQL / PostgreSQL / SQL Server / Oracle / SQLite
- **`.env` 环境变量配置**：敏感配置与环境解耦

### 架构特性

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