ether
/
ether-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ether-docs/_archive/domains-old/REVERSE-AUTH.md

37 KiB
Raw Permalink Blame History

认证授权域功能详细设计文档（反推自代码）

文档类型: 反推设计文档 数据来源: module-auth 实际代码 生成日期: 2026-04-23 对照文档: 05-AUTH.md（原需求设计）

一、领域概述

1.1 领域职责

认证授权域（module-auth）负责 Ether 平台的身份认证与授权管理，核心职责包括：

  • 身份认证：用户登录/登出、JWT Token 生成与验证、登录失败锁定
  • 用户管理：多类型用户（企业员工、项目员工、住户）的 CRUD 与扩展信息管理
  • RBAC 权限模型：角色-权限-用户三层关联，支持项目级角色隔离
  • 数据权限：四级数据范围（ALL/PROJECT/DEPARTMENT/SELF）
  • 项目隔离：用户-项目多对多关联，项目成员管理与角色分配
  • 部门管理：树形组织架构，支持多种部门类型
  • 审计日志：操作日志自动记录，异步持久化，30天查询窗口
  • 系统配置：键值对形式的系统参数管理

1.2 核心概念

概念 说明 对应实体
用户 系统登录账户，支持四种用户类型 User
企业员工 企业类型用户的扩展信息 EnterpriseUser
项目员工 项目类型员工的扩展信息，含班次、岗位状态 ProjectStaff
住户 业主/家属/租户，含认证流程 Resident
角色 权限集合，支持系统级/项目级/部门级 Role
权限 功能访问控制点，支持菜单/按钮/API三种类型 Permission
部门 组织架构节点，支持树形结构 Dept
用户-项目关联 用户参与项目的多对多关系 UserProject
项目员工角色 项目员工在项目中的角色分配 ProjectStaffRole
数据访问授权 细粒度数据访问控制记录 DataAccess
审计日志 操作审计记录 AuditLog
房屋空间 项目下的房屋/空间信息 Space
住户-房屋关联 住户与房屋的绑定关系 ResidentSpace
系统配置 键值对形式的系统参数 SysConfig

1.3 用户类型体系

User (基础用户)
├── EnterpriseUser (企业员工) — 共享主键一对一
│   └── 员工工号、部门、职位、入职日期、员工类别
├── ProjectStaff (项目员工) — 独立主键一对一
│   └── 所属项目、员工类型、班次、班组长、在岗状态
│       └── ProjectStaffRole (项目员工角色) — 一对多
└── Resident (住户) — 共享主键一对一
    └── 身份证、住户类型、认证状态
        └── ResidentSpace (住户-房屋关联) — 一对多

二、数据结构设计

2.1 User（用户）

字段 类型 约束 说明
id UUID PK, 自动生成 用户唯一标识符
username VARCHAR(50) NOT NULL, UNIQUE 登录用户名，仅字母数字下划线，3-50位
password VARCHAR(255) NOT NULL, JSON忽略 BCrypt加密密码
salt VARCHAR JSON忽略 密码盐值（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 用户状态枚举
userType VARCHAR(20) NOT NULL 用户类型：ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER
deptId UUID 所属部门ID
lastLoginTime LocalDateTime 最后登录时间
lastLoginIp VARCHAR 最后登录IP
roles List<Role> M2M, LAZY 关联角色列表（通过auth_user_role表）
createdAt LocalDateTime NOT NULL, 自动填充 创建时间
updatedAt LocalDateTime NOT NULL, 自动填充 更新时间
createdBy UUID 创建人ID

枚举：UserStatus

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

关联表：auth_user_role

字段 类型 说明
user_id UUID FK → auth_user
role_id UUID FK → auth_role

2.2 Role（角色）

字段 类型 约束 说明
id UUID PK, 自动生成 角色唯一标识符
code VARCHAR(50) NOT NULL, UNIQUE 角色代码，仅字母数字下划线，2-50位
name VARCHAR(50) NOT NULL 角色名称
description VARCHAR(200) 角色描述
type VARCHAR(20) NOT NULL 角色类型枚举
dataScope VARCHAR(20) 默认SELF 数据范围枚举
projectId UUID 所属项目ID（NULL=系统级）
status VARCHAR(20) NOT NULL, 默认ENABLED 角色状态枚举
permissions List<Permission> M2M, LAZY 关联权限列表（通过auth_role_permission表）
createdAt LocalDateTime NOT NULL, 自动填充 创建时间
updatedAt LocalDateTime NOT NULL, 自动填充 更新时间

