ai-engineering-init 1.3.3 → 1.4.0

package/.claude/skills/file-oss-management/SKILL.md

@@ -8,856 +8,248 @@ description: |
   - 云存储配置
   - 预签名URL生成
   - 文件元数据管理
-  - 图片处理
+  - OSS服务商切换
 
-  触发词：文件上传、OSS、云存储、MinIO、阿里云、腾讯云、七牛、图片上传、文件下载、预签名、presigned
+  触发词：文件上传、OSS、云存储、MinIO、阿里云、腾讯云、七牛、图片上传、文件下载、预签名、presigned、OssClient、OssFactory
 ---
 
 # 文件与云存储指南
 
-> ⚠️ **本项目规范**：本文档基于项目实际代码编写，所有API和字段名均已验证。标记 `🔴 本项目规范` 的部分必须严格遵守。
+> 模块位置：`ruoyi-common/ruoyi-common-oss`
+> 统一协议：基于 AWS S3 SDK v2，兼容所有 S3 协议云服务
 
----
-
-## 支持的存储类型
-
-> **统一协议**：基于 AWS S3 SDK v2，支持所有兼容 S3 协议的云服务
+## 核心类
 
-| 类型 | 配置键示例 | 说明 |
-|------|-----------|------|
-| 本地存储 | `local` | 存储到服务器本地目录 |
-| 阿里云OSS | `aliyun` | 阿里云对象存储 |
-| 腾讯云COS | `qcloud` | 腾讯云对象存储 |
-| 七牛云 | `qiniu` | 七牛云存储 |
-| MinIO | `minio` | 开源对象存储 |
-| 华为云OBS | `obs` | 华为云对象存储 |
+| 类 | 说明 |
+|----|------|
+| `OssFactory` | 获取 OssClient 实例（只有2个方法） |
+| `OssClient` | 统一操作入口（基于 AWS S3 SDK v2） |
+| `UploadResult` | 上传结果（url, filename, eTag） |
+| `ISysOssService` | OSS 文件管理服务接口 |
 
 ---
 
-## 核心类（已验证）
-
-| 类 | 位置 | 说明 |
-|----|------|------|
-| `OssFactory` | `ruoyi-common-oss/.../factory/OssFactory.java` | 获取 OssClient 实例（只有2个方法） |
-| `OssClient` | `ruoyi-common-oss/.../core/OssClient.java` | 统一操作入口（基于 AWS S3 SDK v2） |
-| `UploadResult` | `ruoyi-common-oss/.../entity/UploadResult.java` | 上传结果（url, filename, eTag） |
-| `ISysOssService` | `ruoyi-system/.../service/ISysOssService.java` | OSS 文件管理服务接口 |
-| `SysOssServiceImpl` | `ruoyi-system/.../service/impl/SysOssServiceImpl.java` | OSS 文件管理服务实现 |
-| `SysOssController` | `ruoyi-system/.../controller/system/SysOssController.java` | OSS 文件上传下载接口 |
-
----
-
-## 🔴 基础使用（本项目规范）
-
-### 获取 OssClient
-
-> **实际代码位置**：`ruoyi-common-oss/src/main/java/org/dromara/common/oss/factory/OssFactory.java`
-
-> **重要**：OssFactory 只有 2 个方法，配置键是字符串（如 "aliyun", "minio"），不是枚举。
+## 一、获取 OssClient
 
 ```java
 import org.dromara.common.oss.factory.OssFactory;
 import org.dromara.common.oss.core.OssClient;
 
-// ✅ 获取默认配置的客户端（从 Redis 读取默认 configKey）
-OssClient client = OssFactory.instance();
-
-// ✅ 根据配置键获取（配置键是字符串）
-OssClient client = OssFactory.instance("aliyun");
+OssClient client = OssFactory.instance();            // 默认配置
+OssClient client = OssFactory.instance("aliyun");    // 指定配置（字符串，非枚举）
 OssClient client = OssFactory.instance("minio");
 
-// ❌ 错误：不存在 OssType 枚举参数
+// ❌ 不存在 OssType 枚举参数
 OssClient client = OssFactory.instance(OssType.ALIYUN);  // 编译错误！
 ```
 
-**工作原理**：
-- 使用 `ConcurrentHashMap` 缓存 OssClient 实例
-- 使用 `ReentrantLock` 双检锁模式确保线程安全
-- 支持多租户隔离（对每个租户的 configKey 分别缓存）
-- 配置信息从 Redis 中读取（`CacheNames.SYS_OSS_CONFIG`）
+> 内部使用 ConcurrentHashMap + ReentrantLock 双检锁缓存实例，支持多租户隔离。
 
 ---
 
