@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-oss/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,77 @@
+# OSS 快速接入与配置
+
+## 1. 添加依赖
+
+```xml
+<dependency>
+    <groupId>com.iflytek.avatar.boot</groupId>
+    <artifactId>avatar-boot-starter-oss</artifactId>
+</dependency>
+```
+
+## 2. 配置连接信息
+
+```yaml
+avatar:
+  oss:
+    enabled: true
+    type: ALIOSS                          # ALIOSS / MINIO / TXCOS / AWS3
+    endpoint: https://oss-cn-beijing.aliyuncs.com
+    bucket: your-bucket-name
+    access-key: ${OSS_ACCESS_KEY}         # 通过环境变量注入，禁止明文
+    access-secret: ${OSS_ACCESS_SECRET}
+    region: default
+    use-ssl: false
+    virtual-host: false
+    cdn-endpoint: https://your-cdn.com    # CDN 域名，无 CDN 时填同 endpoint
+    project-name: your-service-name
+```
+
+## 3. 注入使用
+
+```java
+@Autowired
+private OssClient ossClient;
+```
+
+`@ConditionalOnProperty(name = "enabled", havingValue = "true")` 自动生效，无需额外注解。
+
+## 配置项说明
+
+| 配置项 | 必填 | 默认值 | 说明 |
+|:--|:--|:--|:--|
+| `enabled` | 是 | `false` | 是否启用 OSS |
+| `type` | 是 | — | 存储类型 |
+| `endpoint` | 是 | — | 存储服务域名 |
+| `bucket` | 是 | — | 存储空间名称 |
+| `access-key` | 是 | — | 访问密钥 ID |
+| `access-secret` | 是 | — | 访问密钥 Secret |
+| `region` | 否 | `default` | 区域（MinIO 填 default） |
+| `use-ssl` | 否 | `false` | 是否启用 HTTPS |
+| `cdn-endpoint` | 否 | 同 endpoint | CDN 加速域名 |
+| `thread-pool.enable-multipart-upload-size` | 否 | `50` | 触发分片上传的文件大小（MB） |
+| `thread-pool.part-size` | 否 | `10` | 每个分片大小（MB） |
+
+## 各 OSS 类型推荐配置
+
+### 阿里云 OSS
+
+```yaml
+avatar:
+  oss:
+    type: ALIOSS
+    endpoint: https://oss-cn-beijing.aliyuncs.com
+    virtual-host: false
+    region: default
+```
+
+### MinIO
+
+```yaml
+avatar:
+  oss:
+    type: MINIO
+    endpoint: http://minio:9000
+    use-ssl: false
+    region: default
+```

package/templates/.claude/skills/avatar-boot-starter-oss/references//346/240/270/345/277/203/345/212/237/350/203/275.md

@@ -0,0 +1,94 @@
+# OSS 核心功能
+
+## 文件上传
+
+```java
+// 方式一：字节数组上传（后端服务生成文件时使用）
+String fileKey = OssFileKeyHelper.videoKey(tenantId, taskId, "output.mp4");
+String cdnUrl = ossClient.upload(fileBytes, fileKey, "video/mp4");
+// cdnUrl 仅用于即时展示，入库时存 {bucket}/{fileKey} 格式
+
+// 方式二：本地文件路径上传
+String cdnUrl = ossClient.upload("/tmp/output.mp4", fileKey, "video/mp4");
+```
+
+## 预签名上传（前端直传）
+
+适合客户端直接上传素材，流量不经过业务服务器：
+
+```java
+String fileKey = OssFileKeyHelper.materialKey(tenantId, "source.mp4");
+PresignResult result = ossClient.getPresignUploadUrl(fileKey, "video/mp4", Duration.ofMinutes(30));
+
+result.getUrl();            // 预签名上传地址，前端 PUT 到此地址
+result.getSignedHeaders();  // 上传时必须携带的额外 header
+```
+
+前端上传示例：
+```javascript
+// 阿里云：signedHeaders 为空，直接 PUT
+await fetch(result.url, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'video/mp4', ...result.signedHeaders },
+    body: file
+});
+```
+
+## 预签名下载（临时授权访问）
+
+```java
+PresignResult result = ossClient.getPresignDownloadUrl(fileKey, Duration.ofHours(2));
+String accessUrl = result.getUrl(); // 可直接访问的签名 URL
+```
+
+## URL 解析（接口返回文件 URL 时统一使用）
+
+```java
+// 自动处理新旧格式，默认有效期 2 小时
+String accessUrl = ossClient.resolveAccessUrl(dbStoredValue);
+
+// 自定义有效期
+String accessUrl = ossClient.resolveAccessUrl(dbStoredValue, Duration.ofHours(4));
+```
+
+| DB 中的值 | 处理结果 |
+|:--|:--|
+| `bucket/videos/.../output.mp4`（新格式） | 动态生成 CDN 签名 URL |
+| `https://cdn.old.com/.../output.mp4`（旧格式完整 URL） | 直接返回原值 |
+
+## 文件下载到本地
+
+```java
+// 普通下载
+ossClient.download(fileKey, "/tmp/output.mp4");
+
+// 大文件分片下载（推荐 1GB 以上使用）
+ossClient.multipartDownload(fileKey, "/tmp/", "output.mp4");
+```
+
+## 文件删除
+
+```java
+// 删除单个文件
+ossClient.delete(fileKey);
+
+// 批量删除（任务完成后清理临时文件）
+ossClient.deleteMultiple(List.of(key1, key2, key3));
+```
+
+## 前端分片上传（大文件）
+
+```java
+// 1. 初始化分片任务
+String uploadId = ossClient.createMultipartUpload(fileKey, "video/mp4", Duration.ofHours(1));
+
+// 2. 生成各分片预签名 URL，返回前端（每片约 5MB）
+List<String> partUrls = ossClient.getMultipartUploadUrls(fileKey, uploadId, totalBytes, Duration.ofHours(1));
+
+// 3. 前端按顺序 PUT 上传各分片，收集 ETag 后通知后端合并
+List<UploadPart> parts = /* 前端传回的 partNumber + ETag 列表 */;
+String cdnUrl = ossClient.completeMultipartUpload(fileKey, uploadId, parts);
+
+// 异常情况：取消并清理已上传分片
+ossClient.abortMultipartUpload(fileKey, uploadId, Duration.ofHours(1));
+```

