senmesh-zc/backend/docs/接口文档-用户管理与记录查询.md

# 前端接口文档 —— 用户管理增强 & 机构账号查询 & 按手机号查询文件记录

> 版本：v1.2（2026-10-27，新增 1.4 修改用户姓名、1.5 批量创建机构用户）
> 适用后端：s-file（alita-bjy-uygur）
> Swagger 分组：「用户」「用户文件」

---

## 0. 通用约定

### 0.1 请求与认证

- 所有接口均需**登录后调用**，认证 token 按现有方式携带（header 或 cookie，与系统其他接口一致）。
- 新增接口均要求**平台管理员（超管）身份**（`uc_user.supeiror = true`），非管理员调用统一返回失败，提示「当前用户无操作权限」。

### 0.2 统一返回结构 `AlitaResult<T>`

```json
{
  "requestId": "xxx",
  "code": "200",
  "success": true,
  "msg": null,
  "data": { ... }
}
```

| 字段 | 说明 |
|---|---|
| code | `"200"` 成功；业务失败时 success=false，msg 为错误提示（如「不能禁用当前登录账号」） |
| success | 是否成功 |
| data | 业务数据，失败时为 null |

### 0.3 分页请求与返回

分页查询接口通过 **URL query 参数** 传递分页信息，返回结构 `Page<T>`：

```
pageNo      第几页，默认 1
pageSize    页宽，默认 20，上限 1000
needPage    是否分页，默认 true（无需传）
```

```json
{
  "pageNo": 1,
  "pageSize": 20,
  "pageCount": 5,
  "totalCount": 88,
  "entityList": [ ... ]
}
```

### 0.4 通用枚举（前后端共用）

**用户状态 `status`**

| 值 | 含义 |
|---|---|
| 1 | 待激活 |
| 2 | 已激活 |
| 3 | 已注销 |

**是否启用 `enabled`**：`true` 启用，`false` 禁用。

**文件状态 `fileStatus`**

| 值 | 含义 |
|---|---|
| 1 | 正常 |
| 2 | 失效 |
| 11 | 解析中 |
| 12 | 待审核 |
| 13 | 传输中 |
| 14 | 失败 |

**记录类型 `recordType`**（本文档 3.4 节专用）

| 值 | 含义 |
|---|---|
| 1 | 上传记录 |
| 2 | 发送记录（本端发起文件传输） |
| 3 | 接收记录（本端接收文件传输） |

> 发送/接收与部署侧有关，但**前端无需关心**：传入 `recordType` 后，后端按部署配置（内网/外网）自动映射到对应的 `root_type`；返回列表中每条记录也已回填 `recordType` / `recordTypeDesc`。

---

## 1. 用户管理：启用 / 禁用 / 注销

### 1.1 启用用户

将被禁用的账号重新启用（幂等：已启用的账号重复调用仍返回成功）。

- **URL**：`POST /user/enable`
- **权限**：平台管理员
- **Body**（application/json）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 目标用户 id |

- **返回**：`AlitaResult<Boolean>`，data 为 `true`
- **失败场景**：用户不存在；账号已注销（提示「已注销账号不可启用」）；非管理员

**请求示例**

```json
POST /user/enable
{ "userId": 10086 }
```

**返回示例**

```json
{ "code": "200", "success": true, "data": true }
```

### 1.2 禁用用户

禁用账号，禁用后该用户无法登录/使用系统（后端登录态校验会实时读取启用状态，被禁用用户下次请求即被拒绝）。幂等：已禁用的账号重复调用仍返回成功。

- **URL**：`POST /user/disable`
- **权限**：平台管理员
- **Body**（application/json）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 目标用户 id |

- **返回**：`AlitaResult<Boolean>`，data 为 `true`
- **失败场景**：
  - 用户不存在
  - `userId` 为当前登录人（提示「不能禁用当前登录账号」）
  - 目标是超级管理员（提示「不能禁用超级管理员账号」）
  - 目标已注销（提示「已注销账号无需禁用」）

**请求示例**

```json
POST /user/disable
{ "userId": 10086 }
```

### 1.3 注销用户（管理员直接注销）

管理员将账号直接置为**已注销**（status=3）并同步禁用（enabled=false），**不进入注销申请审批流程**。注销后账号不可恢复、不可登录。幂等：已注销账号重复调用返回成功。

- **URL**：`POST /user/admin_cancel`
- **权限**：平台管理员
- **Body**（application/json）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 目标用户 id |

