# 权限与账户领域技术方案

**领域编号**: 4.5  
**微服务**: ether-auth  
**最后更新**: 2026-04-26

> **更新记录**:
> - 2026-04-26: 反向同步实际代码实现到文档。主要变更：Role.type 改为 SYSTEM/PROJECT/DEPARTMENT 三级分类；Role.status 改为 RoleStatus 枚举；Permission 结构简化（parentCode 替代 parentId）；UserRole 简化为 M2M 中间表；OperationLog 更名为 AuditLog（表名和字段结构变更）；新增实体（EnterpriseUser/ProjectStaff/ProjectStaffRole/Resident/ResidentSpace/Space/UserProject/DataAccess/Dept/SysConfig）；新增 API（部门管理/项目成员管理/数据访问授权/审计日志/系统配置/企业员工/用户项目关联）；新增业务规则（登录失败锁定/密码强度校验/审计日志增强/项目成员角色/部门类型/住户认证）；角色体系改为数据库动态管理；API路径去掉v1版本号。标注 TODO 项：Permission 需增加菜单路由属性（path/component/icon）。

---

## 一、领域概述

### 1.1 领域职责

权限与账户领域负责 Ether 平台的身份认证与授权管理：
- 用户认证与登录
- RBAC 权限模型（角色-权限-用户关联）
- 项目隔离与数据权限
- 按钮级权限控制
- 状态驱动权限
- 访客凭证管理
- 操作日志审计

### 1.2 核心概念

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

---

## 二、角色体系设计

### 2.1 角色总览

| 类型 | 角色编码 | 角色名称 | 数据范围 | 终端类型 | 一线人员 |
|------|---------|---------|---------|---------|---------|
| **系统级** |
| 系统管理 | SUPER_ADMIN | 超级管理员 | ALL | ALL | 否 |
| 系统管理 | SYS_ADMIN | 系统管理员 | ALL | ADMIN_ONLY | 否 |
| **项目管理** |
| 项目管理 | PROPERTY_MANAGER | 物业经理 | PROJECT | ALL | 否 |
| 项目管理 | PROJECT_MANAGER | 项目经理 | PROJECT | ALL | 否 |
| **部门主管** |
| 工程管理 | ENGINEERING_LEAD | 工程主管 | DEPARTMENT | ALL | 否 |
| 安保管理 | SECURITY_LEAD | 安保主管 | DEPARTMENT | ALL | 否 |
| 保洁管理 | CLEANING_LEAD | 保洁主管 | DEPARTMENT | ALL | 否 |
| 财务管理 | FINANCE_LEAD | 财务主管 | DEPARTMENT | ALL | 否 |
| **一线执行** |
| 工程执行 | MAINTENANCE_STAFF | 维修人员 | SELF | MOBILE_ONLY | 是 |
| 安保执行 | SECURITY_STAFF | 安保人员 | SELF | MOBILE_ONLY | 是 |
| 保洁执行 | CLEANING_STAFF | 保洁人员 | SELF | MOBILE_ONLY | 是 |
| **服务支持** |
| 业主服务 | CS_STAFF | 客服人员 | PROJECT | ALL | 否 |
| **外部用户** |
| 业主 | OWNER | 业主 | SELF | OWNER_APP | 否 |

### 2.2 角色职责说明

#### 2.2.1 系统级角色

| 角色 | 职责范围 | 典型场景 |
|------|---------|---------|
| **超级管理员** | 系统最高权限，管理所有项目和用户 | 系统初始化、用户创建、项目创建 |
| **系统管理员** | 系统配置管理，不参与业务操作 | 系统参数配置、日志查看 |

#### 2.2.2 项目管理角色

| 角色 | 职责范围 | 典型场景 |
|------|---------|---------|
| **物业经理** | 项目经营第一负责人，拥有本项目全部权限 | 项目整体运营、费用审核、合同审批 |
| **项目经理** | 单项目管理，拥有本项目全部业务权限 | 工单管理、人员分配、报表查看 |

#### 2.2.3 部门主管角色

| 角色 | 管理模块 | 职责范围 | 典型场景 |
|------|---------|---------|---------|
| **工程主管** | 工单、设备、工程巡检 | 本部门工程事务管理 | 工单分配、设备管理、巡检计划制定 |
| **安保主管** | 安保巡检、访客管理 | 本部门安保事务管理 | 安保巡检计划、访客核验监督 |
| **保洁主管** | 保洁巡检、品质检查 | 本部门保洁事务管理 | 保洁巡检计划、品质检查 |
| **财务主管** | 账单、收费、费用审核 | 本部门财务事务管理 | 账单生成、费用审核、报表导出 |

#### 2.2.4 一线执行角色

| 角色 | 执行范围 | 终端限制 | 典型场景 |
|------|---------|---------|---------|
| **维修人员** | 工单处理、设备巡检 | 仅移动端 | 接单、维修、填报费用、设备巡检 |
| **安保人员** | 安保巡检、访客核验 | 仅移动端 | 扫码签到、访客核验、异常报送 |
| **保洁人员** | 保洁巡检、品质检查 | 仅移动端 | 扫码签到、品质异常报送 |

#### 2.2.5 服务支持角色

| 角色 | 职责范围 | 典型场景 |
|------|---------|---------|
| **客服人员** | 业主服务接口，不参与工单流程 | 业主咨询、资料维护、访客辅助核验 |

#### 2.2.6 外部用户角色

| 角色 | 权限范围 | 典型场景 |
|------|---------|---------|
| **业主** | 本人房产相关数据 | 在线报修、缴费、访客邀请、评价 |

---

## 三、领域模型

### 3.1 聚合根设计

#### User（系统用户）

