# 身份与权限域 - 详细设计

**文档版本**: v1.0
**生成日期**: 2026-05-18
**数据来源**: module-auth 实际代码 + REVERSE-AUTH.md
**对照需求**: 05-AUTH.md

---

## 一、功能点清单

| 功能ID | 功能名称 | 优先级 | 实现状态 | 对应需求ID |
|--------|----------|--------|----------|------------|
| AUTH-001 | 用户登录 | P0 | 已实现 | 05-AUTH-001 |
| AUTH-002 | 用户登出 | P0 | 已实现 | 05-AUTH-002 |
| AUTH-003 | 获取当前用户 | P0 | 已实现 | 05-AUTH-003 |
| AUTH-004 | Token刷新 | P0 | 已实现 | 05-AUTH-004 |
| AUTH-005 | 用户CRUD | P0 | 已实现 | 05-AUTH-010 |
| AUTH-006 | 修改密码 | P0 | 已实现 | 05-AUTH-011 |
| AUTH-007 | 分配用户角色 | P0 | 已实现 | 05-AUTH-020 |
| AUTH-008 | 用户项目关联 | P1 | 已实现 | 05-AUTH-030 |
| AUTH-009 | 企业员工管理 | P1 | 已实现 | 05-AUTH-012 |
| AUTH-010 | 角色CRUD | P0 | 已实现 | 05-AUTH-020 |
| AUTH-011 | 角色权限分配 | P0 | 已实现 | 05-AUTH-021 |
| AUTH-012 | 按项目查询角色 | P1 | 已实现 | 05-AUTH-022 |
| AUTH-013 | 权限CRUD | P0 | 已实现 | 05-AUTH-025 |
| AUTH-014 | 按类型查询权限 | P1 | 已实现 | 05-AUTH-026 |
| AUTH-015 | 菜单权限查询 | P1 | 已实现 | 05-AUTH-027 |
| AUTH-016 | 部门树管理 | P1 | 已实现 | 05-AUTH-040 |
| AUTH-017 | 部门成员查询 | P1 | 已实现 | 05-AUTH-041 |
| AUTH-018 | 项目成员管理 | P0 | 已实现 | 05-AUTH-030 |
| AUTH-019 | 登录失败锁定 | P0 | 已实现 | 05-AUTH-005 |
| AUTH-020 | 密码强度校验 | P0 | 已实现 | 05-AUTH-006 |
| AUTH-021 | 弱密码检测 | P1 | 已实现 | 05-AUTH-007 |
| AUTH-022 | 审计日志查询 | P1 | 已实现 | 05-AUTH-050 |
| AUTH-023 | 审计日志统计 | P2 | 已实现 | 05-AUTH-051 |
| AUTH-024 | 系统配置管理 | P1 | 已实现 | 05-AUTH-060 |
| AUTH-025 | 数据访问授权 | P2 | 已实现(@Deprecated) | 05-AUTH-035 |
| AUTH-026 | 住户认证流程 | P1 | 已实现 | 05-AUTH-015 |
| AUTH-027 | 住户房屋绑定 | P1 | 已实现 | 05-AUTH-016 |
| AUTH-028 | 项目员工角色分配 | P1 | 已实现 | 05-AUTH-031 |

---

## 二、数据结构设计

### 2.1 实体定义

#### 2.1.1 User（用户）

**表名**: `auth_user`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 用户唯一标识符 |
| username | VARCHAR(50) | NOT NULL, UNIQUE, 正则`^[a-zA-Z0-9_]+$`, 3-50位 | 登录用户名 |
| password | VARCHAR(255) | NOT NULL, @JsonIgnore | BCrypt加密密码 |
| salt | VARCHAR | @JsonIgnore | 密码盐值（BCrypt模式下冗余） |
| realName | VARCHAR(50) | | 真实姓名 |
| phone | VARCHAR(20) | 正则`^1[3-9]\d{9}$` | 手机号码 |
| email | VARCHAR(100) | @Email | 电子邮箱 |
| avatar | VARCHAR | | 头像URL |
| status | VARCHAR(20) | NOT NULL, 默认ACTIVE, @Enumerated(STRING) | 用户状态枚举 |
| userType | VARCHAR(20) | NOT NULL | 用户类型：ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER |
| deptId | UUID | | 所属部门ID |
| lastLoginTime | LocalDateTime | | 最后登录时间 |
| lastLoginIp | VARCHAR | | 最后登录IP |
| createdAt | LocalDateTime | NOT NULL, @PrePersist自动填充 | 创建时间 |
| updatedAt | LocalDateTime | NOT NULL, @PreUpdate自动填充 | 更新时间 |
| createdBy | UUID | | 创建人ID |

**索引**:
- `auth_user_username_key` → username (UNIQUE)

**关系**:
- `roles` → M2M → Role（通过 `auth_user_role` 中间表，LAZY加载）

**中间表: auth_user_role**

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| user_id | UUID | FK → auth_user, fk_auth_user_role_user | 用户ID |
| role_id | UUID | FK → auth_role, fk_auth_user_role_role | 角色ID |

---

#### 2.1.2 Role（角色）

**表名**: `auth_role`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 角色唯一标识符 |
| code | VARCHAR(50) | NOT NULL, UNIQUE, 正则`^[a-zA-Z0-9_]+$`, 2-50位 | 角色代码 |
| name | VARCHAR(50) | NOT NULL, 2-50位 | 角色名称 |
| description | VARCHAR(200) | | 角色描述 |
| type | VARCHAR(20) | NOT NULL, @Enumerated(STRING) | 角色类型枚举 |
| dataScope | VARCHAR(20) | 默认SELF, @Enumerated(STRING) | 数据范围枚举 |
| projectId | UUID | columnDefinition=uuid | 所属项目ID（NULL=系统级） |
| status | VARCHAR(20) | NOT NULL, 默认ENABLED, @Enumerated(STRING) | 角色状态枚举 |
| createdAt | LocalDateTime | NOT NULL, @PrePersist自动填充 | 创建时间 |
| updatedAt | LocalDateTime | NOT NULL, @PreUpdate自动填充 | 更新时间 |

**索引**:
- `auth_role_code_key` → code (UNIQUE)

**关系**:
- `permissions` → M2M → Permission（通过 `auth_role_permission` 中间表，LAZY加载）

**中间表: auth_role_permission**

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| role_id | UUID | FK → auth_role, fk_auth_role_permission_role | 角色ID |
| permission_id | UUID | FK → auth_permission, fk_auth_role_permission_permission | 权限ID |