- **返回**：`AlitaResult<Void>`，data 为 null
- **失败场景**：
  - 用户不存在
  - `userId` 为当前登录人（提示「不能注销当前登录账号」）
  - 目标是超级管理员（提示「不能注销超级管理员账号」）
  - 并发重复操作（提示「该用户正在注销,请勿重复操作」）

**请求示例**

```json
POST /user/admin_cancel
{ "userId": 10086 }
```

> **与既有接口的区别**：既有 `POST /user/cancel` 为机构内注销（限定当前登录机构、且要求目标账号启用中），供原「注销申请/同意」流程使用，保持不变；本接口供系统管理员在用户管理页面跨机构直接注销。

### 1.4 修改用户姓名

修改用户账号的真实姓名（`real_name`）。平台超管可修改全部用户；机构管理员仅可修改本机构用户（同一账号属于多个机构时，改的是账号本身，各机构下展示同步生效）。

- **URL**：`POST /user/modify_real_name`
- **权限**：平台超管（全部用户）/ 机构管理员（限本机构用户）
- **Body**（application/json）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | Long | 是 | 目标用户 id |
| realName | String | 是 | 新姓名，2-30 位，仅支持中文或英文姓名 |

- **返回**：`AlitaResult<Boolean>`，data 为 `true`
- **失败场景**：
  - 用户不存在
  - 目标已注销（提示「已注销账号不可修改姓名」）
  - 姓名格式错误（提示「姓名格式错误!（长度2-30位，仅支持中文或英文姓名）」）
  - 与原姓名一致（提示「姓名与原姓名一致，无需修改！」）
  - 机构管理员操作非本机构用户（提示「只能操作本机构的用户」）

**请求示例**

```json
POST /user/modify_real_name
{ "userId": 10086, "realName": "张三" }
```

**返回示例**

```json
{ "code": "200", "success": true, "data": true }
```

> **与既有接口的区别**：既有 `POST /user/modify_org_user_info` 为超管编辑企业用户完整信息（账号名/姓名/启用状态一起校验更新）；本接口仅更新姓名，供用户管理页与机构账号页的「修改姓名」入口使用。

### 1.5 批量创建机构用户

一次性提交多条「手机号 + 姓名」创建机构用户。**单条失败不影响其他条目**（每条独立事务），返回与入参**顺序一一对应**的逐条结果，前端据此展示失败项。

- **URL**：`POST /user/batch_create_org_user`
- **权限**：登录用户（机构取当前登录机构，与单条创建 `POST /user/create_org_user` 一致）
- **Body**（application/json，对象数组，单次最多 **500** 条）

数组元素字段：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | String | 是 | 手机号 |
| realName | String | 否 | 姓名 |

- **返回**：`AlitaResult<List<OrgUserCreateResultDTO>>`

**OrgUserCreateResultDTO 字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| phone | String | 手机号（回显入参） |
| realName | String | 姓名（回显入参） |
| success | Boolean | 是否创建成功 |
| userId | Long | 用户 id，失败时为 null |
| msg | String | 失败原因，成功时为 null |

**请求示例**

```json
POST /user/batch_create_org_user
[
  { "phone": "13800000001", "realName": "张三" },
  { "phone": "13800000002", "realName": "李四" }
]
```

**返回示例**

```json
{
  "code": "200",
  "success": true,
  "data": [
    { "phone": "13800000001", "realName": "张三", "success": true, "userId": 1001, "msg": null },
    { "phone": "13800000002", "realName": "李四", "success": false, "userId": null, "msg": "手机号已存在，不能重复添加" }
  ]
}
```

- **失败场景**（整体请求失败）：列表为空；超过 500 条（提示「单次批量创建不能超过500条」）。单条业务失败（手机号格式不正确、手机号已存在等）不使请求失败，体现在对应条目的 `success/msg` 中。

---

## 2. 系统管理员：查看各机构下的账号信息

### 2.1 分页查询机构账号

按机构维度查看账号信息。一行 = 一个机构下的一个账号（同一账号属于多个机构时会出现多行）。不传 `orgId` 时查询全部机构，传 `orgId` 时查看指定机构。

