senmesh-zc/backend/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&lt;String&gt; | 允许的后缀（小写、不含点），`allowAllType=false` 时有值，否则为 null |
| maxFileSize | Long | 单文件大小上限（MB），null 或 0 表示不限制 |
| configured | Boolean | **机构是否已配置过**。`false` 表示当前是默认策略（允许上传全部类型、不限大小），前端此时可不限制文件选择器 |

**返回示例（已配置）**

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

**返回示例（未配置过）**

```json
{
  "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&lt;String&gt; | 条件必填 | `allowAllType=false` 时必填且不能为空；后缀可带可不带点，自动小写去重 |
| maxFileSize | Long | 否 | 单文件上限（MB），null 或 0 不限制；传负数报错 |

**校验失败提示**

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

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

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

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

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

**返回示例**

```json
{ "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` 说明原因（与真实上传被拦截时的文案一致）。

**不通过返回示例**

```json
{
  "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`。