package/templates/.claude/skills/avatar-boot-starter-oss/references//350/247/204/350/214/203/344/270/216/346/263/250/346/204/217/344/272/213/351/241/271.md

@@ -0,0 +1,61 @@
+# OSS 规范与注意事项
+
+## 文件路径规范
+
+**路径由服务端统一生成，禁止客户端自定义**，使用 `OssFileKeyHelper` 工具类：
+
+```java
+// 客户上传素材：materials/{tenantId}/{yyyy}/{MM}/{dd}/{uuid}/{filename}
+String key = OssFileKeyHelper.materialKey("tenant01", "avatar.mp4");
+// → materials/tenant01/2026/03/13/2495d79518da.../avatar.mp4
+
+// 平台生成视频：videos/{tenantId}/{yyyy}/{MM}/{dd}/{taskId}/{filename}
+String key = OssFileKeyHelper.videoKey("tenant01", "task-789", "output.mp4");
+// → videos/tenant01/2026/03/13/task-789/output.mp4
+
+// 临时中间文件：temp/{serviceName}/{yyyy}/{MM}/{dd}/{taskId}/{filename}
+String key = OssFileKeyHelper.tempKey("render-svc", "task-789", "frame_001.jpg");
+// → temp/render-svc/2026/03/13/task-789/frame_001.jpg
+
+// 前端静态资源：static/{version}/{filename}
+String key = OssFileKeyHelper.staticKey("v1.2.3", "app.abc123.js");
+// → static/v1.2.3/app.abc123.js
+```
+
+## DB 存储规范
+
+**DB 中只存 `{bucket}/{filekey}`，不存完整 URL**：
+
+```
+asset/videos/tenant01/2026/03/13/task-789/output.mp4
+```
+
+访问时调用 `ossClient.resolveAccessUrl(storedValue)` 动态生成签名 URL。
+
+## FileKey 编码（接口传参用）
+
+fileKey 含大量斜杠，作为接口参数时使用 Base64URL 编码：
+
+```java
+// 编码：上传后对外暴露
+String encodedKey = OssFileKeyHelper.encodeKey(fileKey);
+
+// 解码：接收到 encodedKey 后还原
+String rawKey = OssFileKeyHelper.decodeKey(encodedKey);
+```
+
+**约定**：
+- 上传接口响应的 `fileKey` 字段返回**编码后**的值
+- 下载/预签名/删除接口接收编码值，内部自动解码；传入原始路径也兼容
+
+## 注意事项
+
+1. **AK/SK 安全**：生产环境通过环境变量或 Nacos 加密配置注入，**禁止明文写入代码仓库**
+
+2. **临时文件清理**：`temp/` 前缀文件在任务完成后必须主动调用 `delete()` 清理，同时在存储侧配置 Lifecycle Policy 7 天兜底过期删除
+
+3. **分片任务异常**：分片上传中断后若未调用 `abortMultipartUpload`，存储侧会产生碎片，建议配置 Lifecycle Policy 3 天清理未完成分片
+
+4. **Nacos 动态刷新**：修改 `avatar.oss.*` 配置后需**重启应用**，不支持运行时热刷新（IOSS SDK 为单例初始化）
+
+5. **MinIO/COS/S3 的 signedHeaders**：预签名 URL 可能含 `x-amz-te` 等 header，前端上传时必须携带，阿里云 OSS 的 signedHeaders 为空 Map