luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
84 Commits
1 Branch
0 Tags
403 MiB
Tree: 8a078932ad
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '8a078932ad'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/数据模型/用户认证模型.md

528 lines
26 KiB
Raw Normal View History

first-commit
1 month ago
# 用户认证模型
<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)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [AuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java)
- [AuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [IAuthIdentityService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthIdentityService.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件聚焦于用户认证数据模型，围绕 AuthUser、AuthIdentity 等核心实体进行系统化说明，涵盖字段定义、数据类型与业务含义；阐述用户身份验证机制、多身份支持、登录结果数据结构；解释用户状态管理、密码加密存储、第三方身份集成；并提供实体关系图、字段约束与默认值设置；最后总结用户信息 DTO 的设计模式与数据传输规范，为开发者提供完整的用户认证数据模型参考。
## 项目结构
认证相关代码主要位于 crm-auth 模块，采用分层架构：
- controller：对外暴露认证接口
- service：业务逻辑层（认证、用户、身份）
- domain：领域对象（entity、dto、param、enums）
- security：安全配置与令牌处理
- config：安全与初始化配置
- mapper：数据访问映射
```mermaid
graph TB
subgraph "crm-auth"
C["controller<br/>AuthController"] --> S["service<br/>AuthServiceImpl / IAuthService"]
S --> SU["service<br/>AuthUserServiceImpl / IAuthUserService"]
S --> SI["service<br/>AuthIdentityServiceImpl / IAuthIdentityService"]
S --> T["security<br/>TokenService"]
S --> D["domain/entity<br/>AuthUser / AuthIdentity"]
S --> E["domain/enums<br/>IdentityTypeEnum"]
S --> F["service/client<br/>ThirdPartyAuthClient / DingTalkAuthClient"]
C --> P["domain/param<br/>LoginParam"]
S --> R["domain/dto<br/>LoginResultDTO / UserInfoDTO"]
end
subgraph "crm-base"
B["domain/entity<br/>BaseEntity"]
ST["domain/enums<br/>StatusEnum"]
end
D --> B
D --> ST
```
**图表来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.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)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
**章节来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
## 核心组件
- AuthUser：用户主实体，承载用户基本信息、状态、时间戳等，继承基础实体以统一审计字段。
- AuthIdentity：用户身份记录，用于支撑多身份（如手机号、邮箱、第三方平台账号），通过类型枚举区分不同身份源。
- LoginParam：登录请求参数，包含用户名/标识与凭证等。
- LoginResultDTO：登录响应数据，包含令牌、用户信息与权限摘要。
- UserInfoDTO：用户信息传输对象，面向前端展示与跨服务传输。
- IdentityTypeEnum：身份类型枚举，定义系统内支持的各类身份来源。
- TokenService：令牌生成与校验，负责 JWT 生命周期管理。
- ThirdPartyAuthClient 系列：第三方身份客户端抽象与工厂，支持钉钉等外部身份提供商。
**章节来源**
- [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)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
## 架构总览
认证流程从控制器进入，经服务层完成用户校验、身份匹配、令牌签发，并可选地对接第三方身份提供商。JWT 过滤器在后续请求中完成鉴权上下文构建。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "AuthController"
participant Service as "AuthServiceImpl"
participant UserSvc as "AuthUserServiceImpl"
participant IdSvc as "AuthIdentityServiceImpl"
participant Token as "TokenService"
participant Third as "ThirdPartyAuthClient"
Client->>Controller : "提交登录参数(LoginParam)"
Controller->>Service : "调用登录接口"
Service->>UserSvc : "根据标识查询用户"
UserSvc-->>Service : "返回用户实体(AuthUser)"
Service->>IdSvc : "校验身份凭证(含第三方)"
IdSvc-->>Service : "返回身份校验结果"
Service->>Third : "若为第三方则获取外部用户信息"
Third-->>Service : "返回第三方用户信息"
Service->>Token : "生成访问令牌"
Token-->>Service : "返回令牌"
Service-->>Controller : "组装登录结果(LoginResultDTO)"
Controller-->>Client : "返回登录结果"
```
**图表来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
## 详细组件分析
### 实体：AuthUser（用户主实体）
- 继承基础实体 BaseEntity，获得统一的审计字段（如创建/更新时间、创建人等）。
- 关键字段建议包括：
- 用户标识：唯一主键
- 用户名/显示名：用于展示与检索
- 状态：使用 StatusEnum 表示启用/禁用等
- 密码：加密存储，禁止明文
- 扩展字段：头像、联系方式、部门/角色关联ID等
- 业务含义：代表系统内的一个用户主体，作为登录与授权的核心。
```mermaid
classDiagram
class BaseEntity {
+id
+createTime
+updateTime
+createBy
+updateBy
}
class AuthUser {
+userId
+username
+displayName
+status
+password
+avatar
+contact
+deptId
+roleId
+isActive()
+getProfile()
}
class StatusEnum {
+ACTIVE
+DISABLED
}
AuthUser --|> BaseEntity : "继承"
AuthUser --> StatusEnum : "使用"
```
**图表来源**
- [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)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
**章节来源**
- [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)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
### 实体：AuthIdentity（用户身份记录）
- 用于支撑多身份：同一用户可绑定多个身份（如手机号、邮箱、第三方平台账号）。
- 关键字段建议包括：
- 身份标识：唯一主键
- 用户ID：外键关联到 AuthUser
- 身份类型：IdentityTypeEnum（如 phone、email、dingtalk 等）
- 身份值：具体标识（如手机号、邮箱地址、第三方 openId）
- 是否默认：标记该身份是否为登录首选
- 状态：启用/禁用
- 业务含义：解耦用户与具体登录标识，支持灵活的身份管理与扩展。
```mermaid
classDiagram
class AuthIdentity {
+identityId
+userId
+identityType
+identityValue
+isDefault
+status
+validate()
+bindToUser(userId)
}
class IdentityTypeEnum {
+PHONE
+EMAIL
+DINGTALK
+OTHER
}
AuthIdentity --> IdentityTypeEnum : "使用"
```
**图表来源**
- [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)
**章节来源**
- [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)
### 登录参数与结果：LoginParam、LoginResultDTO、UserInfoDTO
- LoginParam：登录请求体，包含身份标识与凭证（如用户名/手机号与密码或第三方授权码）。
- LoginResultDTO：登录响应体，包含访问令牌、刷新令牌（可选）、用户信息摘要、权限集合等。
- UserInfoDTO：用户信息传输对象，屏蔽敏感字段（如密码），仅暴露必要展示字段。
```mermaid
classDiagram
class LoginParam {
+identity
+credential
+provider
}
class LoginResultDTO {
+accessToken
+refreshToken
+expiresIn
+userInfo
+permissions
}
class UserInfoDTO {
+userId
+username
+displayName
+avatar
+roles
+departments
}
LoginResultDTO --> UserInfoDTO : "包含"
```
**图表来源**
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
**章节来源**
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
### 用户状态管理与密码加密存储
- 用户状态：通过 StatusEnum 控制启用/禁用，服务层在登录时检查状态，禁用用户拒绝登录。
- 密码加密：密码字段必须使用强哈希算法（如 BCrypt）存储，禁止明文；登录时比对哈希值而非明文。
- 默认值与约束：
- 状态默认启用
- 用户名唯一
- 身份值唯一（按类型+值组合）
- 必填字段校验（用户名、密码、身份值）
```mermaid
flowchart TD
Start(["登录入口"]) --> CheckStatus["检查用户状态"]
CheckStatus --> StatusOK{"状态有效?"}
StatusOK --> |否| Deny["拒绝登录(状态异常)"]
StatusOK --> |是| VerifyPwd["校验密码(哈希比对)"]
VerifyPwd --> PwdOK{"密码正确?"}
PwdOK --> |否| Deny
PwdOK --> |是| IssueToken["签发令牌(TokenService)"]
IssueToken --> Return["返回登录结果(LoginResultDTO)"]
```
**图表来源**
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
**章节来源**
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
### 多身份支持与第三方身份集成
- 多身份：AuthIdentity 通过 identityType 区分不同来源，支持同一用户绑定多个身份；登录时根据 identity 查找对应身份记录，再关联用户。
- 第三方集成：ThirdPartyAuthClient 抽象统一接口，DingTalkAuthClient 实现钉钉登录；ThirdPartyAuthClientFactory 根据 provider 选择具体客户端。
- 第三方用户信息：ThirdPartyUserInfo 封装外部平台返回的用户属性，映射到系统用户与身份记录。
```mermaid
classDiagram
class ThirdPartyAuthClient {
+authenticate(provider, code) ThirdPartyUserInfo
+getUserInfo(openId) ThirdPartyUserInfo
}
class DingTalkAuthClient {
+authenticate(provider, code) ThirdPartyUserInfo
+getUserInfo(openId) ThirdPartyUserInfo
}
class ThirdPartyAuthClientFactory {
+getClient(provider) ThirdPartyAuthClient
}
class ThirdPartyUserInfo {
+openId
+nickname
+avatar
+email
+phone
}
ThirdPartyAuthClient <|-- DingTalkAuthClient : "实现"
ThirdPartyAuthClientFactory --> ThirdPartyAuthClient : "创建"
ThirdPartyAuthClient --> ThirdPartyUserInfo : "返回"
```
**图表来源**
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
**章节来源**
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
### 登录流程序列图（含第三方）
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "AuthController"
participant Service as "AuthServiceImpl"
participant IdSvc as "AuthIdentityServiceImpl"
participant Third as "DingTalkAuthClient"
participant Token as "TokenService"
Client->>Controller : "POST /auth/login (LoginParam)"
Controller->>Service : "login(param)"
Service->>IdSvc : "resolveIdentity(identity, provider)"
alt "第三方登录"
Service->>Third : "authenticate(provider, code)"
Third-->>Service : "ThirdPartyUserInfo"
Service->>IdSvc : "bindOrFindIdentity(userInfo)"
else "本地登录"
Service->>IdSvc : "verifyLocalCredential(identity, credential)"
end
Service->>Token : "generateToken(user)"
Token-->>Service : "accessToken"
Service-->>Controller : "LoginResultDTO"
Controller-->>Client : "200 OK"
```
**图表来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
**章节来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
### 实体关系图（ER）
```mermaid
erDiagram
AUTH_USER {
bigint id PK
string username UK
string display_name
enum status
string password
string avatar
string contact
bigint dept_id
bigint role_id
timestamp created_at
timestamp updated_at
}
AUTH_IDENTITY {
bigint id PK
bigint user_id FK
enum identity_type
string identity_value UK
boolean is_default
enum status
timestamp created_at
timestamp updated_at
}
AUTH_USER ||--o{ AUTH_IDENTITY : "拥有多个身份"
```
**图表来源**
- [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)
**章节来源**
- [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)
## 依赖关系分析
- 控制器依赖服务层，服务层依赖用户与身份服务，以及令牌服务与第三方客户端。
- 实体依赖基础实体与枚举，保证审计与状态一致性。
- 第三方客户端通过工厂按需实例化，避免耦合具体提供商。
```mermaid
graph LR
AC["AuthController"] --> AS["AuthServiceImpl"]
AS --> AUS["AuthUserServiceImpl"]
AS --> AIS["AuthIdentityServiceImpl"]
AS --> TS["TokenService"]
AS --> TP["ThirdPartyAuthClient"]
TP --> DT["DingTalkAuthClient"]
TP --> TF["ThirdPartyAuthClientFactory"]
AU["AuthUser"] --> BE["BaseEntity"]
AI["AuthIdentity"] --> IT["IdentityTypeEnum"]
```
**图表来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
**章节来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
## 性能考虑
- 令牌签发与校验：TokenService 应缓存密钥与配置，减少重复计算；JWT 体积适中，避免携带过多用户信息。
- 身份查询：AuthIdentity 的 identity_type + identity_value 建立复合索引，提升多身份检索效率。
- 第三方调用：对第三方 API 增加超时与重试策略，必要时引入缓存与降级。
- 密码校验：BCrypt 开销较大，建议在并发场景下合理限制并发度与连接池大小。
[本节为通用指导，不直接分析具体文件]
## 故障排查指南
- 登录失败常见原因：
- 用户状态禁用：检查 StatusEnum 与用户状态字段
- 密码错误：确认密码哈希是否正确更新
- 身份不存在或冲突：检查 AuthIdentity 的唯一性约束
- 第三方回调异常：核对 provider、code、openId 映射
- 调试建议：
- 打印登录参数与解析结果
- 查看令牌生成与校验日志
- 检查第三方客户端返回结构与字段映射
**章节来源**
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
## 结论
本模型通过 AuthUser 与 AuthIdentity 的解耦设计，实现了用户与身份的灵活绑定与多身份支持；结合 TokenService 与第三方客户端抽象，构建了可扩展的认证体系。遵循 DTO 最小暴露原则与枚举化状态管理，确保数据安全与可维护性。建议在生产环境完善索引、缓存与监控，保障认证性能与稳定性。
[本节为总结性内容，不直接分析具体文件]
## 附录
- 字段约束与默认值建议：
- 用户名唯一、非空
- 身份值按类型唯一
- 状态默认启用
- 时间戳由基础实体自动填充
- 数据传输规范：
- LoginParam 仅包含必要登录字段
- LoginResultDTO 不包含敏感信息（如密码）
- UserInfoDTO 仅暴露展示所需字段
[本节为补充说明，不直接分析具体文件]