---

#### 2.1.3 Permission（权限）

**表名**: `auth_permission`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 权限唯一标识符 |
| code | VARCHAR(100) | NOT NULL, UNIQUE, 正则`^[a-zA-Z0-9_:]+$`, 2-100位 | 权限代码，格式`module:resource:action` |
| name | VARCHAR(100) | NOT NULL, 2-100位 | 权限名称 |
| type | VARCHAR(20) | | 权限类型：MENU/BUTTON/API |
| resource | VARCHAR(50) | | 资源路径（API类型） |
| method | VARCHAR(50) | | HTTP方法（API类型） |
| description | VARCHAR(200) | | 权限描述 |
| parentCode | VARCHAR(50) | | 父权限代码（树形结构） |
| path | VARCHAR(200) | | 路由路径（菜单类型） |
| component | VARCHAR(200) | | 组件路径（菜单类型） |
| icon | VARCHAR(100) | | 图标名称（菜单类型） |
| sortOrder | Integer | | 排序序号 |
| visible | Boolean | NOT NULL, 默认true | 是否可见 |
| createdAt | LocalDateTime | @PrePersist自动填充 | 创建时间 |
| updatedAt | LocalDateTime | @PreUpdate自动填充 | 更新时间 |

**索引**:
- `auth_permission_code_key` → code (UNIQUE)

**关系**:
- `roles` → M2M → Role（通过 `auth_role_permission` 中间表，LAZY加载，@JsonIgnoreProperties避免循环序列化）

---

#### 2.1.4 Dept（部门）

**表名**: `dept`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 部门唯一标识符 |
| parentId | UUID | | 上级部门ID（NULL=顶级） |
| deptName | VARCHAR(100) | NOT NULL | 部门名称 |
| deptType | VARCHAR(20) | 默认"ADMIN" | 部门类型 |
| leaderId | UUID | | 部门负责人ID |
| sortOrder | Integer | | 排序序号 |
| status | VARCHAR(20) | 默认"ACTIVE" | 状态：ACTIVE/DISABLED |
| createdAt | LocalDateTime | @PrePersist自动填充 | 创建时间 |
| updatedAt | LocalDateTime | @PreUpdate自动填充 | 更新时间 |
| createdBy | UUID | column: created_by | 创建人ID |
| updatedBy | UUID | column: updated_by | 更新人ID |

**关系**:
- 自引用树形结构：parentId → Dept.id

---

#### 2.1.5 AuditLog（审计日志）

**表名**: `sys_audit_log`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 日志ID |
| userId | UUID | column: user_id | 操作用户ID |
| username | VARCHAR(64) | NOT NULL | 操作用户名 |
| operation | VARCHAR(128) | NOT NULL | 操作描述 |
| module | VARCHAR(64) | NOT NULL | 模块标识 |
| action | VARCHAR(64) | NOT NULL, @Enumerated(STRING) | 操作类型枚举 |
| targetType | VARCHAR(64) | | 目标类型 |
| targetId | VARCHAR(64) | | 目标ID |
| content | VARCHAR(2000) | | 操作内容 |
| params | LONGVARCHAR(5000) | | 请求参数 |
| result | LONGVARCHAR(5000) | | 操作结果 |
| ipAddress | VARCHAR(64) | column: ip_address | IP地址 |
| userAgent | VARCHAR(512) | | 用户代理 |
| requestUrl | VARCHAR(512) | column: request_url | 请求URL |
| requestMethod | VARCHAR(16) | column: request_method | 请求方法 |
| executionTimeMs | Integer | column: execution_time_ms | 执行耗时(ms) |
| status | VARCHAR(16) | 默认SUCCESS, @Enumerated(STRING) | 状态枚举 |
| errorMsg | VARCHAR(2000) | column: error_msg | 错误信息 |
| createdAt | LocalDateTime | NOT NULL, @CreationTimestamp, 不可更新 | 创建时间 |
| tenantId | UUID | column: tenant_id | 租户ID |

**索引**:
- `idx_audit_log_created_at` → createdAt
- `idx_audit_log_user_id` → userId
- `idx_audit_log_module` → module
- `idx_audit_log_action` → action
- `idx_al_user_createdat` → userId, createdAt DESC

---

#### 2.1.6 EnterpriseUser（企业员工）

**表名**: `enterprise_user`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| userId | UUID | PK, FK → auth_user | 用户ID（共享主键） |
| employeeNo | VARCHAR(50) | | 员工工号 |
| deptId | UUID | | 部门ID |
| position | VARCHAR(50) | | 职位 |
| entryDate | LocalDate | | 入职日期 |
| userCategory | VARCHAR(50) | | 员工类别：ENTERPRISE/MANAGEMENT |

**关系**:
- `user` → @OneToOne → User（@MapsId共享主键）

---

#### 2.1.7 ProjectStaff（项目员工）

**表名**: `project_staff`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 主键ID |
| userId | UUID | FK → auth_user, insertable=false, updatable=false | 用户ID |
| projectId | UUID | column: project_id | 所属项目ID |
| deptId | UUID | column: dept_id | 所属部门ID |
| staffType | VARCHAR(50) | | 员工类型：SECURITY/CLEANING/GARDEN/MAINTENANCE/CUSTOMER_SERVICE/GENERAL |
| shiftType | VARCHAR(20) | | 班次类型：DAY/NIGHT/ROTATION |
| leaderId | UUID | | 班组长ID |
| assignmentStatus | VARCHAR(20) | | 在岗状态：ASSIGNED/ON_LEAVE/TRANSFERRED |
| createdAt | LocalDateTime | column: created_at, 不可更新 | 创建时间 |
| updatedAt | LocalDateTime | column: updated_at | 更新时间 |

**关系**:
- `user` → @OneToOne → User（FK: fk_project_staff_user）
- `staffRoles` → @OneToMany → ProjectStaffRole（mappedBy="staff", CASCADE=ALL, orphanRemoval=true）

---

#### 2.1.8 ProjectStaffRole（项目员工角色）

**表名**: `project_staff_role`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 主键ID |
| staff_id | UUID | FK → project_staff, NOT NULL | 关联项目员工 |
| role_id | UUID | FK → auth_role, NOT NULL | 关联角色 |
| createdAt | LocalDateTime | column: created_at, @PrePersist自动填充 | 创建时间 |

**关系**:
- `staff` → @ManyToOne(LAZY) → ProjectStaff
- `role` → @ManyToOne(EAGER) → Role

---

#### 2.1.9 Resident（住户）

