# 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

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

### 新增

- **RouteSpec 反射元数据体系定稿**：控制器方法旁的一条声明同时驱动四件事——路由注册、权限校验、操作日志、OpenAPI 文档，"声明即事实"，杜绝多处不一致
  - 声明字段七个：Method / Path / Summary / Permission / Log / LogType / Public，按控制器集中声明（方法名到路由元数据的映射表）
  - router.Bind 反射扫描控制器方法，按签名过滤（ctx + 请求结构体入参、响应结构体 + error 出参），签名不匹配的方法静默跳过
  - 注册时同步写入进程内路由元数据表（读写锁保护的 map，键为 方法+路径），四个消费方同源读取
  - authz 中间件按元数据 Permission 校验（空 = 登录即可）；operation_log 中间件按 Log/LogType 采集；公开判定读 Public；OpenAPI 生成读全部字段与请求/响应类型
  - 公开接口双来源汇总：基础设施白名单（健康检查、文档、指标端点）与路由元数据 Public 标记，统一经 IsPublicRequest 判定
- **ModuleSpec 泛型基座定稿**：ModuleSpec[Item, LItem, DRes] 三泛型，标准七方法（Page/List/Detail/Add/Update/Delete/BatchDelete）全委托
  - 查询链六步固定顺序生效：Model 数据源工厂、LikeFields 模糊（空串跳过）、EqFields 等值（零值跳过）、KeywordFields 多列 OR（括号包成单个 AND 防优先级问题）、Filter 复杂条件追加、DataScope 数据权限最后收敛
  - 排序链：OrderableFields 前端排序白名单（白名单是排序列注入的唯一防线）、OrderBy 默认排序、ListOrderBy 列表专用排序
  - 输出声明：SerializeMaps 枚举字典回填（status 到 statusText）、FileFields/MultiFileFields 文件字段（写侧转正读侧补域名）、ContentFields 富文本（写侧占位符化读侧还原）、IsTree/ParentOf/ChildSetter 树形输出、FieldLabels 唯一校验标签覆盖
  - 写入声明：ToData 请求转落库映射（审计字段不映射，由钩子补齐）、UniqueFields 唯一性预检（并发最终以数据库唯一索引为准）
  - 生命周期钩子十个：Before/AfterAdd、Before/AfterUpdate、Before/AfterDelete、Before/AfterBatchDelete、AfterPageList、AfterDetail；错误原样上抛，禁 HTTP/文件 IO，禁 append（可就地改元素）
  - 手写方法为合法逃生舱：导入导出、登录、分配角色、状态流转等复杂逻辑直接手写，基座永不出现按模块分支的代码
- **OpenAPI 文档输出**：路由元数据 + 请求/响应类型反射生成 /api.json 原生 JSON；/swagger 提供本地文档页，含权限码与公开标记，受 api.docs 开关控制（生产建议关闭）
- **生成器与基座对齐**：生成的 service 直接产出 ModuleSpec 声明式实现，go build 后即可运行，产物与手写规约逐字一致

### 优化

- **主键策略定稿**（2026-10-13）：统一 int 数据库自增，插入后由 GORM 回读主键，全局钩子不填主键
- **中间件链定稿**：trace → CORS → metrics → response → RateLimit → Demo → JWT → Tenant → Authz → OperationLog，十层顺序固化并注释顺序理由（trace 最先保证全链日志可关联；response 在业务之前保证 panic 恢复包住全部 handler；限流与演示模式在身份之前防未认证高频攻击；JWT、租户、权限逐层依赖前置注入的身份；日志链尾采集须读到最终响应）
- **筛选对齐三件套定稿**（2026-10-14）：前端 querySchemas.ts 查询配置、请求结构体同名驼峰字段、基座声明（LikeFields/EqFields）三处对齐，导出与列表同套筛选条件，所见即所导
- **目录四件套定稿**：dto / repository / service / handler 按层平铺 snake_case 文件，一模块四文件同名成套，跨模块同包直调（无需 import），检索与审查以模块聚合
- **URL 约定收口**：统一 /api 前缀、无版本段；公开白名单在基础设施、路由元数据、汇总判定三处保持一致
- **配置体系定稿**：config.yaml 为基，APP_ 前缀环境变量覆盖（键名 = 配置路径大写下划线，仅覆盖已存在键，空值视为未设置）；.env.example 与配置键一致性经 cmd/api -check-config 硬检查（make check-config）；docker-compose 友好名映射，12-Factor 部署就绪
- **启动与关闭定稿**：启动 fail-fast（配置校验拒绝非法 JWT 密钥与 DSN；生产模式追加拒绝默认密钥、非空万能验证码、未关闭的代码生成器）；优雅关闭顺序固化（停 HTTP（在途请求上限 30 秒）→ 停定时任务 → 关数据库连接池 → 关 Redis），http.Server 读头超时 10 秒防慢速头攻击
- **接线完整性探测**：WireCheck 启动期探测身份加载器、租户加载器、日志落地器三个中间件接线点，缺失仅打告警并说明降级后果，支持按模块裁剪部署形态
- **工程保障**：make check 一站式门禁（gofmt 检查 + go vet + 短测试 + 配置一致性检查）；sqlite（免 CGO）与 MySQL 集成测试；docker compose 一键部署；开发者文档站
- **迁移注释链路补齐**：表/列注释随结构全方言落地——mysql 列注释改为建表内联（原 ALTER MODIFY 补写会整体替换列定义、丢自增/非空/默认值约束）、pgsql/oracle 走 COMMENT ON 语句、mssql 走扩展属性 MS_Description（IF NOT EXISTS 防重复）；源端补齐 mssql 列注释（扩展属性）与 oracle 列注释（user_col_comments）读取；sqlite 无注释机制——作为目标不产出注释、作为源不再把建表 DDL 原文误当表注释搬迁

