UploadAuthtimeController（文件上传下载）

提供管理控制台通用的文件上传与下载能力：把 multipart 文件保存到平台存储根目录下的 uploads/<year>/ 子目录（或自定义 path 子目录），按 UUID 重命名（图标类文件保留原文件名）；按相对路径下载存储根目录下的文件。

• 类级基址：${myapps.context-path.manager:}/api/authtime（完整路径：{manager-context}/api/authtime<相对路径>）
• Tag：控制器未声明 @Tag（源码无 @Tag 注解）
• 控制器源码：obpm-manager/src/main/java/cn/myapps/manager/authtime/controller/common/UploadAuthtimeController.java
• 公共说明：
• 类继承 BaseAuthTimeController，通过其 success(errmsg, data) / error(errcode, errmsg, errors) 返回统一 Resource（字段 errcode/errmsg/data/errors，结构见 ../index.md「统一响应结构」）。
• 上传端点校验文件名（不允许包含 / 或 \）、文件扩展名（禁止 jsp;class;jspx;js；图标模式仅允许 png;ico;gif;jpg;jpeg;bmp），并阻止 path 参数包含 ../ 路径穿越；非法时返回 errcode=4001。
• 下载端点返回二进制流，**不**包统一 Resource；非法路径或文件不存在时抛 OBPMValidateException（由全局异常处理，HTTP 500）。
• 控制器方法显式标注 @ResponseStatus(HttpStatus.OK)。
• 鉴权说明见 index.md「鉴权说明」（adminToken JWT）。

---

1. 文件上传

接收一个或多个 multipart 文件，按规则保存到存储根目录下。普通文件以 <UUID>.<extName> 重命名落盘到 uploads/<year>/；图标文件（icon=true）保留原文件名落到 path 指定子目录，已存在则跳过该文件。

• 接口类型：REST 资源（multipart）
• 请求方式：POST
• 请求路径：/uploads（完整：{manager-context}/api/authtime/uploads）
• 鉴权：是（需管理员 adminToken，详见 index.md「鉴权说明」）
• Tag：（控制器未声明 @Tag）

请求参数

参数名	位置	类型	必填	说明
file	form-data	file[]	是	一个或多个上传文件（字段名固定为 file，可重复）
icon	query/form	boolean	否	是否图标上传模式，缺省 false
path	query/form	string	否	自定义保存子目录（相对存储根目录，含 ../ 或 ..\ 时返回 4001）

注：icon、path 通过控制器内 getParams() 读取，可由 query 串或 multipart 表单字段提供。

请求示例

POST /api/authtime/uploads?icon=false&path= HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="report.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

<二进制内容>
------WebKitFormBoundary--

响应

结构：统一 Resource。 data：JSONArray，元素 JSONObject 字段：

字段	类型	说明
fileName	string	实际保存的源文件名（多个文件循环结束时保留最后一个）
filePath	string	相对存储根目录的访问路径，普通模式为 /uploads/<year>/<uuid>.<ext>，图标模式为 <path>/<原文件名>

条件	errcode	errmsg	data
path 含 ../ 或 ..\	4001	上传的目录不合法！	null
文件扩展名为 jsp;class;jspx;js（或图标模式扩展名不在白名单）	4001	上传的文件类型不合法！	null
图标文件超 1GB	抛 OBPMValidateException（HTTP 500，无统一 Resource）	—	—
文件名含 / 或 \	抛 OBPMValidateException（HTTP 500，无统一 Resource）	—	—
成功	0	ok	[{ "fileName": "...", "filePath": "..." }]

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    { "fileName": "report.xlsx", "filePath": "/uploads/2026/a1b2c3d4-e5f6.xlsx" }
  ],
  "errors": null
}

失败示例：

{ "errcode": 4001, "errmsg": "上传的文件类型不合法！", "data": null, "errors": null }

---

2. 文件下载

按相对存储根目录的 filePath 流式下载文件（分块 1024 字节写到响应输出流）。

• 接口类型：REST 资源（二进制流）
• 请求方式：GET
• 请求路径：/download（完整：{manager-context}/api/authtime/download）
• 鉴权：是
• Tag：（控制器未声明 @Tag）

请求参数

参数名	位置	类型	必填	说明
filePath	query	string	是	文件相对存储根目录的路径；含 ../ 或 ..\、为空时抛 OBPMValidateException

请求示例

GET /api/authtime/download?filePath=/uploads/2026/a1b2c3d4-e5f6.xlsx HTTP/1.1

响应

• Content-Type：由 Servlet 容器默认决定（未显式设置）
• 状态码：200（成功）
• 响应体：文件二进制流（无统一 Resource）

条件	行为
filePath 为空 / 含 ../ / 含 ..\	抛 OBPMValidateException（非法文件路径！），全局异常处理返回 HTTP 500
文件不存在	抛 OBPMValidateException（文件不存在！），全局异常处理返回 HTTP 500
成功	流式写入文件二进制，HTTP 200

注：本端点返回 void，所有错误以异常形式抛出，不在响应体返回统一 Resource。

---