leijiaping
c305ca946e
1. 用户管理：新增启用(user/enable)/禁用(user/disable)/注销(user/admin_cancel)接口，
平台超管可操作全部用户，机构管理员限本机构；注销带分布式锁、禁自己/超管守卫
2. 禁用/注销立即踢下线：Redis黑名单(user:disabled:{uid}) + JWT过滤器拦截，
TTL与token有效期一致
3. 系统管理员查看各机构账号：GET user/page/org_account（机构/账号/手机号等筛选）
4. 按手机号查上传/发送/接收记录：GET user_file/record/page_by_phone，
发送/接收方向按部署侧 file.transfer.location 自动映射
5. 机构上传配置：新表 x_upload_config + upload_config/info|modify|check 接口，
上传总开关/后缀白名单/单文件大小限制，网盘落库时强制校验
6. 加固：UserInfoDTO.setPassword 缺省密码未配置时不再抛 rawPassword cannot be null
7. 新增 x_upload_config 建表脚本(upgrade-20260915-release.sql 为上线版)、
生产部署说明、前端接口文档×2、运维脚本 sfile-ctl.sh、AGENTS.md
182 lines
6.1 KiB
Markdown
182 lines
6.1 KiB
Markdown
# 前端接口文档 —— 机构上传配置（文件上传类型/大小限制）
|
||
|
||
> 版本：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` 表示当前是默认策略（允许上传全部类型、不限大小），前端此时可不限制文件选择器 |
|
||
|
||
**返回示例（已配置）**
|
||
|
||
```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<String> | 条件必填 | `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`。
|