枚举：RoleType

值 描述
SYSTEM 系统级
PROJECT 项目级
DEPARTMENT 部门级

枚举：DataScope

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

枚举：RoleStatus

值 描述
ENABLED 启用
DISABLED 禁用

关联表：auth_role_permission

字段 类型 说明
role_id UUID FK → auth_role
permission_id UUID FK → auth_permission

2.3 Permission（权限）

字段 类型 约束 说明
id UUID PK, 自动生成 权限唯一标识符
code VARCHAR(100) NOT NULL, UNIQUE 权限代码，格式module:resource:action，仅字母数字冒号下划线
name VARCHAR(100) NOT NULL 权限名称
type VARCHAR(20) 权限类型：MENU/BUTTON/API
resource VARCHAR(50) 资源路径（API类型）
method VARCHAR(50) HTTP方法（API类型）
description VARCHAR(200) 权限描述
parentCode VARCHAR(50) 父权限代码（树形结构）
sortOrder Integer 排序序号
roles List<Role> M2M, LAZY 关联角色列表
createdAt LocalDateTime 自动填充 创建时间
updatedAt LocalDateTime 自动填充 更新时间

2.4 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 自动填充 创建时间
updatedAt LocalDateTime 自动填充 更新时间
createdBy UUID 创建人ID
updatedBy UUID 更新人ID

枚举：DeptType

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

2.5 EnterpriseUser（企业员工）

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

2.6 ProjectStaff（项目员工）

字段 类型 约束 说明
id UUID PK, 自动生成 主键ID
userId UUID FK → auth_user 用户ID
projectId UUID 所属项目ID
deptId UUID 所属部门ID
staffType VARCHAR(50) 员工类型
shiftType VARCHAR(20) 班次类型：DAY/NIGHT/ROTATION
leaderId UUID 班组长ID
assignmentStatus VARCHAR(20) 在岗状态：ASSIGNED/ON_LEAVE/TRANSFERRED
staffRoles List<ProjectStaffRole> @OneToMany, 级联删除 员工角色列表
createdAt LocalDateTime 创建时间
updatedAt LocalDateTime 更新时间
user User @OneToOne 关联User实体

StaffType 枚举值：SECURITY / CLEANING / GARDEN / MAINTENANCE / CUSTOMER_SERVICE / GENERAL

2.7 ProjectStaffRole（项目员工角色）

字段 类型 约束 说明
id UUID PK, 自动生成 主键ID
staff ProjectStaff @ManyToOne, LAZY, NOT NULL 关联项目员工
role Role @ManyToOne, EAGER, NOT NULL 关联角色
createdAt LocalDateTime 自动填充 创建时间

2.8 Resident（住户）

字段 类型 约束 说明
userId UUID PK, FK → auth_user 用户ID（共享主键）
idCard VARCHAR(18) JSON忽略 身份证号码
residentType VARCHAR(20) 住户类型：OWNER/FAMILY/TENANT
verificationStatus VARCHAR(20) 认证状态：UNVERIFIED/PENDING/VERIFIED/REJECTED
verifiedAt LocalDateTime 认证时间
verifiedBy UUID 认证人ID
user User @OneToOne @MapsId 关联User实体
createdAt LocalDateTime NOT NULL 创建时间
updatedAt LocalDateTime NOT NULL 更新时间
createdBy UUID 创建人ID
updatedBy UUID 更新人ID

2.9 ResidentSpace（住户-房屋关联）

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

2.10 Space（房屋空间）

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

2.11 UserProject（用户-项目关联）

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

2.12 DataAccess（数据访问授权）

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

2.13 AuditLog（审计日志）

字段 类型 约束 说明
id UUID PK, 自动生成 日志ID
userId UUID 操作用户ID
username VARCHAR(64) NOT NULL 操作用户名
operation VARCHAR(128) NOT NULL 操作描述
module VARCHAR(64) NOT NULL 模块标识
action VARCHAR(64) NOT NULL 操作类型枚举
targetType VARCHAR(64) 目标类型
targetId VARCHAR(64) 目标ID
content VARCHAR(2000) 操作内容
params LONGVARCHAR(5000) 请求参数
result LONGVARCHAR(5000) 操作结果
ipAddress VARCHAR(64) IP地址
userAgent VARCHAR(512) 用户代理
requestUrl VARCHAR(512) 请求URL
requestMethod VARCHAR(16) 请求方法
executionTimeMs Integer 执行耗时（ms）
status VARCHAR(16) 默认SUCCESS 状态枚举
errorMsg VARCHAR(2000) 错误信息
createdAt LocalDateTime NOT NULL, 自动填充 创建时间
tenantId UUID 租户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