- **URL**：`GET /user/page/org_account`
- **权限**：平台管理员
- **参数**（URL query）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orgId | Long | 否 | 机构 id，不传查全部机构 |
| orgNameLike | String | 否 | 机构名称，模糊匹配 |
| usernameLike | String | 否 | 账号，模糊匹配 |
| realNameLike | String | 否 | 真实姓名，模糊匹配 |
| phoneLike | String | 否 | 手机号，模糊匹配 |
| enabled | Boolean | 否 | 是否启用：true/false |
| status | Integer | 否 | 用户状态：1 待激活 / 2 已激活 / 3 已注销 |
| createTimeStart | String | 否 | 创建时间起，格式 `yyyy-MM-dd HH:mm:ss` |
| createTimeEnd | String | 否 | 创建时间止，格式 `yyyy-MM-dd HH:mm:ss` |
| pageNo / pageSize | Integer | 否 | 分页参数，默认 1 / 20 |

- **返回**：`AlitaResult<Page<OrgAccountDTO>>`

**OrgAccountDTO 字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| orgId | Long | 机构 id |
| orgName | String | 机构名称 |
| administrator | Boolean | 是否该机构的管理员 |
| userId | Long | 用户 id（可传给 1.1/1.2/1.3 接口做启停/注销操作） |
| username | String | 账号 |
| nickname | String | 昵称 |
| realName | String | 真实姓名 |
| phone | String | 手机号 |
| email | String | 邮箱 |
| userType | Integer | 用户类型：1 企业用户 / 2 个人用户 |
| enabled | Boolean | 是否启用 |
| status | Integer | 状态：1 待激活 / 2 已激活 / 3 已注销 |
| createTime | String | 创建时间 `yyyy-MM-dd HH:mm:ss` |

- **排序规则**：机构 id 升序，机构管理员排前面，同机构内按用户 id 倒序。

**请求示例**

```
GET /user/page/org_account?orgNameLike=教育&phoneLike=138&enabled=false&pageNo=1&pageSize=20
```

**返回示例**

```json
{
  "code": "200",
  "success": true,
  "data": {
    "pageNo": 1,
    "pageSize": 20,
    "pageCount": 1,
    "totalCount": 2,
    "entityList": [
      {
        "orgId": 12,
        "orgName": "XX市教育局",
        "administrator": true,
        "userId": 1001,
        "username": "admin_xx",
        "nickname": "张三",
        "realName": "张三",
        "phone": "13800000001",
        "email": "zhang@xx.gov.cn",
        "userType": 1,
        "enabled": false,
        "status": 2,
        "createTime": "2026-08-01 10:00:00"
      },
      {
        "orgId": 12,
        "orgName": "XX市教育局",
        "administrator": false,
        "userId": 1002,
        "username": "user_xx01",
        "nickname": "李四",
        "realName": "李四",
        "phone": "13800000002",
        "email": null,
        "userType": 1,
        "enabled": true,
        "status": 2,
        "createTime": "2026-08-03 14:30:00"
      }
    ]
  }
}
```

---

## 3. 按手机号查询文件记录（上传 / 发送 / 接收）

### 3.1 分页查询

输入手机号，精确匹配该手机号名下（可能是多个账号）的全部文件记录，可按记录类型筛选。

- **URL**：`GET /user_file/record/page_by_phone`
- **权限**：平台管理员
- **参数**（URL query）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| phone | String | **是** | 用户手机号，精确匹配，同一手机号关联的所有账号均会命中 |
| recordType | Integer | 否 | 1 上传记录 / 2 发送记录 / 3 接收记录，**不传查全部三类** |
| fileNameLike | String | 否 | 文件名，模糊匹配 |
| fileType | String | 否 | 文件类型：`1` 文件 / `2` 文件夹 |
| fileStatus | String | 否 | 文件状态：1 正常 / 2 失效 / 11 解析中 / 12 待审核 / 13 传输中 / 14 失败 |
| createTimeBegin | String | 否 | 记录时间起，格式 `yyyy-MM-dd HH:mm:ss` |
| createTimeEnd | String | 否 | 记录时间止，格式 `yyyy-MM-dd HH:mm:ss` |
| pageNo / pageSize | Integer | 否 | 分页参数，默认 1 / 20 |

- **返回**：`AlitaResult<Page<UserFileRecordDTO>>`

**UserFileRecordDTO 字段**（继承用户文件全部字段，以下为主要字段）

