通用上传（UploadController）

提供 KMS 知识管理模块「公共上传域」的能力：上传一个或多个文件到服务器 /uploads/avatar/ 目录（主要用于头像、附件等通用场景，不绑定到具体网盘/文件夹）。本控制器仅有 1 个端点。

• 接口类型：REST 资源（@RestController，方法未声明 produces，由全局消息转换器按 JSON 处理）
• 基址：${myapps.context-path.kms:}/api（类级 @RequestMapping 仅声明单一前缀）
• Tag：kms上传模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/upload 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health 等）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此本端点需 accessToken，可通过以下任一方式传递（据 Security.getUserIdFromToken）：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
• 执行用户：本端点不调用 getUser()，仅做文件落盘。
• 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。
• 存储路径：文件统一存至 ${storageRootPath}/uploads/avatar/ 下；文件名以 原名-Sequence序列号.扩展名 形式重命名以避免冲突。
• 路径变量：本控制器无路径变量。

---

1. 上传文件

上传一个或多个文件（multipart/form-data）到 /uploads/avatar/ 目录。服务端按原文件名+序列号重命名落盘，返回每个文件的元信息（原文件名、相对路径、类型、大小）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/upload（完整：{kms-context}/api/upload）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms上传模块

请求参数

参数名	位置	类型	必填	说明
file	body(form)	file[]	是	一个或多个文件（表单字段名固定为 file）

请求示例

POST /api/upload?accessToken=__TOKEN__ HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="avatar.png"
Content-Type: image/png

(二进制内容)
------WebKitFormBoundary--

响应

结构：统一 Resource。 data：JSONArray，每项结构如下：

字段	类型	说明
name	string	原始文件名（不含重命名后缀）
path	string	相对存储根目录的路径，如 /uploads/avatar/avatar-1700000000000.png
type	string	文件扩展名（不含 .）
size	long	文件大小（字节）

若未上传任何文件（multipartFiles.length == 0），data 为 null。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "name": "avatar.png", "path": "/uploads/avatar/avatar-1700000000000.png", "type": "png", "size": 20480 }
  ],
  "errors": null
}

---