```java
@Entity
@Table(name = "auth_user")
@Data
public class User {
    @Id
    private UUID id;
    
    private String username;       // 登录账号
    private String password;       // BCrypt加密密码
    private String salt;           // 密码盐值（BCrypt模式下冗余）
    
    private String realName;       // 真实姓名
    private String phone;
    private String email;
    private String avatar;         // 头像URL
    
    private UserStatus status;     // ACTIVE/LOCKED/DISABLED
    private UserType userType;     // ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER
    private UUID deptId;           // 所属部门ID
    
    private LocalDateTime lastLoginTime;
    private String lastLoginIp;
    
    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "auth_user_role",
        joinColumns = @JoinColumn(name = "user_id"),
        inverseJoinColumns = @JoinColumn(name = "role_id")
    )
    private List<Role> roles;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    private UUID createdBy;
}

public enum UserStatus {
    ACTIVE("正常"),
    LOCKED("锁定"),
    DISABLED("禁用");
}

public enum UserType {
    ENTERPRISE("企业员工"),
    PROJECT_STAFF("项目员工"),
    RESIDENT("住户"),
    CUSTOMER("客户");
}
```

#### Role（角色）

```java
@Entity
@Table(name = "auth_role")
@Data
public class Role {
    @Id
    private UUID id;
    private UUID projectId;        // 项目隔离（NULL表示系统级）
    
    private String name;           // 角色名称
    private String code;           // 角色编码
    private String description;    // 角色描述
    
    private RoleType type;         // SYSTEM(系统级)/PROJECT(项目级)/DEPARTMENT(部门级)
    
    // 数据权限范围（四级）
    private DataScope dataScope;   // ALL/PROJECT/DEPARTMENT/SELF
    
    // 角色状态（枚举替代布尔值）
    private RoleStatus status;     // ENABLED(启用)/DISABLED(禁用)
    
    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(
        name = "auth_role_permission",
        joinColumns = @JoinColumn(name = "role_id"),
        inverseJoinColumns = @JoinColumn(name = "permission_id")
    )
    private List<Permission> permissions;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

public enum RoleType {
    SYSTEM("系统级"),
    PROJECT("项目级"),
    DEPARTMENT("部门级");
}

public enum RoleStatus {
    ENABLED("启用"),
    DISABLED("禁用");
}

// 数据权限范围枚举（四级）
public enum DataScope {
    ALL("全部数据"),
    PROJECT("本项目数据"),
    DEPARTMENT("本部门数据"),
    SELF("仅本人数据");
}
```

> **注意**: 实际代码中角色通过数据库动态管理，无硬编码预定义角色列表。原设计中的 businessType/terminalType/isFrontline 业务属性字段未实现，如需使用需后续补充。

#### Permission（权限）

```java
@Entity
@Table(name = "auth_permission")
@Data
public class Permission {
    @Id
    private UUID id;
    
    private String name;           // 权限名称
    private String code;           // 权限编码: module:resource:action
    private String type;           // 权限类型: MENU/BUTTON/API（String类型）
    
    // 资源信息
    private String resource;       // 资源路径（API类型）
    private String method;         // HTTP方法（API类型）
    
    private String description;    // 权限描述
    
    // 树形结构（简化：parentCode替代parentId）
    private String parentCode;     // 父权限代码（替代原 parentId UUID引用）
    private Integer sortOrder;     // 排序序号
    
    @ManyToMany(fetch = FetchType.LAZY, mappedBy = "permissions")
    private List<Role> roles;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

> **TODO**: Permission 当前实现缺少菜单路由属性（path/component/icon），以及模块/资源/操作拆分字段（module/resource/action），需后续补充以支持前端菜单渲染和权限树展示。

### 3.2 关联实体

#### UserRole（用户角色关联）

> **注意**: 实际代码中 UserRole 已简化为 JPA 自动管理的 M2M 中间表 `auth_user_role`，仅包含 user_id 和 role_id 两个外键列，去掉了原设计中的 projectId 和 isDefault 字段。

```java
// auth_user_role 关联表（JPA自动管理，无独立实体）
// 字段: user_id (FK → auth_user), role_id (FK → auth_role)
```

#### RolePermission（角色权限关联）

```java
@Entity
@Table(name = "auth_role_permission")
@Data
public class RolePermission {
    @Id
    private UUID id;
    
    private UUID roleId;
    private UUID permissionId;
    
    private LocalDateTime createdAt;
}
```

---

## 四、权限编码规范

### 4.1 编码格式

**格式**: `module:resource:action`

| 组成部分 | 说明 | 示例值 |
|---------|------|--------|
| module | 模块标识 | system, mdm, ops, asset, finance |
| resource | 资源类型 | user, role, work_order, equipment, bill |
| action | 操作类型 | view, create, edit, delete, assign, accept, complete |

### 4.2 操作类型说明

| 操作类型 | 说明 | 适用场景 |
|---------|------|---------|
| view | 查看 | 列表、详情查看 |
| create | 创建 | 新增记录 |
| edit | 编辑 | 修改记录 |
| delete | 删除 | 删除记录 |
| assign | 分配 | 工单分配、任务分配 |
| accept | 接单 | 工单接单 |
| start | 开始 | 开始处理、开始巡检 |
| complete | 完成 | 完成工单、完成巡检 |
| transfer | 转单 | 工单转单 |
| close | 关闭 | 关闭工单 |
| evaluate | 评价 | 工单评价 |
| report_fee | 填报费用 | 工单费用填报 |
| audit_fee | 费用审核 | 费用审核 |
| audit_quality | 质量审核 | 质量审核 |
| export | 导出 | 数据导出 |
| generate_qr | 生成二维码 | 二维码生成 |
| scan_view | 扫码查看 | 扫码查看设备 |
| force_close | 强制闭环 | 逾期任务强制关闭 |
| verify | 核验 | 访客核验 |

---

## 五、认证授权流程

### 5.1 JWT Token 认证

```java
@Component
public class JwtTokenProvider {
    
    @Value("${jwt.secret}")
    private String jwtSecret;
    
    @Value("${jwt.expiration:86400000}")
    private long jwtExpiration;
    
    private SecretKey secretKey;
    
    @PostConstruct
    public void init() {
        this.secretKey = Keys.hmacShaKeyFor(jwtSecret.getBytes(StandardCharsets.UTF_8));
    }
    