### 修复

- 富文本还原散落的字符串替换统一收敛到 ExpandContentFields 唯一出口，[IMG_URL] 占位符不再被业务代码旁路解析
- 整库迁移以 SQL Server 为源时内省必失败（查询了 sys.columns 不存在的列）——改经 OBJECT_DEFINITION(default_object_id) 取默认值并归一 ((0))、N'x'、getdate() 等形态；is_nullable 为 BIT 列、驱动返回 true/false，原按 "YES" 判定导致全部列被误判 NOT NULL、搬迁后写入即报空值错误——YES/true/1 三形态统一识别


## [3.9.0] - 2026-09-07

**OAuth2 令牌治理收口，双令牌全生命周期可管可控。**

### 新增

- **令牌刷新**：POST /api/oauth2/token（公开接口），grant_type 支持 refresh_token 与 password 两种授权模式；刷新签发新令牌对的同时将旧 refresh_token 即时拉黑，杜绝重放续期
- **令牌检测**：GET /api/oauth2/check/token 校验当前 access_token 有效性（未过期且未被拉黑），返回 valid 与令牌归属 userId
- **令牌吊销**：DELETE /api/oauth2/remove/:token 指定令牌即时失效，配合在线用户页强制下线
- **会话级联动拉黑**：登出与强制下线按在线登记一次性拉黑该会话的访问令牌与刷新令牌（TTL 取各令牌剩余有效期加缓冲），防止登出后凭刷新令牌兑换新令牌重新上线；在线登记缺失时降级仅拉黑当前访问令牌

### 优化

- 登录与刷新响应保持 OAuth2 惯例字段：access_token / refresh_token / expires_in（秒）/ token_type（Bearer）
- 前端令牌刷新链路统一对接 OAuth2 路由；401 唯一触发刷新或跳登录，刷新仅尝试一次防死循环
- 令牌载荷携带用户与租户身份及独立 jti；签发与解析校验签名、过期与签发者三要素


## [3.8.0] - 2026-07-26

**安全加固与防护增强，入口防护成体系。**

### 新增

- **接口限流**：固定窗口计数限流中间件，计数键按窗口起点对齐（方法 + IP + 路径 + 窗口），经共享缓存原子递增、多实例计数一致
  - 双档阈值：普通接口 rateLimit.limit（默认 120 次/窗口/IP/路径）；认证入口独立更严阈值 rateLimit.authLimit（默认 10 次/窗口/IP），认证入口精确匹配登录、验证码、令牌兑换三路径
  - 仅作用于 /api 前缀接口，健康检查显式豁免，文档与指标端点自然排除；阈值或窗口配置为非正数视为关闭；计数存储故障时放行（限流不阻断业务）；超限写入拒绝原因并终止链，不产生操作日志，指标归类 denied
