feat: 完善数据库表命名规范，新增后勤管理和系统公共模块前缀

📋 主要变更： - ✅ 补充完整的7个业务模块表命名规范 - ✅ 新增后勤管理模块：hq_ 前缀 - ✅ 明确系统公共模块：common_ 前缀 - ✅ 提供完整的命名示例和实体类映射规则 - ✅ 更新变更记录文档 🎯 覆盖模块： - 后勤管理(hq_)、人事管理(rs_)、财务管理(cw_) - 学工管理(xg_)、招生就业(zsjy_)、安全保卫(aqbw_) - 系统公共(common_) 📚 文件变更： - .cursor/cursorrules-backend.md - 数据库表命名规范 - docs/变更管理/code-adjust-record-2025-01-23-wuzilong.md - 变更记录 - 各业务模块工程文件和前端结构文件 Co-authored-by: Cursor AI <cursor@cursor.sh>
2025-07-08 14:11:12 +08:00
1 parent 00297e714b
commit 90b13a6e0c
@@ -40,11 +40,262 @@ backend/
 ├── ruoyi-modules/        # 业务模块组
 │   ├── ruoyi-system/     # 系统管理模块
 │   ├── ruoyi-demo/       # 示例模块
+│   ├── ruoyi-hq/         # 后勤管理模块 (hq)
+│   ├── ruoyi-rs/         # 人事管理模块 (rs)
+│   ├── ruoyi-cw/         # 财务管理模块 (cw)
+│   ├── ruoyi-aqbw/       # 安全保卫管理模块 (aqbw)
+│   ├── ruoyi-zsjy/       # 招生就业管理模块 (zsjy)
+│   ├── ruoyi-xg/         # 学工管理模块 (xg)
 │   └── ... (其他业务模块)
 ├── ruoyi-extend/         # 扩展模块组
 └── script/               # 脚本和SQL
 ```

+## 🔴 模块工程管理规范（强制性，2025-01-23新增）
+
+### 📦 模块工程创建规范
+
+**⚠️ 基于ruoyi-hq工程实践制定，后续所有新模块必须遵循此规范！**
+
+#### 🏗️ 模块命名和位置规范
+
+**模块位置**: `backend/ruoyi-modules/ruoyi-{模块简称}/`
+
+**已规划模块列表**:
+- ✅ `ruoyi-hq` - 后勤管理模块 (已完成)
+- 🚧 `ruoyi-rs` - 人事管理模块
+- 🚧 `ruoyi-cw` - 财务管理模块  
+- 🚧 `ruoyi-aqbw` - 安全保卫管理模块
+- 🚧 `ruoyi-zsjy` - 招生就业管理模块
+- 🚧 `ruoyi-xg` - 学工管理模块
+
+#### 📋 Maven配置规范
+
+**pom.xml标准模板**:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>ruoyi-modules</artifactId>
+        <groupId>org.dromara</groupId>
+        <version>${revision}</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>ruoyi-{模块简称}</artifactId>
+    <description>
+        {模块名称}管理模块
+    </description>
+
+    <dependencies>
+        <!-- 通用工具 -->
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-doc</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-mybatis</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-log</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-security</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-excel</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-idempotent</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-tenant</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-social</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-ratelimiter</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-common-mail</artifactId>
+        </dependency>
+
+        <!-- 系统模块依赖 -->
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-system</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-job</artifactId>
+        </dependency>
+
+        <!-- 代码生成-->
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-generator</artifactId>
+        </dependency>
+
+        <!--  demo模块  -->
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-demo</artifactId>
+        </dependency>
+
+        <!--  工作流模块  -->
+        <dependency>
+            <groupId>org.dromara</groupId>
+            <artifactId>ruoyi-workflow</artifactId>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+#### 🏛️ 包结构规范
+
+**Java包结构**: `org.dromara.{模块简称}`
+
+**标准目录结构**:
+```
+ruoyi-{模块简称}/
+├── pom.xml
+└── src/main/
+    ├── java/org/dromara/{模块简称}/
+    │   ├── controller/              # REST API控制器层
+    │   ├── service/                 # 业务服务接口层
+    │   │   └── impl/               # 业务服务实现层
+    │   ├── mapper/                 # 数据访问层接口
+    │   └── domain/                 # 数据对象层
+    │       ├── [Entity].java       # 实体类 (继承TenantEntity)
+    │       ├── bo/                 # 业务对象 (Business Object)
+    │       └── vo/                 # 视图对象 (View Object)
+    └── resources/
+        └── mapper/                 # MyBatis XML映射文件
+```
+
+#### 🎯 代码规范要求
+
+**Entity实体类**:
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("表名")
+public class EntityName extends TenantEntity {
+    @Serial
+    private static final long serialVersionUID = 1L;
+    
+    @TableId(value = "id")
+    private Long id;
+    
+    // 业务字段...
+}
+```
+
+**Service接口**:
+```java
+public interface IEntityService {
+    EntityVo queryById(Long id);
+    TableDataInfo<EntityVo> queryPageList(EntityBo bo, PageQuery pageQuery);
+    List<EntityVo> queryList(EntityBo bo);
+    Boolean insertByBo(EntityBo bo);
+    Boolean updateByBo(EntityBo bo);
+    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
+}
+```
+
+**Controller控制器**:
+```java
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/{模块简称}/entity")
+public class EntityController extends BaseController {
+    
+    private final IEntityService entityService;
+    
+    @SaCheckPermission("{模块简称}:entity:list")
+    @GetMapping("/list")
+    public TableDataInfo<EntityVo> list(EntityBo bo, PageQuery pageQuery) {
+        return entityService.queryPageList(bo, pageQuery);
+    }
+    
+    // 其他标准接口...
+}
+```
+
+**Mapper接口**:
+```java
+public interface EntityMapper extends BaseMapperPlus<Entity, EntityVo> {
+    // 自定义查询方法...
+}
+```
+
+#### 🔐 权限命名规范
+
+**权限编码格式**: `{模块简称}:{功能}:{操作}`
+
+**示例**:
+- `hq:repair:list` - 后勤模块报修列表查询权限
+- `rs:employee:add` - 人事模块员工新增权限
+- `cw:budget:export` - 财务模块预算导出权限
+
+#### 📚 模块开发最佳实践
+
+**1. 遵循ruoyi-hq标准模式**:
+- 继承TenantEntity支持多租户
+- 使用@SaCheckPermission进行权限控制
+- 遵循TableDataInfo分页响应格式
+- 使用MapstructUtils进行对象转换
+
+**2. 代码质量要求**:
+- 使用Lombok减少样板代码
+- 完整的中文注释和文档
+- 统一的异常处理机制
+- 完善的参数校验
+
+**3. 模块间解耦**:
+- 模块间通过Service接口交互
+- 避免直接依赖其他模块的内部实现
+- 共用功能提取到common模块
+
+**4. 数据库设计**:
+- 必须遵循数据库规范基础字段
+- 支持逻辑删除和多租户
+- 合理的索引设计
+- 完整的数据字典配置
+
+#### 🚨 模块创建检查清单
+
+**创建新模块前必须检查**:
+- [ ] 模块名称符合规范？(`ruoyi-{简称}`)
+- [ ] Maven配置是否正确？
+- [ ] 包结构是否遵循标准？
+- [ ] 是否包含完整的分层架构？
+- [ ] 权限编码是否符合规范？
+- [ ] 是否遵循ruoyi-hq的最佳实践？
+- [ ] 数据库设计是否符合规范？
+- [ ] 是否添加了相关文档？
+
 ## 3. 开发规范

 ### 代码规范
