# 门户上传网关 API 文档

## 概览
- 业务说明：统一的门户上传入口，按“场景（scene）”执行文件类型白名单、大小上限与默认目录策略，返回可直接使用的文件 URL。
- 适用模块：失物招领、数字图书馆、课程资源分享（公告不需要门户上传）。
- 认证与权限：仅需登录（`isAuthenticated()`）；不依赖管理端 `manage:*` 按钮权限。

## 路由清单

### 接口：上传文件
- 方法：POST
- 路径：/portal/upload/oss
- 权限：登录可用
- 请求（multipart/form-data）：
  - file (binary) 必需：要上传的文件
  - scene (string) 可选但建议必填：业务场景枚举（见下文“支持场景”）；大小写不敏感，支持 `library.pdf` 或 `library_pdf`
  - dir (string) 可选：自定义子目录（默认使用场景默认目录）
  - publicUrl (boolean) 可选：是否返回公开 URL（默认随场景策略，通常为 true）
- 返回示例：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "url": "https://your-oss-bucket/path/file.pdf",
    "size": 123456,
    "ext": "pdf",
    "contentType": "application/pdf",
    "sha256": "..."
  }
}
```

### 常见错误码
- 400 参数错误：
  - 文件为空
  - 文件大小超过场景上限
  - 不支持的文件类型
  - 仅图片场景时，Content-Type 非 `image/*`
- 500 服务器错误：OSS 上传失败（返回具体错误信息）

## 支持场景（scene）
- lostfound.image
  - 类型：jpg/jpeg/png/webp
  - 上限：≤ 2MB
  - 目录：lostfound
  - 说明：仅支持图片，强制校验 `Content-Type: image/*`
- library.pdf
  - 类型：pdf
  - 上限：≤ 100MB
  - 目录：library/pdf
- library.extra
  - 类型：epub/mobi/zip
  - 上限：≤ 100MB
  - 目录：library/extra
- resource.archive
  - 类型：zip/rar/7z/tar/gz/bz2/xz
  - 上限：≤ 100MB
  - 目录：resource
- notice.attachment（预留，门户通常不启用）
  - 类型：pdf/doc/docx/xls/xlsx/png/jpg/jpeg/zip
  - 上限：≤ 20MB
  - 目录：notice

## 示例

### 失物招领：上传图片（scene 可放在 Query 或 Form-Data）
- 场景：lostfound.image
- 请求（multipart）：
  - file: image.png
  - scene: lostfound.image
  - dir: lostfound
  - publicUrl: true
- 返回：200，`data.url` 可直接用于前端展示

### 图书馆：上传 PDF（scene 可放在 Query 或 Form-Data）
- 场景：library.pdf
- 请求（multipart）：
  - file: book.pdf
  - scene: library.pdf
  - dir: library/pdf
  - publicUrl: true

### 课程资源：上传压缩包（scene 可放在 Query 或 Form-Data）
- 场景：resource.archive
- 请求（multipart）：
  - file: resource.zip
  - scene: resource.archive
  - dir: resource
  - publicUrl: true

## 备注
- 目录安全：后端会规范化 `dir`，禁止 `..` 等穿越；非法目录会被拒绝。
- URL 暴露策略：默认返回公开 URL；如需私有可后续扩展为预签名 URL。
- 审计：上传会记录操作人信息（在服务层完成）。