签入版本

EasyGoAdmin_Gin_AntdVue/zh/changelog.md

@@ -8,460 +8,405 @@
 
 | 版本 | 日期 | 主要内容 |
 |:-----|:-----|:---------|
-| **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 | 项目初始化，基础架构框架搭建 |
+| **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 | 工程奠基与认证闭环 |
 
 
-## [5.0.0] - 2026-10-01
+## [4.0.0] - 2026-10-20
 
-**正式稳定版发布，全面完善文档、安全加固与生产环境适配。**
+**核心架构定稿：RouteSpec 反射元数据体系与 ModuleSpec 泛型基座全面落地，路由、权限、日志、文档一体驱动，全域能力就位，生产部署就绪。**
 
 ### 新增
 
-- **自动参数校验**：Logic 层配置 `$validateClass` 后，`add`/`update` 自动调用验证器校验，覆盖所有 CRUD 入口（含导入），新增 CityValidate、TenantValidate，全模块验证器覆盖率 100%
-- **项目文档体系**：文档站点全面改版，覆盖快速入门、模块开发、架构设计、运维部署全场景
-- **生产环境部署指南**：Docker 容器化支持，提供 Dockerfile + docker-compose.yml 一键部署
-- **系统健康检查接口**：运行状态监控，服务可用性实时检测
-- **多数据库 SQL 脚本**：MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五套完整建表脚本
+- **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 后即可运行，产物与手写规约逐字一致
 
 ### 优化
 
-- **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`
-- 全模块稳定性测试与边界条件覆盖
-- 错误提示信息统一规范化，提升用户友好度
-- 日志输出格式标准化，便于日志采集与分析
-- 依赖包版本锁定，确保生产环境一致性
-- 接口限流策略优化，防止恶意请求
+- **主键策略定稿**（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 原文误当表注释搬迁
 
 ### 修复
 
-- JWT 密钥强制从环境变量读取，禁止硬编码
-- 敏感配置项统一迁移至 `.env` 文件
-- CORS 配置支持环境变量动态指定允许域名
+- 富文本还原散落的字符串替换统一收敛到 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 三形态统一识别
 
 
-## [4.9.0] - 2026-06-18
+## [3.9.0] - 2026-09-07
 
-**OAuth2 认证与令牌管理增强。**
+**OAuth2 令牌治理收口，双令牌全生命周期可管可控。**
 
 ### 新增
 
-- **OAuth2 完整认证流程**：Token 签发 / 刷新 / 吊销 / 检测，兼容标准 OAuth2 协议（`LoginController::token` / `removeToken` / `checkToken`）
-- **Token 黑名单机制**：登出后令牌即时失效，防止令牌被盗用
-- **密码强度校验策略**：长度、复杂度、常见密码库校验
-- **登录日志增强**：增加 IP 归属地与浏览器信息记录
+- **令牌刷新**：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 取各令牌剩余有效期加缓冲），防止登出后凭刷新令牌兑换新令牌重新上线；在线登记缺失时降级仅拉黑当前访问令牌
 
 ### 优化
 
-- JWT access_token 有效期可配置化（默认 2 小时）
-- refresh_token 续签逻辑优化，支持滑动过期
-- 验证码生成算法升级，增加干扰线与噪点
-- 登录失败次数限制与账户锁定机制
+- 登录与刷新响应保持 OAuth2 惯例字段：access_token / refresh_token / expires_in（秒）/ token_type（Bearer）
+- 前端令牌刷新链路统一对接 OAuth2 路由；401 唯一触发刷新或跳登录，刷新仅尝试一次防死循环
+- 令牌载荷携带用户与租户身份及独立 jti；签发与解析校验签名、过期与签发者三要素
 
 
-## [4.8.0] - 2026-04-06
+## [3.8.0] - 2026-07-26
 
-**安全加固与防护增强。**
+**安全加固与防护增强，入口防护成体系。**
 
 ### 新增
 
-- **SQL 注入防护增强**：表名拼接统一经 `validateTableName` 校验，防止注入攻击
-- **XSS 防护增强**：富文本内容过滤策略优化，白名单机制
-- **CORS 配置增强**：支持环境变量动态指定允许域名，凭证模式兼容
-- **演示模式增强**：`#[DemoAllow]` 注解精细化控制，指定接口放行
+- **接口限流**：固定窗口计数限流中间件，计数键按窗口起点对齐（方法 + 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），防超大请求体打爆内存
 
 ### 优化
 