- **受信代理**：api.proxyIps（逗号分隔，支持 CIDR）列表内的代理来源才信任 X-Forwarded-For 首段与 X-Real-IP，防来源 IP 伪造
- **演示模式精细化**：app.demo 开启后按 HTTP 方法判定——GET/HEAD/OPTIONS 与公开路径精确放行，其余方法统一拦截并提示"演示环境，禁止操作"，拒绝不产生操作日志
- **健康检查**：/api/health 公开探测接口，返回服务状态，供负载均衡与容器探活使用
- **请求体防护**：api.maxBodyMB 请求体大小上限（默认 10MB），防超大请求体打爆内存

### 优化

- 限流位于身份解析之前生效，防住未认证阶段的高频攻击；被限流、被鉴权拒绝、未认证、租户拒绝四类请求均不进入链尾操作日志，避免审计表被攻击尝试刷爆，指标侧按 denied/error 分类可观测


## [3.7.0] - 2026-06-13

**五方言驱动与整库迁移能力建成，数据库选型与搬迁零代码切换。**

### 新增

- **五方言驱动注册表**：驱动名到方言工厂的注册表，MySQL / PostgreSQL / SQL Server / SQLite 四方业内置预注册，Oracle 经构建标签（-tags oracle）启用、经 RegisterDriver 挂入；改 database.default.driver 一处即换库，业务代码零改动
- **连接装配**：DSN 按驱动拼装（各方言 params 示例内置注释），连接池参数（最大打开/空闲连接、连接最大存活时间）配置化；SQL 调试日志受 debug 开关控制，生产可关
- **SQLite 纯 Go 实现**：免 CGO 编译，文件库场景（dbname 为文件路径）开箱即用，亦支撑免外部依赖的集成测试
- **五份方言初始化脚本**：document/ 目录按方言定稿，与 MySQL 基准逐表对齐，全新环境按方言导入即就绪
- **整库迁移器**：internal/migrate 五模块流水线——源库内省（表/列/索引）、中间表示、目标方言 DDL 渲染、分批数据搬运、序列/自增修复，行数校验闭环
- **迁移 CLI**：源/目标全参数（类型、主机、端口、库名、账号、密码），-drop-target-first 迁移前物理清空目标（不可恢复，慎用）；Oracle 经构建标签启用

### 优化

- 方言 DDL 差异（类型映射、引号、自增语法）收敛于 DDL 生成模块，新增方言只需补类型映射表


## [3.6.0] - 2026-05-01

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

### 新增

- **双入口**：CLI（cmd/gen）与 Web 页面（tool/generator）共享同一生成引擎
  - CLI：-tables 参数格式"表名|表注释"（多表英文逗号分隔，表注释进文件头与菜单名）、-preview 仅预览打印不落盘不注册副作用；配套 make gen / make gen-preview 目标
  - Web：表列表查询（表名/注释模糊，返回引擎、行数、数据大小、自增当前值、排序规则等元数据）、代码预览（文件树 + 内容）、一键生成、批量生成；权限码 sys:generator:* 保护
- **产物**：后端四件套（dto / repository / service / handler）+ 前端五件（api 模块、index / edit / detail 页面、columns 列配置、querySchemas 查询配置）；树形表自动切换 ui2 模板产出树形页面
- **幂等副作用**：菜单与权限节点幂等创建（挂载位置由 generator.parentMenuId 指定）、字典与字典项按枚举列自动初始化、router.go 路由声明块按模块标记幂等追加（重复生成不重复插入）
- **注释驱动推断**：列注释标准枚举形态（1-在用 2-停用）推断字典与 SerializeMaps；uk_ 前缀唯一索引推断 UniqueFields；parent_id 列推断树形；tenant_id 列按租户级模块产出
- **生成结果分类呈现**：新建（generated）、跳过（skipped）、覆盖（overwritten）、失败（failed）四类文件清单，附菜单创建、字典初始化、路由声明三项副作用结果

### 优化

- **覆盖保护**：generator.overwrite 为 false 时缺失补生成、存在跳过（保护手写内容）；为 true 时全部产物覆盖重新生成（模板升级同步用）
- 生成代码统一 gofmt；生产模式（app.prod）启动校验拒绝未关闭的生成器（其具备写服务器源码能力）


## [3.5.0] - 2026-03-21

**运行监控体系上线，运行状态一目了然。**

### 新增