枚举：ActionType

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

枚举：Status

值 描述
SUCCESS 成功
FAIL 失败

2.14 SysConfig（系统配置）

字段 类型 约束 说明
id UUID PK, 自动生成 配置项ID
configKey VARCHAR(128) NOT NULL, UNIQUE 配置键
configValue VARCHAR(5000) 配置值
description VARCHAR(256) 配置描述
createdAt LocalDateTime NOT NULL, 自动填充 创建时间
updatedAt LocalDateTime NOT NULL, 自动填充 更新时间

2.15 实体关系图

┌──────────┐     M2M      ┌──────────┐     M2M      ┌────────────┐
│   User   │◄────────────►│   Role   │◄────────────►│ Permission │
└────┬─────┘  auth_user   └────┬─────┘ auth_role    └────────────┘
     │         _role            │        _permission
     │ 1:1                     │
     ▼                         ▼
┌──────────────┐       ┌──────────────────┐
│EnterpriseUser│       │  ProjectStaff    │
│  (共享主键)   │       │  (独立主键)       │
└──────────────┘       └───────┬──────────┘
                               │ 1:N
                               ▼
                       ┌──────────────────┐
                       │ProjectStaffRole  │──────► Role
                       └──────────────────┘

┌──────────┐     1:1     ┌──────────┐
│   User   │◄───────────►│ Resident │
└──────────┘             └────┬─────┘
                              │ 1:N
                              ▼
                      ┌───────────────┐     N:1     ┌───────┐
                      │ResidentSpace  │◄────────────►│ Space │
                      └───────────────┘              └───────┘

┌──────────┐     N:N     ┌──────────┐
│   User   │◄───────────►│ Project  │  (通过 UserProject)
└──────────┘              └──────────┘

┌──────────┐
│   Dept   │  树形结构（parentId → 自引用）
└──────────┘

┌──────────┐
│DataAccess│  通用数据访问授权
└──────────┘

┌──────────┐
│ AuditLog │  操作审计日志
└──────────┘

┌──────────┐
│ SysConfig│  系统键值对配置
└──────────┘

三、API接口设计

3.1 AuthController — 认证管理

基础路径: /api/auth

方法 路径 说明 请求体 响应
POST /login 用户登录 {username, password} {token, userId, username, realName, roles}
POST /logout 用户登出 Header: Authorization void
GET /me 获取当前用户 Header: Authorization {username}
POST /refresh 刷新Token Header: Authorization {token}

登录流程：

  1. 检查登录失败锁定（Redis，5次失败锁定10分钟）
  2. 查询用户（含角色）
  3. 验证密码（BCrypt）
  4. 检查用户状态（LOCKED/DISABLED拒绝）
  5. 收集所有角色（用户直接角色 + 项目员工角色）
  6. 生成JWT Token（含userId、username、roles claims）
  7. 返回Token和用户基本信息

3.2 UserController — 用户管理

基础路径: /api/auth/users

方法 路径 说明 审计日志
GET / 分页查询用户列表 -
GET /{id} 根据ID获取用户 -
POST / 创建用户 CREATE
PUT /{id} 更新用户 UPDATE
DELETE /{id} 删除用户 DELETE
PUT /{id}/password 修改密码 UPDATE
POST /{id}/roles 分配角色 ASSIGN
GET /{id}/projects 获取用户项目列表 -
POST /{id}/projects 添加用户到项目 -
DELETE /{id}/projects/{projectId} 从项目移除用户 -
GET /enterprise 获取企业员工列表 -

密码修改规则：

  • 需验证原密码
  • 新密码需通过强度校验（8-20位，大小写+数字+特殊字符）
  • 弱密码检测（黑名单：password、123456、admin等）

3.3 RoleController — 角色管理

基础路径: /api/auth/roles

方法 路径 说明 审计日志
GET / 分页查询角色列表 -
GET /{id} 根据ID获取角色 -
GET /project/{projectId} 根据项目ID查询角色 -
POST / 创建角色 CREATE
PUT /{id} 更新角色 UPDATE
DELETE /{id} 删除角色 DELETE
POST /{id}/permissions 为角色分配权限 ASSIGN
GET /{id}/permissions 获取角色权限列表 -
GET /{id}/users 获取拥有某角色的用户 -

