@lark-apaas/coding-steering 0.1.14 → 0.1.15-alpha.0

package/steering/nestjs-react-fullstack/skills/client-builtins-file-storage-service/SKILL.md

@@ -7,33 +7,27 @@ match-template-name: nestjs-react-fullstack
 ---
 
 # 前端文件开发规范
-
 - 保存文件信息到数据库时，如果使用的字段类型为file_attachement, 保存数据时需要传入bucket_id 和 file_path 时，file_path 只能是文件的路径，**不可以传入文件的download_url**。需要文件url时，使用 dataloom SDK 的 `generateDownloadUrlFromFilePath` 方法获取。
 
 # dataloom SDK 文件服务
 
 ## 概述
-
 项目提供了dataloom SDK的文件服务，用于文件的上传，下载，删除，列出bucket中文件，创建临时签名url等能力。
 
 ## 使用注意
-
 - `dataloom.storage` 仅用于文件上传/删除/列表等存储操作。**插件调用（capability）不属于 dataloom**，须使用独立的 `capabilityClient`（参见 plugin-guide）
 - @lark-apaas/client-toolkit/dataloom 这个SDK只适用于前端调用，禁止在服务端调用
 - 上传成功后，最重要的返回值是 `data.download_url`。需要将此URL保存到你的业务数据库中