**表名**: `resident`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| userId | UUID | PK, FK → auth_user | 用户ID（共享主键） |
| idCard | VARCHAR(18) | @JsonIgnore | 身份证号码 |
| residentType | VARCHAR(20) | | 住户类型：OWNER/FAMILY/TENANT |
| verificationStatus | VARCHAR(20) | | 认证状态：UNVERIFIED/PENDING/VERIFIED/REJECTED |
| verifiedAt | LocalDateTime | | 认证时间 |
| verifiedBy | UUID | | 认证人ID |
| createdAt | LocalDateTime | NOT NULL, @PrePersist自动填充 | 创建时间 |
| updatedAt | LocalDateTime | NOT NULL, @PreUpdate自动填充 | 更新时间 |
| createdBy | UUID | column: created_by | 创建人ID |
| updatedBy | UUID | column: updated_by | 更新人ID |

**关系**:
- `user` → @OneToOne → User（@MapsId共享主键）

---

#### 2.1.10 Space（房屋空间）

**表名**: `space`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 空间ID |
| projectId | UUID | column: project_id | 所属项目ID |
| building | VARCHAR(50) | | 楼栋 |
| unit | VARCHAR(50) | | 单元 |
| roomNo | VARCHAR(50) | | 房号 |
| spaceType | VARCHAR(20) | | 房屋类型：RESIDENTIAL/COMMERCIAL |
| floor | Integer | | 楼层 |
| unitArea | BigDecimal | | 建筑面积(㎡) |
| status | VARCHAR(20) | | 状态 |

---

#### 2.1.11 ResidentSpace（住户-房屋关联）

**表名**: `resident_space`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 关联记录ID |
| userId | UUID | NOT NULL, column: user_id | 用户ID |
| spaceId | UUID | NOT NULL, column: space_id | 房屋ID |
| relationType | VARCHAR(20) | | 关系类型：OWNER/FAMILY/TENANT |
| bindingStatus | VARCHAR(20) | | 绑定状态：PENDING/ACTIVE/EXPIRED/CANCELLED |
| startDate | LocalDate | | 生效日期 |
| endDate | LocalDate | | 失效日期（NULL=永久） |

---

#### 2.1.12 UserProject（用户-项目关联）

**表名**: `user_project`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 关联记录ID |
| userId | UUID | NOT NULL, column: user_id | 用户ID |
| projectId | UUID | NOT NULL, column: project_id | 项目ID |
| roleInProject | VARCHAR | NOT NULL, 默认"member", column: role_in_project | 项目中角色：leader/member/viewer |
| joinedAt | LocalDateTime | NOT NULL, 默认当前时间, column: joined_at | 加入时间 |

---

#### 2.1.13 SysConfig（系统配置）

**表名**: `sys_config`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 配置项ID |
| configKey | VARCHAR(128) | NOT NULL, UNIQUE, column: config_key | 配置键 |
| configValue | VARCHAR(5000) | column: config_value | 配置值 |
| description | VARCHAR(256) | | 配置描述 |
| createdAt | LocalDateTime | NOT NULL, @CreationTimestamp, 不可更新 | 创建时间 |
| updatedAt | LocalDateTime | NOT NULL, @UpdateTimestamp | 更新时间 |

---

#### 2.1.14 DataAccess（数据访问授权）@Deprecated

**表名**: `biz_data_access`

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | UUID | PK, 自动生成 | 授权记录ID |
| dataType | VARCHAR | NOT NULL, column: data_type | 数据类型 |
| dataId | UUID | NOT NULL, column: data_id | 数据ID |
| accessType | VARCHAR | NOT NULL, column: access_type | 访问者类型 |
| accessId | UUID | NOT NULL, column: access_id | 访问者ID |
| accessLevel | VARCHAR | NOT NULL, 默认"read", column: access_level | 访问级别 |
| grantedBy | UUID | column: granted_by | 授权人ID |
| grantedAt | LocalDateTime | NOT NULL, 默认当前时间, column: granted_at | 授权时间 |

> **注意**: DataAccess 实体及对应控制器已标记 @Deprecated，后续版本将移除。

---

### 2.2 枚举定义

#### UserStatus

| 值 | 描述 |
|----|------|
| ACTIVE | 正常 |
| LOCKED | 锁定 |
| DISABLED | 禁用 |

#### RoleType

| 值 | 描述 |
|----|------|
| SYSTEM | 系统级，可访问所有项目数据 |
| PROJECT | 项目级，仅可访问指定项目数据 |
| DEPARTMENT | 部门级，仅可访问本部门数据 |

#### DataScope

| 值 | 描述 |
|----|------|
| ALL | 全部数据 |
| PROJECT | 本项目数据 |
| DEPARTMENT | 本部门数据 |
| SELF | 仅本人数据 |

#### RoleStatus

| 值 | 描述 |
|----|------|
| ENABLED | 启用 |
| DISABLED | 禁用 |

#### DeptType

| 值 | 描述 |
|----|------|
| ADMIN | 行政管理 |
| ENGINEERING | 工程部 |
| SECURITY | 安保部 |
| CS | 客服部 |
| CLEANING | 保洁部 |

#### ActionType

| 值 | 描述 |
|----|------|
| CREATE | 创建 |
| UPDATE | 修改 |
| DELETE | 删除 |
| QUERY | 查询 |
| VIEW | 查看 |
| LOGIN | 登录 |
| LOGOUT | 登出 |
| EXPORT | 导出 |
| IMPORT | 导入 |
| ASSIGN | 分配 |
| REVOKE | 撤销 |

---

### 2.3 ER关系图（Mermaid）

```mermaid
erDiagram
    User ||--o{ Role : "auth_user_role M2M"
    Role ||--o{ Permission : "auth_role_permission M2M"
    User ||--|| EnterpriseUser : "共享主键 1:1"
    User ||--|| ProjectStaff : "FK 1:1"
    User ||--|| Resident : "共享主键 1:1"
    ProjectStaff ||--o{ ProjectStaffRole : "1:N 级联删除"
    ProjectStaffRole }o--|| Role : "N:1 EAGER"
    Resident ||--o{ ResidentSpace : "1:N"
    ResidentSpace }o--|| Space : "N:1"
    User ||--o{ UserProject : "1:N"
    UserProject }o--|| Project : "N:1"

    Dept ||--o{ Dept : "自引用树形 parentId"

    AuditLog {
        UUID id PK
        UUID userId
        String username
        String operation
        String module
        String action
        String targetType
        String targetId
        String status
    }

    SysConfig {
        UUID id PK
        String configKey UK
        String configValue
    }

    DataAccess {
        UUID id PK
        String dataType
        UUID dataId
        String accessType
        UUID accessId
        String accessLevel
    }
```