3.4 PermissionController — 权限管理

基础路径: /api/auth/permissions

方法 路径 说明 审计日志
GET / 分页查询权限列表 -
GET /{id} 根据ID获取权限 -
GET /type/{type} 根据类型查询权限 -
GET /menus 查询所有菜单权限 -
POST / 创建权限 -
PUT /{id} 更新权限 -
DELETE /{id} 删除权限 -

3.5 DeptController — 部门管理

基础路径: /api/auth/depts

方法 路径 说明 审计日志
GET /tree 获取部门树 -
GET / 获取所有启用部门 -
GET /{id} 根据ID获取部门 -
POST / 创建部门 CREATE
PUT /{id} 更新部门 UPDATE
DELETE /{id} 删除部门 DELETE
GET /{deptId}/members 获取部门成员 -
GET /by-type/{deptType} 根据类型查询部门 -

部门树构建：后端返回扁平列表，Controller层递归构建树形结构（DeptVO含children字段）

3.6 ProjectMemberController — 项目成员管理

基础路径: /api/auth/projects

方法 路径 说明 审计日志
GET /{projectId}/members 查询项目成员列表（分页） -
GET /{projectId}/available-members 获取可添加成员（企业员工） -
POST /{projectId}/members 添加项目成员 CREATE
DELETE /{projectId}/members/{userId} 移除项目成员 DELETE

添加项目成员流程：

  1. 创建/更新 ProjectStaff 记录（设定员工类型、分配状态）
  2. 覆盖模式更新角色：先删除旧角色，再添加新角色
  3. 支持 search 参数模糊搜索可用成员（用户名/姓名）

3.7 DataAccessController — 数据访问授权

基础路径: /api/data-access

方法 路径 说明 请求体
POST / 授予数据访问权限 {dataType, dataId, accessType, accessId, accessLevel}
DELETE /{id} 撤销数据访问权限 -
GET / 查询数据访问记录 参数: dataType, dataId

授权逻辑：若已存在相同 dataType+dataId+accessType+accessId 的记录，则更新 accessLevel；否则新建。

3.8 AuditLogController — 审计日志

基础路径: /api/audit-logs

方法 路径 说明
GET / 分页查询审计日志（支持module/action/username/日期范围筛选）
GET /modules 获取模块列表（用于筛选下拉）
GET /actions 获取操作类型列表（用于筛选下拉）
GET /stats 获取最近30天日志统计

查询约束：强制限制查询范围不超过30天，防止大量数据查询。

模块列表：USER / ROLE / PERMISSION / PROJECT / AUTH

3.9 SysConfigController — 系统配置

基础路径: /api/config

方法 路径 说明 审计日志
GET / 获取所有配置项 -
GET /{configKey} 根据键获取配置 -
PUT /{configKey} 更新单个配置 UPDATE
PUT / 批量更新配置 UPDATE

四、业务规则

4.1 RBAC 权限模型

模型结构：User ←M2M→ Role ←M2M→ Permission

双层角色分配：

  1. 用户直接角色：通过 auth_user_role 表关联，用户创建时或通过 UserController.assignRoles 分配
  2. 项目员工角色：通过 ProjectStaffRole 关联，项目成员管理时分配

登录时角色收集：

用户所有角色 = 用户直接角色 ∪ 项目员工角色

角色类型与数据范围：

角色类型 说明 数据范围
SYSTEM 系统级角色，跨项目 ALL
PROJECT 项目级角色，绑定特定项目 PROJECT
DEPARTMENT 部门级角色 DEPARTMENT

4.2 四级数据范围

数据范围 编码 说明 实际效果
全部 ALL 可查看所有数据 不做数据过滤
项目 PROJECT 仅可查看所属项目数据 过滤 project_id
部门 DEPARTMENT 仅可查看本部门数据 过滤 project_id + dept_id
本人 SELF 仅可查看本人数据 过滤 assigned_to/creator

DataScopeService 实现：

  • canAccessAllData(): 检查角色集中是否有 ALL 范围
  • isSelfScopeOnly(): 检查是否所有角色都是 SELF 范围
  • getPermittedProjectIds(): 获取用户可访问的项目ID列表

4.3 JWT 认证流程

