:::tip 用户管理
用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数而非继承 BaseService 的类方法。
:::

## 模块结构

```
src/modules/system/user/
├── models.py     # 用户模型
├── schemas.py    # 表单验证
├── repository.py # 数据访问层
└── service.py    # 业务逻辑层（自定义函数）

src/modules/system/user_role/
├── models.py     # 用户-角色关联模型
├── repository.py # 关联数据访问
└── service.py    # 关联业务逻辑
```

## 用户模型

```python
# src/modules/system/user/models.py
# ============================================================
# 用户模型
# ============================================================
class User(base_model, base_db):
    """用户模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "user"
    __table_comment__ = "用户表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 用户编码
    code = Column(String(100), nullable=True, default='', server_default=text("''"), index=True, comment="用户编码")
    # 用户姓名
    realname = Column(String(150), nullable=False, index=True, comment="用户姓名")
    # 性别：1-男 2-女 3-保密
    gender = Column(Integer, default=1, server_default=text('1'), comment="性别：1-男 2-女 3-保密")
    # 用户头像
    avatar = Column(String(255), nullable=False, comment="用户头像")
    # 手机号
    mobile = Column(String(30), nullable=False, index=True, comment="手机号")
    # 邮箱
    email = Column(String(30), nullable=False, index=True, comment="邮箱")
    # 部门ID
    dept_id = Column(Integer, default=0, server_default=text('0'), index=True, comment="部门ID")
    # 职级ID
    level_id = Column(Integer, default=0, server_default=text('0'), comment="职级ID")
    # 岗位ID
    position_id = Column(Integer, default=0, server_default=text('0'), comment="岗位ID")
    # 省份编码
    province_code = Column(String(30), nullable=False, comment="省份编码")
    # 城市编码
    city_code = Column(String(30), nullable=False, comment="城市编码")
    # 县区编码
    district_code = Column(String(30), nullable=False, comment="县区编码")
    # 街道编码
    street_code = Column(String(30), nullable=False, comment="街道编码")
    # 省市区信息
    city_info = Column(String(255), nullable=True, comment="省市区信息")
    # 详细地址
    address = Column(String(255), nullable=False, comment="详细地址")
    # 用户名
    username = Column(String(30), nullable=True, index=True, comment="用户名")
    # 密码
    password = Column(String(255), nullable=True, comment="密码")
    # 加密盐
    salt = Column(String(30), nullable=True, comment="加密盐")
    # 个人简介
    intro = Column(String(255), nullable=True, comment="个人简介")
    # 状态：1-正常 2-禁用
    status = Column(Integer, default=1, server_default=text('1'), index=True, comment="状态：1-正常 2-禁用")
    # 排序
    sort = Column(Integer, default=0, server_default=text('0'), comment="排序")
    # 个人备注
    note = Column(String(255), nullable=True, comment="个人备注")

    # ============================================================
    # 内置方法
    # ============================================================
    def __str__(self):
        """返回用户ID作为字符串表示"""
        return "用户{}".format(self.id)
```

## 密码加密

使用 bcrypt 双重加盐方案，由 `src/core/password.py` 提供：

```python
# src/core/password.py
# +======================================================================
# | 模块: 密码加密工具
# | 说明: 基于 bcrypt 的双重加盐方案
# +======================================================================

"""密码加密工具：基于 bcrypt 的双重加盐方案。"""

import secrets

import bcrypt

# bcrypt 工作因子，值越大计算越慢越安全，默认12（约250ms）
BCRYPT_ROUNDS = 12


# ============================================================
# 密码工具函数
# ============================================================
def generate_salt(length: int = 10) -> str:
    """生成随机盐值"""
    return secrets.token_urlsafe(length)[:length]


def encrypt_password(password: str, salt: str) -> str:
    """使用 bcrypt 加密密码（外部 salt 双重加盐）"""
    combined = (password + salt).encode('utf-8')
    hashed = bcrypt.hashpw(combined, bcrypt.gensalt(rounds=BCRYPT_ROUNDS))
    return hashed.decode('utf-8')


def verify_password(password: str, salt: str, hashed: str) -> bool:
    """验证密码是否正确"""
    combined = (password + salt).encode('utf-8')
    return bcrypt.checkpw(combined, hashed.encode('utf-8'))
```

:::tip 双重加盐
密码加密采用双重加盐：外部 salt（存储在 user 表）+ bcrypt 内部 salt。即使数据库泄露，攻击者也无法通过彩虹表破解密码。工作因子 12，单次加密约 250ms。
:::

## 角色关联

用户与角色通过 `fastapi_user_role` 关联表实现多对多关系：

```python
# src/modules/system/user_role/models.py
# ============================================================
# 用户角色关联模型
# ============================================================
class UserRole(base_model, base_db):
    """用户角色关联模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "user_role"
    __table_comment__ = "用户角色关联表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 用户ID
    user_id = Column(Integer, default=0, server_default=text('0'), index=True, comment="用户ID")
    # 角色ID
    role_id = Column(Integer, default=0, server_default=text('0'), index=True, comment="角色ID")

    # ============================================================
    # 内置方法
    # ============================================================
    def __str__(self):
        """返回用户ID作为字符串表示"""
        return "用户角色表{}".format(self.user_id)
```

新增用户时同时创建角色关联，删除用户时硬删关联数据：