---

## 三、API设计

### 3.1 AuthController -- 认证管理

**基础路径**: `/api/auth`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| AUTH-API-001 | POST | `/login` | 用户登录 | Body: `{username: String(3-50), password: String(8-128)}` | `{code, data: {token, userId, username, realName, roles}}` | 无（公开） | 用户名不存在; 密码错误; 账户锁定; 账户禁用; 登录失败超5次锁定10分钟 |
| AUTH-API-002 | POST | `/logout` | 用户登出 | Header: Authorization: Bearer {token} | `{code, data: null}` | 已登录 | Token无效 |
| AUTH-API-003 | GET | `/me` | 获取当前用户 | Header: Authorization: Bearer {token} | `{code, data: {username}}` | 已登录 | Token缺失; Token无效 |
| AUTH-API-004 | POST | `/refresh` | 刷新Token | Header: Authorization: Bearer {token} | `{code, data: {token}}` | 已登录 | Token缺失; Token无效; Token已过期 |

**登录响应详细格式**:
```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "userId": "uuid",
    "username": "admin",
    "realName": "管理员",
    "roles": ["SYSTEM_ADMIN", "PROJECT_MANAGER"]
  }
}
```

---

### 3.2 UserController -- 用户管理

**基础路径**: `/api/auth/users`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| USER-API-001 | GET | `/` | 分页查询用户列表 | page(int, 默认0), size(int, 默认10) | `{code, data: {content: [User], totalElements, totalPages, ...}}` | 已登录 | 分页参数越界 |
| USER-API-002 | GET | `/{id}` | 根据ID获取用户 | id(UUID, Path) | `{code, data: User}` | 已登录 | 用户不存在 |
| USER-API-003 | POST | `/` | 创建用户 | Body: User实体 | `{code, data: User}` | 管理员 | 用户名已存在; 字段校验失败 |
| USER-API-004 | PUT | `/{id}` | 更新用户 | id(UUID, Path), Body: User实体 | `{code, data: User}` | 管理员 | 用户不存在; 用户名冲突 |
| USER-API-005 | DELETE | `/{id}` | 删除用户 | id(UUID, Path) | `{code, data: null}` | 管理员 | 用户不存在; 用户有关联数据 |
| USER-API-006 | PUT | `/{id}/password` | 修改密码 | id(UUID, Path), Body: `{oldPassword: String(8-128), newPassword: String(8-128)}` | `{code, data: null}` | 本人或管理员 | 原密码错误; 新密码强度不足; 新密码为弱密码 |
| USER-API-007 | POST | `/{id}/roles` | 分配角色 | id(UUID, Path), Body: `[roleId1, roleId2, ...]` | `{code, data: null}` | 管理员 | 用户不存在; 角色ID不存在; 分配数量超限 |
| USER-API-008 | GET | `/{id}/projects` | 获取用户项目列表 | id(UUID, Path) | `{code, data: [UserProject]}` | 已登录 | 用户不存在 |
| USER-API-009 | POST | `/{id}/projects` | 添加用户到项目 | id(UUID, Path), Body: `{projectId: UUID, roleInProject: String}` | `{code, data: null}` | 管理员 | 用户不存在; 项目不存在; 已在该项目中 |
| USER-API-010 | DELETE | `/{id}/projects/{projectId}` | 从项目移除用户 | id(UUID, Path), projectId(UUID, Path) | `{code, data: null}` | 管理员 | 关联不存在 |
| USER-API-011 | GET | `/enterprise` | 获取企业员工列表 | 无 | `{code, data: [UserVO]}` | 已登录 | 无 |

**UserVO格式**:
```json
{
  "id": "uuid",
  "username": "zhangsan",
  "realName": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "avatar": "url",
  "status": "ACTIVE",
  "userType": "ENTERPRISE",
  "deptId": "uuid"
}
```

---

### 3.3 RoleController -- 角色管理

**基础路径**: `/api/auth/roles`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| ROLE-API-001 | GET | `/` | 分页查询角色列表 | page(int, 默认0), size(int, 默认10) | `{code, data: Page<Role>}` | 已登录 | 分页参数越界 |
| ROLE-API-002 | GET | `/{id}` | 根据ID获取角色 | id(UUID, Path) | `{code, data: Role}` | 已登录 | 角色不存在 |
| ROLE-API-003 | GET | `/project/{projectId}` | 根据项目ID查询角色 | projectId(UUID, Path) | `{code, data: [Role]}` | 已登录 | 项目不存在 |
| ROLE-API-004 | POST | `/` | 创建角色 | Body: Role实体 | `{code, data: Role}` | 管理员 | 角色代码已存在; 字段校验失败 |
| ROLE-API-005 | PUT | `/{id}` | 更新角色 | id(UUID, Path), Body: Role实体 | `{code, data: Role}` | 管理员 | 角色不存在; 角色代码冲突 |
| ROLE-API-006 | DELETE | `/{id}` | 删除角色 | id(UUID, Path) | `{code, data: null}` | 管理员 | 角色不存在; 角色已分配给用户 |
| ROLE-API-007 | POST | `/{id}/permissions` | 为角色分配权限 | id(UUID, Path), Body: `[permissionId1, permissionId2, ...]` | `{code, data: null}` | 管理员 | 角色不存在; 权限ID不存在 |
| ROLE-API-008 | GET | `/{id}/permissions` | 获取角色权限列表 | id(UUID, Path) | `{code, data: [Permission]}` | 已登录 | 角色不存在 |
| ROLE-API-009 | GET | `/{id}/users` | 获取拥有某角色的用户 | id(UUID, Path) | `{code, data: [User]}` | 已登录 | 角色不存在 |

---

### 3.4 PermissionController -- 权限管理