Token 生成：

  • 算法：HMAC-SHA256
  • Claims：userId（subject）、username、roles 列表
  • 过期时间：可配置（默认86400000ms = 24小时）

认证流程：

1. 客户端 POST /api/auth/login {username, password}
2. 检查登录锁定（Redis: login:attempt:{username}）
3. 查询用户 + 验证密码（BCrypt）
4. 检查用户状态
5. 收集角色（直接角色 + 项目员工角色）
6. 生成 JWT Token
7. 返回 {token, userId, username, realName, roles}

后续请求：
1. 客户端 Header: Authorization: Bearer {token}
2. JwtTokenProvider.validateToken() 验证签名和过期
3. 解析 userId / username / roles

Token 刷新：

  • POST /api/auth/refresh，需携带有效Token
  • 生成新Token返回

4.4 登录失败锁定机制

实现：LoginAttemptService（基于Redis）

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

流程：

  • 每次失败：increment计数，首次设置TTL
  • 达到上限：isLockedOut返回true，拒绝登录
  • 登录成功：清除计数
  • 手动解锁：unlock方法清除Key

4.5 项目隔离机制

双层隔离：

  1. UserProject 关联：用户-项目多对多，记录用户参与的项目
  2. ProjectStaff 扩展：项目员工在特定项目中的详细角色和状态

项目上下文传递：

  • 请求头 X-Project-ID 携带当前项目ID
  • ProjectContextInterceptor 拦截器设置 ThreadLocal
  • 业务层通过 DataScopeService 过滤数据

项目成员管理：

  • 添加成员：创建 ProjectStaff + 分配 ProjectStaffRole
  • 移除成员：删除 ProjectStaff（级联删除角色关联）
  • 角色分配：覆盖模式（先删后加）

4.6 审计日志

记录方式：@OperationLog 注解 + AOP切面

@OperationLog(operation = "创建用户", module = "USER", action = AuditLog.ActionType.CREATE)

异步持久化：通过 auditLogExecutor 线程池异步保存，避免影响业务性能

查询窗口：强制限制30天，超过30天的查询自动截断起始时间

归档策略：90天以上日志归档（当前实现为直接删除，TODO: 导出至对象存储）

记录模块：USER / ROLE / PERMISSION / PROJECT / AUTH / DEPT / PROJECT_MEMBER / SYSTEM

4.7 密码加密与强度校验

加密算法：BCrypt（Spring Security PasswordEncoder）

强度校验规则（可配置，前缀 password.*）：

规则 默认值 说明
minLength 8 最小长度
maxLength 20 最大长度
requireUppercase true 需要大写字母
requireLowercase true 需要小写字母
requireDigit true 需要数字
requireSpecial true 需要特殊字符

弱密码检测：黑名单包含 password、123456、admin、qwerty、letmein、welcome、monkey、dragon

旧密码兼容：检测非BCrypt格式密码（MD5/SHA-1），强制返回false要求重置

五、前端操作流程

5.1 登录

页面：/auth/Login.vue

流程：

  1. 输入用户名 + 密码
  2. 调用 POST /api/auth/login
  3. 存储 Token 到本地
  4. 跳转至主页

前端API：auth.ts → login(), logout(), getCurrentUser(), refreshToken()

5.2 项目选择

流程：

  1. 登录后获取用户项目列表 GET /api/auth/users/{id}/projects
  2. 用户选择项目
  3. 后续请求携带 X-Project-ID Header

5.3 用户管理

页面：/system/Users.vue, /system/UserDetail.vue

操作：

  • 用户列表（分页、搜索、状态筛选）
  • 创建用户（用户名、密码、真实姓名、手机号、邮箱、用户类型、部门）
  • 编辑用户信息
  • 删除用户
  • 修改密码（需原密码）
  • 分配角色（多选，覆盖模式）
  • 查看用户参与的项目

前端API：user.ts → getUsers(), createUser(), updateUser(), deleteUser(), updatePassword(), assignRoles(), getUserProjects()

5.4 角色管理

页面：/system/Roles.vue

操作：

  • 角色列表（分页、搜索）
  • 创建角色（代码、名称、描述、类型、数据范围、所属项目、状态）
  • 编辑角色
  • 删除角色
  • 为角色分配权限（多选，覆盖模式）
  • 查看角色关联的用户

前端API：role.ts → getRoles(), createRole(), updateRole(), deleteRole(), assignPermissions(), getRolePermissions(), getRoleUsers(), getRolesByProject()

