# 数据库层改进方案 (MyBatis-Plus 升级)

## 1. 框架引入与集成 (MyBatis-Plus)
- [x] **依赖升级**：引入 `mybatis-plus-boot-starter` 3.5.3.1 ，兼容现有 SpringBoot 版本。
- [x] **配置迁移**：将原 `mybatis` 配置节点平移至 `mybatis-plus`。
- [x] **插件配置**：新增 `MybatisPlusConfig`，集成分页插件 (`PaginationInnerInterceptor`)、乐观锁及防全表更新插件。
- [x] **自动填充**：实现 `MetaObjectHandler`，支持 `createTime`、`updateTime` 等基础字段的自动化维护。
- [x] **渐进式兼容**：保留原有 XML 映射机制，支持 `BaseMapper` 与自定义 XML SQL 混用。

## 2. 主键标准化 (统一 ID 方案)
- [ ] **数据库重构**：编写 SQL 脚本，将所有业务表的主键字段名统一修改为 `id` (例如 `user_id` -> `id`)。
- [x] **Java 层双主键映射**：
- [ ] 在 Domain 类中新增 `id` 字段并标记为 `@TableId`。
- [ ] 保留旧字段 (如 `userId`) 并标记为 `@TableField(exist = false)`。
- [ ] 实现双向联动 Setter ，确保新旧代码逻辑无感切换。
- [ ] **XML 映射更新**：批量修改 `resultMap` 中的 `<id>` 标签，将其指向新的数据库 `id` 列。
- [ ] **前端解耦**：逐步将前端表格与 JS 中的 `row.userId` 引用切换为通用的 `row.id`。

## 3. 删除标记标准化 (逻辑删除)
- [ ] **逻辑删除方案演进 (规划中)**：
- [ ] **字段更名**：将 `del_flag` 统一更名为 `deleted`。
- [ ] **类型切换**：由 `String (char/varchar)` 切换为 `Boolean (bit)`。
- [ ] **值规范化**：放弃 `0/2` 逻辑，统一使用 `0 (false/正常)` 和 `1 (true/已删除)`。
- [ ] **全局配置调整**：待数据库调整后，更新 `application.yml` 中的 `logic-delete-field` 及对应 value 。
- [ ] **实体类同步**：批量将 Domain 实体中的 `delFlag` (String) 重构为 `deleted` (Boolean)，并标注 `@TableLogic`。
- [ ] **历史 SQL 适配**：清理 XML 中手动拼写的 `del_flag = '0'` 硬编码条件。

## 4. 字段语义清晰化与命名规范化（规划中）
- [ ] **命名统一**：对表名、字段名进行语义化重命名，避免缩写/歧义命名，提升可读性与跨团队理解一致性。
- [ ] **类型对齐**：将枚举/状态位字段尽量收敛为 `Boolean` 或明确的枚举值，减少魔法值（如 `0/1/2`）的传播。
- [ ] **示例**：
- [ ] 岗位：`sys_post` / `post*` 命名调整为 `sys_position` / `position*`（ post 在业务语境中歧义较大）。
- [ ] 用户状态：`status`（`0=正常,1=停用`）调整为 `disabled`（ Boolean ），使字段含义更直接：`false=启用`，`true=停用`。
- [ ] 各表 type/flag 歧义及魔术值 Boolean/Enum 化

## 5. 时间类型统一（规划中）
- [ ] **类型规范**：
- [ ] 业务字段表示“日期 + 时间”的，统一使用 `LocalDateTime`（如创建/更新/登录/过期时间点等）。
- [ ] 业务字段仅表示“日期”的，统一使用 `LocalDate`（如生日、到期日、结算日等）。
- [ ] **命名规范**：
- [ ] 时间点字段统一使用 `xxxTime` 风格。
- [ ] 示例：`createTime` / `updateTime`
- [ ] 纯日期字段统一使用 `xxxDate` 风格。
- [ ] 示例：`birthDate`、`expireDate`

## 4. 数据统一性方向
- [ ] **去 Join 化重构**：针对性能敏感接口，将原有复杂的联表查询拆分为“多次单表查询 + Service 层聚合”。
- [ ] **主键策略统一**：全量应用分布式 ID (Snowflake) 策略，提升跨库/拆库扩展性。
- [ ] **统一字符类型及排序规则** 统一使用 utf8mb4/utf8mb4_general_ci

# 模块层次优化（完成）
- [x] **目标**：降低包路径层级，提高可发现性；将 `project/**/子模块/分层目录` 收敛为 `project/**/按层目录`，减少写代码时反复切换目录的成本。
- [x] **组织原则**：以“技术分层”作为第一层目录；业务模块通过类名前缀/命名约定区分（避免再次按模块建子目录）。

# 框架选型优化
## 1. 运行基座与基础设施
- [x] **Java 运行时**：最低要求升至 Java 11 （推荐 17 LTS ），彻底弃用 Java 8 兼容代码。
- [ ] **构建增强**：优化 Maven 配置，统一管理版本号，清理冗余依赖。

## 2. 核心架构组件替换
- [ ] **权限安全**：由 Shiro 迁移至 `Sa-Token`（实现更轻量、响应式的权限控制）。
- [ ] **数据缓存**：由 Ehcache 迁移至 `Caffeine`（单机本地缓存的最优选）。
- [ ] **字典缓存组件化**：引入 `DictCache`（`@Bean("dict")`）作为模板层唯一入口
- 使用启动时全量预热字典数据，字典增删改在事务提交后触发刷新/重建方案，确保模板查询不直连数据库且不依赖 miss 回源。
- [ ] **数据层增强**：深度集成 `MyBatis-Plus`，标准化逻辑删除与自动填充逻辑。

