leietal/senmesh-zc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
733dcb9fc0bce8d73d36108889a065197ba7c740
senmesh-zc/docs/接口文档-用户管理与记录查询.md

16 KiB
Raw Blame History

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

版本：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>

{
  "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（无需传）

{
  "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
  • 失败场景：用户不存在；账号已注销（提示「已注销账号不可启用」）；非管理员

请求示例

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

返回示例

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

1.2 禁用用户

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

  • URL：POST /user/disable
  • 权限：平台管理员
  • Body（application/json）
字段 类型 必填 说明
userId Long 是 目标用户 id
  • 返回：AlitaResult<Boolean>，data 为 true
  • 失败场景：
    • 用户不存在
    • userId 为当前登录人（提示「不能禁用当前登录账号」）
    • 目标是超级管理员（提示「不能禁用超级管理员账号」）
    • 目标已注销（提示「已注销账号无需禁用」）

请求示例

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 为当前登录人（提示「不能注销当前登录账号」）
    • 目标是超级管理员（提示「不能注销超级管理员账号」）
    • 并发重复操作（提示「该用户正在注销,请勿重复操作」）

请求示例

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位，仅支持中文或英文姓名）」）
    • 与原姓名一致（提示「姓名与原姓名一致，无需修改！」）
    • 机构管理员操作非本机构用户（提示「只能操作本机构的用户」）

请求示例

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

返回示例

{ "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

请求示例

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

返回示例

{
  "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

返回示例

{
  "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

返回示例

{
  "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位，仅支持中文或英文姓名）
修改姓名与原值相同 姓名与原姓名一致，无需修改！
机构管理员越机构操作 只能操作本机构的用户
Reference in New Issue View Git Blame Copy Permalink