-- 敏感配置项统一迁移至 `.env` 文件，禁止硬编码
-- 请求参数统一校验，空参数与类型错误提前拦截
-- 异常信息脱敏，生产环境不暴露文件路径与行号
+- 限流位于身份解析之前生效，防住未认证阶段的高频攻击；被限流、被鉴权拒绝、未认证、租户拒绝四类请求均不进入链尾操作日志，避免审计表被攻击尝试刷爆，指标侧按 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 秒，角色变更主动失效；重新登录立即生效
 
 ### 修复
 
-- 修复并发请求下会话数据串扰问题
-- 修复文件上传超大文件未中断导致内存溢出
-- 修复特殊字符参数未转义导致的解析异常
+- 未分配部门用户在"本部门"档位越权可见——身份加载层降级为仅本人
 
 
-## [4.7.0] - 2026-01-13
+## [3.1.0] - 2025-09-29
 
-**扩展业务模块，覆盖更多管理场景。**
+**租户治理与状态校验完善。**
 
 ### 新增
 
-- **岗位管理模块**：岗位信息维护与部门关联（PositionController / PositionLogic）
-- **系统参数管理模块**：系统参数与业务参数分类管理（ParamController / ParamLogic / ParamService）
-- **级别管理模块**：级别信息维护与排序（LevelController / LevelLogic）
-- **城市行政区划模块**：城市树形结构与模糊搜索（CityController / CityLogic）
+- **租户状态校验中间件**：租户摘要（状态与过期时间）缓存 60 秒；禁用租户拒绝、过期时间早于当前拒绝；摘要加载失败或加载器未注册时放行（降级，不因租户设施故障阻断全部请求）
+- **租户成员视图**：按租户维度检索用户列表（GET /api/tenant/users/:tenantId）；租户管理员账号维护（POST /api/tenant/account）
+- **平台数据语义明确**：超管（平台级）直接放行；租户用户可见范围为 自身租户加平台共享数据（tenant_id 为 0 的公共行）
+- **租户内唯一约束**：手机号、用户名等唯一性走分组唯一索引，租户内不跨租户冲突
+- **租户错误码体系**：租户已过期、已禁用、用户数达上限、不存在四类业务错误码，登录与中间件统一引用
 
 ### 优化
 
-- 参数管理支持缓存策略，高频参数请求级缓存
-- 城市数据支持树形结构展示与模糊搜索
-- 岗位与部门关联查询优化
-- 字段校验器统一规范化（新增 PositionValidate / ParamValidate / LevelValidate）
+- 登录支持 tenantCode 定位租户（留空按用户名全局定位，优先平台租户）；租户不存在按禁用拦截
 
 
-## [4.6.0] - 2025-11-25
+## [3.0.0] - 2025-08-18
 
-**数据处理能力与文件管理全面增强。**
+**多租户架构与数据隔离建成，SaaS 能力就绪。**
 
 ### 新增
 
-- **文件模板管理模块**：模板文件上传、版本管理与在线编辑（FileTemplateController / FileTemplateLogic）
-- **富文本占位符机制**：`[IMG_URL]` 占位符，入库替换、出库还原域名，迁移无感知
-- **文件字段自动迁移**：临时文件自动迁移至正式目录，自动去除域名前缀
-- **批量导出分批查询**：`chunkList` 支持逐批处理，避免大数据量内存溢出
-
-### 优化
-
-- `save_file` / `save_content` / `get_file_url` 函数链路优化
-- 文件上传 MIME 类型真实检测（`finfo`），不信任客户端声明
-- 上传目录自动按日期分目录，避免单目录文件过多
-- 图片字段与文件字段处理逻辑分离，支持不同校验策略
+- **全局钩子横切**：审计盖章（创建补齐 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 便捷入口；已删行对查询天然不可见
 
 
-## [4.5.0] - 2025-09-16
+## [2.9.0] - 2025-07-06
 