**基础路径**: `/api/auth/permissions`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| PERM-API-001 | GET | `/` | 分页查询权限列表 | page(int, 默认0), size(int, 默认10) | `{code, data: Page<Permission>}` | 已登录 | 分页参数越界 |
| PERM-API-002 | GET | `/{id}` | 根据ID获取权限 | id(UUID, Path) | `{code, data: Permission}` | 已登录 | 权限不存在 |
| PERM-API-003 | GET | `/type/{type}` | 根据类型查询权限 | type(String, Path): MENU/BUTTON/API | `{code, data: [Permission]}` | 已登录 | 无效类型 |
| PERM-API-004 | GET | `/menus` | 查询所有菜单权限 | 无 | `{code, data: [Permission]}` | 已登录 | 无 |
| PERM-API-005 | POST | `/` | 创建权限 | Body: Permission实体 | `{code, data: Permission}` | 管理员 | 权限代码已存在; 字段校验失败 |
| PERM-API-006 | PUT | `/{id}` | 更新权限 | id(UUID, Path), Body: Permission实体 | `{code, data: Permission}` | 管理员 | 权限不存在; 权限代码冲突 |
| PERM-API-007 | DELETE | `/{id}` | 删除权限 | id(UUID, Path) | `{code, data: null}` | 管理员 | 权限不存在; 权限已分配给角色 |

---

### 3.5 DeptController -- 部门管理

**基础路径**: `/api/auth/depts`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| DEPT-API-001 | GET | `/tree` | 获取部门树 | 无 | `{code, data: [DeptVO]}` | 已登录 | 无 |
| DEPT-API-002 | GET | `/` | 获取所有启用部门 | 无 | `{code, data: [Dept]}` | 已登录 | 无 |
| DEPT-API-003 | GET | `/{id}` | 根据ID获取部门 | id(UUID, Path) | `{code, data: Dept}` | 已登录 | 部门不存在 |
| DEPT-API-004 | POST | `/` | 创建部门 | Body: DeptDTO `{deptName, parentId, deptType, leaderId, sortOrder}` | `{code, data: Dept}` | 管理员 | 父部门不存在; 字段校验失败 |
| DEPT-API-005 | PUT | `/{id}` | 更新部门 | id(UUID, Path), Body: DeptDTO | `{code, data: Dept}` | 管理员 | 部门不存在; 形成环 |
| DEPT-API-006 | DELETE | `/{id}` | 删除部门 | id(UUID, Path) | `{code, data: null}` | 管理员 | 部门不存在; 有子部门; 部门下有用户 |
| DEPT-API-007 | GET | `/{deptId}/members` | 获取部门成员 | deptId(UUID, Path) | `{code, data: [UserVO]}` | 已登录 | 部门不存在 |
| DEPT-API-008 | GET | `/by-type/{deptType}` | 根据类型查询部门 | deptType(String, Path): ADMIN/ENGINEERING/SECURITY/CS/CLEANING | `{code, data: [Dept]}` | 已登录 | 无效类型 |

**DeptVO格式**:
```json
{
  "id": "uuid",
  "parentId": "uuid",
  "deptName": "工程部",
  "deptType": "ENGINEERING",
  "leaderId": "uuid",
  "sortOrder": 1,
  "status": "ACTIVE",
  "children": [DeptVO, DeptVO, ...]
}
```

---

### 3.6 ProjectMemberController -- 项目成员管理

**基础路径**: `/api/auth/projects`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| PMM-API-001 | GET | `/{projectId}/members` | 查询项目成员列表 | projectId(UUID, Path), page(int, 默认0), size(int, 默认20) | `{code, data: PageResponse<ProjectMemberVO>}` | 已登录 | 项目不存在 |
| PMM-API-002 | GET | `/{projectId}/available-members` | 获取可添加成员 | projectId(UUID, Path), search(String, 可选) | `{code, data: [UserVO]}` | 已登录 | 项目不存在 |
| PMM-API-003 | POST | `/{projectId}/members` | 添加项目成员 | projectId(UUID, Path), Body: AddProjectMemberDTO `{userId, staffType, roleIds}` | `{code, data: null}` | 项目管理员 | 用户不存在; 项目不存在; 用户已是成员 |
| PMM-API-004 | DELETE | `/{projectId}/members/{userId}` | 移除项目成员 | projectId(UUID, Path), userId(UUID, Path) | `{code, data: null}` | 项目管理员 | 成员不存在 |

**ProjectMemberVO格式**:
```json
{
  "id": "uuid",
  "userId": "uuid",
  "username": "zhangsan",
  "realName": "张三",
  "staffType": "SECURITY",
  "shiftType": "DAY",
  "assignmentStatus": "ASSIGNED",
  "roles": [
    {"id": "uuid", "code": "SECURITY_GUARD", "name": "保安"}
  ]
}
```

---

### 3.7 DataAccessController -- 数据访问授权 @Deprecated

**基础路径**: `/api/data-access`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| DA-API-001 | POST | `/` | 授予数据访问权限 | Body: DataAccessRequest `{dataType, dataId, accessType, accessId, accessLevel}` | `{code, data: null}` | 已登录 | 未登录(401); 字段校验失败 |
| DA-API-002 | DELETE | `/{id}` | 撤销数据访问权限 | id(UUID, Path) | `{code, data: null}` | 已登录 | 记录不存在 |
| DA-API-003 | GET | `/` | 查询数据访问记录 | dataType(String), dataId(UUID) | `{code, data: [DataAccess]}` | 已登录 | 参数缺失 |

> **注意**: 此控制器所有端点已标记 @Deprecated，后续版本将移除。

---

### 3.8 AuditLogController -- 审计日志

**基础路径**: `/api/audit-logs`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| AUDIT-API-001 | GET | `/` | 分页查询审计日志 | page(int, 默认0), size(int, 默认10), module(String, 可选), action(String, 可选), username(String, 可选), startDate(DateTime, 可选), endDate(DateTime, 可选) | `{code, data: Page<AuditLog>}` | 管理员 | 查询范围超30天自动截断 |
| AUDIT-API-002 | GET | `/modules` | 获取模块列表 | 无 | `{code, data: [{value, label}]}` | 管理员 | 无 |
| AUDIT-API-003 | GET | `/actions` | 获取操作类型列表 | 无 | `{code, data: [{value, label}]}` | 管理员 | 无 |
| AUDIT-API-004 | GET | `/stats` | 获取最近30天日志统计 | 无 | `{code, data: {total, retentionDays, description}}` | 管理员 | 无 |

**模块列表固定值**: USER(用户管理), ROLE(角色管理), PERMISSION(权限管理), PROJECT(项目管理), AUTH(登录认证)

---

### 3.9 SysConfigController -- 系统配置

**基础路径**: `/api/config`