-### 文件上传
-
-> **实际代码位置**：`ruoyi-common-oss/src/main/java/org/dromara/common/oss/core/OssClient.java:140-227`
+## 二、文件上传
 
 ```java
 import org.dromara.common.oss.entity.UploadResult;
-import java.nio.file.Path;
 
-// ✅ 1. 上传字节数组，自动生成路径（推荐）
-byte[] data = multipartFile.getBytes();
+// 1. 上传字节数组，自动生成路径（推荐）
 UploadResult result = client.uploadSuffix(data, ".jpg", "image/jpeg");
-// 结果：prefix/2024/12/01/uuid.jpg
 
-// ✅ 2. 上传输入流，自动生成路径
-InputStream is = multipartFile.getInputStream();
-Long fileSize = multipartFile.getSize();
+// 2. 上传输入流，自动生成路径
 UploadResult result = client.uploadSuffix(is, ".jpg", fileSize, "image/jpeg");
 
-// ✅ 3. 上传 File 对象，自动生成路径
-File file = new File("/path/to/file.jpg");
+// 3. 上传 File 对象，自动生成路径
 UploadResult result = client.uploadSuffix(file, ".jpg");
 
-// ✅ 4. 上传到指定路径（手动指定完整 key）
-Path filePath = file.toPath();
-UploadResult result = client.upload(filePath, "avatar/user123.jpg", null, "image/jpeg");
+// 4. 上传到指定路径
+UploadResult result = client.upload(file.toPath(), "avatar/user123.jpg", null, "image/jpeg");
 
-// ✅ 5. 上传流到指定路径
+// 5. 上传流到指定路径
 UploadResult result = client.upload(is, "images/photo.jpg", fileSize, "image/jpeg");
 ```
 
-**方法签名（已验证）**：
+**方法签名：**
 ```java
-// 上传本地文件到S3
-public UploadResult upload(Path filePath, String key, String md5Digest, String contentType)
-
-// 上传输入流到S3
-public UploadResult upload(InputStream inputStream, String key, Long length, String contentType)
-
-// 上传字节数组（带后缀自动拼接路径）
-public UploadResult uploadSuffix(byte[] data, String suffix, String contentType)
-
-// 上传流（带后缀自动拼接路径）
-public UploadResult uploadSuffix(InputStream inputStream, String suffix, Long length, String contentType)
-
-// 上传文件对象（带后缀自动拼接路径）
-public UploadResult uploadSuffix(File file, String suffix)
+UploadResult upload(Path filePath, String key, String md5Digest, String contentType)
+UploadResult upload(InputStream inputStream, String key, Long length, String contentType)
+UploadResult uploadSuffix(byte[] data, String suffix, String contentType)
+UploadResult uploadSuffix(InputStream inputStream, String suffix, Long length, String contentType)
+UploadResult uploadSuffix(File file, String suffix)
 ```
 
 ---
 
-### UploadResult 字段（已验证）
-
-> **实际代码位置**：`ruoyi-common-oss/src/main/java/org/dromara/common/oss/entity/UploadResult.java`
+## 三、UploadResult 字段
 
-> **重要**：UploadResult 使用 Lombok `@Builder`，只有 3 个字段。
+> 只有 3 个字段，使用 Lombok `@Builder`。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `url` | String | 文件访问URL（完整路径） |
-| `filename` | String | 文件名/对象键（注意是小写 'n'） |
-| `eTag` | String | 文件校验标记（用来校验文件） |
+| `url` | String | 文件访问URL |
+| `filename` | String | 文件名/对象键（**小写 n**） |
+| `eTag` | String | 文件校验标记 |
 
 ```java
-// ✅ 正确
 String url = result.getUrl();
-String filename = result.getFilename();  // 小写 'n'
-String eTag = result.getETag();
-
-// ❌ 错误：不存在这些字段
-String fileName = result.getFileName();  // 编译错误！
-Long fileSize = result.getFileSize();    // 编译错误！
-String contentType = result.getContentType();  // 编译错误！
+String filename = result.getFilename();   // ✅ 小写 'n'
+// ❌ result.getFileName() / result.getFileSize() / result.getContentType() 不存在
 ```
 
 ---
 
