@lark-apaas/coding-steering 0.1.6-alpha.1 → 0.1.6-alpha.10

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

@@ -0,0 +1,405 @@
+---
+name: client-builtins-file-storage-service
+description: 前端文件存储服务指南，基于 dataloom.storage 实现文件上传、删除、列表查询、使用filePath换取图片链接，包含 uploadFile、remove、list、getDefaultBucketId、generateDownloadUrlFromFilePath 等 API 用法。Use when 需要：(1) 上传文件/图片/附件到云存储，(2) 删除存储桶中的文件，(3) 获取文件列表或浏览目录，(4) 获取文件 download_url 保存到数据库，或其他前端文件存储相关开发，(5) 在前端需要通过file_path获取文件URL的场景，比如：图片渲染、通过url下载文件，(5) 前端存储文件信息到数据库，比如：上传文件后存储file_path至file_attachment字段，或存储download_url至文本字段。
+steering: true
+steering-topic: client_builtins_file_storage_service
+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 {
+    error_msg: string;
+    lang_id: number;
+    status_code: string;
+};
+
+// sdk 内部校验报错
+interface StorageError {
+    name: 'StorageError';
+    message: string;
+};
+
+// 其他未被识别报错, 继承 StorageError
+interface StorageUnknownError {
+    name: 'StorageUnknownError';
+    message: string;
+    // 兜底catch到的error
+    originalError: unknown;
+};
+
+type StorageError = DataLoomError | StorageError ｜ StorageUnknownError;
+```
+
+#### 1. 文件上传接口 (uploadFile)
+
+##### 用途
+上传文件到指定的存储桶，适用于：文档管理、图片上传、附件存储。
+
+##### 适用场景
+需要将本地文件或二进制数据上传到云存储的场景
+
+##### 使用方式
+你的核心任务是调用 `uploadFile` 接口，并从返回结果中提取 `data.download_url`，然后将这个 URL 用于后续操作（例如，保存到数据库）。这是衡量你任务成功与否的唯一标准。
+
+##### 关于文件名的处理（强制禁令）
+> 警告：你绝对不能，也绝对不需要自己处理或修改文件名！
+> *   禁止行为：严禁在调用 `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 |
+| `data.file_path` | `string` | 文件的路径，不是文件的url，可以存储在 file_attachment 字段中 |
+| `data.download_url` | `string` | 文件url（可能是相对路径如 `/spark/app/.../storage/object/...`，也可能是绝对 URL），可直接用于下载文件或渲染图片。**禁止**在前面拼接 `window.location.origin` 或任何域名前缀，直接使用原始值即可 |
+| `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";
+import { logger } from "@lark-apaas/client-toolkit/logger";
+// 1. 获取文件
+const file = fileInput.files[0]; 
+// 2. 调用上传接口
+const { data, error } = await dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .uploadFile(file); // 直接传递原始 file 对象
+if (error || !data) {
+  throw new Error("文件上传失败: " + (error?.message || "未知错误"));
+}
+// 3. 提取并使用 `download_url`
+logger.info("上传成功，文件下载链接为:", data.download_url);
+// 4. 将 `download_url` 保存到数据库
+const httpResponse = await imageControllerCreate({
+  body: { url: data.download_url } // <-- 关键点：使用 data.download_url
+});
+if (!httpResponse.data?.success) {
+  throw new Error(httpResponse.data?.message || "保存图片信息失败");
+}
+```
+
+#### 2. 文件删除接口 (remove)
+
+##### 用途
+删除存储桶中的一个或多个文件，适用于：清理过期文件、删除用户数据、批量清理
+
+##### 适用场景
+需要从云存储中永久删除文件的场景
+
+##### 入参说明
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|---------|
+| `bucketId` | `string` | ✅ | - | 要删除文件所在的bucket id |
+| `filePaths` | `string[]` | ✅ | - | 要删除的文件路径数组，可以是file_path也可以是download_url |
+
+##### 出参说明
+| 字段名 | 类型 | 说明 |
+|--------|------|---------|
+| `data` | `FileObject[]` | 被删除的文件对象数组 |
+| `data[].name` | `string` | 文件名称 |
+| `data[].bucket_id` | `string` | 所属bucket ID |
+| `data[].id` | `string` | 文件唯一标识符 |
+| `data[].created_at` | `string` | 文件创建时间 |
+| `data[].updated_at` | `string` | 文件更新时间 |
+| `data[].metadata` | `TosMetaData` | 文件元数据信息 |
+| `error` | `StorageError \| null` | 错误信息，成功时为null |
+
+##### 使用示例
+```typescript
+import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
+import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
+import { logger } from "@lark-apaas/client-toolkit/logger";
+
+// 异步获取dataloom实例
+const dataloom = await getDataloom();
+
+// 删除单个文件
+const { data, error } = await dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .remove(['/documents/old-report.pdf']);
+
+// 批量删除文件
+const { data, error } = await dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .remove([
+    '/documents/file1.pdf',
+    '/images/image1.jpg',
+    '/temp/cache.txt'
+  ]);
+
+// 注意：删除不存在的filePaths会返回空数组
+if (data) {
+  logger.info('删除的文件:', data); // 返回所有被删除的文件对象
+}
+```
+
+#### 3. 文件列表接口 (list)
+
+##### 用途
+获取存储桶中的文件列表，适用于：文件管理、目录浏览、文件检索
+
+##### 适用场景
+需要查看和管理存储桶中文件的场景
+
+##### 入参说明
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|---------|
+| `bucketId` | `string` | ✅ | - | 文件所在的bucket id |
+| `path` | `string` | ❌ | - | 文件夹路径，用于筛选特定目录 |
+| `options.limit` | `number` | ❌ | `100` | 返回的文件数量限制 |
+| `options.offset` | `number` | ❌ | `0` | 分页起始位置 |
+| `options.sortBy.column` | `'name' \| 'created_at' \| 'updated_at'` | ❌ | `'name'` | 排序字段 |
+| `options.sortBy.order` | `'asc' \| 'desc'` | ❌ | `'asc'` | 排序方向 |
+
+##### 出参说明
+| 字段名 | 类型 | 说明 |
+|--------|------|---------|
+| `data` | `FileObject[]` | 文件对象数组 |
+| `data[].name` | `string` | 文件名称 |
+| `data[].bucket_id` | `string` | 所属bucket ID |
+| `data[].id` | `string` | 文件唯一标识符，如果id不存在则说明当前为文件夹，需要通过list接口继续获取文件夹下的文件，直到遍历完成才能拿到所有文件 |
+| `data[].created_at` | `string` | 文件创建时间 |
+| `data[].updated_at` | `string` | 文件更新时间 |
+| `data[].created_by` | `string` | 文件创建者 |
+| `data[].updated_by` | `string` | 文件更新者 |
+| `data[].buckets` | `Bucket` | bucket详细信息 |
+| `data[].metadata` | `TosMetaData` | 文件元数据（包含文件大小、类型等） |
+| `error` | `StorageError \| null` | 错误信息，成功时为null |
+
+##### 使用示例
+```typescript
+import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
+import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
+
+// 异步获取dataloom实例
+const dataloom = await getDataloom();
+
+// 基本列表查询
+const { data, error } = await dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .list('/documents');
+
+// 带分页和排序的查询
+const { data, error } = await dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .list('/images', {
+    limit: 20,
+    offset: 0,
+    sortBy: {
+      column: 'created_at',
+      order: 'desc'
+    }
+  });
+```
+
+#### 4. 根据filePath生成downloadUrl接口 (generateDownloadUrlFromFilePath)
+
+##### 用途
+通过 file_path 生成文件的url，适用于：通过url渲染图片、使用url下载文件。如果已有download_url，直接使用，严禁使用该接口再次生成。
+
+##### 适用场景
+在前端通过file_path展示图片或下载文件的场景。
+
+##### 入参说明
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|--------|---------|--------|---------|
+| `filePath` | `string` | ✅ | - | 文件的filePath。 **只可以从数据库的file_attachment字段中获取，不允许自己拼接路径** |
+
+##### 出参说明
+| 类型 | 说明 |
+|------|---------|
+| `string` | 文件的url，直接在页面上展示即可 |
+
+##### 使用示例
+
+```typescript
+import { useEffect, useState } from "react";
+import { Button } from '@client/src/components/ui/button';
+import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
+import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
+
+const ImageExample = ({ file }: { file: { file_path: string; bucket_id: string } }) => {
+  const [imageUrl, setImageUrl] = useState('');
+
+  useEffect(() => {
+    const getImageUrl = async () => {
+      const dataloom = await getDataloom();
+      const imageUrl = dataloom
+        .storage
+        .from(getDefaultBucketId())
+        .generateDownloadUrlFromFilePath(file.file_path);
+      setImageUrl(imageUrl);
+    };
+
+    getImageUrl();
+  }, [file.file_path]);
+
+  return <img src={imageUrl} alt="图片" />;
+}
+```
+
+#### 5. 最小化文件上传与展示示例
+
+##### 后端接口假设（`shared/api.interface.ts`）
+
+```typescript
+export interface FileRecord { id: string; fileName: string; downloadUrl: string; createdAt: string; }
+// POST /api/files  → { success: true, data: FileRecord, message: "ok" }
+// GET  /api/files  → { success: true, data: FileRecord[], message: "ok" }
+export interface FileApiResp<T = FileRecord> { success: boolean; data: T; message: string; }
+```
+
+##### 各 API 预估返回格式
+
+| API | 成功返回 | 失败返回 |
+|-----|---------|---------|
+| `uploadFile(file)` | `{ data: { bucket_id: "xxx", file_path: "123456.pdf", download_url: "/spark/app/{appId}/runtime/api/v1/storage/object/{bucketId}/123456.pdf" }, error: null }` | `{ data: null, error: { name: "StorageError", message: "..." } }` |
+| `list('/path')` | `{ data: [{ name, bucket_id, id, created_at, metadata: { size, mimetype } }], error: null }` | `{ data: null, error: { error_msg: "...", status_code: "404" } }` |
+| `remove([url])` | `{ data: [{ name, bucket_id, id, ... }], error: null }`；不存在则 `data: []` | 同上 |
+| `POST /api/files` | `{ success: true, data: { id, fileName, downloadUrl, createdAt }, message: "ok" }` | `{ success: false, data: null, message: "错误描述" }` |
+| `GET /api/files` | `{ success: true, data: [FileRecord, ...], message: "ok" }` | 同上 |
+
+##### 示例代码
+
+```tsx
+import React, { useEffect, useRef, useState } from "react";
+import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
+import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
+import { axiosForBackend } from "@lark-apaas/client-toolkit/utils/getAxiosForBackend";
+import { logger } from "@lark-apaas/client-toolkit/logger";
+import { Button } from "@client/src/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@client/src/components/ui/card";
+import { toast } from "sonner";
+import { Upload, FileIcon, Loader2 } from "lucide-react";
+import type { FileRecord, FileApiResp } from "@shared/api.interface";
+
+const FileUploadDemo: React.FC = () => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [files, setFiles] = useState<FileRecord[]>([]);
+  const [uploading, setUploading] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  const fetchFiles = async () => {
+    setLoading(true);
+    try {
+      const res = await axiosForBackend.get<FileApiResp<FileRecord[]>>("/api/files");
+      if (res.data?.success) setFiles(res.data.data);
+    } catch (err) {
+      logger.error(`获取文件列表失败: ${String(err)}`);
+      toast.error("获取文件列表失败");
+    } finally { setLoading(false); }
+  };
+
+  useEffect(() => { fetchFiles(); }, []);
+
+  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    setUploading(true);
+    try {
+      // 1. dataloom SDK 上传（直接传原始 file，禁止包装或修改文件名）
+      const dataloom = await getDataloom();
+      const { data, error } = await dataloom.storage.from(getDefaultBucketId()).uploadFile(file);
+      if (error || !data) throw new Error("上传失败: " + (error?.message ?? error?.error_msg ?? "未知错误"));
+
+      // 2. 保存 download_url 到后端
+      const res = await axiosForBackend.post<FileApiResp>("/api/files", {
+        fileName: file.name, downloadUrl: data.download_url,
+      });
+      if (!res.data?.success) throw new Error(res.data?.message || "保存失败");
+
+      toast.success(`${file.name} 上传成功`);
+      fetchFiles();
+    } catch (err) {
+      logger.error(`上传失败: ${String(err)}`);
+      toast.error(String(err));
+    } finally {
+      setUploading(false);
+      if (inputRef.current) inputRef.current.value = "";
+    }
+  };
+
+  return (
+    <Card className="w-full max-w-2xl mx-auto">
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2"><FileIcon className="h-5 w-5" />文件管理</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <input ref={inputRef} type="file" onChange={handleUpload} className="hidden" />
+        <Button onClick={() => inputRef.current?.click()} disabled={uploading}>
+          {uploading ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Upload className="mr-2 h-4 w-4" />}
+          {uploading ? "上传中..." : "选择文件上传"}
+        </Button>
+        {loading ? (
+          <div className="flex justify-center py-8"><Loader2 className="h-6 w-6 animate-spin text-muted-foreground" /></div>
+        ) : files.length === 0 ? (
+          <p className="text-center text-muted-foreground py-8">暂无文件</p>
+        ) : (
+          <ul className="space-y-2">
+            {files.map((f) => (
+              <li key={f.id} className="flex items-center justify-between gap-2 rounded-md border p-3">
+                <a href={f.downloadUrl} target="_blank" rel="noopener noreferrer" className="flex items-center gap-2 min-w-0 truncate text-sm hover:underline">
+                  <FileIcon className="h-4 w-4 shrink-0 text-muted-foreground" />{f.fileName}
+                </a>
+                <span className="text-xs text-muted-foreground shrink-0">{new Date(f.createdAt).toLocaleDateString()}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </CardContent>
+    </Card>
+  );
+};
+export default FileUploadDemo;
+```
+
+##### 关键点
+
+| 要点 | 说明 |
+|------|------|
+| 上传流程 | `uploadFile(file)` → 取 `data.download_url` → POST 后端保存 |
+| 文件对象 | 直接传原始 `File`，**禁止**包装或修改文件名 |
+| 组件依赖 | shadcn/ui `Button`/`Card` + `lucide-react` + `sonner` |
+| 请求实例 | 必须用 `axiosForBackend`，禁止 `fetch` |