    public String generateToken(User user, UUID projectId) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + jwtExpiration);
        
        return Jwts.builder()
            .setSubject(user.getId().toString())
            .claim("username", user.getUsername())
            .claim("realName", user.getRealName())
            .claim("projectId", projectId != null ? projectId.toString() : null)
            .setIssuedAt(now)
            .setExpiration(expiryDate)
            .signWith(secretKey, SignatureAlgorithm.HS256)
            .compact();
    }
    
    public boolean validateToken(String token) {
        try {
            Jwts.parserBuilder()
                .setSigningKey(secretKey)
                .build()
                .parseClaimsJws(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }
    
    public UUID getUserIdFromToken(String token) {
        Claims claims = Jwts.parserBuilder()
            .setSigningKey(secretKey)
            .build()
            .parseClaimsJws(token)
            .getBody();
        
        return UUID.fromString(claims.getSubject());
    }
    
    public UUID getProjectIdFromToken(String token) {
        Claims claims = Jwts.parserBuilder()
            .setSigningKey(secretKey)
            .build()
            .parseClaimsJws(token)
            .getBody();
        
        String projectId = claims.get("projectId", String.class);
        return projectId != null ? UUID.fromString(projectId) : null;
    }
}
```

### 5.2 项目上下文

```java
public class ProjectContextHolder {
    private static final ThreadLocal<UUID> PROJECT_CONTEXT = new ThreadLocal<>();
    
    public static void setCurrentProjectId(UUID projectId) {
        PROJECT_CONTEXT.set(projectId);
    }
    
    public static UUID getCurrentProjectId() {
        return PROJECT_CONTEXT.get();
    }
    
    public static void clear() {
        PROJECT_CONTEXT.remove();
    }
}

@Component
public class ProjectContextInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String projectId = request.getHeader("X-Project-ID");
        if (StringUtils.hasText(projectId)) {
            try {
                ProjectContextHolder.setCurrentProjectId(UUID.fromString(projectId));
            } catch (IllegalArgumentException e) {
                // 无效的Project ID格式
            }
        }
        return true;
    }
    
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        ProjectContextHolder.clear();
    }
}
```

### 5.3 权限检查

```java
@Service
public class PermissionService {
    
    @Autowired
    private UserRepository userRepository;
    
    @Autowired
    private RoleRepository roleRepository;
    
    // 检查用户是否有指定权限
    public boolean hasPermission(UUID userId, String permissionCode) {
        User user = userRepository.findById(userId)
            .orElseThrow(() -> new NotFoundException("用户不存在"));
        
        // 超级管理员拥有所有权限
        if (isSuperAdmin(user)) {
            return true;
        }
        
        // 检查用户角色是否包含该权限
        for (Role role : user.getRoles()) {
            if (!role.getEnabled()) {
                continue;
            }
            for (Permission permission : role.getPermissions()) {
                if (permission.getCode().equals(permissionCode)) {
                    return true;
                }
            }
        }
        
        return false;
    }
    
    // 检查用户是否有指定权限（带项目隔离）
    public boolean hasPermission(UUID userId, UUID projectId, String permissionCode) {
        // 超级管理员
        if (isSuperAdmin(userId)) {
            return true;
        }
        
        // 获取用户在该项目下的权限
        List<Permission> permissions = permissionRepository
            .findPermissionsByUserIdAndProjectId(userId, projectId);
        
        return permissions.stream()
            .anyMatch(p -> p.getCode().equals(permissionCode));
    }
    
    // 获取用户菜单
    public List<Permission> getUserMenus(UUID userId, UUID projectId) {
        List<Permission> permissions = permissionRepository
            .findByUserIdAndProjectId(userId, projectId);
        
        return permissions.stream()
            .filter(p -> p.getType() == PermissionType.MENU)
            .filter(Permission::getEnabled)
            .sorted(Comparator.comparing(Permission::getSortOrder))
            .collect(Collectors.toList());
    }
}
```

---

## 六、数据权限设计

### 6.1 数据范围级别

| 数据范围 | 编码 | 说明 | SQL预设 |
|---------|------|------|---------|
| 全部 | ALL | 所有项目数据 | `WHERE 1=1` |
| 项目 | PROJECT | 本项目数据 | `WHERE project_id = $current_project` |
| 部门 | DEPARTMENT | 本部门数据 | `WHERE project_id = $current_project AND dept_id = $current_dept` |
| 本人 | SELF | 仅本人数据 | `WHERE assigned_to = $current_user` |

### 6.2 数据权限工具类

```java
public final class DataScopeHelper {
    
    public static String getDataFilterSql(String tableAlias, String creatorField, 
                                          String deptField, String projectField) {
        DataScopeInfo scope = DataScopeContext.getDataScopeInfo();
        String prefix = tableAlias != null ? tableAlias + "." : "";
        
        return switch (scope.getScope()) {
            case ALL -> "1=1";
            case PROJECT -> prefix + projectField + " = '" + scope.getProjectId() + "'";
            case DEPARTMENT -> prefix + projectField + " = '" + scope.getProjectId() + "' " +
                              "AND " + prefix + deptField + " = '" + scope.getDepartmentId() + "'";
            case SELF -> prefix + creatorField + " = '" + scope.getUserId() + "'";
        };
    }
    
    public static boolean canAccessData(UUID dataProjectId, UUID dataDeptId, UUID dataCreatorId) {
        DataScopeInfo scope = DataScopeContext.getDataScopeInfo();
        
        return switch (scope.getScope()) {
            case ALL -> true;
            case PROJECT -> dataProjectId.equals(scope.getProjectId());
            case DEPARTMENT -> dataProjectId.equals(scope.getProjectId()) && 
                              (dataDeptId == null || dataDeptId.equals(scope.getDepartmentId()));
            case SELF -> dataCreatorId.equals(scope.getUserId());
        };
    }
}
```

---

## 七、状态驱动权限

### 7.1 工单状态与操作映射

```java
public enum WorkOrderStatus {
    CREATED("已创建"),
    ASSIGNED("已分配"),
    ACCEPTED("已接单"),
    IN_PROGRESS("处理中"),
    PENDING("待确认"),
    COMPLETED("已完成"),
    CLOSED("已关闭"),
    SUSPENDED("已挂起"),
    RETURNED("已退回");
    