-## 文件下载
-
-> **实际代码位置**：`OssClient.java:236-319`
+## 四、文件下载
 
 ```java
-import java.nio.file.Path;
-import java.io.OutputStream;
-
-// ✅ 1. 下载到临时文件
+// 下载到临时文件
 Path tempFile = client.fileDownload("images/photo.jpg");
-// 返回临时文件路径
 
-// ✅ 2. 下载到输出流（推荐用于响应流）
-OutputStream out = response.getOutputStream();
+// 下载到输出流（推荐用于HTTP响应）
 client.download("images/photo.jpg", out, contentLength -> {
-    // 可选的文件大小回调（用于设置响应头）
     response.setContentLengthLong(contentLength);
 });
 
-// ✅ 3. 获取文件输入流
+// 获取文件输入流（内部创建临时文件，使用后自动删除）
 InputStream is = client.getObjectContent("images/photo.jpg");
-// 注意：此方法会创建临时文件，使用后会自动删除
-```
-
-**方法签名（已验证）**：
-```java
-// 下载文件到临时目录
-public Path fileDownload(String path)
-
-// 下载文件到输出流（含文件大小回调）
-public void download(String key, OutputStream out, Consumer<Long> consumer)
-
-// 获取文件输入流
-public InputStream getObjectContent(String path) throws IOException
 ```
 
 ---
 
-## 文件操作
-
-> **实际代码位置**：`OssClient.java`
+## 五、文件删除与预签名URL
 
 ```java
-// ✅ 删除文件
+// 删除
 client.delete("images/photo.jpg");
+// ❌ client.copyFile() / client.getFileMetadata() / client.listFiles() 不存在
 
-// ❌ 以下方法不存在于 OssClient
-client.copyFile(...);        // 不存在
-client.getFileMetadata(...); // 不存在
-client.listFiles(...);       // 不存在
-```
-
----
-
-## 预签名URL
-
-> **实际代码位置**：`OssClient.java:343-375`
-
-### 下载预签名URL
-
-```java
-import java.time.Duration;
-
-// ✅ 生成60分钟有效的预签名下载URL
-String presignedUrl = client.createPresignedGetUrl("images/photo.jpg", Duration.ofMinutes(60));
-
-// ❌ 以下方法不存在
-String url = client.generatePresignedUrl(...);  // 不存在
-String url = client.generatePublicUrl(...);     // 不存在
-```
-
-### 上传预签名URL（前端直传）
-
-```java
-import java.util.Map;
-
-// ✅ 生成预签名上传URL
-Map<String, String> metadata = Map.of("user-id", "123");
-String uploadUrl = client.createPresignedPutUrl(
-    "images/upload.jpg",           // 对象键
-    Duration.ofHours(1),           // 有效期
-    metadata                       // 元数据（可为 null）
-);
-
-// 前端使用此 URL 直接 PUT 上传
-```
-
-**方法签名（已验证）**：
-```java
-// 创建下载预签名URL（GET请求）
-public String createPresignedGetUrl(String objectKey, Duration expiredTime)
+// 下载预签名URL
+String url = client.createPresignedGetUrl("images/photo.jpg", Duration.ofMinutes(60));
 
-// 创建上传预签名URL（PUT请求）
-public String createPresignedPutUrl(String objectKey, Duration expiredTime, Map<String, String> metadata)
+// 上传预签名URL（前端直传）
+String url = client.createPresignedPutUrl("images/upload.jpg", Duration.ofHours(1), metadata);
+// ❌ client.generatePresignedUrl() / client.generatePublicUrl() 不存在
 ```
 
 ---
 
-## OssClient 其他工具方法
-
-> **实际代码位置**：`OssClient.java`
+## 六、OssClient 工具方法
 
 ```java
-// 获取云存储服务的基础URL
-String baseUrl = client.getUrl();
-
-// 获取终端点URL (http:// 或 https://)
-String endpoint = client.getEndpoint();
-
-// 获取自定义域名或终端点
-String domain = client.getDomain();
-
-// 获取服务商配置键
-String configKey = client.getConfigKey();
-
-// 获取桶权限类型（PUBLIC 或 PRIVATE）
-AccessPolicyType accessPolicy = client.getAccessPolicy();
-
-// 生成对象键路径（prefix + dateTime + uuid + suffix）
-String path = client.getPath("", ".jpg");
-
-// 移除基础URL获取相对路径
-String relativePath = client.removeBaseUrl(fullUrl);
-
-// 检查配置是否相同
-boolean isSame = client.checkPropertiesSame(newProperties);
+String baseUrl = client.getUrl();                  // 基础URL
+String endpoint = client.getEndpoint();            // 终端点URL
+String domain = client.getDomain();                // 自定义域名
+String configKey = client.getConfigKey();           // 配置键
+AccessPolicyType policy = client.getAccessPolicy(); // 桶权限（PUBLIC/PRIVATE）
+String path = client.getPath("", ".jpg");          // 生成对象键路径
+String relative = client.removeBaseUrl(fullUrl);   // 获取相对路径
+boolean same = client.checkPropertiesSame(props);  // 配置是否相同
 ```
 
 ---
 