```python
# src/modules/system/user/service.py 关键片段
async def add_user(request, data: UserForm):
    """新增用户"""
    def _add():
        # 唯一性校验
        if user_repo.get_one(username=data.username):
            return R.failed("登录账号不能重复"), None

        formData = data.model_dump(exclude={'id', 'city', 'roles'})

        # 密码加密：未传密码时使用默认密码
        pwd = data.password or DEFAULT_PASSWORD
        salt = password.generate_salt()
        formData['password'] = password.encrypt_password(pwd, salt)
        formData['salt'] = salt

        # 行政区划处理
        citys = data.city or []
        formData['provinceCode'] = str(citys[0]) if len(citys) > 0 and citys[0] else ''
        # ... 其他字段处理

        user = user_repo.create(**formData, create_user=get_realname(request))
        user.code = f"{user.id:06d}"  # 根据自增ID生成6位用户编码
        return None, user.id

    err, user_id = await asyncio.to_thread(_add)
    if err:
        return err

    # 创建用户角色数据 + 清理权限缓存
    if data.roles is not None:
        await add_user_role(user_id, data.roles)

    return R.ok(msg="添加成功")
```

## 关联数据富化

用户列表和详情需要富化部门、职级、岗位、角色等关联数据：

```python
# src/modules/system/user/service.py
def _enrich_user_records(records):
    """为用户记录补充关联数据"""
    dept_map = {d.id: d.name for d in dept_repo.get_all()}
    level_map = {l.id: l.name for l in level_repo.get_all()}
    position_map = {p.id: p.name for p in position_repo.get_all()}
    gender_map = get_dict_map('gender')

    user_ids = [data.get("id") for data in records]
    role_map = get_user_role_map(user_ids)

    for data in records:
        data["genderName"] = gender_map.get(str(data.get("gender")))
        data["deptName"] = dept_map.get(data.get("deptId"))
        data["levelName"] = level_map.get(data.get("levelId"))
        data["positionName"] = position_map.get(data.get("positionId"))
        data["roles"] = role_map.get(data.get("id"), [])

    return records
```

## 权限缓存清理

用户增删改、角色变更、状态变更时需清理 Redis 中的权限和有效状态缓存：

```python
from utils.perm_cache import invalidate_user_perms, invalidate_user_active

# 角色变更后清理缓存
await invalidate_user_perms(user_id)
await invalidate_user_active(user_id)

# 状态变更后清理缓存（禁用即时踢出、启用即时放行）
await invalidate_user_perms(id)
await invalidate_user_active(id)
```

## Excel 导入导出

用户模块支持完整的 Excel 导入导出，导入列定义和导出列定义通过数组声明：

```python
# 导入列定义（顺序即 Excel 列序）
USER_IMPORT_COLUMNS = [
    {"title": "登录账号", "key": "username", "required": True},
    {"title": "用户姓名", "key": "realname", "required": True},
    {"title": "性别", "key": "gender", "parser": _parse_gender},
    {"title": "手机号", "key": "mobile", "required": True},
    {"title": "邮箱", "key": "email", "required": True},
    {"title": "部门", "key": "dept_id", "parser": _parse_dept},
    {"title": "职级", "key": "level_id", "parser": _parse_level},
    {"title": "岗位", "key": "position_id", "parser": _parse_position},
    {"title": "用户角色", "key": "roles", "parser": _parse_roles},
    {"title": "状态", "key": "status", "parser": _parse_status},
    {"title": "城市信息", "key": "city_codes", "parser": _parse_city_info},
    {"title": "详细地址", "key": "address", "required": True},
    # ...
]
```

:::tip 导入解析器
每个导入列可声明 `parser` 函数，负责将 Excel 单元格值转换为目标类型。例如 `_parse_dept` 按部门名称查询部门 ID，`_parse_roles` 按角色名称（逗号分隔）查询角色 ID 列表。解析失败时返回行级错误信息，不影响其他行。
:::

## API 接口

| 接口 | 方法 | 权限节点 | 说明 |
|------|------|---------|------|
| `/api/v1/user/page` | GET | `sys:user:page` | 用户分页列表 |
| `/api/v1/user/detail/{id}` | GET | `sys:user:detail` | 用户详情 |
| `/api/v1/user/add` | POST | `sys:user:add` | 新增用户 |
| `/api/v1/user/update` | PUT | `sys:user:update` | 编辑用户 |
| `/api/v1/user/delete/{id}` | DELETE | `sys:user:delete` | 删除用户 |
| `/api/v1/user/batchDelete` | DELETE | `sys:user:batchDelete` | 批量删除 |
| `/api/v1/user/status` | PUT | `sys:user:status` | 设置状态 |
| `/api/v1/user/resetPwd` | PUT | `sys:user:resetPwd` | 重置密码 |
| `/api/v1/user/updatePassword` | PUT | - | 修改密码（本人） |
| `/api/v1/user/updateInfo` | PUT | - | 更新个人信息 |
| `/api/v1/user/import` | POST | `sys:user:import` | 导入用户 |
| `/api/v1/user/export` | GET | `sys:user:export` | 导出用户 |

:::warning 内置超管保护
用户 ID 为 1 的内置超管账号（`SUPERADMIN_ID`）禁止通过管理接口修改、删除、禁用、重置密码。这些操作会在 service 层提前拦截并返回失败提示。
:::

## 总结

用户管理模块具备以下特点：

```
1. 复杂业务：自定义 service 函数，异步操作用 asyncio.to_thread 包裹
2. 密码安全：bcrypt 双重加盐，工作因子12（约250ms）
3. 角色关联：多对多关系，通过 user_role 关联表，删除时硬删关联
4. 权限缓存：角色/状态变更后即时清理 Redis 缓存
5. 关联富化：列表/详情补充部门、职级、岗位、角色、性别等展示名称
6. 行政区划：省/市/区/街道四级编码，自动拼接城市信息
7. Excel 导入导出：列定义式导入解析，逐行校验，部分成功返回明细
8. 超管保护：ID=1 账号禁止修改/删除/禁用/重置密码
```