-**代码生成器功能增强与模板优化。**
+**共享能力层沉淀，横切逻辑收口。**
 
 ### 新增
 
-- **批量生成**：支持多表批量生成代码，一次操作完成多模块搭建
-- **代码预览**：生成前可查看所有文件内容，确认无误后再写入
-- **字典自动生成**：从字段注释中提取枚举值，自动生成字典数据
-- **路由与菜单自动生成**：生成代码时自动注册路由与菜单权限节点
+- **service 共享能力层**：字典查询接线（SetDictLookup 由字典模块 init 注册、DictGetText 统一消费，避免反向依赖环）、map 字段取整辅助、切片解引用、单元格取值与取整辅助、行数据取串辅助等横切能力统一沉淀
+- **唯一性预检**：落库前逐条 Count 快速报错（错误码"记录已存在"，携带中文字段标签），并发唯一性最终由数据库 uk_ 唯一索引兜底
+- **事务包裹**：WithTrans 事务入口，回调 ctx 自动携带事务连接（内部全部仓储查询加入事务），返回错误整体回滚；事务使用规约（回调内一律用入参 ctx）固化
+- **树形构建**：基座树形输出（IsTree + ParentOf 取父指针、ChildSetter 子级写入器，缺省反射写 Children 字段），平铺数据自动组树，叶子 Children 预置空数组；父指针缺失或字段缺失在运行期 panic（fail-fast）
 
 ### 优化
 
-- 模板渲染引擎优化，变量替换更精准
-- 字段属性自动分析（图片字段、富文本字段、筛选字段、模糊搜索字段）
-- 生成文件冲突检测，已存在文件提示跳过或覆盖
-- 多数据库驱动适配优化（PostgreSQL / Oracle / SQL Server / SQLite）
+- repository.Base 数据访问基座定稿：Ctx 唯一常规入口（自动注入软删过滤与租户 Scope）、Raw 受限入口（导入、字典管理等明确场景，条件完整性由使用者保证）、ExistsByCond 存在性判断（软删/租户已过滤）
 
 
-## [4.4.0] - 2025-08-07
+## [2.8.0] - 2025-05-24
 
-**性能优化与缓存策略升级。**
+**工具模块与标准示范补齐。**
 
 ### 新增
 
-- **查询参数自动转换**：驼峰转下划线自动转换（`convertQueryParams`），前后端命名风格无感适配
-- **动态排序**：排序字段支持前端动态指定（`orderField` / `orderType`）
-- **返回字段过滤**：前端通过 `fields` 参数指定需要的字段，减少数据传输量
-- **分批查询回调**：`chunkList` 支持逐批回调处理，适合大数据量导出
-
-### 优化
-
-- 数据权限查询缓存（角色权限 1 小时缓存）
-- 字典数据请求级缓存，同一请求内不重复查询
-- 系统参数请求级缓存，减少数据库查询
-- 表字段列表静态缓存，同一请求内只查一次
+- **example 案例模块**：全项目规约参考实现，十个接口覆盖标准 CRUD 全场景——分页（名称模糊、类型状态等值、字典显示名回填）、列表（limit 上限）、详情、新增修改（单图转正）、单列状态更新（手写逻辑）、删除批量删除（软删）、Excel 导入（multipart 逃生舱、逐行校验、失败原因含工作表行号）、Excel 导出（复用基座过滤器、字典翻译列、返回文件访问地址）；导入结果自定义提示语（成功导入 X 条，失败 Y 条）
+- **文件模板管理模块**：模板文件上传登记（名称、编码、文件字段转正），按编码获取（ByCode）供业务页"下载导入模板"标准接入，模板与导入解析列头同源
+- **upload 上传模块**：统一上传入口，单文件与批量上传；返回字段约定（原始文件名、扩展名、MIME 类型、大小、存储文件名、入库相对路径、访问地址），批量返回列表结构
 
 
-## [4.3.0] - 2025-06-21
+## [2.7.0] - 2025-04-12
 