-## Controller 示例（已验证）
-
-> **实际代码位置**：`ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysOssController.java`
-
-### API 接口清单
+## 七、Controller 接口（SysOssController）
 
-| 操作 | HTTP方法 | 路径 | 权限 |
-|------|---------|------|------|
+| 操作 | HTTP | 路径 | 权限 |
+|------|------|------|------|
 | 查询列表 | GET | `/resource/oss/list` | `system:oss:list` |
 | 批量查询 | GET | `/resource/oss/listByIds/{ossIds}` | `system:oss:query` |
 | 上传文件 | POST | `/resource/oss/upload` | `system:oss:upload` |
 | 下载文件 | GET | `/resource/oss/download/{ossId}` | `system:oss:download` |
 | 删除文件 | DELETE | `/resource/oss/{ossIds}` | `system:oss:remove` |
 
-### 🔴 文件上传接口（本项目规范）
-
-```java
-@RestController
-@RequestMapping("/resource/oss")
-@RequiredArgsConstructor
-public class SysOssController extends BaseController {
-
-    private final ISysOssService ossService;
-
-    /**
-     * 上传文件
-     *
-     * 🔴 注意：
-     * 1. 必须使用 @RequestPart("file")
-     * 2. 必须指定 consumes = MediaType.MULTIPART_FORM_DATA_VALUE
-     * 3. 参数名必须是 "file"（前端约定）
-     */
-    @SaCheckPermission("system:oss:upload")
-    @Log(title = "OSS对象存储", businessType = BusinessType.INSERT)
-    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
-    public R<SysOssUploadVo> upload(@RequestPart("file") MultipartFile file) {
-        // 调用 Service 上传（会保存到数据库）
-        SysOssVo oss = ossService.upload(file);
-
-        // 构建返回对象
-        SysOssUploadVo uploadVo = new SysOssUploadVo();
-        uploadVo.setUrl(oss.getUrl());
-        uploadVo.setFileName(oss.getOriginalName());
-        uploadVo.setOssId(oss.getOssId().toString());
-
-        return R.ok(uploadVo);
-    }
-
-    /**
-     * 下载文件
-     */
-    @SaCheckPermission("system:oss:download")
-    @GetMapping("/download/{ossId}")
-    public void download(@PathVariable Long ossId, HttpServletResponse response) throws IOException {
-        ossService.download(ossId, response);
-    }
-
-    /**
-     * 删除文件
-     */
-    @SaCheckPermission("system:oss:remove")
-    @Log(title = "OSS对象存储", businessType = BusinessType.DELETE)
-    @DeleteMapping("/{ossIds}")
-    public R<Void> remove(@NotEmpty(message = "主键不能为空") @PathVariable Long[] ossIds) {
-        return toAjax(ossService.deleteWithValidByIds(List.of(ossIds), true));
-    }
+**上传接口规范：**
+```java
+// 必须使用 @RequestPart("file")，必须指定 consumes
+@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+public R<SysOssUploadVo> upload(@RequestPart("file") MultipartFile file) {
+    SysOssVo oss = ossService.upload(file);
+    SysOssUploadVo uploadVo = new SysOssUploadVo();
+    uploadVo.setUrl(oss.getUrl());
+    uploadVo.setFileName(oss.getOriginalName());
+    uploadVo.setOssId(oss.getOssId().toString());
+    return R.ok(uploadVo);
 }
 ```
 
-**返回对象 SysOssUploadVo**：
-```java
-@Data
-public class SysOssUploadVo {
-    private String url;        // 文件URL
-    private String fileName;   // 原始文件名
-    private String ossId;      // OSS对象ID（String类型）
-}
-```
+**SysOssUploadVo**：`url`(String) / `fileName`(String) / `ossId`(String)
 
 ---
 
-## Service 层示例（已验证）
-
-> **实际代码位置**：`ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssServiceImpl.java`
-
-### 服务接口方法（ISysOssService）
+## 八、Service 层接口（ISysOssService）
 
 ```java
-// 分页查询OSS对象
 TableDataInfo<SysOssVo> queryPageList(SysOssBo sysOss, PageQuery pageQuery);
-
-// 根据ossId列表查询
 List<SysOssVo> listByIds(Collection<Long> ossIds);