- **服务器监控**：CPU、内存、磁盘、goroutine 数等主机指标采集，实现按平台拆分（windows / linux / other 三实现，公共接口一致），goroutine 数反映应用内部状态、突增可定位泄漏或堆积
- **缓存监控**：经缓存层原始操作（PING 延迟探测、Info 分区解析、DBSize 键空间规模）展示 Redis 运行视图；内存降级模式返回 memory 模式标识，避免把降级态误读为真实 Redis
- **监控接口**：GET /api/server/info（权限码 sys:server:info）与 GET /api/cache/info（权限码 sys:cache:info），前端图表化呈现
- **HTTP 指标**：Prometheus 指标中间件采集请求总数（按路由模板/方法/状态/结果分类）与耗时直方图（多档桶），/metrics 端点受 api.metrics 开关控制；trace_id 只进日志严禁进指标标签（防高基数）的红线固化


## [3.4.0] - 2026-02-05

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

### 新增

- **LogClean 内置任务**：分批物理清理操作日志、登录日志、任务日志三张表中创建时间早于保留期限的记录
  - 保留天数优先取任务参数 retentionDays，缺省回退配置 job.logRetentionDays（再缺省 90 天）
  - 单批删除 5000 行、单表单次任务上限 20 万行，防长事务与失控清理；残留留待下次调度，按时间阈值删除天然幂等
  - 物理删除经 WithPhysicalDelete 显式放行，放行仅在本任务 ctx 作用域内生效（定时清理是唯一的物理删除场景）
- **在线用户模块**：登录登记、登出注销；在线列表（有序集合按令牌过期时间排序 + 明细键）与强制下线（按会话 jti 单独踢出、按 userId 踢出全部设备）；列表与强退按租户隔离；多端登录并存不互踢
- **任务执行策略与同步标记协同**：执行策略三种（立即执行 / 执行一次 / 放弃）配合是否同步标记，避免同实例与多实例重复执行

### 优化

- 上传临时目录清理纳入调度统一管理（每日 03:30 触发，按 file.tempExpireDays 保留，超期日期目录自动清理）


## [3.3.0] - 2025-12-24

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

### 新增

- **常驻调度器**：基于成熟 cron 库，启动时按数据库任务记录重建挂载，Cron 表达式或 @every 描述符触发；调度基础设施在 service 任务模块，任务实现集中于独立任务包
- **处理器注册模型**：任务包每任务一文件，init 中经 RegisterJobHandler 注册（注册名与任务记录 url 字段一致，数据驱动查找；重复注册启动期 panic 保证全局唯一）；处理器签名统一为 上下文 + 参数文本 返回 摘要 + 错误；空白导入触发注册，依赖方向单向（任务包到服务包）
- **内置任务三个**：HelloWorld（链路连通性验证，无状态无副作用）、SendSms（短信发送占位，参数约定 phone/content 结构，供后续接入通道）、LogClean（见 3.4.0）
- **多实例执行锁**：执行锁键按任务 ID 生成（共享缓存 SET NX），TTL 默认 300 秒且执行期自动续期，长任务不会被并发抢占；单例与放弃策略叠加锁
- **任务日志**：每次执行写任务日志表（任务名/组、触发器、cron 表达式、开始/结束时间、耗时、状态、异常详情、参数与摘要文本），失败写入日志不影响下次调度
- **任务操作接口**：立即执行、暂停（cron 摘除）、恢复（cron 重新挂载）、状态设置、调度器守护状态查询；任务管理界面配套

### 优化

- 优雅关闭链中"停定时任务"排在"关数据库"之前，任务可能还在写库，先停任务再关连接，避免执行期报错


## [3.2.0] - 2025-11-11

**角色数据权限四档上线，行级可见性可治理。**

### 新增

- **四档数据范围**：全部 / 本部门及以下 / 本部门 / 仅本人，档位存于角色，多角色用户在身份装配层取最宽松
- **一行接线**：ApplyDataScope 部门列名工厂声明到模块基座即生效，作用于分页、列表、导出（applyFilters 链最后一步）；详情、单条更新删除不过滤（由权限节点与租户隔离兜底）
- **子孙部门计算**：本部门及以下档位按部门树计算子孙集合（dept IN 子孙），部门调整即时影响可见范围
- **豁免与兜底**：平台级身份豁免过滤；未分配部门的用户挂部门档时降级为仅本人（安全兜底，杜绝越权可见）
- **身份缓存**：角色、权限节点、数据范围、部门随身份缓存 300 秒，角色变更主动失效；重新登录立即生效

### 修复

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


## [3.1.0] - 2025-09-29

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

### 新增