    // 获取该状态下可执行的操作
    public Set<WorkOrderAction> getAllowedActions() {
        return switch (this) {
            case CREATED -> Set.of(WorkOrderAction.ASSIGN, WorkOrderAction.EDIT, WorkOrderAction.DELETE);
            case ASSIGNED -> Set.of(WorkOrderAction.ACCEPT, WorkOrderAction.TRANSFER, 
                                    WorkOrderAction.SUSPEND, WorkOrderAction.RETURN);
            case ACCEPTED -> Set.of(WorkOrderAction.START, WorkOrderAction.TRANSFER, WorkOrderAction.SUSPEND);
            case IN_PROGRESS -> Set.of(WorkOrderAction.COMPLETE, WorkOrderAction.REPORT_FEE, WorkOrderAction.SUSPEND);
            case PENDING -> Set.of(WorkOrderAction.COMPLETE, WorkOrderAction.AUDIT_QUALITY);
            case COMPLETED -> Set.of(WorkOrderAction.EVALUATE, WorkOrderAction.CLOSE, WorkOrderAction.AUDIT_FEE);
            case CLOSED -> Set.of();
            case SUSPENDED -> Set.of(WorkOrderAction.RESUME);
            case RETURNED -> Set.of(WorkOrderAction.ASSIGN, WorkOrderAction.DELETE);
        };
    }
}

public enum WorkOrderAction {
    VIEW, CREATE, EDIT, DELETE,
    ASSIGN, ACCEPT, START, COMPLETE, TRANSFER, CLOSE, SUSPEND, RESUME, RETURN,
    EVALUATE, REPORT_FEE, AUDIT_FEE, AUDIT_QUALITY
}
```

### 7.2 权限校验增强

```java
// WorkOrderServiceImpl.java
public WorkOrder assign(UUID workOrderId, UUID assigneeId, String assigneeName) {
    WorkOrder workOrder = getWorkOrder(workOrderId);
    UUID currentUserId = getCurrentUserId();
    
    // 1. 状态校验
    validateStatusTransition(workOrder.getStatus(), WorkOrderStatus.ASSIGNED);
    
    // 2. 权限校验
    if (!hasActionPermission(workOrder, WorkOrderAction.ASSIGN)) {
        throw new PermissionDeniedException("无分配工单权限");
    }
    
    // 3. 数据权限校验
    if (!canAccessWorkOrder(workOrder)) {
        throw new PermissionDeniedException("无权访问该工单");
    }
    
    // 执行分配逻辑...
}

private boolean hasActionPermission(WorkOrder workOrder, WorkOrderAction action) {
    // 1. 检查状态是否允许该操作
    if (!workOrder.getStatus().getAllowedActions().contains(action)) {
        return false;
    }
    
    // 2. 检查用户是否有该操作的权限编码
    String permissionCode = "ops:work_order:" + action.name().toLowerCase();
    return permissionService.hasPermission(getCurrentUserId(), getProjectId(), permissionCode);
}

private boolean canAccessWorkOrder(WorkOrder workOrder) {
    DataScopeInfo scope = dataScopeContext.getDataScopeInfo();
    
    return switch (scope.getScope()) {
        case ALL -> true;
        case PROJECT -> workOrder.getProjectId().equals(scope.getProjectId());
        case DEPARTMENT -> workOrder.getDepartmentId().equals(scope.getDepartmentId());
        case SELF -> workOrder.getAssigneeId().equals(scope.getUserId()) ||
                     workOrder.getCreatorId().equals(scope.getUserId());
    };
}
```

---

## 八、访客凭证管理

### 8.1 访客凭证设计

```java
@Entity
@Table(name = "auth_visitor_credential")
@Data
public class VisitorCredential {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String visitorName;
    private String visitorPhone;
    private String visitorIdCard;
    
    private String credentialCode;
    private String qrCode;
    private LocalDateTime expireTime;
    
    private UUID spaceNodeId;
    private String accessGates;
    
    private CredentialStatus status;
    
    private LocalDateTime firstUseTime;
    private LocalDateTime lastUseTime;
    private Integer useCount;
    
    private UUID creatorId;
    private String creatorName;
    
    private LocalDateTime createdAt;
}

public enum CredentialStatus {
    ACTIVE("有效"),
    USED("已使用"),
    EXPIRED("已过期"),
    REVOKED("已撤销");
}
```

### 8.2 二维码生成与验证

```java
@Service
public class VisitorCredentialService {
    
    @Autowired
    private VisitorCredentialRepository credentialRepository;
    
    public VisitorCredential generateCredential(VisitorCredentialRequest request) {
        VisitorCredential credential = new VisitorCredential();
        credential.setId(UUID.randomUUID());
        credential.setProjectId(request.getProjectId());
        credential.setVisitorName(request.getVisitorName());
        credential.setVisitorPhone(request.getVisitorPhone());
        credential.setVisitorIdCard(request.getVisitorIdCard());
        credential.setSpaceNodeId(request.getSpaceNodeId());
        credential.setAccessGates(JsonUtils.toJson(request.getAccessGates()));
        credential.setStatus(CredentialStatus.ACTIVE);
        credential.setExpireTime(LocalDateTime.now().plusHours(24));
        credential.setUseCount(0);
        credential.setCreatorId(request.getCreatorId());
        credential.setCreatedAt(LocalDateTime.now());
        
        String qrContent = generateQrContent(credential);
        credential.setQrCode(qrContent);
        
        return credentialRepository.save(credential);
    }
    
    private String generateQrContent(VisitorCredential credential) {
        String data = String.format("VC:%s:%d", 
            credential.getId(), 
            System.currentTimeMillis());
        
        String signature = generateSignature(data);
        return data + ":" + signature;
    }
    