-
-// 单个ID查询（带缓存）
 @Cacheable(cacheNames = CacheNames.SYS_OSS, key = "#ossId")
 SysOssVo getById(Long ossId);
-
-// MultipartFile上传
 SysOssVo upload(MultipartFile file);
-
-// File对象上传
 SysOssVo upload(File file);
-
-// 文件下载
 void download(Long ossId, HttpServletResponse response) throws IOException;
-
-// 删除文件
 Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 ```
 
-### 文件上传完整流程
+> 推荐通过 `ISysOssService.upload()` 上传，会自动保存数据库记录。
+> 直接使用 `OssClient` 上传不会有数据库记录。
 
-```java
-@RequiredArgsConstructor
-@Service
-public class SysOssServiceImpl implements ISysOssService {
-
-    private final SysOssMapper baseMapper;
-
-    /**
-     * 上传文件（保存到 OSS 并记录到数据库）
-     *
-     * 🔴 重要：
-     * 1. 使用 new ServiceException() 抛出异常
-     * 2. UploadResult.getFilename() 是小写 'n'
-     * 3. 扩展信息存储在 ext1 字段（JSON格式）
-     */
-    @Override
-    public SysOssVo upload(MultipartFile file) {
-        if (ObjectUtil.isNull(file) || file.isEmpty()) {
-            throw new ServiceException("上传文件不能为空");
-        }
-
-        // 1. 提取文件后缀
-        String originalfileName = file.getOriginalFilename();
-        String suffix = StringUtils.substring(originalfileName,
-                                             originalfileName.lastIndexOf("."),
-                                             originalfileName.length());
-
-        // 2. 获取 OSS 客户端（默认配置）
-        OssClient storage = OssFactory.instance();
-
-        // 3. 上传文件
-        UploadResult uploadResult;
-        try {
-            uploadResult = storage.uploadSuffix(file.getBytes(), suffix, file.getContentType());
-        } catch (IOException e) {
-            throw new ServiceException(e.getMessage());
-        }
-
-        // 4. 构建扩展信息
-        SysOssExt ext1 = new SysOssExt();
-        ext1.setFileSize(file.getSize());
-        ext1.setContentType(file.getContentType());
-
-        // 5. 保存到数据库
-        return buildResultEntity(originalfileName, suffix,
-            storage.getConfigKey(), uploadResult, ext1);
-    }
-
-    /**
-     * 构建结果实体并保存
-     */
-    private SysOssVo buildResultEntity(String originalfileName, String suffix,
-        String configKey, UploadResult uploadResult, SysOssExt ext1) {
-
-        SysOss oss = new SysOss();
-        oss.setUrl(uploadResult.getUrl());
-        oss.setFileSuffix(suffix);
-        oss.setFileName(uploadResult.getFilename());       // 对象键（小写 'n'）
-        oss.setOriginalName(originalfileName);              // 原始文件名
-        oss.setService(configKey);                          // 服务商标识
-        oss.setExt1(JsonUtils.toJsonString(ext1));         // 扩展信息（JSON）
-
-        baseMapper.insert(oss);
-        SysOssVo sysOssVo = MapstructUtils.convert(oss, SysOssVo.class);
-        return this.matchingUrl(sysOssVo);
-    }
-
-    /**
-     * 文件下载
-     */
-    @Override
-    public void download(Long ossId, HttpServletResponse response) throws IOException {
-        SysOssVo sysOss = SpringUtils.getAopProxy(this).getById(ossId);
-        if (ObjectUtil.isNull(sysOss)) {
-            throw new ServiceException("文件数据不存在!");
-        }
-
-        // 设置响应头
-        FileUtils.setAttachmentResponseHeader(response, sysOss.getOriginalName());
-        response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE + "; charset=UTF-8");
-
-        // 下载文件
-        OssClient storage = OssFactory.instance(sysOss.getService());
-        storage.download(sysOss.getFileName(),
-            response.getOutputStream(),
-            response::setContentLengthLong);  // 设置响应头Content-Length
-    }
-
-    /**
-     * 删除文件
-     */
-    @Override
-    public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
-        if (isValid) {
-            // 做一些业务上的校验，判断是否需要校验
-        }
-
-        List<SysOss> list = baseMapper.selectByIds(ids);
-        for (SysOss sysOss : list) {
-            OssClient storage = OssFactory.instance(sysOss.getService());
-            storage.delete(sysOss.getUrl());  // 删除OSS中的文件
-        }
-
-        return baseMapper.deleteByIds(ids) > 0;  // 删除数据库记录
-    }
-
-    /**
-     * 为私有文件生成预签名 URL
-     *
-     * 🔴 重要：私有桶的文件需要生成临时访问 URL（120秒有效）
-     */
-    private SysOssVo matchingUrl(SysOssVo oss) {
-        OssClient storage = OssFactory.instance(oss.getService());
-        // 仅修改桶类型为 private 的URL，临时URL时长为120s
-        if (AccessPolicyType.PRIVATE == storage.getAccessPolicy()) {
-            oss.setUrl(storage.createPresignedGetUrl(oss.getFileName(), Duration.ofSeconds(120)));
-        }
-        return oss;
-    }
-}
-```
+> 完整 Service 实现代码详见 [references/service-impl.md](references/service-impl.md)
 
 ---
 
-## 数据库实体类（已验证）
-
-### SysOss 实体
-
-```java
-@Data
-@EqualsAndHashCode(callSuper = true)
-@TableName("sys_oss")
-public class SysOss extends TenantEntity {
-
-    @TableId(value = "oss_id")
-    private Long ossId;              // 对象存储主键
-
-    private String fileName;         // 文件名（OSS对象键）
-    private String originalName;     // 原始文件名
-    private String fileSuffix;       // 文件后缀名（如 .jpg）
-    private String url;              // URL地址
-    private String ext1;             // 扩展字段（JSON格式）
-    private String service;          // 服务商标识
-
-    // 继承自 TenantEntity 的字段
-    // tenantId, createTime, createBy, updateTime, updateBy, delFlag 等
-}
-```
-
-### SysOssVo 视图对象
+## 九、数据库实体
 
-```java
-@Data
-@AutoMapper(target = SysOss.class)
-public class SysOssVo implements Serializable {
-
-    private Long ossId;
-    private String fileName;
-    private String originalName;
-    private String fileSuffix;
-    private String url;
-    private String ext1;
-    private Date createTime;
-    private Long createBy;
-
-    @Translation(type = TransConstant.USER_ID_TO_NAME, mapper = "createBy")
-    private String createByName;  // 上传人名称（自动翻译）
-
-    private String service;
-}
-```
+> 完整实体/VO/BO 定义详见 [references/entities.md](references/entities.md)
 
-### SysOssBo 业务对象
+**SysOss 关键字段：**
 
-```java
-@Data
-@EqualsAndHashCode(callSuper = true)
-@AutoMapper(target = SysOss.class, reverseConvertGenerate = false)
-public class SysOssBo extends BaseEntity {
-
-    private Long ossId;
-    private String fileName;
-    private String originalName;
-    private String fileSuffix;
-    private String url;
-    private String ext1;
-    private String service;
-
-    // 继承自 BaseEntity 的 params 字段（时间范围查询用）
-}
-```
-
-### SysOssExt 扩展信息对象
-
-> **存储在 ext1 字段中**：以 JSON 字符串形式存储
-
-```java
-@Data
-public class SysOssExt implements Serializable {
-
-    private String bizType;         // 业务类型（avatar、report等）
-    private Long fileSize;          // 文件大小（字节）
-    private String contentType;     // MIME类型
-    private String source;          // 来源标识
-    private String uploadIp;        // 上传IP
-    private String remark;          // 备注
-    private List<String> tags;      // 标签
-    private String refId;           // 绑定业务ID
-    private String refType;         // 绑定业务类型
-    private Boolean isTemp;         // 是否临时文件
-    private String md5;             // 文件MD5值
-}
-```
+| 字段 | 说明 |
+|------|------|
+| `ossId` | 主键 |
+| `fileName` | OSS对象键 |
+| `originalName` | 原始文件名 |
+| `fileSuffix` | 后缀名 |
+| `url` | 访问URL |
+| `ext1` | 扩展字段（JSON，存储 SysOssExt） |
+| `service` | 服务商标识 |
 
 ---
 
-## 配置说明
-
-### 数据库配置表（sys_oss_config）
-
-> **配置存储位置**：Redis（`CacheNames.SYS_OSS_CONFIG`）
+## 十、配置（sys_oss_config 表）
 
 | 字段 | 说明 |
 |------|------|
-| `config_key` | 配置标识（如 aliyun、minio） |
-| `access_key` | Access Key |
-| `secret_key` | Secret Key |
-| `bucket_name` | 存储桶名称 |
+| `config_key` | 配置标识（aliyun、minio等） |
+| `access_key` / `secret_key` | 认证信息 |
+| `bucket_name` | 存储桶 |
 | `prefix` | 路径前缀 |
 | `endpoint` | 服务端点 |
 | `domain` | 自定义域名 |
 | `is_https` | 是否HTTPS（Y/N） |
 | `region` | 区域 |
-| `access_policy` | 访问策略（0-private, 1-public, 2-custom） |
-| `status` | 启用状态 |
-
-### OssProperties 配置类
-
-```java
-@Data
-public class OssProperties {
-
-    private String tenantId;       // 租户ID
-    private String endpoint;       // 访问站点（endpoint）
-    private String domain;         // 自定义域名
-    private String prefix;         // 文件前缀（对象键前缀）
-    private String accessKey;      // ACCESS_KEY
-    private String secretKey;      // SECRET_KEY
-    private String bucketName;     // 存储空间名
-    private String region;         // 存储区域
-    private String isHttps;        // 是否HTTPS（Y/N）
-    private String accessPolicy;   // 桶权限类型（0-private, 1-public, 2-custom）
-}
-```
-
-### 访问策略
-
-| 策略 | 说明 |
-|------|------|
-| `PRIVATE` | 私有访问（"0"），需要预签名URL（matchingUrl 自动处理） |
-| `PUBLIC` | 公开访问（"1"），URL 直接可访问 |
-| `CUSTOM` | 自定义访问（"2"），公开读取 |
-
----
-
-## 最佳实践
-
-### 1. 文件路径规范
-
-```java
-// ✅ 推荐：使用 uploadSuffix 自动生成路径
-OssClient client = OssFactory.instance();
-UploadResult result = client.uploadSuffix(file.getBytes(), ".jpg", contentType);
-// 结果：prefix/2024/12/01/550e8400-e29b.jpg
-
-// ❌ 避免：手动拼接路径容易出错
-UploadResult result = client.upload(file.toPath(), "avatar/" + fileName, null, contentType);
-```
-
-### 2. 文件上传后保存数据库
+| `access_policy` | 0-private, 1-public, 2-custom |
 
-```java
-// ✅ 推荐：使用 SysOssService 上传（自动保存到数据库）
-@Autowired
-private ISysOssService ossService;
-
-SysOssVo ossVo = ossService.upload(multipartFile);
-Long ossId = ossVo.getOssId();  // 保存 ossId 到业务表
-
-// ❌ 不推荐：直接使用 OssClient（无数据库记录，难以管理）
-OssClient client = OssFactory.instance();
-UploadResult result = client.uploadSuffix(file.getBytes(), ".jpg", contentType);
-```
-
-### 3. 文件类型校验
-
-```java
-// 限制允许的文件类型
-private static final Set<String> ALLOWED_TYPES = Set.of(
-    "image/jpeg", "image/png", "image/gif", "application/pdf"
-);
-
-public SysOssVo upload(MultipartFile file) {
-    if (!ALLOWED_TYPES.contains(file.getContentType())) {
-        throw new ServiceException("不支持的文件类型");
-    }
-    // 继续上传...
-}
-```
-
-### 4. 文件大小限制
-
-```yaml
-# application.yml
-spring:
-  servlet:
-    multipart:
-      max-file-size: 10MB
-      max-request-size: 20MB
-```
-
-### 5. 异常处理方式
-
-```java
-// ✅ 正确：使用 new ServiceException()
-if (file.isEmpty()) {
-    throw new ServiceException("上传文件不能为空");
-}
-
-// ❌ 错误：不存在 of() 静态方法
-throw ServiceException.of("上传文件不能为空");  // 编译错误！
-```
+> 配置从 Redis 读取（`CacheNames.SYS_OSS_CONFIG`），私有桶文件自动生成 120 秒预签名URL。
 
 ---
 
-## 常见问题
-
-### ⚠️ UploadResult.getFilename() vs getFileName()
+## 十一、快速对照表
 
-```java
-// ✅ 正确：字段名是 filename（小写 'n'）
-UploadResult result = client.uploadSuffix(file.getBytes(), ".jpg", contentType);
-String filename = result.getFilename();  // 正确
-
-// ❌ 错误：不是 fileName（驼峰）
-String fileName = result.getFileName();  // 编译错误！
-```
-
-### ⚠️ ServiceException 构造方式
-
-```java
-// ✅ 正确：使用 new ServiceException()
-if (file.isEmpty()) {
-    throw new ServiceException("上传文件不能为空");
-}
-
-// ❌ 错误：不存在 of() 静态方法
-throw ServiceException.of("上传文件不能为空");  // 编译错误！
-```
-
-### 上传失败：Access Denied
-
-- 检查 Access Key 和 Secret Key
-- 检查存储桶权限配置
-- 检查 IP 白名单
-
-### 预签名URL无效
-
-- 检查服务器时间是否同步
-- 检查 URL 有效期是否过期
-- 私有桶必须使用预签名URL（matchingUrl 自动处理）
-
-### 跨域问题
-
-配置存储桶 CORS 规则：
-- AllowedOrigins: `*` 或具体域名
-- AllowedMethods: `GET, PUT, POST, DELETE`
-- AllowedHeaders: `*`
-
----
-
-## 快速对照表
-
-| ❌ 错误 | ✅ 正确 |
-|--------|--------|
+| 错误 | 正确 |
+|------|------|
 | `OssFactory.instance(OssType.ALIYUN)` | `OssFactory.instance("aliyun")` |
-| `client.uploadFile(file, key, type)` | `client.upload(file.toPath(), key, null, type)` |
-| `client.uploadStream(is, key, size, type)` | `client.upload(is, key, size, type)` |
 | `result.getFileName()` | `result.getFilename()` |
-| `result.getFileSize()` | 不存在此字段 |
+| `result.getFileSize()` | 不存在 |
 | `client.downloadToTempFile(path)` | `client.fileDownload(path)` |
-| `client.generatePresignedUrl(key, duration)` | `client.createPresignedGetUrl(key, duration)` |
+| `client.generatePresignedUrl(...)` | `client.createPresignedGetUrl(...)` |
 | `throw ServiceException.of("msg")` | `throw new ServiceException("msg")` |
-| `client.copyFile(...)` | 不存在此方法 |
-| `client.listFiles(...)` | 不存在此方法 |
-
----
-
-## 核心工作流程
-
-### 上传流程
-
-```
-1. Controller 接收 MultipartFile
-2. Service 验证文件非空
-3. 从文件名提取后缀
-4. 获取默认 OssClient（从 Redis 读取配置）
-5. 上传到 OSS（自动生成对象键：prefix/date/uuid + suffix）
-6. 保存文件信息和扩展信息到数据库（ext1字段存JSON）
-7. 若是私有桶，生成预签名URL（120秒有效）
-8. 返回上传结果
-```
-
-### 下载流程
-
-```
-1. Controller 接收 ossId
-2. Service 从数据库查询文件信息（带缓存）
-3. 检查私有桶，若是则生成预签名URL
-4. 获取对应的 OssClient
-5. 下载文件到输出流
-6. 设置响应头（Content-Disposition、Content-Type、Content-Length）
-```
-
-### 删除流程
-
-```
-1. 查询数据库获取文件信息
-2. 获取对应的 OssClient
-3. 删除 OSS 中的文件
-4. 删除数据库记录
-```
-
----
-
-## 架构特性
-
-1. **客户端缓存**：OssFactory 使用 ConcurrentHashMap 缓存 OssClient，支持多租户隔离
-
-2. **配置来源**：从 Redis 中读取（`CacheNames.SYS_OSS_CONFIG`），配置为 JSON 格式
-
-3. **默认配置键**：从 Redis key `sys_oss:default_config` 获取
-
-4. **S3 协议支持**：支持所有兼容 S3 协议的云服务（阿里云、腾讯云、七牛云、MinIO等）
-
-5. **异步传输**：基于 AWS SDK v2 的异步客户端和 S3TransferManager
-
-6. **路径风格**：MinIO 使用路径风格访问，云服务商使用虚拟主机风格
-
-7. **私有桶处理**：私有桶的URL自动生成预签名URL（120秒过期）
-
-8. **扩展字段**：使用 JSON 存储在 ext1 字段中，支持灵活扩展
+| `client.copyFile/listFiles/getFileMetadata` | 不存在 |
 
 ---
 
-## 相关文件位置
+## 核心文件位置
 
 | 类型 | 位置 |
 |------|------|
-| OssFactory | `ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/factory/OssFactory.java` |
-| OssClient | `ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/core/OssClient.java` |
-| UploadResult | `ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/entity/UploadResult.java` |
-| SysOssController | `ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysOssController.java` |
-| SysOssServiceImpl | `ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssServiceImpl.java` |
+| OssFactory | `ruoyi-common/ruoyi-common-oss/.../factory/OssFactory.java` |
+| OssClient | `ruoyi-common/ruoyi-common-oss/.../core/OssClient.java` |
+| UploadResult | `ruoyi-common/ruoyi-common-oss/.../entity/UploadResult.java` |
+| SysOssController | `ruoyi-modules/ruoyi-system/.../controller/system/SysOssController.java` |
+| SysOssServiceImpl | `ruoyi-modules/ruoyi-system/.../service/impl/SysOssServiceImpl.java` |