- **租户状态校验中间件**：租户摘要（状态与过期时间）缓存 60 秒；禁用租户拒绝、过期时间早于当前拒绝；摘要加载失败或加载器未注册时放行（降级，不因租户设施故障阻断全部请求）
- **租户成员视图**：按租户维度检索用户列表（GET /api/tenant/users/:tenantId）；租户管理员账号维护（POST /api/tenant/account）
- **平台数据语义明确**：超管（平台级）直接放行；租户用户可见范围为 自身租户加平台共享数据（tenant_id 为 0 的公共行）
- **租户内唯一约束**：手机号、用户名等唯一性走分组唯一索引，租户内不跨租户冲突
- **租户错误码体系**：租户已过期、已禁用、用户数达上限、不存在四类业务错误码，登录与中间件统一引用

### 优化

- 登录支持 tenantCode 定位租户（留空按用户名全局定位，优先平台租户）；租户不存在按禁用拦截


## [3.0.0] - 2025-08-18

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

### 新增

- **全局钩子横切**：审计盖章（创建补齐 create_user/create_time/del_flag，更新盖章 update_user/update_time）、物理删除拦截（默认拒绝一切物理 DELETE）、查询侧 Scope 注入统一在 GORM 钩子层完成；repository.Ctx 是唯一常规查询入口，业务代码零手写 del_flag 与 tenant_id 条件
- **租户白名单机制**：含 tenant_id 的租户级表清单集中登记（用户/用户角色/角色/部门/职级/岗位/文章/分类/公告/友链共 9 张），写侧自动填充、读侧自动过滤均以此为唯一判定依据；新增租户级表必须同步登记
- **写侧租户填充**：租户用户写入未指定租户时强制携带自身（零值视为未指定，防跨租户逃逸）；超管未指定时代入默认租户（tenant.defaultId），显式传 0 可创建平台共享行
- **读侧租户过滤**：非平台级身份对租户级表追加 tenant_id IN (0, 自身租户) 条件，于 SQL 构建前经 Scope 注入
- **租户管理模块**：租户 CRUD、启停、有效期管理、用户数统计
- **事务化开户**：租户与初始管理员账号同一事务创建（失败整体回滚），租户编码自动生成（T 前缀加数字序列）
- **用户上限管控**：tenant.max_user_num 校验，超限拒绝开户
- **软删除体系**：一切删除走软删除（UPDATE del_flag=1），仓储层提供 SoftDelete / SoftDeleteByID 便捷入口；已删行对查询天然不可见


## [2.9.0] - 2025-07-06

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

### 新增

- **service 共享能力层**：字典查询接线（SetDictLookup 由字典模块 init 注册、DictGetText 统一消费，避免反向依赖环）、map 字段取整辅助、切片解引用、单元格取值与取整辅助、行数据取串辅助等横切能力统一沉淀
- **唯一性预检**：落库前逐条 Count 快速报错（错误码"记录已存在"，携带中文字段标签），并发唯一性最终由数据库 uk_ 唯一索引兜底
- **事务包裹**：WithTrans 事务入口，回调 ctx 自动携带事务连接（内部全部仓储查询加入事务），返回错误整体回滚；事务使用规约（回调内一律用入参 ctx）固化
- **树形构建**：基座树形输出（IsTree + ParentOf 取父指针、ChildSetter 子级写入器，缺省反射写 Children 字段），平铺数据自动组树，叶子 Children 预置空数组；父指针缺失或字段缺失在运行期 panic（fail-fast）

### 优化

- repository.Base 数据访问基座定稿：Ctx 唯一常规入口（自动注入软删过滤与租户 Scope）、Raw 受限入口（导入、字典管理等明确场景，条件完整性由使用者保证）、ExistsByCond 存在性判断（软删/租户已过滤）


## [2.8.0] - 2025-05-24

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

### 新增

- **example 案例模块**：全项目规约参考实现，十个接口覆盖标准 CRUD 全场景——分页（名称模糊、类型状态等值、字典显示名回填）、列表（limit 上限）、详情、新增修改（单图转正）、单列状态更新（手写逻辑）、删除批量删除（软删）、Excel 导入（multipart 逃生舱、逐行校验、失败原因含工作表行号）、Excel 导出（复用基座过滤器、字典翻译列、返回文件访问地址）；导入结果自定义提示语（成功导入 X 条，失败 Y 条）
- **文件模板管理模块**：模板文件上传登记（名称、编码、文件字段转正），按编码获取（ByCode）供业务页"下载导入模板"标准接入，模板与导入解析列头同源
- **upload 上传模块**：统一上传入口，单文件与批量上传；返回字段约定（原始文件名、扩展名、MIME 类型、大小、存储文件名、入库相对路径、访问地址），批量返回列表结构