| 字段 | 类型 | 说明 |
|---|---|---|
| id | Long | 记录 id |
| phone | String | 归属手机号 |
| username | String | 归属账号 |
| realName | String | 归属真实姓名 |
| userType | Integer | 归属用户类型：1 企业用户 / 2 个人用户 |
| recordType | Integer | 记录类型：1 上传 / 2 发送 / 3 接收 |
| recordTypeDesc | String | 记录类型描述（「上传记录」「发送记录」「接收记录」） |
| userId | Long | 归属用户 id |
| rootType | String | 原始根类型：1 普通 / 2 内穿外 / 3 外传内（调试用，前端一般用 recordType 即可） |
| fileType | String | 文件大类：1 文件 / 2 文件夹 |
| fileName | String | 文件名 |
| fileCode | String | 物理文件编码 |
| fileSize | Long | 文件大小（字节） |
| fileStatus | String | 文件状态：1 正常 / 2 失效 / 11 解析中 / 12 待审核 / 13 传输中 / 14 失败 |
| createTime | String | 记录时间（上传/发送/接收发起时间）`yyyy-MM-dd HH:mm:ss` |
| endTime | String | 有效期（分享类记录使用），可能为 null |
| fileCategory | String | 文件种类（文档/图片/视频等，按后缀归类） |
| maxRiskLevel | String | 最高风险等级：1 重度 / 2 中度 / 3 轻度，可能为 null |

- **排序**：记录 id 倒序（即时间倒序）。
- **失败场景**：phone 为空；recordType 非法（提示「记录类型不合法,仅支持1上传/2发送/3接收」）；非管理员。

**请求示例**

```
GET /user_file/record/page_by_phone?phone=13800000001&recordType=2&pageNo=1&pageSize=10
```

**返回示例**

```json
{
  "code": "200",
  "success": true,
  "data": {
    "pageNo": 1,
    "pageSize": 10,
    "pageCount": 1,
    "totalCount": 2,
    "entityList": [
      {
        "id": 9001,
        "phone": "13800000001",
        "username": "user_xx01",
        "realName": "李四",
        "userType": 1,
        "recordType": 2,
        "recordTypeDesc": "发送记录",
        "userId": 1002,
        "rootType": "2",
        "fileType": "2",
        "fileName": "2026年预算材料_20260912103000",
        "fileCode": null,
        "fileSize": null,
        "fileStatus": "1",
        "createTime": "2026-09-12 10:30:00",
        "endTime": null,
        "fileCategory": null,
        "maxRiskLevel": null
      },
      {
        "id": 8802,
        "phone": "13800000001",
        "username": "user_xx01",
        "realName": "李四",
        "userType": 1,
        "recordType": 1,
        "recordTypeDesc": "上传记录",
        "userId": 1002,
        "rootType": "1",
        "fileType": "1",
        "fileName": "工作总结.docx",
        "fileCode": "fc_3a7d92",
        "fileSize": 1048576,
        "fileStatus": "1",
        "createTime": "2026-09-10 09:12:00",
        "endTime": null,
        "fileCategory": "文档",
        "maxRiskLevel": null
      }
    ]
  }
}
```

> **记录类型口径说明**（便于前端理解，无需处理）：
> - 上传记录：用户在网盘中上传的文件/文件夹（rootType=1）。
> - 发送记录：用户发起的文件传输（文件夹整体外发，传输中状态为 13，完成后变 1，失败为 14）。
> - 接收记录：对端传来的文件在本端解包后归属到该手机号用户的记录（若开启风险审查，先为 12 待审核，通过后为 1）。

---

## 4. 错误处理建议

前端统一按 `success=false` 判定失败并 toast `msg`；特殊 code 沿用系统既有约定（`401` 未登录等，与现有接口一致）。

涉及本批接口的典型业务错误文案：

| 场景 | msg |
|---|---|
| 非平台管理员操作 | 当前用户无操作权限 |
| 启用已注销账号 | 已注销账号不可启用 |
| 禁用/注销自己 | 不能禁用当前登录账号 / 不能注销当前登录账号 |
| 禁用/注销超管 | 不能禁用超级管理员账号 / 不能注销超级管理员账号 |
| recordType 非法 | 记录类型不合法,仅支持1上传/2发送/3接收 |
| phone 为空 | 手机号不能为空 |
| 修改姓名格式错误 | 姓名格式错误!（长度2-30位，仅支持中文或英文姓名） |
| 修改姓名与原值相同 | 姓名与原姓名一致，无需修改！ |
| 机构管理员越机构操作 | 只能操作本机构的用户 |