# 1.6 更新日志

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

## 版本总览

| 版本 | 日期 | 主要内容 |
|:-----|:-----|:---------|
| **4.0.0** | **2026-10-20** | **核心架构定稿：标签体系与泛型基座** |
| 3.9.0 | 2026-09-07 | OAuth2 令牌治理 |
| 3.8.0 | 2026-07-26 | 安全加固与防护增强 |
| 3.7.0 | 2026-06-13 | 五方言驱动与整库迁移 |
| 3.6.0 | 2026-05-01 | 代码生成器 |
| 3.5.0 | 2026-03-21 | 运行监控体系 |
| 3.4.0 | 2026-02-05 | 内置任务与在线用户 |
| 3.3.0 | 2025-12-24 | 定时任务调度 |
| 3.2.0 | 2025-11-11 | 数据权限四档 |
| 3.1.0 | 2025-09-29 | 租户治理与状态校验 |
| 3.0.0 | 2025-08-18 | 多租户架构与数据隔离 |
| 2.9.0 | 2025-07-06 | 共享能力层沉淀 |
| 2.8.0 | 2025-05-24 | 工具模块与案例示范 |
| 2.7.0 | 2025-04-12 | 数据导入导出 |
| 2.6.0 | 2025-03-01 | 文件上传与富文本契约 |
| 2.5.0 | 2025-01-17 | 内容管理与行政区划 |
| 2.4.0 | 2024-12-05 | 字典、配置与参数 |
| 2.3.0 | 2024-10-23 | 操作审计与日志查询 |
| 2.2.0 | 2024-09-10 | 组织架构与个人中心 |
| 2.1.0 | 2024-07-29 | 用户管理与 RBAC 权限 |
| 2.0.0 | 2024-06-16 | 工程奠基与认证闭环 |


## [4.0.0] - 2026-10-20

**核心架构定稿：gmeta 标签体系与 ModuleSpec 泛型基座全面落地，路由、权限、日志、文档一体驱动，全域能力就位，生产部署就绪。**

### 新增

- **gmeta 标签体系定稿**：请求结构体上的一个标签同时驱动路由注册、权限校验、操作日志、OpenAPI 文档四件事，"标签即事实"，杜绝多处不一致
- **ModuleSpec 泛型基座**：筛选、排序、树形、字典文本、文件字段、富文本、唯一校验、数据权限全部声明化，生命周期钩子承接差异，手写方法为合法逃生舱，基座永不出现按模块分支的代码
- **OpenAPI 输出**：gmeta 补注册进 goai，/api.json 原生 JSON + /swagger 本地 Redoc 页面
- **生成器与基座对齐**：生成的 logic 直接产出基座声明式实现，go build 后即可运行
- **模块版图收口**：监控域（操作日志/登录日志/定时任务/任务日志）与工具域（案例/文件模板/生成器/上传）能力全量就位

### 优化

- **主键策略定稿**（2026-10-13）：统一 int 数据库自增，插入后经 LastInsertId() 回读，全局钩子不填主键
- **中间件链定稿**：CORS → Response → RateLimit → Demo → JWT → Tenant → OperationLog，权限校验收敛到 Bind 包装层每请求判定
- **筛选对齐三件套定稿**（2026-10-14）：前端 querySchemas.ts、请求结构体同名驼峰字段、基座声明（LikeFields/EqFields）三处对齐，导出与列表同套筛选
- **目录平铺定稿**：api/controller/logic/service 单包 snake_case 文件，同包 init 自动注册
- **URL 约定收口**：统一 /api 前缀、无 /v1 版本段；公开白名单三处一致
- **配置环境变量覆盖**：GF_ 前缀 env-first 适配器（键名=配置路径大写下划线），compose 友好名映射，12-Factor 部署就绪
- **工程保障**：go vet / gofmt 门禁、sqlite 与 MySQL 集成测试、golden 黄金样本响应比对回归、CI workflow、docker compose 一键部署、145 页文档站

### 修复

