用户管理模块

概述

用户模块负责系统用户的管理，包括用户信息、密码、角色关联、组织架构（上下级关系）、OAuth 第三方登录等功能。

模块路径：backend-fastapi/core/user/

API 前缀：/api/core/users

数据模型

class User(BaseModel):
    __tablename__ = "core_user"

    # 基本信息
    username: str       # 用户名（唯一）
    password: str       # 密码（bcrypt 加密）
    name: str           # 真实姓名
    email: str          # 邮箱
    mobile: str         # 手机号
    avatar: str         # 头像文件 ID
    gender: int         # 性别
    birthday: date      # 生日
    city: str           # 所在城市
    address: str        # 详细地址
    bio: str            # 个人简介

    # 状态与类型
    is_superuser: bool  # 是否超级管理员
    is_active: bool     # 是否激活
    user_type: int      # 用户类型
    user_status: int    # 用户状态

    # 组织关系（逻辑外键）
    dept_id: str        # 所属部门 ID
    post_id: str        # 所属岗位 ID
    manager_id: str     # 直属上级 ID

    # 登录信息
    last_login: datetime
    last_login_ip: str
    last_login_type: str

    # OAuth 字段
    oauth_provider: str
    gitee_id: str
    github_id: str
    qq_id: str
    google_id: str
    wechat_unionid: str
    wechat_openid: str
    microsoft_id: str
    dingtalk_unionid: str
    feishu_union_id: str
    wecom_userid: str

性别 (gender)

值	说明
0	未知
1	男
2	女

用户类型 (user_type)

值	说明
0	系统用户（不可删除）
1	普通用户
2	外部用户

用户状态 (user_status)

值	说明
0	禁用
1	正常
2	锁定

用户角色关联

用户与角色是多对多关系，通过 core_user_role 中间表关联：

class UserRole(BaseModel):
    __tablename__ = "core_user_role"

    user_id: str   # 用户 ID
    role_id: str   # 角色 ID

服务层

UserService 继承 BaseService，提供以下方法：

密码管理

方法	说明
hash_password(password)	使用 bcrypt 加密密码
verify_password(plain, hashed)	验证密码
change_password(db, user_id, old, new)	修改密码（需验证旧密码）
reset_password(db, user_id, new)	重置密码（管理员操作）

用户查询

方法	说明
get_by_username(db, username)	根据用户名查询
get_by_email(db, email)	根据邮箱查询
get_by_mobile(db, mobile)	根据手机号查询
get_by_dept(db, dept_id)	获取部门下的用户

认证

方法	说明
authenticate(db, username, password)	用户认证（登录）
update_last_login(db, user_id, ip, login_type)	更新登录信息

角色管理

方法	说明
get_user_role_ids(db, user_id)	获取用户的所有角色 ID
_invalidate_user_permission_cache(user_id)	清除用户权限缓存

组织架构

方法	说明
get_subordinates(db, user_id)	获取下属用户列表
get_subordinate_count(db, user_id)	获取下属数量
get_top_users(db)	获取顶层用户（无上级）
get_report_chain(db, user_id)	获取汇报链（当前用户到顶层）

批量操作

方法	说明
batch_update_status(db, ids, status)	批量更新用户状态

字段元数据

用户模块配置了敏感字段元数据，用于字段权限控制：

FIELD_METADATA = generate_field_metadata(
    User,
    sensitive_fields=['name', 'email', 'mobile', 'password'],
    maskable_fields=['name', 'email', 'mobile'],
    hidden_fields=['password'],
)

• sensitive_fields：敏感字段，可配置数据权限
• maskable_fields：可脱敏字段，支持部分隐藏（如 138****1234）
• hidden_fields：隐藏字段，API 响应中不返回

API 接口

基础 CRUD

方法	路径	说明
POST	/	创建用户（自动加密密码）
GET	/	获取用户列表（分页）
GET	/{record_id}	获取用户详情
PUT	/{record_id}	更新用户
DELETE	/{record_id}	删除用户

密码管理

方法	路径	说明
POST	/{record_id}/reset-password	重置密码（管理员）
POST	/change-password	修改密码（当前用户）

状态管理

方法	路径	说明
POST	/batch/status	批量更新状态

导入导出

方法	路径	说明
GET	/export/excel	导出 Excel
GET	/import/template	下载导入模板
POST	/import/excel	导入 Excel

权限缓存清除

当用户角色变更时，系统自动清除相关缓存：

1. Redis 用户信息缓存：中间件下次请求会重新加载
2. 菜单路由缓存：用户菜单会重新生成
3. API 权限缓存：权限检查会重新查询

与其他模块的关系

• 部门模块：用户通过 dept_id 关联部门
• 岗位模块：用户通过 post_id 关联岗位
• 角色模块：用户通过 core_user_role 关联多个角色
• 认证模块：登录时调用 authenticate 方法
• 工作流模块：审批人解析时查询用户的上级、部门等