## 3. 开发工具与工程化
- [ ] **代码简化**：全面引入 `Lombok`，通过注解消除 POJO 中的样板代码。
- [ ] **JSON 栈统一**：彻底移除 `Fastjson`，全量使用 `Jackson` 并建立全局统一序列化规范。
- [ ] **工具库稳固**：引入 `Guava` 作为核心基础工具库，确立“Guava + Spring Utils”的优先使用准则。
- [ ] **接口文档（ Knife4j ）**：引入 Knife4j （基于 OpenAPI 3 ），统一接口分组/鉴权示例/错误码展示，确保“启动即能看文档、复制即能调接口”。
- [ ] **测试用例样板**：提供最小可运行测试模板（ JUnit5 + SpringBootTest ），覆盖 Controller/Service/Mapper 三类示例，并固化到 `test` 模块/目录，保证新人可照抄扩展。

## 4. 统一异常处理与日志完善
- [ ] **统一异常拦截**：引入 `@RestControllerAdvice` + `@ExceptionHandler`，对所有 Controller 请求返回统一错误结构（ code/message/traceId ），禁止异常导致无响应。
- [ ] **全链路兜底**：补充 `HandlerExceptionResolver` / `ErrorController` 兜底，覆盖 Filter/Interceptor 层抛出的异常，保证一定能写回 JSON 或错误页。
- [ ] **异常可观测性**：所有异常输出结构化日志（ traceId + uri + userId ），并对 NPE/运行时异常降级为友好提示。
- [ ] **日志追踪（ MDC traceId ）**：自研轻量 traceId 方案（ Filter 生成/透传 `X-Trace-Id` + Logback MDC ），异常响应携带 traceId ；补齐异步线程池 MDC 传播，保证单体阶段排障闭环
- [ ] **出入参日志（ DEBUG 向）**：提供统一请求日志打印能力，提供关闭并内置敏感字段脱敏（ password/token/phone),并排除文件下载/上传等大 body 场景，避免性能与泄露风险。

# UI 优化
## 1. 引入更现代的 UI 框架
- [ ] **Layui 2 **：
>>>优点：生态成熟、文档完善、对 “后台管理系统” 组件覆盖好（表格/表单/弹窗/树/分页等）。
- 延用 Thymeleaf 模板体系
- [ ] **Alpine.js （轻交互现代化增强）**：
>>>Alpine.js 可以理解为“HTML 里写点简单状态/交互的轻量 Vue 替代品”，无需 Node/脚手架，直接 `<script>` 引入即可在 Thymeleaf 页面上用，特别适合后台系统里的表单联动、显示/隐藏、局部状态切换等需求。
- [ ] 定位：在不引入前端脚手架（ Vue/React ）的前提下，为 Thymeleaf 页面提供轻量的“状态驱动”交互能力，提升开发体验与页面现代感。
- [ ] 适用场景：表单联动、显示/隐藏切换、简单状态管理、局部区域交互（非复杂表格/树/弹窗）。
- [ ] 使用边界（双模式）：
- [ ] Layui：负责后台系统的“重组件”（ table/form/layer/tree/date 等）。
- [ ] Alpine.js：仅用于页面内“小状态/轻交互”，避免接管 Layui 渲染后的复杂 DOM 。
- [ ] 原则：同一页面内减少“jQuery + Alpine”混用；新增页面优先 Alpine 管状态，Layui 管组件。

# 功能优化增强
## 1. 导出（前端导出：ExcelJS ）
- [ ] 导出功能从后端转向前端，使用 `xlsxjs` 在浏览器端生成并下载。
- [ ] 移除后端 Excel 导出体系（`@Excel/@Excels` 注解、ExcelUtil 相关导出入口以及 pom 依赖），避免数据库实体类被展示/导出需求污染。
- [ ] 导出元数据来源统一：以 **数据库字段注释（ column comment ）** 为准，由代码生成模板生成前端导出列定义（标题/字典映射/格式化等）。
- [ ] 导出范围约束（ starter 阶段）：仅支持“当前筛选条件下的中小数据量导出”；超大数据量导出暂不支持或后续扩展为后端异步任务。
- [ ] 落地方式（样板优先）：生成代码模板时,默认生成导出逻辑,导出列和数据列一致
- [ ] ~~大量数据导出场影建议使用导出任务方式(启动框架不实现此功能)~~

## 2. 日志与可观测性
- [ ] **IP 库升级**：集成 `ip2region` 实现毫秒级地理位置解析。

## 3. 文件与媒体
- [ ] **存储抽象化**：实现 `FileStorageService`，支持本地/OSS 一键切换。
- [ ] **轻量化图片处理**：支持通过 URL 参数进行缩略、剪裁。

## 4. 定时任务
- [ ] **内置 xxljob** 替换现在定时任务组件
- 改造 XXL-JOB 为应用内置模块，实现零部署、开箱即用的分布式任务调度。通过配置使主节点兼任调度中心，替换原有 @Scheduled 任务方案。
- 考虑参考:https://gitee.com/haohandongku/RxJob

---
坑多到我...准备改一个