crm-backend-matt/.qoder/repowiki/zh/content/项目概览/模块说明/认证服务模块(crm-auth)/领域模型与实体.md

# 领域模型与实体

<cite>
**本文引用的文件**   
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java)
- [AuthIdentityMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthIdentityMapper.java)
- [SysDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysDeptMapper.java)
- [SysUserRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserRoleMapper.java)
- [SysRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMapper.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [SysUserDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserDeptMapper.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)
</cite>

## 更新摘要
**变更内容**   
- 新增用户列表相关的参数类 UserPageParam，用于分页查询用户信息
- 新增用户列表数据传输对象 UserListDTO，用于返回用户基本信息
- 新增用户统计视图对象 UserStatsVO，用于展示用户统计数据
- 完善了用户管理的领域模型，增强了用户查询和统计功能

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本章节聚焦认证相关的领域模型与实体设计，围绕用户、身份标识、部门、角色与菜单等核心对象，阐述实体关系映射、枚举类型定义、数据验证规则，以及数据库表结构设计、字段含义与业务约束。文档旨在帮助开发者快速理解并正确使用这些实体，确保权限控制、数据范围与多源身份接入的一致性与可维护性。

**更新** 新增了用户列表相关的参数类和数据传输对象，完善了用户管理的领域模型，支持更灵活的用户查询和统计功能。

## 项目结构
认证域位于 crm-auth 模块，基础通用能力位于 crm-base 模块。实体类集中在 domain/entity 包下，枚举在 domain/enums 包下，数据传输对象在 domain/dto 包下，参数类在 domain/param 包下，数据访问层在 mapper 包下，服务实现位于 service/impl 包中。基础实体 BaseEntity 与 OwnedEntity 提供公共字段与审计能力，MyBatis-Plus 配置与填充策略由 base 模块统一提供。

```mermaid
graph TB
subgraph "认证域(crm-auth)"
A["AuthUser"] --> B["AuthIdentity"]
A --> C["SysUserRole"]
C --> D["SysRole"]
D --> E["SysRoleMenu"]
E --> F["SysMenu"]
A --> G["SysUserDept"]
G --> H["SysDept"]
I["UserPageParam"] --> A
J["UserListDTO"] --> A
K["UserStatsVO"] --> A
end
subgraph "基础域(crm-base)"
L["BaseEntity"] --> A
M["OwnedEntity"] --> A
N["CrmBaseMapper"] --> O["各Mapper接口"]
end
O --> P["MyBatis-Plus配置"]
```

图表来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)

章节来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

## 核心组件
本节概述认证相关核心实体的职责与关系：
- AuthUser 用户实体：系统内用户的主体信息，关联身份标识、角色与部门。
- AuthIdentity 身份标识：支持多种登录来源（如账号密码、第三方平台），通过类型区分。
- SysDept 部门实体：组织树形结构，用于数据范围与权限隔离。
- SysUserRole 用户角色关联：多对多关系，承载用户与角色的绑定。
- SysRole 角色实体：权限集合的载体，与菜单存在多对多关系。
- SysMenu 菜单实体：功能点与资源标识，支撑菜单与按钮级权限。
- SysRoleMenu 角色菜单关联：角色与菜单的多对多中间表。
- SysUserDept 用户部门关联：用户与部门的归属关系，支撑数据可见范围。
- **新增** UserPageParam 用户分页查询参数：用于构建用户列表的分页查询条件。
- **新增** UserListDTO 用户列表数据传输对象：封装用户基本信息用于列表展示。
- **新增** UserStatsVO 用户统计视图对象：聚合用户统计数据用于管理界面展示。

章节来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

## 架构总览
下图展示认证域实体之间的关系与数据流向，包括用户、身份、角色、菜单与部门的关联，以及基础实体提供的公共字段与审计能力。新增的用户列表相关对象提供了更好的数据封装和查询能力。