@@ -71,6 +322,93 @@ backend/
 5. **完整的中文注释是必须的**
 6. **禁止使用数据库外键约束**，关联关系通过应用层维护

+#### 🔴 表命名规范（强制性）
+
+**⚠️ 超级重要：所有数据库表必须按业务模块使用统一前缀命名！**
+
+**模块表名前缀规范**：
+- **后勤管理**：`hq_` 开头 (如：`hq_repair`, `hq_maintenance`)
+- **人事管理**：`rs_` 开头 (如：`rs_employee`, `rs_department`)
+- **财务管理**：`cw_` 开头 (如：`cw_budget`, `cw_expense`)
+- **学工管理**：`xg_` 开头 (如：`xg_student`, `xg_dormitory`)
+- **招生就业**：`zsjy_` 开头 (如：`zsjy_application`, `zsjy_job`)
+- **安全保卫**：`aqbw_` 开头 (如：`aqbw_security`, `aqbw_patrol`)
+- **系统公共**：`common_` 开头 (如：`common_dict`, `common_config`)
+
+**命名示例**：
+```sql
+-- 后勤管理模块表
+CREATE TABLE `hq_repair` (
+    `id` bigint(20) NOT NULL COMMENT '报修ID',
+    -- 其他字段...
+) COMMENT='报修管理表';
+
+-- 人事管理模块表
+CREATE TABLE `rs_employee` (
+    `id` bigint(20) NOT NULL COMMENT '员工ID',
+    -- 其他字段...
+) COMMENT='员工信息表';
+
+-- 财务管理模块表
+CREATE TABLE `cw_budget` (
+    `id` bigint(20) NOT NULL COMMENT '预算ID',
+    -- 其他字段...
+) COMMENT='预算管理表';
+
+-- 学工管理模块表
+CREATE TABLE `xg_student` (
+    `id` bigint(20) NOT NULL COMMENT '学生ID',
+    -- 其他字段...
+) COMMENT='学生信息表';
+
+-- 招生就业模块表
+CREATE TABLE `zsjy_application` (
+    `id` bigint(20) NOT NULL COMMENT '申请ID',
+    -- 其他字段...
+) COMMENT='招生申请表';
+
+-- 安全保卫模块表
+CREATE TABLE `aqbw_security` (
+    `id` bigint(20) NOT NULL COMMENT '安全记录ID',
+    -- 其他字段...
+) COMMENT='安全管理表';
+
+-- 系统公共模块表
+CREATE TABLE `common_dict` (
+    `id` bigint(20) NOT NULL COMMENT '字典ID',
+    -- 其他字段...
+) COMMENT='数据字典表';
+```
+
+**强制性要求**：
+- ✅ 新建表时必须使用对应模块前缀
+- ✅ 表名采用下划线命名法（snake_case）
+- ✅ 表名必须是英文，禁止使用中文或拼音
+- ✅ 表注释必须用中文清楚说明表的用途
+- ❌ 禁止跨模块混用前缀（如人事模块不能创建 cw_ 开头的表）
+- ❌ 禁止使用无前缀的表名（系统核心表除外）
+
+**实体类命名对应**：
+```java
+// 表名: hq_repair -> 实体类: HqRepair
+@TableName("hq_repair")
+public class HqRepair extends TenantEntity {
+    // ...
+}
+
+// 表名: rs_employee -> 实体类: RsEmployee
+@TableName("rs_employee")
+public class RsEmployee extends TenantEntity {
+    // ...
+}
+
+// 表名: cw_budget -> 实体类: CwBudget
+@TableName("cw_budget") 
+public class CwBudget extends TenantEntity {
+    // ...
+}
+```
+
 #### 🔴 强制性基础字段模板

 ```sql
@@ -1156,7 +1494,7 @@ testPermissions(token, permissionTests).then((results) => {

 ```
 org.mybatis.spring.MyBatisSystemException:
-Could not set property 'createBy' of 'class org.dromara.venue.domain.vo.HqVenueReservationVo'
+Could not set property 'createBy' of 'class org.dromara.hq.domain.vo.HqVenueReservationVo'
 with value '1' Cause: There is no setter for property named 'createBy'
 ```

@@ -33,6 +33,176 @@
 -   **前端访问**: http://localhost (默认 80 端口)
 -   **后端服务**: http://localhost:8080

+## 🔴 前端模块管理规范（强制性，2025-01-23新增）
+
+### 📦 前端模块文件夹规范
+
+**⚠️ 基于后端模块工程统一规划，前端必须建立对应的模块文件夹结构！**
+
+#### 🏗️ 模块命名和位置规范
+
+**界面文件夹位置**: `web/src/views/{模块简称}/`  
+**API文件夹位置**: `web/src/api/{模块简称}/`
+
+**已规划模块列表**:
+- ✅ `hq` - 后勤管理模块 (已完成)
+- ✅ `rs` - 人事管理模块
+- ✅ `cw` - 财务管理模块  
+- ✅ `aqbw` - 安全保卫管理模块
+- ✅ `zsjy` - 招生就业管理模块
+- ✅ `xg` - 学工管理模块
+
+#### 📁 标准目录结构
+
+**界面文件夹结构** (web/src/views/{模块简称}/):
+```
+web/src/views/{模块简称}/
+├── README.md                    # 模块说明文档
+├── {功能模块1}/                # 按功能模块细分
+│   ├── index.vue               # 列表页面
+│   ├── add.vue                 # 新增页面
+│   ├── edit.vue                # 编辑页面
+│   └── detail.vue              # 详情页面
+├── {功能模块2}/
+│   └── ...
+└── components/                 # 模块内公共组件
+    └── ...
+```
+
+**API文件夹结构** (web/src/api/{模块简称}/):
+```
+web/src/api/{模块简称}/
+├── index.ts                    # API入口文件
+├── README.md                   # API接口说明文档
+├── types.ts                    # 类型定义文件
+├── {功能模块1}/                # 按功能模块细分
+│   └── index.ts               # 功能模块API接口
+├── {功能模块2}/
+│   └── index.ts
+└── ...
+```
+
+#### 🎯 文件命名规范
+
+**Vue组件文件**:
+- 页面组件: PascalCase (如: `UserList.vue`)
+- 组件文件: kebab-case (如: `user-form.vue`)
+
+**TypeScript文件**:
+- API文件: kebab-case (如: `user-api.ts`)
+- 类型文件: kebab-case (如: `user-types.ts`)
+
+**路由命名**:
+- 路由路径: kebab-case (如: `/rs/employee-list`)
+- 路由名称: camelCase (如: `rsEmployeeList`)
+
+#### 🔐 权限命名规范
+
+**前端权限指令格式**: `v-hasPermi="'{模块简称}:{功能}:{操作}'"`
+
+**示例**:
+```vue
+<!-- 人事模块员工新增权限 -->
+<el-button v-hasPermi="'rs:employee:add'" type="primary">新增员工</el-button>
+
+<!-- 财务模块预算查看权限 -->
+<el-button v-hasPermi="'cw:budget:view'" type="primary">查看预算</el-button>
+
+<!-- 学工模块学生编辑权限 -->
+<el-button v-hasPermi="'xg:student:edit'" link type="primary">编辑</el-button>
+```
+
+#### 📋 路由配置规范
+
+**路由路径格式**: `/{模块简称}/{功能模块}`
+
+**router配置示例**:
+```typescript
+// router/modules/rs.ts - 人事管理模块路由
+export default {
+  path: '/rs',
+  name: 'Rs',
+  component: () => import('@/layout/index.vue'),
+  redirect: '/rs/employee',
+  meta: {
+    title: '人事管理',
+    icon: 'peoples',
+    rank: 3
+  },
+  children: [
+    {
+      path: '/rs/employee',
+      name: 'RsEmployee',
+      component: () => import('@/views/rs/employee/index.vue'),
+      meta: {
+        title: '员工管理',
+        keepAlive: true
+      }
+    },
+    {
+      path: '/rs/department',
+      name: 'RsDepartment', 
+      component: () => import('@/views/rs/department/index.vue'),
+      meta: {
+        title: '部门管理',
+        keepAlive: true
+      }
+    }
+  ]
+}
+```
+
+#### 🚨 前端模块开发检查清单
+
+**创建新模块前必须检查**:
+- [ ] 模块文件夹是否按规范命名？(`web/src/views/{简称}/`)
+- [ ] API文件夹是否对应创建？(`web/src/api/{简称}/`)
+- [ ] 是否创建了模块说明文档？(README.md)
+- [ ] 路由配置是否符合规范？
+- [ ] 权限指令是否使用正确的编码格式？
+- [ ] 是否遵循前端开发规范和UI设计标准？
+- [ ] 组件和文件命名是否符合规范？
+- [ ] API接口类型定义是否与后端VO保持一致？
+
+#### 💡 模块开发最佳实践
+
+**1. 组件复用**:
+- 模块内公共组件放在`components/`目录
+- 跨模块公共组件放在`@/components/`目录
+- 使用组合式API提高代码复用性
+
+**2. 状态管理**:
+- 模块相关状态使用Pinia store管理
+- Store文件命名：`@/stores/{模块简称}.ts`
+- 避免不同模块间的状态耦合
+
+**3. 样式管理**:
+- 使用SCSS变量和mixin提高样式复用
+- 遵循Art Design Pro UI设计规范
+- 统一使用轮廓式按钮设计
+
+**4. 类型安全**:
+- 所有API接口必须定义TypeScript类型
+- 类型定义与后端VO对象保持一致
+- 使用泛型提高类型复用性
+
+#### 📝 注意事项
+
+**模块间解耦**:
+- 避免模块间直接依赖，通过事件总线或状态管理通信
+- API接口按模块严格分离
+- 路由按模块独立配置，避免交叉引用
+
+**性能优化**:
+- 页面组件使用懒加载
+- 合理使用keep-alive缓存页面状态
+- 图片资源优化和懒加载
+
+**用户体验**:
+- 统一的加载状态和错误处理
+- 合理的页面过渡动画
+- 响应式设计支持多设备访问
+
 ## 2. Art Design Pro UI 规范

 ### 设计理念