| 编号 | 方法 | 路径 | 说明 | 请求参数 | 响应格式 | 权限要求 | 例外情况 |
|------|------|------|------|----------|----------|----------|----------|
| CFG-API-001 | GET | `/` | 获取所有配置项 | 无 | `{code, data: {key1: value1, key2: value2}}` | 管理员 | 无 |
| CFG-API-002 | GET | `/{configKey}` | 根据键获取配置 | configKey(String, Path) | `{code, data: SysConfig}` | 管理员 | 配置键不存在 |
| CFG-API-003 | PUT | `/{configKey}` | 更新单个配置 | configKey(String, Path), Body: `{configValue: String(NotBlank)}` | `{code, data: SysConfig}` | 管理员 | 配置键不存在; 配置值为空 |
| CFG-API-004 | PUT | `/` | 批量更新配置 | Body: `{key1: value1, key2: value2}` | `{code, data: {key1: value1, key2: value2}}` | 管理员 | 配置键不存在 |

---

## 四、业务规则

### 4.1 RBAC权限模型（角色-权限-用户关联规则）

**模型结构**: User <--M2M--> Role <--M2M--> Permission

**双层角色分配**:

1. **用户直接角色**: 通过 `auth_user_role` 中间表关联
   - 用户创建时分配
   - 通过 `UserController.assignRoles` 接口分配
   - 覆盖模式：新分配的角色列表完全替换旧列表

2. **项目员工角色**: 通过 `ProjectStaffRole` 关联
   - 项目成员管理时分配
   - 覆盖模式：先删除旧角色，再添加新角色
   - 级联删除：删除 ProjectStaff 时自动删除其所有 ProjectStaffRole

**登录时角色收集规则**:
```
用户所有角色 = 用户直接角色(auth_user_role) ∪ 项目员工角色(ProjectStaffRole → Role)
```

**角色类型与数据范围对应关系**:

| 角色类型 | 说明 | 默认数据范围 | projectId |
|---------|------|-------------|-----------|
| SYSTEM | 系统级角色，跨项目 | ALL | NULL |
| PROJECT | 项目级角色，绑定特定项目 | PROJECT | 非NULL |
| DEPARTMENT | 部门级角色 | DEPARTMENT | NULL |

**角色分配约束**:
- 角色分配数量受 `BatchOperationValidator.validateAssignmentSize()` 限制
- 分配不存在的角色ID将抛出异常
- 角色状态为 DISABLED 时不应分配给用户（需业务层校验）

---

### 4.2 数据范围控制（ALL/PROJECT/DEPARTMENT/SELF的SQL过滤规则）

**四级数据范围**:

| 数据范围 | 编码 | 说明 | SQL过滤规则 |
|---------|------|------|------------|
| 全部 | ALL | 可查看所有数据 | 不做数据过滤 |
| 项目 | PROJECT | 仅可查看所属项目数据 | `WHERE project_id IN (用户可访问的项目ID列表)` |
| 部门 | DEPARTMENT | 仅可查看本部门数据 | `WHERE project_id IN (...) AND dept_id = 用户部门ID` |
| 本人 | SELF | 仅可查看本人数据 | `WHERE assigned_to = 当前用户ID OR created_by = 当前用户ID` |

**DataScopeService 核心方法**:

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `canAccessAllData()` | 检查角色集中是否有ALL范围 | Boolean |
| `isSelfScopeOnly()` | 检查是否所有角色都是SELF范围 | Boolean |
| `getPermittedProjectIds()` | 获取用户可访问的项目ID列表 | List\<UUID\> |

**项目上下文传递机制**:
1. 前端请求携带 `X-Project-ID` Header
2. `ProjectContextInterceptor` 拦截器设置 ThreadLocal
3. 业务层通过 DataScopeService 过滤数据

---

### 4.3 JWT认证流程（登录→Token生成→验证→刷新→登出）

**Token生成**:
- 算法: HMAC-SHA256
- Claims: userId(subject), username, roles列表
- 过期时间: 可配置（默认86400000ms = 24小时）
- 密钥: 配置项 `jwt.secret`

**完整认证流程**:

```
1. 登录 POST /api/auth/login
   ├── 检查登录锁定(Redis: login:attempt:{username})
   ├── 查询用户(含角色, LAZY加载)
   ├── 验证密码(BCrypt.matches)
   ├── 检查用户状态(LOCKED/DISABLED → 拒绝)
   ├── 收集角色(直接角色 + 项目员工角色)
   ├── 生成JWT Token
   ├── 清除登录失败计数
   ├── 更新lastLoginTime/lastLoginIp
   └── 返回 {token, userId, username, realName, roles}

2. 请求认证
   ├── Header: Authorization: Bearer {token}
   ├── JwtTokenProvider.validateToken() 验证签名和过期
   └── 解析 userId / username / roles

3. Token刷新 POST /api/auth/refresh
   ├── 验证当前Token有效
   ├── 检查Token未过期
   ├── 生成新Token
   └── 返回 {token}

4. 登出 POST /api/auth/logout
   └── 客户端清除Token（服务端无状态）
```

---

### 4.4 密码策略（BCrypt/强度校验/弱密码检测/登录锁定）

**加密算法**: BCrypt（Spring Security PasswordEncoder）

**密码强度校验规则**（可配置，前缀 `password.*`）:

| 规则 | 配置键 | 默认值 | 说明 |
|------|--------|--------|------|
| 最小长度 | password.minLength | 8 | 最小长度 |
| 最大长度 | password.maxLength | 20 | 最大长度 |
| 需要大写字母 | password.requireUppercase | true | 至少1个大写字母 |
| 需要小写字母 | password.requireLowercase | true | 至少1个小写字母 |
| 需要数字 | password.requireDigit | true | 至少1个数字 |
| 需要特殊字符 | password.requireSpecial | true | 至少1个特殊字符 |

**弱密码黑名单**: password, 123456, admin, qwerty, letmein, welcome, monkey, dragon

**旧密码兼容策略**:
- 检测非BCrypt格式密码（MD5/SHA-1等）
- 非BCrypt密码强制返回 `matches=false`
- 用户需通过修改密码流程重置为BCrypt格式

**登录失败锁定机制**（基于Redis）:

| 参数 | 默认值 | 说明 |
|------|--------|------|
| maxAttempts | 5 | 最大失败次数 |
| lockoutDurationMinutes | 10 | 锁定时长(分钟) |
| Key格式 | `login:attempt:{username}` | Redis Key |

**锁定流程**:
1. 每次失败: increment计数，首次设置TTL
2. 达到上限(5次): isLockedOut返回true，拒绝登录
3. 登录成功: 清除计数
4. 手动解锁: unlock方法清除Key

---

### 4.5 项目成员管理（添加/移除/角色分配/在岗状态变更）