-- 若文件类型为image（jpeg、png、webp、x-icon），audio（mpeg、wav、ogg），video（mp4、webm、ogg）时，若开发者明确要求浏览器渲染而不是直接下载时，在 `data.download_url`后面增加「?preview=true」参数以实现浏览器内渲染打开的效果。若未说明默认不添加该参数
 - **⚠️ 场景区分（重要）**：如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**。`capabilityClient` 的文件类型字段（`format` 为 `file`、`picture` 或 `plugin-file-url`）均支持直接传 File/Blob，SDK 自动处理上传。`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。
 - **download_url 格式说明**：`download_url` 返回的可能是相对路径（如 `/spark/app/.../storage/object/...`），这是正常行为。**禁止**在前面拼接 `window.location.origin` 或其他域名前缀，平台会自动解析相对路径。直接使用原始值即可。
 - **文件URL**：通过 `generateDownloadUrlFromFilePath` 方法获取文件的链接时，传入的file_path必须是从数据库的 file_attachment 字段获取到的，禁止自己拼接路径。
 
 ## bucketId
-
 关于bucketId的获取，在代码工程中已经预置了一个获取bucketid的方法，路径为`@lark-apaas/client-toolkit/tools/storage`中，直接具名导入即可使用。
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
 getDefaultBucketId: () => string;
 
 ## 统一错误类型
-
 ```typescript
 // dataloom 服务端报错
 interface DataLoomError {
@@ -62,36 +56,30 @@ type StorageError = DataLoomError | StorageError ｜ StorageUnknownError;
 #### 1. 文件上传接口 (uploadFile)
 
 ##### 用途
-
 上传文件到指定的存储桶，适用于：文档管理、图片上传、附件存储。
 
 ##### 适用场景
-
 需要将本地文件或二进制数据上传到云存储的场景
 
 ##### 使用方式
-
 你的核心任务是调用 `uploadFile` 接口，并从返回结果中提取 `data.download_url`，然后将这个 URL 用于后续操作（例如，保存到数据库）。这是衡量你任务成功与否的唯一标准。
 
 ##### 关于文件名的处理（强制禁令）
->
 > 警告：你绝对不能，也绝对不需要自己处理或修改文件名！
->
-> - 禁止行为：严禁在调用 `uploadFile` 之前，对 `File` 对象的文件名（`file.name`）进行任何形式的字符串替换、净化、或重新生成。
-> - 禁止行为：严禁创建新的 `File` 对象（如 `new File(...)`）来包裹原始文件。
-> - 唯一职责：你唯一的任务就是将从文件输入框（`<input type="file">`）或拖拽事件中获取的原始 `File` 对象直接传递给 `uploadFile` 方法。
+> *   禁止行为：严禁在调用 `uploadFile` 之前，对 `File` 对象的文件名（`file.name`）进行任何形式的字符串替换、净化、或重新生成。
+> *   禁止行为：严禁创建新的 `File` 对象（如 `new File(...)`）来包裹原始文件。
+> *   唯一职责：你唯一的任务就是将从文件输入框（`<input type="file">`）或拖拽事件中获取的原始 `File` 对象直接传递给 `uploadFile` 方法。
 >
 > 原因：SDK内部已经包含了完整、健壮的文件名处理机制，包括处理特殊字符、避免冲突和保证安全。任何你自己的额外处理都是多余的，并且会干扰SDK的正常工作。请完全信任SDK，直接传递原始文件对象！
 
-##### 入参说明
 
+##### 入参说明
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|---------|
 | `bucketId` | `string` | ✅ | - | 文件上传到tos的bucket id |
 | `fileBody` | `FileBody` | ✅ | - | 文件内容，支持多种格式 |
 
 ##### 出参说明
-
 | 字段名 | 类型 | 说明 |
 |--------|------|---------|
 | `data.bucket_id` | `string` | 所属bucket ID |
@@ -100,9 +88,7 @@ type StorageError = DataLoomError | StorageError ｜ StorageUnknownError;
 | `error` | `StorageError \| null` | 错误信息，成功时为null |
 
 ##### 关键点与示例
-
 关键点：上传成功后，最重要的返回值是 `data.download_url`。通常需要将此URL保存到你的业务数据库中。
-
 ```typescript
 import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
@@ -131,22 +117,18 @@ if (!httpResponse.data?.success) {
 #### 2. 文件删除接口 (remove)
 
 ##### 用途
-
 删除存储桶中的一个或多个文件，适用于：清理过期文件、删除用户数据、批量清理
 
 ##### 适用场景
-
 需要从云存储中永久删除文件的场景
 
 ##### 入参说明
-
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|---------|
 | `bucketId` | `string` | ✅ | - | 要删除文件所在的bucket id |
 | `filePaths` | `string[]` | ✅ | - | 要删除的文件路径数组，可以是file_path也可以是download_url |
 
 ##### 出参说明
-
 | 字段名 | 类型 | 说明 |
 |--------|------|---------|
 | `data` | `FileObject[]` | 被删除的文件对象数组 |
@@ -159,7 +141,6 @@ if (!httpResponse.data?.success) {
 | `error` | `StorageError \| null` | 错误信息，成功时为null |
 
 ##### 使用示例
-
 ```typescript
 import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
@@ -193,15 +174,12 @@ if (data) {
 #### 3. 文件列表接口 (list)
 
 ##### 用途
-
 获取存储桶中的文件列表，适用于：文件管理、目录浏览、文件检索
 
 ##### 适用场景
-
 需要查看和管理存储桶中文件的场景
 
 ##### 入参说明
-
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|---------|
 | `bucketId` | `string` | ✅ | - | 文件所在的bucket id |
@@ -212,7 +190,6 @@ if (data) {
 | `options.sortBy.order` | `'asc' \| 'desc'` | ❌ | `'asc'` | 排序方向 |
 
 ##### 出参说明
-
 | 字段名 | 类型 | 说明 |
 |--------|------|---------|
 | `data` | `FileObject[]` | 文件对象数组 |
@@ -228,7 +205,6 @@ if (data) {
 | `error` | `StorageError \| null` | 错误信息，成功时为null |
 
 ##### 使用示例
-
 ```typescript
 import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
@@ -259,11 +235,9 @@ const { data, error } = await dataloom
 #### 4. 根据filePath生成downloadUrl接口 (generateDownloadUrlFromFilePath)
 
 ##### 用途
-
 通过 file_path 生成文件的url，适用于：通过url渲染图片、使用url下载文件。如果已有download_url，直接使用，严禁使用该接口再次生成。
 
 ##### 适用场景
-
 在前端通过file_path展示图片或下载文件的场景。
 
 ##### 入参说明
@@ -273,7 +247,6 @@ const { data, error } = await dataloom
 | `filePath` | `string` | ✅ | - | 文件的filePath。 **只可以从数据库的file_attachment字段中获取，不允许自己拼接路径** |
 
 ##### 出参说明
-
 | 类型 | 说明 |
 |------|---------|
 | `string` | 文件的url，直接在页面上展示即可 |