senmesh-zc/docs/接口文档-机构上传配置.md

前端接口文档 —— 机构上传配置（文件上传类型/大小限制）

版本：v1.0（2026-09-14） 适用后端：s-file（alita-bjy-uygur） Swagger 分组：「机构上传配置」

功能说明

机构管理员可以为本机构配置网盘上传策略：

• 上传总开关：关闭后本机构用户不能上传任何文件到网盘；
• 类型白名单：可限制只允许上传指定后缀的文件（如 doc、docx、pdf、jpg）；
• 单文件大小上限：单位 MB，超过即拒绝。

规则约定：

• 配置按机构隔离，作用于当前登录机构，管理的是本机构用户的网盘上传（normal_user_file/create 落库时强制校验）；
• 未配置过的机构 = 默认策略：允许上传、允许全部类型、不限大小（对现有用户完全兼容）；
• 个人用户（无登录机构）不受机构配置限制；
• 后缀不区分大小写，配置时可带可不带前导点（PDF、.pdf、pdf 等价），服务端统一转小写存储；
• 文件夹创建不受类型/大小校验影响；
• 文件传输（发送/接收）与分享不受此配置影响，该配置只管上传。

通用约定

与既有接口一致：登录态调用；统一返回 AlitaResult<T>（code="200" 且 success=true 成功；业务失败 success=false，msg 为提示文案）；时间格式 yyyy-MM-dd HH:mm:ss。

---

1. 查询当前机构的上传配置

• URL：GET /upload_config/info
• 权限：所有登录用户（前端可在上传前读取并据此过滤可选文件类型）
• 参数：无（按当前登录机构查询）
• 返回：AlitaResult<UploadConfigDTO>

UploadConfigDTO 字段

字段	类型	说明
orgId	Long	机构 id
uploadEnabled	Boolean	是否允许上传
allowAllType	Boolean	是否允许全部类型
allowedSuffixes	List<String>	允许的后缀（小写、不含点），allowAllType=false 时有值，否则为 null
maxFileSize	Long	单文件大小上限（MB），null 或 0 表示不限制
configured	Boolean	机构是否已配置过。false 表示当前是默认策略（允许上传全部类型、不限大小），前端此时可不限制文件选择器

返回示例（已配置）

{
  "code": "200",
  "success": true,
  "data": {
    "orgId": 12,
    "uploadEnabled": true,
    "allowAllType": false,
    "allowedSuffixes": ["doc", "docx", "pdf", "jpg", "png"],
    "maxFileSize": 200,
    "configured": true
  }
}

返回示例（未配置过）

{
  "code": "200",
  "success": true,
  "data": {
    "orgId": 12,
    "uploadEnabled": true,
    "allowAllType": true,
    "allowedSuffixes": null,
    "maxFileSize": null,
    "configured": false
  }
}

---

2. 保存机构的上传配置

Upsert：该机构无配置则新建，有则更新。

• URL：POST /upload_config/modify
• 权限：机构管理员 或 平台超管（其他用户返回「当前用户无操作权限」）
• Body（application/json）

字段	类型	必填	说明
uploadEnabled	Boolean	是	是否允许上传
allowAllType	Boolean	是	是否允许全部类型
allowedSuffixes	List<String>	条件必填	allowAllType=false 时必填且不能为空；后缀可带可不带点，自动小写去重
maxFileSize	Long	否	单文件上限（MB），null 或 0 不限制；传负数报错

校验失败提示

场景	msg
非机构管理员/超管	当前用户无操作权限
白名单为空	未允许全部类型时,允许的文件后缀不能为空
maxFileSize ≤ 0	单文件大小上限必须大于0
并发修改	上传配置正在修改,请稍后重试

请求示例（只允许文档和图片，单个最大 200MB）

POST /upload_config/modify
{
  "uploadEnabled": true,
  "allowAllType": false,
  "allowedSuffixes": ["doc", "docx", "xls", "xlsx", "pdf", "jpg", "png"],
  "maxFileSize": 200
}

请求示例（禁止本机构上传）

POST /upload_config/modify
{
  "uploadEnabled": false,
  "allowAllType": true
}

返回示例

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

---

3. 上传预检（可选，提升体验）

按文件名/大小对当前机构配置做一次预检，用于选择文件后、真正上传前给出友好提示，避免白传一遍物理文件才被拒绝。

• URL：GET /upload_config/check
• 权限：所有登录用户
• 参数（URL query）

参数	类型	必填	说明
fileName	String	是	完整文件名（含后缀）
fileSize	Long	否	文件大小（字节），不传则跳过大小校验

• 返回：通过时 {"code":"200","success":true,"data":true}；不通过时 success=false，msg 说明原因（与真实上传被拦截时的文案一致）。

不通过返回示例

{
  "code": "700",
  "success": false,
  "msg": "仅允许上传后缀为 doc、docx、pdf、jpg、png 的文件",
  "data": null
}

---

4. 上传被拦截时的服务端行为

用户上传最终在网盘创建记录接口（POST /normal_user_file/create）被强制校验，不通过时接口返回 success=false，msg 为以下之一：

场景	msg
机构关闭上传	当前机构已禁止上传文件,请联系机构管理员
后缀不在白名单	仅允许上传后缀为 doc、docx、pdf 的文件（动态列出）
机构白名单为空（异常配置）	当前机构未配置可上传的文件类型,请联系机构管理员
超过大小上限	上传文件过大,单文件最大不得超过200MB（动态数值）

前端建议：

1. 上传页加载时调 GET /upload_config/info：uploadEnabled=false 时直接隐藏/禁用上传入口；allowAllType=false 时设置文件选择器的 accept 过滤；
2. 选择文件后可先调 GET /upload_config/check 预检（可选）；
3. 真实上传两步（/file/upload → /normal_user_file/create）中第二步失败时直接 toast msg。