**添加项目成员流程**:
1. 接收 AddProjectMemberDTO: `{userId, staffType, roleIds}`
2. 创建/更新 ProjectStaff 记录（设定员工类型、分配状态=ASSIGNED）
3. 覆盖模式更新角色: 先删除旧 ProjectStaffRole，再添加新 ProjectStaffRole
4. 创建 UserProject 关联记录

**移除项目成员流程**:
1. 删除 ProjectStaff 记录（级联删除 ProjectStaffRole）
2. 删除 UserProject 关联记录

**在岗状态变更**:
- ASSIGNED: 已分配（正常在岗）
- ON_LEAVE: 请假（临时离岗）
- TRANSFERRED: 已调离（永久离岗）

**员工类型**:
- SECURITY(保安), CLEANING(保洁), GARDEN(绿化), MAINTENANCE(维修), CUSTOMER_SERVICE(客服), GENERAL(普通员工)

**班次类型**:
- DAY(白班), NIGHT(夜班), ROTATION(轮班)

---

### 4.6 住户认证流程（申请→审核→通过/拒绝→房屋绑定）

**认证状态流转**:

```
UNVERIFIED(未认证) → PENDING(待审核) → VERIFIED(已认证)
                                      → REJECTED(已拒绝) → PENDING(重新申请)
```

**认证流程**:
1. 住户注册账号，verificationStatus = UNVERIFIED
2. 住户提交认证申请（身份证、住户类型），verificationStatus = PENDING
3. 管理员审核:
   - 通过: verificationStatus = VERIFIED, 记录 verifiedAt/verifiedBy
   - 拒绝: verificationStatus = REJECTED

**房屋绑定流程**:
1. 住户认证通过后，创建 ResidentSpace 关联
2. 关联字段: userId, spaceId, relationType(OWNER/FAMILY/TENANT)
3. 绑定状态: PENDING(待生效) → ACTIVE(生效中) → EXPIRED(已过期) / CANCELLED(已取消)
4. 支持生效/失效日期: startDate / endDate（NULL=永久）

---

## 五、执行约束

### 5.1 用户名唯一性约束

- **数据库约束**: `auth_user.username` 列 UNIQUE
- **校验规则**: 正则 `^[a-zA-Z0-9_]+$`，长度3-50位
- **违反后果**: 创建/更新用户时抛出 DataIntegrityViolationException
- **处理方式**: 业务层先查询是否存在相同用户名，存在则抛出 BusinessException

### 5.2 角色代码唯一性约束

- **数据库约束**: `auth_role.code` 列 UNIQUE
- **校验规则**: 正则 `^[a-zA-Z0-9_]+$`，长度2-50位
- **违反后果**: 创建/更新角色时抛出 DataIntegrityViolationException
- **处理方式**: 业务层先查询是否存在相同角色代码，存在则抛出 BusinessException

### 5.3 权限代码唯一性约束

- **数据库约束**: `auth_permission.code` 列 UNIQUE
- **校验规则**: 正则 `^[a-zA-Z0-9_:]+$`，长度2-100位，格式 `module:resource:action`
- **违反后果**: 创建/更新权限时抛出 DataIntegrityViolationException
- **处理方式**: 业务层先查询是否存在相同权限代码，存在则抛出 BusinessException

### 5.4 部门树完整性约束（不能形成环）

- **约束说明**: 部门通过 parentId 自引用形成树形结构，更新 parentId 时不能形成环路
- **校验方式**: 业务层在更新 parentId 时，沿 parentId 链向上遍历，检查是否会回到当前节点
- **违反后果**: 抛出 BusinessException，提示"不能将部门设置为其子部门的下级"
- **附加约束**: 删除部门时，必须先删除或移动其所有子部门

### 5.5 密码强度约束

- **最小长度**: 8位
- **最大长度**: 20位（业务层校验）/ 128位（API层校验）
- **必须包含**: 大写字母、小写字母、数字、特殊字符各至少1个
- **弱密码检测**: 不允许使用黑名单中的密码
- **违反后果**: 修改密码时抛出 BusinessException，提示具体不满足的规则

---

## 六、权限控制

### 6.1 API端点权限矩阵

| 控制器 | 端点 | 所需角色 | 数据范围过滤 |
|--------|------|----------|-------------|
| AuthController | POST /login | 公开(无需认证) | 无 |
| AuthController | POST /logout | 已登录用户 | 无 |
| AuthController | GET /me | 已登录用户 | SELF |
| AuthController | POST /refresh | 已登录用户 | 无 |
| UserController | GET / | 管理员 | ALL/PROJECT/DEPARTMENT/SELF |
| UserController | GET /{id} | 管理员 | 同上 |
| UserController | POST / | 管理员(SYSTEM级) | 无 |
| UserController | PUT /{id} | 管理员 | 同上 |
| UserController | DELETE /{id} | 管理员(SYSTEM级) | 无 |
| UserController | PUT /{id}/password | 本人或管理员 | SELF |
| UserController | POST /{id}/roles | 管理员(SYSTEM级) | 无 |
| UserController | GET /{id}/projects | 已登录用户 | SELF |
| UserController | POST /{id}/projects | 管理员(PROJECT级) | 无 |
| UserController | DELETE /{id}/projects/{projectId} | 管理员(PROJECT级) | 无 |
| UserController | GET /enterprise | 已登录用户 | ALL/PROJECT |
| RoleController | GET / | 已登录用户 | ALL/PROJECT |
| RoleController | GET /{id} | 已登录用户 | 同上 |
| RoleController | GET /project/{projectId} | 已登录用户 | PROJECT |
| RoleController | POST / | 管理员(SYSTEM级) | 无 |
| RoleController | PUT /{id} | 管理员(SYSTEM级) | 无 |
| RoleController | DELETE /{id} | 管理员(SYSTEM级) | 无 |
| RoleController | POST /{id}/permissions | 管理员(SYSTEM级) | 无 |
| RoleController | GET /{id}/permissions | 已登录用户 | 同上 |
| RoleController | GET /{id}/users | 已登录用户 | 同上 |
| PermissionController | GET / | 已登录用户 | ALL |
| PermissionController | GET /{id} | 已登录用户 | ALL |
| PermissionController | GET /type/{type} | 已登录用户 | ALL |
| PermissionController | GET /menus | 已登录用户 | SELF(按角色过滤) |
| PermissionController | POST / | 管理员(SYSTEM级) | 无 |
| PermissionController | PUT /{id} | 管理员(SYSTEM级) | 无 |
| PermissionController | DELETE /{id} | 管理员(SYSTEM级) | 无 |
| DeptController | GET /tree | 已登录用户 | ALL |
| DeptController | GET / | 已登录用户 | ALL |
| DeptController | GET /{id} | 已登录用户 | ALL |
| DeptController | POST / | 管理员(SYSTEM级) | 无 |
| DeptController | PUT /{id} | 管理员(SYSTEM级) | 无 |
| DeptController | DELETE /{id} | 管理员(SYSTEM级) | 无 |
| DeptController | GET /{deptId}/members | 已登录用户 | DEPARTMENT |
| DeptController | GET /by-type/{deptType} | 已登录用户 | ALL |
| ProjectMemberController | GET /{projectId}/members | 项目成员 | PROJECT |
| ProjectMemberController | GET /{projectId}/available-members | 项目管理员 | PROJECT |
| ProjectMemberController | POST /{projectId}/members | 项目管理员 | PROJECT |
| ProjectMemberController | DELETE /{projectId}/members/{userId} | 项目管理员 | PROJECT |
| DataAccessController | POST / | 已登录用户(@Deprecated) | 无 |
| DataAccessController | DELETE /{id} | 已登录用户(@Deprecated) | 无 |
| DataAccessController | GET / | 已登录用户(@Deprecated) | 无 |
| AuditLogController | GET / | 管理员(SYSTEM级) | ALL |
| AuditLogController | GET /modules | 管理员(SYSTEM级) | 无 |
| AuditLogController | GET /actions | 管理员(SYSTEM级) | 无 |
| AuditLogController | GET /stats | 管理员(SYSTEM级) | ALL |
| SysConfigController | GET / | 管理员(SYSTEM级) | ALL |
| SysConfigController | GET /{configKey} | 管理员(SYSTEM级) | ALL |
| SysConfigController | PUT /{configKey} | 管理员(SYSTEM级) | 无 |
| SysConfigController | PUT / | 管理员(SYSTEM级) | 无 |