    public CredentialVerifyResult verifyCredential(String qrCode, String gateCode) {
        String[] parts = qrCode.split(":");
        if (parts.length != 4 || !"VC".equals(parts[0])) {
            return CredentialVerifyResult.fail("无效的二维码格式");
        }
        
        UUID credentialId = UUID.fromString(parts[1]);
        
        VisitorCredential credential = credentialRepository.findById(credentialId)
            .orElse(null);
        
        if (credential == null) {
            return CredentialVerifyResult.fail("凭证不存在");
        }
        
        if (credential.getStatus() == CredentialStatus.EXPIRED ||
            credential.getExpireTime().isBefore(LocalDateTime.now())) {
            return CredentialVerifyResult.fail("凭证已过期");
        }
        
        if (credential.getStatus() == CredentialStatus.REVOKED) {
            return CredentialVerifyResult.fail("凭证已撤销");
        }
        
        List<String> accessGates = JsonUtils.fromJson(credential.getAccessGates(), List.class);
        if (!accessGates.contains(gateCode)) {
            return CredentialVerifyResult.fail("无此门禁通行权限");
        }
        
        credential.setUseCount(credential.getUseCount() + 1);
        credential.setLastUseTime(LocalDateTime.now());
        if (credential.getFirstUseTime() == null) {
            credential.setFirstUseTime(LocalDateTime.now());
        }
        credentialRepository.save(credential);
        
        return CredentialVerifyResult.success(credential);
    }
}
```

---

## 九、审计日志

### 9.1 审计日志设计

> **注意**: 实际代码中操作日志已更名为审计日志（AuditLog），表名从 `auth_operation_log` 改为 `sys_audit_log`，字段结构也有较大变更，增加了目标追踪（targetType/targetId）、操作内容（content）、操作结果（result）、租户ID（tenantId）等字段，并采用异步持久化。

```java
@Entity
@Table(name = "sys_audit_log")
@Data
public class AuditLog {
    @Id
    private UUID id;
    
    private UUID userId;
    private String username;        // 操作用户名
    private String operation;       // 操作描述
    private String module;          // 模块标识
    private ActionType action;      // 操作类型枚举
    
    // 目标追踪（新增）
    private String targetType;      // 目标类型
    private String targetId;        // 目标ID
    
    // 操作详情（替代原 requestBody/responseBody）
    private String content;         // 操作内容
    private String params;          // 请求参数
    private String result;          // 操作结果
    
    private String ipAddress;
    private String userAgent;
    private String requestUrl;
    private String requestMethod;
    private Integer executionTimeMs; // 执行耗时(ms)
    
    private AuditStatus status;     // SUCCESS/FAIL
    private String errorMsg;        // 错误信息
    
    private UUID tenantId;          // 租户ID（新增）
    private LocalDateTime createdAt;
}

public enum ActionType {
    CREATE, UPDATE, DELETE, QUERY, VIEW,
    LOGIN, LOGOUT, EXPORT, IMPORT, ASSIGN, REVOKE;
}

public enum AuditStatus {
    SUCCESS("成功"),
    FAIL("失败");
}
```

### 9.2 日志记录注解

```java
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface OperationLog {
    String operation();
    String module();
    AuditLog.ActionType action();
}
```

> **业务规则**:
> - 审计日志通过 `@OperationLog` 注解 + AOP 切面自动记录
> - 采用异步持久化（`auditLogExecutor` 线程池），避免影响业务性能
> - 查询窗口强制限制30天，超过30天的查询自动截断起始时间
> - 归档策略：90天以上日志归档（当前实现为直接删除，TODO: 导出至对象存储）
> - 记录模块：USER / ROLE / PERMISSION / PROJECT / AUTH / DEPT / PROJECT_MEMBER / SYSTEM

---

## 十、API 接口

> **注意**: 实际代码中 API 路径已去掉 v1 版本号，统一为 `/api/auth` 前缀。

### 10.1 认证接口

```java
@RestController
@RequestMapping("/api/auth")
@Tag(name = "认证管理")
public class AuthController {

    @PostMapping("/login")
    @Operation(summary = "用户登录")
    public Result<LoginResponse> login(@RequestBody @Valid LoginRequest request);

    @PostMapping("/logout")
    @Operation(summary = "用户登出")
    public Result<Void> logout();

    @PostMapping("/refresh")
    @Operation(summary = "刷新Token")
    public Result<TokenResponse> refreshToken();

    @GetMapping("/me")
    @Operation(summary = "获取当前用户信息")
    public Result<UserVO> getCurrentUser();
}
```

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

### 10.2 用户管理接口

```java
@RestController
@RequestMapping("/api/auth/users")
@Tag(name = "用户管理")
public class UserController {

    @PostMapping
    @Operation(summary = "创建用户")
    public Result<UserVO> create(@RequestBody @Valid UserCreateRequest request);

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情")
    public Result<UserVO> getById(@PathVariable UUID id);

    @GetMapping
    @Operation(summary = "分页查询用户")
    public Result<Page<UserVO>> page(UserQueryRequest request);

    @PutMapping("/{id}")
    @Operation(summary = "更新用户")
    public Result<UserVO> update(@PathVariable UUID id, @RequestBody @Valid UserUpdateRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "删除用户")
    public Result<Void> delete(@PathVariable UUID id);

    @PutMapping("/{id}/password")
    @Operation(summary = "修改密码")
    public Result<Void> changePassword(@PathVariable UUID id, @RequestBody @Valid ChangePasswordRequest request);

    @PostMapping("/{id}/roles")
    @Operation(summary = "分配角色")
    public Result<Void> assignRoles(@PathVariable UUID id, @RequestBody UserRoleAssignRequest request);

    @GetMapping("/{id}/projects")
    @Operation(summary = "获取用户项目列表")
    public Result<List<UserProjectVO>> getUserProjects(@PathVariable UUID id);

    @PostMapping("/{id}/projects")
    @Operation(summary = "添加用户到项目")
    public Result<Void> addUserToProject(@PathVariable UUID id, @RequestBody UserProjectRequest request);

