leniu-dev 2.0.0

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

@@ -0,0 +1,260 @@
+---
+name: file-oss-management
+description: |
+  当需要进行文件上传、下载、存储管理时自动使用此 Skill。支持本地存储、阿里云OSS、腾讯云COS、七牛云、MinIO等。
+
+  触发场景：
+  - 文件上传下载
+  - 云存储配置
+  - 预签名URL生成
+  - 文件元数据管理
+  - OSS服务商切换
+
+  触发词：文件上传、OSS、云存储、MinIO、阿里云、腾讯云、七牛、图片上传、文件下载、预签名、presigned、S3
+---
+
+# 文件与云存储指南
+
+> 统一协议：基于 AWS S3 SDK v2，兼容所有 S3 协议云服务
+
+## 架构概述
+
+| 组件 | 说明 |
+|----|------|
+| `[你的OssClient]` | 统一操作入口（基于 AWS S3 SDK v2） |
+| `S3Client` | AWS SDK 底层客户端 |
+| `UploadResult` | 上传结果（url, filename, eTag） |
+
+---
+
+## 一、S3 Client 初始化
+
+```java
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.presigner.S3Presigner;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.regions.Region;
+
+// 通用 S3 客户端构建（兼容 MinIO / 阿里云 / 腾讯云等）
+S3Client s3Client = S3Client.builder()
+    .endpointOverride(URI.create(endpoint))
+    .credentialsProvider(StaticCredentialsProvider.create(
+        AwsBasicCredentials.create(accessKey, secretKey)))
+    .region(Region.of(region))
+    .forcePathStyle(true)   // MinIO 需要开启
+    .build();
+```
+
+---
+
+## 二、文件上传
+
+### 基础上传
+
+```java
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+import software.amazon.awssdk.core.sync.RequestBody;
+
+// 上传文件
+PutObjectRequest request = PutObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .contentType("image/jpeg")
+    .build();
+
+s3Client.putObject(request, RequestBody.fromFile(file.toPath()));
+
+// 上传输入流
+s3Client.putObject(request, RequestBody.fromInputStream(inputStream, contentLength));
+
+// 上传字节数组
+s3Client.putObject(request, RequestBody.fromBytes(data));
+```
+
+### 封装上传服务（推荐模式）
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OssService {
+
+    private final S3Client s3Client;
+    private final OssProperties properties;
+
+    /**
+     * 上传文件，自动生成路径
+     */
+    public UploadResult upload(MultipartFile file) {
+        String suffix = getFileSuffix(file.getOriginalFilename());
+        String key = generateObjectKey(suffix);  // 如 2026/03/07/uuid.jpg
+
+        PutObjectRequest request = PutObjectRequest.builder()
+            .bucket(properties.getBucketName())
+            .key(key)
+            .contentType(file.getContentType())
+            .build();
+
+        s3Client.putObject(request,
+            RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
+
+        return UploadResult.builder()
+            .url(properties.getDomain() + "/" + key)
+            .filename(key)
+            .build();
+    }
+
+    private String generateObjectKey(String suffix) {
+        String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
+        return datePath + "/" + UUID.randomUUID() + suffix;
+    }
+}
+```
+
+---
+
+## 三、文件下载
+
+```java
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.core.ResponseInputStream;
+
+// 下载到输出流（推荐用于HTTP响应）
+GetObjectRequest getRequest = GetObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .build();
+
+ResponseInputStream<?> response = s3Client.getObject(getRequest);
+
+// 写入 HTTP 响应
+try (InputStream is = response) {
+    httpResponse.setContentType("image/jpeg");
+    httpResponse.setContentLengthLong(response.response().contentLength());
+    is.transferTo(httpResponse.getOutputStream());
+}
+```
+
+---
+
+## 四、文件删除
+
+```java
+import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
+
+DeleteObjectRequest deleteRequest = DeleteObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .build();
+
+s3Client.deleteObject(deleteRequest);
+```
+
+---
+
+## 五、预签名 URL
+
+```java
+import software.amazon.awssdk.services.s3.presigner.S3Presigner;
+import software.amazon.awssdk.services.s3.presigner.model.*;
+
+S3Presigner presigner = S3Presigner.builder()
+    .endpointOverride(URI.create(endpoint))
+    .credentialsProvider(credentialsProvider)
+    .region(Region.of(region))
+    .build();
+
+// 下载预签名URL
+GetObjectPresignRequest getPresignRequest = GetObjectPresignRequest.builder()
+    .signatureDuration(Duration.ofMinutes(60))
+    .getObjectRequest(b -> b.bucket(bucketName).key("images/photo.jpg"))
+    .build();
+String downloadUrl = presigner.presignGetObject(getPresignRequest).url().toString();
+
+// 上传预签名URL（前端直传）
+PutObjectPresignRequest putPresignRequest = PutObjectPresignRequest.builder()
+    .signatureDuration(Duration.ofHours(1))
+    .putObjectRequest(b -> b.bucket(bucketName).key("images/upload.jpg"))
+    .build();
+String uploadUrl = presigner.presignPutObject(putPresignRequest).url().toString();
+```
+
+---
+
+## 六、Controller 接口（设计模式）
+
+```java
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/oss")
+public class OssController {
+
+    private final OssService ossService;
+
+    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    public UploadResult upload(@RequestPart("file") MultipartFile file) {
+        return ossService.upload(file);
+    }
+
+    @GetMapping("/download/{id}")
+    public void download(@PathVariable Long id, HttpServletResponse response) throws IOException {
+        ossService.download(id, response);
+    }
+
+    @DeleteMapping("/{ids}")
+    public void delete(@PathVariable List<Long> ids) {
+        ossService.deleteByIds(ids);
+    }
+}
+```
+
+---
+
+## 七、配置模型
+
+```yaml
+# application.yml
+oss:
+  endpoint: https://s3.amazonaws.com    # 或 MinIO/阿里云/腾讯云端点
+  access-key: your-access-key
+  secret-key: your-secret-key
+  bucket-name: your-bucket
+  region: us-east-1
+  domain: https://cdn.example.com       # 自定义域名（可选）
+```
+
+```java
+@Data
+@ConfigurationProperties(prefix = "oss")
+public class OssProperties {
+    private String endpoint;
+    private String accessKey;
+    private String secretKey;
+    private String bucketName;
+    private String region;
+    private String domain;
+}
+```
+
+---
+
+## 八、服务商对照
+
+| 服务商 | endpoint 示例 | 备注 |
+|--------|-------------|------|
+| 阿里云 OSS | `https://oss-cn-hangzhou.aliyuncs.com` | S3 兼容 |
+| 腾讯云 COS | `https://cos.ap-guangzhou.myqcloud.com` | S3 兼容 |
+| 七牛云 | `https://s3-cn-south-1.qiniucs.com` | S3 兼容 |
+| MinIO | `http://localhost:9000` | 需 `forcePathStyle(true)` |
+| AWS S3 | `https://s3.amazonaws.com` | 原生支持 |
+
+---
+
+## 九、设计要点
+
+1. **统一封装**：通过 S3 协议统一对接多个云服务商，切换只需改配置
+2. **路径生成**：按日期+UUID生成对象路径，避免冲突
+3. **私有桶**：私有桶文件通过预签名URL访问，设置合理的过期时间
+4. **文件记录**：上传后保存数据库记录，关联业务数据
+5. **大文件**：超过 100MB 考虑分片上传（`CreateMultipartUpload`）
+6. **安全**：前端直传使用预签名URL，不暴露密钥

package/src/skills/file-oss-management/references/entities.md

@@ -0,0 +1,105 @@
+# OSS 数据库实体类定义
+
+## 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;
+}
+```
+
+## SysOssBo 业务对象
+
+```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;
+}
+```
+
+## SysOssExt 扩展信息对象
+
+> 以 JSON 字符串形式存储在 ext1 字段中
+
+```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值
+}
+```
+
+## OssProperties 配置类
+
+```java
+@Data
+public class OssProperties {
+
+    private String tenantId;
+    private String endpoint;       // 访问站点
+    private String domain;         // 自定义域名
+    private String prefix;         // 文件前缀
+    private String accessKey;
+    private String secretKey;
+    private String bucketName;
+    private String region;
+    private String isHttps;        // Y/N
+    private String accessPolicy;   // 0-private, 1-public, 2-custom
+}
+```

package/src/skills/file-oss-management/references/service-impl.md

@@ -0,0 +1,104 @@
+# SysOssServiceImpl 完整实现
+
+> 位置：`ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssServiceImpl.java`
+
+## 文件上传
+
+```java
+@RequiredArgsConstructor
+@Service
+public class SysOssServiceImpl implements ISysOssService {
+
+    private final SysOssMapper baseMapper;
+
+    @Override
+    public SysOssVo upload(MultipartFile file) {
+        if (ObjectUtil.isNull(file) || file.isEmpty()) {
+            throw new ServiceException("上传文件不能为空");
+        }
+
+        String originalfileName = file.getOriginalFilename();
+        String suffix = StringUtils.substring(originalfileName,
+                                             originalfileName.lastIndexOf("."),
+                                             originalfileName.length());
+
+        OssClient storage = OssFactory.instance();
+
+        UploadResult uploadResult;
+        try {
+            uploadResult = storage.uploadSuffix(file.getBytes(), suffix, file.getContentType());
+        } catch (IOException e) {
+            throw new ServiceException(e.getMessage());
+        }
+
+        SysOssExt ext1 = new SysOssExt();
+        ext1.setFileSize(file.getSize());
+        ext1.setContentType(file.getContentType());
+
+        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));
+
+        baseMapper.insert(oss);
+        SysOssVo sysOssVo = MapstructUtils.convert(oss, SysOssVo.class);
+        return this.matchingUrl(sysOssVo);
+    }
+}
+```
+
+## 文件下载
+
+```java
+@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);
+}
+```
+
+## 文件删除
+
+```java
+@Override
+public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
+    List<SysOss> list = baseMapper.selectByIds(ids);
+    for (SysOss sysOss : list) {
+        OssClient storage = OssFactory.instance(sysOss.getService());
+        storage.delete(sysOss.getUrl());
+    }
+    return baseMapper.deleteByIds(ids) > 0;
+}
+```
+
+## 私有桶预签名URL
+
+```java
+private SysOssVo matchingUrl(SysOssVo oss) {
+    OssClient storage = OssFactory.instance(oss.getService());
+    if (AccessPolicyType.PRIVATE == storage.getAccessPolicy()) {
+        oss.setUrl(storage.createPresignedGetUrl(oss.getFileName(), Duration.ofSeconds(120)));
+    }
+    return oss;
+}
+```