## [2.7.0] - 2025-04-12

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

### 新增

- **Excel 读取封装**：读首个工作表返回表头与数据行（首行表头剥离、空行自动跳过），文件句柄抽象兼容上传文件与普通文件
- **Excel 写出封装**：按表头与数据行写出 xlsx 到指定目录，返回文件名与路径，配合上传模块转为访问地址
- **导入范式**：逐行校验（必填、格式）——合法行写入、失败行记录原因（工作表行号 = 数据序号 + 2 折算含表头行号）；无事务逐行独立写入，失败行不影响已写入行；结果汇总返回总数、成功数、失败数与原因列表
- **导出范式**：查询条件与分页同口径（复用基座过滤器），枚举列按字典翻译（与读侧显示同源），写出文件返回访问地址供前端下载
- **启用模块**：用户、职级、案例演示三模块启用导入导出
- **前端配套**：Excel 解析组件、导入交互组件、URL 下载工具统一封装

### 修复

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


## [2.6.0] - 2025-03-01

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

### 新增

- **两段式上传**：第一段上传落临时目录（日期分桶 + 32 位密码学随机十六进制文件名，防猜测遍历）；第二段表单保存时经转正函数搬到模块正式目录（日期分桶 + 时分秒加随机后缀），入库存相对路径
- **上传校验**：扩展名白名单（图片与通用文件两套配置）、单文件大小上限、图片类型额外做内容魔数嗅探（非图片头即拒）；任一步失败返回错误且不残留半截文件
- **文件字段声明驱动**：基座文件字段名单声明即获得写侧批量转正与读侧访问域名补全；多文件字段按逗号分隔逐段处理
- **富文本占位符契约**：正文内本站文件地址统一存 [IMG_URL] 相对路径占位符，读侧经 ExpandContentFields 唯一还原出口补全域名；外站 URL 原样保留不处理（规避服务端请求伪造）；换域名、迁环境只改配置，正文零改动
- **路径安全**：路径拼接经安全拼接函数断言（清洗后物理路径必须仍在上传根目录内），防路径穿越；临时目录始终封禁对外访问（防未落库文件被枚举下载）
- **SVG 安全加固**：.svg 响应强制附件下载加 X-Content-Type-Options nosniff，防内嵌脚本同源执行（存储型 XSS 防护）
- **临时目录自动清理**：每日 03:30 清理超期临时日期目录（file.tempExpireDays 控制保留天数，0 为不清理）

### 优化

- 生产形态由 Nginx 直供上传目录（file.domainUrl 契约：访问地址 = 域址 + 入库相对路径，不含 upload 段），应用不参与文件服务；本地未配置域名时应用挂开发回退（同样封禁临时目录、路径穿越防护），开发生产行为一致


## [2.5.0] - 2025-01-17

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

### 新增

- **文章管理**：标题、封面单图、图集多图、简介、富文本正文、作者、状态、点击量、排序；正文走富文本占位符契约，封面走文件字段转正；分类关联与分类名读侧回填；租户级隔离
- **分类管理**：树形无限级嵌套（parent_id 自关联），基座树形声明组树输出；分类编码与名称维护；被引用删除守卫
- **通知公告**：标题、封面、类型、点击数、发布状态、富文本内容；上下架单列状态更新
- **友情链接**：名称、类型、链接地址、表单描述、图标、状态、排序；刻意最小接口集（无列表与状态接口）
- **行政区划**：省市区县三级数据（编码、父级、级别、经纬度、拼音等全字段），按父级取下级（级联选择器数据源）、省份数据入口、列表聚合接口；大数据量表级联懒加载

### 优化

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


## [2.4.0] - 2024-12-05

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

### 新增

- **字典管理**：字典与字典项两级维护（名称、编码、排序、备注）；枚举显示名经基座声明（字段到字典编码映射）在读侧自动回填 {field}Text 字段，字典为显示名唯一真相
- **字典缓存**：字典项集合按编码缓存（缓存键统一前缀），字典项增删改主动删除对应键、下次读取回源重建；refreshCache 接口手动刷新兜底
- **字典消费接口**：业务别名接口（字典列表/详情，登录即可）与字典项快捷查询（按编码取全部字典项，登录即可，前端下拉标准数据源）
- **字典结果翻译**：导出等手写场景经统一字典查询函数翻译枚举列，与读侧显示同口径
- **配置管理**：配置与配置项两级维护（分组树 + 键值项，选项、类型、状态、排序）；网站配置聚合读取与聚合保存接口（独立权限码），前台设置页一次请求完成读写
- **参数管理**：扁平单表键值（名称、编码、值、类型、状态、备注），按编码定位，适合独立系统参数
- **字典枚举约定**：建表列注释按"1-在用 2-停用"标准枚举形态书写，生成器据此自动初始化字典