-**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`）
-- 软删除全局查询范围自动过滤已删除数据
+- **Excel 读取封装**：读首个工作表返回表头与数据行（首行表头剥离、空行自动跳过），文件句柄抽象兼容上传文件与普通文件
+- **Excel 写出封装**：按表头与数据行写出 xlsx 到指定目录，返回文件名与路径，配合上传模块转为访问地址
+- **导入范式**：逐行校验（必填、格式）——合法行写入、失败行记录原因（工作表行号 = 数据序号 + 2 折算含表头行号）；无事务逐行独立写入，失败行不影响已写入行；结果汇总返回总数、成功数、失败数与原因列表
+- **导出范式**：查询条件与分页同口径（复用基座过滤器），枚举列按字典翻译（与读侧显示同源），写出文件返回访问地址供前端下载
+- **启用模块**：用户、职级、案例演示三模块启用导入导出
+- **前端配套**：Excel 解析组件、导入交互组件、URL 下载工具统一封装
 
 ### 修复
 
-- 修复批量软删除未关闭全局作用域导致条件叠加的问题
-- 修复富文本内容中域名替换不完整的问题
-- 修复驼峰/下划线转换中数组嵌套场景的边界问题
+- 富文本跨域名图片占位符替换不完整
 
 
-## [3.9.0] - 2024-12-22
+## [2.6.0] - 2025-03-01
 
-**代码生成器上线，开发效率质的飞跃。**
+**文件上传体系与富文本持久化契约。**
 
 ### 新增
 
-- **代码生成器模块**：一键生成 Controller / Logic / Model / Validate / 前端页面（GeneratorController / GeneratorLogic / GeneratorService）
-- **数据表列表查询**：从数据库读取所有表信息，支持按表名搜索
-- **表结构分析**：字段类型归一化与属性自动识别（图片、富文本、筛选项、唯一、模糊搜索）
-- **多数据库适配**：支持 MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五种驱动
+- **两段式上传**：第一段上传落临时目录（日期分桶 + 32 位密码学随机十六进制文件名，防猜测遍历）；第二段表单保存时经转正函数搬到模块正式目录（日期分桶 + 时分秒加随机后缀），入库存相对路径
+- **上传校验**：扩展名白名单（图片与通用文件两套配置）、单文件大小上限、图片类型额外做内容魔数嗅探（非图片头即拒）；任一步失败返回错误且不残留半截文件
+- **文件字段声明驱动**：基座文件字段名单声明即获得写侧批量转正与读侧访问域名补全；多文件字段按逗号分隔逐段处理
+- **富文本占位符契约**：正文内本站文件地址统一存 [IMG_URL] 相对路径占位符，读侧经 ExpandContentFields 唯一还原出口补全域名；外站 URL 原样保留不处理（规避服务端请求伪造）；换域名、迁环境只改配置，正文零改动
+- **路径安全**：路径拼接经安全拼接函数断言（清洗后物理路径必须仍在上传根目录内），防路径穿越；临时目录始终封禁对外访问（防未落库文件被枚举下载）
+- **SVG 安全加固**：.svg 响应强制附件下载加 X-Content-Type-Options nosniff，防内嵌脚本同源执行（存储型 XSS 防护）
+- **临时目录自动清理**：每日 03:30 清理超期临时日期目录（file.tempExpireDays 控制保留天数，0 为不清理）
 
 ### 优化
 
-- 生成代码风格与项目现有代码保持一致
-- 生成的 Validate 自动按字段类型生成校验规则
-- 生成的 Controller 自动配置 `#[Permission]` 与 `#[Log]` 注解
-- 生成的菜单自动挂载到指定父菜单下
+- 生产形态由 Nginx 直供上传目录（file.domainUrl 契约：访问地址 = 域址 + 入库相对路径，不含 upload 段），应用不参与文件服务；本地未配置域名时应用挂开发回退（同样封禁临时目录、路径穿越防护），开发生产行为一致
 
 
-## [3.8.0] - 2024-10-17
+## [2.5.0] - 2025-01-17
 
-**多租户架构，支持 SaaS 化部署。**
+**内容管理与行政区划能力就绪。**
 
 ### 新增
 