```mermaid
classDiagram
class BaseEntity {
+id
+createBy
+createTime
+updateBy
+updateTime
+remark
}
class OwnedEntity {
+ownerId
+ownerType
}
class AuthUser {
+username
+status
+deptIds
+roleIds
}
class AuthIdentity {
+userId
+identityType
+thirdPartyId
+credential
}
class SysDept {
+parentId
+name
+sort
+status
}
class SysUserRole {
+userId
+roleId
}
class SysRole {
+code
+name
+status
}
class SysMenu {
+parentId
+type
+path
+permission
+status
}
class SysRoleMenu {
+roleId
+menuId
}
class SysUserDept {
+userId
+deptId
}
class UserPageParam {
+pageNum
+pageSize
+keyword
+status
+deptId
}
class UserListDTO {
+id
+username
+nickname
+phone
+email
+status
+deptName
+roleNames
}
class UserStatsVO {
+totalUsers
+activeUsers
+inactiveUsers
+deptStats
+roleStats
}
BaseEntity <|-- AuthUser
BaseEntity <|-- SysDept
BaseEntity <|-- SysRole
BaseEntity <|-- SysMenu
OwnedEntity <|-- AuthUser
AuthUser "1" o-- "n" AuthIdentity : "一对多"
AuthUser "1" o-- "n" SysUserRole : "多对多"
SysRole "1" o-- "n" SysUserRole : "多对多"
SysRole "1" o-- "n" SysRoleMenu : "多对多"
SysMenu "1" o-- "n" SysRoleMenu : "多对多"
AuthUser "1" o-- "n" SysUserDept : "多对多"
SysDept "1" o-- "n" SysUserDept : "多对多"
UserPageParam --> AuthUser : "查询条件"
UserListDTO --> AuthUser : "数据展示"
UserStatsVO --> AuthUser : "统计分析"
```

图表来源
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

## 详细组件分析

### AuthUser 用户实体
- 职责：表示系统用户主记录，承载用户名、状态、所属部门与角色等关键信息。
- 继承关系：继承 BaseEntity 与 OwnedEntity，获得通用审计字段与数据所有者标记。
- 关联关系：
  - 与 AuthIdentity 一对多：一个用户可拥有多个身份标识（如手机号、邮箱、第三方ID）。
  - 与 SysUserRole 多对多：通过中间表建立用户与角色的绑定。
  - 与 SysUserDept 多对多：通过中间表建立用户与部门的归属。
- 数据验证与约束：
  - 用户名唯一性、非空校验。
  - 状态字段受 StatusEnum 约束，仅允许有效值。
  - 部门与角色通过中间表维护，避免冗余与不一致。
- 使用示例：
  - 注册新用户时创建 AuthUser，并插入一条或多条 AuthIdentity。
  - 分配角色与部门时写入 SysUserRole 与 SysUserDept。
  - 查询用户权限时，基于角色与菜单关联计算可用权限集。

章节来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)

### AuthIdentity 身份标识
- 职责：抽象不同登录来源的身份凭证，支持账号密码与第三方平台登录。
- 关键字段：
  - identityType：身份类型，受 IdentityTypeEnum 约束（如账号、第三方）。
  - thirdPartyId：第三方平台的唯一标识。
  - credential：加密后的凭证或令牌。
- 数据验证与约束：
  - 同一 userId 下 identityType 唯一，防止重复来源冲突。
  - 第三方登录需校验 thirdPartyId 的唯一性。
- 使用示例：
  - 第三方授权回调时，根据 identityType 与 thirdPartyId 查找或创建 AuthIdentity。
  - 账号密码登录时，校验 credential 并与 AuthUser 关联。

章节来源
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)

### SysDept 部门实体
- 职责：组织部门树，支撑数据范围与权限隔离。
- 关键字段：
  - parentId：父部门ID，根节点为空或特定值。
  - name：部门名称。
  - sort：排序权重。
  - status：状态受 StatusEnum 约束。
- 数据验证与约束：
  - 父子层级关系自引用，禁止循环引用。
  - 名称唯一性在同一父级下校验。
- 使用示例：
  - 初始化部门树时按 sort 顺序构建。
  - 数据范围过滤时，依据用户所属部门及其子部门生成 SQL 条件。

章节来源
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### SysUserRole 用户角色关联
- 职责：用户与角色的多对多中间表，承载授权关系。
- 关键字段：
  - userId：用户ID。
  - roleId：角色ID。
- 数据验证与约束：
  - (userId, roleId) 组合唯一，避免重复授权。
  - 外键约束保证引用完整性。
- 使用示例：
  - 为用户分配角色时批量插入 SysUserRole。
  - 撤销角色时删除对应记录。

章节来源
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)