    @DeleteMapping("/{id}/projects/{projectId}")
    @Operation(summary = "从项目移除用户")
    public Result<Void> removeUserFromProject(@PathVariable UUID id, @PathVariable UUID projectId);

    @GetMapping("/enterprise")
    @Operation(summary = "获取企业员工列表")
    public Result<List<EnterpriseUserVO>> getEnterpriseUsers();
}
```

> **密码修改规则**（实际代码新增）:
> - 需验证原密码
> - 新密码需通过强度校验（8-20位，大小写+数字+特殊字符）
> - 弱密码检测（黑名单：password、123456、admin等）

### 10.3 角色权限接口

```java
@RestController
@RequestMapping("/api/auth/roles")
@Tag(name = "角色管理")
public class RoleController {

    @PostMapping
    @Operation(summary = "创建角色")
    public Result<RoleVO> createRole(@RequestBody @Valid RoleCreateRequest request);

    @GetMapping
    @Operation(summary = "分页查询角色列表")
    public Result<Page<RoleVO>> listRoles();

    @GetMapping("/{id}")
    @Operation(summary = "获取角色详情")
    public Result<RoleVO> getRoleById(@PathVariable UUID id);

    @GetMapping("/project/{projectId}")
    @Operation(summary = "根据项目ID查询角色")
    public Result<List<RoleVO>> getRolesByProject(@PathVariable UUID projectId);

    @PutMapping("/{id}")
    @Operation(summary = "更新角色")
    public Result<RoleVO> updateRole(@PathVariable UUID id, @RequestBody @Valid RoleUpdateRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "删除角色")
    public Result<Void> deleteRole(@PathVariable UUID id);

    @PostMapping("/{id}/permissions")
    @Operation(summary = "分配权限")
    public Result<Void> assignPermissions(@PathVariable UUID id, @RequestBody RolePermissionAssignRequest request);

    @GetMapping("/{id}/permissions")
    @Operation(summary = "获取角色权限列表")
    public Result<List<PermissionVO>> getRolePermissions(@PathVariable UUID id);

    @GetMapping("/{id}/users")
    @Operation(summary = "获取拥有某角色的用户")
    public Result<List<UserVO>> getRoleUsers(@PathVariable UUID id);
}
```

### 10.4 权限管理接口

```java
@RestController
@RequestMapping("/api/auth/permissions")
@Tag(name = "权限管理")
public class PermissionController {

    @PostMapping
    @Operation(summary = "创建权限")
    public Result<PermissionVO> createPermission(@RequestBody @Valid PermissionCreateRequest request);

    @GetMapping
    @Operation(summary = "分页查询权限列表")
    public Result<Page<PermissionVO>> listPermissions();

    @GetMapping("/{id}")
    @Operation(summary = "获取权限详情")
    public Result<PermissionVO> getPermissionById(@PathVariable UUID id);

    @GetMapping("/type/{type}")
    @Operation(summary = "根据类型查询权限")
    public Result<List<PermissionVO>> getPermissionsByType(@PathVariable String type);

    @GetMapping("/menus")
    @Operation(summary = "查询所有菜单权限")
    public Result<List<PermissionVO>> listMenuPermissions();

    @PutMapping("/{id}")
    @Operation(summary = "更新权限")
    public Result<PermissionVO> updatePermission(@PathVariable UUID id, @RequestBody @Valid PermissionUpdateRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "删除权限")
    public Result<Void> deletePermission(@PathVariable UUID id);
}
```

### 10.5 部门管理接口（新增）

```java
@RestController
@RequestMapping("/api/auth/depts")
@Tag(name = "部门管理")
public class DeptController {

    @GetMapping("/tree")
    @Operation(summary = "获取部门树")
    public Result<List<DeptTreeVO>> getDeptTree();

    @GetMapping
    @Operation(summary = "获取所有启用部门")
    public Result<List<DeptVO>> listActiveDepts();

    @GetMapping("/{id}")
    @Operation(summary = "获取部门详情")
    public Result<DeptVO> getById(@PathVariable UUID id);

    @PostMapping
    @Operation(summary = "创建部门")
    public Result<DeptVO> create(@RequestBody @Valid DeptCreateRequest request);

    @PutMapping("/{id}")
    @Operation(summary = "更新部门")
    public Result<DeptVO> update(@PathVariable UUID id, @RequestBody @Valid DeptUpdateRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "删除部门")
    public Result<Void> delete(@PathVariable UUID id);

    @GetMapping("/{deptId}/members")
    @Operation(summary = "获取部门成员")
    public Result<List<UserVO>> getDeptMembers(@PathVariable UUID deptId);

    @GetMapping("/by-type/{deptType}")
    @Operation(summary = "根据类型查询部门")
    public Result<List<DeptVO>> getDeptsByType(@PathVariable String deptType);
}
```

> **部门类型**: ADMIN(行政管理) / ENGINEERING(工程部) / SECURITY(安保部) / CS(客服部) / CLEANING(保洁部)

### 10.6 项目成员管理接口（新增）

```java
@RestController
@RequestMapping("/api/auth/projects")
@Tag(name = "项目成员管理")
public class ProjectMemberController {

    @GetMapping("/{projectId}/members")
    @Operation(summary = "查询项目成员列表（分页）")
    public Result<Page<ProjectStaffVO>> listMembers(@PathVariable UUID projectId);

    @GetMapping("/{projectId}/available-members")
    @Operation(summary = "获取可添加成员（企业员工）")
    public Result<List<EnterpriseUserVO>> getAvailableMembers(@PathVariable UUID projectId);

    @PostMapping("/{projectId}/members")
    @Operation(summary = "添加项目成员")
    public Result<Void> addMember(@PathVariable UUID projectId, @RequestBody AddMemberRequest request);