-- **租户管理模块**：租户 CRUD、用户数统计、管理员账号创建（TenantController / TenantLogic）
-- **`TenantMiddleware` 租户中间件**：从 JWT 解析用户租户，注入租户上下文
-- **`BaseLogic` 租户隔离**：配置 `tenantScopeField` 后自动按租户过滤数据
-- **租户 ID 自动填充**：新增数据时自动写入 `tenant_id`，超级管理员代入默认租户
-- **租户状态校验**：启用/禁用/过期三种状态，过期租户自动拒绝访问
+- **文章管理**：标题、封面单图、图集多图、简介、富文本正文、作者、状态、点击量、排序；正文走富文本占位符契约，封面走文件字段转正；分类关联与分类名读侧回填；租户级隔离
+- **分类管理**：树形无限级嵌套（parent_id 自关联），基座树形声明组树输出；分类编码与名称维护；被引用删除守卫
+- **通知公告**：标题、封面、类型、点击数、发布状态、富文本内容；上下架单列状态更新
+- **友情链接**：名称、类型、链接地址、表单描述、图标、状态、排序；刻意最小接口集（无列表与状态接口）
+- **行政区划**：省市区县三级数据（编码、父级、级别、经纬度、拼音等全字段），按父级取下级（级联选择器数据源）、省份数据入口、列表聚合接口；大数据量表级联懒加载
 
 ### 优化
 
-- 超级管理员（`tenantId=0`）跳过租户隔离
-- 租户隔离字段可配置化，不同表可指定不同隔离字段
-- 租户信息缓存，减少重复查询
-- `config/tenant.php` 租户配置文件
+- 富文本编辑器全站统一接入（双引擎可选）；列表状态筛选与模糊搜索标准化
 
 
-## [3.7.0] - 2024-09-03
+## [2.4.0] - 2024-12-05
 
-**定时任务调度系统，支持可视化管理。**
+**字典、配置与参数三件套，基础数据标准化。**
 
 ### 新增
 
-- **定时任务管理**：任务 CRUD、Cron 表达式配置、启用/禁用（JobController / JobLogic）
-- **任务执行日志**：完整记录每次执行的开始时间、结束时间、执行状态、耗时、错误详情（JobLogController / JobLogLogic）
-- **Daemon 常驻进程调度器**：后台常驻进程自动调度任务执行
-- **任务操作**：手动执行一次、暂停、恢复、启用/禁用
-- **调度器状态查询**：`daemonStatus` 接口查询 Daemon 进程运行状态与 PID
-
-### 优化
-
-- 任务锁文件机制（`runtime/job_daemon.lock`），防止重复调度
-- 跨平台进程检测（Windows `tasklist` / Linux `posix_kill`）
-- 任务执行异常捕获与日志记录
-- Cron 表达式校验与解析
+- **字典管理**：字典与字典项两级维护（名称、编码、排序、备注）；枚举显示名经基座声明（字段到字典编码映射）在读侧自动回填 {field}Text 字段，字典为显示名唯一真相
+- **字典缓存**：字典项集合按编码缓存（缓存键统一前缀），字典项增删改主动删除对应键、下次读取回源重建；refreshCache 接口手动刷新兜底
+- **字典消费接口**：业务别名接口（字典列表/详情，登录即可）与字典项快捷查询（按编码取全部字典项，登录即可，前端下拉标准数据源）
+- **字典结果翻译**：导出等手写场景经统一字典查询函数翻译枚举列，与读侧显示同口径
+- **配置管理**：配置与配置项两级维护（分组树 + 键值项，选项、类型、状态、排序）；网站配置聚合读取与聚合保存接口（独立权限码），前台设置页一次请求完成读写
+- **参数管理**：扁平单表键值（名称、编码、值、类型、状态、备注），按编码定位，适合独立系统参数
+- **字典枚举约定**：建表列注释按"1-在用 2-停用"标准枚举形态书写，生成器据此自动初始化字典
 
 
-## [3.6.0] - 2024-07-26
+## [2.3.0] - 2024-10-23
 
-**通知公告与友情链接模块。**
+**操作审计与日志查询上线。**
 
 ### 新增
 