5.5 权限管理

页面：/system/Permissions.vue

操作：

  • 权限列表（分页、搜索）
  • 创建权限（代码、名称、类型、资源路径、HTTP方法、描述、父权限、排序）
  • 编辑权限
  • 删除权限
  • 按类型筛选（MENU/BUTTON/API）
  • 查看菜单权限

前端API：permission.ts → getPermissions(), createPermission(), updatePermission(), deletePermission(), getPermissionsByModule()

5.6 部门管理

页面：/system/Depts.vue

操作：

  • 部门树展示
  • 创建部门（名称、上级部门、类型、负责人、排序）
  • 编辑部门
  • 删除部门（需先删除子部门）
  • 查看部门成员
  • 按类型筛选部门

前端API：dept.ts → getDeptTree(), getAllDepts(), createDept(), updateDept(), deleteDept(), getDeptMembers(), getDeptsByType()

5.7 审计日志

页面：/system/Audit.vue

操作：

  • 日志列表（分页、模块/操作类型/用户名/日期范围筛选）
  • 查看日志统计（最近30天总量）
  • 模块和操作类型下拉选项

前端API：audit.ts → getAuditLogs(), getAuditModules(), getAuditActions(), getAuditStats()

5.8 系统设置

页面：/system/Settings.vue

操作：

  • 查看所有配置项（键值对）
  • 单个/批量更新配置值

前端API：system.ts → getConfig(), updateConfig()

六、与原需求文档 05-AUTH.md 的差异对比

6.1 实体差异

对比项 原需求 05-AUTH.md 实际代码实现 差异说明
Role.type SYSTEM / CUSTOM SYSTEM / PROJECT / DEPARTMENT 实际代码使用三级分类（系统/项目/部门），而非预设/自定义
Role 业务属性 有 businessType、terminalType、isFrontline 字段 无这些字段 实际代码未实现角色业务属性扩展
Role.status enabled (Boolean) status (RoleStatus枚举: ENABLED/DISABLED) 实际代码使用枚举而非布尔值
Permission 结构 有 projectId、module、resource、action、path、component、icon、parentId(UUID)、level、apiMethod、apiPath、enabled 无 projectId/module/resource/action/path/component/icon/parentId(UUID)/level/apiMethod/apiPath/enabled，有 parentCode(String)、resource、method 实际代码简化了权限结构，用 parentCode 替代 parentId，缺少菜单路由属性
Permission.type PermissionType 枚举 (MENU/BUTTON/API) String 类型 实际代码用字符串而非枚举
UserRole 关联 独立实体 UserRole（含 projectId、isDefault） JPA自动管理的 M2M 中间表 auth_user_role（无额外字段） 实际代码简化了关联，去掉了项目隔离和默认角色标记
OperationLog auth_operation_log 表，含 projectId、realName、description、requestBody、responseBody、responseStatus、hasError sys_audit_log 表，含 content、params、result、targetType、targetId、executionTimeMs、status、errorMsg、tenantId 实际代码使用了不同的表名和字段结构，增加了目标追踪和租户ID
VisitorCredential 完整实体（auth_visitor_credential） 不存在于 module-auth 访客凭证未在认证模块实现
EnterpriseUser 未提及 存在，共享主键一对一 实际代码增加了企业员工扩展实体
ProjectStaff 未提及 存在，独立主键一对一 实际代码增加了项目员工扩展实体
ProjectStaffRole 未提及 存在，项目员工-角色关联 实际代码增加了项目级角色分配机制
Resident 未提及 存在，含认证流程 实际代码增加了住户实体
ResidentSpace 未提及 存在，住户-房屋关联 实际代码增加了住户房屋绑定
Space 未提及 存在，房屋空间 实际代码增加了房屋空间实体
UserProject 未提及 存在，用户-项目关联 实际代码增加了用户项目多对多
DataAccess 未提及 存在，细粒度数据访问控制 实际代码增加了数据访问授权机制
Dept 未提及 存在，树形部门结构 实际代码增加了部门管理
SysConfig 未提及 存在，键值对配置 实际代码增加了系统配置
User.userType 未提及 存在，ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER 实际代码增加了用户类型区分
User.deptId 未提及 存在 实际代码增加了部门关联

6.2 API 差异