    @DeleteMapping("/{projectId}/members/{userId}")
    @Operation(summary = "移除项目成员")
    public Result<Void> removeMember(@PathVariable UUID projectId, @PathVariable UUID userId);
}
```

### 10.7 数据访问授权接口（新增，接口预留）

```java
@RestController
@RequestMapping("/api/data-access")
@Tag(name = "数据访问授权")
public class DataAccessController {

    @PostMapping
    @Operation(summary = "授予数据访问权限")
    public Result<DataAccessVO> grantAccess(@RequestBody @Valid DataAccessGrantRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "撤销数据访问权限")
    public Result<Void> revokeAccess(@PathVariable UUID id);

    @GetMapping
    @Operation(summary = "查询数据访问记录")
    public Result<List<DataAccessVO>> queryAccess(@RequestParam String dataType, @RequestParam UUID dataId);
}
```

### 10.8 审计日志接口（新增）

```java
@RestController
@RequestMapping("/api/audit-logs")
@Tag(name = "审计日志")
public class AuditLogController {

    @GetMapping
    @Operation(summary = "分页查询审计日志")
    public Result<Page<AuditLogVO>> page(AuditLogQueryRequest request);

    @GetMapping("/modules")
    @Operation(summary = "获取模块列表")
    public Result<List<String>> getModules();

    @GetMapping("/actions")
    @Operation(summary = "获取操作类型列表")
    public Result<List<String>> getActions();

    @GetMapping("/stats")
    @Operation(summary = "获取最近30天日志统计")
    public Result<AuditStatsVO> getStats();
}
```

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

### 10.9 系统配置接口（新增）

```java
@RestController
@RequestMapping("/api/config")
@Tag(name = "系统配置")
public class SysConfigController {

    @GetMapping
    @Operation(summary = "获取所有配置项")
    public Result<List<SysConfigVO>> listConfigs();

    @GetMapping("/{configKey}")
    @Operation(summary = "根据键获取配置")
    public Result<SysConfigVO> getConfig(@PathVariable String configKey);

    @PutMapping("/{configKey}")
    @Operation(summary = "更新单个配置")
    public Result<Void> updateConfig(@PathVariable String configKey, @RequestBody String configValue);

    @PutMapping
    @Operation(summary = "批量更新配置")
    public Result<Void> batchUpdateConfigs(@RequestBody List<SysConfigUpdateRequest> requests);
}
```

---

## 十一、实现状态与差异

### 11.1 实现状态

| 功能模块 | 实现状态 | 备注 |
|---------|---------|------|
| User | 🟢 已实现 | 基础CRUD，含 userType/deptId 扩展字段 |
| Role | 🟢 已实现 | 基础CRUD，三级分类(SYSTEM/PROJECT/DEPARTMENT)，RoleStatus枚举 |
| Permission | 🟢 已实现 | 基础CRUD，简化结构(parentCode替代parentId) |
| JWT认证 | 🟢 已实现 | Token生成/验证，含登录失败锁定(Redis) |
| 项目上下文 | 🟢 已实现 | 项目隔离 |
| 审计日志 | 🟢 已实现 | AuditLog(原OperationLog)，异步持久化，30天查询窗口 |
| 部门管理 | 🟢 已实现 | 树形结构，5种部门类型 |
| 项目成员管理 | 🟢 已实现 | ProjectStaff + ProjectStaffRole |
| 企业员工 | 🟢 已实现 | EnterpriseUser扩展实体 |
| 住户管理 | 🟢 已实现 | Resident + ResidentSpace + Space |
| 用户项目关联 | 🟢 已实现 | UserProject多对多 |
| 系统配置 | 🟢 已实现 | SysConfig键值对 |
| 数据访问授权 | 🟢 已实现 | DataAccess接口预留 |
| 登录失败锁定 | 🟢 已实现 | Redis实现，5次失败锁10分钟 |
| 密码强度校验 | 🟢 已实现 | 8-20位+大小写数字特殊字符+弱密码检测 |
| 数据权限 | 🟡 部分实现 | DataScopeService提供判断方法，未实现SQL自动注入 |
| 按钮级权限 | ⏳ 待实现 | 细粒度操作权限 |
| 状态驱动权限 | ⏳ 待实现 | 根据业务状态控制操作 |
| 字段脱敏 | ⏳ 待实现 | 敏感字段脱敏 |
| 访客凭证 | 🔴 未实现 | 原设计有但未在认证模块实现 |
| 角色业务属性 | 🔴 未实现 | businessType/terminalType/isFrontline未实现 |
| 权限树端点 | 🔴 未实现 | GET /permissions/tree |
| 权限校验端点 | 🔴 未实现 | POST /check |
| 用户菜单端点 | 🔴 未实现 | GET /users/{id}/menus |
| 用户权限查询端点 | 🔴 未实现 | GET /users/{id}/permissions |
| Permission菜单路由属性 | 🔴 未实现 | path/component/icon字段缺失 |

### 11.2 改进计划

| 优先级 | 改进项 | 说明 |
|--------|--------|------|
| P0 | Permission菜单路由属性 | 增加 path/component/icon/module/action 字段，支持前端菜单渲染 |
| P0 | 权限树端点 | 实现 GET /permissions/tree |
| P0 | 用户菜单端点 | 实现 GET /users/{id}/menus |
| P0 | 权限校验端点 | 实现 POST /check |
| P1 | 数据权限完善 | 实现SQL自动注入，补充PROJECT级别 |
| P1 | 角色业务属性 | 新增 businessType/terminalType/isFrontline 字段 |
| P1 | 按钮级权限控制 | 新增操作按钮权限编码 |
| P1 | 状态驱动权限 | 工单状态与操作联动 |
| P2 | 字段脱敏 | 敏感字段脱敏 |
| P2 | 访客凭证 | 在认证模块实现访客凭证管理 |
| P2 | 审计日志归档 | 导出至对象存储替代直接删除 |

---

## 十二、数据库表结构

```sql
-- 用户表
CREATE TABLE auth_user (
    id UUID PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    password VARCHAR(100) NOT NULL,
    salt VARCHAR(20) NOT NULL,
    real_name VARCHAR(100),
    phone VARCHAR(20),
    email VARCHAR(100),
    avatar VARCHAR(255),
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',
    last_login_time TIMESTAMP,
    last_login_ip VARCHAR(50),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    created_by UUID,
    UNIQUE(username)
);