-- **通知公告模块**：通知 CRUD、类型管理、发布状态、排序（NoticeController / NoticeLogic）
-- **友情链接模块**：链接 CRUD、图标管理、启用/禁用（LinkController / LinkLogic）
-- **通知类型字典**：通知/公告/提醒三种类型，字典驱动
-- **链接状态管理**：启用/禁用状态控制
-
-### 优化
-
-- 通知内容支持富文本编辑
-- 通知发布状态与排序管理
-- 链接图标与描述字段扩展
-- 列表查询支持状态筛选与模糊搜索
+- **操作日志中间件**：链尾采集（须读到最终响应），采集内容含操作人、请求方法与路径、请求参数摘要、响应码与摘要、耗时、来源 IP、User-Agent 解析（操作系统与浏览器）、IP 归属地
+  - 异步落库：常驻工作协程（仅启动一次）缓冲日志，单批 100 条或定时 1 秒触发刷新，逐条写入日志落地器；单条失败仅记错误日志不影响批内其余；优雅关闭时排空通道残留并最终刷新，防在途日志丢失；落地器未接线时批内条目丢弃（启动期已告警）
+  - 脱敏与截断：密码类字段脱敏（maskSecret）、请求参数统一脱敏后截断（查询参数同样过脱敏，防密码令牌经 URL 直传入日志）、响应摘要截断
+  - 声明驱动：日志标题与类型来自路由声明；总开关与"是否记录查询类"开关独立配置
+  - 拒绝类请求不记录：限流、演示模式、未认证、租户拒绝、权限拒绝均不产生操作日志（指标侧按分类可观测），防审计表被攻击尝试刷爆
+- **日志类型体系**：40 余个类型常量（新增/修改/删除/查询/导入/导出/审批/驳回/提交/上传/下载/发送/同步/代码生成/重置/分配/授权/执行/暂停/恢复/发布/下架/归档/绑定/解绑等），路由声明字符串经映射落库为数值，前端按数值映射显示名（未收录值回退数字文本）
+- **日志查询模块**：操作日志与登录日志的分页、列表、详情、软删除与批量删除（权限码按 operLog / loginLog 域划分）
+- **IP 归属地**：ip2region 离线库（xdb）自动填充归属地字段，登录日志与操作日志共用
+- **登录日志**：登录成功与失败均留痕（失败含错误分类：验证码错误、用户不存在、租户禁用或过期、账号禁用、密码错误），失败日志是安全审计核心素材；日志写失败仅告警不影响登录结果（审计设施故障不阻断业务入口）
 
 
-## [3.5.0] - 2024-06-11
+## [2.2.0] - 2024-09-10
 
-**内容管理模块上线。**
+**组织架构与个人中心完善。**
 
 ### 新增
 
-- **文章管理模块**：文章 CRUD、封面图、图集、状态管理、点击率统计（ArticleController / ArticleLogic）
-- **文章分类模块**：分类 CRUD、树形结构、多级嵌套（CategoryController / CategoryLogic）
-- **分类树形结构**：支持无限级分类嵌套（`parent_id` 自关联）
-- **文章状态管理**：正常/下架两种状态
-
-### 优化
-
-- 分类编码唯一性校验
-- 文章内容支持富文本编辑器
-- 文章排序与置顶功能
-- 分类支持模糊搜索与树形展示
+- **个人中心接口**：当前用户信息（身份、角色、部门聚合）、当前用户菜单树（按角色过滤，前端动态路由与侧边栏唯一数据源）、按 ID 取菜单（管理场景）、修改个人密码（旧密码必验、新密码加盐哈希落库）、更新个人资料
+- **部门管理**：树形组织架构（parent_id 自关联，基座树形声明），删除守卫（存在下级返回"存在下级或关联记录，不能删除"）；部门为数据权限锚点（用户挂部门、角色按部门收敛）
+- **岗位与职级**：扁平定义表维护、启停状态单列更新；职级支持 Excel 导入导出；与用户关联由用户表承载
+- **用户角色关联**：新增与修改请求携带角色 ID 列表，事务内先清后写关联表（空列表即清空全部角色）；关联重写服务方法供事务复用
+- **前端联动**：登录后经菜单接口生成动态路由并注入（懒加载组件映射），侧边栏按路由表渲染；标签页、面包屑随路由联动
 
 
-## [3.4.0] - 2024-04-19
+## [2.1.0] - 2024-07-29
 