## [2.3.0] - 2024-10-23

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

### 新增

- **操作日志中间件**：链尾采集（须读到最终响应），采集内容含操作人、请求方法与路径、请求参数摘要、响应码与摘要、耗时、来源 IP、User-Agent 解析（操作系统与浏览器）、IP 归属地
  - 异步落库：常驻工作协程（仅启动一次）缓冲日志，单批 100 条或定时 1 秒触发刷新，逐条写入日志落地器；单条失败仅记错误日志不影响批内其余；优雅关闭时排空通道残留并最终刷新，防在途日志丢失；落地器未接线时批内条目丢弃（启动期已告警）
  - 脱敏与截断：密码类字段脱敏（maskSecret）、请求参数统一脱敏后截断（查询参数同样过脱敏，防密码令牌经 URL 直传入日志）、响应摘要截断
  - 声明驱动：日志标题与类型来自路由声明；总开关与"是否记录查询类"开关独立配置
  - 拒绝类请求不记录：限流、演示模式、未认证、租户拒绝、权限拒绝均不产生操作日志（指标侧按分类可观测），防审计表被攻击尝试刷爆
- **日志类型体系**：40 余个类型常量（新增/修改/删除/查询/导入/导出/审批/驳回/提交/上传/下载/发送/同步/代码生成/重置/分配/授权/执行/暂停/恢复/发布/下架/归档/绑定/解绑等），路由声明字符串经映射落库为数值，前端按数值映射显示名（未收录值回退数字文本）
- **日志查询模块**：操作日志与登录日志的分页、列表、详情、软删除与批量删除（权限码按 operLog / loginLog 域划分）
- **IP 归属地**：ip2region 离线库（xdb）自动填充归属地字段，登录日志与操作日志共用
- **登录日志**：登录成功与失败均留痕（失败含错误分类：验证码错误、用户不存在、租户禁用或过期、账号禁用、密码错误），失败日志是安全审计核心素材；日志写失败仅告警不影响登录结果（审计设施故障不阻断业务入口）


## [2.2.0] - 2024-09-10

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

### 新增

- **个人中心接口**：当前用户信息（身份、角色、部门聚合）、当前用户菜单树（按角色过滤，前端动态路由与侧边栏唯一数据源）、按 ID 取菜单（管理场景）、修改个人密码（旧密码必验、新密码加盐哈希落库）、更新个人资料
- **部门管理**：树形组织架构（parent_id 自关联，基座树形声明），删除守卫（存在下级返回"存在下级或关联记录，不能删除"）；部门为数据权限锚点（用户挂部门、角色按部门收敛）
- **岗位与职级**：扁平定义表维护、启停状态单列更新；职级支持 Excel 导入导出；与用户关联由用户表承载
- **用户角色关联**：新增与修改请求携带角色 ID 列表，事务内先清后写关联表（空列表即清空全部角色）；关联重写服务方法供事务复用
- **前端联动**：登录后经菜单接口生成动态路由并注入（懒加载组件映射），侧边栏按路由表渲染；标签页、面包屑随路由联动


## [2.1.0] - 2024-07-29

**用户管理与 RBAC 权限建成。**

### 新增