-- 角色表
CREATE TABLE auth_role (
    id UUID PRIMARY KEY,
    project_id UUID,                    -- NULL表示系统级角色
    name VARCHAR(100) NOT NULL,
    code VARCHAR(50) NOT NULL,
    description VARCHAR(500),
    type VARCHAR(20) NOT NULL DEFAULT 'CUSTOM',
    data_scope VARCHAR(20) DEFAULT 'SELF',
    business_type VARCHAR(30),          -- 新增：业务类型
    terminal_type VARCHAR(20),          -- 新增：终端类型
    is_frontline BOOLEAN DEFAULT FALSE, -- 新增：是否一线人员
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, code)
);

-- 权限表
CREATE TABLE auth_permission (
    id UUID PRIMARY KEY,
    project_id UUID,                    -- NULL表示系统级权限
    name VARCHAR(100) NOT NULL,
    code VARCHAR(100) NOT NULL,         -- module:resource:action
    type VARCHAR(20) NOT NULL,
    module VARCHAR(50),                 -- 新增：模块标识
    resource VARCHAR(50),               -- 新增：资源类型
    action VARCHAR(30),                 -- 新增：操作类型
    path VARCHAR(255),
    component VARCHAR(255),
    icon VARCHAR(50),
    sort_order INTEGER DEFAULT 0,
    parent_id UUID,
    level INTEGER DEFAULT 0,
    api_method VARCHAR(10),
    api_path VARCHAR(255),
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(code, project_id)
);

-- 用户角色关联表
CREATE TABLE auth_user_role (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    role_id UUID NOT NULL,
    project_id UUID,
    is_default BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(user_id, role_id, project_id)
);

-- 角色权限关联表
CREATE TABLE auth_role_permission (
    id UUID PRIMARY KEY,
    role_id UUID NOT NULL,
    permission_id UUID NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(role_id, permission_id)
);

-- 项目表
CREATE TABLE auth_project (
    id UUID PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    code VARCHAR(50) NOT NULL,
    description VARCHAR(500),
    province VARCHAR(50),
    city VARCHAR(50),
    district VARCHAR(50),
    address VARCHAR(255),
    manager_id UUID,
    manager_name VARCHAR(100),
    manager_phone VARCHAR(20),
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',
    start_date DATE,
    end_date DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(code)
);

-- 访客凭证表
CREATE TABLE auth_visitor_credential (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    visitor_name VARCHAR(100) NOT NULL,
    visitor_phone VARCHAR(20),
    visitor_id_card VARCHAR(18),
    credential_code VARCHAR(50) NOT NULL,
    qr_code TEXT NOT NULL,
    expire_time TIMESTAMP NOT NULL,
    space_node_id UUID,
    access_gates JSONB,
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',
    first_use_time TIMESTAMP,
    last_use_time TIMESTAMP,
    use_count INTEGER DEFAULT 0,
    creator_id UUID,
    creator_name VARCHAR(100),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(credential_code)
);

-- 操作日志表
CREATE TABLE auth_operation_log (
    id UUID PRIMARY KEY,
    project_id UUID,
    user_id UUID,
    username VARCHAR(50),
    real_name VARCHAR(100),
    module VARCHAR(50) NOT NULL,
    operation VARCHAR(50) NOT NULL,
    description VARCHAR(255),
    request_method VARCHAR(10),
    request_url VARCHAR(255),
    request_params TEXT,
    request_body TEXT,
    response_status INTEGER,
    response_body TEXT,
    execution_time BIGINT,
    ip_address VARCHAR(50),
    user_agent TEXT,
    has_error BOOLEAN DEFAULT FALSE,
    error_message TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_user_username ON auth_user(username);
CREATE INDEX idx_user_status ON auth_user(status);
CREATE INDEX idx_role_project ON auth_role(project_id);
CREATE INDEX idx_permission_parent ON auth_permission(parent_id);
CREATE INDEX idx_permission_module ON auth_permission(module);
CREATE INDEX idx_user_role_user ON auth_user_role(user_id);
CREATE INDEX idx_user_role_role ON auth_user_role(role_id);
CREATE INDEX idx_role_permission_role ON auth_role_permission(role_id);
CREATE INDEX idx_credential_project ON auth_visitor_credential(project_id);
CREATE INDEX idx_credential_status ON auth_visitor_credential(status);
CREATE INDEX idx_operation_log_user ON auth_operation_log(user_id);
CREATE INDEX idx_operation_log_created ON auth_operation_log(created_at);
```

---

## 十三、更新记录

| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-02-10 | 创建权限与账户领域技术方案 | - |
| 2026-02-27 | 重构角色体系，新增13个角色 | - |
| 2026-02-27 | 新增权限编码规范 | - |
| 2026-02-27 | 新增数据权限四级范围 | - |
| 2026-02-27 | 新增状态驱动权限设计 | - |
| 2026-02-27 | 新增角色业务属性字段 | - |
| 2026-04-26 | 反向同步实际代码实现：Role.type改为SYSTEM/PROJECT/DEPARTMENT三级分类；Role.status改为RoleStatus枚举；Permission结构简化(parentCode替代parentId)；UserRole简化为M2M中间表；OperationLog更名为AuditLog；新增实体(EnterpriseUser/ProjectStaff/ProjectStaffRole/Resident/ResidentSpace/Space/UserProject/DataAccess/Dept/SysConfig)；新增API(部门管理/项目成员管理/数据访问授权/审计日志/系统配置/企业员工/用户项目关联)；新增业务规则(登录失败锁定/密码强度校验/审计日志增强/项目成员角色/部门类型/住户认证)；角色体系改为数据库动态管理；API路径去掉v1版本号；标注TODO: Permission需增加菜单路由属性 | - |

---

**文档维护**: 本领域技术方案由 ether-auth 服务负责人维护