### SysRole 角色实体
- 职责：权限集合的载体，描述一组可访问的资源与操作。
- 关键字段：
  - code：角色编码，全局唯一。
  - name：角色名称。
  - status：状态受 StatusEnum 约束。
- 数据验证与约束：
  - code 唯一性校验。
  - 状态变更需遵循业务流程。
- 使用示例：
  - 创建系统预设角色（管理员、普通用户）并分配菜单权限。

章节来源
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### SysMenu 菜单实体
- 职责：功能点与资源标识，支撑菜单与按钮级权限。
- 关键字段：
  - parentId：父菜单ID，形成树形结构。
  - type：菜单类型，受 MenuTypeEnum 约束（目录、菜单、按钮）。
  - path：路由路径。
  - permission：权限标识。
  - status：状态受 StatusEnum 约束。
- 数据验证与约束：
  - 父子层级关系自引用，禁止循环引用。
  - permission 唯一性校验。
- 使用示例：
  - 前端根据菜单树渲染导航。
  - 后端基于 permission 进行接口级鉴权。

章节来源
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### SysRoleMenu 角色菜单关联
- 职责：角色与菜单的多对多中间表，承载菜单授权。
- 关键字段：
  - roleId：角色ID。
  - menuId：菜单ID。
- 数据验证与约束：
  - (roleId, menuId) 组合唯一。
  - 外键约束保证引用完整性。
- 使用示例：
  - 为角色批量授权菜单时插入多条记录。
  - 取消授权时删除对应记录。

章节来源
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)

### SysUserDept 用户部门关联
- 职责：用户与部门的归属关系，支撑数据可见范围。
- 关键字段：
  - userId：用户ID。
  - deptId：部门ID。
- 数据验证与约束：
  - (userId, deptId) 组合唯一。
  - 外键约束保证引用完整性。
- 使用示例：
  - 用户加入部门后插入记录。
  - 数据范围过滤时，结合 DataScopeEnum 决定查询范围。

章节来源
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)

### UserPageParam 用户分页查询参数
- 职责：封装用户列表分页查询的条件参数，支持多维度筛选。
- 关键字段：
  - pageNum：当前页码，用于分页查询。
  - pageSize：每页大小，限制返回结果数量。
  - keyword：关键词搜索，支持用户名、昵称、手机号模糊匹配。
  - status：用户状态筛选，支持启用/禁用过滤。
  - deptId：部门ID筛选，限定特定部门的用户。
- 数据验证与约束：
  - 页码和页大小需要进行合理性校验。
  - 关键词长度限制，防止SQL注入攻击。
  - 状态值必须在枚举范围内。
- 使用示例：
  - 前端传递分页参数调用用户列表接口。
  - 后端根据参数动态构建查询条件。

章节来源
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)

### UserListDTO 用户列表数据传输对象
- 职责：封装用户基本信息用于列表展示，包含用户与部门、角色的关联信息。
- 关键字段：
  - id：用户ID。
  - username：用户名。
  - nickname：用户昵称。
  - phone：手机号码。
  - email：电子邮箱。
  - status：用户状态。
  - deptName：所属部门名称。
  - roleNames：角色名称列表。
- 数据转换：
  - 从 AuthUser 实体转换为 DTO 对象。
  - 关联查询部门和角色信息。
- 使用示例：
  - 用户列表接口返回此对象数组。
  - 前端直接用于表格展示。

章节来源
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)

### UserStatsVO 用户统计视图对象
- 职责：聚合用户统计数据，用于管理界面的统计展示。
- 关键字段：
  - totalUsers：用户总数。
  - activeUsers：活跃用户数。
  - inactiveUsers：非活跃用户数。
  - deptStats：各部门用户分布统计。
  - roleStats：各角色用户分布统计。
- 数据来源：
  - 基于 AuthUser 实体进行聚合查询。
  - 结合部门、角色信息进行多维度统计。
- 使用示例：
  - 用户管理首页展示统计概览。
  - 数据分析报表的基础数据源。

章节来源
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

### 枚举类型定义
- IdentityTypeEnum：身份类型枚举，区分账号、第三方等平台来源。
- DataScopeEnum：数据范围枚举，定义个人、本部门、本部门及子部门、全部等范围。
- MenuTypeEnum：菜单类型枚举，区分目录、菜单、按钮。
- StatusEnum：通用状态枚举，定义启用、禁用等状态。
- HasValueEnum：通用有值/无值枚举，用于布尔语义化表达。