- 富文本还原散落的字符串替换统一收敛到 ExpandContentFields 唯一出口，[IMG_URL] 占位符不再被业务代码旁路解析


## [3.9.0] - 2026-09-07

**OAuth2 令牌治理收口。**

### 新增

- **令牌刷新**：/oauth2/token 持 refresh_token 轮换新令牌，旧 jti 即时拉黑
- **令牌检测**：/oauth2/check/token 校验有效性
- **令牌吊销**：/oauth2/remove/:token 指定令牌即时失效

### 优化

- 前端令牌刷新链路统一对接 OAuth2 路由；登录响应保持 OAuth2 惯例字段（access_token / refresh_token / expires_in / token_type）


## [3.8.0] - 2026-07-26

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

### 新增

- **接口限流**：固定窗口限流中间件，登录/验证码入口独立更严阈值（authLimit），计数经共享缓存多实例一致
- **受信代理**：api.proxyIps（支持 CIDR）内的代理才信任 X-Forwarded-For 首段 / X-Real-IP
- **演示模式白名单精细化**：公开路径与读操作精确放行，写操作统一拦截提示
- **健康检查**：/api/health 公开探测接口

### 优化

- 限流仅作用于 /api/ 路径，静态资源与文档页不受影响


## [3.7.0] - 2026-06-13

**五方言驱动与整库迁移能力建成。**

### 新增

- **五方言驱动**：MySQL / PostgreSQL / SQL Server / Oracle / SQLite 运行时切换，改配置 type/link 即换库
- **五份方言 DDL**：resource/sql 定稿，与 MySQL 基准逐表对齐
- **整库迁移器**：源库内省 → 中间表示 → 方言 DDL 渲染 → 分批搬运 → pgsql 序列修复，行数校验闭环
- **迁移 CLI**：源/目标连接参数、-drop-target-first 清空目标、-dry-run 预演


## [3.6.0] - 2026-05-01

**代码生成器上线，模块产出工业化。**

### 新增

- **双入口**：HTTP 页面与 CLI（-tables / -preview / -batch）
- **产出**：后端八件套（api/controller/logic/service + dao/index、dao/internal、entity、do）与前端页面五件
- **幂等副作用**：同步创建菜单、权限节点、字典数据与路由注册
- **字典自动创建**：按列注释枚举解析（支持 `1-正常` 与 `1=正常` 两种写法）
- **覆盖保护**：缺失补生成、存在跳过，generator.overwrite 开启才覆盖

### 优化

- 生成代码统一 gofmt；前端模板以 [[]] 定界，规避 Vue 插值冲突


## [3.5.0] - 2026-03-21

**运行监控体系上线。**

### 新增

- **服务器监控**：运行时、内存、磁盘分平台采集，MySQL / Redis 连通检测
- **缓存监控**：Redis INFO 解析展示，内存降级模式标识（mode=memory）
- **监控接口**：/server/info、/cache/info，配合在线用户列表运行状态一目了然


## [3.4.0] - 2026-02-05

**内置任务与在线用户治理。**

### 新增

- **LogClean 内置任务**：每日 02:30 分批物理清理三张日志表（保留天数默认 90，任务参数可覆盖）
- **在线用户模块**：登录登记 / 登出注销，在线列表与强制踢出（jti 拉黑防刷新复活）

### 优化

- CleanTemp 临时目录清理纳入调度统一管理（每日 03:30 触发）
- 调度消费约定完善：同步/异步标记与三种执行策略协同


## [3.3.0] - 2025-12-24

**数据驱动的定时任务调度系统。**

### 新增

- **常驻调度器**：启动加载启用任务，Cron 表达式触发
- **双执行形态**：HTTP 接口任务与本地处理器任务
- **三种执行策略**：并行 / 单例 / 放弃，单例与放弃叠加多实例执行锁（job:lock:{id}，共享缓存 SET NX、300s 兜底）
- **任务日志**：执行时间、状态、耗时、错误详情完整留档
- **任务操作**：立即执行、暂停、恢复、状态设置、调度器状态查询


## [3.2.0] - 2025-11-11

**角色数据权限四档上线。**

