# 6.1 用户管理

:::tip 概述
用户模块（goframe_user，租户级表）是机制最全的模块：唯一校验（按行现租户）、租户用户上限、角色全量重写、城市编解码、Excel 导入导出、数据权限接线、批量名称回填。路由前缀 /api/user。
:::

## 接口清单

| 方法 | 路由 | 权限 | 说明 |
|------|------|------|------|
| GET | /api/user/page | sys:user:page | 分页（关键词/状态/部门/角色/职级/岗位筛选） |
| GET | /api/user/list | sys:user:list | 全量列表（下拉选择用） |
| GET | /api/user/detail/:id | sys:user:detail | 详情（含角色 ID 数组与四级区划编码） |
| POST | /api/user/add | sys:user:add | 新增（返回新记录 ID） |
| PUT | /api/user/update | sys:user:update | 修改（密码留空不改） |
| PUT | /api/user/status | sys:user:status | 状态切换 |
| PUT | /api/user/resetPwd | sys:user:resetPwd | 重置密码（logType=reset） |
| DELETE | /api/user/delete/:id | sys:user:delete | 软删（清理 user_role） |
| DELETE | /api/user/batchDelete | sys:user:batchDelete | 批量删除 |
| POST | /api/user/import | sys:user:import | Excel 导入 |
| GET | /api/user/export | sys:user:export | Excel 导出 |
| GET | /api/user/document/:id | sys:user:detail | 打印信息 |

## 核心机制

### 唯一校验（手写，按行现租户）

```text
usernameExists / mobileExists 按 (username|mobile, tenant_id, 排除自身) 查；
Update 时先读被改行的 tenant_id 再校验——校验范围必须等于
uk_tenant_username / uk_tenant_mobile 索引范围（含 del_flag 由 dao.Ctx 恒过滤保证）。

历史教训：用 GetTenantID（超管=默认租户）会漏报 1062——必须按行现租户。
```

### 角色同步（AssignRoles）

```text
AssignRoles(userId, roleIds)：全量重写 user_role（先删后插）
  → clearIdentityCache(userId)
Add/Update 均经此方法；Update 改 dept_id 也在该路径清缓存——部门变更即时生效
（数据权限无需等 300s 缓存过期）
```

### 租户用户上限（checkTenantUserMax）

统计租户现有用户数 vs tenant.max_user_num，超限返回 1007。在 user.Add 生效。

### 用户编码（genUserCode）

```text
前缀=租户 code（平台/超管为 "SYS"），序号=该租户现有用户数+1
格式 "{prefix}-%06d"，如 T0001-000001
```

### 数据权限接线

userSpec 声明 `DataScope: ApplyDataScope("dept_id")`——user 是当前唯一接线模块（全库仅 user 表有 dept_id 列）。

### 列表名称回填（userExpandNames）

列表行批量补 dept/level/position/role 名称与城市文本（namesById/dictName 批查防 N+1）。

## 导入导出

```text
Import（POST /api/user/import）：
  excel.ReadSheet → 表头映射 → 逐行：唯一校验 / 租户上限 / 默认密码 bcrypt
  （事务外预计算）/ 角色与城市解析 → 批量插入 → 返回成功/失败统计
  城市列经 ResolveCityCodes(名称串) 转编码入库

Export（GET /api/user/export）：
  与列表同筛选（userFilter + DataScope，applyFilters 同链）
  → ChunkQuery 500/页 → excel.WriteSheet
  导出可见集 = 列表可见集（导出=所见）
```

## 城市编解码接入

Add/Update/Import/Detail 均接入包级函数：写侧 `ResolveCityCodes`（名称串 → 四级编码入库），读侧 `ResolveCityNames`（编码 → 名称还原）。机制见 [6.9 行政区划管理](./city)。

## 字段与安全边界

```text
password/salt：bcrypt 双重加盐；接口永不返回
密码留空 = 不修改（Update 语义）
删除守卫：userDeleteGuard / 关联清理（user_role）
SerializeMaps：status → user_status（{field}Text 字典填充）
FileFields: avatar + FileSaveDir: "user"（两段式上传自动转正）
```