章节来源
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)

### 数据库表结构设计
以下为认证域核心表的建议结构与字段说明（以实际实体与约定为准）：
- auth_user
  - id: 主键
  - username: 用户名（唯一）
  - status: 状态（受 StatusEnum 约束）
  - owner_id: 数据所有者ID
  - owner_type: 数据所有者类型
  - create_by/create_time/update_by/update_time/remark: 审计字段
- auth_identity
  - id: 主键
  - user_id: 用户ID（外键）
  - identity_type: 身份类型（受 IdentityTypeEnum 约束）
  - third_party_id: 第三方ID（唯一）
  - credential: 凭证（加密存储）
  - 审计字段同上
- sys_dept
  - id: 主键
  - parent_id: 父部门ID
  - name: 部门名称
  - sort: 排序
  - status: 状态
  - 审计字段同上
- sys_user_role
  - id: 主键
  - user_id: 用户ID（外键）
  - role_id: 角色ID（外键）
  - 唯一约束(user_id, role_id)
- sys_role
  - id: 主键
  - code: 角色编码（唯一）
  - name: 角色名称
  - status: 状态
  - 审计字段同上
- sys_menu
  - id: 主键
  - parent_id: 父菜单ID
  - type: 菜单类型（受 MenuTypeEnum 约束）
  - path: 路由路径
  - permission: 权限标识（唯一）
  - status: 状态
  - 审计字段同上
- sys_role_menu
  - id: 主键
  - role_id: 角色ID（外键）
  - menu_id: 菜单ID（外键）
  - 唯一约束(role_id, menu_id)
- sys_user_dept
  - id: 主键
  - user_id: 用户ID（外键）
  - dept_id: 部门ID（外键）
  - 唯一约束(user_id, dept_id)

**更新** 新增的用户列表相关对象主要用于数据传输和查询条件封装，不直接对应数据库表结构。

章节来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

### 数据验证规则与业务约束
- 唯一性约束：
  - 用户名、角色编码、菜单权限标识、第三方ID、(userId, identityType)、(userId, roleId)、(roleId, menuId)、(userId, deptId) 等组合唯一。
- 状态约束：
  - 所有状态字段受 StatusEnum 约束，仅允许预定义值。
- 层级约束：
  - 部门与菜单的父子关系禁止循环引用，需在应用层校验。
- 数据范围：
  - 数据范围受 DataScopeEnum 控制，结合用户部门与角色权限生成查询条件。
- 审计字段：
  - 通过 MetaObjectFillHandler 自动填充创建与更新时间、操作人等。
- **新增** 参数验证：
  - 分页参数需要进行边界值校验。
  - 搜索关键词需要进行长度和特殊字符过滤。
  - 状态筛选值必须在枚举范围内。

章节来源
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)

### 使用示例
- 用户注册与身份绑定：
  - 创建 AuthUser，插入 AuthIdentity（identityType=账号，credential=加密密码）。
  - 分配角色与部门：写入 SysUserRole 与 SysUserDept。
- 第三方登录流程：
  - 根据第三方回调获取 thirdPartyId，查找或创建 AuthIdentity（identityType=第三方）。
  - 校验成功后返回用户上下文。
- 权限与菜单加载：
  - 基于用户角色与 SysRoleMenu 获取菜单树。
  - 接口鉴权时校验 permission 是否命中。
- **新增** 用户列表查询：
  - 构建 UserPageParam 参数对象，设置分页条件和筛选条件。
  - 调用服务层方法获取 UserListDTO 列表。
  - 将结果转换为前端需要的格式。
- **新增** 用户统计：
  - 调用统计接口获取 UserStatsVO 对象。
  - 在管理界面展示用户分布和状态统计。

章节来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

## 依赖关系分析
认证域实体依赖基础域的公共实体与配置，数据访问层通过 MyBatis-Plus 的 Mapper 接口进行 CRUD 操作。新增的用户列表相关对象增强了数据传输和查询能力。

