# 管理端OSS文件上传功能

## 📋 功能概述

基于用户端OSS上传接口 `/user/oss/post-signature` 实现的管理端文件上传功能，提供了更强大的文件管理能力，同时**与用户端文件存储在同一目录下**，便于统一管理。

## ✅ 已实现功能

### 核心接口
- ✅ `POST /admin/oss/post-signature` - 生成OSS POST签名
- ✅ `DELETE /admin/oss/file` - 删除单个文件
- ✅ `POST /admin/oss/batch-delete` - 批量删除文件
- ✅ `GET /admin/oss/file-info` - 获取文件信息
- ✅ `GET /admin/oss/upload-config` - 获取上传配置

### 技术实现
- ✅ **DTO类设计**: AdminOssUploadRequest、AdminOssUploadResponse
- ✅ **服务层**: AdminOssService接口 + AdminOssServiceImpl实现
- ✅ **控制器**: AdminOssController，包含完整的CRUD操作
- ✅ **权限验证**: 使用@RequireAdminOrStaff注解，确保只有管理员可访问
- ✅ **统一目录**: 与用户端共享`user_img/`目录

### 功能特性
- ✅ **更大文件**: 支持最大500MB文件上传（用户端10MB）
- ✅ **更多格式**: 支持图片、文档、音视频、压缩包等全格式
- ✅ **更长有效期**: 2小时有效期（用户端1小时）
- ✅ **完整管理**: 支持文件删除、批量删除、信息查询
- ✅ **灵活配置**: 支持自定义子目录、文件大小限制
- ✅ **操作记录**: 完整的操作日志记录

## 📁 目录结构

```
项目根目录/
├── src/main/java/com/dora/
│   ├── dto/
│   │   ├── AdminOssUploadRequest.java     # 管理端上传请求DTO
│   │   └── AdminOssUploadResponse.java    # 管理端上传响应DTO
│   ├── service/
│   │   ├── AdminOssService.java           # 管理端OSS服务接口
│   │   └── impl/
│   │       └── AdminOssServiceImpl.java   # 管理端OSS服务实现
│   └── controller/
│       └── AdminOssController.java        # 管理端OSS控制器
├── docs/
│   ├── admin-oss-upload-api.md           # 完整API文档
│   ├── admin-oss-upload-examples.md      # 使用示例
│   └── admin-oss-upload-readme.md        # 本文件
└── ...
```

## 🔗 存储路径

### 统一存储规则
- **基础目录**: `user_img/` (配置在OssConfig.userImgFolder)
- **用户端文件**: `user_img/{用户上传的文件}`
- **管理端文件**: `user_img/{指定子目录}/{管理端上传的文件}`

### 推荐子目录
```
user_img/
├── banners/          # Banner图片 (管理端)
├── images/           # 通用图片 (管理端)
├── documents/        # 文档文件 (管理端)
├── videos/           # 视频文件 (管理端)
├── audios/           # 音频文件 (管理端)
├── uploads/          # 默认目录 (管理端)
└── {用户文件}         # 用户端直接上传的文件
```

## 🚀 快速使用

### 1. 获取管理员Token
```bash
curl -X POST "https://your-api.com/admin/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'
```

### 2. 生成上传签名
```bash
curl -X POST "https://your-api.com/admin/oss/post-signature" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "banner.jpg",
    "directory": "banners",
    "maxSizeMB": 50
  }'
```

### 3. 上传文件到OSS
```bash
# 使用返回的签名信息上传到OSS
curl -X POST "{返回的host}" \
  -F "key={返回的dir}文件名" \
  -F "policy={返回的policy}" \
  -F "OSSAccessKeyId={返回的accessKeyId}" \
  -F "x-oss-signature-version={返回的version}" \
  -F "x-oss-credential={返回的x_oss_credential}" \
  -F "x-oss-date={返回的x_oss_date}" \
  -F "signature={返回的signature}" \
  -F "success_action_status=200" \
  -F "file=@/path/to/your/file.jpg"
```

## 📊 功能对比

| 特性 | 用户端接口 | 管理端接口 | 说明 |
|------|-----------|-----------|------|
| **接口路径** | `/user/oss/post-signature` | `/admin/oss/post-signature` | 路径不同 |
| **权限验证** | 无需认证 | 需要管理员Token | 安全级别不同 |
| **文件大小** | 最大10MB | 最大500MB | 管理端支持更大文件 |
| **文件格式** | 基础格式 | 全格式支持 | 管理端支持更多格式 |
| **有效期** | 1小时 | 2小时 | 管理端有效期更长 |
| **存储目录** | `user_img/` | `user_img/{subdir}/` | 同一根目录 |
| **管理功能** | 仅上传 | 完整CRUD | 管理端功能更全 |