### 新增

- **data_scope 四档**：全部 / 本部门及以下 / 本部门 / 仅本人
- **一行接线**：ApplyDataScope("dept_id") 声明即生效，作用于分页/列表/导出
- **身份缓存**：300s 缓存含数据范围与部门，多角色取最宽松档位，角色变更主动失效

### 修复

- 未分配部门用户在"本部门"档位越权可见——身份加载层降级为仅本人


## [3.1.0] - 2025-09-29

**租户治理与状态校验完善。**

### 新增

- **状态/过期校验**：中间件拦截（60s 缓存），禁用与过期租户拒绝访问
- **租户用户查询**：按租户维度检索用户列表
- **平台数据绕过**：超管与租户级表中的平台数据（tenant_id=0）自动放行
- **租户内分组唯一**：手机号/用户名等唯一性走分组唯一索引


## [3.0.0] - 2025-08-18

**多租户架构与数据隔离建成，SaaS 能力就绪。**

### 新增

- **全局钩子横切**：审计字段盖章、软删改写、租户隔离统一在 gdb 模型钩子层完成，dao.Ctx 是唯一查询入口
- **9 张租户级表自动隔离**：Insert 自动填充 tenant_id 与审计字段，Select 自动附加 del_flag 与租户条件
- **租户管理模块**：租户 CRUD、用户数统计
- **事务化开户**：租户与初始管理员同一事务创建（code = T + 4 位 ID）
- **用户上限**：tenant.max_user_num 校验，超限拒绝开户

### 优化

- 业务代码零侵入：不手写一行 del_flag / tenant_id 条件，横切逻辑全部下沉钩子层


## [2.9.0] - 2025-07-06

**共享能力层沉淀，横切逻辑收口。**

### 新增

- **base.go 共享能力层**：文件字段、富文本、枚举文本、唯一校验、事务、分块查询、树、临时清理八类横切能力统一沉淀
- **CheckUnique 唯一性预检**：UX 快速报错，并发真值由数据库 uk_* 唯一索引兜底
- **WithTrans 事务包裹**：错误自动回滚，事务内禁 HTTP/文件 IO，bcrypt 预计算
- **BuildTree 泛型树**：平铺数据转树形，叶子 Children 预置空数组

### 优化

- 共享层导出函数上限 15 个，超出按能力拆分子包，防止能力层膨胀


## [2.8.0] - 2025-05-24

**工具模块与标准示范补齐。**

### 新增

- **example 案例模块**：完整示范七件套 + 导入导出 + 字典文本 + 文件字段的标准写法
- **文件模板管理模块**：模板上传维护，按编码取用（getTemplateByCode）
- **upload 上传模块**：统一上传入口与返回 URL 约定


## [2.7.0] - 2025-04-12

**数据导入导出能力建成。**

### 新增

- **Excel 导入**：excelize 驱动，表头映射导入，空行自动过滤
- **Excel 导出**：标准化导出与文件下载，user / level / example 模块启用
- **大数据量分批导出**：ChunkQuery 分批查询（默认 500 条/页）防内存溢出
- **前端 xlsx 组件**：导入向导与导出按钮统一封装

### 修复

- 富文本跨域名图片占位符替换不完整


## [2.6.0] - 2025-03-01

**文件上传体系与富文本持久化契约。**

### 新增

- **两段式上传**：先落 temp 临时目录（扩展名白名单、单文件大小上限、图片魔数嗅探），表单保存时转正到按日期分子目录的正式位置
- **文件字段统一处理**：SaveFileField / SaveFileFields / SaveMultiFileField，批量转正与 URL 补全
- **富文本占位符契约**：入库 [IMG_URL] 占位、出库统一还原（LocalizeContentFields / ExpandContentFields 唯一出口），外站 URL 不处理规避 SSRF
- **SVG 安全加固**：.svg 响应强制 attachment + nosniff，防存储型 XSS
- **临时目录自动清理**：每日 03:30 清理超期 temp 日期目录（file.tempExpireDays 控制保留天数）

### 优化