- **RBAC 模型**：用户-角色-菜单三级关联（用户角色、角色菜单两张关联表同样建仓储）；菜单表权限节点列承载权限码，菜单类型区分页面与纯权限节点，打开方式支持组件/内链/外链，支持停用与隐藏
- **权限校验中间件**：权限码来自路由声明（与注册同源），放行条件为免登录路径、未声明权限（登录即可）、超管直通、权限集合命中；拒绝写入拒绝原因与 403 业务响应后终止链
- **超管语义**：平台级身份（租户为 0）功能权限直通、数据全量可见；超管角色编码与通配权限码为全局保留（防租户自建同名角色提权，保留编码判定加平台门控双重防线）
- **身份装配**：登录后装配角色编码集合、权限节点集合、数据范围档位（多角色取最宽松）、部门 ID，结果缓存 300 秒、角色变更主动失效
- **用户管理**：分页（关键字/部门/状态过滤）、详情（含角色与部门信息回显）、新增（租户场景归属租户、密码加盐哈希）、修改（全量表单语义）、启停、重置密码、软删除批量删除、Excel 导入（逐行校验）与导出、打印信息接口
- **密码体系**：外部盐加 bcrypt 哈希（密码加盐后哈希、盐独立存储防彩虹表、恒时比对防时序侧信道、哈希格式识别兼容迁移）；数据库不存明文
- **前端权限**：权限指令两枚——包含其一（数组入参 some 判定）与包含全部（every 判定），不满足时移除元素（非隐藏）；超管通配码直通；组合式权限判定函数供条件渲染


## [2.0.0] - 2024-06-16

**工程奠基与认证闭环。**

### 新增

- **Gin 工程骨架**：四件套分层定型（dto 契约、repository 数据访问、service 业务、handler 接口委托），依赖单向；配置、日志、缓存等基础设施收敛独立工具包（无业务语义、不反向依赖业务层）
- **统一响应信封**：四字段结构（业务码、成功标记、提示语、数据）；对外码值三分支语义——0 成功、1 失败（提示语说明原因）、401 未认证（原码透出供前端跳登录）；构造函数覆盖成功、自定义文案、分页、失败、指定错误码五形态；无路由返回 JSON 404、兜底恢复返回 JSON 500，绝不出现 HTML 错误页
- **请求绑定引擎**：写入顺序 query、body、path（后写覆盖，最终路径参数优先）；校验读 binding 标签、错误消息取 msg 标签（多规则以分号分段一一对应，单段适用全部规则，缺失按规则默认提示兜底），快速失败返回首条错误；内嵌分页结构递归校验；文件类请求经请求体解析逃生舱接口接管（multipart 表单标准姿势）
- **公共契约结构**：分页请求（页码兜底 1、每页条数默认 10 上限 500）、分页结果五字段（记录列表空时输出空数组而非空值）、空响应壳、本地时间包装（空值输出空值、统一格式化）
- **JWT 双令牌认证**：访问令牌短时效、刷新令牌长时效，载荷携带用户与租户身份及独立令牌标识；签发、解析（签名/过期/签发者三校验）、有效期查询工具化
- **图形验证码**：随机字符（长度 4 到 8 可配、字符集排除易混淆字符）加随机标识，答案存缓存（有效期可配）；TTF 字体渲染 PNG、字体缺失自动降级 SVG（前端同为 dataURL 无感）；干扰线与噪点可配；一码一用（无论比对成败均消费，防爆破重放）；标识为空宽松放行；万能验证码仅开发调试（生产模式拒绝非空配置）
- **中间件基座**：trace（入站追踪标识透传或本地生成、回显响应头、注入请求元信息，预检请求降级仅注入标识）、CORS（来源回显与 Vary 头、预检 204 终止、凭证模式、最大预检缓存）、响应包裹（统一信封出口加 panic 恢复，包住其后全部 handler）
- **配置体系**：config.yaml 十六配置节（服务、日志、数据库、缓存、令牌、验证码、限流、操作日志、任务、租户、应用、接口、跨域、文件、生成器、归属地库）；环境变量覆盖；启动 fail-fast 校验（令牌密钥与数据源不合法直接拒绝启动）
- **日志与缓存**：结构化日志（支持上下文追踪字段、控制台与文件双目标、级别可配）；缓存抽象（Redis 探测失败自动降级内存并告警，业务无感知）
- **错误体系**：业务错误类型（错误码加消息，格式化构造）；通用与认证、租户、守卫三组错误码别名统一从常量包引用（内部层只依赖单一入口）
- **服务生命周期**：HTTP 服务封装（读头超时防慢速头攻击）；信号驱动优雅关闭（停止接收新请求、在途请求上限 30 秒、按序释放任务、数据库、缓存）；优雅关闭顺序固化
- **工程命令**：make 目标体系（运行、构建、测试、短测试、检查门禁），Windows 批处理等价目标


## 附：版本说明

- 语义化版本：主版本.次版本.修订号；2.x 为能力奠基期，3.x 为域能力补齐期，4.0 为架构定稿
- 各版本能力均对应当前代码库已落地实现；升级前请结合目标版本条目核对配置键、接口路径与权限码变化