-**字典与配置管理，系统基础数据标准化。**
+**用户管理与 RBAC 权限建成。**
 
 ### 新增
 
-- **字典管理模块**：字典 CRUD、字典项管理（DictController / DictLogic / DictItemController / DictItemLogic）
-- **配置管理模块**：配置 CRUD、配置项管理（ConfigController / ConfigLogic / ConfigItemController / ConfigItemLogic）
-- **`DictService` 字典服务**：按编码查询字典值，请求级缓存
-- **`ParamService` 参数服务**：按编码查询系统参数，请求级缓存
-
-### 优化
-
-- 字典数据按编码缓存，同一请求内不重复查询
-- 配置项支持分组管理
-- 字典值与显示名自动映射
-- 配置项支持启用/禁用状态
+- **RBAC 模型**：用户-角色-菜单三级关联（用户角色、角色菜单两张关联表同样建仓储）；菜单表权限节点列承载权限码，菜单类型区分页面与纯权限节点，打开方式支持组件/内链/外链，支持停用与隐藏
+- **权限校验中间件**：权限码来自路由声明（与注册同源），放行条件为免登录路径、未声明权限（登录即可）、超管直通、权限集合命中；拒绝写入拒绝原因与 403 业务响应后终止链
+- **超管语义**：平台级身份（租户为 0）功能权限直通、数据全量可见；超管角色编码与通配权限码为全局保留（防租户自建同名角色提权，保留编码判定加平台门控双重防线）
+- **身份装配**：登录后装配角色编码集合、权限节点集合、数据范围档位（多角色取最宽松）、部门 ID，结果缓存 300 秒、角色变更主动失效
+- **用户管理**：分页（关键字/部门/状态过滤）、详情（含角色与部门信息回显）、新增（租户场景归属租户、密码加盐哈希）、修改（全量表单语义）、启停、重置密码、软删除批量删除、Excel 导入（逐行校验）与导出、打印信息接口
+- **密码体系**：外部盐加 bcrypt 哈希（密码加盐后哈希、盐独立存储防彩虹表、恒时比对防时序侧信道、哈希格式识别兼容迁移）；数据库不存明文
+- **前端权限**：权限指令两枚——包含其一（数组入参 some 判定）与包含全部（every 判定），不满足时移除元素（非隐藏）；超管通配码直通；组合式权限判定函数供条件渲染
 
 
-## [3.3.0] - 2024-03-05
+## [2.0.0] - 2024-06-16
 
-**部门菜单与数据权限体系。**
+**工程奠基与认证闭环。**
 
 ### 新增
 
-- **部门管理模块**：部门 CRUD、树形结构（DeptController / DeptLogic）
-- **菜单管理模块**：菜单 CRUD、目录/菜单/按钮三种类型（MenuController / MenuLogic）
-- **数据权限控制**：全部 / 本部门 / 仅本人三级数据权限
-- **`BaseLogic` 数据权限过滤**：配置 `dataScopeUserField` / `dataScopeDeptField` 后自动过滤
-- **角色数据权限范围**：`data_scope` 字段控制角色可见数据范围
-
-### 优化
-
-- 菜单支持目录 / 菜单 / 按钮三种类型（`type` 字段）
-- 权限节点与菜单分离，按钮级权限控制
-- 部门树形结构展示
-- 数据权限缓存机制（角色权限 1 小时缓存）
+- **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 批处理等价目标
 
 
-## [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 8 框架初始化**：基于 ThinkPHP 8 搭建前后端分离 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`）
-- 软删除全局查询范围自动过滤
-- 审计字段模型事件自动写入
+- 语义化版本：主版本.次版本.修订号；2.x 为能力奠基期，3.x 为域能力补齐期，4.0 为架构定稿
+- 各版本能力均对应当前代码库已落地实现；升级前请结合目标版本条目核对配置键、接口路径与权限码变化