- /upload/** 静态访问由 SetServerRoot("resource") 统一提供，上传目录按日期分子目录


## [2.5.0] - 2025-01-17

**内容管理与行政区划能力就绪。**

### 新增

- **文章与分类**：文章 CRUD（封面、图集、状态、点击量），分类树形无限级嵌套
- **通知公告**：类型、发布状态、富文本内容
- **友情链接**：图标、描述、启用/禁用
- **行政区划**：省市县三级数据与树形查询，ResolveCityNames / ResolveCityCodes 编解码（用户模块地址字段接入）

### 优化

- 富文本编辑器全站统一接入；列表状态筛选与模糊搜索标准化


## [2.4.0] - 2024-12-05

**字典、配置与参数三件套，基础数据标准化。**

### 新增

- **字典管理**：字典与字典项两级维护，枚举显示名经 {field}Text 字典驱动（唯一真相，进程内缓存 300s）
- **字典前端消费**：登录即可的查询接口与字典组件，下拉/徽标数据源统一
- **配置管理**：配置与配置项两级维护，站点设置页一键读取与保存
- **参数管理**：系统参数分类维护，请求级缓存
- **字典缓存刷新**：refreshCache 接口即时生效


## [2.3.0] - 2024-10-23

**操作审计与日志查询上线。**

### 新增

- **操作日志中间件**：异步批量落库（100 条或 1 秒刷盘），password/salt 脱敏、响应截断、耗时与状态记录，失败降级日志、不阻塞业务
- **日志类型体系**：新增/修改/删除/查询/导入/导出等 40+ 类型常量，logType 字符串声明驱动
- **日志查询模块**：操作日志/登录日志分页、详情、软删与批量删除
- **IP 归属地**：ip2region（xdb）自动填充归属地字段

### 优化

- 密码类字段响应自动剔除，日志参数统一脱敏


## [2.2.0] - 2024-09-10

**组织架构与个人中心完善。**

### 新增

- **部门/职级/岗位三模块**：部门树形无限级（parent_id 自关联）
- **树形接口约定**：叶子节点 Children 预置空数组，前端免判空
- **个人中心**：获取用户信息与菜单、修改密码（旧密码校验）、更新资料与头像
- 用户列表按部门/角色筛选，禁止删除有子部门/用户的部门


## [2.1.0] - 2024-07-29

**用户、角色与菜单权限体系落地。**

### 新增

- **用户/角色/菜单三模块**：标准七件套（分页/列表/详情/新增/修改/删除/批量删除）
- **RBAC 权限模型**：用户 → 角色 → 菜单权限节点（目录/菜单/按钮三级），按钮级控制
- **超级管理员**：通配权限 *:*:*，权限校验单点入口
- **角色保存权限**：重写角色-菜单关联并即时刷新缓存
- **用户扩展**：重置密码、用户-角色多角色分配、用户名/手机号唯一校验
- **gmeta 标签声明**：路由与权限经标签声明，包装层每请求判定
- 前端用户/角色/菜单管理页，权限指令控制按钮可见性


## [2.0.0] - 2024-06-16

**工程奠基版本：前后端分离骨架与认证闭环建立。**

### 新增

- **后端分层骨架**：api / controller / logic / service 四层 + dao/entity/do 数据访问链路，统一响应信封（code/msg/data）与 PageData 分页
- **建表约定**：goframe_ 表前缀、del_flag 软删列、审计字段（create_user/create_time/update_user/update_time）
- **登录认证**：用户名密码 + 图形验证码（TTF 渲染 + SVG 降级）
- **JWT 双令牌**：access 2 小时 + refresh 7 天，刷新轮换、旧 jti 拉黑防刷新复活
- **密码安全**：bcrypt 双重加盐加密
- **登录日志**：成功/失败/退出全记录（IP、浏览器、耗时、失败原因）
- **中间件链雏形**：CORS → Response → JWT → Demo 演示模式拦截
- **前端工程**：Vite + Vue3 + TypeScript + Pinia + ElementPlus，登录页、主布局、axios 封装与动态路由守卫