签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/changelog.md

@@ -1,52 +1,349 @@
 # 1.6 更新日志
 
-:::tip 概述
-本项目遵循语义化版本演进，重大架构决策与约定变更记录于此。详细提交历史见 [Gitee 仓库](https://gitee.com/easygoadmin/EasyGoAdmin_GoFrame_EleVue)。
+:::tip 说明
+更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。对于开发者，可快速掌握新功能与 API 变更，降低升级成本；对于企业，可评估版本稳定性与功能成熟度，为技术选型和升级决策提供依据。建议在升级前阅读目标版本的变更内容，确保业务代码平滑适配。
 :::
 
-## v4.0.0（2026-10 · 当前版本）
+## 版本总览
 
-GoFrame+ElementPlus 版本首个正式封板版本，25 张业务表 → 27 个模块完整落地。
+| 版本 | 日期 | 主要内容 |
+|:-----|:-----|:---------|
+| **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 | 工程奠基与认证闭环 |
 
-### 架构定稿
 
-+ **主键统一 int 数据库自增**（2026-10-13 定稿）：禁用雪花算法（`utility/id` 已删除）；新增后用 `result.LastInsertId()` 回读；hooks 不填 id
-+ **目录平铺结构**：api/v1、controller、logic、service 均为单包，每模块一个 snake_case 文件，同包 init 自动注册
-+ **中间件链定稿**：CORS → Response → RateLimit → Demo → JWT → Tenant → OperationLog，权限校验在 Bind 包装层完成
-+ **筛选对齐三件套**（2026-10-14 定稿）：前端 querySchemas.ts ↔ XxxPageReq 同名驼峰字段 ↔ spec 声明（LikeFields/EqFields），导出与列表同套筛选
-+ **URL 约定**：全部路由统一 `/api` 前缀，无 `/v1` 版本段；公开白名单三处一致（public.go / gmeta public 标签 / router.go 手工注册）
+## [4.0.0] - 2026-10-20
 
-### 功能清单
+**核心架构定稿：gmeta 标签体系与 ModuleSpec 泛型基座全面落地，路由、权限、日志、文档一体驱动，全域能力就位，生产部署就绪。**
 
-+ 认证与安全：JWT 双令牌（access 2h + refresh 7d 轮换）、jti 黑名单、图形验证码（TTF 渲染 + SVG 降级）、bcrypt 双重加盐、固定窗口限流（认证入口独立阈值）、演示模式、受信代理 IP
-+ 权限体系：RBAC（user→role→menu 权限节点）、gmeta permission 标签、前端权限指令、超管通配权限 `*:*:*`
-+ 多租户：9 张租户级表自动隔离（hooks.tenantTables）、租户状态/过期中间件校验（60s 缓存）、事务化开户、用户上限
-+ 数据权限：role.data_scope 四档（全部/本部门及以下/本部门/仅本人），`ApplyDataScope("dept_id")` 一行声明接线
-+ CRUD 基座：ModuleSpec 泛型（筛选/排序/树形/字典/文件/富文本/唯一校验/钩子/数据权限）
-+ 监控体系：在线用户（双令牌拉黑强退）、服务器监控、缓存监控（Redis INFO）、操作日志（异步批量落库 + 脱敏）、登录日志（ip2region 归属地）
-+ 定时任务：数据驱动调度器、HTTP/本地处理器双形态、三种执行策略、多实例执行锁（job:lock:{id}）、内置 LogClean/CleanTemp
-+ 代码生成器：HTTP + CLI 双入口、后端八件套 + 前端五件产出、菜单/权限/字典/路由幂等副作用、覆盖策略保护
-+ 整库迁移器：五方言互迁（内省 → IR → 方言 DDL → 分批搬运 → 序列修复 → 行数校验）
-+ 文件体系：两段式上传（temp → 正式目录）、富文本 [IMG_URL] 持久化契约、临时目录每日 03:30 自动清理
+### 新增
 
-### 工程保障
+- **gmeta 标签体系定稿**：请求结构体上的一个标签同时驱动路由注册、权限校验、操作日志、OpenAPI 文档四件事，"标签即事实"，杜绝多处不一致
+- **ModuleSpec 泛型基座**：筛选、排序、树形、字典文本、文件字段、富文本、唯一校验、数据权限全部声明化，生命周期钩子承接差异，手写方法为合法逃生舱，基座永不出现按模块分支的代码
+- **OpenAPI 输出**：gmeta 补注册进 goai，/api.json 原生 JSON + /swagger 本地 Redoc 页面
+- **生成器与基座对齐**：生成的 logic 直接产出基座声明式实现，go build 后即可运行
+- **模块版图收口**：监控域（操作日志/登录日志/定时任务/任务日志）与工具域（案例/文件模板/生成器/上传）能力全量就位
 
-+ 静态门禁：`go vet` + `gofmt` 检查；前端 ESLint + Prettier + Stylelint + commitlint
-+ 测试：sqlite 集成测试 + hooks MySQL 集成测试
-+ 回归：hack/golden 黄金样本接口响应比对（录制参数带 pageSize=3 等）
-+ OpenAPI：gmeta 补注册进 gf goai，`/api.json` 原生输出 + `/swagger` 本地 Redoc 页面
+### 优化
 
-## 历史版本
+- **主键策略定稿**（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 页文档站
 
-| 版本 | 说明 |
-|------|------|
-| v4.0.0-beta | 27 模块全量实现，架构决策落地（主键自增、中间件链、筛选三件套定稿） |
-| v4.0.0-alpha | 项目初始化：GoFrame 骨架 + 核心模块（auth/user/role/menu）+ 前端工程搭建 |
+### 修复
 
-## 破坏性变更记录
+- 富文本还原散落的字符串替换统一收敛到 ExpandContentFields 唯一出口，[IMG_URL] 占位符不再被业务代码旁路解析
 
-::: warning 变更须知
-+ 2026-10-13：主键策略由雪花算法改为数据库自增——历史数据的 id 语义不变，但新增代码禁止依赖 `utility/id`（包已删除）。
-+ URL 全部去版本段——`/api/v1/*` 形式的旧链接失效，前端 baseURL 为 `/api`。
-+ 前端登录响应字段为 `access_token/refresh_token/expires_in/token_type`（下划线），与全局驼峰约定不同，这是 OAuth2 惯例，禁止"修正"。
-:::
+
+## [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 封装与动态路由守卫