对比项 原需求 05-AUTH.md 实际代码实现 差异说明
API路径前缀 /api/v1/auth /api/auth 实际代码去掉了版本号 v1
认证接口 login/logout/refreshToken/currentUser/changePassword/userPermissions login/logout/refresh/me 实际代码缺少 changePassword 和 userPermissions 独立端点，/me 替代 currentUser
用户状态修改 POST /{id}/status 独立端点 通过 PUT /{id} 更新status字段 实际代码合并到通用更新接口
权限树 GET /permissions/tree 未实现 实际代码缺少权限树端点
权限校验 POST /check 未实现 实际代码缺少权限校验端点
用户菜单 GET /users/{id}/menus 未实现 实际代码缺少用户菜单端点
用户权限查询 GET /users/{id}/permissions 未实现 实际代码缺少用户权限查询端点
部门管理 未提及 完整CRUD + 树 + 成员查询 实际代码新增了部门管理
项目成员管理 未提及 完整CRUD + 可用成员查询 实际代码新增了项目成员管理
数据访问授权 未提及 grant/revoke/query 实际代码新增了数据访问授权
审计日志 未提及 完整查询 + 统计 + 筛选选项 实际代码新增了审计日志管理
系统配置 未提及 完整CRUD + 批量更新 实际代码新增了系统配置管理
企业员工 未提及 GET /users/enterprise 实际代码新增了企业员工列表
用户项目关联 未提及 完整CRUD 实际代码新增了用户项目关联

6.3 业务规则差异

对比项 原需求 05-AUTH.md 实际代码实现 差异说明
角色体系 13个预定义角色（SUPER_ADMIN到OWNER） 角色通过数据库动态管理，无硬编码预定义 实际代码采用灵活的角色管理，未绑定固定角色列表
数据权限SQL生成 DataScopeHelper 工具类生成SQL片段 DataScopeService 提供判断方法 实际代码未实现SQL自动注入，仅提供判断接口
项目上下文 ProjectContextHolder + 拦截器 同样实现，通过 X-Project-ID Header 基本一致
状态驱动权限 工单状态→操作映射设计 未在认证模块实现 实际代码未实现状态驱动权限（应在业务模块）
访客凭证 完整的二维码生成/验证流程 不存在于 module-auth 实际代码未实现访客凭证
登录失败锁定 未提及 Redis实现，5次失败锁10分钟 实际代码新增了登录安全机制
密码强度校验 未提及 完整的强度规则 + 弱密码检测 实际代码新增了密码安全策略
旧密码兼容 未提及 检测非BCrypt格式，强制重置 实际代码新增了密码迁移策略
审计日志 AOP切面 + 同步保存 AOP切面 + 异步保存 + 30天查询限制 + 90天归档 实际代码增强了审计日志管理
项目成员角色 未提及 双层角色（用户直接角色 + 项目员工角色） 实际代码新增了项目级角色分配
部门类型 未提及 5种部门类型（行政/工程/安保/客服/保洁） 实际代码新增了部门分类
住户认证 未提及 4种认证状态（未认证/待审核/已认证/已拒绝） 实际代码新增了住户认证流程
数据访问授权 未提及 通用数据访问控制（dataType/dataId/accessType/accessId/accessLevel） 实际代码新增了细粒度数据授权

6.4 差异总结

实际代码相比原需求增加的功能：

  1. 多类型用户扩展（EnterpriseUser / ProjectStaff / Resident）
  2. 项目成员管理（ProjectStaff + ProjectStaffRole）
  3. 部门管理（树形结构 + 5种类型）
  4. 住户与房屋关联（ResidentSpace + Space）
  5. 数据访问授权（DataAccess）
  6. 系统配置管理（SysConfig）
  7. 登录失败锁定（Redis）
  8. 密码强度校验 + 弱密码检测
  9. 审计日志增强（异步保存、30天窗口、90天归档）
  10. 用户-项目多对多关联（UserProject）

原需求中未实现的功能：

  1. 角色业务属性（businessType / terminalType / isFrontline）
  2. 权限树端点（GET /permissions/tree）
  3. 权限校验端点（POST /check）
  4. 用户菜单端点（GET /users/{id}/menus）
  5. 用户权限查询端点（GET /users/{id}/permissions）
  6. 访客凭证管理（VisitorCredential）
  7. 状态驱动权限（工单状态→操作映射）
  8. Permission 的菜单路由属性（path / component / icon）
  9. Permission 的模块/资源/操作拆分字段（module / resource / action）
  10. UserRole 关联的项目隔离和默认角色标记