diff --git a/README.md b/README.md index 7b255660f0289f484c437af6de810f0ed3b291fe..1fa87d6b531f0ddb1caf3513d250116a71e16fa0 100644 --- a/README.md +++ b/README.md @@ -1,681 +1,523 @@ -# Ruoyi-Plus-Uniapp新特性 - -- **[📺新特性全面解析](https://www.bilibili.com/video/BV1YrtMzvEaT/)** - -### 分支说明 -- master: 默认分支，多租户分支 -- workflow: 多租户工作流分支 -- single：移除所有多租户逻辑的分支 - -### 核心理念 - -- **代码即文档** - 通过规范化命名和完善注释实现代码自解释 -- **全栈统一** - 前后端命名规范、类型定义、接口管理保持一致 -- **开发友好** - 注重开发体验和可维护性，减少冗余代码 - -## 一、后端重构优化 - -### 1.1 基础架构重构 - -#### 四层架构设计 - -- 采用标准**四层架构**：Controller → Service → DAO → Mapper，职责清晰分离 -- **Service层**：不继承任何基类，直接实现业务接口，保持轻量和灵活 -- **DAO层**：独立数据访问层，继承 `IBaseDao` 接口，实现 `buildQueryWrapper()` 方法构建查询条件 -- **Mapper层**：只继承 `BaseMapper`，专注SQL执行 -- 数据类型规范：DAO和Mapper层只返回Entity类型，Service层使用 `MapstructUtils.convert()` 进行BO/VO转换 - -#### 查询增强组件 - -- 增强 MyBatis-Plus 查询功能，Query增强为PlusQuery，LambdaQuery增强为PlusLambdaQuery 支持聚合函数及条件自动处理 -- 查询条件统一在DAO层通过 `buildQueryWrapper(Bo)` 方法构建，自动处理null值判断 -- 支持精确匹配、模糊查询、时间范围查询等多种查询方式的灵活组合 - -#### 响应结果封装 - -- 重构 TableDataInfo 为 PageResult，统一返回数据为 `R>` 里面包含分页信息（是否最后一页 页码 每页条数等）和数据列表 -- 完善 R 类注释，统一 API 响应结果封装，优化成功和失败消息返回方法 -- 增加安全获取 data 方法和标准 API 响应结构 - -### 1.2 配置与环境管理 - -#### 应用配置重构 - -- 增加前后端唯一标识符应用ID，做好不同项目间的数据隔离 -- 重命名 RuoYiConfig 为 AppConfig，更新相关配置项 -- 增加core核心包相关工具类功能 - -### 1.3 数据库与字典系统 - -#### 数据库结构调整 - -- 重构数据库表命名规范，统一使用 sys_ 前缀 修改 gen_table 为 sys_gen_table，gen_table_column 为 sys_gen_table_column -- 逻辑删除统一修改为 isDeleted -- 性别字典修改：女0 男1 未知2，sys_user_sex 改为 sys_user_gender -- 修改字典数据主键 dict_code 改为 dict_data_id - -#### 字典系统重构 - -- 系统中统一采用 1=是/正面状态，0=否/负面状态 的约定 -- 重构字典类型和字典值，字典数据默认值统一为 1，否为 0 -- 重构字典枚举命名以 Dict 开头，字典枚举统一放在core/dict包下 提高代码可发现性 -- 优化字典实现类 - -### 1.4 租户系统完善 - -#### 租户功能增强 - -- 统一获取租户 ID 方案，提供兜底租户 ID，确保租户 ID 不为空 可以随时开启或者关闭租户功能不产生脏数据 -- OSS 存储加上租户 ID 前缀作为目录区分 -- 新增租户需要同步角色，增加角色同步到租户功能 因为开发过程角色也属于业务的一部分 实现同步功能可以最小化改动来供新租户使用 - -### 1.5 权限与安全系统 - -#### 权限标识符规范化 - -- 菜单权限标识符为：模块:表:标识符 格式 -- 如 system:user:view/query/add/update/delete/import/export -- 代码生成默认生成权限控制部分 打开注释即可启用 - -#### 认证系统优化 - -- 登录实现迁移到系统模块 auth 包下，保持 admin 模块简洁 -- 重命名授权类型和设备类型为认证方式和应用类型 -- 移除客户端管理，减少冗余代码，精简实现 主要分为两个客户端即可 由枚举UserType进行控制管理 -- 增加miniapp小程序模块，增加mp模块，实现对小程序（包括微信小程序的完整实现，以及QQ 支付宝 京东 - 抖音等各类小程序的扩展实现和预留实现）以及微信公众号的完整实现 开箱即用 -- 实现小程序 公众号多个配置同时使用以及租户间的数据隔离 - -### 1.6 文件管理系统 - -#### OSS 系统增强 - -- 重构 OSS 模块 抽离出接口层OssStrategy，可通过不同实现类实现不同的存储方式 如S3、本地文件等 -- 重构 OSS 模块同时支持 S3 和本地文件上传 -- 增加转换远程图片到 OSS 的接口实现 增加OSS文件的目录管理功能，支持多租户隔离 实现素材管理 -- 头像存储统一修改为字符串存储链接 -- 增加图片和文件前端/移动端直传功能，一键即可开启直传，支持多种云服务 - -### 1.7 WebSocket 通讯模块重构 - -#### WebSocket 多租户与多连接支持 - -- **完整多租户隔离**：实现三级映射结构（tenantId -> userId -> sessionId -> WebSocketSession），确保不同租户间的连接和消息完全隔离 -- **多设备多连接支持**：同一用户可在多个设备/浏览器标签页建立多个连接，避免互相挤号，所有连接独立管理 -- **智能消息分发**：向用户发送消息时自动推送到用户的所有活跃连接，确保多设备同步接收 -- **租户权限控制**： - - 超级管理员：可查看和管理所有租户的WebSocket连接 - - 租户管理员：只能查看和管理本租户的WebSocket连接 - - 普通用户：只能使用自己的WebSocket连接 -- **跨租户消息功能**：超级管理员可发送跨租户消息和全局广播消息 -- **连接管理 API**：提供完整的WebSocket管理控制器，支持连接统计、在线用户查询、消息推送、连接断开等管理功能 -- **多连接会话管理**：精确的会话生命周期管理，支持单个连接的精确移除，不影响用户的其他连接 -- **多格式心跳检测**：支持简单字符串、JSON 格式等多种心跳消息格式 -- **分布式消息分发**：基于 Redis 发布订阅的跨服务实例消息分发，支持租户上下文动态切换 - -### 1.8 系统功能模块 - -#### 序列化模块增强和重构 - -- 重构序列化模块名称为serialmap，因为只涉及序列化，不涉及反序列化，因为不叫translation，命名上不够恰当 -- 调整序列化注解为SerialMap，调整注解属性更符合规范 converter转换器 source来源 param额外参数 entityClass数据源实体类 - targetField 目标映射字段 -- 增加序列化注解实现FieldMapImpl，实现通用字典映射转换器，同时实现缓存，减少后续序列化实现的重复样板代码 - -#### 监控与日志 - -- monitor 监控增加通知功能 -- 完善操作日志、登录日志等页面优化 -- 重构日志注解的使用和类的命名 Log注解属性使用operType操作类型，指定字典DictOperType为操作类型枚举 -- 抽离登录日志发布者到 log 模块为 LoginLogPublisher 实现日志发布异步保存操作 - -#### 代码生成增强 - -- 完善代码生成界面使用体验，固定 tab 页签和弹窗高度 -- 实现主子表代码生成功能 -- 增加并实现代码生成表字段的默认值功能 -- 处理 Excel 导入更新实现和参数传递 - -### 1.9 国际化系统 - -#### 消息国际化 - -- 增删改查等消息实现后端返回国际化 默认情况还是由前端处理国际化 -- 通过接口常量实现管理和分类，去除 code 硬编码 -- 菜单国际化后端返回时增加国际化键名计算 -- 增加I18nMessageInterceptor国际化消息拦截器，简化国际化消息处理，无需花括号包围 - -### 1.10 高级功能模块 - -#### 支付系统 - -- 增加 IJPay 支付模块和相关商品订单逻辑 支付回调等统一处理再根据不同支付方式进行分发 -- 支付模块支持租户数据隔离和智能刷新数据 自动重试请求支付状态 - -#### 业务扩展 - -- 完成公告功能的可用性，实现精准推送和查阅 -- 实现已读未读统计等功能 - -### 1.11 部署与运维 - -#### Docker 部署 - -- 优化 docker-compose 相关编排名称 统一相关命名 -- 在主应用添加远程调试参数，支持本地 idea 远程调试 -- 完美适配 Docker容器化部署 - -#### 轻松开发和维护 - -- 全部代码注释完善，使用 Javadoc 规范 -- 统一使用 Lombok 注解简化代码，减少样板代码 -- 统一包管理和依赖管理规范 提供统一的包使用规范 提供业务模块供开发者直接用于开发业务逻辑 -- 重构代码生成器，支持主子表生成，优化代码生成体验，接口路径、方法名、变量名等语义化且唯一，快速定位 - -## 二、前端重构优化 - -### 2.1 架构重构 - -#### 目录结构调整 - -- 重构为 composables 目录(组合式)，lang 改为 locales -- store 目录统一命名为 stores，提升语义化 layout命名为layouts directives 命名为 directives -- 路由模块路由进行归类和分拆管理 -- 调整前端项目结构与后端结构基本统一 - -#### 组件命名规范化 - -- 全局统一组件命名，不使用 index，提升开发体验 -- 自定义组件统一使用首字母大写驼峰命名，ElementPlus 组件保持连字符 -- 所有页面组件改为首字母小写的驼峰，后端菜单进行适配 - -#### 类型重构 - -- 全局统一类型命名规范，与后端保持一致 减少使用认知负担 如Bo Vo等 -- 请求响应类型统一使用 `R`，减少冗余代码 ，分页类型统一使用 `R>`，减少冗余代码 - -### 2.2 工具类与组合函数函数重构 - -#### Utils部分逻辑 重构为 Composables组合函数 发挥vue3的组合式API优势 - -- 移除 utils/auth.ts，封装 useToken 到 composables -- 移除 utils/permission.ts，改为 composables/useAuth 组合函数 -- 移除 utils/theme.ts，改为 composables/useTheme 组合函数 -- 移除 utils/i18n，改为 composables/useI18n，全局使用自定义 i18n -- 移除animate.ts，改为 composables/useAnimation 组合函数 -- 移除dict.ts，改为 composables/useDict 组合函数 -- 移除request.ts，改为 composables/useHttp 组合函数 使用http.get, http.post 等方法进行请求 -- 移除sse.ts，改为 composables/useSSE 组合函数 -- 移除websocket.ts，改为 composables/useWS 组合函数 -- 移除i18n.ts，改为 composables/useI18n 组合函数 -- 移除auth.ts，改为 composables/useToken 组合函数 -- 增加useTableHeight 组合函数，优化表格高度计算 -- 增加useSelection 组合函数，处理表格全选和取消全选 -- 增加useDownload 组合函数，处理文件下载逻辑 - -#### 工具类功能增强 - -- 增加boolean.ts，封装布尔值相关方法 -- 增加date.ts，封装日期相关方法 -- 增加cache.ts，封装缓存相关方法 -- 增加format.ts，封装格式化相关方法 -- 增加function.ts，封装函数相关方法 如防抖、节流 拷贝等 -- 增加modal.ts，封装模态框相关方法 统一调用为show开头的前缀如showMsgSuccess、showMsgError等 showConfirm、showPrompt等 -- 增加object.ts，封装对象相关方法 -- 增加string.ts，封装字符串相关方法 -- 增加tab.ts，封装标签页导航操作相关工具函数 -- 抽离树形相关方法为tree.ts，封装树形结构相关方法 -- 增加class.ts，封装 DOM 操作相关方法 -- 增加to.ts，封装安全异步执行工具函数集 减少try catch 的使用 -- 增加validators.ts，封装表单验证相关方法 -- 完善 utils/crypto.ts，进行方法扩充，jsencrypt 改名为 rsa - -### 2.3 样式系统重构 - -#### 样式系统优化 - -- 为全部样式文件添加完善备注 -- 重构分类简化所有样式文件 -- 完善 UnoCSS 配置进行增强：颜色配置、间距变量、字体配置等 - -#### 布局组件重构 - -- 重构 Layout 页面相关组件，统一取消 index 命名 -- 调整 ParentView 组件到 layout，移动 TopNav 组件到 navbar 目录 -- 重新调整归类Layout层组件目录结构，调整样式控制实现 -- 优化导航栏、页签效果，调整鼠标滚轮滚动效果 - -### 2.4 表单与表格增强 - -#### 表单组件系统 - -- 增加各类表单组件： - AFormCascader 级联选择 - AFormCheckbox 复选框 - AFormDate 日期选择 - AFormEditor 富文本编辑器 富文本组件接入基于WangEditor - AFormFileUpload 文件上传 - AFormlmgUpload 图片上传 - AFormlnput 输入框 - AFormRadio 单选框 - AFormSelect 下拉选择 - AFormSwitch 开关选择 - AFormTreeSelect 树形选择 - -#### 表格功能增强 - -- 移除vxetable，vxetable 组件重构为 el-table 组件，实现跨页选择功能 -- 封装 useSelection 组合函数处理表格全选和取消全选 -- 增加 useTableHeight 优化表格显示效果，让分页组件保持固定位置 - -### 2.5 权限指令增强 - -#### 权限自定义指令 - -- 完善重构权限自定义指令，支持延迟加载组件 -- 扩充指令：permi、role、admin、superadmin、permiAll、roleAll 等 -- 移除全局 proxy 代理使用，进行对应代码适配转换 - -### 2.6 媒体库功能 - -#### AOssMediaManager 组件 - -- 添加媒体库功能组件 AOssMediaManager 增强图片上传 -- 增加替换功能，优化图片管理体验 -- 增加目录管理功能，支持多租户隔离，可以对图片进行分类管理，可以对图片进行批量操作 批量移动等（移动只是修改文件对应的所在目录id） -- 配合后端实现前端文件直传功能 一个属性即可配置开启 - -### 2.7 iconify引入图标功能重构菜单图标 - -#### 图标系统重构 - -- 引入 iconify 图标库，支持多种图标格式 -- 重构菜单图标使用 iconify 图标，实现图标库管理功能，方便进行维护和扩展 -- 优化图标选择组件，支持多种图标格式和自定义图标 -- 图标组件重构为Icon,支持图标名称类型提示，支持海量图标库 - -### 2.8 国际化系统 - -#### 前端国际化 - -- 增强useI18n 组合函数，增强t函数，实现智能提示 -- 前端实现菜单国际化，增加统一键名 -- 引入 ElementPlus 国际化资源，优化字体大小选择组件 - -### 2.9 性能优化 - -#### 实时通信 - -- SSE 连接增加重连退避策略，支持手动重连和状态监控 -- **实现动态退避策略的 WebSocket 连接管理，支持多租户上下文和多连接场景** - -#### 构建优化 - -- 优化 Vite 配置 - -#### 代码优化 - -- 全框架取消使用 reactive 函数，统一使用 ref 函数 -- 移除原生滚动，改用 el-scrollbar 滚动，优化滚动体验 -- 优化重构 tree 页面模板 -- 重构代码生成页面结构和实现，代码职责更加清晰 - -## 三、移动端重构优化 - -### 3.1 UniApp 框架重构 - -#### 框架改造 - -- 基于 unibest 框架进行重量级重构改造，移除不必要模块 -- 增加应用 ID 配置管理，模仿前端实现 -- 实现基础的 tabbar 页面，不使用原生 tabbar，使用自定义组件实现，可以更灵活地控制样式和功能 -- 增加分包管理，可以实现管理员端和代码示例等的分包加载，优化小程序加载速度 -- 插件重构，单一原则，分拆插件，提高复用性，增加静态目录插件，实现静态目录文件类型自动生成 - -#### 目录结构重构 - -- 重新调整插件目录结构，分拆插件分别维护 -- 复用前端 composables 目录下的部分组合函数函数，优化移动端开发体验 -- 封装 pinia 的相关模块：dict、tabbar、user 等 - -### 3.2 网络请求与认证 - -#### HTTP 请求封装 - -- 封装移动端 useHttp，实现移动端 API 加密解密 -- 统一请求拦截和响应处理机制 - -#### 小程序登录认证 - -- 实现微信小程序登录和公众号登录，模块化管理 -- 实现 unionid/手机号关联绑定用户账号唯一性 -- 用户手机实现无账户则自动注册 -- 实现登录页面的自动登录开关，以及多种登录方式的支持 -- 实现手机号注册和登录功能，支持验证码登录和密码登录 - -### 3.3 组合式函数与工具类 - -#### Composables 组合函数函数 - -- 复用前端 useDict、useAuth 等组合函数函数 -- 增加移动端 usePayment 组合函数，封装支付相关逻辑 -- 增加 useScroll 组合函数，封装滚动相关逻辑 -- 增加 useTheme 组合函数，封装主题相关逻辑 -- **移动端 useWebSocket 组合函数，支持多租户WebSocket连接管理** - -#### 工具类函数增强 - -- 复用前端的 utils 工具类库部分功能：boolean.ts、date.ts、format.ts、function.ts、object.ts、string.ts 等 -- 新增 tenant.ts，封装租户相关逻辑 -- 新增 validators.ts，封装移动端表单验证相关方法 - -### 3.4 组件库重构 - -#### WotUI 组件重构 - -- 重构 wot-ui 组件库所有组件，使用最新的 vue3 和 typescript 语法进行重构 -- 提高代码可读性、自行维护性和可扩展性 -- 重构单位统一为 rpx，移动端获得更好体验 -- 增加 wd-paging 组件，实现下滑分页加载功能 -- 增加wd-rich-text富文本组件，实现富文本读写 - -#### 图标组件系统 - -- 增加 wd-iconify 组件，支持 iconify 图标库 -- 增加 wd-icon 组件，支持 iconify 图标库和 json 图标 -- 重构了图标库近 400 个图标，包含线条图标和实心图标两大类 -- 可以方便在示例代码中搜索使用 - -### 3.5 小程序功能增强 - -#### 多平台支持 - -- 支持微信小程序完整功能实现 -- 预留 QQ、支付宝、京东、抖音等各类小程序的扩展实现 -- 统一小程序 API 调用接口 - -#### 示例代码系统 - -- 增加完善和齐全 wd 组件示例代码，可以直接看到效果 -- 效果判断统一有代码查看和复制按钮，方便开发者查看和使用 -- 提供丰富的组件使用示例和最佳实践 - -## 四、最新版本更新 (2024年8.4-9.22) - -### 4.1 后端核心升级 - -#### 依赖版本升级 -- **Spring Boot**: 3.2.8 → 3.2.10，提升性能与安全性 -- **MyBatis-Plus**: 3.5.7 → 3.5.8，优化SQL执行效率 -- **Sa-Token**: 1.38.0 → 1.39.0，增强权限管理功能 -- **EasyExcel**: 3.3.4 → 4.0.3，提升Excel处理性能 -- **Redisson**: 3.33.0 → 3.36.0，优化分布式缓存 -- **Hutool**: 5.8.29 → 5.8.31，修复Jakarta兼容性问题 - -#### 安全性大幅提升 -- **全局XSS过滤**：默认开启XSS过滤，提高系统安全性 -- **异常信息净化**：去除返回前端异常信息中的HTML标签 -- **依赖漏洞修复**：修复Scala库版本漏洞，限制高风险依赖版本 -- **权限验证增强**：优化登录状态判断和权限校验逻辑 - -#### 租户系统完善 -- **租户缓存优化**：修复一级缓存key未区分租户的问题 -- **租户套餐管理**：增加重名校验，优化套餐管理逻辑 -- **字典同步功能**：新增同步租户字典功能，支持租户间数据同步 -- **租户控制开关**：租户相关controller支持动态开关控制 - -### 4.2 支付系统重大升级 - -#### 微信支付智能切换 -- **v2/v3智能适配**：实现微信支付v2和v3版本的智能切换 -- **平台证书支持**：添加平台证书路径配置，支持v3支付安全验证 -- **证书路径修复**：修正keyPath配置项，确保私钥正确加载 -- **订单金额计算**：支持微信支付v3回调及自动计算订单金额 - -#### 支付配置优化 -- **表单字段优化**：优化支付配置表单字段与提示信息 -- **租户隔离实现**：支付配置实现完整的租户数据隔离 -- **动态配置加载**：平台配置支持启用禁用的动态加载更新 -- **回调处理增强**：统一支付回调处理，支持多种支付方式 - -### 4.3 移动端WD UI组件库全面升级 - -#### 核心组件增强 -- **wd-textarea**：支持自动高度最大行数限制和固定行数显示 -- **wd-button**：默认防冒泡处理，新增隐形按钮功能 -- **wd-upload**：支持预览图大小配置，实现文件直传功能 -- **wd-paging**：支持计算属性动态参数，新增前置后置插槽 -- **wd-navbar**：支持状态栏字体颜色、标题加粗等个性化配置 - -#### 新增功能组件 -- **wd-voice-recorder**：录音组件，支持音频录制功能 -- **富文本编辑器**：增强富文本组件，支持图片视频上传 -- **文件直传**：一键开启直传功能，支持阿里云、腾讯云等多平台 -- **小程序更新检测**：自动检测小程序版本更新功能 - -#### 交互体验优化 -- **wd-search**：支持圆角大小设置，提升视觉效果 -- **wd-cell**：支持右侧flex值配置，灵活控制布局宽度 -- **wd-action-sheet**：支持DictItem数组传递，简化字典选择 -- **wd-tabbar**：默认开启底部安全区域适配，避免遮挡问题 - -### 4.4 前端界面现代化升级 - -#### 组件系统重构 -- **AModal组件**：替换el-dialog，支持响应式识别和弹窗抽屉切换 -- **图标库双引擎**：同时支持iconfont和iconify图标库，无感切换使用 -- **Element Plus现代化**：优化组件样式，实现现代化界面设计 -- **可拖拽面板**：新增AResizablePanels组件，支持面板拖拽调整 - -#### 布局主题优化 -- **背景色层级系统**：引入多层级背景色系统，优化视觉层次 -- **悬停效果统一**：统一导航栏工具项悬停样式，提升交互一致性 -- **侧边栏优化**：调整Logo组件对齐方式，优化边框和阴影效果 -- **打印功能**：新增系统打印功能，支持页面内容打印 - -### 4.5 代码生成器智能化 - -#### 模板生成优化 -- **实体类路径调整**：entity包调整到domain包，符合DDD设计理念 -- **分组验证支持**：添加分组验证和OSS翻译自动适配 -- **查看逻辑生成**：自动生成ADetailDialog组件和查看功能 -- **主子表增强**：完善主子表代码生成，支持复杂业务场景 - -#### 开发体验提升 -- **Vue目录统一**：生成目录改为src，可直接复制到前端项目 -- **权限注解生成**：默认生成权限控制注解，打开注释即可启用 -- **Excel处理**：优化Excel导入导出代码生成逻辑 - -### 4.6 媒体库系统 - -#### 图片处理引擎 -- **多图合成GIF**：支持多张图片合成动态GIF图像 -- **复杂海报生成**：提供强大的海报设计和生成功能 -- **二维码生成**：内置二维码生成工具，支持自定义样式 -- **字体颜色工具**：丰富的字体和颜色处理工具类 - -#### 文件管理增强 -- **目录管理**：支持文件目录分类管理，提升文件组织能力 -- **租户隔离**：完整的多租户文件隔离机制 -- **直传功能**：前端/移动端文件直传，减少服务器压力 - -### 4.7 数据库结构优化 - -#### 表结构调整 -- **部门区划码**：部门表增加area_code字段，支持省市区区划 -- **表名规范化**：products→product，orders→order，避免复数命名 -- **商品字段增强**：新增商品编码、原价、折扣等字段 -- **订单状态字典**：完善订单状态枚举，包含支付、发货、完成等 - -#### SQL文件管理 -- **分类存储**：数据库脚本分为sys、job、app三个部分 -- **新增表脚本**：每种数据库提供new.sql用于新业务表管理 - -### 4.9 国际化系统增强 - -#### 多语言支持 -- **移动端国际化重构**：支持英语、阿拉伯语、德语等多种语言 -- **语言选择器**：新增自定义语言选择器组件 -- **动态语言切换**：支持语言缓存和动态加载 -- **HTTP请求适配**：自动在请求头中添加当前语言信息 - -### 4.10 部署运维优化 - -#### 容器化部署增强 -- **环境变量占位符**：支持${变量名:默认值}语法，避免敏感信息硬编码 -- **远程调试支持**：Docker容器支持本地IDE远程调试 -- **编排优化**：优化docker-compose配置，简化部署流程 -- **文件上传路径**：Docker构建增加文件上传路径配置 - -#### 开发体验提升 -- **Claude Code集成**：提供AI辅助开发的智能上下文支持 -- **ESLint优化**：完善代码规范检查，提升代码质量 -- **文档完善**：更新开发指南和使用文档 - ---- - -## 五、架构重构与AI集成 (2024年10月) - -### 5.1 四层架构重构 🏗️ - -#### Controller-Service-DAO-Mapper分层重构 -- **Service层解耦**：移除对 `IBaseService` 和 `BaseServiceImpl` 的继承，Service层更加轻量和灵活 -- **DAO层重构**：新增独立 DAO 层，负责查询条件构建和数据访问 - - DAO接口继承 `IBaseDao`，提供统一的数据访问接口 - - DAO实现继承 `BaseDaoImpl`，封装常用数据操作 -- **Mapper层规范**：Mapper仅继承 `BaseMapper`，专注SQL执行 -- **职责明确分离**： - - **Controller层**：参数验证、响应包装 - - **Service层**：业务逻辑处理、类型转换（Entity ↔ Bo/Vo） - - **DAO层**：查询条件构建、数据访问 - - **Mapper层**：纯SQL执行 - -#### 数据类型规范化 -- **Entity类型统一**：DAO层和Mapper层只返回Entity类型，不允许返回Vo/Bo -- **类型转换规范**：Service层使用 `MapstructUtils.convert()` 进行类型转换 -- **分页转换优化**：使用 `PageResult.convert(Class)` 简单转换，`PageResult.map(Function)` 处理复杂业务逻辑 - -#### 查询条件构建 -- **buildQueryWrapper方法**：所有查询条件统一在DAO层通过 `buildQueryWrapper(Bo)` 构建 -- **PlusLambdaQuery增强**：自动处理null值，无需手动判空 -- **PlusQuery支持**：支持表别名和字符串列名，适用复杂联表查询 - -### 5.2 LangChain4j AI集成 🤖 - -#### AI能力引入 -- **LangChain4j框架集成**：引入企业级LLM应用开发框架 -- **多模型支持**：统一接口支持OpenAI、Azure OpenAI、通义千问等主流大模型 -- **AI配置模块**：独立的langchain4j配置模块，支持动态配置和热更新 -- **环境变量配置**：支持通过环境变量配置API密钥，避免敏感信息硬编码 -- **功能开关控制**：提供 `LANGCHAIN4J_ENABLED` 开关，可动态启用/禁用AI功能 - -#### AI聊天功能实现 -- **AI聊天接口**：实现完整的AI聊天REST API和流式聊天接口 -- **会话管理**：支持创建会话、清除会话、获取会话历史等功能 -- **WebSocket集成**：通过WebSocket实现AI聊天实时消息推送 -- **统一返回格式**：所有AI接口返回 `R` 格式，保持接口一致性 -- **前端组件**：新增 `AAiChat` 组件，提供完整的AI聊天界面和交互体验 -- **动态显示**：根据后端功能配置动态显示/隐藏AI聊天入口 - -#### AI应用场景 -- **智能对话**：基于上下文的智能问答系统 -- **文本生成**：内容创作、摘要生成、文本改写等 -- **语义理解**：意图识别、情感分析、关键信息提取 -- **代码辅助**：代码生成、代码审查、bug分析建议 - -#### AI工具链 -- **Prompt模板管理**：结构化Prompt模板管理，支持变量替换 -- **Memory管理**：会话记忆和上下文管理，实现连贯对话 -- **Tool调用**：AI Agent支持调用外部工具和API -- **RAG支持**：检索增强生成，结合知识库提升回答准确性 -- **向量模型优化**：移除本地向量模型依赖，减少包体积，支持按需启用 - -### 5.3 开发规范文档完善 📚 - -#### Claude Code智能提示 -- **CLAUDE.md重构**：新增四层架构详细说明和最佳实践 -- **工具类优先原则**：强调优先使用项目现有工具类，避免重复造轮子 -- **46+工具类目录**：详细列出后端25+、前端11、移动端11个常用工具类 -- **代码模板扩充**：提供完整的6层代码模板（Controller、Service、DAO、Mapper、Bo、Vo） - -#### AGENTS.md同步更新 -- **多AI助手支持**：适配Claude Code、GitHub Copilot、Cursor、Windsurf、Codeium等 -- **统一规范说明**：各AI助手共享相同的架构规范和开发指南 -- **错误示例对比**：提供正确与错误的代码对比，帮助理解最佳实践 - -#### 架构规范文档 -- **四层架构指南**：详细说明各层职责、调用关系和数据流转 -- **常见场景速查**：提供分页查询、树形数据、复杂查询等常见场景的标准实现 -- **工具类使用指南**：每个工具类的详细用法和使用场景说明 - -### 5.4 测试体系完善 🧪 - -#### 集成测试全覆盖 -- **系统模块测试**：完善用户、角色、菜单、部门、字典等核心模块的集成测试 -- **业务模块测试**：新增AI聊天、首页、统计、系统功能配置等业务接口测试 -- **监控模块测试**：添加缓存监控、登录日志、操作日志、通知公告等监控接口测试 -- **租户模块测试**：完善租户管理相关接口的集成测试覆盖 - -#### 测试基础设施 -- **Forest HTTP客户端集成**：使用Forest进行HTTP接口测试，简化测试代码 -- **动态端口支持**：支持Spring Boot随机端口测试，提升测试灵活性 -- **测试数据清理**：提供测试数据清理脚本，确保测试环境干净 -- **工具类单元测试**：新增StringUtils、DateUtils等核心工具类的单元测试 - -#### 测试覆盖率提升 -- **核心模块P0接口**：核心功能接口测试覆盖率提升约42% -- **CRUD完整性测试**：确保所有增删改查接口的完整测试覆盖 -- **边界条件测试**：添加参数校验、权限校验等边界条件测试用例 - -### 5.5 代码生成器优化 ⚙️ - -#### 生成规范调整 -- **实体类路径优化**：entity包调整到domain包，符合DDD领域驱动设计 -- **DAO接口命名规范**：统一DAO接口命名为 `I{Entity}Dao` 格式 -- **查看功能生成**：自动生成 `ADetail` 组件和查看详情功能 -- **权限注解生成**：默认生成 `@SaCheckPermission` 权限控制注解 - -#### 代码模板增强 -- **OSS翻译适配**：自动生成OSS字段的序列化映射配置 -- **Vue目录统一**：生成目录改为src，可直接复制到前端项目 -- **主子表完善**：增强主子表代码生成，支持复杂业务场景 - -### 5.6 前端组件系统升级 🎨 - -#### 新增核心组件 -- **AModal组件**：替换el-dialog，支持响应式识别，实现弹窗/抽屉自动切换 -- **ADetail组件**：通用详情展示组件，支持分组显示和自定义插槽 -- **AFormEditor组件**：富文本编辑器组件，基于WangEditor实现 -- **AResizablePanels组件**：可拖拽调整大小的面板组件 -- **AImportExcel组件**：优化导入Excel功能，支持模板下载和子表导入 - -#### 组件功能优化 -- **图标系统双引擎**：同时支持iconfont和iconify图标库，无感切换 -- **密码字段支持**：ADetail组件支持密码类型字段的安全显示 -- **富文本字段支持**：ADetail组件支持富文本类型字段的渲染 -- **行数控制**：新增lines1/lines2/lines3属性，灵活控制长文本显示 - -#### 路由与权限重构 -- **路由模块化**：路由配置拆分为常量路由和动态路由（系统、工作流、工具） -- **路由守卫重构**：permission.ts重构为guard.ts，放置于router目录下 -- **权限指令优化**：支持延迟加载组件，扩充permi、role、admin等权限指令 -- **动态菜单优化**：菜单加载和权限验证逻辑优化 - -### 5.7 依赖版本升级 📦 - -#### 后端依赖升级 -- **Spring Boot**: 3.3.5 → 3.4.1，性能和安全性提升 -- **MyBatis-Plus**: 3.5.9 → 3.5.11，SQL执行效率优化 -- **Hutool**: 5.8.31 → 5.8.35，工具类功能增强 -- **Redisson**: 3.39.0 → 3.43.0，分布式缓存优化 -- **SnailJob**: 1.2.0 → 1.4.0，定时任务调度增强 -- **WarmFlow**: 升级至 1.6.6 正式版，工作流功能完善 - -#### 前端依赖优化 -- **移除await-to-js**：使用项目自定义的 `to.ts` 工具类替代 -- **移除vxe-table**：统一使用el-table，减少依赖体积 -- **富文本编辑器**：新增WangEditor依赖，提供强大的编辑能力 - ---- - -每个端的重构都遵循模块化、标准化的原则，确保代码质量和可维护性。最新版本的更新重点关注**架构分层清晰化**、**AI能力集成**、**测试体系完善**、**代码生成优化**、**组件系统升级**和**智能化开发体验提升**，为企业级应用提供更强大的技术支撑和更高效的开发体验。 + + +# Ruoyi-Plus-Uniapp新特性 + +## 项目简介 + +Ruoyi-Plus-Uniapp 是一个企业级全栈开发平台，基于 RuoYi 系统进行深度重构和优化，提供完整的前端、后端和移动端解决方案。该项目采用现代化的技术栈，注重开发体验和代码可维护性，通过规范化的架构设计和丰富的功能组件，帮助开发者快速构建企业级应用。 + +## 分支说明 + +本项目采用多分支策略，以满足不同业务场景的需求： + +- **master**：默认分支，采用多租户架构设计，适合需要数据隔离的多租户业务场景 +- **workflow**：多租户工作流分支，在 master 基础上集成了完整的工作流引擎，支持业务流程的自动化处理 +- **single**：单租户分支，移除了所有多租户相关逻辑，适合不需要数据隔离的单一组织应用 + +开发者可根据实际需求选择合适的分支进行开发。分支之间的功能差异主要体现在数据隔离机制和租户管理模块，其他核心功能保持一致。 + +## 核心理念 + +本项目遵循三大核心理念，以确保代码质量和开发体验的持续提升： + +**代码即文档** - 项目通过规范化的命名约定和完善的代码注释实现代码自解释。每一个类、方法、变量都遵循统一的命名规范，配合详细的 Javadoc 注释，使代码本身即成为最好的文档。这种做法不仅降低了团队成员的理解成本，也大大减少了文档维护的工作量。开发者在阅读代码时能够快速理解其用途和设计意图，无需频繁查阅外部文档。 + +**全栈统一** - 前后端在命名规范、类型定义、接口管理等方面保持高度一致。后端的实体类、服务接口与前端的类型定义使用相同的命名约定，API 接口遵循统一的响应格式规范。这种统一性不仅降低了前后端联调的沟通成本，也使得代码复用率大幅提升。新成员加入项目后，可以快速熟悉整个技术栈，无需在前后端技术之间频繁切换。 + +**开发友好** - 项目始终将开发体验放在重要位置，致力于减少冗余代码和重复劳动。通过大量使用 Lombok 注解消除样板代码，采用 MapStruct 进行对象转换，统一异常处理机制等措施，开发者可以专注于业务逻辑的实现，而不必纠缠于繁琐的重复性工作。同时，项目提供了丰富的代码生成工具和开发规范文档，进一步提升开发效率。 + +## 一、后端重构优化 + +### 1.1 基础架构重构 + +#### 四层架构设计 + +后端采用标准的四层架构设计，将系统职责清晰分离，各层各司其职又相互协作。Controller 层负责接收和响应 HTTP 请求，进行参数校验和响应封装；Service 层处理业务逻辑，实现核心业务功能；DAO 层专注于数据访问，封装查询条件的构建；Mapper 层直接与数据库交互，执行 SQL 语句。 + +在具体实现上，Service 层不继承任何基类，直接实现业务接口，保持轻量和灵活的设计理念。DAO 层作为独立的数据访问层，继承 IBaseDao 接口，并实现 buildQueryWrapper() 方法来构建查询条件。Mapper 层仅继承 BaseMapper，专注于 SQL 执行，不包含任何业务逻辑。这种分层设计使得各层职责清晰，便于测试和维护。 + +数据类型规范方面，DAO 层和 Mapper 层只返回 Entity 类型，不允许返回 VO 或 BO。Service 层使用 MapstructUtils.convert() 进行类型转换，确保数据在层间传递时的类型安全和一致性。分页查询使用 PageResult.convert() 进行简单转换，使用 PageResult.map() 处理复杂的业务逻辑转换。 + +#### 查询增强组件 + +为了提升查询能力，项目对 MyBatis-Plus 进行了增强扩展。PlusQuery 和 PlusLambdaQuery 在原有 Query 和 LambdaQuery 的基础上，增加了聚合函数支持和条件自动处理功能。查询条件统一在 DAO 层通过 buildQueryWrapper(Bo) 方法构建，系统自动处理 null 值判断，开发者无需手动进行空值检查。 + +查询增强组件支持多种查询方式的灵活组合，包括精确匹配、模糊查询、时间范围查询、IN 查询、 BETWEEN 查询等。对于常见的查询场景，如按状态筛选、按时间范围查询、按关键词搜索等，只需在业务对象中定义相应字段即可自动生成对应的查询条件。复杂查询场景下，支持链式调用组合多个查询条件，满足各种业务需求。 + +#### 响应结果封装 + +项目重构了分页响应结构，将原来的 TableDataInfo 改为 PageResult，统一返回数据格式为 R>。PageResult 内部包含完整的分页信息，如当前页码、每页条数、总记录数、是否最后一页、是否第一页等，以及当前页的数据列表。这种统一的响应格式使得前端可以方便地进行分页展示和交互控制。 + +R 类作为统一的响应结果封装类，提供了完善的注释和丰富的成功失败消息返回方法。成功时使用 R.ok() 返回数据，失败时使用 R.fail() 返回错误信息。R 类还提供了安全获取 data 的方法，避免直接访问可能为 null 的响应数据。所有 API 接口统一使用这种响应格式，确保前端处理逻辑的一致性。 + +### 1.2 配置与环境管理 + +#### 应用配置重构 + +项目增加了前后端唯一标识符应用 ID，用于区分不同项目间的数据隔离。这一设计使得同一个数据库中可以存在多个独立的应用，每个应用的数据相互独立，互不干扰。应用 ID 在请求头中传递，后端根据该 ID 过滤相应应用的数据。 + +原有的 RuoYiConfig 重命名为 AppConfig，配置项也进行了相应更新，使其命名更加清晰和语义化。同时，core 核心包中增加了丰富的工具类，涵盖字符串处理、日期操作、集合操作、加密解密等功能，为业务开发提供便利。所有工具类都经过精心设计和测试，确保其稳定性和性能。 + +### 1.3 数据库与字典系统 + +#### 数据库结构调整 + +为了提高数据库表的规范性和可维护性，项目重构了数据库表命名规范。原有的一些表名移除了统一前缀，现统一使用 sys_ 前缀，例如 gen_table 改为 sys_gen_table，gen_table_column 改为 sys_gen_table_column。这种命名方式使系统表与业务表清晰区分，便于管理和识别。 + +逻辑删除字段统一修改为 is_deleted，语义更加明确。性别字段的字典值进行了调整：女为 0、男为 1、未知为 2，字典表 sys_user_sex 相应改为 sys_user_gender。字典数据主键由 dict_code 改为 dict_data_id，使其更符合主键命名规范。这些调整使得数据库结构更加清晰，数据含义更加明确。 + +#### 字典系统重构 + +系统中的状态判断统一采用 1 代表是或正面状态、0 代表否或负面状态的约定。这一约定贯穿整个系统，包括启用禁用、是否删除、状态开关等所有场景。字典类型和字典值也进行了相应重构，字典数据默认值统一为 1，否为 0，保持一致性。 + +字典枚举命名统一以 Dict 开头，所有字典枚举放置在 core/dict 包下，提高了代码的可发现性和维护性。枚举类包含了字典的键值对映射，支持根据键获取值、根据值获取键等操作。字典实现类进行了优化，支持字典数据的缓存和动态刷新，减少数据库查询压力。 + +### 1.4 租户系统完善 + +#### 租户功能增强 + +项目提供了统一的租户 ID 获取方案，并设有兜底租户 ID，确保租户 ID 在任何情况下都不为空。这种设计使得开发者可以随时开启或关闭租户功能，而不会产生脏数据。租户开关通过配置文件控制，启用后系统自动进行数据隔离，关闭后系统正常运行不受影响。 + +OSS 存储模块为每个租户创建独立的存储目录，目录命名使用租户 ID 作为前缀，实现不同租户间的文件隔离。新增租户时，系统支持自动同步角色数据，增加了角色同步到租户的功能。由于在开发过程中角色也属于业务的一部分，实现同步功能可以最小化改动来供新租户使用，快速搭建新租户的基础数据。 + +### 1.5 权限与安全系统 + +#### 权限标识符规范化 + +菜单权限标识符采用统一的格式规范：模块:表:标识符。例如，用户管理的权限标识符为 system:user:view/query/add/update/delete/import/export。这种格式清晰表达了权限所属模块、操作对象和具体操作，便于权限的管理和维护。代码生成模块默认生成权限控制代码，打开注释即可启用。 + +权限校验基于 Sa-Token 框架实现，支持多种授权方式和权限验证策略。系统内置了 @SaCheckPermission 注解，开发者只需在方法上添加相应注解即可实现权限控制。同时支持角色权限、接口权限、数据权限等多维度的权限控制，满足企业级应用的复杂权限需求。 + +#### 认证系统优化 + +登录实现迁移到系统模块的 auth 包下，保持 admin 模块的简洁性。授权类型和设备类型重命名为认证方式和应用类型，命名更加准确和统一。移除了客户端管理模块，精简实现，主要分为两个客户端即可，由 UserType 枚举进行控制管理。 + +项目新增了 miniapp 小程序模块和 mp 模块，实现了对小程序（包括微信小程序的完整实现，以及 QQ、支付宝、京东、抖音等各类小程序的扩展实现和预留实现）以及微信公众号的完整实现。这些模块开箱即用，支持多个配置同时使用，并实现租户间的数据隔离。 + +### 1.6 文件管理系统 + +#### OSS 系统增强 + +OSS 模块进行了全面重构，抽离出接口层 OssStrategy，可通过不同实现类实现不同的存储方式。目前支持 S3 协议云存储（如阿里云 OSS、腾讯云 COS）和本地文件存储两种方式。开发者可以根据实际需求选择合适的存储方案，或自行实现其他存储方式的适配器。 + +OSS 模块同时支持转换远程图片到 OSS 的功能，增加了 OSS 文件的目录管理功能，支持多租户隔离，实现素材管理功能。头像存储统一修改为字符串存储链接，简化了数据结构和访问方式。系统增加了图片和文件前端及移动端直传功能，只需配置相应参数即可开启直传，支持阿里云、腾讯云等多种云服务。 + +### 1.7 WebSocket 通讯模块重构 + +#### WebSocket 多租户与多连接支持 + +WebSocket 模块实现了完整的多租户隔离，采用三级映射结构：tenantId → userId → sessionId → WebSocketSession。这种结构确保不同租户间的连接和消息完全隔离，租户之间无法访问彼此的连接和消息。同时支持同一用户在多个设备或浏览器标签页建立多个连接，所有连接独立管理，避免互相挤号。 + +消息发送采用智能分发策略，向用户发送消息时自动推送到该用户的所有活跃连接，确保多设备同步接收。租户权限控制方面，超级管理员可查看和管理所有租户的 WebSocket 连接，租户管理员只能查看和管理本租户的连接，普通用户只能使用自己的连接。超级管理员还可发送跨租户消息和全局广播消息。 + +系统提供了完整的 WebSocket 管理控制器，支持连接统计、在线用户查询、消息推送、连接断开等管理功能。分布式部署时，基于 Redis 发布订阅实现跨服务实例的消息分发，支持租户上下文动态切换。多格式心跳检测支持简单字符串、JSON 等多种心跳消息格式，满足不同场景的需求。 + +### 1.8 系统功能模块 + +#### 序列化模块增强和重构 + +序列化模块名称重构为 serialmap，因为该模块只涉及序列化，不涉及反序列化，原来的命名不够准确。序列化注解调整为 SerialMap，注解属性更符合规范：converter 为转换器、source 为来源、param 为额外参数、entityClass 为数据源实体类、targetField 为目标映射字段。 + +系统增加了序列化注解实现类 FieldMapImpl，提供通用字典映射转换器，同时实现缓存功能，减少后续序列化实现的重复样板代码。开发者只需在实体类字段上添加相应注解，即可自动完成字典值的转换和数据映射，大大简化了开发工作。 + +#### 监控与日志 + +监控模块增加了通知功能，可通过多种渠道（邮件、短信、钉钉、企业微信等）发送告警通知。操作日志和登录日志等功能进行了页面优化，提升用户体验。日志注解的使用和类命名进行了重构，Log 注解属性使用 operType 指定操作类型，对应 DictOperType 枚举类。 + +登录日志发布者抽离到 log 模块，命名为 LoginLogPublisher，实现日志发布异步保存操作，避免日志记录影响业务接口的响应速度。系统支持多种日志级别、日志分类和日志查询，方便运维人员排查问题。 + +#### 代码生成增强 + +代码生成界面进行了体验优化，固定了 tab 页签和弹窗的高度，使布局更加整齐美观。实现了主子表代码生成功能，支持复杂业务场景的代码生成。增加了表字段默认值功能，生成的代码可直接使用默认值配置。优化了 Excel 导入更新实现和参数传递，使导入功能更加稳定可靠。 + +### 1.9 国际化系统 + +#### 消息国际化 + +增删改查等操作的消息实现了后端返回国际化，默认情况下仍由前端处理国际化消息。通过接口常量实现国际化的管理和分类，去除了硬编码的问题，使代码更加清晰和可维护。菜单国际化后端返回时增加国际化键名计算，前端可据此获取对应的国际化文本。 + +系统增加了 I18nMessageInterceptor 国际化消息拦截器，简化了国际化消息的处理流程。开发者无需使用花括号包围消息键名，拦截器自动处理键名到文本的转换，大幅提升了国际化功能的开发效率。 + +### 1.10 高级功能模块 + +#### 支付系统 + +项目集成了 IJPay 支付模块，实现了完整的支付功能，包括商品订单逻辑和支付回调处理。支付回调统一处理后，根据不同支付方式进行分发。支付模块支持租户数据隔离，每个租户拥有独立的支付配置。智能刷新数据功能自动重试请求支付状态，确保支付状态的准确性。 + +微信支付支持 v2 和 v3 版本的智能切换，根据商户配置自动选择合适的版本。添加了平台证书路径配置，支持 v3 支付安全验证。订单金额支持微信支付 v3 回调及自动计算，无需手动处理金额计算逻辑。支付配置表单字段进行了优化，提供了更清晰的提示信息。 + +#### 业务扩展 + +公告功能完成了可用性实现，支持精准推送和阅读统计。用户阅读公告后可标记已读，系统统计每个公告的阅读情况。实现了已读未读统计功能，可查看公告的详细阅读数据。这些功能为系统内部沟通和信息发布提供了完整的解决方案。 + +### 1.11 部署与运维 + +#### Docker 部署 + +Docker 部署进行了优化，docker-compose 相关编排名称统一，使用更规范的命名规则。主应用添加了远程调试参数，支持本地 IDE 远程调试容器中的应用。系统完美适配 Docker 容器化部署，可快速在生产环境或测试环境中部署运行。 + +环境变量配置支持 ${变量名:默认值} 语法，避免敏感信息硬编码在配置文件中。Docker 构建时增加了文件上传路径配置，可根据实际需求调整存储路径。容器化部署方案经过充分测试，确保在各种环境下稳定运行。 + +#### 轻松开发和维护 + +全部代码注释完善，使用 Javadoc 规范编写。统一使用 Lombok 注解简化代码，减少样板代码，提高代码可读性。统一包管理和依赖管理规范，提供统一的包使用规范，提供业务模块供开发者直接用于开发业务逻辑。 + +代码生成器进行了重构，支持主子表生成，优化了代码生成体验。接口路径、方法名、变量名等语义化且唯一，方便快速定位。生成的代码结构清晰、命名规范，可直接用于生产环境。 + +## 二、前端重构优化 + +### 2.1 架构重构 + +#### 目录结构调整 + +前端项目目录结构进行了全面调整，将 composables 目录作为组合式 API 的存放位置，lang 目录改为 locales 用于国际化资源。store 目录统一命名为 stores，layout 目录命名为 layouts，directives 目录命名为 directives，使目录命名更加清晰和语义化。 + +路由模块进行了归类和分拆管理，将常量路由和动态路由分开管理。前端项目结构与后端结构基本统一，采用相似的目录组织方式，降低前后端开发者的学习成本。这种统一的目录结构便于项目的维护和扩展。 + +#### 组件命名规范化 + +全局统一组件命名规则，不再使用 index 命名方式，提升开发体验。自定义组件统一使用首字母大写的驼峰命名法，如 UserCard、OrderList。Element Plus 组件保持连字符命名方式，如 el-button、el-table。这种区分使得组件类型一目了然。 + +所有页面组件改为首字母小写的驼峰命名，后端菜单配置进行相应适配。页面路由和组件名称保持一致，开发者可以快速从路由定位到对应的组件文件。 + +#### 类型重构 + +全局统一类型命名规范，与后端保持一致，减少使用认知负担。请求响应类型统一使用 R，分页类型统一使用 R>，减少冗余代码和类型定义。类型定义集中管理，便于查找和维护。 + +与后端对应的 BO、VO、DTO 等类型定义保持命名一致，前端可直接复用后端的类型定义文档。TypeScript 类型检查确保数据格式的正确性，减少运行时错误。 + +### 2.2 工具类与组合函数重构 + +#### Utils 部分逻辑重构为 Composables 组合函数 + +项目将原有的 utils 目录下的工具函数重构为 Vue3 组合式 API 形式的 composables 函数，充分发挥 Vue3 组合式 API 的优势。auth.ts 封装为 useToken，permission.ts 改为 useAuth，theme.ts 改为 useTheme，i18n 改为 useI18n，dict.ts 改为 useDict，request.ts 改为 useHttp。 + +sse.ts 改为 useSSE 组合函数，websocket.ts 改为 useWS 组合函数，animate.ts 改为 useAnimation 组合函数。这些重构使代码逻辑更加内聚，逻辑复用更加灵活。组合式函数可在多个组件间自由组合使用，提高代码复用率。 + +项目新增了多个实用的组合式函数：useTableHeight 用于优化表格高度计算，useSelection 用于处理表格全选和取消全选，useDownload 用于处理文件下载逻辑。这些函数解决了日常开发中的常见需求，提升开发效率。 + +#### 工具类功能增强 + +utils 目录下的工具类进行了功能增强和扩充。boolean.ts 封装了布尔值相关的方法，如布尔转换、布尔判断等。date.ts 封装了日期相关的操作，包括日期格式化、日期计算、时区转换等。cache.ts 封装了缓存操作，支持本地存储和会话存储的统一接口。 + +format.ts 封装了各种格式化方法，如数字格式化、货币格式化、百分比格式化等。function.ts 封装了函数相关的方法，如防抖、节流、深拷贝等。modal.ts 封装了模态框相关的方法，统一调用方式以 show 开头，如 showMsgSuccess、showMsgError、showConfirm、showPrompt 等。 + +object.ts 封装了对象操作方法，如对象合并、对象拷贝、属性遍历等。string.ts 封装了字符串操作方法，如字符串截取、格式验证、字符串转换等。tab.ts 封装了标签页导航操作相关的工具函数。tree.ts 抽离了树形结构相关的处理方法。class.ts 封装了 DOM 操作相关的方法。 + +to.ts 封装了安全异步执行工具函数集，减少 try catch 的使用，简化异步代码。validators.ts 封装了表单验证相关的方法。crypto.ts 进行了方法扩充，jsencrypt 改名为 rsa，支持 RSA 加密解密操作。 + +### 2.3 样式系统重构 + +#### 样式系统优化 + +所有样式文件添加了完善的注释，说明样式的作用域、用途和注意事项。样式文件进行了重构和简化，按照功能分类存放。UnoCSS 配置进行了增强，包括颜色配置、间距变量、字体配置等。构建时自动生成所需的 CSS 代码，减少手动编写。 + +#### 布局组件重构 + +Layout 页面相关组件进行了重构，统一取消 index 命名方式。ParentView 组件移到 layout 目录，TopNav 组件移到 navbar 目录。Layout 层组件目录结构重新调整，样式控制逻辑更加清晰。导航栏、页签效果进行了优化，鼠标滚轮滚动效果更加流畅。 + +### 2.4 表单与表格增强 + +#### 表单组件系统 + +项目新增了多种表单组件，完善了表单系统：AFormCascader 级联选择组件、AFormCheckbox 复选框组件、AFormDate 日期选择组件、AFormEditor 富文本编辑器组件（基于 WangEditor 实现）、AFormFileUpload 文件上传组件、AFormImgUpload 图片上传组件、AFormInput 输入框组件、AFormRadio 单选框组件、AFormSelect 下拉选择组件、AFormSwitch 开关选择组件、AFormTreeSelect 树形选择组件。 + +这些组件统一了表单交互风格，提供了更好的用户体验。组件支持双向绑定、动态校验、联动控制等高级功能，满足各种复杂的表单场景需求。 + +#### 表格功能增强 + +移除了 vxetable 组件，重构为 el-table 组件，实现跨页选择功能。封装了 useSelection 组合函数处理表格全选和取消全选逻辑。增加了 useTableHeight 组合函数，优化表格显示效果，让分页组件保持固定位置。表格支持固定列、虚拟滚动、合并单元格等高级功能。 + +### 2.5 权限指令增强 + +#### 权限自定义指令 + +权限自定义指令进行了完善重构，支持延迟加载组件。新增了多种指令：permi 用于权限标识符校验、role 用于角色校验、admin 用于管理员校验、superadmin 用于超级管理员校验、permiAll 用于校验是否拥有所有指定权限、roleAll 用于校验是否拥有所有指定角色。 + +移除了全局 proxy 代理的使用，进行了对应代码的适配转换。权限指令支持动态权限变更，无需刷新页面即可更新权限状态。指令使用简单方便，只需在模板中添加相应指令即可实现权限控制。 + +### 2.6 媒体库功能 + +#### AOssMediaManager 组件 + +添加了 AOssMediaManager 媒体库功能组件，增强图片上传体验。组件支持图片预览、替换、删除等基础操作。增加了目录管理功能，支持多租户隔离，可对图片进行分类管理和批量操作。批量移动功能通过修改文件对应的目录 ID 实现。 + +组件配合后端实现了前端文件直传功能，只需配置相应属性即可开启。直传支持阿里云、腾讯云等多种云存储服务。媒体库支持图片预览、水印添加、格式转换等高级功能。 + +### 2.7 图标系统重构 + +#### iconify 引入图标功能重构菜单图标 + +引入了 iconify 图标库，支持多种图标格式和海量图标资源。菜单图标使用 iconify 图标重构，实现了图标库管理功能，方便维护和扩展。图标选择组件进行了优化，支持多种图标格式和自定义图标上传。 + +图标组件重构为 Icon 组件，支持图标名称类型提示，海量图标库可供选择。图标可设置大小、颜色、旋转等属性，满足各种设计需求。图标库持续更新，常用图标均可找到。 + +### 2.8 国际化系统 + +#### 前端国际化 + +useI18n 组合函数进行了增强，t 函数实现了智能提示。实现了菜单国际化功能，菜单配置增加统一键名。引入了 Element Plus 国际化资源，支持多语言切换。语言切换支持缓存和动态加载，用户偏好语言自动保存。 + +前端支持英语、中文、阿拉伯语、德语等多种语言。语言选择器组件支持自定义，可快速切换当前语言。HTTP 请求自动在请求头中添加当前语言信息，后端可据此返回对应语言的文本。 + +### 2.9 性能优化 + +#### 实时通信 + +SSE 连接增加了重连退避策略，支持手动重连和状态监控。实现了动态退避策略的 WebSocket 连接管理，支持多租户上下文和多连接场景。连接异常时自动重连，状态变化实时通知。 + +#### 构建优化 + +Vite 配置进行了优化，提升构建速度和构建产物体积。开启了代码分割、懒加载等优化策略。生产环境构建支持 tree shaking，消除未使用的代码。 + +#### 代码优化 + +全框架取消使用 reactive 函数，统一使用 ref 函数，简化状态管理。移除了原生滚动，改用 el-scrollbar 滚动，优化滚动体验。tree 页面模板进行了重构，代码生成页面结构和实现进行了优化，代码职责更加清晰。 + +## 三、移动端重构优化 + +### 3.1 UniApp 框架重构 + +#### 框架改造 + +移动端基于 unibest 框架进行了重量级重构，移除了不必要模块，保持轻量级。增加了应用 ID 配置管理，模仿前端的实现方式。实现了基础的 tabbar 页面，不使用原生 tabbar，使用自定义组件实现，可更灵活控制样式和功能。 + +增加了分包管理功能，可实现管理员端和代码示例等的分包加载，优化小程序加载速度。插件进行了重构，单一原则分拆插件，提高复用性。增加了静态目录插件，实现静态目录文件类型自动生成。 + +#### 目录结构重构 + +插件目录结构进行了重新调整，分拆插件分别维护。复用了前端 composables 目录下的部分组合函数，优化移动端开发体验。封装了 pinia 相关模块：dict、tabbar、user 等。移动端代码结构清晰，模块划分合理。 + +### 3.2 网络请求与认证 + +#### HTTP 请求封装 + +封装了移动端 useHttp，实现了移动端 API 加密解密。统一了请求拦截和响应处理机制，支持请求前预处理、响应后处理、错误处理等。请求超时、自动重试、请求取消等功能完善。 + +#### 小程序登录认证 + +实现了微信小程序登录和公众号登录，模块化管理。实现了 unionid 和手机号关联绑定，确保用户账号唯一性。用户手机无账户时自动注册，无需繁琐的注册流程。登录页面支持自动登录开关和多种登录方式。 + +实现了手机号注册和登录功能，支持验证码登录和密码登录。登录状态自动保存，下次打开应用自动登录。支持账号切换和退出登录功能。 + +### 3.3 组合式函数与工具类 + +#### Composables 组合函数 + +复用了前端的 useDict、useAuth 等组合函数，保持代码一致性。增加了移动端 usePayment 组合函数，封装支付相关逻辑。增加了 useScroll 组合函数，封装滚动相关逻辑。增加了 useTheme 组合函数，封装主题相关逻辑。 + +移动端实现了 useWebSocket 组合函数，支持多租户 WebSocket 连接管理。组合式函数针对移动端场景进行了优化，在各种设备上稳定运行。 + +#### 工具类函数增强 + +复用了前端 utils 工具类库的部分功能：boolean、date、format、function、object、string 等。新增了 tenant.ts，封装租户相关逻辑。新增了 validators.ts，封装移动端表单验证相关方法。工具类针对小程序环境进行了适配。 + +### 3.4 组件库重构 + +#### WotUI 组件重构 + +wot-ui 组件库所有组件进行了重构，使用最新的 Vue3 和 TypeScript 语法。提高了代码可读性、自行维护性和可扩展性。重构单位统一为 rpx，移动端获得更好体验。增加了 wd-paging 组件，实现下滑分页加载功能。增加了 wd-rich-text 富文本组件，实现富文本读写功能。 + +#### 图标组件系统 + +增加了 wd-iconify 组件和 wd-icon 组件，支持 iconify 图标库和 json 图标。重构了图标库近 400 个图标，包含线条图标和实心图标两大类。图标可在示例代码中搜索使用，方便开发者查找和预览。 + +### 3.5 小程序功能增强 + +#### 多平台支持 + +支持微信小程序完整功能实现。预留了 QQ、支付宝、京东、抖音等各类小程序的扩展实现。统一了小程序 API 调用接口，屏蔽不同平台的差异性。开发者可使用同一套代码发布到多个平台。 + +#### 示例代码系统 + +增加了完善和齐全的 wd 组件示例代码，可直接看到效果。示例代码提供效果预览、代码查看和复制按钮。提供丰富的组件使用示例和最佳实践。开发者可快速学习组件用法并应用到实际项目中。 + +## 四、最新版本更新 + +### 4.1 后端核心升级 + +#### 依赖版本升级 + +后端依赖版本进行了升级：Spring Boot 3.2.8 升级到 3.2.10，MyBatis-Plus 3.5.7 升级到 3.5.8，Sa-Token 1.38.0 升级到 1.39.0，EasyExcel 3.3.4 升级到 4.0.3，Redisson 3.33.0 升级到 3.36.0，Hutool 5.8.29 升级到 5.8.31。版本升级提升了性能和安全性。 + +#### 安全性提升 + +新增全局 XSS 过滤，默认开启，提升系统安全性。异常信息进行了净化处理，去除返回前端异常信息中的 HTML 标签。修复了 Scala 库版本漏洞，限制了高风险依赖版本。权限验证逻辑进行了优化，增强了登录状态判断。 + +#### 租户系统完善 + +修复了一级缓存 key 未区分租户的问题。租户套餐管理增加了重名校验，优化了套餐管理逻辑。新增了同步租户字典功能，支持租户间数据同步。租户相关 controller 支持动态开关控制。 + +### 4.2 支付系统重大升级 + +#### 微信支付智能切换 + +实现了微信支付 v2 和 v3 版本的智能切换。添加了平台证书路径配置，支持 v3 支付安全验证。修正了 keyPath 配置项，确保私钥正确加载。支持微信支付 v3 回调及自动计算订单金额。 + +#### 支付配置优化 + +支付配置表单字段进行了优化，提供了更清晰的提示信息。支付配置实现了完整的租户数据隔离。平台配置支持启用禁用的动态加载更新。统一了支付回调处理，支持多种支付方式。 + +### 4.3 移动端 WD UI 组件库全面升级 + +#### 核心组件增强 + +wd-textarea 支持自动高度和最大行数限制。wd-button 默认防冒泡处理，新增隐形按钮功能。wd-upload 支持预览图大小配置，实现文件直传功能。wd-paging 支持计算属性动态参数，新增前置后置插槽。wd-navbar 支持状态栏字体颜色、标题加粗等个性化配置。 + +#### 新增功能组件 + +新增 wd-voice-recorder 录音组件，支持音频录制功能。富文本编辑器进行了增强，支持图片视频上传。文件直传功能一键开启，支持阿里云、腾讯云等多平台。新增小程序更新检测功能，自动检测版本更新。 + +#### 交互体验优化 + +wd-search 支持圆角大小设置，提升视觉效果。wd-cell 支持右侧 flex 值配置，灵活控制布局宽度。wd-action-sheet 支持 DictItem 数组传递，简化字典选择。wd-tabbar 默认开启底部安全区域适配，避免遮挡问题。 + +### 4.4 前端界面现代化升级 + +#### 组件系统重构 + +AModal 组件替换 el-dialog，支持响应式识别，实现弹窗抽屉自动切换。图标库双引擎同时支持 iconfont 和 iconify 图标库，无感切换使用。Element Plus 组件进行了现代化样式优化。新增 AResizablePanels 可拖拽面板组件。 + +#### 布局主题优化 + +引入了多层级背景色系统，优化视觉层次。统一了导航栏工具项悬停样式，提升交互一致性。Logo 组件对齐方式进行了优化，调整了边框和阴影效果。新增了系统打印功能，支持页面内容打印。 + +### 4.5 代码生成器智能化 + +#### 模板生成优化 + +实体类路径调整，entity 包调整到 domain 包，符合 DDD 设计理念。添加了分组验证和 OSS 翻译自动适配。自动生成 ADetailDialog 组件和查看功能。完善了主子表代码生成，支持复杂业务场景。 + +#### 开发体验提升 + +Vue 生成目录改为 src，可直接复制到前端项目。默认生成权限控制注解，打开注释即可启用。Excel 导入导出代码生成逻辑进行了优化。 + +### 4.6 媒体库系统 + +#### 图片处理引擎 + +支持多张图片合成动态 GIF 图像。提供强大的海报设计和生成功能。内置二维码生成工具，支持自定义样式。提供丰富的字体和颜色处理工具类。 + +#### 文件管理增强 + +支持文件目录分类管理，提升文件组织能力。完整的多租户文件隔离机制。前端和移动端文件直传，减少服务器压力。 + +### 4.7 数据库结构优化 + +#### 表结构调整 + +部门表增加 area_code 字段，支持省市区区划。表名规范化，避免复数命名。商品表新增商品编码、原价、折扣等字段。完善订单状态枚举，包含支付、发货、完成等状态。 + +#### SQL 文件管理 + +数据库脚本分为 sys、job、app 三个部分。每种数据库提供 new.sql 用于新业务表管理。SQL 脚本经过优化，执行效率提升。 + +### 4.8 国际化系统增强 + +#### 多语言支持 + +移动端国际化重构，支持英语、阿拉伯语、德语等多种语言。新增自定义语言选择器组件。支持语言缓存和动态加载。HTTP 请求自动在请求头中添加当前语言信息。 + +### 4.9 部署运维优化 + +#### 容器化部署增强 + +环境变量支持 ${变量名:默认值} 语法，避免敏感信息硬编码。Docker 容器支持本地 IDE 远程调试。docker-compose 配置进行了优化。Docker 构建增加文件上传路径配置。 + +#### 开发体验提升 + +提供 Claude Code 集成，支持 AI 辅助开发。完善了 ESLint 代码规范检查。更新了开发指南和使用文档。 + +## 五、架构重构与 AI 集成 + +### 5.1 四层架构重构 + +#### Controller-Service-DAO-Mapper 分层重构 + +Service 层解耦，移除了对 IBaseService 和 BaseServiceImpl 的继承，Service 层更加轻量和灵活。新增独立 DAO 层，负责查询条件构建和数据访问：DAO 接口继承 IBaseDao，提供统一的数据访问接口；DAO 实现继承 BaseDaoImpl，封装常用数据操作。Mapper 层仅继承 BaseMapper，专注 SQL 执行。 + +职责明确分离：Controller 层负责参数验证和响应包装；Service 层负责业务逻辑处理和类型转换；DAO 层负责查询条件构建和数据访问；Mapper 层负责纯 SQL 执行。 + +#### 数据类型规范化 + +Entity 类型统一，DAO 层和 Mapper 层只返回 Entity 类型，不允许返回 VO 或 BO。Service 层使用 MapstructUtils.convert() 进行类型转换。分页转换优化，使用 PageResult.convert(Class) 简单转换，使用 PageResult.map(Function) 处理复杂业务逻辑。 + +#### 查询条件构建 + +所有查询条件统一在 DAO 层通过 buildQueryWrapper(Bo) 方法构建。PlusLambdaQuery 自动处理 null 值，无需手动判空。PlusQuery 支持表别名和字符串列名，适用于复杂联表查询。 + +### 5.2 LangChain4j AI 集成 + +#### AI 能力引入 + +集成 LangChain4j 企业级 LLM 应用开发框架。统一接口支持 OpenAI、Azure OpenAI、通义千问等主流大模型。独立的 langchain4j 配置模块，支持动态配置和热更新。支持环境变量配置 API 密钥，避免敏感信息硬编码。提供 LANGCHAIN4J_ENABLED 开关，可动态启用禁用 AI 功能。 + +#### AI 聊天功能实现 + +实现了完整的 AI 聊天 REST API 和流式聊天接口。支持创建会话、清除会话、获取会话历史等功能。WebSocket 集成实现 AI 聊天实时消息推送。所有 AI 接口返回 R 格式，保持接口一致性。前端新增 AAiChat 组件，提供完整的 AI 聊天界面和交互体验。根据后端功能配置动态显示或隐藏 AI 聊天入口。 + +#### AI 应用场景 + +智能对话基于上下文实现智能问答系统。文本生成支持内容创作、摘要生成、文本改写等。语义理解实现意图识别、情感分析、关键信息提取。代码辅助支持代码生成、代码审查、bug 分析建议。 + +#### AI 工具链 + +结构化 Prompt 模板管理，支持变量替换。实现会话记忆和上下文管理，对话连贯。AI Agent 支持调用外部工具和 API。RAG 支持检索增强生成，结合知识库提升回答准确性。移除本地向量模型依赖，减少包体积，支持按需启用。 + +### 5.3 开发规范文档完善 + +#### Claude Code 智能提示 + +CLAUDE.md 重构，新增四层架构详细说明和最佳实践。强调工具类优先原则，优先使用项目现有工具类，避免重复造轮子。详细列出了后端 25+、前端 11、移动端 11 个常用工具类。提供完整的 6 层代码模板。 + +#### AGENTS.md 同步更新 + +适配 Claude Code、GitHub Copilot、Cursor、Windsurf、Codeium 等多 AI 助手。各 AI 助手共享相同的架构规范和开发指南。提供正确与错误的代码对比，帮助理解最佳实践。 + +### 5.4 测试体系完善 + +#### 集成测试全覆盖 + +完善用户、角色、菜单、部门、字典等核心模块的集成测试。新增 AI 聊天、首页、统计、系统功能配置等业务接口测试。添加缓存监控、登录日志、操作日志、通知公告等监控接口测试。完善租户管理相关接口的集成测试覆盖。 + +#### 测试基础设施 + +集成 Forest HTTP 客户端进行 HTTP 接口测试。动态端口支持 Spring Boot 随机端口测试。提供测试数据清理脚本，确保测试环境干净。新增 StringUtils、DateUtils 等核心工具类的单元测试。 + +#### 测试覆盖率提升 + +核心功能接口测试覆盖率提升约 42%。确保所有增删改查接口的完整测试覆盖。添加参数校验、权限校验等边界条件测试用例。 + +### 5.5 代码生成器优化 + +#### 生成规范调整 + +实体类路径优化，entity 包调整到 domain 包，符合 DDD 领域驱动设计。DAO 接口命名规范统一为 I{Entity}Dao 格式。自动生成 ADetail 组件和查看详情功能。默认生成 @SaCheckPermission 权限控制注解。 + +#### 代码模板增强 + +自动生成 OSS 字段的序列化映射配置。Vue 目录统一改为 src，可直接复制到前端项目。增强主子表代码生成，支持复杂业务场景。 + +### 5.6 前端组件系统升级 + +#### 新增核心组件 + +AModal 组件替换 el-dialog，支持响应式识别和弹窗抽屉自动切换。ADetail 组件通用详情展示，支持分组显示和自定义插槽。AFormEditor 富文本编辑器组件基于 WangEditor 实现。AResizablePanels 可拖拽调整大小的面板组件。AImportExcel 组件优化导入 Excel 功能，支持模板下载和子表导入。 + +#### 组件功能优化 + +图标系统双引擎同时支持 iconfont 和 iconify 图标库，无感切换。ADetail 组件支持密码类型字段的安全显示。ADetail 组件支持富文本类型字段的渲染。新增 lines1/lines2/lines3 属性，灵活控制长文本显示。 + +#### 路由与权限重构 + +路由模块化，配置拆分为常量路由和动态路由（系统、工作流、工具）。permission.ts 重构为 guard.ts，放置于 router 目录下。权限指令支持延迟加载组件，扩充 permi、role、admin 等权限指令。菜单加载和权限验证逻辑优化。 + +### 5.7 依赖版本升级 + +#### 后端依赖升级 + +Spring Boot 3.3.5 升级到 3.4.1，性能和安全性提升。MyBatis-Plus 3.5.9 升级到 3.5.11，SQL 执行效率优化。Hutool 5.8.31 升级到 5.8.35，工具类功能增强。Redisson 3.39.0 升级到 3.43.0，分布式缓存优化。SnailJob 1.2.0 升级到 1.4.0，定时任务调度增强。WarmFlow 升级至 1.6.6 正式版，工作流功能完善。 + +#### 前端依赖优化 + +移除 await-to-js，使用项目自定义的 to.ts 工具类替代。移除 vxe-table，统一使用 el-table，减少依赖体积。新增 WangEditor 富文本编辑器依赖，提供强大的编辑能力。 \ No newline at end of file