### 6.2 数据范围过滤规则

| 操作类型 | ALL范围 | PROJECT范围 | DEPARTMENT范围 | SELF范围 |
|---------|---------|------------|---------------|---------|
| 查询用户列表 | 全部用户 | 本项目成员 | 本部门用户 | 仅本人 |
| 查询角色列表 | 全部角色 | 本项目角色 | - | - |
| 查询审计日志 | 全部日志 | 本项目日志 | 本部门日志 | 本人操作日志 |
| 查询部门成员 | 全部 | 本项目部门成员 | 本部门成员 | - |

---

## 七、例外情况处理

### 7.1 用户相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 用户名已存在 | 409 | "用户名{username}已存在" | 创建/更新前查询，存在则拒绝 |
| 用户不存在 | 404 | "用户不存在" | findById返回空时抛出 |
| 密码错误 | 401 | "用户名或密码错误" | BCrypt.matches返回false |
| 账户锁定 | 423 | "账户已锁定，请{minutes}分钟后重试" | 检查Redis锁定状态 |
| 账户禁用 | 403 | "账户已被禁用" | 检查UserStatus.DISABLED |
| 原密码错误 | 400 | "原密码不正确" | 修改密码时验证 |
| 新密码强度不足 | 400 | "密码必须包含大写字母、小写字母、数字和特殊字符，长度8-20位" | 密码策略校验 |
| 新密码为弱密码 | 400 | "该密码过于简单，请使用更复杂的密码" | 弱密码黑名单检测 |
| 手机号格式错误 | 400 | "手机号格式不正确" | 正则校验 |
| 邮箱格式错误 | 400 | "邮箱格式不正确" | @Email校验 |
| 删除有关联数据的用户 | 400 | "该用户存在关联数据，无法删除" | 检查UserProject/ProjectStaff等关联 |

### 7.2 角色相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 角色代码已存在 | 409 | "角色代码{code}已存在" | 创建/更新前查询 |
| 角色不存在 | 404 | "角色不存在" | findById返回空时抛出 |
| 删除已分配的角色 | 400 | "该角色已分配给用户，无法删除" | 检查auth_user_role关联 |
| 角色代码格式错误 | 400 | "角色代码只能包含字母、数字和下划线" | 正则校验 |

### 7.3 权限相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 权限代码已存在 | 409 | "权限代码{code}已存在" | 创建/更新前查询 |
| 权限不存在 | 404 | "权限不存在" | findById返回空时抛出 |
| 删除已分配的权限 | 400 | "该权限已分配给角色，无法删除" | 检查auth_role_permission关联 |
| 权限代码格式错误 | 400 | "权限代码只能包含字母、数字、冒号和下划线" | 正则校验 |

### 7.4 部门相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 部门不存在 | 404 | "部门不存在" | getById返回空时返回error |
| 有子部门不能删除 | 400 | "该部门存在子部门，无法删除" | 检查子部门数量 |
| 部门下有用户不能删除 | 400 | "该部门下存在用户，无法删除" | 检查部门成员 |
| 部门树形成环 | 400 | "不能将部门设置为其子部门的下级" | 遍历parentId链检查 |
| 父部门不存在 | 400 | "上级部门不存在" | 创建/更新时校验parentId |

### 7.5 认证相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| Token缺失 | 401 | "未授权" | Authorization Header为空 |
| Token无效 | 401 | "Token无效" | JWT签名验证失败 |
| Token已过期 | 401 | "Token已过期" | JWT过期时间检查 |
| 登录失败超限 | 423 | "登录失败次数过多，账户已锁定{minutes}分钟" | Redis计数检查 |
| 用户名不存在 | 401 | "用户名或密码错误" | 不暴露具体原因 |

### 7.6 项目成员相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 用户已是项目成员 | 409 | "该用户已是项目成员" | 检查ProjectStaff存在性 |
| 项目成员不存在 | 404 | "项目成员不存在" | 删除时校验 |
| 角色ID不存在 | 400 | "角色ID{id}不存在" | 分配角色时校验 |

### 7.7 系统配置相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 配置键不存在 | 404 | "配置项{key}不存在" | 查询时校验 |
| 配置值为空 | 400 | "配置值不能为空" | @NotBlank校验 |

### 7.8 审计日志相关例外

| 例外场景 | 错误码 | 错误信息 | 处理方式 |
|---------|--------|---------|---------|
| 查询范围超30天 | 200(自动截断) | 无(自动截断起始时间) | 强制限制查询窗口 |
| 分页参数过大 | 200(自动修正) | 无(使用getSafeSize修正) | PaginationValidator校验 |