提供部门相关的RESTful API接口，包括部门树查询、创建部门、获取部门成员等功能。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@RestController +@RequestMapping("/api/auth/depts") +@RequiredArgsConstructor +public class DeptController { + + private final DeptService deptService; + + /** + * 获取部门树 + */ + @GetMapping("/tree") + public ApiResponse提供权限（Permission）相关的HTTP API接口，包括权限的增删改查、类型筛选、菜单权限获取等功能。 + * 所有接口均遵循RESTful设计规范，返回统一的ApiResponse格式。
+ * + *主要接口：
+ *按权限类型筛选，如MENU、BUTTON、API等。
+ * + * @param type 权限类型 + * @return 包含该类型权限列表的响应 + */ @GetMapping("/type/{type}") public ResponseEntity获取type为MENU的所有权限，通常用于前端菜单渲染。
+ * + * @return 包含菜单权限列表的响应 + */ @GetMapping("/menus") public ResponseEntity创建一个新的权限。
+ * + * @param permission 要创建的权限信息（请求体） + * @return 包含创建后权限信息的响应 + */ @PostMapping public ResponseEntity更新指定权限的信息。
+ * + * @param id 要更新的权限ID + * @param permission 包含新数据的权限信息（请求体） + * @return 包含更新后权限信息的响应 + */ @PutMapping("/{id}") public ResponseEntity删除指定的权限。
+ * + * @param id 要删除的权限ID + * @return 空响应（表示操作成功） + */ @DeleteMapping("/{id}") public ResponseEntity提供项目成员相关的RESTful API接口，用于管理项目成员列表、添加成员、移除成员等功能。
+ * + *所有接口路径前缀为/api/auth/projects/{projectId}/members。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@RestController +@RequestMapping("/api/auth/projects") +@RequiredArgsConstructor +public class ProjectMemberController { + + /** 用户管理服务 */ + private final UserManagementService userManagementService; + + /** + * 查询项目成员列表 + * + *分页返回指定项目下的所有成员信息，包含角色信息。
+ * + * @param projectId 项目唯一标识符 + * @param page 页码，从1开始 + * @param size 每页数量 + * @return 包含分页成员信息的成功响应 + */ + @GetMapping("/{projectId}/members") + public ApiResponse返回尚未加入该项目的所有企业员工列表，支持模糊搜索用户。
+ * + * @param projectId 项目唯一标识符 + * @param search 搜索关键字（可选），支持用户名和真实姓名模糊匹配 + * @return 包含可用成员列表的成功响应 + */ + @GetMapping("/{projectId}/available-members") + public ApiResponse将指定用户添加到项目中，并分配多个角色。
+ * + * @param projectId 项目唯一标识符 + * @param dto 添加项目成员的请求数据 + * @return 成功响应 + */ + @PostMapping("/{projectId}/members") + @OperationLog(operation = "添加项目成员", module = "PROJECT_MEMBER", action = AuditLog.ActionType.CREATE) + public ApiResponse将指定用户从项目中移除。
+ * + * @param projectId 项目唯一标识符 + * @param userId 用户唯一标识符 + * @return 成功响应 + */ + @DeleteMapping("/{projectId}/members/{userId}") + @OperationLog(operation = "移除项目成员", module = "PROJECT_MEMBER", action = AuditLog.ActionType.DELETE) + public ApiResponse提供角色（Role）相关的HTTP API接口，包括角色的增删改查、权限分配、用户关联等功能。 + * 所有接口均遵循RESTful设计规范，返回统一的ApiResponse格式。
+ * + *主要接口：
+ *获取指定项目下的所有角色。
+ * + * @param projectId 项目ID + * @return 包含该项目角色列表的响应 + */ @GetMapping("/project/{projectId}") public ResponseEntity创建一个新的角色，记录审计日志。
+ * + * @param role 要创建的角色信息（请求体） + * @return 包含创建后角色信息的响应 + */ @PostMapping @OperationLog(operation = "创建角色", module = "ROLE", action = AuditLog.ActionType.CREATE) public ResponseEntity更新指定角色的信息，记录审计日志。
+ * + * @param id 要更新的角色ID + * @param role 包含新数据的角色信息（请求体） + * @return 包含更新后角色信息的响应 + */ @PutMapping("/{id}") @OperationLog(operation = "更新角色", module = "ROLE", action = AuditLog.ActionType.UPDATE) public ResponseEntity删除指定的角色，记录审计日志。
+ * + * @param id 要删除的角色ID + * @return 空响应（表示操作成功） + */ @DeleteMapping("/{id}") @OperationLog(operation = "删除角色", module = "ROLE", action = AuditLog.ActionType.DELETE) public ResponseEntity替换角色原有的所有权限，记录审计日志。
+ * + * @param id 角色ID + * @param permissionIds 要分配的权限ID列表（请求体） + * @return 空响应（表示操作成功） + */ @PostMapping("/{id}/permissions") @OperationLog(operation = "分配权限", module = "ROLE", action = AuditLog.ActionType.ASSIGN) public ResponseEntity查询指定角色关联的所有权限。
+ * + * @param id 角色ID + * @return 包含角色权限列表的响应 + */ @GetMapping("/{id}/permissions") public ResponseEntity查询所有拥有指定角色ID的用户。
+ * + * @param id 角色ID + * @return 包含用户列表的响应 + */ @GetMapping("/{id}/users") public ResponseEntity提供用户相关的RESTful API接口，包括用户CRUD、密码管理、角色分配、项目关联等功能。
+ * + *所有接口路径前缀为/api/auth/users，使用JSON格式进行数据交互。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @RestController -@RequestMapping("/api/users") +@RequestMapping("/api/auth/users") @RequiredArgsConstructor public class UserController { + /** 用户服务 */ private final UserService userService; + /** 用户项目关联服务 */ private final UserProjectService userProjectService; - + /** 用户管理服务 */ + private final UserManagementService userManagementService; + + /** + * 获取所有用户列表 + * + *返回系统中所有用户的信息，包含关联的角色列表。
+ * + * @return 包含所有用户的成功响应 + */ @GetMapping public ResponseEntity根据用户唯一标识符查询指定用户的详细信息。
+ * + * @param id 用户唯一标识符 + * @return 包含用户信息的成功响应 + */ @GetMapping("/{id}") public ResponseEntity创建一个新的用户账号，需要提供用户名、密码等基本信息。
+ * + * @param user 待创建的用户信息 + * @return 包含创建成功的用户信息的成功响应 + */ @PostMapping @OperationLog(operation = "创建用户", module = "USER", action = AuditLog.ActionType.CREATE) public ResponseEntity更新指定用户的个人信息，如真实姓名、手机号、邮箱等。
+ * + * @param id 用户唯一标识符 + * @param user 包含更新信息的用户对象 + * @return 包含更新后用户信息的成功响应 + */ @PutMapping("/{id}") @OperationLog(operation = "更新用户", module = "USER", action = AuditLog.ActionType.UPDATE) public ResponseEntity根据用户ID删除指定用户账号。
+ * + * @param id 用户唯一标识符 + * @return 成功响应 + */ @DeleteMapping("/{id}") @OperationLog(operation = "删除用户", module = "USER", action = AuditLog.ActionType.DELETE) public ResponseEntity用户修改自己的密码，需要提供原密码和新密码。
+ * + * @param id 用户唯一标识符 + * @param request 包含原密码和新密码的请求对象 + * @return 成功响应 + */ @PutMapping("/{id}/password") @OperationLog(operation = "修改密码", module = "USER", action = AuditLog.ActionType.UPDATE) public ResponseEntity为指定用户分配一个或多个角色，替换现有的角色。
+ * + * @param id 用户唯一标识符 + * @param roleIds 要分配的角色ID列表 + * @return 成功响应 + */ @PostMapping("/{id}/roles") @OperationLog(operation = "分配角色", module = "USER", action = AuditLog.ActionType.ASSIGN) public ResponseEntity查询指定用户参与的所有项目及其在项目中的角色。
+ * + * @param id 用户唯一标识符 + * @return 包含用户参与项目列表的成功响应 + */ @GetMapping("/{id}/projects") public ResponseEntity将指定用户添加到某个项目中，并设置用户在项目中的角色。
+ * + * @param id 用户唯一标识符 + * @param request 包含项目ID和角色信息的请求对象 + * @return 成功响应 + */ @PostMapping("/{id}/projects") public ResponseEntity将指定用户从某个项目中移除，删除用户与项目的关联关系。
+ * + * @param id 用户唯一标识符 + * @param projectId 项目唯一标识符 + * @return 成功响应 + */ @DeleteMapping("/{id}/projects/{projectId}") public ResponseEntity返回所有企业员工的用户信息列表。
+ * + * @return 包含企业员工列表的成功响应 + */ + @GetMapping("/enterprise") + public ResponseEntity包含修改密码所需的原密码和新密码。
+ */ @Data public static class PasswordRequest { + /** 原密码 */ private String oldPassword; + /** 新密码 */ private String newPassword; } -} +} \ No newline at end of file diff --git a/module-auth/src/main/java/com/ether/pms/auth/controller/dto/AddProjectMemberDTO.java b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/AddProjectMemberDTO.java new file mode 100644 index 0000000..1e6e87d --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/AddProjectMemberDTO.java @@ -0,0 +1,39 @@ +package com.ether.pms.auth.controller.dto; + +import java.util.List; +import java.util.UUID; + +import jakarta.validation.constraints.NotNull; +import lombok.Data; + +/** + * 添加项目成员请求DTO + * + *用于接收将用户添加到项目的请求数据。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class AddProjectMemberDTO { + + /** + * 用户ID + * 要添加到项目的用户唯一标识符 + */ + @NotNull(message = "用户ID不能为空") + private UUID userId; + + /** + * 员工类型 + * 标识员工的工作类型：SECURITY（保安）、CLEANING（保洁）、GARDEN（绿化）、MAINTENANCE（维修）、CUSTOMER_SERVICE（客服）、GENERAL（普通员工） + */ + private String staffType; + + /** + * 角色ID列表 + * 可选参数，分配的角色ID列表 + */ + private List用于接收创建企业用户的请求数据，包含用户基础信息和企业扩展信息。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class CreateEnterpriseUserDTO { + + /** + * 用户名 + * 用于登录系统 + */ + @NotBlank(message = "用户名不能为空") + private String username; + + /** + * 密码 + * 用户登录密码 + */ + @NotBlank(message = "密码不能为空") + private String password; + + /** + * 真实姓名 + * 用户的真实姓名 + */ + private String realName; + + /** + * 手机号码 + * 中国大陆手机号 + */ + private String phone; + + /** + * 电子邮箱 + * 用户的邮箱地址 + */ + private String email; + + /** + * 员工工号 + * 企业内部员工编号 + */ + private String employeeNo; + + /** + * 部门ID + * 用户所属的部门标识符 + */ + private UUID deptId; + + /** + * 职位 + * 用户在企业中的职位 + */ + private String position; + + /** + * 入职日期 + * 员工加入企业的日期 + */ + private LocalDate entryDate; + + /** + * 员工类别 + * 标识员工类型：ENTERPRISE（普通员工）、MANAGEMENT（管理层） + */ + private String userCategory; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptDTO.java b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptDTO.java new file mode 100644 index 0000000..6cb2538 --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptDTO.java @@ -0,0 +1,63 @@ +package com.ether.pms.auth.controller.dto; + +import jakarta.validation.constraints.NotBlank; +import lombok.Data; + +import java.util.UUID; + +/** + * 部门数据传输对象 + * + *用于接收创建或更新部门的请求数据。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class DeptDTO { + + /** + * 部门名称 + */ + @NotBlank(message = "部门名称不能为空") + private String deptName; + + /** + * 部门编码 + */ + private String deptCode; + + /** + * 上级部门ID + */ + private UUID parentId; + + /** + * 部门类型 + * ADMIN: 行政管理 + * ENGINEERING: 工程部 + * SECURITY: 安保部 + * CS: 客服部 + * CLEANING: 保洁部 + */ + private String deptType = "ADMIN"; + + /** + * 部门默认角色编码 + * 属于该部门的员工默认拥有的系统角色 + */ + private String defaultRoleCode; + + /** + * 部门负责人ID + */ + private UUID leaderId; + + /** + * 排序序号 + */ + private Integer sortOrder; + + private String status = "ACTIVE"; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptVO.java b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptVO.java new file mode 100644 index 0000000..5c493d1 --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/controller/dto/DeptVO.java @@ -0,0 +1,115 @@ +package com.ether.pms.auth.controller.dto; + +import com.ether.pms.auth.entity.Dept; +import lombok.Data; + +import java.util.ArrayList; +import java.util.List; +import java.util.UUID; + +/** + * 部门视图对象 + * + *用于返回部门信息的视图对象，包含部门基本信息和子部门列表。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class DeptVO { + + /** + * 部门唯一标识符 + */ + private UUID id; + + /** + * 上级部门ID + */ + private UUID parentId; + + /** + * 部门名称 + */ + private String deptName; + + /** + * 部门编码 + */ + private String deptCode; + + /** + * 部门类型 + */ + private String deptType; + + /** + * 部门类型描述 + */ + private String deptTypeDesc; + + /** + * 部门默认角色编码 + */ + private String defaultRoleCode; + + /** + * 部门负责人ID + */ + private UUID leaderId; + + /** + * 排序序号 + */ + private Integer sortOrder; + + /** + * 部门状态 + */ + private String status; + + /** + * 子部门列表 + */ + private List用于返回分页数据的统一格式，包含内容列表、分页信息和总数。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +@NoArgsConstructor +@AllArgsConstructor +public class PageResponse用于返回项目成员信息，包含用户基本信息、角色信息和加入时间。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class ProjectMemberVO { + + /** + * 用户唯一标识符 + */ + private UUID id; + + /** + * 用户名 + */ + private String username; + + /** + * 真实姓名 + */ + private String realName; + + /** + * 手机号 + */ + private String phone; + + /** + * 邮箱 + */ + private String email; + + /** + * 用户类型 + */ + private String userType; + + /** + * 用户状态 + */ + private String status; + + /** + * 员工类型 + */ + private String staffType; + + /** + * 项目中的角色列表 + */ + private List用于返回用户信息的简化视图，包含用户基本信息、部门信息和角色列表。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Data +public class UserVO { + + /** + * 用户唯一标识符 + */ + private UUID id; + + /** + * 用户名 + */ + private String username; + + /** + * 真实姓名 + */ + private String realName; + + /** + * 手机号 + */ + private String phone; + + /** + * 邮箱 + */ + private String email; + + /** + * 用户类型 + */ + private String userType; + + /** + * 用户状态 + */ + private String status; + + /** + * 部门ID + */ + private UUID deptId; + + /** + * 部门名称 + */ + private String deptName; + + /** + * 角色列表 + */ + private List表示组织架构中的部门信息，包含部门名称、编码、负责人、类型等。
+ * + *支持树形结构，通过parentId指向上级部门。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "dept") +@Data +public class Dept { + + /** + * 部门唯一标识符 + * 采用UUID策略自动生成 + */ + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + /** + * 上级部门ID + * 指向父部门的ID，用于构建部门树形结构，顶级部门此字段为空 + */ + private UUID parentId; + + /** + * 部门名称 + * 部门的显示名称 + */ + @Column(nullable = false, length = 100) + private String deptName; + + /** + * 部门编码 + * 部门的唯一编码，用于系统间对接 + */ + @Column(length = 50) + private String deptCode; + + /** + * 部门类型 + * 标识部门所属的业务类型 + * ADMIN: 行政管理 + * ENGINEERING: 工程部 + * SECURITY: 安保部 + * CS: 客服部 + * CLEANING: 保洁部 + */ + @Column(length = 20) + private String deptType = "ADMIN"; + + /** + * 部门默认角色编码 + * 属于该部门的员工默认拥有的系统角色 + */ + @Column(length = 50) + private String defaultRoleCode; + + /** + * 部门负责人ID + * 部门负责人的用户ID + */ + private UUID leaderId; + + /** + * 排序序号 + * 部门在同一级别中的排序顺序，数字越小越靠前 + */ + private Integer sortOrder; + + /** + * 部门状态 + * 标识部门的状态：ACTIVE-正常、DISABLED-停用 + */ + @Column(length = 20) + private String status = "ACTIVE"; + + /** + * 创建时间 + */ + private LocalDateTime createdAt; + + /** + * 更新时间 + */ + private LocalDateTime updatedAt; + + @PrePersist + protected void onCreate() { + createdAt = LocalDateTime.now(); + updatedAt = LocalDateTime.now(); + } + + @PreUpdate + protected void onUpdate() { + updatedAt = LocalDateTime.now(); + } + + /** + * 部门类型枚举 + */ + public enum DeptType { + ADMIN("行政管理"), + ENGINEERING("工程部"), + SECURITY("安保部"), + CS("客服部"), + CLEANING("保洁部"); + + private final String desc; + + DeptType(String desc) { + this.desc = desc; + } + + public String getDesc() { + return desc; + } + } +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/EnterpriseUser.java b/module-auth/src/main/java/com/ether/pms/auth/entity/EnterpriseUser.java new file mode 100644 index 0000000..2af111f --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/EnterpriseUser.java @@ -0,0 +1,72 @@ +package com.ether.pms.auth.entity; + +import jakarta.persistence.*; +import lombok.Data; +import java.time.LocalDate; +import java.util.UUID; + +/** + * 企业用户实体类 + * + *表示企业类型的用户信息，包含员工的职位、入职日期等企业相关信息。
+ * + *与User实体为一对一关系，共享主键。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "enterprise_user") +@Data +public class EnterpriseUser { + + /** + * 用户ID + * 主键，也是外键指向auth_user表 + */ + @Id + private UUID userId; + + /** + * 员工工号 + * 企业内部员工编号 + */ + @Column(length = 50) + private String employeeNo; + + /** + * 部门ID + * 用户所属的部门标识符 + */ + private UUID deptId; + + /** + * 职位 + * 用户在企业中的职位 + */ + @Column(length = 50) + private String position; + + /** + * 入职日期 + * 员工加入企业的日期 + */ + private LocalDate entryDate; + + /** + * 员工类别 + * 标识员工类型：ENTERPRISE（普通员工）、MANAGEMENT（管理层） + */ + @Column(length = 50) + private String userCategory; + + /** + * 关联的User实体 + * 采用一对一关系，共享主键 + */ + @OneToOne + @MapsId + @JoinColumn(name = "user_id") + private User user; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/Permission.java b/module-auth/src/main/java/com/ether/pms/auth/entity/Permission.java index cdcdae8..5f6a5fc 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/entity/Permission.java +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/Permission.java @@ -10,47 +10,101 @@ import java.time.LocalDateTime; import java.util.List; import java.util.UUID; +/** + * 权限实体类 + * + *用于定义系统中的权限信息，包括权限代码、名称、类型、资源路径等属性。 + * 权限是系统安全的基础单元，用于控制用户对具体功能的访问能力。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Entity @Table(name = "auth_permission") @Data public class Permission { - + + /** + * 权限唯一标识符 + * 使用UUID自动生成 + */ @Id @GeneratedValue(strategy = GenerationType.UUID) private UUID id; - + + /** + * 权限代码 + * 系统内部识别符，必须唯一 + * 格式：只能包含字母、数字、冒号和下划线，长度2-100位 + * 例如：system:user:create, menu:project:view + */ @NotNull(message = "权限代码不能为空") @Size(min = 2, max = 100, message = "权限代码长度必须在2-100位之间") @Pattern(regexp = "^[a-zA-Z0-9_:]+$", message = "权限代码只能包含字母、数字、冒号和下划线") @Column(unique = true, nullable = false, length = 100) private String code; - + + /** + * 权限名称 + * 用于前端展示和用户理解，长度2-100位 + */ @NotNull(message = "权限名称不能为空") @Size(min = 2, max = 100, message = "权限名称长度必须在2-100位之间") @Column(nullable = false, length = 100) private String name; - + + /** + * 权限类型 + * 用于分类权限，如：MENU（菜单）、BUTTON（按钮）、API（接口）等 + */ @Size(max = 20, message = "权限类型长度不能超过20位") @Column(length = 20) private String type; - + + /** + * 资源路径 + * 对于API类型的权限，表示对应的接口路径 + */ @Size(max = 50, message = "资源路径长度不能超过50位") @Column(length = 50) private String resource; - + + /** + * 请求方法 + * 对于API类型的权限，表示对应的HTTP方法（如GET、POST、PUT、DELETE） + */ @Size(max = 50, message = "请求方法长度不能超过50位") @Column(length = 50) private String method; - + + /** + * 权限描述 + * 对权限的详细说明，用于帮助理解权限用途，长度不超过200位 + */ @Size(max = 200, message = "权限描述长度不能超过200位") @Column(length = 200) private String description; - + + /** + * 父权限代码 + * 用于构建权限树形结构，支持层级管理 + * 顶级权限的父代码为空 + */ @Column(length = 50) private String parentCode; - + + /** + * 排序序号 + * 用于前端展示时的排序，数字越小越靠前 + */ private Integer sortOrder; - + + /** + * 权限关联的角色列表 + * 多对多关系，通过auth_role_permission关联表维护 + * JsonIgnoreProperties避免循环序列化 + */ @JsonIgnoreProperties({"permissions", "roles"}) @ManyToMany(fetch = FetchType.LAZY) @JoinTable( @@ -59,19 +113,35 @@ public class Permission { inverseJoinColumns = @JoinColumn(name = "role_id") ) private List表示项目类型的员工信息，包含所属项目、员工类型、班次等信息。
+ * + *与User实体为一对一关系，共享主键。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "project_staff") +@Data +public class ProjectStaff { + + /** + * 主键ID + */ + @Id + @GeneratedValue(strategy = GenerationType.UUID) + @Column(name = "id") + private UUID id; + + /** + * 用户ID + * 外键指向auth_user表 + */ + @Column(name = "user_id", insertable = false, updatable = false) + private UUID userId; + + /** + * 所属项目ID + * 员工所属项目的唯一标识符 + */ + private UUID projectId; + + /** + * 所属部门ID + * 员工所属部门的唯一标识符，用于组织架构管理 + */ + private UUID deptId; + + /** + * 员工类型 + * 标识员工的工作类型：SECURITY（保安）、CLEANING（保洁）、GARDEN（绿化）、MAINTENANCE（维修）、CUSTOMER_SERVICE（客服）、GENERAL（普通员工） + */ + @Column(length = 50) + private String staffType; + + /** + * 班次类型 + * 标识员工的班次：DAY（白班）、NIGHT（夜班）、ROTATION（轮班） + */ + @Column(length = 20) + private String shiftType; + + /** + * 班组长ID + * 员工所属班组长的用户ID + */ + private UUID leaderId; + + /** + * 在岗状态 + * 标识员工的在岗状态：ASSIGNED（已分配）、ON_LEAVE（请假）、TRANSFERRED（已调离） + */ + @Column(length = 20) + private String assignmentStatus; + + /** + * 员工角色列表 + */ + @OneToMany(mappedBy = "staff", cascade = CascadeType.ALL, orphanRemoval = true) + private List表示住户类型的用户信息，包含身份证、认证状态等住户相关信息。
+ * + *与User实体为一对一关系，共享主键。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "resident") +@Data +public class Resident { + + /** + * 用户ID + * 主键，也是外键指向auth_user表 + */ + @Id + private UUID userId; + + /** + * 身份证号码 + * 住户的身份证号，用于身份验证 + */ + @Column(length = 18) + private String idCard; + + /** + * 住户类型 + * 标识住户类型：OWNER（业主）、FAMILY（家属）、TENANT（租户） + */ + @Column(length = 20) + private String residentType; + + /** + * 认证状态 + * 标识住户的认证状态：UNVERIFIED（未认证）、PENDING（待审核）、VERIFIED（已认证）、REJECTED（已拒绝） + */ + @Column(length = 20) + private String verificationStatus; + + /** + * 认证时间 + * 记录住户认证通过的时间 + */ + private LocalDateTime verifiedAt; + + /** + * 认证人ID + * 执行认证操作的管理员用户ID + */ + private UUID verifiedBy; + + /** + * 关联的User实体 + * 采用一对一关系，共享主键 + */ + @OneToOne + @MapsId + @JoinColumn(name = "user_id") + private User user; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/ResidentSpace.java b/module-auth/src/main/java/com/ether/pms/auth/entity/ResidentSpace.java new file mode 100644 index 0000000..3fdc583 --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/ResidentSpace.java @@ -0,0 +1,71 @@ +package com.ether.pms.auth.entity; + +import jakarta.persistence.*; +import lombok.Data; +import java.time.LocalDate; +import java.util.UUID; + +/** + * 住户房屋关联实体类 + * + *表示住户与房屋之间的关联关系，记录住户与房屋的绑定信息。
+ * + *支持业主、家属、租户等多种关系类型，以及绑定状态管理。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "resident_space") +@Data +public class ResidentSpace { + + /** + * 关联记录唯一标识符 + * 采用UUID策略自动生成 + */ + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + /** + * 用户ID + * 关联的用户唯一标识符 + */ + @Column(name = "user_id", nullable = false) + private UUID userId; + + /** + * 房屋ID + * 关联的房屋唯一标识符 + */ + @Column(name = "space_id", nullable = false) + private UUID spaceId; + + /** + * 关系类型 + * 标识住户与房屋的关系：OWNER（业主）、FAMILY（家属）、TENANT（租户） + */ + @Column(length = 20) + private String relationType; + + /** + * 绑定状态 + * 标识关联的状态：PENDING（待生效）、ACTIVE（生效中）、EXPIRED（已过期）、CANCELLED（已取消） + */ + @Column(length = 20) + private String bindingStatus; + + /** + * 开始日期 + * 关联关系的生效日期 + */ + private LocalDate startDate; + + /** + * 结束日期 + * 关联关系的失效日期，永久关联则为空 + */ + private LocalDate endDate; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/Role.java b/module-auth/src/main/java/com/ether/pms/auth/entity/Role.java index 7a5dab8..204c6d3 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/entity/Role.java +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/Role.java @@ -9,45 +9,92 @@ import java.time.LocalDateTime; import java.util.List; import java.util.UUID; +/** + * 角色实体类 + * + *用于定义系统中的角色信息，包括角色代码、名称、描述、类型、数据范围等属性。 + * 角色与权限通过多对多关联，一个角色可以拥有多个权限。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Entity @Table(name = "auth_role") @Data public class Role { - + + /** + * 角色唯一标识符 + * 使用UUID自动生成 + */ @Id @GeneratedValue(strategy = GenerationType.UUID) private UUID id; - + + /** + * 角色代码 + * 用于系统内部识别，必须唯一 + * 格式：只能包含字母、数字和下划线，长度2-50位 + */ @NotNull(message = "角色代码不能为空") @Size(min = 2, max = 50, message = "角色代码长度必须在2-50位之间") @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "角色代码只能包含字母、数字和下划线") @Column(unique = true, nullable = false, length = 50) private String code; - + + /** + * 角色名称 + * 用于前端展示，长度2-50位 + */ @NotNull(message = "角色名称不能为空") @Size(min = 2, max = 50, message = "角色名称长度必须在2-50位之间") @Column(nullable = false, length = 50) private String name; - + + /** + * 角色描述 + * 对角色的详细说明，长度不超过200位 + */ @Size(max = 200, message = "角色描述长度不能超过200位") @Column(length = 200) private String description; - + + /** + * 角色类型 + * 区分系统级、项目级、部门级角色 + */ @Enumerated(EnumType.STRING) @Column(length = 20) private RoleType type; - + + /** + * 数据范围 + * 定义角色可访问的数据范围，默认为本人数据 + */ @Enumerated(EnumType.STRING) @Column(length = 20) private DataScope dataScope = DataScope.SELF; - + + /** + * 所属项目ID + * 用于项目级角色的项目归属 + */ @Column(length = 50) private String projectId; - + + /** + * 角色状态 + * 启用或禁用，默认为启用 + */ @Enumerated(EnumType.STRING) @Column(length = 20) private RoleStatus status = RoleStatus.ENABLED; - + + /** + * 角色关联的权限列表 + * 多对多关系，通过auth_role_permission关联表维护 + */ @ManyToMany(fetch = FetchType.LAZY) @JoinTable( name = "auth_role_permission", @@ -55,55 +102,92 @@ public class Role { inverseJoinColumns = @JoinColumn(name = "permission_id") ) private List表示项目中的房屋或空间信息，包含楼栋、单元、房号等。
+ * + *支持住宅和商业两种类型的空间管理。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Entity +@Table(name = "space") +@Data +public class Space { + + /** + * 空间唯一标识符 + * 采用UUID策略自动生成 + */ + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + /** + * 所属项目ID + * 空间所属项目的唯一标识符 + */ + private UUID projectId; + + /** + * 楼栋 + * 房屋所在的楼栋号或名称 + */ + @Column(length = 50) + private String building; + + /** + * 单元 + * 房屋所在的单元号 + */ + @Column(length = 50) + private String unit; + + /** + * 房号 + * 房屋的房间号 + */ + @Column(length = 50) + private String roomNo; + + /** + * 房屋类型 + * 标识房屋类型：RESIDENTIAL（住宅）、COMMERCIAL（商业） + */ + @Column(length = 20) + private String spaceType; + + /** + * 楼层 + * 房屋所在的楼层 + */ + private Integer floor; + + /** + * 建筑面积 + * 房屋的建筑面积，单位平方米 + */ + private BigDecimal unitArea; + + /** + * 状态 + * 标识房屋的状态：正常、空置、已售等 + */ + @Column(length = 20) + private String status; +} diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/SysConfig.java b/module-auth/src/main/java/com/ether/pms/auth/entity/SysConfig.java index 9adc3ab..328e08c 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/entity/SysConfig.java +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/SysConfig.java @@ -11,6 +11,13 @@ import org.hibernate.annotations.UpdateTimestamp; import java.time.LocalDateTime; import java.util.UUID; +/** + * 系统配置实体类 + * 用于存储系统的键值对配置信息，如物业企业名称等 + * + * @author Ether Team + * @since 1.0.0 + */ @Entity @Table(name = "sys_config") @Data @@ -19,23 +26,47 @@ import java.util.UUID; @Builder public class SysConfig { + /** + * 配置项唯一标识 + * 使用 UUID 自动生成 + */ @Id @GeneratedValue(strategy = GenerationType.UUID) private UUID id; + /** + * 配置键 + * 唯一标识一个配置项，如：property_company_name + */ @Column(name = "config_key", nullable = false, unique = true, length = 128) private String configKey; + /** + * 配置值 + * 使用 TEXT 类型存储，支持长文本 + */ @Column(name = "config_value", columnDefinition = "TEXT") private String configValue; + /** + * 配置描述 + * 用于说明该配置项的用途 + */ @Column(name = "description", length = 256) private String description; + /** + * 创建时间 + * 自动填充，不可更新 + */ @CreationTimestamp @Column(name = "created_at", nullable = false, updatable = false) private LocalDateTime createdAt; + /** + * 更新时间 + * 自动填充，更新时自动修改 + */ @UpdateTimestamp @Column(name = "updated_at", nullable = false) private LocalDateTime updatedAt; diff --git a/module-auth/src/main/java/com/ether/pms/auth/entity/User.java b/module-auth/src/main/java/com/ether/pms/auth/entity/User.java index ed12425..bf9c3cc 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/entity/User.java +++ b/module-auth/src/main/java/com/ether/pms/auth/entity/User.java @@ -10,48 +10,120 @@ import java.time.LocalDateTime; import java.util.List; import java.util.UUID; +/** + * 用户实体类 + * + *表示系统中的用户信息，包含用户的基本认证信息和个人资料。
+ * + *使用JPA注解映射到auth_user表，支持基本的CRUD操作。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Entity @Table(name = "auth_user") @Data public class User { - + + /** + * 用户唯一标识符 + * 采用UUID策略自动生成 + */ @Id @GeneratedValue(strategy = GenerationType.UUID) private UUID id; - + + /** + * 用户名 + * 用于用户登录，唯一标识，长度3-50位，只能包含字母、数字和下划线 + */ @NotNull(message = "用户名不能为空") @Size(min = 3, max = 50, message = "用户名长度必须在3-50位之间") @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "用户名只能包含字母、数字和下划线") @Column(unique = true, nullable = false, length = 50) private String username; - + + /** + * 密码（加密存储） + * 使用BCrypt加密后的密码原文 + */ @NotNull(message = "密码不能为空") @Column(nullable = false, length = 255) private String password; - + + /** + * 密码盐值 + * 用于增强密码加密的安全性 + */ private String salt; - + + /** + * 真实姓名 + * 用户的真实姓名，用于显示 + */ @Column(length = 50) private String realName; - + + /** + * 手机号码 + * 中国大陆手机号格式，11位数字 + */ @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确") @Column(length = 20) private String phone; - + + /** + * 电子邮箱 + * 用户的邮箱地址，用于通知和验证 + */ @Email(message = "邮箱格式不正确") @Column(length = 100) private String email; - + + /** + * 头像URL + * 用户头像的存储路径或URL + */ private String avatar; - + + /** + * 用户状态 + * 标识用户的当前状态：正常、锁定或禁用 + */ @Enumerated(EnumType.STRING) @Column(length = 20) private UserStatus status = UserStatus.ACTIVE; - + + /** + * 用户类型 + * 标识用户的类型：ENTERPRISE（企业用户）、PROJECT_STAFF（项目员工）、RESIDENT（住户）、CUSTOMER（客户） + */ + @Column(length = 20) + private String userType; + + /** + * 部门ID + * 用户所属的部门标识符 + */ + private UUID deptId; + + /** + * 最后登录时间 + * 记录用户最后一次成功登录的时间 + */ private LocalDateTime lastLoginTime; - + + /** + * 最后登录IP + * 记录用户最后一次成功登录的IP地址 + */ private String lastLoginIp; - + + /** + * 用户关联的角色列表 + * 采用懒加载方式获取用户的所有角色 + */ @ManyToMany(fetch = FetchType.LAZY) @JoinTable( name = "auth_user_role", @@ -59,35 +131,73 @@ public class User { inverseJoinColumns = @JoinColumn(name = "role_id") ) private List表示用户与项目之间的关联关系，记录用户在特定项目中的角色和加入时间。
+ * + *一个用户可以关联多个项目，一个项目也可以关联多个用户，形成多对多关系。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Entity @Table(name = "user_project") @Data public class UserProject { + /** + * 关联记录唯一标识符 + * 采用UUID策略自动生成 + */ @Id @GeneratedValue(strategy = GenerationType.UUID) private UUID id; + /** + * 用户ID + * 关联的用户唯一标识符 + */ @Column(name = "user_id", nullable = false) private UUID userId; + /** + * 项目ID + * 关联的项目唯一标识符 + */ @Column(name = "project_id", nullable = false) private UUID projectId; + /** + * 在项目中的角色 + * 记录用户在关联项目中的角色，默认值为"member"（成员） + */ @Column(name = "role_in_project", nullable = false) private String roleInProject = "member"; + /** + * 加入时间 + * 记录用户加入项目的时间，默认为当前时间 + */ @Column(name = "joined_at", nullable = false) private LocalDateTime joinedAt = LocalDateTime.now(); + /** + * 持久化前回调 + * 在关联记录首次保存前，如果加入时间为空则设置为当前时间 + */ @PrePersist public void prePersist() { if (this.joinedAt == null) { this.joinedAt = LocalDateTime.now(); } } -} +} \ No newline at end of file diff --git a/module-auth/src/main/java/com/ether/pms/auth/repository/DeptRepository.java b/module-auth/src/main/java/com/ether/pms/auth/repository/DeptRepository.java new file mode 100644 index 0000000..ccee90e --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/repository/DeptRepository.java @@ -0,0 +1,97 @@ +package com.ether.pms.auth.repository; + +import com.ether.pms.auth.entity.Dept; +import org.springframework.data.jpa.repository.JpaRepository; +import org.springframework.data.jpa.repository.Query; +import org.springframework.data.repository.query.Param; +import org.springframework.stereotype.Repository; + +import java.util.List; +import java.util.Optional; +import java.util.UUID; + +/** + * 部门数据访问层接口 + * + *提供部门数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface DeptRepository extends JpaRepository查询没有上级部门的部门，即树形结构的根节点。
+ * + * @return 顶级部门列表 + */ + List提供企业用户数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface EnterpriseUserRepository extends JpaRepository提供权限（Permission）实体的数据库操作方法，继承Spring Data JPA的JpaRepository。 + * 支持按权限类型、父权限代码等条件查询。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Repository public interface PermissionRepository extends JpaRepository按权限类型筛选，如MENU（菜单）、BUTTON（按钮）、API（接口）等。
+ * + * @param type 权限类型 + * @return 该类型的所有权限列表 + */ List用于构建权限树形结构，查找属于某个父权限的所有子权限。
+ * + * @param parentCode 父权限代码 + * @return 该父权限下的所有子权限列表 + */ List用于创建权限时的唯一性校验。
+ * + * @param code 权限代码 + * @return 存在返回true，不存在返回false + */ boolean existsByCode(String code); -} +} \ No newline at end of file diff --git a/module-auth/src/main/java/com/ether/pms/auth/repository/ProjectStaffRepository.java b/module-auth/src/main/java/com/ether/pms/auth/repository/ProjectStaffRepository.java new file mode 100644 index 0000000..6eeaac4 --- /dev/null +++ b/module-auth/src/main/java/com/ether/pms/auth/repository/ProjectStaffRepository.java @@ -0,0 +1,86 @@ +package com.ether.pms.auth.repository; + +import java.util.List; +import java.util.Optional; +import java.util.UUID; + +import org.springframework.data.jpa.repository.JpaRepository; +import org.springframework.data.jpa.repository.Query; +import org.springframework.stereotype.Repository; + +import com.ether.pms.auth.entity.ProjectStaff; + +/** + * 项目员工数据访问层接口 + * + *提供项目员工数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface ProjectStaffRepository extends JpaRepository提供住户数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface ResidentRepository extends JpaRepository提供住户房屋关联数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface ResidentSpaceRepository extends JpaRepository提供角色（Role）实体的数据库操作方法，继承Spring Data JPA的JpaRepository。 + * 支持按角色代码、项目ID、类型等条件查询，以及带权限信息的复杂查询。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Repository public interface RoleRepository extends JpaRepository角色代码在系统中唯一，用于精确查找特定角色。
+ * + * @param code 角色代码 + * @return 角色对象（如果存在） + */ Optional用于创建角色时的唯一性校验。
+ * + * @param code 角色代码 + * @return 存在返回true，不存在返回false + */ boolean existsByCode(String code); + /** + * 根据项目ID查询角色列表 + * + *获取指定项目下的所有角色，通常用于项目级别的角色筛选。
+ * + * @param projectId 项目ID + * @return 该项目下的角色列表 + */ List按角色类型（如系统级、项目级、部门级）筛选角色。
+ * + * @param type 角色类型枚举 + * @return 该类型的所有角色列表 + */ List使用EntityGraph eagerly加载permissions关联数据， + * 避免N+1查询问题，提升查询性能。
+ * + * @param id 角色ID + * @return 包含权限信息的角色对象（如果存在） + */ @EntityGraph(attributePaths = {"permissions"}) Optional提供房屋空间数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Repository +public interface SpaceRepository extends JpaRepository提供用户与项目关联关系的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + *支持用户项目关系查询、分页、批量操作等功能。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Repository public interface UserProjectRepository extends JpaRepository返回指定用户参与的所有项目关联记录列表。
+ * + * @param userId 用户唯一标识符 + * @return 该用户关联的所有项目列表 + */ List返回参与指定项目的所有用户关联记录列表。
+ * + * @param projectId 项目唯一标识符 + * @return 该项目关联的所有用户列表 + */ List支持分页展示项目成员列表。
+ * + * @param projectId 项目唯一标识符 + * @param pageable 分页参数，包含页码和每页大小 + * @return 分页的用户项目关联列表 + */ Page仅返回项目ID列表，用于快速判断用户参与的项目。
+ * + * @param userId 用户唯一标识符 + * @return 该用户关联的所有项目ID列表 + */ @Query("SELECT up.projectId FROM UserProject up WHERE up.userId = :userId") List用于判断用户是否参与了指定项目。
+ * + * @param userId 用户唯一标识符 + * @param projectId 项目唯一标识符 + * @return 存在返回true，不存在返回false + */ boolean existsByUserIdAndProjectId(UUID userId, UUID projectId); + /** + * 删除用户与项目的关联 + * + *根据用户ID和项目ID删除关联记录，用于用户退出项目或移除项目成员。
+ * + * @param userId 用户唯一标识符 + * @param projectId 项目唯一标识符 + */ void deleteByUserIdAndProjectId(UUID userId, UUID projectId); -} + + /** + * 统计项目下的成员数量 + */ + long countByProjectId(UUID projectId); +} \ No newline at end of file diff --git a/module-auth/src/main/java/com/ether/pms/auth/repository/UserRepository.java b/module-auth/src/main/java/com/ether/pms/auth/repository/UserRepository.java index d831b40..ec68913 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/repository/UserRepository.java +++ b/module-auth/src/main/java/com/ether/pms/auth/repository/UserRepository.java @@ -9,24 +9,121 @@ import java.util.List; import java.util.Optional; import java.util.UUID; +/** + * 用户数据访问层接口 + * + *提供用户数据的持久化操作，继承Spring Data JPA的JpaRepository接口。
+ * + *包含用户查询、角色关联查询等数据库操作方法。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Repository public interface UserRepository extends JpaRepository最基础的按用户名查询方法，返回Optional包装的用户对象。
+ * + * @param username 用户名 + * @return 包含用户的Optional对象，如果不存在则为空 + */ Optional使用LEFT JOIN FETCH预加载用户的角色信息，避免N+1查询问题。
+ * + * @param username 用户名 + * @return 包含用户及其角色的Optional对象 + */ @Query("SELECT u FROM User u LEFT JOIN FETCH u.roles WHERE u.username = :username") Optional一次性加载所有用户及其角色信息，适用于管理后台用户列表。
+ * + * @return 包含所有用户及其角色的列表 + */ @Query("SELECT u FROM User u LEFT JOIN FETCH u.roles") List使用LEFT JOIN FETCH预加载用户的角色信息。
+ * + * @param id 用户唯一标识符 + * @return 包含用户及其角色的Optional对象 + */ @Query("SELECT u FROM User u LEFT JOIN FETCH u.roles WHERE u.id = :id") Optional用于查询具有特定角色的所有用户列表。
+ * + * @param roleId 角色唯一标识符 + * @return 拥有该角色的所有用户列表 + */ @Query("SELECT u FROM User u JOIN u.roles r WHERE r.id = :roleId") List用于用户注册时验证用户名唯一性。
+ * + * @param username 用户名 + * @return 存在返回true，不存在返回false + */ boolean existsByUsername(String username); + /** + * 检查手机号是否存在 + * + *用于用户注册或更新时验证手机号唯一性。
+ * + * @param phone 手机号码 + * @return 存在返回true，不存在返回false + */ boolean existsByPhone(String phone); -} + + /** + * 根据用户类型查询用户列表 + * + *用于查询特定类型的用户，如ENTERPRISE、PROJECT_STAFF等。
+ * + * @param userType 用户类型 + * @return 该类型的所有用户列表 + */ + List用于查询属于特定部门的所有用户。
+ * + * @param deptId 部门唯一标识符 + * @return 该部门下的所有用户列表 + */ + List通过关联ProjectStaff表查询属于指定项目的所有员工用户。
+ * + * @param projectId 项目唯一标识符 + * @return该项目下的所有员工用户列表 + */ + @Query("SELECT u FROM User u JOIN ProjectStaff ps ON u.id = ps.userId WHERE ps.projectId = :projectId") + List提供部门相关的业务逻辑处理，包括部门树查询、部门CRUD、部门员工查询等功能。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ +@Service +@RequiredArgsConstructor +public class DeptService { + + private final DeptRepository deptRepository; + private final UserRepository userRepository; + + /** + * 获取部门树 + * + *返回所有部门的列表，支持前端构建树形结构。
+ * + * @return 所有部门的列表 + */ + public List根据部门ID查询该部门下的所有员工用户。
+ * + * @param deptId 部门唯一标识符 + * @return 该部门下的所有员工用户列表 + */ + public List提供权限（Permission）相关的业务操作，包括权限的增删改查、类型筛选、菜单权限获取等功能。 + * 所有写操作均支持事务管理，确保数据一致性。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Service @RequiredArgsConstructor public class PermissionService { - + + /** 权限数据访问仓库 */ private final PermissionRepository permissionRepository; - + + /** + * 查询所有权限 + * + * @return 所有权限的列表 + */ public List如果权限不存在，抛出PERMISSION_002业务异常。
+ * + * @param id 权限ID + * @return 权限对象 + * @throws BusinessException 如果权限不存在 + */ public Permission findById(UUID id) { return permissionRepository.findById(id) .orElseThrow(() -> new BusinessException(ErrorCode.PERMISSION_002)); } - + + /** + * 根据权限类型查询权限列表 + * + *按权限类型筛选，如MENU、BUTTON、API等。
+ * + * @param type 权限类型 + * @return 该类型的所有权限列表 + */ public List用于获取某个父权限下的所有子权限，构建权限树。
+ * + * @param parentCode 父权限代码 + * @return 该父权限下的所有子权限列表 + */ public List获取type为MENU的所有权限，通常用于前端菜单渲染。
+ * + * @return 所有菜单权限列表 + */ public List如果权限代码已存在，抛出PERMISSION_001业务异常。 + * 创建时会自动设置创建时间和更新时间。
+ * + * @param permission 要创建的权限对象 + * @return 创建后的权限对象（包含数据库生成的主键） + * @throws BusinessException 如果权限代码已存在 + */ @Transactional public Permission create(Permission permission) { if (permissionRepository.existsByCode(permission.getCode())) { @@ -45,11 +103,22 @@ public class PermissionService { } return permissionRepository.save(permission); } - + + /** + * 更新权限信息 + * + *仅更新传入参数中非空的字段，保持其他字段不变。 + * 如果权限不存在，抛出PERMISSION_002业务异常。
+ * + * @param id 要更新的权限ID + * @param permission 包含新数据的权限对象 + * @return 更新后的权限对象 + * @throws BusinessException 如果权限不存在 + */ @Transactional public Permission update(UUID id, Permission permission) { Permission existing = findById(id); - + if (permission.getName() != null) { existing.setName(permission.getName()); } @@ -71,12 +140,19 @@ public class PermissionService { if (permission.getSortOrder() != null) { existing.setSortOrder(permission.getSortOrder()); } - + return permissionRepository.save(existing); } - + + /** + * 删除权限 + * + *根据权限ID删除权限记录。
+ * + * @param id 要删除的权限ID + */ @Transactional public void delete(UUID id) { permissionRepository.deleteById(id); } -} +} \ No newline at end of file diff --git a/module-auth/src/main/java/com/ether/pms/auth/service/RoleService.java b/module-auth/src/main/java/com/ether/pms/auth/service/RoleService.java index e8e2bb0..71f39ea 100644 --- a/module-auth/src/main/java/com/ether/pms/auth/service/RoleService.java +++ b/module-auth/src/main/java/com/ether/pms/auth/service/RoleService.java @@ -15,32 +15,88 @@ import org.springframework.transaction.annotation.Transactional; import java.util.List; import java.util.UUID; +/** + * 角色业务逻辑服务类 + * + *提供角色（Role）相关的业务操作，包括角色的增删改查、权限分配、用户关联等功能。 + * 所有操作均支持事务管理，确保数据一致性。
+ * + * @author Ether开发团队 + * @version 1.0.0 + * @since 2024-01-01 + */ @Service @RequiredArgsConstructor public class RoleService { - + + /** 角色数据访问仓库 */ private final RoleRepository roleRepository; + + /** 权限数据访问仓库 */ private final PermissionRepository permissionRepository; + + /** 用户数据访问仓库 */ private final UserRepository userRepository; - + + /** + * 查询所有角色 + * + * @return 所有角色的列表 + */ public List如果角色不存在，抛出ROLE_002业务异常。
+ * + * @param id 角色ID + * @return 角色对象 + * @throws BusinessException 如果角色不存在 + */ public Role findById(UUID id) { return roleRepository.findById(id) .orElseThrow(() -> new BusinessException(ErrorCode.ROLE_002)); } - + + /** + * 根据角色代码查询角色 + * + *如果角色不存在，抛出ROLE_002业务异常。
+ * + * @param code 角色代码 + * @return 角色对象 + * @throws BusinessException 如果角色不存在 + */ public Role findByCode(String code) { return roleRepository.findByCode(code) .orElseThrow(() -> new BusinessException(ErrorCode.ROLE_002)); } - + + /** + * 根据项目ID查询角色列表 + * + *获取指定项目下的所有角色。
+ * + * @param projectId 项目ID + * @return 该项目下的角色列表 + */ public List如果角色代码已存在，抛出ROLE_001业务异常。 + * 创建时会自动设置创建时间和更新时间。
+ * + * @param role 要创建的角色对象 + * @return 创建后的角色对象（包含数据库生成的主键） + * @throws BusinessException 如果角色代码已存在 + */ @Transactional public Role create(Role role) { if (roleRepository.existsByCode(role.getCode())) { @@ -48,11 +104,22 @@ public class RoleService { } return roleRepository.save(role); } - + + /** + * 更新角色信息 + * + *仅更新传入参数中非空的字段，保持其他字段不变。 + * 如果角色不存在，抛出ROLE_002业务异常。
+ * + * @param id 要更新的角色ID + * @param role 包含新数据的角色对象 + * @return 更新后的角色对象 + * @throws BusinessException 如果角色不存在 + */ @Transactional public Role update(UUID id, Role role) { Role existing = findById(id); - + if (role.getName() != null) { existing.setName(role.getName()); } @@ -71,10 +138,20 @@ public class RoleService { if (role.getStatus() != null) { existing.setStatus(role.getStatus()); } - + return roleRepository.save(existing); } - + + /** + * 为角色分配权限 + * + *替换角色原有的所有权限为新分配的权限列表。 + * 如果角色或权限不存在，抛出相应业务异常。
+ * + * @param roleId 角色ID + * @param permissionIds 要分配的权限ID列表 + * @throws BusinessException 如果角色或权限不存在 + */ @Transactional public void assignPermissions(UUID roleId, List