diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 000000000..25b312ef3
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,18 @@
+# http://editorconfig.org
+root = true
+
+# 空格替代Tab缩进在各种编辑工具下效果一致
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+
+[*.md]
+insert_final_newline = false
+trim_trailing_whitespace = false
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 000000000..fa3ee9749
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,48 @@
+######################################################################
+# Build Tools
+
+.gradle
+/build/
+!gradle/wrapper/gradle-wrapper.jar
+
+target/
+!.mvn/wrapper/maven-wrapper.jar
+
+######################################################################
+# IDE
+
+### STS ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### JRebel ###
+rebel.xml
+
+### NetBeans ###
+nbproject/private/
+build/*
+nbbuild/
+nbdist/
+.nb-gradle/
+
+######################################################################
+# Others
+*.log
+*.xml.versionsBackup
+*.swp
+
+!*/build/*.java
+!*/build/*.html
+!*/build/*.xml
+
+.flattened-pom.xml
diff --git a/.run/ruoyi-monitor-admin.run.xml b/.run/ruoyi-monitor-admin.run.xml
new file mode 100644
index 000000000..065ff01a7
--- /dev/null
+++ b/.run/ruoyi-monitor-admin.run.xml
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/.run/ruoyi-server.run.xml b/.run/ruoyi-server.run.xml
new file mode 100644
index 000000000..6c5031edb
--- /dev/null
+++ b/.run/ruoyi-server.run.xml
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/.run/ruoyi-snailjob-server.run.xml b/.run/ruoyi-snailjob-server.run.xml
new file mode 100644
index 000000000..859902ac1
--- /dev/null
+++ b/.run/ruoyi-snailjob-server.run.xml
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 000000000..d53ecaf3d
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,4 @@
+{
+ "java.compile.nullAnalysis.mode": "automatic",
+ "java.configuration.updateBuildConfiguration": "automatic"
+}
\ No newline at end of file
diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md
new file mode 100644
index 000000000..24fa2f599
--- /dev/null
+++ b/DEPLOYMENT_GUIDE.md
@@ -0,0 +1,106 @@
+# RuoYi-Vue-Plus 系统部署指南
+
+## 一、环境准备
+1. **JDK**:需要 JDK 17 或 JDK 21
+2. **数据库**:支持 MySQL/Oracle/PostgreSQL/SQLServer
+3. **Redis**:5.0+ 版本
+4. **Maven**:3.6+ 版本
+5. **Node.js**:前端需要(建议 v18+)
+
+## 二、后端配置部署
+1. **核心配置文件**:
+ - `ruoyi-admin/src/main/resources/application.yml` - 主配置文件
+ - `application-dev.yml`/`application-prod.yml` - 环境配置
+
+2. **关键配置项**:
+ ```yaml
+ # 数据库配置
+ spring.datasource:
+ url: jdbc:mysql://localhost:3306/ry-vue-plus
+ username: root
+ password: 123456
+ driver-class-name: com.mysql.cj.jdbc.Driver
+
+ # Redis配置
+ spring.redis:
+ host: 127.0.0.1
+ port: 6379
+ password: ruoyi123
+ ```
+
+3. **数据库初始化**:
+ - 执行对应数据库的SQL脚本(位于`script/sql/`目录)
+ - 例如MySQL:执行`mysql_ry_vue_5.X.sql`
+
+4. **启动方式**:
+必须启动基础建设: mysql redis admin
+可选启动基础建设: minio(影响文件上传) monitor(影响监控) snailjob(影响定时任务)
+MonitorAdminApplication 为 Admin监控服务(非必要 可参考对应文档关闭 搭建Admin监控)
+SnailJobServerApplication 为 任务调度中心服务(非必要 可参考对应文档关闭 搭建调度中心)
+DromaraApplication 为 主应用服务
+需优先启动 MonitorAdminApplication 与 SnailJobServerApplication 具体配置方式参考对应文档
+最后启动 主服务 DromaraApplication
+工作流相关初始化使用 工作流初始化
+
+## 三、前端部署
+克隆仓库
+git clone https://gitee.com/xlsea/ruoyi-plus-soybean.git
+cd ruoyi-plus-soybean
+安装 pnpm (如果未安装)
+npm install pnpm -g
+设置淘宝镜像
+
+pnpm config set registry https://registry.npmmirror.com
+安装依赖
+pnpm install
+运行开发服务器
+pnpm dev
+构建生产版本
+pnpm build
+
+## 四、Docker部署(可选)
+1. **使用docker-compose**:
+ ```bash
+ cd script/docker
+ docker-compose up -d
+ ```
+ 包含的服务:
+ - Redis
+ - MinIO
+ - RuoYi主服务
+ - 监控中心
+
+2. **独立容器运行**:
+ ```bash
+ docker run -d -p 8080:8080 ruoyi/ruoyi-server:5.3.1
+ ```
+
+## 五、监控中心
+1. **监控服务**:
+ - 访问地址:`http://localhost:9090/admin`
+ - 默认账号:ruoyi/123456
+
+2. **任务调度中心**:
+ - 访问地址:`http://localhost:8800`
+ - 配置见`application-dev.yml`中的`snail-job`部分
+
+## 六、注意事项
+1. 首次启动会自动初始化系统数据
+2. 默认管理员账号:admin/admin123
+3. 生产环境建议:
+ - 修改默认密码
+ - 关闭Swagger(设置`springdoc.swagger-ui.enabled=false`)
+ - 配置HTTPS
+
+完整文档参考:[RuoYi-Vue-Plus文档](https://plus-doc.dromara.org)
+
+ruoyi-vue-plus/
+├── ruoyi-admin/ # 后台核心模块
+├── ruoyi-common/ # 公共模块库
+├── ruoyi-modules/ # 业务模块
+├── ruoyi-extend/ # 扩展模块
+├── ruoyi-plus-soybean/ # 前端Vue3项目
+├── script/ # 部署脚本
+├── target/ # 编译输出
+├── pom.xml # Maven父工程配置
+└── README.md # 项目说明
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 000000000..32b307112
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 RuoYi-Vue-Plus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..fc3131a24
--- /dev/null
+++ b/README.md
@@ -0,0 +1,185 @@
+
+
+
+- - -
+## 平台简介
+
+[](https://gitee.com/dromara/RuoYi-Vue-Plus)
+[](https://github.com/dromara/RuoYi-Vue-Plus)
+[](https://gitcode.com/dromara/RuoYi-Vue-Plus)
+[](https://gitee.com/dromara/RuoYi-Vue-Plus/blob/master/LICENSE)
+[](https://www.jetbrains.com/?from=RuoYi-Vue-Plus)
+
+[](https://gitee.com/dromara/RuoYi-Vue-Plus)
+[]()
+[]()
+[]()
+
+> Dromara RuoYi-Vue-Plus 是重写 RuoYi-Vue 针对 `分布式集群与多租户` 场景全方位升级(不兼容原框架)
+
+> 项目代码、文档 均开源免费可商用 遵循开源协议在项目中保留开源协议文件即可
+活到老写到老 为兴趣而开源 为学习而开源 为让大家真正可以学到技术而开源
+
+> 系统演示: [传送门](https://plus-doc.dromara.org/#/common/demo_system)
+
+> 官方前端项目地址: [plus-ui](https://gitee.com/JavaLionLi/plus-ui)
+> 成员前端项目地址: 基于vben5 [ruoyi-plus-vben5](https://gitee.com/dapppp/ruoyi-plus-vben5)
+
+> 文档地址: [plus-doc](https://plus-doc.dromara.org)
+
+## 赞助商
+
+MaxKey 业界领先单点登录产品 - https://gitee.com/dromara/MaxKey
+CCFlow 驰聘低代码-流程-表单 - https://gitee.com/opencc/RuoYi-JFlow
+数舵科技 软件定制开发APP小程序等 - http://www.shuduokeji.com/
+引迈信息 软件开发平台 - https://www.jnpfsoft.com/index.html?from=plus-doc
+**启山商城系统 多租户商城源码可免费商用可二次开发 - https://www.73app.cn/**
+[如何成为赞助商 加群联系作者详谈](https://plus-doc.dromara.org/#/common/add_group)
+
+# 本框架与RuoYi的功能差异
+
+| 功能 | 本框架 | RuoYi |
+|-------------|-------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+| 前端项目 | 采用 Vue3 + TS + ElementPlus 重写 | 基于Vue2/Vue3 + JS |
+| 后端项目结构 | 采用插件化 + 扩展包形式 结构解耦 易于扩展 | 模块相互注入耦合严重难以扩展 |
+| 后端代码风格 | 严格遵守Alibaba规范与项目统一配置的代码格式化 | 代码书写与常规结构不同阅读障碍大 |
+| Web容器 | 采用 Undertow 基于 XNIO 的高性能容器 | 采用 Tomcat |
+| 权限认证 | 采用 Sa-Token、Jwt 静态使用功能齐全 低耦合 高扩展 | Spring Security 配置繁琐扩展性极差 |
+| 权限注解 | 采用 Sa-Token 支持注解 登录校验、角色校验、权限校验、二级认证校验、HttpBasic校验、忽略校验
角色与权限校验支持多种条件 如 `AND` `OR` 或 `权限 OR 角色` 等复杂表达式 | 只支持是否存在匹配 |
+| 三方鉴权 | 采用 JustAuth 第三方登录组件 支持微信、钉钉等数十种三方认证 | 无 |
+| 关系数据库支持 | 原生支持 MySQL、Oracle、PostgreSQL、SQLServer
可同时使用异构切换(支持其他 mybatis-plus 支持的所有数据库 只需要增加jdbc依赖即可使用 达梦金仓等均有成功案例) | 支持 Mysql、Oracle 不支持同时使用、不支持异构切换 |
+| 缓存数据库 | 支持 Redis 5-7 支持大部分新功能特性 如 分布式限流、分布式队列 | Redis 简单 get set 支持 |
+| Redis客户端 | 采用 Redisson Redis官方推荐 基于Netty的客户端工具
支持Redis 90%以上的命令 底层优化规避很多不正确的用法 例如: keys被转换为scan
支持单机、哨兵、单主集群、多主集群等模式 | Lettuce + RedisTemplate 支持模式少 工具使用繁琐
连接池采用 common-pool Bug多经常性出问题 |
+| 缓存注解 | 采用 Spring-Cache 注解 对其扩展了实现支持了更多功能
例如 过期时间 最大空闲时间 组最大长度等 只需一个注解即可完成数据自动缓存 | 需手动编写Redis代码逻辑 |
+| ORM框架 | 采用 Mybatis-Plus 基于对象几乎不用写SQL全java操作 功能强大插件众多
例如多租户插件 分页插件 乐观锁插件等等 | 采用 Mybatis 基于XML需要手写SQL |
+| SQL监控 | 采用 p6spy 可输出完整SQL与执行时间监控 | log输出 需手动拼接sql与参数无法快速查看调试问题 |
+| 数据分页 | 采用 Mybatis-Plus 分页插件
框架对其进行了扩展 对象化分页对象 支持多种方式传参 支持前端多排序 复杂排序 | 采用 PageHelper 仅支持单查询分页 参数只能从param传 只能单排序 功能扩展性差 体验不好 |
+| 数据权限 | 采用 Mybatis-Plus 插件 自行分析拼接SQL 无感式过滤
只需为Mapper设置好注解条件 支持多种自定义 不限于部门角色 | 采用 注解+aop 实现 基于部门角色 生成的sql兼容性差 不支持其他业务扩展
生成sql后需手动拼接到具体业务sql上 对于多个Mapper查询不起作用 |
+| 数据脱敏 | 采用 注解 + jackson 序列化期间脱敏 支持不同模块不同的脱敏条件
支持多种策略 如身份证、手机号、地址、邮箱、银行卡等 可自行扩展 | 无 |
+| 数据加解密 | 采用 注解 + mybatis 拦截器 对存取数据期间自动加解密
支持多种策略 如BASE64、AES、RSA、SM2、SM4等 | 无 |
+| 接口传输加密 | 采用 动态 AES + RSA 加密请求 body 每一次请求秘钥都不同大幅度降低可破解性 | 无 |
+| 数据翻译 | 采用 注解 + jackson 序列化期间动态修改数据 数据进行翻译
支持多种模式: `映射翻译` `直接翻译` `其他扩展条件翻译` 接口化两步即可完成自定义扩展 内置多种翻译实现 | 无 |
+| 多数据源框架 | 采用 dynamic-datasource 支持市面大部分数据库
通过yml配置即可动态管理异构不同种类的数据库 也可通过前端页面添加数据源
支持spel表达式从请求头参数等条件切换数据源 | 基于 druid 手动编写代码配置数据源 配置繁琐 支持性差 |
+| 多数据源事务 | 采用 dynamic-datasource 支持多数据源不同种类的数据库事务回滚 | 不支持 |
+| 数据库连接池 | 采用 HikariCP Spring官方内置连接池 配置简单 以性能与稳定性闻名天下 | 采用 druid bug众多 社区维护差 活跃度低 配置众多繁琐性能一般 |
+| 数据库主键 | 采用 雪花ID 基于时间戳的 有序增长 唯一ID 再也不用为分库分表 数据合并主键冲突重复而发愁 | 采用 数据库自增ID 支持数据量有限 不支持多数据源主键唯一 |
+| WebSocket协议 | 基于 Spring 封装的 WebSocket 协议 扩展了Token鉴权与分布式会话同步 不再只是基于单机的废物 | 无 |
+| SSE推送 | 采用 Spring SSE 实现 扩展了Token鉴权与分布式会话同步 | 无 |
+| 序列化 | 采用 Jackson Spring官方内置序列化 靠谱!!! | 采用 fastjson bugjson 远近闻名 |
+| 分布式幂等 | 参考美团GTIS防重系统简化实现(细节可看文档) | 手动编写注解基于aop实现 |
+| 分布式锁 | 采用 Lock4j 底层基于 Redisson | 无 |
+| 分布式任务调度 | 采用 SnailJob 天生支持分布式 统一的管理中心 支持多种数据库 支持分片重试DAG任务流等 | 采用 Quartz 基于数据库锁性能差 集群需要做很多配置与改造 |
+| 文件存储 | 采用 Minio 分布式文件存储 天生支持多机、多硬盘、多分片、多副本存储
支持权限管理 安全可靠 文件可加密存储 | 采用 本机文件存储 文件裸漏 易丢失泄漏 不支持集群有单点效应 |
+| 云存储 | 采用 AWS S3 协议客户端 支持 七牛、阿里、腾讯 等一切支持S3协议的厂家 | 不支持 |
+| 短信 | 采用 sms4j 短信融合包 支持数十种短信厂家 只需在yml配置好厂家密钥即可使用 可多厂家共用 | 不支持 |
+| 邮件 | 采用 mail-api 通用协议支持大部分邮件厂商 | 不支持 |
+| 接口文档 | 采用 SpringDoc、javadoc 无注解零入侵基于java注释
只需把注释写好 无需再写一大堆的文档注解了 | 采用 Springfox 已停止维护 需要编写大量的注解来支持文档生成 |
+| 校验框架 | 采用 Validation 支持注解与工具类校验 注解支持国际化 | 仅支持注解 且注解不支持国际化 |
+| Excel框架 | 采用 Alibaba EasyExcel 基于插件化
框架对其增加了很多功能 例如 自动合并相同内容 自动排列布局 字典翻译等 | 基于 POI 手写实现 功能有限 复杂 扩展性差 |
+| 工作流支持 | 支持各种复杂审批 转办 委派 加减签 会签 或签 票签 等功能 | 无 |
+| 工具类框架 | 采用 Hutool、Lombok 上百种工具覆盖90%的使用需求 基于注解自动生成 get set 等简化框架大量代码 | 手写工具稳定性差易出问题 工具数量有限 代码臃肿需自己手写 get set 等 |
+| 监控框架 | 采用 SpringBoot-Admin 基于SpringBoot官方 actuator 探针机制
实时监控服务状态 框架还为其扩展了在线日志查看监控 | 无 |
+| 链路追踪 | 采用 Apache SkyWalking 还在为请求不知道去哪了 到哪出了问题而烦恼吗
用了它即可实时查看请求经过的每一处每一个节点 | 无 |
+| 代码生成器 | 只需设计好表结构 一键生成所有crud代码与页面
降低80%的开发量 把精力都投入到业务设计上
框架为其适配MP、SpringDoc规范化代码 同时支持动态多数据源代码生成 | 代码生成原生结构 只支持单数据源生成 |
+| 部署方式 | 支持 Docker 编排 一键搭建所有环境 让开发人员从此不再为搭建环境而烦恼 | 原生jar部署 其他环境需手动下载安装 自行搭建 |
+| 项目路径修改 | 提供详细的修改方案文档 并为其做了一些改动 非常简单即可修改成自己想要的 | 需要做很多改造 文档说明有限 |
+| 国际化 | 基于请求头动态返回不同语种的文本内容 开发难度低 有对应的工具类 支持大部分注解内容国际化 | 只提供基础功能 其他需自行编写扩展 |
+| 代码单例测试 | 提供单例测试 使用方式编写方法与maven多环境单测插件 | 只提供基础功能 其他需自行编写扩展 |
+| Demo案例 | 提供框架功能的实际使用案例 单独一个模块提供了很多很全 | 无 |
+
+
+## 本框架与RuoYi的业务差异
+
+| 业务 | 功能说明 | 本框架 | RuoYi |
+|--------|----------------------------------------------------------------------|-----|------------------|
+| 租户管理 | 系统内租户的管理 如:租户套餐、过期时间、用户数量、企业信息等 | 支持 | 无 |
+| 租户套餐管理 | 系统内租户所能使用的套餐管理 如:套餐内所包含的菜单等 | 支持 | 无 |
+| 客户端管理 | 系统内对接的所有客户端管理 如: pc端、小程序端等
支持动态授权登录方式 如: 短信登录、密码登录等 支持动态控制token时效 | 支持 | 无 |
+| 用户管理 | 用户的管理配置 如:新增用户、分配用户所属部门、角色、岗位等 | 支持 | 支持 |
+| 部门管理 | 配置系统组织机构(公司、部门、小组) 树结构展现支持数据权限 | 支持 | 支持 |
+| 岗位管理 | 配置系统用户所属担任职务 | 支持 | 支持 |
+| 菜单管理 | 配置系统菜单、操作权限、按钮权限标识等 | 支持 | 支持 |
+| 角色管理 | 角色菜单权限分配、设置角色按机构进行数据范围权限划分 | 支持 | 支持 |
+| 字典管理 | 对系统中经常使用的一些较为固定的数据进行维护 | 支持 | 支持 |
+| 参数管理 | 对系统动态配置常用参数 | 支持 | 支持 |
+| 通知公告 | 系统通知公告信息发布维护 | 支持 | 支持 |
+| 操作日志 | 系统正常操作日志记录和查询 系统异常信息日志记录和查询 | 支持 | 支持 |
+| 登录日志 | 系统登录日志记录查询包含登录异常 | 支持 | 支持 |
+| 文件管理 | 系统文件展示、上传、下载、删除等管理 | 支持 | 无 |
+| 文件配置管理 | 系统文件上传、下载所需要的配置信息动态添加、修改、删除等管理 | 支持 | 无 |
+| 在线用户管理 | 已登录系统的在线用户信息监控与强制踢出操作 | 支持 | 支持 |
+| 定时任务 | 运行报表、任务管理(添加、修改、删除)、日志管理、执行器管理等 | 支持 | 仅支持任务与日志管理 |
+| 代码生成 | 多数据源前后端代码的生成(java、html、xml、sql)支持CRUD下载 | 支持 | 仅支持单数据源 |
+| 系统接口 | 根据业务代码自动生成相关的api接口文档 | 支持 | 支持 |
+| 服务监控 | 监视集群系统CPU、内存、磁盘、堆栈、在线日志、Spring相关配置等 | 支持 | 仅支持单机CPU、内存、磁盘监控 |
+| 缓存监控 | 对系统的缓存信息查询,命令统计等。 | 支持 | 支持 |
+| 在线构建器 | 拖动表单元素生成相应的HTML代码。 | 支持 | 支持 |
+| 使用案例 | 系统的一些功能案例 | 支持 | 不支持 |
+
+## 参考文档
+
+使用框架前请仔细阅读文档重点注意事项
+
+>[初始化项目 必看](https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/init)
+>>[https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/init](https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/init)
+>
+>[专栏与视频 入门必看](https://plus-doc.dromara.org/#/common/column)
+>>[https://plus-doc.dromara.org/#/common/column](https://plus-doc.dromara.org/#/common/column)
+>
+>[部署项目 必看](https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/deploy)
+>>[https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/deploy](https://plus-doc.dromara.org/#/ruoyi-vue-plus/quickstart/deploy)
+>
+>[如何加群](https://plus-doc.dromara.org/#/common/add_group)
+>>[https://plus-doc.dromara.org/#/common/add_group](https://plus-doc.dromara.org/#/common/add_group)
+>
+>[参考文档 Wiki](https://plus-doc.dromara.org)
+>>[https://plus-doc.dromara.org](https://plus-doc.dromara.org)
+
+## 软件架构图
+
+
+
+## 如何参与贡献
+
+[参与贡献的方式 https://plus-doc.dromara.org/#/common/contribution](https://plus-doc.dromara.org/#/common/contribution)
+
+## 捐献作者
+作者为兼职做开源,平时还需要工作,如果帮到了您可以请作者吃个盒饭
+
+
+
+## 演示图例
+
+| | |
+|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+|  |  |
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/RuoYi-Vue-Plus二次开发最佳实践.md b/RuoYi-Vue-Plus二次开发最佳实践.md
new file mode 100644
index 000000000..0605906d7
--- /dev/null
+++ b/RuoYi-Vue-Plus二次开发最佳实践.md
@@ -0,0 +1,941 @@
+# RuoYi-Vue-Plus 二次开发最佳实践
+
+本文档旨在为基于 RuoYi-Vue-Plus (Soybean Admin Pro 版本前端) 进行二次开发的开发者提供一套实践指南,帮助大家更高效、规范地进行项目开发。
+
+## 1. 引言
+
+### 1.1 文档目的与核心读者
+
+本文档的核心目标是为基于 RuoYi-Vue-Plus (特别是采用 Soybean Admin Pro 前端技术栈的版本) 进行二次开发的开发者提供一套清晰、实用的指南,**专注于如何高效、规范地设计、开发和集成全新的业务模块**。本文档尤其强调如何结合 Cursor 这一现代化 AI 辅助开发工具,进一步提升开发效率和代码质量。
+
+Cursor是一款基于AI的智能编辑器,它能够理解您的代码库和开发意图,提供高质量的代码补全、重构建议和智能问答能力。使用Cursor进行RuoYi-Vue-Plus项目的二次开发,能够显著减少重复性工作,提高代码生成效率,并保持项目代码风格的一致性。
+
+无论您是需要为现有系统添加新的业务功能,还是希望基于 RuoYi-Vue-Plus 快速构建包含自定义模块的企业级应用,本文档都将力求为您提供从概念到实践的全方位指导,同时充分利用 Cursor 提供的智能代码辅助功能。
+
+### 1.2 RuoYi-Vue-Plus 模块化特性简介
+
+RuoYi-Vue-Plus 在设计上充分考虑了系统的可扩展性和模块化。后端采用多模块 Maven 项目结构,前端也支持模块化的视图和路由管理。这种设计使得开发者可以相对独立地开发和维护各个业务模块,降低了模块间的耦合度,提高了开发效率和系统的可维护性。
+
+"模块"通常指一组相关联的业务功能单元,例如"订单管理模块"、"产品管理模块"或"客户关系模块",它们在后端有独立的 Maven 模块(通常在 `ruoyi-modules`下),在前端有对应的视图组件、API 服务和路由配置。
+
+通过使用 Cursor 进行开发,您可以借助其强大的代码智能补全和上下文理解能力,使模块化开发更加高效。Cursor能够:
+
+- 分析现有代码结构,快速理解项目架构和组件关系
+- 根据上下文提供符合项目规范的代码片段
+- 协助生成前后端一致的API接口和数据模型
+- 智能重构和改进现有代码,保持风格一致性
+- 减少常见错误和提高代码质量
+
+### 1.3 二次开发新模块的核心原则
+
+在进行新模块开发时,我们遵循以下核心原则:
+
+* **高内聚、低耦合**:新模块内部功能紧密相关,模块之间尽可能减少直接依赖。
+* **遵循框架规范**:充分利用并遵循 RuoYi-Vue-Plus 已有的架构设计、代码规范和工具。
+* **可复用性**:考虑模块内部组件和服务的可复用性,避免代码冗余。
+* **可维护性**:编写清晰、易懂、易于测试的代码,确保长期维护成本最小化。
+* **安全性**:从设计之初就考虑新模块的权限控制和数据安全,防范常见的安全风险。
+* **AI辅助开发**:合理利用 Cursor 提供的 AI 能力进行代码生成、重构和优化,同时保持对生成代码的质量审核。
+
+### 1.4 使用Cursor提升开发体验
+
+作为一款智能开发工具,Cursor在RuoYi-Vue-Plus二次开发中可以提供以下关键优势:
+
+- **快速上手项目**:使用聊天功能直接询问项目结构、核心组件和开发规范
+- **智能代码生成**:基于项目上下文自动生成符合规范的代码片段和完整模块
+- **跨语言开发支持**:同时支持后端Java和前端Vue/TypeScript的智能补全和建议
+- **代码解释和重构**:为复杂代码提供解释,并建议更优的实现方案
+- **标准化编码**:帮助团队保持一致的代码风格和最佳实践
+- **学习辅助**:通过提问了解框架各组件的用法,减少学习曲线
+
+要充分利用Cursor的能力,建议:
+
+1. 将整个项目代码库导入Cursor工作区
+2. 在使用AI功能前,确保已浏览关键部分的代码以建立上下文
+3. 使用具体、明确的提示来获取最佳结果
+4. 先让Cursor解释代码后再请求修改或生成新代码
+
+## 2. 环境准备与项目结构
+
+在开始新模块开发之前,请确保您的开发环境已正确配置,并熟悉项目的基本结构。
+
+### 2.1 开发环境要求
+
+* **后端**:
+ * JDK 17+ (请根据项目 `pom.xml` 中指定的 Java 版本为准)
+ * Maven 3.6+
+ * Redis 6.0+
+ * MySQL 8.0+ (或其他兼容数据库,如PostgreSQL, Oracle)
+ * IDE: IntelliJ IDEA (推荐,对 Maven 和 Spring Boot 支持良好)
+* **前端** (`ruoyi-plus-soybean`):
+ * Node.js 16.x 或 18.x+
+ * 包管理器: pnpm 8.x+ (强烈推荐,项目默认配置)
+ * IDE: VSCode 配合 Cursor 插件 (推荐) 或 Cursor 独立应用
+* **AI辅助开发工具**:
+ * Cursor IDE (集成了 Claude AI 的智能编辑器)
+ * 配置建议:
+ * 启用代码补全和聊天功能
+ * 设置项目级别的上下文提示,说明项目结构和模块关系
+ * 配置保存检查,确保生成的代码符合项目linting规则
+ * 设置快捷键,加速常用AI操作的执行
+ * 对于团队协作,考虑共享提示模板和命令
+
+*重要提示*:
+
+1. 确保所有环境与 RuoYi-Vue-Plus 主项目所依赖的版本兼容。建议查阅项目根目录的 `pom.xml` (后端) 和 `package.json` (前端) 以获取精确的版本信息。
+2. 使用 Cursor 进行开发时,可以通过命令面板 (Cmd/Ctrl+Shift+P) 选择 "Chat with codebase" 功能,帮助快速理解项目结构和代码逻辑。
+3. 建议添加对项目特定文件(如README.md、架构图文档、API规范)的上下文,帮助Cursor更好地理解项目规范。
+
+### 2.2 后端项目结构 (`ruoyi-vue-plus`)
+
+后端项目采用典型的 Maven 多模块结构,这对于添加新业务模块至关重要:
+
+* `ruoyi-vue-plus` (根项目)
+ * `pom.xml`: 主 POM 文件,管理所有模块的依赖和插件。**新增业务模块后,需要在此处的 `` 标签内注册新模块。**
+ * `ruoyi-admin`: 启动和核心管理模块。
+ * `ruoyi-common`: 通用模块父级,包含多个功能明确的子模块:
+ * `ruoyi-common-core`: 核心工具类、常量、枚举、通用 Service/Mapper 接口等。
+ * `ruoyi-common-mybatis`: MyBatis Plus 相关配置和基类。
+ * `ruoyi-common-redis`: Redis 相关配置和工具。
+ * `ruoyi-common-satoken`: SaToken 权限认证相关。
+ * `ruoyi-common-log`: 操作日志和系统日志处理。
+ * `ruoyi-common-web`: Web 相关通用处理,如全局异常、XSS过滤等。
+ * `ruoyi-common-excel`: Excel导入导出处理。
+ * `ruoyi-common-translation`: 数据翻译功能。
+ * `ruoyi-common-tenant`: 多租户支持。
+ * ... (其他通用组件)
+ * `ruoyi-modules`: **所有业务模块的父级模块。您开发的新业务模块将作为其子模块存放。**
+ * `ruoyi-system`: 系统管理模块 (用户、角色、菜单、部门、字典等)。
+ * `ruoyi-generator`: 代码生成器模块。
+ * `ruoyi-job`: 定时任务模块。
+ * `ruoyi-workflow`: 工作流模块(如果已启用)。
+ * `your-new-module`: **您新增的业务模块将放置于此,例如 `ruoyi-pms` (商品管理)。**
+ * `ruoyi-extend`: 扩展模块,如监控等。
+
+**Cursor使用技巧**:
+
+- 使用"文件探索"功能快速导航到关键模块的代码文件
+- 通过聊天功能询问"系统模块之间的依赖关系是什么?"来理解项目架构
+- 请求Cursor生成新模块的Maven配置文件,如"帮我创建一个名为ruoyi-crm的新业务模块的pom.xml文件"
+- 让Cursor分析现有模块的结构,如"分析ruoyi-system模块的目录结构和主要类"
+- 使用Cursor生成符合项目规范的新模块基础结构
+
+### 2.3 前端项目结构 (`ruoyi-plus-soybean`)
+
+前端项目基于 Soybean Admin Pro,采用 Vue 3 + TypeScript + Naive UI 技术栈,组织结构清晰:
+
+* `ruoyi-plus-soybean` (项目根目录)
+ * `src/`: 主要源代码目录。
+ * `views/`: 页面视图组件。**新模块的页面通常会在此目录下创建对应子目录**,例如 `src/views/pms/product/index.vue`。
+ * `service/api/`: API 请求服务。**新模块的后端接口调用会在此目录下创建对应的 `ts` 文件**,例如 `src/service/api/pms/product.ts`。
+ * `router/routes/modules/`: 路由配置文件。**新模块的路由信息会在此目录下创建新的 `ts` 文件**,如 `product.ts`。
+ * `store/modules/`: Pinia 状态管理模块。如果新模块有复杂的状态管理需求,可以在此创建。
+ * `locales/langs/`: 国际化语言包。新模块中需要国际化的文本,其键值对会添加到此处的语言文件中。
+ * `components/`: 通用或业务组件。
+ * `common/`: 通用基础组件。
+ * `custom/`: 业务相关组件。
+ * `advanced/`: 复杂功能组件。
+ * `hooks/`: 自定义 Hooks (Composition API)。
+ * `business/`: 业务相关的钩子函数,如表格操作、权限校验等。
+ * `common/`: 通用钩子函数,如状态管理、UI交互等。
+ * `typings/`: TypeScript 类型定义,特别是 API 相关的类型。
+ * `api/`: 后端接口类型定义。
+ * `utils/`: 工具函数集合。
+
+**Cursor使用技巧**:
+
+- 使用聊天功能分析前端项目结构:"分析ruoyi-plus-soybean前端项目的文件组织和主要模块"
+- 了解组件使用模式:"ruoyi-plus-soybean项目中的表格组件是如何封装的?"
+- 根据已有模块生成新模块:"基于system模块的用户管理页面,创建一个产品管理页面的基础结构"
+- 分析Hooks使用方式:"分析项目中useTable这个hook的用法和参数"
+- 生成符合规范的API服务:"为产品管理模块创建API服务文件,包含列表查询、新增、修改和删除方法"
+
+### 2.4 代码生成器简介与Cursor协同使用
+
+RuoYi-Vue-Plus 提供了强大的代码生成器功能(通常在系统后台的"开发工具"→"代码生成"菜单下)。它可以根据数据库表结构自动生成包括后端 Controller, Service, Mapper, Domain (Entity, BO, VO) 以及前端 Vue 页面和 API 调用代码。
+
+代码生成步骤:
+
+1. 配置数据源(如果尚未配置)
+2. 导入要生成代码的数据表
+3. 编辑表和字段配置(包括字段显示类型、查询方式、是否必填等)
+4. 生成代码
+5. 下载代码包或直接生成到项目中
+
+**强烈建议在创建新模块的基础 CRUD 功能时,优先使用代码生成器**,它可以显著提高开发效率并保证代码结构的统一性。后续可在生成代码的基础上进行业务逻辑的定制和优化。
+
+**代码生成器与Cursor协同工作**:
+
+1. 使用代码生成器生成基础CRUD代码
+2. 将生成的代码导入项目
+3. 使用Cursor分析生成的代码结构:"分析这个新生成的XXX模块的代码结构和主要功能点"
+4. 让Cursor帮助优化生成的代码:"优化这个Controller中的分页查询方法,添加更多的查询条件支持"
+5. 使用Cursor扩展业务逻辑:"在这个Service中添加一个批量处理的方法"
+6. 请求Cursor解释复杂部分:"解释这段MyBatis XML中的动态SQL语句的功能"
+
+这种组合利用代码生成器的快速创建能力和Cursor的智能优化能力,可以最大化提升开发效率,同时确保代码质量和一致性。
+
+## 3. 模块深入分析:以"用户管理"为例
+
+本章通过对用户管理模块的分析,帮助理解 RuoYi-Vue-Plus 项目的模块设计、分层架构以及常用功能的集成方式。
+
+### 3.1 使用Cursor理解模块架构
+
+在开始开发新模块前,彻底理解项目的现有模块结构和设计模式至关重要。Cursor能够帮助开发者快速分析和理解复杂的模块架构,特别是像用户管理这样的核心功能模块。
+
+以下是使用Cursor理解用户管理模块的有效方式:
+
+1. **快速概览模块结构**:
+
+ * 使用聊天功能询问:"用户管理模块的主要组件和类有哪些?"
+ * 让Cursor分析关键类之间的关系:"分析SysUserController、SysUserService和SysUserMapper之间的交互流程"
+2. **分析数据流转**:
+
+ * 请求Cursor绘制数据流程:"从前端请求到后端处理,用户管理模块的数据流是怎样的?"
+ * 了解BO/VO对象转换:"SysUserBo和SysUserVo的区别和转换过程是什么?"
+3. **分析权限控制**:
+
+ * 理解注解应用:"分析用户管理模块中@SaCheckPermission的使用场景和实现逻辑"
+ * 探索数据权限:"用户管理模块如何实现基于部门的数据权限?"
+4. **理解业务逻辑**:
+
+ * 让Cursor解释复杂方法:"解释SysUserServiceImpl中的importUser方法的业务逻辑"
+ * 分析关键业务规则:"用户管理模块中的密码策略是如何实现的?"
+
+通过这些提问和分析,可以快速掌握模块的设计理念和实现细节,为开发新模块打下坚实基础。
+
+### 3.2 后端实现 (`ruoyi-system` 模块)
+
+后端实现遵循经典的分层架构:
+
+* **Controller 层**: 负责接收前端请求,进行初步参数校验和权限验证,然后调用 Service 层处理业务逻辑,并返回统一格式的响应。它主要关注 HTTP 请求和响应的处理。
+* **Service 层**: 包含核心业务逻辑。负责协调对 Mapper 层的调用,执行复杂的业务规则,处理事务和缓存等。Service 层是业务流程的核心。
+* **Mapper 层**: 负责与数据库进行直接交互,执行 SQL 语句完成数据的持久化和检索。通常使用 MyBatis Plus。
+* **Domain 层**: 定义数据对象,包括:
+ * **Entity**: 映射数据库表结构,用于 ORM 操作。
+ * **BO (Business Object)**: 用于 Controller 层接收请求参数和 Service 层内部数据传递,主要负责参数校验。
+ * **VO (View Object)**: 用于 Service 层向 Controller 层返回数据,最终响应给前端,包含前端展示所需的字段,可能进行数据脱敏和翻译。
+
+**Cursor使用提示**: 可以向Cursor请求"生成一个分析用户管理模块各层次依赖关系的结构图",快速理解分层架构。
+
+#### 3.2.1 核心功能实现分析
+
+用户管理模块中的核心功能在后端各层的应用:
+
+* **权限控制 (SaToken)**: 通过注解或编程式方式在 Controller 层对接口进行访问权限校验。
+ * **Cursor分析点:** 请求"分析SaToken在用户管理模块中的应用方式和关键代码"
+* **数据权限**: 在 Mapper 层通过注解实现,根据用户角色动态过滤数据访问范围。
+ * **Cursor分析点:** 询问"解释@DataPermission注解在SysUserMapper中的具体作用"
+* **操作日志**: 通过注解在 Controller 层记录用户的业务操作。
+ * **Cursor分析点:** 请求"展示用户管理模块中操作日志注解的使用示例"
+* **参数校验**: 主要在 BO 对象上通过 JSR 303/380 注解实现,Controller 层触发校验。
+ * **Cursor分析点:** 询问"用户管理模块使用了哪些校验注解及其作用?"
+* **Excel 导入/导出**: 利用 EasyExcel 工具类及其注解简化操作。
+ * **Cursor分析点:** 请求"分析用户Excel导入导出功能的核心实现逻辑"
+* **多租户处理**: 通过框架提供的机制在 Entity 和 Mapper 层实现数据隔离。
+ * **Cursor分析点:** 询问"用户管理模块如何处理多租户数据隔离?"
+* **事务管理**: 在 Service 层通过 `@Transactional` 注解确保数据库操作的原子性。
+ * **Cursor分析点:** 请求"找出用户管理模块中的事务应用示例"
+* **缓存使用 (Redis)**: 通过 Spring Cache 注解和工具类提升数据访问性能。
+ * **Cursor分析点:** 询问"用户管理模块的哪些数据使用了缓存,如何实现?"
+* **国际化**: 通过资源文件和 MessageSource 在后端实现多语言支持。
+ * **Cursor分析点:** 请求"显示用户管理模块中国际化的实现方式"
+* **统一结果与异常处理**: 使用统一的响应结构和全局异常处理器提升代码一致性和用户体验。
+ * **Cursor分析点:** 询问"用户管理模块如何处理业务异常并返回统一结果?"
+
+通过Cursor对这些核心功能的分析,可以深入理解框架的设计理念和实现方式,为开发新模块奠定基础。
+
+### 3.3 前端实现 (`ruoyi-plus-soybean`)
+
+前端实现主要基于 Vue 3、TypeScript 和 Soybean Admin Pro 框架:
+
+* **视图组件**: 使用 Vue 3 组件构建页面,通常包含搜索区、操作按钮区、数据表格等。
+* **Hooks 应用**: 大量使用框架提供的自定义 Hooks (Composables) 封装和复用通用逻辑,如表格数据处理、操作处理、权限校验、字典获取等。
+* **API 服务**: 集中封装所有与后端交互的 API 请求函数,提供统一的请求处理和类型约束。
+* **路由配置**: 定义页面访问路径、组件加载和菜单元信息,通常按模块组织。
+
+**Cursor使用提示**: 可以请求Cursor"分析用户管理前端组件的结构和主要功能块",快速理解前端实现。
+
+#### 3.3.1 前端功能实现分析
+
+前端用户管理模块的核心功能实现:
+
+* **接口调用与数据处理**: 调用封装的 API 服务函数,处理后端数据更新视图。
+ * **Cursor分析点:** 请求"分析用户管理模块的API调用和数据处理流程"
+* **表单与校验**: 使用 UI 组件库构建表单,配合校验规则进行数据验证。
+ * **Cursor分析点:** 询问"用户表单组件的校验规则是如何设置的?"
+* **权限控制**: 利用 `useAuth` Hook 判断用户权限,控制页面元素的显示和操作。
+ * **Cursor分析点:** 请求"展示useAuth在用户管理页面中的应用案例"
+* **国际化**: 使用 `$t` 函数实现界面文本的多语言支持。
+ * **Cursor分析点:** 请求"显示用户管理模块中国际化的实现方式"
+* **状态管理 (Pinia)**: 管理全局或跨组件共享的状态,如用户认证信息、数据字典等。
+ * **Cursor分析点:** 请求"分析用户管理使用了哪些Pinia状态管理"
+* **子组件通信**: 通过标准的 Props 和 Emits 实现组件间的数据传递和事件交互。
+ * **Cursor分析点:** 询问"用户管理页面中的组件通信方式有哪些?"
+
+通过对前端实现的深入分析,结合Cursor的辅助,可以清晰理解Vue 3 + TypeScript的组件化开发模式和最佳实践,为新模块的前端开发提供参考。
+
+### 3.4 使用Cursor复现模块架构
+
+通过对用户管理模块的分析,我们可以使用Cursor帮助复现类似的架构到新的业务模块中:
+
+1. **基础结构生成**:
+
+ * 请求"根据用户管理模块的结构,生成一个产品管理模块的基础结构框架"
+ * 让Cursor生成新模块所需的关键文件列表
+2. **分层设计复现**:
+
+ * 请求"参考用户管理模块,设计产品管理模块的Entity, BO, VO对象结构"
+ * 让Cursor生成"产品管理模块的Controller、Service、Mapper接口定义"
+3. **功能特性实现**:
+
+ * 请求"基于用户管理模块,为产品管理实现数据权限控制代码"
+ * 让Cursor生成"产品管理的Excel导入导出功能实现代码"
+4. **前端组件设计**:
+
+ * 请求"参考用户管理的前端组件,设计产品管理的页面组件结构"
+ * 让Cursor生成"产品管理的API服务和类型定义文件"
+
+通过这种方式,Cursor能够在理解现有模块架构的基础上,生成高度符合项目规范的新模块代码,大幅提高开发效率并保证代码一致性。
+
+## 4. 后端开发最佳实践
+
+本章节将基于对RuoYi-Vue-Plus(特别是用户管理模块)的分析,并结合通用的后端开发原则和Cursor辅助开发能力,总结在进行二次开发时推荐遵循的最佳实践。
+
+### 4.1 Cursor辅助后端开发技巧
+
+在进行RuoYi-Vue-Plus的后端开发时,Cursor可以显著提升开发效率和代码质量。以下是一些关键的辅助开发技巧:
+
+1. **快速理解项目结构**:
+
+ * 使用Cursor分析整体架构:"分析RuoYi-Vue-Plus后端的核心模块结构和依赖关系"
+ * 了解设计模式:"RuoYi-Vue-Plus中应用了哪些设计模式?请举例说明"
+ * 生成模块结构图:"绘制一个RuoYi-Vue-Plus模块依赖关系图"
+2. **代码生成与完善**:
+
+ * 生成常用类文件:"基于RuoYi规范创建一个ProductController类"
+ * 补充接口方法:"为ProductService接口添加批量导入和导出方法"
+ * 实现复杂逻辑:"实现一个根据销售状态统计产品数量的Service方法"
+ * 增强生成代码:"优化代码生成器生成的ProductServiceImpl类,添加缓存支持"
+3. **分析与解释现有代码**:
+
+ * 理解原理:"解释SaToken在RuoYi-Vue-Plus中的集成方式和工作原理"
+ * 分析性能:"分析UserServiceImpl中这个查询方法的性能瓶颈"
+ * 学习最佳实践:"RuoYi项目中MyBatis动态SQL的最佳实践有哪些?"
+4. **代码重构与优化**:
+
+ * 优化复杂方法:"重构这个导入用户的方法,提高可读性和维护性"
+ * 消除代码气味:"这段代码有什么可以改进的地方?"
+ * 提取公共逻辑:"从这几个Service中提取通用的验证逻辑到工具类"
+5. **排查与修复问题**:
+
+ * 分析错误:"为什么这个查询方法返回的结果和预期不符?"
+ * 性能诊断:"为什么这个接口响应很慢?可能的原因和解决方案"
+ * 解决冲突:"解决这个多租户环境下的数据访问冲突问题"
+
+通过这些技巧,开发者可以充分利用Cursor的AI能力,加快开发进度,提升代码质量,同时深入理解项目架构和设计理念。
+
+### 4.2 模块设计与创建
+
+* **单一职责原则 (SRP)**: 设计模块时,应确保每个模块聚焦于一块明确、独立的业务功能领域(例如,系统管理模块 `ruoyi-system` 负责用户、角色、菜单、部门、字典等;产品管理模块 `ruoyi-pms` 负责产品信息的维护)。避免创建过于庞大、职责不清的"上帝模块",这会导致业务逻辑交织,难以理解、维护和独立升级。
+
+**使用Cursor进行模块设计:**
+
+* 分析现有模块分工:"分析RuoYi-Vue-Plus各业务模块的职责边界和交互方式"
+* 设计新模块:"帮我设计一个订单管理模块的功能和边界,考虑与其他模块的关系"
+* 避免过度耦合:"检查我设计的这个模块是否存在责任划分不清的问题"
+
+* **模块命名规范**:
+ * **Maven模块名**: 采用小写字母,多个单词之间使用中横线连接(kebab-case),如 `ruoyi-order-management`, `ruoyi-customer-support`。这与RuoYi-Vue-Plus现有的模块命名风格(如 `ruoyi-common-core`)保持一致。
+ * **Java包名**: 遵循标准的Java包命名约定,通常以反向域名开头,后跟项目名和模块名,全小写。例如:`org.dromara.ordermanagement` 或 `com.yourcompany.yourproject.customersupport`。
+* **模块依赖管理**:
+ * **清晰的依赖关系**: 业务模块(如 `ruoyi-pms`)应明确依赖其所需的平台公共模块(如 `ruoyi-common-core`, `ruoyi-common-mybatis`, `ruoyi-common-web`, `ruoyi-common-satoken`, `ruoyi-common-excel` 等)。
+ * **避免业务模块间的直接强依赖**: 如果业务模块A需要调用业务模块B的功能,应优先考虑是否可以通过更松耦合的方式实现,例如:
+ * **API调用**: 如果模块未来可能独立部署为微服务,或者希望保持高度的独立性,可以设计模块间的API接口,通过HTTP/RPC调用(如使用OpenFeign,若项目引入了Spring Cloud相关技术栈)。
+ * **异步消息/事件**: 对于非核心业务流程的解耦、最终一致性场景或耗时操作,推荐使用消息队列(如RocketMQ、Kafka,需额外集成)或Spring框架内置的事件发布/监听机制 (`ApplicationEvent`)。
+ * **共享公共服务/DTO**: 如果仅仅是共享一些通用的业务逻辑或数据结构,可以考虑将其抽象并下沉到 `ruoyi-common-core` 或创建一个新的、更细粒度的 `ruoyi-common-{feature}` 模块中。
+ * **依赖的最小化原则**: 只依赖真正需要的模块和库,避免不必要的依赖传递和潜在的冲突。
+* **新模块创建流程** (回顾PMS模块示例):
+ 1. 在 `ruoyi-vue-plus/ruoyi-modules` 父Maven模块下,通过IDE或Maven命令创建新的子模块。
+ 2. 在新模块的 `pom.xml` 文件中,将其 `` 指向 `ruoyi-modules`,并根据新模块的业务需求,添加对RuoYi公共模块(如 `ruoyi-common-core`, `ruoyi-common-mybatis`等)和其他第三方库的依赖。
+ 3. 在项目根目录的 `pom.xml` 和 `ruoyi-modules/pom.xml` 文件的 `` 部分,添加新创建的模块名。
+ 4. 在新模块的 `src/main/java/` 目录下,按照既定的包结构(如 `org.dromara.{模块名}`)创建 `controller`, `service`, `mapper`, `domain` (包含 `entity`, `bo`, `vo`) 等子包。
+ 5. 在 `src/main/resources/` 目录下,创建 `mapper/{模块名}` 子目录用于存放MyBatis的XML映射文件,以及 `i18n` 目录用于存放国际化属性文件 (如 `messages_zh_CN.properties`, `messages_en_US.properties`)。
+
+### 4.3 分层架构约定
+
+RuoYi-Vue-Plus 遵循了经典且职责清晰的分层架构,二次开发时应严格遵守此约定:
+
+* **Controller (表现层 / 控制层)**:
+
+ * **核心职责**: 作为HTTP请求的直接入口,负责请求的接收、参数的初步绑定与校验(主要通过JSR 303/380注解在BO上完成)、调用相应的Service层方法来执行核心业务逻辑、组装Service层返回的数据并构建统一的响应结果 (`R` 对象) 返回给前端。
+ * **关注点**: HTTP协议相关的处理,如路径映射 (`@RequestMapping`, `@GetMapping`等)、请求参数解析 (`@PathVariable`, `@RequestParam`, `@RequestBody`等)、权限控制 (`@SaCheckPermission`)、操作日志记录 (`@Log`)。
+ * **禁止**: 直接调用Mapper层进行数据库操作;包含复杂的业务流程代码;直接处理数据库实体 `Entity` 的输入输出(应使用BO和VO)。
+* **Service (业务逻辑层)**:
+
+ * **接口 (`ISyourService.java`)**: 定义业务操作的契约,明确本业务模块能提供的服务能力。面向接口编程是推荐的。
+ * **实现 (`YourServiceImpl.java`)**: 包含核心的业务逻辑实现。负责编排对一个或多个Mapper方法的调用、组合其他Service提供的服务、执行复杂的业务规则校验、管理事务边界、处理缓存逻辑(读/写)、发送领域事件或消息等。
+ * **禁止**: 直接依赖或处理HTTP相关的对象 (如 `HttpServletRequest`, `HttpServletResponse`);将数据库实体 `Entity` 直接返回给Controller层(应转换为VO)。
+ * **事务管理**: 在实现类的公开业务方法上使用 `@Transactional(rollbackFor = Exception.class)` 注解来声明事务边界,确保数据操作的原子性和一致性。
+* **Mapper (数据访问层)**:
+
+ * **接口 (`YourMapper.java`)**: 继承自框架提供的 `BaseMapperPlus`,并可以定义针对特定业务需求的自定义数据库操作方法。对于复杂的SQL语句,应在对应的XML映射文件中编写。
+ * **核心职责**: 负责与数据库进行直接交互,执行SQL语句完成数据的持久化(增删改)和检索(查)。
+ * **禁止**: 包含任何业务逻辑代码;被Controller层直接调用。
+ * **数据权限**: 在Mapper接口方法上使用框架提供的 `@DataPermission` 注解来实现声明式的数据权限控制。
+* **Domain (领域对象层)**:
+
+ * **Entity (`YourEntity.java`)**: 数据库表在Java中的映射对象,用于ORM操作,其字段和结构应与数据表严格对应。
+ * **BO (`YourBo.java`)**: Business Object (业务对象),也常作为DTO (Data Transfer Object)。主要用于Controller层接收前端传入的参数,以及在Service层内部进行数据传递。BO对象是进行参数校验 (JSR 303/380注解) 的主要场所。
+ * **VO (`YourVo.java`)**: View Object (视图对象)。主要用于Service层向Controller层返回处理结果,最终序列化为JSON响应给前端。VO的字段应为前端展示所需,并可能包含经过数据脱敏 (`@Sensitive`)、数据翻译 (`@Translation`) 或其他格式化处理的数据。
+
+**遵循分层架构的好处**:
+
+* **高内聚、低耦合**: 各层职责单一且明确,层与层之间通过接口或定义好的数据对象进行交互,降低了代码的耦合度。
+* **可维护性**: 清晰的结构使得代码更易于理解、修改和维护。问题定位也更加方便。
+* **可测试性**: 可以针对每一层(尤其是Service层和Mapper层)独立编写单元测试和集成测试。
+* **可扩展性与复用性**: 更容易在不影响其他层的情况下替换某一层或某一部分的具体实现,业务逻辑也更容易被复用。
+
+### 4.4 Domain 对象规范 (Entity, BO, VO)
+
+在RuoYi-Vue-Plus中,合理设计和使用Entity、BO、VO对于保持代码清晰和高效至关重要。
+
+* **Entity (`YourEntity.java`) - 持久化对象**: (如 `SysUser`)
+
+ * **用途**: 直接映射数据库表,作为MyBatis Plus进行ORM操作的基础。
+ * **规范**:
+ * 使用 `@TableName` 指明对应的数据库表名。
+ * 使用 `@TableId` 标记主键字段,并可指定主键策略 (如雪花算法 `IdType.ASSIGN_ID`)。
+ * 对于逻辑删除字段,使用 `@TableLogic` 注解。
+ * 字段命名采用驼峰式,对应数据库表的下划线命名(MyBatis Plus默认支持此转换)。
+ * 继承框架提供的基类 (如 `TenantEntity` 以支持多租户和通用审计字段,或 `BaseEntity` 仅包含审计字段)。
+ * **不应**包含任何业务逻辑方法 (除了简单的、基于自身属性的判断,如 `SysUser::isSuperAdmin`)。
+ * **不应**包含与数据库持久化无关的临时字段或计算字段。
+* **BO (`YourBo.java`) - 业务/数据传输对象**: (如 `SysUserBo`)
+
+ * **用途**:
+ 1. Controller层接收前端HTTP请求体 (`@RequestBody`) 或查询参数时的数据封装对象。
+ 2. Service层方法的形式参数类型,用于传递业务操作所需的数据。
+ 3. Service层内部复杂业务逻辑处理时的数据载体。
+ * **规范**:
+ * 字段可以部分来源于Entity,也可以包含Entity中没有的、特定于业务操作的辅助字段(例如,`SysUserBo` 中的 `roleIds`, `postIds` 用于关联操作;`params` Map中的 `beginTime`, `endTime` 用于范围查询)。
+ * **必须**承担参数校验的主要职责,在其字段上使用JSR 303/380标准校验注解 (`@NotBlank`, `@NotNull`, `@Size`, `@Min`, `@Max`, `@Email`, `@Pattern`等) 以及框架自定义的校验注解 (如 `@Xss`)。
+ * 可以使用MapStruct Plus的 `@AutoMapper(target = YourEntity.class)` 注解来辅助与Entity对象之间的属性复制,简化转换代码。
+ * **不应**直接用于数据库的持久化操作(应先转换为对应的Entity对象)。
+ * **不应**包含大量与前端展示强相关的逻辑或格式化字段(这些应在VO中处理)。
+* **VO (`YourVo.java`) - 视图对象**: (如 `SysUserVo`, `SysUserExportVo`, `SysUserImportVo`)
+
+ * **用途**: Service层处理完业务逻辑后,将结果数据封装成VO对象返回给Controller层,最终序列化为JSON响应给前端。
+ * **规范**:
+ * 字段内容应完全根据前端界面的展示需求来定制。可能只包含Entity中的部分字段,也可能包含通过关联查询、计算或数据翻译得到的额外字段。
+ * 对于敏感信息字段(如用户邮箱、手机号),应使用框架提供的 `@Sensitive` 注解进行数据脱敏处理,并可根据权限 (`perms`)决定是否对特定用户展示完整信息。
+ * 对于需要代码/ID转换的字段(如部门ID转部门名称、用户ID转用户昵称、字典值转字典标签、OSS文件ID转URL),应使用框架提供的 `@Translation` 注解进行自动翻译。
+ * 对于导出Excel的场景,应创建专门的ExportVo (如 `SysUserExportVo`),其字段使用 `@ExcelProperty` 注解定义Excel列标题,并使用 `@ExcelDictFormat` 等注解处理字典转换。
+ * 对于从Excel导入数据的场景,应创建专门的ImportVo (如 `SysUserImportVo`),其字段同样使用 `@ExcelProperty` 匹配Excel列,并可使用 `@ExcelDictFormat` 进行字典值的反向转换。
+ * **绝不应**包含用户的密码等高度敏感且不应在前端展示的原始信息。
+ * 可以使用MapStruct Plus的 `@AutoMapper(target = YourEntity.class)` 注解(通常是反向的,从Entity/BO生成VO)来辅助对象属性的复制。
+ * **不应**用于接收前端的输入参数(这是BO的职责)。
+ * **不应**包含业务校验逻辑。
+* **命名约定**:
+
+ * Entity: 直接使用领域名词,如 `Product`, `Order`。
+ * BO: 通常以 `...Bo` 为后缀,如 `ProductBo`, `OrderQueryBo`。
+ * VO: 通常以 `...Vo` 为后缀,如 `ProductVo`, `OrderDetailVo`。特定用途的VO可以更具体,如 `ProductExportVo`。
+* **对象转换**:
+
+ * 推荐使用MapStruct Plus (`@AutoMapper`) 或其他成熟的Java Bean映射工具 (如 `cn.hutool.core.bean.BeanUtil.copyProperties`) 来完成Entity, BO, VO之间的属性复制,以减少手动编写大量getter/setter的模板代码,并提高代码的可读性和可维护性。
+ * 进行对象转换时,需注意深拷贝与浅拷贝的问题,特别是当对象中包含集合或复杂嵌套对象时。对于复杂映射逻辑,MapStruct Plus也支持自定义映射方法。
+* **序列化**: 所有VO对象(以及可能需要缓存的Entity/BO对象)都应实现 `java.io.Serializable` 接口,这是Java序列化的基本要求,对于对象的缓存、分布式Session共享、RPC传输等场景非常重要。
+
+## 5. 前端开发最佳实践
+
+基于对RuoYi-Vue-Plus (Soybean Admin Pro 版本前端) 的分析,本章节将提供前端开发的最佳实践指南,帮助开发人员高效地进行二次开发。
+
+### 5.1 Cursor辅助前端开发技巧
+
+在进行RuoYi-Vue-Plus的前端开发时,Cursor可以显著提升开发效率和代码质量。以下是一些关键的辅助开发技巧:
+
+1. **快速理解项目结构**:
+
+ * 分析项目架构:"分析ruoyi-plus-soybean前端项目的整体架构和核心概念"
+ * 查看技术栈:"列出ruoyi-plus-soybean使用的主要技术栈和库"
+ * 生成目录结构图:"绘制一个ruoyi-plus-soybean前端项目的目录结构图"
+2. **组件开发与完善**:
+
+ * 生成业务组件:"基于项目规范创建一个产品详情页组件"
+ * 添加表单验证:"为这个产品表单添加完整的字段验证规则"
+ * 实现复杂UI:"实现一个带有拖拽排序功能的产品分类管理组件"
+ * 增强现有组件:"为这个表格组件添加导出Excel功能"
+3. **前端工具类分析**:
+
+ * 理解工具实现:"解释useTable hook的实现原理和主要功能"
+ * 分析性能:"分析这个表单渲染方法的性能瓶颈"
+ * 学习最佳实践:"项目中API请求封装的最佳实践有哪些?"
+4. **代码重构与优化**:
+
+ * 优化复杂组件:"重构这个多级表单组件,提高可维护性"
+ * 消除代码气味:"这段TypeScript代码有哪些可以改进的地方?"
+ * 提取公共逻辑:"从这几个组件中提取通用的表单处理逻辑到Hook"
+5. **排查与修复前端问题**:
+
+ * 分析渲染问题:"为什么这个组件首次加载时显示异常?"
+ * 性能诊断:"为什么这个表格组件滚动卡顿?可能的原因和解决方案"
+ * 解决兼容性问题:"解决这个组件在不同浏览器下的显示差异"
+
+通过这些技巧,开发者可以充分利用Cursor的AI能力,加快前端开发进度,提升代码质量和用户体验。
+
+### 5.2 前端项目结构与规范
+
+RuoYi-Vue-Plus (Soybean Admin Pro 版本) 前端项目采用了Vue 3 + TypeScript + Vite的现代化技术栈,在二次开发时应遵循以下结构与规范:
+
+* **核心目录结构**:
+ * `src/assets/`: 静态资源文件,如图片、图标和全局样式。
+ * `src/components/`: 通用组件库,包含可复用的UI组件。
+ * `src/hooks/`: Vue 3 Composition API的自定义hooks,封装可复用的逻辑。
+ * `src/layouts/`: 布局组件,定义整体页面结构。
+ * `src/router/`: 路由配置,定义应用的导航结构。
+ * `src/service/api/`: API服务,封装与后端的HTTP通信。
+ * `src/store/`: 使用Pinia的全局状态管理。
+ * `src/views/`: 页面组件,通常按业务模块组织。
+ * `src/typings/api/`: TypeScript类型定义,特别是API相关的类型。
+
+**使用Cursor进行前端结构分析:**
+
+* 分析目录结构:"分析ruoyi-plus-soybean前端项目的目录结构和主要职责"
+* 查看组件组织:"ruoyi-plus-soybean中组件是如何组织和复用的?"
+* 理解技术集成:"项目中Naive UI是如何与Vue 3集成的?"
+
+* **前端命名规范**:
+ * **文件命名**: 组件文件采用PascalCase(如`UserForm.vue`),工具/服务类文件采用camelCase(如`userService.ts`)。
+ * **目录命名**: 使用kebab-case(如`user-management/`)。
+ * **组件命名**: 组件名应该始终是多个单词的,使用PascalCase,以避免与HTML元素冲突(如`AppButton`而非`Button`)。
+ * **Props命名**: 在组件内部,props应使用camelCase声明,在模板中使用kebab-case传递(Vue自动转换)。
+ * **事件命名**: 使用kebab-case(如`@item-click`),并优先使用原生事件名。
+* **代码风格与最佳实践**:
+ * **Vue 3 Composition API**: 优先使用Composition API + `
+```
+
+## 5. 二次开发指南
+
+### 5.1 开发环境准备
+
+1. **基础环境**:
+ - JDK 17/21
+ - Maven 3.8+
+ - Node.js 16+
+ - MySQL 8.0+/Oracle/PostgreSQL/SQLServer
+ - Redis 5.0+
+
+2. **IDE推荐**:
+ - IntelliJ IDEA(后端)
+ - VSCode(前端)
+
+### 5.2 开发规范与原则
+
+1. **遵循现有架构**:
+ - 保持与现有代码风格一致
+ - 保持模块的独立性和可插拔性
+ - 不随意修改核心模块代码
+
+2. **扩展而非修改**:
+ - 通过扩展现有组件实现功能
+ - 避免直接修改框架核心代码
+
+3. **注重代码质量**:
+ - 编写单元测试
+ - 遵循代码规范
+ - 注释完善
+
+### 5.3 增加PMS模块实施步骤
+
+以下是添加一个产品管理系统(PMS)模块的具体步骤:
+
+#### 5.3.1 后端开发
+
+1. **创建模块结构**:
+ ```
+ ruoyi-modules
+ └── ruoyi-pms -- PMS模块
+ ├── src/main/java/org/dromara/pms
+ │ ├── controller -- 控制器
+ │ ├── domain -- 实体类
+ │ │ ├── bo -- 业务对象
+ │ │ ├── entity -- 数据库实体
+ │ │ └── vo -- 视图对象
+ │ ├── mapper -- MyBatis接口
+ │ └── service -- 服务实现
+ └── src/main/resources
+ ├── mapper -- MyBatis XML
+ └── i18n -- 国际化资源
+ ```
+
+2. **配置模块POM**:
+ - 创建pom.xml,添加必要依赖
+ - 在父模块中添加新模块引用
+
+3. **创建数据库表**:
+ - 设计表结构
+ - 编写SQL脚本
+
+4. **开发核心功能**:
+ - 使用代码生成器生成基础CRUD代码
+ - 扩展实现具体业务逻辑
+ - 添加权限控制
+ - 实现多租户和数据权限
+ - 添加接口文档注释
+
+#### 5.3.2 前端开发
+
+1. **创建模块目录**:
+ ```
+ ruoyi-plus-soybean/src/views/pms
+ ├── product -- 产品管理
+ ├── category -- 分类管理
+ └── inventory -- 库存管理
+ ```
+
+2. **API接口定义**:
+ ```
+ ruoyi-plus-soybean/src/service/api/pms
+ ├── product.ts -- 产品API
+ ├── category.ts -- 分类API
+ └── inventory.ts -- 库存API
+ ```
+
+3. **配置路由**:
+ - 在router/routes目录下创建pms.ts
+ - 在router/index.ts中导入并注册路由
+
+4. **开发页面组件**:
+ - 列表页面
+ - 表单页面
+ - 详情页面
+
+5. **添加权限控制**:
+ - 配置菜单与按钮权限
+ - 实现页面级与按钮级权限控制
+
+#### 5.3.3 集成与测试
+
+1. **数据库脚本集成**:
+ - 将建表SQL添加到初始化脚本中
+
+2. **菜单配置**:
+ - 通过系统管理-菜单管理添加PMS模块菜单
+ - 配置菜单权限
+
+3. **角色授权**:
+ - 为相关角色分配PMS模块权限
+
+4. **单元测试**:
+ - 编写API测试
+ - 编写服务层测试
+
+5. **集成测试**:
+ - 测试完整业务流程
+ - 测试与其他模块的交互
+
+### 5.4 使用框架核心功能的最佳实践
+
+#### 5.4.1 使用多租户
+
+1. **实体类继承TenantEntity**:
+```java
+@Data
+@TableName("pms_product")
+public class PmsProduct extends TenantEntity {
+ // 实体字段定义
+}
+```
+
+2. **多租户过滤配置**:
+```java
+@Configuration
+public class TenantConfig {
+ /**
+ * 配置需要进行多租户过滤的表
+ */
+ @Bean
+ public TenantLineHandler tenantLineHandler() {
+ return new PlusTenantLineHandler() {
+ @Override
+ public String getTenantIdColumn() {
+ return "tenant_id";
+ }
+
+ @Override
+ public boolean ignoreTable(String tableName) {
+ // 配置不需要过滤的表
+ return ArrayUtil.contains(IGNORE_TENANT_TABLES, tableName);
+ }
+ };
+ }
+}
+```
+
+#### 5.4.2 使用数据权限
+
+1. **在Mapper接口上使用注解**:
+```java
+@DataPermission({
+ @DataColumn(key = "deptName", value = "d.dept_id"),
+ @DataColumn(key = "userName", value = "u.user_id")
+})
+public interface SysUserMapper extends BaseMapperPlus {
+ // 方法定义
+}
+```
+
+2. **在查询方法上使用注解**:
+```java
+@Override
+@DataScope(userAlias = "u", deptAlias = "d")
+public List selectUserList(SysUserBo user) {
+ return baseMapper.selectUserList(user);
+}
+```
+
+#### 5.4.3 使用数据脱敏
+
+```java
+public class UserVo {
+
+ // 手机号码脱敏
+ @Sensitive(strategy = SensitiveStrategy.PHONE)
+ private String phonenumber;
+
+ // 邮箱脱敏
+ @Sensitive(strategy = SensitiveStrategy.EMAIL)
+ private String email;
+
+ // 身份证脱敏
+ @Sensitive(strategy = SensitiveStrategy.ID_CARD)
+ private String idCard;
+}
+```
+
+#### 5.4.4 使用Excel导入导出
+
+```java
+@Data
+@ExcelIgnoreUnannotated
+public class UserImportVo {
+
+ @ExcelProperty(value = "用户编号")
+ private Long userId;
+
+ @ExcelProperty(value = "用户名称")
+ @ExcelRequired
+ private String userName;
+
+ @ExcelProperty(value = "用户昵称")
+ @ExcelRequired
+ private String nickName;
+
+ @ExcelProperty(value = "手机号码")
+ @ExcelRequired
+ private String phonenumber;
+
+ @ExcelProperty(value = "邮箱")
+ private String email;
+}
+
+@RestController
+public class UserController {
+
+ /**
+ * 导出用户
+ */
+ @SaCheckPermission("system:user:export")
+ @Log(title = "用户管理", businessType = BusinessType.EXPORT)
+ @PostMapping("/export")
+ public void export(HttpServletResponse response, SysUserBo user) {
+ List list = userService.selectUserList(user);
+ ExcelUtil.exportExcel(list, "用户数据", SysUserVo.class, response);
+ }
+
+ /**
+ * 导入用户
+ */
+ @SaCheckPermission("system:user:import")
+ @Log(title = "用户管理", businessType = BusinessType.IMPORT)
+ @PostMapping("/importData")
+ public R importData(@RequestPart("file") MultipartFile file, boolean updateSupport) throws Exception {
+ ExcelResult result = ExcelUtil.importExcel(file, UserImportVo.class);
+ userService.importUser(result.getList(), updateSupport);
+ return R.ok();
+ }
+}
+```
+
+#### 5.4.5 使用接口幂等性控制
+
+```java
+@RestController
+@RequestMapping("/system/user")
+public class SysUserController {
+
+ /**
+ * 新增用户
+ */
+ @SaCheckPermission("system:user:add")
+ @Log(title = "用户管理", businessType = BusinessType.INSERT)
+ @RepeatSubmit(interval = 5000) // 5秒内不允许重复提交
+ @PostMapping
+ public R add(@Validated @RequestBody SysUserBo user) {
+ return toAjax(userService.insertUser(user));
+ }
+}
+```
+
+#### 5.4.6 使用Redis缓存
+
+```java
+@Service
+public class SysConfigServiceImpl implements ISysConfigService {
+
+ /**
+ * 查询参数配置信息
+ *
+ * @param configId 参数配置ID
+ * @return 参数配置信息
+ */
+ @Override
+ @Cacheable(cacheNames = CacheNames.SYS_CONFIG, key = "#configId")
+ public SysConfig selectConfigById(Long configId) {
+ return baseMapper.selectById(configId);
+ }
+
+ /**
+ * 新增参数配置
+ *
+ * @param config 参数配置信息
+ * @return 结果
+ */
+ @Override
+ @CachePut(cacheNames = CacheNames.SYS_CONFIG, key = "#config.configId")
+ public int insertConfig(SysConfig config) {
+ return baseMapper.insert(config);
+ }
+
+ /**
+ * 删除参数配置
+ *
+ * @param configId 参数ID
+ * @return 结果
+ */
+ @Override
+ @CacheEvict(cacheNames = CacheNames.SYS_CONFIG, key = "#configId")
+ public int deleteConfigById(Long configId) {
+ return baseMapper.deleteById(configId);
+ }
+}
+```
+
+## 6. 总结
+
+RuoYi-Vue-Plus是一个功能完善、架构清晰的企业级应用开发框架,其插件化设计和模块化结构使其非常适合二次开发。在进行二次开发时,应当遵循项目的架构设计和编码规范,通过扩展而非修改的方式实现业务需求,确保系统的可维护性和可扩展性。
+
+通过合理利用项目提供的代码生成、多租户、权限控制等特性,可以大幅提高开发效率,专注于业务逻辑的实现,而非底层架构的搭建。
+
+## 7. 常见问题与解决方案
+
+### 7.1 多租户问题
+
+**问题**:如何对特定表或操作排除多租户过滤?
+
+**解决方案**:
+- 全局排除:在TenantConfig中的ignoreTable方法中添加表名
+- 局部排除:使用@TenantIgnore注解标注在方法或类上
+
+```java
+@TenantIgnore
+public List selectTenantList(SysTenant tenant) {
+ return baseMapper.selectList(buildQueryWrapper(tenant));
+}
+```
+
+### 7.2 权限问题
+
+**问题**:如何实现细粒度的数据权限控制?
+
+**解决方案**:
+- 使用@DataScope注解并配置用户、部门别名
+- 在Mapper层使用@DataPermission定义权限字段
+- 在XML中引用权限过滤片段
+
+### 7.3 分布式事务问题
+
+**问题**:如何处理跨服务的分布式事务?
+
+**解决方案**:
+- 对于强一致性需求,使用Seata进行分布式事务管理
+- 对于最终一致性需求,考虑使用本地消息表+定时任务或消息队列实现
+- 避免长事务,将业务拆分成多个小事务
+
+### 7.4 性能优化问题
+
+**问题**:系统运行缓慢,如何优化?
+
+**解决方案**:
+- 使用Redis缓存热点数据,减少数据库访问
+- 优化SQL查询,避免全表扫描
+- 使用分页查询代替全量查询
+- 合理使用索引
+- 利用多级缓存(本地缓存+Redis缓存)
+- 考虑使用读写分离或分库分表
\ No newline at end of file
diff --git a/docs/GIT_MANUAL.md b/docs/GIT_MANUAL.md
new file mode 100644
index 000000000..76025f8e3
--- /dev/null
+++ b/docs/GIT_MANUAL.md
@@ -0,0 +1,107 @@
+# RuoYi-Vue-Plus 多仓库 Git 管理手册
+
+## 目录
+1. [项目架构说明](#项目架构说明)
+2. [初始化设置](#初始化设置)
+3. [日常操作流程](#日常操作流程)
+4. [冲突处理](#冲突处理)
+5. [命令速查表](#命令速查表)
+6. [注意事项](#注意事项)
+
+## 项目架构说明
+- **主仓库**:`ruoyi-vue-plus`
+ - 同步源:`https://github.com/dromara/RuoYi-Vue-Plus`
+ - 推送目标:`https://github.com/figo990/RuoYi-Vue-Plus`
+- **子模块**:`ruoyi-plus-soybean`
+ - 同步源:`https://gitee.com/xlsea/ruoyi-plus-soybean`
+ - 与主仓库一起推送到 `figo990/RuoYi-Vue-Plus`
+
+## 初始化设置
+```bash
+# 1. 克隆主仓库
+git clone https://github.com/figo990/RuoYi-Vue-Plus.git ruoyi-vue-plus
+cd ruoyi-vue-plus
+
+# 2. 添加官方仓库为上游源
+git remote add upstream https://github.com/dromara/RuoYi-Vue-Plus.git
+
+# 3. 初始化子模块
+git submodule add https://gitee.com/xlsea/ruoyi-plus-soybean.git ruoyi-plus-soybean
+```
+
+## 日常操作流程
+### 同步主仓库更新
+```bash
+git fetch upstream
+git merge upstream/main
+git push origin main
+```
+
+### 同步子模块更新
+```bash
+cd ruoyi-plus-soybean
+git pull origin main
+cd ..
+git add ruoyi-plus-soybean
+git commit -m "Update submodule"
+git push origin main
+```
+
+### 提交本地修改
+```bash
+# 修改主仓库
+git add .
+git commit -m "修改说明"
+git push origin main
+
+# 修改子模块
+cd ruoyi-plus-soybean
+git add .
+git commit -m "子模块修改说明"
+git push origin main
+cd ..
+git add ruoyi-plus-soybean
+git commit -m "更新子模块引用"
+git push origin main
+```
+
+## 冲突处理
+### 主仓库冲突
+```bash
+git fetch upstream
+git merge upstream/main
+# 手动解决冲突后
+git add .
+git commit -m "解决冲突"
+git push origin main
+```
+
+### 子模块冲突
+```bash
+cd ruoyi-plus-soybean
+git pull origin main
+# 手动解决冲突后
+git add .
+git commit -m "解决子模块冲突"
+git push origin main
+cd ..
+git add ruoyi-plus-soybean
+git commit -m "更新子模块引用"
+git push origin main
+```
+
+## 命令速查表
+| 操作 | 命令 |
+| -------------- | ----------------------------------------------------------------------------------- |
+| 拉取官方更新 | `git fetch upstream && git merge upstream/main` |
+| 推送主仓库修改 | `git add . && git commit -m "msg" && git push origin main` |
+| 更新子模块 | `cd ruoyi-plus-soybean && git pull origin main` |
+| 提交子模块修改 | `cd ruoyi-plus-soybean && git add . && git commit -m "msg" && git push origin main` |
+
+## 注意事项
+1. 首次克隆后需初始化子模块:
+ ```bash
+ git submodule update --init --recursive
+ ```
+2. 子模块修改需单独提交到其仓库
+3. 保持主仓库和子模块分支一致(推荐使用`main`分支)
\ No newline at end of file
diff --git a/docs/basic/PMS数据模型.md b/docs/basic/PMS数据模型.md
new file mode 100644
index 000000000..0a7d2539a
--- /dev/null
+++ b/docs/basic/PMS数据模型.md
@@ -0,0 +1,754 @@
+## 云宿居 PMS 系统 - PMS核心数据模型 (最终版 v_ry_final_4.0)
+
+**快速导航:**
+- [1. 引言](#1-引言)
+- [2. PMS 核心E-R图 (最终版 - 简化)](#2-pms-核心er图-最终版---简化)
+- [3. 表结构定义](#3-表结构定义)
+ - [3.1 SaaS平台与系统基础表 (源自若依)](#31-saas平台与系统基础表-源自若依)
+ - [3.2 PMS核心业务表](#32-pms核心业务表)
+ - [3.3 公共数据模型 (PMS相关)](#33-公共数据模型-pms相关)
+- [4. 主要业务实体状态流转](#4-主要业务实体状态流转)
+- [5. 核心业务枚举值定义 (PMS主要部分)](#5-核心业务枚举值定义-pms主要部分)
+- [6. 索引命名与规范建议](#6-索引命名与规范建议)
+
+## 1. 引言
+
+### 1.1 文档目的与范围
+本文档详细定义了"云宿居"民宿 Property Management System (PMS) 的数据库逻辑模型,并与其依赖的若依框架的基础表(如租户、用户、部门等)进行了整合。本文档旨在为数据库的物理实现和后端开发提供具体指导。
+
+**核心原则:**
+1. 若依框架的基础实体(用户、租户、角色、部门等)及其字段规范固定不变。
+2. PMS新增的核心业务表主键统一采用 `BIGINT` 自增ID。
+3. **PMS业务表只关联部门(`dept_id`),不直接关联租户(`tenant_id`)。部门代表实际的门店/分店,通过部门可以查询到其所属租户信息。** 这使得"一个租户下有多个门店"的业务模型更加清晰,同时减少数据冗余。
+4. **特例:`pms_tenant_settings`和`pms_mp_settings`表保留tenant_id字段,通过dept_id为NULL来表示租户全局设置,通过具体的dept_id值表示部门/门店特定设置。**
+5. PMS业务表中的枚举字段,统一使用 `VARCHAR(50)` 存储描述性字符串以增强可读性和扩展性。这与若依常用的 `CHAR(1)` 枚举在交互时需注意API层面的适配。
+
+### 1.2 命名与设计约定 (PMS新增表部分)
+* **表命名:** `pms_` (PMS核心业务表),`cmn_` (公共模块)。若依表使用其原生 `sys_` 前缀。
+* **字段命名:** `snake_case` (小写下划线)。
+* **主键 (PK):**
+ * PMS核心业务实体: **`BIGINT` AUTO_INCREMENT**。
+ * 日志类高频写入表: `BIGINT` AUTO_INCREMENT。
+* **部门ID `dept_id`:** `bigint(20)` (同 `sys_dept.dept_id`),在PMS业务表中非空,用于标识数据归属于哪个门店。
+* **外键 (FK):** 类型与关联表主键一致。`COMMENT '关联 table_name.column_name'`。
+* **通用审计字段 (对齐若依):**
+ * `create_by` (BIGINT(20) NULLABLE, COMMENT '创建者,关联 sys_user.user_id')
+ * `create_time` (DATETIME NULLABLE, COMMENT '创建时间')
+ * `update_by` (BIGINT(20) NULLABLE, COMMENT '更新者,关联 sys_user.user_id')
+ * `update_time` (DATETIME NULLABLE, COMMENT '更新时间')
+ * `create_dept_id` (BIGINT(20) NULLABLE, COMMENT '创建记录的操作员所属部门,关联 sys_dept.dept_id')
+* **软删除策略 (对齐若依):**
+ * `del_flag` (CHAR(1) DEFAULT '0' NOT NULL, COMMENT '删除标志(0代表存在 1代表删除)')。
+* **状态与枚举字段 (PMS优化):**
+ * PMS业务表中的枚举字段,统一使用 `VARCHAR(50)` 存储描述性枚举字符串。
+
+## 2. PMS 核心E-R图 (最终版 - 简化)
+
+```mermaid
+erDiagram
+ %% --- 若依基础表 (关键部分) ---
+ sys_tenant {
+ varchar(20) tenant_id PK "租户编号 (业务主键)"
+ bigint id "物理主键, 若依内部使用"
+ varchar(255) company_name "企业/民宿名称"
+ }
+
+ sys_dept {
+ bigint dept_id PK "部门ID"
+ varchar(20) tenant_id FK "关联 sys_tenant.tenant_id"
+ varchar(30) dept_name "部门名称"
+ }
+
+ sys_user {
+ bigint user_id PK "用户ID (PMS员工)"
+ varchar(20) tenant_id FK "用户初始归属租户"
+ bigint dept_id FK "用户所属部门"
+ varchar(30) user_name "用户名, 全局唯一"
+ }
+
+ sys_role {
+ bigint role_id PK "角色ID"
+ varchar(20) tenant_id FK "角色定义所属租户 (或平台)"
+ varchar(30) role_name "角色名称"
+ }
+
+ %% --- Common Contact Table ---
+ cmn_contacts {
+ BIGINT contact_id PK "联系人ID (自增)"
+ BIGINT dept_id FK "所属部门ID"
+ VARCHAR(255) full_name "姓名"
+ }
+
+ %% --- PMS Core Business Tables (主键改为BIGINT) ---
+ pms_room_types {
+ BIGINT room_type_id PK "房型ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(255) name "房型名称"
+ }
+
+ pms_room_rooms {
+ BIGINT room_id PK "房间ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ BIGINT room_type_id FK "房型ID"
+ VARCHAR(255) room_number "房间号"
+ VARCHAR(50) room_status "物理状态"
+ VARCHAR(50) cleaning_status "清洁状态"
+ }
+
+ pms_room_locks {
+ BIGINT lock_id PK "锁定ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ BIGINT room_id FK "房间ID"
+ }
+
+ pms_core_orders {
+ BIGINT order_id PK "订单ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ BIGINT contact_id FK "联系人ID"
+ BIGINT room_type_id FK "房型ID"
+ BIGINT pms_room_id FK "房间ID(可空)"
+ VARCHAR(50) order_status "订单状态"
+ VARCHAR(50) order_source "订单来源"
+ }
+
+ pms_core_order_items {
+ BIGINT order_item_id PK "订单项ID (自增)"
+ BIGINT order_id FK "订单ID"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(50) product_type "产品类型"
+ }
+
+ pms_core_channels {
+ BIGINT channel_id PK "渠道ID (自增)"
+ BIGINT dept_id FK "部门ID(可空)"
+ VARCHAR(50) channel_type "渠道类型"
+ }
+
+ pms_finance_folios {
+ BIGINT folio_id PK "账单ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ BIGINT order_id FK "订单ID(UNIQUE)"
+ VARCHAR(50) folio_status "账单状态"
+ }
+
+ pms_finance_transactions {
+ BIGINT transaction_id PK "交易ID (自增)"
+ BIGINT folio_id FK "账单ID"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(50) transaction_type "交易类型"
+ }
+
+ pms_finance_payment_methods {
+ BIGINT payment_method_id PK "支付方式ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(50) method_type "支付方式类型"
+ }
+
+ pms_finance_extra_charge_items {
+ BIGINT item_id PK "附加费用项ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ }
+
+ pms_room_pricing_rules {
+ BIGINT rule_id PK "价格规则ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ BIGINT room_type_id FK "房型ID(可空)"
+ }
+
+ pms_tenant_settings {
+ BIGINT setting_id PK "设置ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(100) setting_group "设置分组"
+ VARCHAR(100) setting_key "设置键名"
+ }
+
+ pms_mp_settings {
+ BIGINT setting_id PK "小程序设置ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ VARCHAR(100) setting_key "设置键名"
+ }
+
+ pms_tenant_user_devices {
+ BIGINT id PK "设备记录ID (自增)"
+ BIGINT user_id FK "用户ID"
+ }
+
+ cmn_contact_tags {
+ BIGINT tag_id PK "标签ID (自增)"
+ BIGINT dept_id FK "部门ID"
+ }
+
+ cmn_contact_tag_relations {
+ BIGINT relation_id PK "关联ID (自增)"
+ BIGINT contact_id FK "联系人ID"
+ BIGINT tag_id FK "标签ID"
+ }
+
+ %% --- 若依基础表关联 ---
+ sys_tenant ||--o{ sys_dept : "包含门店/部门"
+ sys_tenant ||--o{ sys_user : "的主要租户"
+ sys_tenant ||--o{ sys_role : "定义角色归属"
+
+ sys_dept ||--o{ sys_user : "员工属于门店"
+
+ %% --- PMS 表关联到若依基础表 ---
+ sys_dept ||--o{ pms_room_types : "定义房型"
+ sys_dept ||--o{ pms_room_rooms : "拥有房间"
+ sys_dept ||--o{ pms_core_orders : "拥有订单"
+ sys_dept ||--o{ cmn_contacts : "拥有联系人"
+ sys_dept ||--o{ pms_tenant_settings : "拥有PMS配置"
+ sys_dept ||--o{ pms_mp_settings : "拥有小程序配置"
+ sys_dept ||--o{ cmn_contact_tags : "定义联系人标签"
+
+ sys_user ||--o{ pms_tenant_user_devices : "注册设备"
+
+ %% --- PMS 内部表关联 ---
+ pms_room_types ||--o{ pms_room_rooms : "有具体房间"
+ pms_room_types ||--o{ pms_core_orders : "被预订类型"
+ pms_room_types o|--o{ pms_room_pricing_rules : "规则适用房型"
+
+ pms_room_rooms ||--o{ pms_room_locks : "可被锁定"
+ pms_room_rooms o|--o{ pms_core_orders : "被分配房间"
+ pms_room_rooms o|--o{ pms_core_order_items : "关联房晚项目"
+
+ pms_core_orders ||--o{ pms_core_order_items : "包含项目"
+ pms_core_orders ||--|| pms_finance_folios : "生成账单"
+ cmn_contacts o|--o{ pms_core_orders : "是主要联系人"
+ pms_core_channels o|--o{ pms_core_orders : "是来源渠道"
+
+ pms_finance_folios ||--o{ pms_finance_transactions : "记录交易"
+ pms_finance_payment_methods o|--o{ pms_finance_transactions : "使用支付方式"
+ pms_finance_extra_charge_items o|--o{ pms_core_order_items : "可以是附加项"
+
+ cmn_contacts ||--o{ cmn_contact_tag_relations : "关联标签"
+ cmn_contact_tags ||--o{ cmn_contact_tag_relations : "被应用于"
+```
+*注:E-R图中部分表的字段为简化表示,详细字段请参照下文。*
+
+## 3. 表结构定义
+
+### 3.1 SaaS平台与系统基础表 (源自若依)
+这些表结构直接采用或参考附件 `ry_vue_5.X - 副本.txt` 中的定义,关键表包括:
+* `sys_tenant`: 租户表 (业务主键 `tenant_id varchar(20)`)
+* `sys_dept`: 部门表 (主键 `dept_id bigint(20)`),在本系统中将作为门店/分店使用
+* `sys_user`: 用户信息表 (主键 `user_id bigint(20)`)
+* `sys_role`: 角色信息表 (主键 `role_id bigint(20)`)
+* `sys_user_role`: 用户角色关联表
+* `sys_config`: 参数配置表
+* `sys_logininfor`: 系统访问记录(登录日志)
+* `sys_dict_type`, `sys_dict_data`: 字典表 (PMS枚举值优先在PMS表中使用 `VARCHAR(50)`,但若依系统本身的字典可按其规范使用)
+
+**PMS系统将直接使用或关联这些若依表中的记录,例如PMS订单的 `dept_id` 将关联到 `sys_dept.dept_id`,`create_by` 将关联到 `sys_user.user_id`。部门进一步通过 `sys_dept.tenant_id` 关联到租户。**
+
+### 3.2 PMS核心业务表
+
+#### 3.2.1 `pms_room_types` - 房型表
+* 业务描述: 存储各部门(门店)定义的房型信息。
+* 主键: `room_type_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `room_type_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '房型唯一ID'): 主键。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID(门店), 关联 sys_dept.dept_id')。
+ * `name` (VARCHAR(255), NOT NULL, COMMENT '房型名称 (例如: 豪华大床房)')。
+ * `default_price` (DECIMAL(10,2), NOT NULL, COMMENT '房型默认价格 (每晚)')。
+ * `capacity` (INT, NOT NULL, COMMENT '标准入住人数')。
+ * `amenities` (JSON, NULLABLE, COMMENT '房型设施标签。JSON数组,例如 [\"wifi\", \"空调\"]')。
+ * `description` (TEXT, NULLABLE, COMMENT '房型描述')。
+ * `images_json` (JSON, NULLABLE, COMMENT '房型图片。JSON数组')。
+ * `sort_order` (INT, DEFAULT 0, COMMENT '显示排序值')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (启用), inactive (禁用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_rt_dept_name` (dept_id, name), `idx_pms_rt_dept_status` (dept_id, status)
+
+#### 3.2.2 `pms_room_rooms` - 房间表
+* 业务描述: 存储各部门(门店)的具体房间信息。
+* 主键: `room_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `room_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '房间唯一ID')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID(门店), 关联 sys_dept.dept_id')。
+ * `room_type_id` (BIGINT, FK, NOT NULL, COMMENT '所属房型ID, 关联 pms_room_types.room_type_id')。
+ * `room_number` (VARCHAR(50), NOT NULL, COMMENT '房间号 (在门店内应唯一)')。
+ * `floor` (VARCHAR(50), NULLABLE, COMMENT '楼层')。
+ * `room_status` (VARCHAR(50), NOT NULL, DEFAULT 'available', COMMENT '物理状态。枚举: available (可用), occupied (占用中), maintenance (维护中), out_of_service (停用服务)')。
+ * `cleaning_status` (VARCHAR(50), NOT NULL, DEFAULT 'clean', COMMENT '清洁状态。枚举: clean (已清洁), dirty (待清洁), cleaning_in_progress (清洁中), inspected (已查房)')。
+ * `description` (TEXT, NULLABLE, COMMENT '房间描述或备注')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '记录状态。枚举: active (启用), inactive (禁用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 唯一约束: `unq_pms_r_dept_room_number` (dept_id, room_number, del_flag)
+* 索引: `idx_pms_r_dept_rt` (dept_id, room_type_id), `idx_pms_r_dept_room_status` (dept_id, room_status), `idx_pms_r_dept_cleaning_status` (dept_id, cleaning_status)
+
+#### 3.2.3 `pms_room_locks` - 房间锁定记录表
+* 业务描述: 记录房间因维护、手动操作等原因被锁定的情况。
+* 主键: `lock_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `lock_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '锁定记录唯一ID')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
+ * `room_id` (BIGINT, FK, NOT NULL, COMMENT '被锁定的房间ID, 关联 pms_room_rooms.room_id')。
+ * `start_datetime` (DATETIME, NOT NULL, COMMENT '锁定开始时间')。
+ * `end_datetime` (DATETIME, NOT NULL, COMMENT '锁定结束时间')。
+ * `reason` (TEXT, NULLABLE, COMMENT '锁定原因')。
+ * `lock_type` (VARCHAR(50), NOT NULL, DEFAULT 'manual_lock', COMMENT '锁定类型。枚举: manual_lock (手动锁定), maintenance (维护), auto_block (自动锁定), staff_use (员工自用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_rl_tenant_dept_room_time` (tenant_id, dept_id, room_id, start_datetime, end_datetime), `idx_pms_rl_tenant_dept_lock_type` (tenant_id, dept_id, lock_type)
+
+#### 3.2.4 `pms_core_orders` - 核心订单表
+* 业务描述: 存储所有来源的预订订单核心信息。
+* 主键: `order_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `order_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '订单唯一ID')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
+ * `contact_id` (BIGINT, FK, NULLABLE, COMMENT '主要联系人ID, 关联 cmn_contacts.contact_id')。
+ * `primary_contact_name` (VARCHAR(100), NOT NULL, COMMENT '主要联系人姓名 (冗余)')。
+ * `primary_contact_phone` (VARCHAR(50), NOT NULL, COMMENT '主要联系人电话 (冗余)')。
+ * `pms_room_id` (BIGINT, FK, NULLABLE, COMMENT '分配的房间ID, 关联 pms_room_rooms.room_id, 入住时分配')。
+ * `room_type_id` (BIGINT, FK, NOT NULL, COMMENT '预订的房型ID, 关联 pms_room_types.room_type_id')。
+ * `channel_id` (BIGINT, FK, NULLABLE, COMMENT '订单来源渠道ID, 关联 pms_core_channels.channel_id')。
+ * `check_in_date` (DATE, NOT NULL, COMMENT '计划入住日期')。
+ * `check_out_date` (DATE, NOT NULL, COMMENT '计划离店日期')。
+ * `num_adults` (INT, NOT NULL, DEFAULT 1, COMMENT '成人数')。
+ * `num_children` (INT, DEFAULT 0, COMMENT '儿童数')。
+ * `estimated_arrival_time` (TIME, NULLABLE, COMMENT '预计抵达时间')。
+ * `total_amount` (DECIMAL(10,2), NOT NULL, COMMENT '订单总金额')。
+ * `paid_amount` (DECIMAL(10,2), DEFAULT 0.00, COMMENT '已付金额')。
+ * `due_amount` (DECIMAL(10,2), AS (`total_amount` - `paid_amount`)) STORED COMMENT '应付金额 (计算列)'。
+ * `currency` (VARCHAR(3), NOT NULL, DEFAULT 'CNY', COMMENT '货币代码')。
+ * `order_status` (VARCHAR(50), NOT NULL, COMMENT '订单状态。枚举: pending_confirmation, confirmed, checked_in, checked_out, cancelled, no_show, extended, waitlist')。
+ * `order_source` (VARCHAR(50), NOT NULL, COMMENT '订单来源。枚举: direct_walk_in, direct_phone, direct_website, direct_mall_h5, ota_channel_manager, travel_agency, corporate, other')。
+ * `notes` (TEXT, NULLABLE, COMMENT '订单备注')。
+ * `cancelled_at` (DATETIME, NULLABLE, COMMENT '取消时间')。
+ * `cancellation_reason` (TEXT, NULLABLE, COMMENT '取消原因')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_o_tenant_dept_status_dates` (tenant_id, dept_id, order_status, check_in_date, check_out_date), `idx_pms_o_tenant_dept_contact_phone` (tenant_id, dept_id, primary_contact_phone), `idx_pms_o_tenant_dept_source` (tenant_id, dept_id, order_source)
+
+#### 3.2.5 `pms_core_order_items` - 核心订单项目表
+* 业务描述: 记录订单中包含的具体商品或服务项目。
+* 主键: `order_item_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `order_item_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '订单项目唯一ID')。
+ * `order_id` (BIGINT, FK, NOT NULL, COMMENT '所属订单ID, 关联 pms_core_orders.order_id')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余)')。
+ * `pms_room_id` (BIGINT, FK, NULLABLE, COMMENT '关联房间ID (如房晚项目), 关联 pms_room_rooms.room_id')。
+ * `product_id` (BIGINT, FK, NULLABLE, COMMENT '关联产品ID (多态), 如 pms_finance_extra_charge_items.item_id')。
+ * `product_type` (VARCHAR(50), NOT NULL, COMMENT '产品类型。枚举: room_night (房晚), extra_charge_item (附加收费项目), package_component (套餐子项), service_fee (服务费), discount_adjustment (折扣调整)')。
+ * `description` (VARCHAR(255), NOT NULL, COMMENT '项目描述 (例如: 豪华大床房住宿, 额外早餐)')。
+ * `quantity` (INT, NOT NULL, DEFAULT 1, COMMENT '数量')。
+ * `unit_price` (DECIMAL(10,2), NOT NULL, COMMENT '单价')。
+ * `total_price` (DECIMAL(10,2), AS (`quantity` * `unit_price`)) STORED COMMENT '总价 (计算列)'。
+ * `service_date` (DATE, NULLABLE, COMMENT '服务发生日期 (例如房晚对应的日期)')。
+ * `notes` (TEXT, NULLABLE, COMMENT '项目备注')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_oi_order_id` (order_id), `idx_pms_oi_tenant_dept_product_type` (tenant_id, dept_id, product_type)
+
+#### 3.2.6 `pms_core_channels` - 订单来源渠道表
+* 业务描述: 管理订单的来源渠道。
+* 主键: `channel_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `channel_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '渠道唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若渠道归属特定部门')。
+ * `name` (VARCHAR(100), NOT NULL, COMMENT '渠道名称 (例如: 携程, 官网直订)')。
+ * `channel_type` (VARCHAR(50), NOT NULL, COMMENT '渠道类型。枚举: ota, direct_booking (官网/电话/前台), gds (全球分销系统), wholesaler (批发商), corporate (公司协议), internal_use (内部使用), other')。
+ * `description` (TEXT, NULLABLE, COMMENT '渠道描述')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), deprecated (弃用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_ch_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_ch_type` (channel_type), `idx_pms_ch_status` (status)
+
+#### 3.2.7 `pms_finance_folios` - 客户账单(Folio)表
+* 业务描述: 记录与订单关联的客户账单核心信息。
+* 主键: `folio_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `folio_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '账单唯一ID')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id')。
+ * `order_id` (BIGINT, UNIQUE, FK, NOT NULL, COMMENT '关联的订单ID, 关联 pms_core_orders.order_id')。
+ * `total_charges` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总应收费用')。
+ * `total_payments` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总已收付款')。
+ * `total_refunds` (DECIMAL(10,2), NOT NULL, DEFAULT 0.00, COMMENT '总已退款')。
+ * `balance` (DECIMAL(10,2), AS (`total_charges` - `total_payments` + `total_refunds`)) STORED COMMENT '当前余额 (计算列)'。
+ * `folio_status` (VARCHAR(50), NOT NULL, DEFAULT 'open', COMMENT '账单状态。枚举: open (开放/未结清), closed (已结清/关闭), void (作废), pending_settlement (待结算)')。
+ * `notes` (TEXT, NULLABLE, COMMENT '账单备注')。
+ * `closed_at` (DATETIME, NULLABLE, COMMENT '账单关闭时间')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_f_tenant_dept_order_id` (tenant_id, dept_id, order_id), `idx_pms_f_tenant_dept_status` (tenant_id, dept_id, folio_status)
+
+#### 3.2.8 `pms_finance_transactions` - 财务交易流水表
+* 业务描述: 记录在Folio中的每一笔财务交易。
+* 主键: `transaction_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `transaction_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '交易唯一ID')。
+ * `folio_id` (BIGINT, FK, NOT NULL, COMMENT '所属账单ID, 关联 pms_finance_folios.folio_id')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余)')。
+ * `transaction_type` (VARCHAR(50), NOT NULL, COMMENT '交易类型。枚举: charge (应收费用), payment (客人付款), refund (退款给客人), deposit (押金), deposit_refund (押金退还), adjustment_positive (正调整), adjustment_negative (负调整)')。
+ * `amount` (DECIMAL(10,2), NOT NULL, COMMENT '交易金额')。
+ * `description` (VARCHAR(255), NOT NULL, COMMENT '交易描述')。
+ * `payment_method_id` (BIGINT, FK, NULLABLE, COMMENT '支付方式ID, 关联 pms_finance_payment_methods.payment_method_id')。
+ * `payment_gateway_txn_id` (VARCHAR(255), NULLABLE, COMMENT '支付网关交易号')。
+ * `transaction_time` (DATETIME, NOT NULL, COMMENT '交易实际发生时间')。
+ * `related_order_item_id` (BIGINT, FK, NULLABLE, COMMENT '关联的订单项ID, 关联 pms_core_order_items.order_item_id')。
+ * `notes` (TEXT, NULLABLE, COMMENT '交易备注')。
+ * `is_void` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否已作废冲销')。
+ * `voided_at` (DATETIME, NULLABLE, COMMENT '作废时间')。
+ * `voided_reason` (TEXT, NULLABLE, COMMENT '作废原因')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_ft_folio_id` (folio_id), `idx_pms_ft_tenant_dept_type_time` (tenant_id, dept_id, transaction_type, transaction_time), `idx_pms_ft_payment_gateway_txn_id` (payment_gateway_txn_id)
+
+#### 3.2.9 `pms_finance_payment_methods` - 支付方式表
+* 业务描述: 存储租户可定义的支付方式。
+* 主键: `payment_method_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `payment_method_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '支付方式唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若支付方式归属特定部门')。
+ * `name` (VARCHAR(100), NOT NULL, COMMENT '支付方式名称 (例如: 现金, 微信支付)')。
+ * `method_type` (VARCHAR(50), NOT NULL, COMMENT '支付方式类型。枚举: cash, credit_card_visa, credit_card_mastercard, credit_card_amex, alipay, wechat_pay, bank_transfer, company_account, voucher, points, other_online_payment, mobile_payment, other')。
+ * `details_json` (JSON, NULLABLE, COMMENT '支付方式附加配置。例如支付网关参数等')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_fpm_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_fpm_tenant_dept_type` (tenant_id, dept_id, method_type), `idx_pms_fpm_tenant_dept_status` (tenant_id, dept_id, status)
+
+#### 3.2.10 `pms_finance_extra_charge_items` - 附加费用项目表
+* 业务描述: 存储租户可预定义的附加消费项目,如额外早餐、加床费等。
+* 主键: `item_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `item_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '附加费用项目唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若项目归属特定部门')。
+ * `name` (VARCHAR(255), NOT NULL, COMMENT '项目名称')。
+ * `default_price` (DECIMAL(10,2), NOT NULL, COMMENT '默认单价')。
+ * `category` (VARCHAR(100), NULLABLE, COMMENT '费用类别,如餐饮、服务、商品等')。
+ * `is_taxable` (BOOLEAN, NOT NULL, DEFAULT TRUE, COMMENT '是否应税')。
+ * `description` (TEXT, NULLABLE, COMMENT '项目描述')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_feci_tenant_dept_name` (tenant_id, dept_id, name), `idx_pms_feci_tenant_dept_category` (tenant_id, dept_id, category), `idx_pms_feci_tenant_dept_status` (tenant_id, dept_id, status)
+
+#### 3.2.11 `pms_room_pricing_rules` - 房间价格规则表
+* 业务描述: 为特定房型在特定日期范围或特定条件下设置价格调整规则。
+* 主键: `rule_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `rule_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '价格规则唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若规则归属特定部门')。
+ * `name` (VARCHAR(255), NOT NULL, COMMENT '规则名称 (例如: 周末特价, 连住优惠)')。
+ * `room_type_id` (BIGINT, FK, NULLABLE, COMMENT '适用的房型ID, 关联 pms_room_types.room_type_id, NULL表示适用于所有房型')。
+ * `date_range_start` (DATE, NULLABLE, COMMENT '规则适用开始日期')。
+ * `date_range_end` (DATE, NULLABLE, COMMENT '规则适用结束日期')。
+ * `days_of_week_json` (JSON, NULLABLE, COMMENT 'JSON数组,数字代表星期几, e.g., [1,2,7] (1-Mon, 7-Sun)')。
+ * `min_length_of_stay` (INT, NULLABLE, COMMENT '最小入住天数要求')。
+ * `max_length_of_stay` (INT, NULLABLE, COMMENT '最大入住天数限制')。
+ * `price_adjustment_type` (VARCHAR(50), NOT NULL, COMMENT '调整类型。枚举: fixed_amount_override (固定价格覆盖), percentage_discount_from_base (基价百分比折扣), fixed_amount_increase_on_base (基价固定金额上浮), fixed_amount_decrease_from_base (基价固定金额下调), set_to_value (设置为特定值)')。
+ * `adjustment_value` (DECIMAL(10,2), NOT NULL, COMMENT '调整值 (具体金额或百分比,如50.00或0.1代表10%)')。
+ * `priority` (INT, NOT NULL, DEFAULT 0, COMMENT '规则优先级,数字越大优先级越高')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), scheduled (计划中)')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 索引: `idx_pms_rpr_tenant_dept_dates` (tenant_id, dept_id, date_range_start, date_range_end), `idx_pms_rpr_tenant_dept_status_priority` (tenant_id, dept_id, status, priority)
+
+#### 3.2.12 `pms_tenant_user_devices` - 租户用户设备表
+* 业务描述: 用于存储租户用户(员工)登录过的设备信息,主要用于推送通知。
+* 主键: `id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '设备记录唯一ID')。
+ * `user_id` (BIGINT(20), FK, NOT NULL, COMMENT '关联的用户ID, 关联 sys_user.user_id')。
+ * `device_type` (VARCHAR(50), NOT NULL, COMMENT '设备类型,例如: ios_app, android_app, wechat_miniprogram, web_push_browser')。
+ * `device_token` (VARCHAR(512), NOT NULL, COMMENT '设备推送令牌')。
+ * `app_version` (VARCHAR(50), NULLABLE, COMMENT '客户端应用版本')。
+ * `last_login_at` (DATETIME, NOT NULL, COMMENT '此设备最后登录时间')。
+ * `status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '状态。枚举: active (激活), inactive (停用), token_expired (令牌过期)')。
+ * `create_time` (DATETIME, NOT NULL, COMMENT '记录创建时间')。
+ * `update_time` (DATETIME, NOT NULL, COMMENT '记录更新时间')。
+* 唯一约束: `unq_pms_ud_user_device_token_type` (user_id, device_token, device_type)
+* 索引: `idx_pms_ud_tenant_user_token` (tenant_id, user_id, device_token), `idx_pms_ud_user_status` (user_id, status)
+
+#### 3.2.13 `pms_tenant_settings` - 租户级PMS特定设置表
+* 业务描述: 存储租户或部门级别的PMS特定业务配置项。与若依的 `sys_config` 互补。
+* 主键: `setting_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `setting_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '设置唯一ID')。
+ * `tenant_id` (VARCHAR(20), NOT NULL, COMMENT '租户编号, 关联 sys_tenant.tenant_id')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, NULL表示租户全局PMS设置')。
+ * `setting_group` (VARCHAR(100), NOT NULL, COMMENT '设置分组,例如: pms_booking_rules, pms_financial_params, pms_ui_appearance')。
+ * `setting_key` (VARCHAR(100), NOT NULL, COMMENT '设置项的唯一键 (在tenant_id, dept_id, setting_group下唯一)')。
+ * `setting_value` (TEXT, NOT NULL, COMMENT '设置项的值 (根据需要可存储JSON字符串)')。
+ * `value_type` (VARCHAR(50), NOT NULL, DEFAULT 'string', COMMENT '值类型,如 string, integer, boolean, json,方便解析')。
+ * `description` (TEXT, NULLABLE, COMMENT '设置项描述')。
+ * `is_sensitive` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否为敏感设置')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 唯一约束: `unq_pms_ts_tenant_dept_group_key` (tenant_id, dept_id, setting_group, setting_key, del_flag)
+* 索引: `idx_pms_ts_tenant_dept_group_key` (tenant_id, dept_id, setting_group, setting_key)
+
+#### 3.2.14 `pms_mp_settings` - 民宿管理小程序配置表
+* 业务描述: 存储租户或部门级别针对民宿员工管理小程序的特定配置项。
+* 主键: `setting_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `setting_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '小程序设置唯一ID')。
+ * `tenant_id` (VARCHAR(20), NOT NULL, COMMENT '租户编号, 关联 sys_tenant.tenant_id')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, NULL表示租户全局小程序设置')。
+ * `setting_key` (VARCHAR(100), NOT NULL, COMMENT '小程序配置项的唯一键。例如: mp_theme_color, mp_enable_feature_xyz')。
+ * `setting_value` (TEXT, NOT NULL, COMMENT '配置项的值 (可存储JSON字符串)')。
+ * `value_type` (VARCHAR(50), NOT NULL, DEFAULT 'string', COMMENT '值类型,如 string, integer, boolean, json')。
+ * `description` (TEXT, NULLABLE, COMMENT '配置项描述')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 唯一约束: `unq_pms_mps_tenant_dept_key` (tenant_id, dept_id, setting_key, del_flag)
+* 索引: `idx_pms_mps_tenant_dept_key` (tenant_id, dept_id, setting_key)
+
+### 3.3 公共数据模型 (PMS相关)
+
+#### 3.3.1 `cmn_contacts` - 联系人表
+* 业务描述: 存储系统中所有类型的联系人信息,主要是PMS的住客。
+* 主键: `contact_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `contact_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '联系人唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若联系人主要归属某部门')。
+ * `contact_type` (VARCHAR(50), NOT NULL, COMMENT '联系人类型。枚举: guest_individual (散客), guest_group_contact (团队联系人), corporate_contact (公司协议联系人), travel_agent_contact (旅行社联系人), company_profile (公司档案), supplier_contact (供应商联系人), employee_profile (员工档案关联), other (其他)')。
+ * `full_name` (VARCHAR(255), NULLABLE, COMMENT '姓名')。
+ * `phone_number` (VARCHAR(50), NULLABLE, COMMENT '主要联系电话')。
+ * `email` (VARCHAR(255), NULLABLE, COMMENT '电子邮件地址')。
+ * `wechat_openid` (VARCHAR(100), NULLABLE, COMMENT '微信OpenID (特定于单个微信公众号或小程序)')。
+ * `wechat_unionid` (VARCHAR(100), NULLABLE, COMMENT '微信UnionID (跨多个微信应用的用户唯一标识)')。
+ * `related_user_id` (BIGINT(20), FK, NULLABLE, COMMENT '关联的系统用户ID, 关联 sys_user.user_id, 如员工档案关联')。
+ * `gender` (VARCHAR(20), NULLABLE, COMMENT '性别。枚举: male (男), female (女), non_binary (非二元), prefer_not_to_say (不愿透露), unknown (未知)')。
+ * `date_of_birth` (DATE, NULLABLE, COMMENT '出生日期')。
+ * `id_type` (VARCHAR(50), NULLABLE, COMMENT '证件类型,如身份证、护照等。可关联sys_dict_data')。
+ * `id_number_encrypted` (VARCHAR(255), NULLABLE, COMMENT '证件号码 (加密存储)')。
+ * `nationality_country_code` (VARCHAR(10), NULLABLE, COMMENT '国籍代码 (ISO 3166-1 alpha-2)')。
+ * `preferred_language` (VARCHAR(10), NULLABLE, COMMENT '偏好语言代码 (e.g., en, zh-CN)')。
+ * `address_street` (VARCHAR(255), NULLABLE, COMMENT '街道地址')。
+ * `address_city` (VARCHAR(100), NULLABLE, COMMENT '城市')。
+ * `address_state_province` (VARCHAR(100), NULLABLE, COMMENT '省/州')。
+ * `address_postal_code` (VARCHAR(50), NULLABLE, COMMENT '邮政编码')。
+ * `address_country_code` (VARCHAR(10), NULLABLE, COMMENT '国家代码 (ISO 3166-1 alpha-2)')。
+ * `contact_status` (VARCHAR(50), NOT NULL, DEFAULT 'active', COMMENT '联系人状态。枚举: active (活跃), inactive (不活跃), prospect (潜在客户), blacklisted (黑名单), pending_verification (待验证), merged_duplicate (已合并重复)')。
+ * `remarks` (TEXT, NULLABLE, COMMENT '备注信息')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 唯一约束 (建议,考虑 `del_flag`):
+ * `unq_cmn_c_tenant_dept_phone` (tenant_id, dept_id, phone_number, del_flag) (如果电话在部门内唯一)
+ * `unq_cmn_c_tenant_dept_email` (tenant_id, dept_id, email, del_flag) (如果邮箱在部门内唯一)
+* 索引: `idx_cmn_c_tenant_dept_fname` (tenant_id, dept_id, full_name), `idx_cmn_c_tenant_dept_status_type` (tenant_id, dept_id, contact_status, contact_type), `idx_cmn_c_related_user` (related_user_id)
+
+#### 3.3.2 `cmn_contact_tags` - 联系人标签表
+* 业务描述: 定义可用于分类和标记联系人的标签。
+* 主键: `tag_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `tag_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '标签唯一ID')。
+ * `dept_id` (BIGINT(20), NULLABLE, COMMENT '部门ID, 关联 sys_dept.dept_id, 若标签归属特定部门或全局')。
+ * `name` (VARCHAR(100), NOT NULL, COMMENT '标签名称')。
+ * `color` (VARCHAR(20), NULLABLE, COMMENT '标签显示颜色,如十六进制色值 #FF5733')。
+ * `category` (VARCHAR(50), NULLABLE, COMMENT '标签分类,如兴趣、客户级别、来源等')。
+ * `description` (TEXT, NULLABLE, COMMENT '标签描述')。
+ * `is_system` (BOOLEAN, NOT NULL, DEFAULT FALSE, COMMENT '是否为系统预设标签 (不可删除)')。
+ * `sort_order` (INT, NOT NULL, DEFAULT 0, COMMENT '排序值')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NULLABLE, COMMENT '创建时间')。
+ * `update_by` (BIGINT(20), NULLABLE, COMMENT '更新者ID, 关联 sys_user.user_id')。
+ * `update_time` (DATETIME, NULLABLE, COMMENT '更新时间')。
+ * `create_dept_id` (BIGINT(20), NULLABLE, COMMENT '创建部门ID, 关联 sys_dept.dept_id')。
+ * `del_flag` (CHAR(1), NOT NULL, DEFAULT '0', COMMENT '删除标志(0存在 1删除)')。
+* 唯一约束: `unq_cmn_ct_tenant_dept_name_category` (tenant_id, dept_id, name, category, del_flag)
+* 索引: `idx_cmn_ct_category` (category), `idx_cmn_ct_is_system` (is_system)
+
+#### 3.3.3 `cmn_contact_tag_relations` - 联系人标签关联表
+* 业务描述: 实现联系人与标签的多对多关系。
+* 主键: `relation_id` (BIGINT AUTO_INCREMENT)
+* 字段定义:
+ * `relation_id` (BIGINT, PK, AUTO_INCREMENT, NOT NULL, COMMENT '关联唯一ID')。
+ * `dept_id` (BIGINT(20), NOT NULL, COMMENT '部门ID, 关联 sys_dept.dept_id (冗余, 以联系人所属部门为准)')。
+ * `contact_id` (BIGINT, FK, NOT NULL, COMMENT '联系人ID, 关联 cmn_contacts.contact_id')。
+ * `tag_id` (BIGINT, FK, NOT NULL, COMMENT '标签ID, 关联 cmn_contact_tags.tag_id')。
+ * `create_by` (BIGINT(20), NULLABLE, COMMENT '创建者ID, 关联 sys_user.user_id')。
+ * `create_time` (DATETIME, NOT NULL, COMMENT '创建时间')。
+* 唯一约束: `unq_cmn_ctr_tenant_dept_contact_tag` (tenant_id, dept_id, contact_id, tag_id)
+* 索引: `idx_cmn_ctr_contact_id` (contact_id), `idx_cmn_ctr_tag_id` (tag_id)
+
+## 4. 主要业务实体状态流转
+
+#### 4.1 订单 (`pms_core_orders`) 状态流转
+
+```mermaid
+stateDiagram-v2
+ [*] --> pending_confirmation: 创建订单
+ pending_confirmation --> confirmed: 确认订单
+ pending_confirmation --> cancelled: 取消订单
+ confirmed --> checked_in: 办理入住
+ confirmed --> cancelled: 取消订单
+ confirmed --> no_show: 未按时入住
+ checked_in --> checked_out: 办理退房
+ checked_in --> extended: 延长入住
+ extended --> checked_out: 办理退房
+ checked_out --> [*] : 订单完成
+ cancelled --> [*] : 订单取消
+ no_show --> [*] : 订单标记为No Show
+```
+* **订单状态 (`order_status` VARCHAR(50)) 枚举值示例:**
+ * `pending_confirmation` (待确认)
+ * `confirmed` (已确认)
+ * `checked_in` (已入住)
+ * `checked_out` (已退房)
+ * `cancelled` (已取消)
+ * `no_show` (未到店)
+ * `extended` (已延期)
+ * `waitlist` (等候名单)
+
+#### 4.2 房间 (`pms_room_rooms`) 状态流转 (物理状态 & 清洁状态)
+
+**物理状态 (`room_status` VARCHAR(50))**
+```mermaid
+stateDiagram-v2
+ [*] --> available: 房间空闲可用
+ available --> occupied: 客人入住 / 预留占用
+ available --> maintenance: 安排维护 / 维修
+ available --> out_of_service: 暂停服务 (其他原因)
+ occupied --> available: 客人退房 (且房间已清洁完成)
+ maintenance --> available: 维护完成 (房间恢复可用)
+ out_of_service --> available: 恢复服务
+```
+* **物理状态枚举值示例:**
+ * `available` (可用)
+ * `occupied` (占用中)
+ * `maintenance` (维护中)
+ * `out_of_service` (暂停服务)
+
+**清洁状态 (`cleaning_status` VARCHAR(50))**
+```mermaid
+stateDiagram-v2
+ [*] --> clean: 初始状态 / 清洁完成
+ clean --> dirty: 客人使用后 / 退房后标记
+ dirty --> cleaning_in_progress: 客房服务员开始清洁
+ cleaning_in_progress --> inspected: 清洁完成待查房
+ inspected --> clean: 查房通过
+ inspected --> cleaning_in_progress: 查房未通过,返工
+ clean --> cleaning_in_progress: 客中打扫 (客人仍在住,但安排了打扫)
+```
+* **清洁状态枚举值示例:**
+ * `clean` (已清洁)
+ * `dirty` (待清洁)
+ * `cleaning_in_progress` (清洁中)
+ * `inspected` (已查房/待检)
+
+#### 4.3 账单 (`pms_finance_folios`) 状态流转
+
+```mermaid
+stateDiagram-v2
+ [*] --> open: 订单创建时自动生成 / 手动创建
+ open --> closed: 账务结清 (所有费用付清)
+ open --> void: 作废账单 (如错误创建)
+ open --> pending_settlement: 等待结算 (如对公转账)
+ pending_settlement --> closed: 结算完成
+ pending_settlement --> open: 取消结算,返回开放
+ closed --> open: 重新打开 (特殊情况,需权限,如补充入账或退款)
+ void --> [*] : 账单作废
+ closed --> [*] : 账单关闭
+```
+* **账单状态 (`folio_status` VARCHAR(50)) 枚举值示例:**
+ * `open` (开放/未结清)
+ * `closed` (已结清/关闭)
+ * `void` (作废)
+ * `pending_settlement` (待结算)
+
+## 5. 核心业务枚举值定义 (PMS主要部分)
+
+以下列出PMS核心业务表中 `VARCHAR(50)` 类型枚举字段的建议值,具体值可根据业务细化调整。
+
+* **`pms_room_types.status`**: `active` (启用), `inactive` (禁用)
+* **`pms_room_rooms.room_status`**: `available` (可用), `occupied` (占用中), `maintenance` (维护中), `out_of_service` (暂停服务)
+* **`pms_room_rooms.cleaning_status`**: `clean` (已清洁), `dirty` (待清洁), `cleaning_in_progress` (清洁中), `inspected` (已查房/待检)
+* **`pms_room_rooms.status` (记录状态)**: `active` (启用), `inactive` (禁用)
+* **`pms_room_locks.lock_type`**: `manual_lock` (手动锁定), `maintenance` (维护), `auto_block` (自动锁定,如欠费), `staff_use` (员工自用), `cleaning_block` (清洁锁定)
+* **`pms_core_orders.order_status`**: `pending_confirmation` (待确认), `confirmed` (已确认), `checked_in` (已入住), `checked_out` (已退房), `cancelled` (已取消), `no_show` (未到店), `extended` (已延期), `waitlist` (等候名单), `provisional` (暂定预订)
+* **`pms_core_orders.order_source`**: `direct_walk_in` (现场步入), `direct_phone` (电话预订), `direct_website` (官网预订), `direct_mall_h5` (H5商城), `ota_channel_manager` (OTA渠道管理), `travel_agency` (旅行社), `corporate_account` (公司协议), `internal_booking` (内部预订), `other` (其他)
+* **`pms_core_order_items.product_type`**: `room_night` (房晚), `extra_charge_item` (附加收费项目), `package_component` (套餐子项), `service_fee` (服务费), `discount_adjustment` (折扣调整), `cancellation_fee` (取消费)
+* **`pms_core_channels.channel_type`**: `ota` (在线旅行社), `direct_booking` (直接预订-官网/电话/前台), `gds` (全球分销系统), `wholesaler` (批发商), `corporate` (公司协议), `internal_use` (内部使用), `meta_search` (元搜索), `other` (其他)
+* **`pms_core_channels.status`**: `active` (激活), `inactive` (停用), `deprecated` (弃用)
+* **`pms_finance_folios.folio_status`**: `open` (开放/未结清), `closed` (已结清/关闭), `void` (作废), `pending_settlement` (待结算)
+* **`pms_finance_transactions.transaction_type`**: `charge` (应收费用), `payment` (客人付款), `refund` (退款给客人), `deposit` (押金收款), `deposit_refund` (押金退还), `adjustment_positive` (正调整), `adjustment_negative` (负调整), `folio_transfer_out` (转出), `folio_transfer_in` (转入)
+* **`pms_finance_payment_methods.method_type`**: `cash` (现金), `credit_card_visa` (VISA卡), `credit_card_mastercard` (万事达卡), `credit_card_amex` (运通卡), `credit_card_unionpay` (银联卡), `alipay` (支付宝), `wechat_pay` (微信支付), `bank_transfer` (银行转账), `company_account` (公司账户/挂账), `voucher` (代金券), `points_redemption` (积分兑换), `other_online_payment` (其他在线支付), `mobile_payment` (其他移动支付), `other` (其他)
+* **`pms_finance_payment_methods.status`**: `active` (激活), `inactive` (停用)
+* **`pms_finance_extra_charge_items.status`**: `active` (激活), `inactive` (停用)
+* **`pms_room_pricing_rules.price_adjustment_type`**: `fixed_amount_override` (固定价格覆盖), `percentage_discount_from_base` (基价百分比折扣), `fixed_amount_increase_on_base` (基价固定金额上浮), `fixed_amount_decrease_from_base` (基价固定金额下调), `set_to_value` (设置为特定值)
+* **`pms_room_pricing_rules.status`**: `active` (激活), `inactive` (停用), `scheduled` (计划中/待生效)
+* **`pms_tenant_user_devices.status`**: `active` (激活), `inactive` (停用), `token_expired` (令牌过期)
+* **`cmn_contacts.contact_type`**: `guest_individual` (散客), `guest_group_contact` (团队联系人), `corporate_contact` (公司协议联系人), `travel_agent_contact` (旅行社联系人), `company_profile` (公司档案), `supplier_contact` (供应商联系人), `employee_profile` (员工档案关联), `other` (其他)
+* **`cmn_contacts.gender`**: `male` (男), `female` (女), `non_binary` (非二元性别), `prefer_not_to_say` (不愿透露), `unknown` (未知)
+* **`cmn_contacts.contact_status`**: `active` (活跃), `inactive` (不活跃), `prospect` (潜在客户), `blacklisted` (黑名单), `pending_verification` (待验证), `merged_duplicate` (已合并重复档案)
+
+## 6. 索引命名与规范建议
+
+* **唯一索引:** `unq_[子系统前缀]_[表名简写]_[字段1]_[字段2]`,例如:`unq_pms_r_tdrn` 代表 `pms_room_rooms` 表上 `tenant_id, dept_id, room_number` 的唯一索引。
+* **普通索引:** `idx_[子系统前缀]_[表名简写]_[字段1]_[字段2]`,例如:`idx_pms_o_tds` 代表 `pms_core_orders` 表上 `tenant_id, dept_id, order_status` 的普通索引。
+* **租户和部门优先:** 对于所有包含 `tenant_id` 和 `dept_id` 的PMS业务表,查询相关的索引应优先考虑这两个字段,顺序通常为 `(tenant_id, dept_id, ...其他条件字段)`。
+* **覆盖索引:** 尽量设计覆盖索引以减少回表,提高查询性能。
+* **避免过多索引:** 每个表的索引数量不宜过多,以免影响写入性能。
+
+---
+**(文档末尾)**
+
+**重要提示:**
+* 本文档中的主键类型已统一为 `BIGINT AUTO_INCREMENT` (用于PMS新增业务表) 或遵循若依原有的 `BIGINT` (用于若依系统表)。
+* PMS业务表中的枚举字段统一为 `VARCHAR(50)`,这与若依的 `CHAR(1)` 不同,在系统集成和前端交互时,可能需要在API层或逻辑层进行适配和转换。
+* 所有PMS业务表已添加 `dept_id` 字段,用于数据归属和统计。确保所有相关查询和业务逻辑都考虑到 `dept_id`。
+* 审计字段和软删除标记已尽量对齐若依规范。
+
+请仔细审查此最终方案,确保其满足所有业务需求和技术约束。
\ No newline at end of file
diff --git a/docs/basic/PMS需求.md b/docs/basic/PMS需求.md
new file mode 100644
index 000000000..a74535433
--- /dev/null
+++ b/docs/basic/PMS需求.md
@@ -0,0 +1,328 @@
+# 云宿居 PMS 系统 - 核心功能需求 (PMS内部聚焦)
+
+## 1. 引言
+
+### 1.1 文档目的与范围
+
+本文档定义了"云宿居"民宿 Property Management System (PMS) 的核心功能需求,**重点聚焦于PMS租户核心业务子系统(以下简称PMS核心模块)的内部功能**。它旨在明确该子系统的核心功能范围和关键业务流程。
+
+本文档是PMS核心模块后续详细设计和开发工作的基础。
+
+### 1.2 目标读者
+
+产品经理、架构师、开发工程师、测试工程师。
+
+### 1.4 术语表
+
+| 术语 | 全称 | 描述 |
+| ------- | -------------------------- | ------------------------------------------------------------- |
+| PMS | Property Management System | 民宿/酒店属性管理系统,管理房间、预订、联系人、账务等核心业务 |
+| Folio | Folio | 客户账单,用于记录联系人在店期间所有费用和付款的详细清单 |
+| Tenant | Tenant | 租户,指使用本SaaS化PMS系统的单个民宿运营方 |
+| Dept | Department | 部门,在本系统中表示租户下的门店/分店 |
+| Contact | Contact | 联系人,指系统中统一管理的客户信息,包括预订人、实际入住人等 |
+
+### 1.5 优先级定义
+
+* **[P0]**: MVP 阶段必须实现的核心功能。
+* **[P1]**: 重要功能,MVP 后第一个主要版本包含。
+* **[P2]**: 次要或完善性功能,后续迭代实现。
+* **[P3]**: 未来规划或可选功能。
+
+## 2. 核心设计原则 (适用于PMS内部)
+
+1. **核心稳固**: 保持PMS核心功能(房态、订单、账务、联系人)的极简和稳定。
+2. **数据为基**: 确保PMS核心数据结构设计合理,易于内部功能扩展。
+3. **安全隐私**: PMS内部数据处理需考虑数据安全和隐私保护。
+4. **门店为中心**: 所有业务数据以门店(部门)为归属单位,支持一个租户下多个门店的业务模型。
+
+## 3. 系统架构概览 (PMS视角)
+
+PMS租户核心业务子系统是整个云宿居平台的核心,负责处理民宿日常运营的核心业务流程。
+
+```mermaid
+flowchart TD
+ subgraph PMSCore["PMS核心业务子系统"]
+ PMS["PMS租户
核心业务子系统"]:::coreSystem
+ end
+
+ subgraph ExternalSystems["外部关联系统"]
+ SaaSPlat[SaaS平台管理]:::system
+ WCDSMM[商城与商品管理]:::system
+ end
+
+ PMSAdmin[PMS核心后台]:::app
+ OwnerApp[民宿管理小程序]:::app
+
+ UserB([民宿主/前台]):::user
+
+ SaaSPlat -- "租户配置" --> PMS
+ WCDSMM -- "预订数据" --> PMS
+ PMS -- "房态/价格" --> WCDSMM
+
+ PMSAdmin --> PMS
+ OwnerApp --> PMS
+
+ UserB -.-> PMSAdmin
+ UserB -.-> OwnerApp
+
+ classDef system fill:#f0f8ff,stroke:#1890ff,stroke-width:1px
+ classDef coreSystem fill:#f6ffed,stroke:#52c41a,stroke-width:3px,color:#135200,font-weight:bold
+ classDef app fill:#d9f7be,stroke:#52c41a,stroke-width:1px
+ classDef user fill:#fff7e6,stroke:#fa8c16,stroke-width:1px,shape:person
+```
+
+## 4. PMS租户核心业务子系统 (PMSTenantCoreSubsystem)
+
+**目标:** 为民宿租户提供稳定、高效的核心运营管理能力。
+**主要用户:** 民宿主/管理员、前台员工。
+
+#### 4.2.1 房态管理 [P0]
+* **功能:**
+ * **网格日历视图:** 直观展示房间占用情况(已预订、已入住、清洁中、维护锁定)。
+ * **今日状态列表:** 按预抵、在住、预离分类展示当日订单/房间。
+ * **清洁状态管理:** 手动标记房间清洁状态 (待清洁/清洁中/已干净)。
+ * **快捷操作:** 在房态图上可快速创建预订、登记入住/退房、标记房间清洁状态、设置房间临时锁定/解锁。支持拖动修改预订的入住日期或房间。
+* **关键数据:**
+ * `pms_room_types` (room_type_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), default_price:DECIMAL(10,2), capacity:INT, amenities:JSON, description:TEXT, images_json:JSON, status:VARCHAR(50))
+ * `pms_room_rooms` (room_id:BIGINT:pk, dept_id:BIGINT, room_type_id:BIGINT, room_number:VARCHAR(50), floor:VARCHAR(50), room_status:VARCHAR(50), cleaning_status:VARCHAR(50), description:TEXT, status:VARCHAR(50))
+ * `pms_room_locks` (lock_id:BIGINT:pk, dept_id:BIGINT, room_id:BIGINT, start_datetime:DATETIME, end_datetime:DATETIME, reason:TEXT, lock_type:VARCHAR(50))
+
+#### 4.2.2 订单管理 [P0, P1, P2]
+* **目标:** 高效、准确地管理所有来源的预订订单。
+* **[P0] 核心订单生命周期管理:**
+ * 功能: 手动创建订单、接收外部系统订单、订单详情查看与编辑、核心状态管理(待确认、已确认、已入住、已退房、已取消、未入住)、关联联系人与房间、生成账单基础、房态联动。
+ * 库存策略: `pending_confirmation` 状态不锁硬库存。`confirmed` 状态锁定库存。
+ * 关键数据:
+ * `pms_core_orders` (order_id:BIGINT:pk, dept_id:BIGINT, contact_id:BIGINT, primary_contact_name:VARCHAR(100), primary_contact_phone:VARCHAR(50), pms_room_id:BIGINT, room_type_id:BIGINT, channel_id:BIGINT, check_in_date:DATE, check_out_date:DATE, num_adults:INT, num_children:INT, estimated_arrival_time:TIME, total_amount:DECIMAL(10,2), paid_amount:DECIMAL(10,2), due_amount:DECIMAL(10,2), currency:VARCHAR(3), order_status:VARCHAR(50), order_source:VARCHAR(50), notes:TEXT, cancelled_at:DATETIME, cancellation_reason:TEXT)
+ * `pms_core_order_items` (order_item_id:BIGINT:pk, order_id:BIGINT, dept_id:BIGINT, pms_room_id:BIGINT, product_id:BIGINT, product_type:VARCHAR(50), description:VARCHAR(255), quantity:INT, unit_price:DECIMAL(10,2), total_price:DECIMAL(10,2), service_date:DATE, notes:TEXT)
+ * `pms_core_channels` (channel_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(100), channel_type:VARCHAR(50), description:TEXT, status:VARCHAR(50))
+ * 状态流转图:
+ ```mermaid
+ stateDiagram-v2
+ [*] --> pending_confirmation: 创建订单
+ pending_confirmation --> confirmed: 确认订单
+ pending_confirmation --> cancelled: 取消订单
+ confirmed --> checked_in: 办理入住
+ confirmed --> cancelled: 取消订单
+ confirmed --> no_show: 未按时入住
+ checked_in --> checked_out: 办理退房
+ checked_in --> extended: 延长入住
+ extended --> checked_out: 办理退房
+ checked_out --> [*] : 订单完成
+ cancelled --> [*] : 订单取消
+ no_show --> [*] : 订单标记为No Show
+ ```
+* **[P1] 增强功能:** 订单修改(日期、房型等)、款项管理(预付款、押金)、取消与退款细则、基础支付记录(如手动录入)、自动化通知(预订成功、入住提醒)、订单备注与标签。
+* **[P2] 实用订单工具:** 简版团体预订、等候名单、订单报表、发票管理。
+
+#### 4.2.3 财务与支付 (Folio Management) [P0]
+* **功能:** 账单管理(Folio)、交易流水、附加消费管理、收款方式与记录、退款处理、账单生成与查询。
+* **关键数据:**
+ * `pms_finance_folios` (folio_id:BIGINT:pk, dept_id:BIGINT, order_id:BIGINT, total_charges:DECIMAL(10,2), total_payments:DECIMAL(10,2), total_refunds:DECIMAL(10,2), balance:DECIMAL(10,2), folio_status:VARCHAR(50), notes:TEXT, closed_at:DATETIME)
+ * `pms_finance_transactions` (transaction_id:BIGINT:pk, folio_id:BIGINT, dept_id:BIGINT, transaction_type:VARCHAR(50), amount:DECIMAL(10,2), description:VARCHAR(255), payment_method_id:BIGINT, payment_gateway_txn_id:VARCHAR(255), transaction_time:DATETIME, related_order_item_id:BIGINT, notes:TEXT, is_void:BOOLEAN, voided_at:DATETIME, voided_reason:TEXT)
+ * `pms_finance_payment_methods` (payment_method_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(100), method_type:VARCHAR(50), details_json:JSON, status:VARCHAR(50))
+ * `pms_finance_extra_charge_items` (item_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), default_price:DECIMAL(10,2), category:VARCHAR(100), is_taxable:BOOLEAN, description:TEXT, status:VARCHAR(50))
+
+#### 4.2.4 联系人与会员管理 [P1] (P0阶段依赖`cmn_contacts`部分字段)
+* **功能 (P0涉及):** 订单关联联系人时,使用/创建`cmn_contacts`记录。
+* **关键数据 (P0使用部分):**
+ * `cmn_contacts` (contact_id:BIGINT:pk, dept_id:BIGINT, contact_type:VARCHAR(50), full_name:VARCHAR(255), phone_number:VARCHAR(50), email:VARCHAR(255), id_type:VARCHAR(50), id_number_encrypted:VARCHAR(255), gender:VARCHAR(20), contact_status:VARCHAR(50))
+* **[P1] 功能:** 统一联系人档案、证件管理、联系人标签[P2]、联系人偏好[P2]、会员信息管理。
+
+#### 4.2.5 会员营销 (储值、等级、权益) [P2]
+* **功能:** 储值管理、会员等级定义与升级、会员权益定义与关联。
+
+#### 4.2.6 租户级系统管理 [P0]
+* **功能:**
+ * **员工管理:** 租户管理员管理内部员工账号。
+ * **角色与权限:** 租户管理员定义内部角色 [MVP: 预设固定角色]。
+ * **基础设置:** 民宿信息、Logo等;房型管理;房间管理;基础定价策略 (`pms_room_types.default_price`, `pms_room_pricing_rules`表);支付方式管理 (`pms_finance_payment_methods`);附加消费项目 (`pms_finance_extra_charge_items`)。
+ * **门店管理:** 在一个租户下管理多个门店,每个门店对应一个sys_dept记录。
+ * **租户特定配置:** 管理租户全局及各门店特定的配置。
+* **关键数据:**
+ * `pms_tenant_settings` (setting_id:BIGINT:pk, tenant_id:VARCHAR(20), dept_id:BIGINT, setting_group:VARCHAR(100), setting_key:VARCHAR(100), setting_value:TEXT, value_type:VARCHAR(50), description:TEXT, is_sensitive:BOOLEAN)
+ * 特殊说明: 保留tenant_id字段,当dept_id为NULL时表示租户全局配置,当dept_id有值时表示特定门店配置。主要存储PMS业务相关的配置项。
+ * `pms_mp_settings` (setting_id:BIGINT:pk, tenant_id:VARCHAR(20), dept_id:BIGINT, setting_key:VARCHAR(100), setting_value:TEXT, value_type:VARCHAR(50), description:TEXT)
+ * 特殊说明: 保留tenant_id字段,当dept_id为NULL时表示租户级小程序配置,当dept_id有值时表示特定门店的小程序配置。主要存储民宿管理小程序的界面和功能配置。
+ * `pms_tenant_user_devices` (id:BIGINT:pk, user_id:BIGINT, device_type:VARCHAR(50), device_token:VARCHAR(512), app_version:VARCHAR(50), last_login_at:DATETIME, status:VARCHAR(50))
+ * `pms_room_pricing_rules` (rule_id:BIGINT:pk, dept_id:BIGINT, name:VARCHAR(255), room_type_id:BIGINT, date_range_start:DATE, date_range_end:DATE, days_of_week_json:JSON, min_length_of_stay:INT, max_length_of_stay:INT, price_adjustment_type:VARCHAR(50), adjustment_value:DECIMAL(10,2), priority:INT, status:VARCHAR(50))
+
+##### 4.2.6.1 员工管理
+* **功能:** 民宿租户管理员管理本民宿的员工账号、分配角色。用户登录后,若关联多个租户或部门,提供切换租户和部门(门店)功能。
+
+#### 4.2.7 简易报表与分析 [P1]
+* **功能:** 核心运营报表 (总营收、入住率、ADR、RevPAR)、渠道来源分析、会员统计、消费分析。
+* **特点:** 支持门店级和租户级统计分析。
+
+#### 4.2.8 民宿管理小程序 (Owner We App) [P0]
+* **技术:** 前端使用 Uni-App
+* **功能:** 房态查看、订单提醒、日程查看(今日预抵/预离)、状态处理 (简单入住/退房操作)、数据概览(核心收支数据)。
+* **特点:** 支持门店切换功能。
+
+#### 4.2.9 PMS核心管理后台 [P0]
+* **描述:** 提供独立的Web管理后台界面,完成所有PMS核心业务操作。
+
+## 5. 关键业务场景模型图 (PMS内部)
+
+### 5.1 订单状态图 - 房间预订生命周期
+
+```mermaid
+stateDiagram-v2
+ [*] --> 待确认: 用户创建预订
+ 待确认 --> 已确认: 预付款成功/人工确认
+ 待确认 --> 已取消: 超时未确认/用户取消
+ 已确认 --> 已取消: 申请取消并退款
+ 已确认 --> 已入住: 办理入住手续
+ 已入住 --> 已退房: 办理退房手续
+ 已退房 --> 已完成: 完成结算
+ 已取消 --> [*]
+ 已完成 --> [*]
+```
+
+### 5.2 PMS核心业务状态图
+
+```mermaid
+stateDiagram-v2
+ state 房间状态 {
+ [*] --> 空闲
+ 空闲 --> 已预订: 创建预订
+ 空闲 --> 维护中: 设置维护
+ 已预订 --> 已入住: 办理入住
+ 已预订 --> 空闲: 取消预订
+ 已入住 --> 待清洁: 办理退房
+ 待清洁 --> 清洁中: 开始清洁
+ 清洁中 --> 空闲: 完成清洁
+ 维护中 --> 空闲: 完成维护
+ }
+
+ state 财务状态 {
+ [*] --> 未结账
+ 未结账 --> 部分支付: 收取定金/押金
+ 部分支付 --> 部分支付: 增加消费
+ 部分支付 --> 已结清: 支付尾款
+ 部分支付 --> 退款中: 申请退款
+ 退款中 --> 已退款: 确认退款
+ 已结清 --> [*]
+ 已退款 --> [*]
+ }
+```
+
+### 5.3 PMS租户核心业务子系统组件图
+
+```mermaid
+flowchart TD
+ subgraph PMS["PMS租户核心业务子系统"]
+ direction TB
+ APILayer["API层 (内部)"]:::internal --> |请求分发| BusinessModules
+
+ subgraph BusinessModules["核心业务模块"]
+ direction TB
+ Room["房态管理"]:::internal
+ Booking["订单管理"]:::internal
+ Finance["财务与支付"]:::internal
+ Guest["联系人与会员 (P1核心)"]:::internal
+ Settings["系统管理 (含门店管理)"]:::internal
+ Reports["报表分析 (P1+)"]:::internal
+
+ Room <--> Booking
+ Booking <--> Finance
+ Booking --> Guest
+ end
+ end
+
+ subgraph AccessLayer["应用访问层 (PMS用户)"]
+ direction LR
+ MiniApp["民宿管理小程序"]:::external
+ WebAdmin["PMS Web管理后台"]:::external
+ end
+
+ AccessLayer --> APILayer
+
+ classDef internal fill:#f0f8ff,stroke:#1890ff,stroke-width:1px
+ classDef external fill:#f5f5f5,stroke:#d9d9d9,stroke-width:1px
+```
+
+## 6. 系统角色与权限概述 (PMS相关用户)
+
+1. **民宿租户管理员 (Tenant Admin):**
+ * 用户实体: 关联到 `sys_user` 表。
+ * 关联: 通过 `sys_user_role` 表关联到租户及相关角色。
+ * 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
+ * 核心职责: 管理其名下一个或多个民宿门店的完整运营,包括房型房间、订单、财务、员工、租户级系统设置等。
+2. **门店管理员 (Store Manager):**
+ * 用户实体: 关联到 `sys_user` 表。
+ * 关联: 通过 `sys_user_role` 表和 `sys_dept` 表关联到特定门店与角色。
+ * 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
+ * 核心职责: 管理特定门店的日常运营。
+3. **民宿前台/员工 (Tenant Staff):**
+ * 用户实体: 关联到 `sys_user` 表。
+ * 关联: 通过 `sys_user_role` 表和 `sys_dept` 表关联到门店及相关角色。
+ * 操作平台: PMS核心后台 (Web), 民宿管理小程序 (Uni-App)。
+ * 核心职责: 根据分配的权限执行日常操作,如订单处理、房态更新、联系人入住退房、账务录入等。
+
+## 7. 实施策略与演进路径 (PMS P0重点)
+
+### 7.1 MVP阶段 (PMS核心功能)
+- **房态管理:** 基础房型、房间定义和日历视图。
+- **订单管理:** 手动录单、接收外部订单(简化接口)、入住、退房基本流程。
+- **财务与支付:** 基础账单 (Folio)、交易流水、手动收款/支付记录。
+- **租户级系统管理:** 员工账号、门店管理、基础设置(房型、房间、基础价格、支付方式、附加消费项目)。
+- **民宿管理小程序:** 房态查看和简单操作(入住/退房)。
+
+## 8. 版本历史
+- v2.8 (原始文档版本) - 本文档基于此裁剪和聚焦。
+- v3.0 (最新版本) - 修改为"部门作为门店"的数据模型,业务表只关联sys_dept。
+
+## 附录 (PMS内部核心实体)
+
+### 附录A 概念性 E-R 图 (PMS核心)
+
+```mermaid
+graph LR
+ sys_tenant(sys_tenant) -->|1..N| sys_dept(Department)
+ sys_dept -->|1..N| pms_core_orders(Order)
+ sys_dept -->|1..N| pms_room_rooms(Room)
+ sys_dept -->|1..N| sys_user(User)
+ sys_dept -->|1..N| pms_tenant_settings(Settings)
+
+ pms_core_orders -->|0..1| cmn_contacts(Contact)
+ pms_core_orders -->|1..N| pms_core_order_items(OrderItem)
+ pms_core_orders -->|1..1| pms_finance_folios(Folio)
+
+ pms_room_rooms -->|1..1| pms_room_types(RoomType)
+
+ pms_finance_folios -->|1..N| pms_finance_transactions(Transaction)
+```
+
+### 附录B 实体关系图 (PMS核心及关联)
+
+```mermaid
+graph LR
+ sys_tenant("sys_tenant") -->|1..N| sys_dept("sys_dept (门店)")
+ sys_dept -->|1..N| pms_core_orders
+ sys_dept -->|1..N| pms_room_rooms
+ sys_dept -->|1..N| sys_user
+
+ sys_user -->|1..N| pms_tenant_user_devices
+ sys_user -->|1..N| sys_user_role
+
+ sys_dept -->|1..N| pms_tenant_settings
+ sys_dept -->|1..N| pms_mp_settings
+ sys_dept -->|1..N| cmn_contacts
+ sys_dept -->|1..N| pms_room_types
+
+ pms_core_orders -->|0..1| cmn_contacts
+ pms_core_orders -->|1..N| pms_core_order_items
+ pms_core_orders -->|1..1| pms_finance_folios
+
+ pms_room_rooms -->|1..1| pms_room_types
+ pms_room_types -->|1..N| pms_room_pricing_rules
+
+ pms_core_order_items -->|0..1| pms_finance_extra_charge_items
+ pms_core_order_items -->|0..1| pms_room_rooms
+
+ pms_finance_folios -->|1..N| pms_finance_transactions
+
+ pms_finance_transactions -->|0..1| pms_finance_payment_methods
+```
diff --git a/docs/二开todolist.md b/docs/二开todolist.md
new file mode 100644
index 000000000..7b68df63a
--- /dev/null
+++ b/docs/二开todolist.md
@@ -0,0 +1,288 @@
+# PMS 模块二次开发 ToDoList
+
+## 阶段 0: 项目初始化与理解
+
+- [x] **阅读核心文档:**
+ - [x] 仔细阅读《PMS数据模型.md》,完全理解PMS核心表的结构、字段定义、关系以及主键/外键/索引规范。
+ - [x] 仔细阅读《PMS需求.md》,明确PMS核心模块 [P0] 阶段必须实现的功能需求(房态、订单核心生命周期、基础财务支付、租户级系统管理基础)。
+ - [x] 通读《RuoYi-Vue-Plus二次开发最佳实践.md》,重点关注以下章节:
+ - Chapter 1: 引言 (文档目的, 模块化特性, **二次开发核心原则**, **Cursor使用优势**)
+ - Chapter 2: 环境准备与项目结构 (前后端环境, **前后端项目结构**, **代码生成器与Cursor协同**)
+ - Chapter 3: 模块深入分析 (用户管理模块的启示)
+ - Chapter 4: 后端开发最佳实践 (Cursor辅助技巧, 模块设计, 分层约定, Domain对象规范)
+ - Chapter 5: 前端开发最佳实践 (Cursor辅助技巧, 项目结构, 功能模块开发规范, 组件案例, 前后端交互)
+ - Chapter 6: 前后端协作规范
+ - Chapter 7: 代码规范与风格
+ - Chapter 8: 新模块添加流程与实践
+- [x] **环境与工具准备:**
+ - [x] 确保后端开发环境 (JDK, Maven, Redis, MySQL) 符合《最佳实践》Chapter 2.1 要求。
+ - [x] 确保前端开发环境 (Node.js, pnpm) 符合《最佳实践》Chapter 2.1 要求。
+ - [x] 安装并配置好 Cursor IDE,将整个 `ruoyi-vue-plus` 项目导入工作区。
+ - [x] (可选)在 Cursor 中为项目设置特定上下文,如关键模块路径、技术栈等,以便更好地辅助开发。
+
+## 阶段 1: 后端开发 - 模块搭建与核心表结构
+
+- [ ] **创建后端Maven子模块 `ruoyi-pms`** (参考《最佳实践》Chapter 2.2, 4.2, 8.3):
+ - [ ] 在 `ruoyi-vue-plus/ruoyi-modules` 目录下创建新的 Maven 子模块 `ruoyi-pms`。
+ - [ ] 配置 `ruoyi-pms/pom.xml`:
+ - [ ] 设置 `` 指向 `ruoyi-modules`。
+ - [ ] 添加必要的公共模块依赖 (如: `ruoyi-common-core`, `ruoyi-common-mybatis`, `ruoyi-common-web`, `ruoyi-common-satoken`, `ruoyi-common-excel`, `ruoyi-common-translate`, `ruoyi-common-tenant`)。
+ - [ ] 在项目根目录 `pom.xml` 和 `ruoyi-modules/pom.xml` 的 `` 部分注册 `ruoyi-pms`。
+- [ ] **创建后端基础包结构** (参考《最佳实践》Chapter 4.2):
+ - [ ] 在 `ruoyi-pms/src/main/java/` 下创建基础包,例如 `org.dromara.pms`。
+ - [ ] 在 `org.dromara.pms` 下创建标准分层包:`controller`, `service`, `service.impl`, `mapper`, `domain` (包含 `entity`, `bo`, `vo`)。
+- [ ] **数据库表创建与初始化**:
+ - [ ] **执行SQL脚本**: 确保已在开发数据库中执行 `script/sql/pms_tables.sql` 文件,创建所有PMS相关的表。
+ - [ ] **验证表结构**: 对照《PMS数据模型.md》仔细检查已创建的表结构、字段类型、约束、索引是否正确。
+ - [ ] **验证基础数据**: 确认 `pms_core_channels` 和 `pms_finance_payment_methods` 表的基础数据已按 `pms_tables.sql` 中的`INSERT`语句正确插入。
+- [ ] **集成新模块到系统**:
+ - [ ] (如果需要)在 `ruoyi-admin` 模块的 `application.yml` 中,确保新模块的包路径 (如 `org.dromara.pms`) 被扫描到。
+ - [ ] (如果需要)配置MyBatis Plus扫描新模块的Mapper XML文件路径。
+- [ ] **后端国际化资源文件**:
+ - [ ] 在 `ruoyi-pms/src/main/resources/` 下创建 `i18n` 目录。
+ - [ ] 在 `i18n` 目录下创建基础的国际化属性文件,如 `messages_zh_CN.properties` 和 `messages_en_US.properties`。
+
+## 阶段 2: 后端开发 - 核心业务功能 [P0]
+
+**通用后端开发规范 (参考《最佳实践》Chapter 4 & 7.1):**
+ - [ ] 遵循分层架构约定 (Controller -> Service -> Mapper)。
+ - [ ] 严格区分 Entity, BO, VO 的职责和使用场景。
+ - [ ] 使用 MapStruct Plus (`@AutoMapper`) 进行对象转换。
+ - [ ] Service 层实现类的方法应添加 `@Transactional` 注解。
+ - [ ] Controller 层方法应添加 `@Log` 操作日志注解和 `@SaCheckPermission` 权限注解。
+ - [ ] BO 对象字段使用 JSR 303/380 注解进行参数校验。
+ - [ ] VO 对象字段按需使用 `@Translation` 和 `@Sensitive` 注解。
+ - [ ] 编写清晰的 Javadoc 注释和行内注释。
+ - [ ] 使用 Cursor 辅助生成代码、分析逻辑、优化代码。
+
+**具体功能模块开发:**
+
+- [ ] **代码生成器应用 (可选但推荐)** (参考《最佳实践》Chapter 2.4):
+ - [ ] 针对《PMS数据模型.md》中定义的核心表 (如 `pms_room_types`, `pms_room_rooms`, `pms_core_orders` 等),使用若依代码生成器生成初始的 Entity, Mapper, Service, Controller, BO, VO。
+ - [ ] **Cursor辅助**: "请Cursor分析代码生成器为 `pms_room_types` 表生成的后端代码,并指出哪些部分需要根据《PMS需求.md》和《最佳实践》进行调整。"
+
+- [ ] **1. 房型管理 (`pms_room_types`)**:
+ - [ ] **Domain**: 创建/调整 `PmsRoomType`, `PmsRoomTypeBo`, `PmsRoomTypeVo`。
+ - [ ] **Mapper**: 创建/调整 `PmsRoomTypeMapper.java` 和对应的 `PmsRoomTypeMapper.xml`。
+ - [ ] **Service**: 创建/调整 `IPmsRoomTypeService.java` 和 `PmsRoomTypeServiceImpl.java` (实现CRUD逻辑)。
+ - [ ] **Controller**: 创建/调整 `PmsRoomTypeController.java` (暴露RESTful API)。
+
+- [ ] **2. 房间管理 (`pms_room_rooms`)**:
+ - [ ] **Domain**: `PmsRoomRoom`, `PmsRoomRoomBo`, `PmsRoomRoomVo`.
+ - [ ] **Mapper**: `PmsRoomRoomMapper.java` & XML.
+ - [ ] **Service**: `IPmsRoomRoomService.java` & Impl (CRUD, 更新房间状态/清洁状态逻辑).
+ - [ ] **Controller**: `PmsRoomRoomController.java`.
+
+- [ ] **3. 房间锁定 (`pms_room_locks`)**:
+ - [ ] **Domain**: `PmsRoomLock`, `PmsRoomLockBo`, `PmsRoomLockVo`.
+ - [ ] **Mapper**: `PmsRoomLockMapper.java` & XML.
+ - [ ] **Service**: `IPmsRoomLockService.java` & Impl (CRUD).
+ - [ ] **Controller**: `PmsRoomLockController.java`.
+
+- [ ] **4. 核心订单管理 (`pms_core_orders`, `pms_core_order_items`)** (参考《PMS需求.md》4.2.2 [P0]):
+ - [ ] **Domain**:
+ - `PmsCoreOrder`, `PmsCoreOrderBo`, `PmsCoreOrderVo` (应包含订单项列表).
+ - `PmsCoreOrderItem`, `PmsCoreOrderItemBo`, `PmsCoreOrderItemVo`.
+ - [ ] **Mapper**: `PmsCoreOrderMapper`, `PmsCoreOrderItemMapper` & XMLs.
+ - [ ] **Service**: `IPmsCoreOrderService`, `IPmsCoreOrderItemService` & Impls (实现订单创建、查询、修改、取消、状态流转核心逻辑;订单项增删改查).
+ - [ ] 实现订单状态转换逻辑 (pending_confirmation -> confirmed -> checked_in -> checked_out / cancelled / no_show).
+ - [ ] 订单创建时关联/创建 `cmn_contacts` (基础字段)。
+ - [ ] 订单创建时关联 `pms_core_channels`。
+ - [ ] 订单创建/确认时,自动创建或关联 `pms_finance_folios`。
+ - [ ] **Controller**: `PmsCoreOrderController`.
+
+- [ ] **5. 订单来源渠道 (`pms_core_channels`)**:
+ - [ ] **Domain**: `PmsCoreChannel`, `PmsCoreChannelBo`, `PmsCoreChannelVo`.
+ - [ ] **Mapper**: `PmsCoreChannelMapper` & XML.
+ - [ ] **Service**: `IPmsCoreChannelService` & Impl (CRUD).
+ - [ ] **Controller**: `PmsCoreChannelController`.
+
+- [ ] **6. 财务-账单管理 (`pms_finance_folios`)** (参考《PMS需求.md》4.2.3 [P0]):
+ - [ ] **Domain**: `PmsFinanceFolio`, `PmsFinanceFolioBo`, `PmsFinanceFolioVo` (应包含交易流水列表).
+ - [ ] **Mapper**: `PmsFinanceFolioMapper` & XML.
+ - [ ] **Service**: `IPmsFinanceFolioService` & Impl (CRUD, 更新账单状态, 计算余额逻辑 - 应用层计算).
+ - [ ] **Controller**: `PmsFinanceFolioController`.
+
+- [ ] **7. 财务-交易流水 (`pms_finance_transactions`)**:
+ - [ ] **Domain**: `PmsFinanceTransaction`, `PmsFinanceTransactionBo`, `PmsFinanceTransactionVo`.
+ - [ ] **Mapper**: `PmsFinanceTransactionMapper` & XML.
+ - [ ] **Service**: `IPmsFinanceTransactionService` & Impl (CRUD, 关联 `pms_finance_payment_methods`).
+ - [ ] **Controller**: `PmsFinanceTransactionController`.
+
+- [ ] **8. 财务-支付方式 (`pms_finance_payment_methods`)**:
+ - [ ] **Domain**: `PmsFinancePaymentMethod`, `PmsFinancePaymentMethodBo`, `PmsFinancePaymentMethodVo`.
+ - [ ] **Mapper**: `PmsFinancePaymentMethodMapper` & XML.
+ - [ ] **Service**: `IPmsFinancePaymentMethodService` & Impl (CRUD).
+ - [ ] **Controller**: `PmsFinancePaymentMethodController`.
+
+- [ ] **9. 财务-附加费用项目 (`pms_finance_extra_charge_items`)**:
+ - [ ] **Domain**: `PmsFinanceExtraChargeItem`, `PmsFinanceExtraChargeItemBo`, `PmsFinanceExtraChargeItemVo`.
+ - [ ] **Mapper**: `PmsFinanceExtraChargeItemMapper` & XML.
+ - [ ] **Service**: `IPmsFinanceExtraChargeItemService` & Impl (CRUD).
+ - [ ] **Controller**: `PmsFinanceExtraChargeItemController`.
+
+- [ ] **10. 价格规则 (`pms_room_pricing_rules`)**:
+ - [ ] **Domain**: `PmsRoomPricingRule`, `PmsRoomPricingRuleBo`, `PmsRoomPricingRuleVo`.
+ - [ ] **Mapper**: `PmsRoomPricingRuleMapper` & XML.
+ - [ ] **Service**: `IPmsRoomPricingRuleService` & Impl (CRUD).
+ - [ ] **Controller**: `PmsRoomPricingRuleController`.
+
+- [ ] **11. 联系人基础 (`cmn_contacts`)** (P0阶段主要为订单关联所需字段):
+ - [ ] **Domain**: `CmnContact`, `CmnContactBo`, `CmnContactVo` (仅包含P0阶段所需字段,如姓名、电话).
+ - [ ] **Mapper**: `CmnContactMapper` & XML.
+ - [ ] **Service**: `ICmnContactService` & Impl (提供基础的联系人查询、创建接口供订单模块调用).
+ - [ ] **Controller**: (P0阶段可能不需要完整独立的Controller,主要通过订单业务间接操作).
+
+- [ ] **12. 租户/部门特定配置 (`pms_tenant_settings`, `pms_mp_settings`)**:
+ - [ ] **Domain**: `PmsTenantSetting`, `PmsTenantSettingBo`, `PmsTenantSettingVo` & 类似的 `PmsMpSetting` 对象.
+ - [ ] **Mapper**: `PmsTenantSettingMapper`, `PmsMpSettingMapper` & XMLs.
+ - [ ] **Service**: `IPmsTenantSettingService`, `IPmsMpSettingService` & Impls (CRUD, 按 group/key 查询).
+ - [ ] **Controller**: `PmsTenantSettingController`, `PmsMpSettingController`.
+
+- [ ] **13. 租户用户设备 (`pms_tenant_user_devices`)**: (用于民宿管理小程序推送等)
+ - [ ] **Domain**: `PmsTenantUserDevice`, `PmsTenantUserDeviceBo`, `PmsTenantUserDeviceVo`.
+ - [ ] **Mapper**: `PmsTenantUserDeviceMapper` & XML.
+ - [ ] **Service**: `IPmsTenantUserDeviceService` & Impl (CRUD, 设备注册/更新逻辑).
+ - [ ] **Controller**: `PmsTenantUserDeviceController`.
+
+- [ ] **API文档**:
+ - [ ] 为所有Controller和DTO添加清晰的Swagger/Knife4j注解 (参考《最佳实践》Chapter 8.3)。
+
+## 阶段 3: 前端开发 - 核心管理界面 [P0] (Soybean Admin Pro)
+
+**通用前端开发规范 (参考《最佳实践》Chapter 5 & 7.2):**
+ - [ ] 遵循 Soybean Admin Pro 的项目结构和编码规范。
+ - [ ] 使用 Vue 3 Composition API + `
diff --git a/ruoyi-modules/ruoyi-generator/src/main/resources/vm/vue/index.vue.vm b/ruoyi-modules/ruoyi-generator/src/main/resources/vm/vue/index.vue.vm
new file mode 100644
index 000000000..a92d19adc
--- /dev/null
+++ b/ruoyi-modules/ruoyi-generator/src/main/resources/vm/vue/index.vue.vm
@@ -0,0 +1,459 @@
+
+
+
+
+
+
+#foreach($column in $columns)
+#if($column.query)
+#set($dictType=$column.dictType)
+#set($AttrName=$column.javaField.substring(0,1).toUpperCase() + ${column.javaField.substring(1)})
+#set($parentheseIndex=$column.columnComment.indexOf("("))
+#if($parentheseIndex != -1)
+#set($comment=$column.columnComment.substring(0, $parentheseIndex))
+#else
+#set($comment=$column.columnComment)
+#end
+#if($column.htmlType == "input" || $column.htmlType == "textarea")
+
+
+
+#elseif(($column.htmlType == "select" || $column.htmlType == "radio") && "" != $dictType)
+
+
+
+
+
+#elseif(($column.htmlType == "select" || $column.htmlType == "radio") && $dictType)
+
+
+
+
+
+#elseif($column.htmlType == "datetime" && $column.queryType != "BETWEEN")
+
+
+
+#elseif($column.htmlType == "datetime" && $column.queryType == "BETWEEN")
+
+
+
+#end
+#end
+#end
+
+ 搜索
+ 重置
+
+
+
+
+
+
+
+
+
+
+ 新增
+
+
+ 修改
+
+
+ 删除
+
+
+ 导出
+
+
+
+
+
+
+
+#foreach($column in $columns)
+#set($javaField=$column.javaField)
+#set($parentheseIndex=$column.columnComment.indexOf("("))
+#if($parentheseIndex != -1)
+#set($comment=$column.columnComment.substring(0, $parentheseIndex))
+#else
+#set($comment=$column.columnComment)
+#end
+#if($column.pk)
+
+#elseif($column.list && $column.htmlType == "datetime")
+
+
+ {{ parseTime(scope.row.${javaField}, '{y}-{m}-{d}') }}
+
+
+#elseif($column.list && $column.htmlType == "imageUpload")
+
+
+
+
+
+#elseif($column.list && $column.dictType && "" != $column.dictType)
+
+
+#if($column.htmlType == "checkbox")
+
+#else
+
+#end
+
+
+#elseif($column.list && "" != $javaField)
+
+#end
+#end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#foreach($column in $columns)
+#set($field=$column.javaField)
+#if(($column.insert || $column.edit) && !$column.pk)
+#set($parentheseIndex=$column.columnComment.indexOf("("))
+#if($parentheseIndex != -1)
+#set($comment=$column.columnComment.substring(0, $parentheseIndex))
+#else
+#set($comment=$column.columnComment)
+#end
+#set($dictType=$column.dictType)
+#if($column.htmlType == "input")
+
+
+
+#elseif($column.htmlType == "imageUpload")
+
+
+
+#elseif($column.htmlType == "fileUpload")
+
+
+
+#elseif($column.htmlType == "editor")
+
+
+
+#elseif($column.htmlType == "select" && "" != $dictType)
+
+
+
+
+
+#elseif($column.htmlType == "select" && $dictType)
+
+
+
+
+
+#elseif($column.htmlType == "checkbox" && "" != $dictType)
+
+
+
+ {{dict.label}}
+
+
+
+#elseif($column.htmlType == "checkbox" && $dictType)
+
+
+ 请选择字典生成
+
+
+#elseif($column.htmlType == "radio" && "" != $dictType)
+
+
+ {{dict.label}}
+
+
+#elseif($column.htmlType == "radio" && $dictType)
+
+
+ 请选择字典生成
+
+
+#elseif($column.htmlType == "datetime")
+
+
+
+
+#elseif($column.htmlType == "textarea")
+
+
+
+#end
+#end
+#end
+
+
+
+
+
+
+
+
+
diff --git a/ruoyi-modules/ruoyi-generator/src/main/resources/vm/xml/mapper.xml.vm b/ruoyi-modules/ruoyi-generator/src/main/resources/vm/xml/mapper.xml.vm
new file mode 100644
index 000000000..9fb48d991
--- /dev/null
+++ b/ruoyi-modules/ruoyi-generator/src/main/resources/vm/xml/mapper.xml.vm
@@ -0,0 +1,7 @@
+
+
+
+
+
diff --git a/ruoyi-modules/ruoyi-job/pom.xml b/ruoyi-modules/ruoyi-job/pom.xml
new file mode 100644
index 000000000..2431a1ce8
--- /dev/null
+++ b/ruoyi-modules/ruoyi-job/pom.xml
@@ -0,0 +1,34 @@
+
+
+
+ org.dromara
+ ruoyi-modules
+ ${revision}
+
+ 4.0.0
+ jar
+ ruoyi-job
+
+
+ 任务调度
+
+
+
+
+
+
+ org.dromara
+ ruoyi-common-json
+
+
+
+ org.dromara
+ ruoyi-common-job
+
+
+
+
+
+
diff --git a/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/package-info.java b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/package-info.java
new file mode 100644
index 000000000..2f118b071
--- /dev/null
+++ b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/package-info.java
@@ -0,0 +1 @@
+package org.dromara.job;
diff --git a/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestAnnoJobExecutor.java b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestAnnoJobExecutor.java
new file mode 100644
index 000000000..5bea9daf3
--- /dev/null
+++ b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestAnnoJobExecutor.java
@@ -0,0 +1,23 @@
+package org.dromara.job.snailjob;
+
+import com.aizuda.snailjob.client.job.core.annotation.JobExecutor;
+import com.aizuda.snailjob.client.job.core.dto.JobArgs;
+import com.aizuda.snailjob.client.model.ExecuteResult;
+import com.aizuda.snailjob.common.core.util.JsonUtil;
+import com.aizuda.snailjob.common.log.SnailJobLog;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author opensnail
+ * @date 2024-05-17
+ */
+@Component
+@JobExecutor(name = "testJobExecutor")
+public class TestAnnoJobExecutor {
+
+ public ExecuteResult jobExecute(JobArgs jobArgs) {
+ SnailJobLog.LOCAL.info("testJobExecutor. jobArgs:{}", JsonUtil.toJsonString(jobArgs));
+ SnailJobLog.REMOTE.info("testJobExecutor. jobArgs:{}", JsonUtil.toJsonString(jobArgs));
+ return ExecuteResult.success("测试成功");
+ }
+}
diff --git a/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestClassJobExecutor.java b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestClassJobExecutor.java
new file mode 100644
index 000000000..6f7c21fb6
--- /dev/null
+++ b/ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestClassJobExecutor.java
@@ -0,0 +1,19 @@
+package org.dromara.job.snailjob;
+
+import com.aizuda.snailjob.client.job.core.dto.JobArgs;
+import com.aizuda.snailjob.client.job.core.executor.AbstractJobExecutor;
+import com.aizuda.snailjob.client.model.ExecuteResult;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author opensnail
+ * @date 2024-05-17
+ */
+@Component
+public class TestClassJobExecutor extends AbstractJobExecutor {
+
+ @Override
+ protected ExecuteResult doJobExecute(JobArgs jobArgs) {
+ return ExecuteResult.success("TestJobExecutor测试成功");
+ }
+}
diff --git a/ruoyi-modules/ruoyi-pms/pom.xml b/ruoyi-modules/ruoyi-pms/pom.xml
new file mode 100644
index 000000000..46222f400
--- /dev/null
+++ b/ruoyi-modules/ruoyi-pms/pom.xml
@@ -0,0 +1,66 @@
+
+
+
+ org.dromara
+ ruoyi-modules
+ ${revision}
+
+ 4.0.0
+
+ ruoyi-pms
+
+
+ 民宿管理系统(Property Management System)模块
+
+
+
+
+
+ org.dromara
+ ruoyi-common-core
+
+
+
+ org.dromara
+ ruoyi-common-mybatis
+
+
+
+ org.dromara
+ ruoyi-common-web
+
+
+
+ org.dromara
+ ruoyi-common-satoken
+
+
+
+ org.dromara
+ ruoyi-common-excel
+
+
+
+ org.dromara
+ ruoyi-common-translation
+
+
+
+ org.dromara
+ ruoyi-common-tenant
+
+
+
+ org.dromara
+ ruoyi-common-log
+
+
+
+ org.dromara
+ ruoyi-common-redis
+
+
+
+
diff --git a/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_en_US.properties b/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_en_US.properties
new file mode 100644
index 000000000..000c22efa
--- /dev/null
+++ b/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_en_US.properties
@@ -0,0 +1,48 @@
+# PMS module internationalization messages - English
+pms.title=Property Management System
+pms.description=Property Management System
+
+# Room Type
+pms.room.type=Room Type
+pms.room.type.id=Room Type ID
+pms.room.type.name=Room Type Name
+pms.room.type.default.price=Default Price
+pms.room.type.capacity=Standard Capacity
+pms.room.type.amenities=Amenities
+pms.room.type.description=Description
+pms.room.type.images=Images
+pms.room.type.status=Status
+
+# Room
+pms.room=Room
+pms.room.id=Room ID
+pms.room.number=Room Number
+pms.room.floor=Floor
+pms.room.status=Room Status
+pms.room.status.available=Available
+pms.room.status.occupied=Occupied
+pms.room.status.maintenance=Maintenance
+pms.room.status.out_of_service=Out of Service
+pms.room.cleaning.status=Cleaning Status
+pms.room.cleaning.status.clean=Clean
+pms.room.cleaning.status.dirty=Dirty
+pms.room.cleaning.status.cleaning_in_progress=Cleaning in Progress
+pms.room.cleaning.status.inspected=Inspected
+
+# Order
+pms.order=Order
+pms.order.id=Order ID
+pms.order.contact=Contact
+pms.order.room=Room
+pms.order.room.type=Room Type
+pms.order.check.in.date=Check-in Date
+pms.order.check.out.date=Check-out Date
+pms.order.amount=Amount
+pms.order.status=Order Status
+pms.order.status.pending_confirmation=Pending Confirmation
+pms.order.status.confirmed=Confirmed
+pms.order.status.checked_in=Checked In
+pms.order.status.checked_out=Checked Out
+pms.order.status.cancelled=Cancelled
+pms.order.status.no_show=No Show
+pms.order.source=Order Source
diff --git a/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_zh_CN.properties b/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_zh_CN.properties
new file mode 100644
index 000000000..3007856f8
--- /dev/null
+++ b/ruoyi-modules/ruoyi-pms/src/main/resources/i18n/messages_zh_CN.properties
@@ -0,0 +1,48 @@
+# PMS模块相关的国际化消息 - 中文
+pms.title=民宿管理系统
+pms.description=民宿管理系统(Property Management System)
+
+# 房型相关
+pms.room.type=房型
+pms.room.type.id=房型ID
+pms.room.type.name=房型名称
+pms.room.type.default.price=默认价格
+pms.room.type.capacity=标准入住人数
+pms.room.type.amenities=房型设施
+pms.room.type.description=房型描述
+pms.room.type.images=房型图片
+pms.room.type.status=状态
+
+# 房间相关
+pms.room=房间
+pms.room.id=房间ID
+pms.room.number=房间号
+pms.room.floor=楼层
+pms.room.status=房间状态
+pms.room.status.available=可用
+pms.room.status.occupied=占用中
+pms.room.status.maintenance=维护中
+pms.room.status.out_of_service=停用服务
+pms.room.cleaning.status=清洁状态
+pms.room.cleaning.status.clean=已清洁
+pms.room.cleaning.status.dirty=待清洁
+pms.room.cleaning.status.cleaning_in_progress=清洁中
+pms.room.cleaning.status.inspected=已查房
+
+# 订单相关
+pms.order=订单
+pms.order.id=订单ID
+pms.order.contact=联系人
+pms.order.room=房间
+pms.order.room.type=房型
+pms.order.check.in.date=入住日期
+pms.order.check.out.date=离店日期
+pms.order.amount=订单金额
+pms.order.status=订单状态
+pms.order.status.pending_confirmation=待确认
+pms.order.status.confirmed=已确认
+pms.order.status.checked_in=已入住
+pms.order.status.checked_out=已退房
+pms.order.status.cancelled=已取消
+pms.order.status.no_show=未到店
+pms.order.source=订单来源
diff --git a/ruoyi-modules/ruoyi-system/pom.xml b/ruoyi-modules/ruoyi-system/pom.xml
new file mode 100644
index 000000000..0fc6d5513
--- /dev/null
+++ b/ruoyi-modules/ruoyi-system/pom.xml
@@ -0,0 +1,105 @@
+
+
+
+ org.dromara
+ ruoyi-modules
+ ${revision}
+
+ 4.0.0
+
+ ruoyi-system
+
+
+ system系统模块
+
+
+
+
+
+ org.dromara
+ ruoyi-common-core
+
+
+
+ org.dromara
+ ruoyi-common-doc
+
+
+
+ org.dromara
+ ruoyi-common-mybatis
+
+
+
+ org.dromara
+ ruoyi-common-translation
+
+
+
+
+ org.dromara
+ ruoyi-common-oss
+
+
+
+ org.dromara
+ ruoyi-common-log
+
+
+
+
+ org.dromara
+ ruoyi-common-excel
+
+
+
+
+ org.dromara
+ ruoyi-common-sms
+
+
+
+ org.dromara
+ ruoyi-common-tenant
+
+
+
+ org.dromara
+ ruoyi-common-security
+
+
+
+ org.dromara
+ ruoyi-common-web
+
+
+
+ org.dromara
+ ruoyi-common-idempotent
+
+
+
+ org.dromara
+ ruoyi-common-sensitive
+
+
+
+ org.dromara
+ ruoyi-common-encrypt
+
+
+
+ org.dromara
+ ruoyi-common-websocket
+
+
+
+ org.dromara
+ ruoyi-common-sse
+
+
+
+
+
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/CacheController.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/CacheController.java
new file mode 100644
index 000000000..6b7499ace
--- /dev/null
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/CacheController.java
@@ -0,0 +1,55 @@
+package org.dromara.system.controller.monitor;
+
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import org.dromara.common.core.domain.R;
+import org.dromara.common.core.utils.StringUtils;
+import org.dromara.system.domain.vo.CacheListInfoVo;
+import lombok.RequiredArgsConstructor;
+import org.redisson.spring.data.connection.RedissonConnectionFactory;
+import org.springframework.data.redis.connection.RedisConnection;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.*;
+
+/**
+ * 缓存监控
+ *
+ * @author Lion Li
+ */
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/monitor/cache")
+public class CacheController {
+
+ private final RedissonConnectionFactory connectionFactory;
+
+ /**
+ * 获取缓存监控列表
+ */
+ @SaCheckPermission("monitor:cache:list")
+ @GetMapping()
+ public R getInfo() throws Exception {
+ RedisConnection connection = connectionFactory.getConnection();
+ Properties commandStats = connection.commands().info("commandstats");
+
+ List