```mermaid
graph LR
A["AuthUser"] --> B["AuthIdentity"]
A --> C["SysUserRole"]
C --> D["SysRole"]
D --> E["SysRoleMenu"]
E --> F["SysMenu"]
A --> G["SysUserDept"]
G --> H["SysDept"]
I["BaseEntity"] --> A
J["OwnedEntity"] --> A
K["CrmBaseMapper"] --> L["AuthUserMapper"]
K --> M["AuthIdentityMapper"]
K --> N["SysDeptMapper"]
K --> O["SysUserRoleMapper"]
K --> P["SysRoleMapper"]
K --> Q["SysMenuMapper"]
K --> R["SysRoleMenuMapper"]
K --> S["SysUserDeptMapper"]
T["UserPageParam"] --> A
U["UserListDTO"] --> A
V["UserStatsVO"] --> A
```

图表来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java)
- [AuthIdentityMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthIdentityMapper.java)
- [SysDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysDeptMapper.java)
- [SysUserRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserRoleMapper.java)
- [SysRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMapper.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [SysUserDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserDeptMapper.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

章节来源
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java)
- [AuthIdentityMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthIdentityMapper.java)
- [SysDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysDeptMapper.java)
- [SysUserRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserRoleMapper.java)
- [SysRoleMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMapper.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [SysUserDeptMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysUserDeptMapper.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)

## 性能考虑
- 索引优化：
  - 为高频查询字段建立索引，如 user_id、identity_type、third_party_id、role_id、menu_id、dept_id。
  - 组合唯一约束自动创建复合索引，提升去重与关联查询效率。
- 缓存策略：
  - 部门树与菜单树可缓存，减少重复构建成本。
  - 用户权限集可在会话或Redis中缓存，缩短鉴权路径。
  - **新增** 用户统计数据可缓存，减少频繁聚合查询。
- 批量操作：
  - 批量插入角色菜单与用户部门关联，降低事务开销。
- 分页与投影：
  - 列表查询使用分页与必要字段投影，减少网络传输与内存占用。
  - **新增** UserPageParam 支持精确的分页查询，避免全表扫描。
- **新增** 数据传输优化：
  - UserListDTO 只包含必要的展示字段，减少数据传输量。
  - UserStatsVO 预先聚合统计数据，避免前端重复计算。

## 故障排查指南
- 常见错误与定位：
  - 唯一性冲突：检查用户名、角色编码、菜单权限标识、第三方ID等是否重复。
  - 层级循环：校验部门与菜单的父子关系，避免闭环。
  - 状态非法：确认状态字段取值是否在枚举范围内。
  - 审计字段未填充：检查 MetaObjectFillHandler 是否正确配置。
  - **新增** 分页参数错误：检查页码和页大小是否为正数。
  - **新增** 搜索条件异常：检查关键词是否包含特殊字符或过长。
- 调试建议：
  - 开启SQL日志，观察生成的SQL与参数。
  - 使用单元测试覆盖注册、授权、鉴权流程。
  - 通过日志追踪用户上下文与数据范围计算过程。
  - **新增** 测试用户列表查询接口的各种参数组合。
  - **新增** 验证数据统计的准确性。

章节来源
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)

## 结论
认证域实体围绕用户、身份、角色、菜单与部门构建了完整的权限与数据范围体系。通过统一的基类与枚举约束，确保了数据一致性与可维护性。配合 MyBatis-Plus 的数据访问层与填充策略，实现了高效的CRUD与审计能力。

**更新** 新增的用户列表相关参数类和数据传输对象进一步完善了用户管理功能，提供了更灵活的分页查询、数据展示和统计分析能力。建议在开发中严格遵循唯一性、层级与状态约束，合理使用索引与缓存，保障系统性能与稳定性。同时充分利用新的数据传输对象，简化前后端交互逻辑。

## 附录
- ID生成策略：
  - 使用 Snowflake 或自定义 ID 生成器，确保分布式环境下的唯一性。
- 配置项：
  - MyBatis-Plus 配置包含分页、填充、注入器等，影响实体行为与SQL生成。
- **新增** 数据传输规范：
  - UserPageParam 用于查询条件封装，支持分页和多维度筛选。
  - UserListDTO 用于列表数据展示，包含用户基本信息和关联信息。
  - UserStatsVO 用于统计数据展示，提供用户分布和状态分析。

章节来源
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [UserPageParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/UserPageParam.java)
- [UserListDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserListDTO.java)
- [UserStatsVO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserStatsVO.java)