[Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00
commit 0f7bc05697
587 changed files with 103215 additions and 0 deletions
--- a/docs/admin-oss-upload-readme.md
+++ b/docs/admin-oss-upload-readme.md
@@ -0,0 +1,242 @@
+# 管理端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*