## 🔧 配置说明

### OSS配置
```yaml
# application.yml
aliyun:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    bucket-name: oss-1818ai-user-img
    region: cn-hangzhou
    user-img-folder: user_img/              # 统一存储目录
    expiration-seconds: 3600
    access-key-id: ${ALIYUN_OSS_ACCESS_KEY_ID}
    access-key-secret: ${ALIYUN_OSS_ACCESS_KEY_SECRET}
```

### 支持的文件格式
```java
// 图片格式
.jpg, .jpeg, .png, .gif, .bmp, .webp, .svg, .ico, .tiff

// 文档格式
.pdf, .txt, .md, .json, .xml, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx

// 压缩包格式
.zip, .rar, .7z, .tar, .gz, .bz2, .xz

// 音频格式
.mp3, .wav, .flac, .aac, .ogg, .wma

// 视频格式
.mp4, .avi, .mov, .wmv, .flv, .mkv, .webm

// 其他格式
.html, .css, .js, .sql, .log
```

## 🛡️ 安全特性

### 权限控制
- **接口级别**: `@RequireAdminOrStaff` 注解确保只有管理员/工作人员可访问
- **AspectJ切面**: 自动验证JWT Token有效性和用户权限
- **身份记录**: 自动记录操作者的管理员ID

### 文件安全
- **类型白名单**: 严格的文件类型验证，防止恶意文件上传
- **大小限制**: 可配置的文件大小限制，防止过大文件占用存储
- **目录隔离**: 支持子目录分类，便于文件管理
- **操作审计**: 完整的操作日志，支持追溯

## 📖 使用文档

- 📚 [完整API文档](./admin-oss-upload-api.md) - 详细的接口文档和参数说明
- 💻 [使用示例](./admin-oss-upload-examples.md) - JavaScript/Vue/React等框架的使用示例
- 🔧 [错误排查指南](#错误排查) - 常见问题和解决方案

## 🚨 注意事项

### 重要提醒
1. **目录统一**: 管理端和用户端文件存储在同一根目录 `user_img/` 下
2. **权限必需**: 所有管理端接口都需要有效的管理员JWT Token
3. **文件命名**: 建议使用时间戳+随机数避免文件名冲突
4. **大小限制**: 注意文件大小限制，避免上传失败
5. **网络超时**: 大文件上传注意设置合适的超时时间

### 最佳实践
1. **错误处理**: 做好网络异常和服务器错误的异常处理
2. **进度显示**: 大文件上传时显示进度，提升用户体验
3. **重试机制**: 对于网络不稳定情况，实现上传重试
4. **文件校验**: 上传完成后可进行文件完整性校验
5. **清理机制**: 定期清理失效或无用的文件

## 🔍 错误排查

### 常见错误及解决方案

| 错误代码 | 错误信息 | 可能原因 | 解决方案 |
|---------|---------|---------|---------|
| 401 | 未授权访问 | JWT Token无效或过期 | 重新登录获取新Token |
| 403 | 权限不足 | 不是管理员或工作人员 | 确认账号权限 |
| 400 | 不支持的文件类型 | 文件格式不在白名单中 | 检查文件格式是否支持 |
| 400 | 文件大小超限 | 文件超过大小限制 | 压缩文件或选择更小的文件 |
| 500 | OSS签名生成失败 | OSS配置错误 | 检查OSS配置参数 |

### 调试技巧
```javascript
// 开启调试模式
localStorage.setItem('debug', 'true');

// 查看详细错误信息
console.log('Upload error details:', error);

// 测试Token有效性
fetch('/admin/oss/upload-config', {
  headers: { 'Authorization': `Bearer ${token}` }
})
.then(r => r.json())
.then(result => console.log('Token test:', result));
```

## 🔄 版本历史

### v1.0.0 (2024-12-25)
- ✅ 实现基础的管理端OSS上传功能
- ✅ 支持与用户端统一目录存储
- ✅ 完整的文件管理CRUD操作
- ✅ 权限验证和安全控制
- ✅ 支持多种文件格式和大文件上传

## 🤝 技术支持

如果在使用过程中遇到问题，请按以下步骤排查：

1. **检查Token**: 确认管理员JWT Token有效
2. **验证权限**: 确认当前用户有管理员/工作人员权限
3. **文件格式**: 确认文件格式在支持列表中
4. **大小限制**: 确认文件大小在限制范围内
5. **网络连接**: 确认网络连接正常
6. **OSS配置**: 确认OSS相关配置正确

---

*最后更新: 2024-12-25*  
*版本: v1.0.0*