next-flow-interface 0.27.11 → 0.27.14

package/index.d.ts

@@ -1786,7 +1786,7 @@ export declare class FirstLoadService {
      * 开始加载所有文件
      *
      * @remarks
-     * 启动首次加载流程，会遍历 RvFileService.instance.files 中的所有文件并开始下载。
+     * 启动首次加载流程，会遍历 RvResourceService 缓存中的所有文件并开始下载。
      * 该方法会:
      * 1. 检查是否有需要加载的文件
      * 2. 跳过正在上传中的文件(uploading = true)
@@ -5358,7 +5358,7 @@ export declare interface RvAwarenessWindow {
  * 全局协同数据总变量
  *
  * 所有项目数据的根结构，通过 RhineVar 实现多人实时同步。
- * files 和 resources 仅存储 ID 列表，元数据通过对应 Service 从后端获取并缓存在本地。
+ * resources 仅存储 ID 列表，元数据通过 RvResourceService 从后端获取并缓存在本地。
  *
  * @public
  */
@@ -5371,8 +5371,6 @@ export declare interface RvBase {
     steps: RhineVarMap<RvStep>;
     /** 插件信息 */
     plugin: RvPlugin;
-    /** 文件 ID 列表，元数据通过 RvFileService.getMetadata() 获取 */
-    files: RhineVarArray<string>;
     /** 资源 ID 列表，元数据通过 RvResourceService.getMetadata() 获取 */
     resources: RhineVarArray<string>;
     /** 场景节点树 */
@@ -5522,121 +5520,6 @@ export declare interface RvEnvironment {
     };
 }
 
-/**
- * 文件元数据接口
- *
- * 描述项目中一个文件的完整元信息。
- * 协同数据中仅存储 fid，完整元数据通过 RvFileService.getMetadata() 从后端获取并缓存。
- *
- * @public
- */
-export declare interface RvFile {
-    /** 文件唯一标识 */
-    fid: string;
-    /** 文件存储类型 */
-    type: RvFileType;
-    /** 文件名 */
-    name: string;
-    /** 文件大小（字节） */
-    size: number;
-    /** MIME 类型 */
-    mime: string;
-    /** 文件内容哈希值，用于去重 */
-    hash?: string;
-    /** 文件地址。格式: https://xxx | oss://{bucket}/{path} | attach://{fid} */
-    url: string;
-    /** 创建时间戳（毫秒） */
-    createdAt: number;
-    /** 更新时间戳（毫秒） */
-    updatedAt: number;
-    /** 是否正在上传中 */
-    uploading?: boolean;
-    /** 扩展数据 */
-    extra?: Record<string, unknown>;
-}
-
-/**
- * 文件协同数据服务
- *
- * 管理协同数据中的 fileId 列表，以及本地文件元数据缓存。
- * fileId 列表存储在协同数据中，元数据从后端获取并缓存在本地。
- *
- * @public
- */
-export declare class RvFileService {
-    static get instance(): RvFileService;
-    private constructor();
-    files: RhineVarArray<string>;
-    private metadataCache;
-    /**
-     * 添加 fileId 到协同数据
-     */
-    add(fileId: string): void;
-    /**
-     * 从协同数据移除 fileId
-     */
-    remove(fileId: string): boolean;
-    /**
-     * 检查 fileId 是否在列表中
-     */
-    has(fileId: string): boolean;
-    /**
-     * 获取缓存的文件元数据
-     */
-    getMetadata(fileId: string): ResourceFileInfo | undefined;
-    /**
-     * 设置文件元数据缓存
-     */
-    setMetadata(fileId: string, metadata: ResourceFileInfo): void;
-    /**
-     * 获取文件下载 URL（通过后端签名）
-     */
-    getDownloadUrl(fileId: string): Promise<string>;
-    /**
-     * 订阅文件列表变化事件（ADD/REMOVE）
-     *
-     * @param subscriber - 事件回调函数
-     * @returns 取消订阅的函数
-     */
-    subscribe(subscriber: RvFileServiceSubscriber): () => void;
-    /**
-     * 取消订阅文件列表变化事件
-     *
-     * @param subscriber - 要取消的回调函数
-     */
-    unsubscribe(subscriber: RvFileServiceSubscriber): void;
-    /**
-     * 订阅单个文件的变化事件
-     *
-     * @param fileId - 文件 ID
-     * @param subscriber - 事件回调函数
-     * @returns 取消订阅的函数
-     */
-    subscribeSingle(fileId: string, subscriber: RvFileServiceSubscriber): () => void;
-    unsubscribeSingle(fileId: string, subscriber: RvFileServiceSubscriber): void;
-}
-
-/**
- * @public
- */
-export declare enum RvFileServiceEventType {
-    ADD = "ADD",
-    REMOVE = "REMOVE"
-}
-
-/**
- * @public
- */
-export declare type RvFileServiceSubscriber = (type: RvFileServiceEventType, fileId: string) => void;
-
-/**
- * @public
- */
-export declare enum RvFileType {
-    OSS = "OSS",
-    URL = "URL"
-}
-
 /**
  * @public
  */
@@ -6102,8 +5985,7 @@ export declare interface RvResource {
 /**
  * 资源协同数据服务
  *
- * 管理协同数据中的 resourceId 列表，以及本地资源元数据缓存。
- * resourceId 列表存储在协同数据中，元数据从后端获取并缓存在本地。
+ * 管理协同数据中的 resourceId 列表，以及本地资源和文件元数据缓存。
  *
  * @public
  */
@@ -6112,8 +5994,11 @@ export declare class RvResourceService {
     private constructor();
     resources: StoredRhineVar<string[]>;
     private metadataCache;
+    private fileToResourceMap;
     /**
      * 添加 resourceId 到协同数据
+     *
+     * 如果资源元数据已在缓存中，会自动同步文件元数据并触发下载
      */
     add(resourceId: string): void;
     /**
@@ -6128,38 +6013,75 @@ export declare class RvResourceService {
      * 获取缓存的资源元数据
      */
     getMetadata(resourceId: string): Resource | undefined;
+    /**
+     * 通过 fileId 获取对应的资源元数据
+     */
+    getMetadataByFileId(fileId: string): Resource | undefined;
     /**
      * 设置资源元数据缓存
      */
     setMetadata(resourceId: string, metadata: Resource): void;
+    private fileMetadataCache;
     /**
-     * 批量获取所有资源元数据（项目初始化时调用）
-     *
-     * 同时从 Resource.contentFile 提取文件元数据，写入 RvFileService.metadataCache
+     * 添加文件元数据到本地缓存，并发布 ADD 事件
      */
-    fetchAllMetadata(): Promise<void>;
+    addFile(fileId: string, metadata?: ResourceFileInfo): void;
     /**
-     * 订阅资源列表变化事件（ADD/REMOVE）
+     * 从本地缓存移除文件元数据，并发布 REMOVE 事件
+     */
+    removeFile(fileId: string): boolean;
+    /**
+     * 检查文件是否在本地缓存中
+     */
+    hasFile(fileId: string): boolean;
+    /**
+     * 获取缓存的文件元数据
+     */
+    getFileMetadata(fileId: string): ResourceFileInfo | undefined;
+    /**
+     * 设置文件元数据缓存（不触发事件）
+     */
+    setFileMetadata(fileId: string, metadata: ResourceFileInfo): void;
+    /**
+     * 获取所有文件 ID 列表
+     */
+    getFileIds(): string[];
+    /**
+     * 获取文件下载 URL（通过后端签名）
+     */
+    getDownloadUrl(fileId: string): Promise<string>;
+    /**
+     * 从后端同步资源列表到本地缓存
      *
-     * @param subscriber - 事件回调函数
-     * @returns 取消订阅的函数
+     * 通过 listResources 一次性拉取后端完整资源列表，
+     * 仅填充本地元数据缓存，不自动添加到协同数据。
+     * 需要手动调用 add() 方法将资源添加到协同数据。
      */
-    subscribe(subscriber: RvResourceServiceSubscriber): () => void;
+    syncFromBackend(): Promise<void>;
     /**
-     * 取消订阅资源列表变化事件
+     * 获取所有后端资源的元数据列表（从本地缓存）
      *
-     * @param subscriber - 要取消的回调函数
+     * @returns 资源元数据数组
      */
-    unsubscribe(subscriber: RvResourceServiceSubscriber): void;
+    getAllMetadata(): Resource[];
     /**
-     * 订阅单个资源的变化事件
+     * 获取所有未添加到协同数据的资源列表
      *
-     * @param resourceId - 资源 ID
-     * @param subscriber - 事件回调函数
-     * @returns 取消订阅的函数
+     * @returns 未添加的资源元数据数组
      */
+    getUnaddedResources(): Resource[];
+    /**
+     * 订阅资源列表变化事件（ADD/REMOVE）
+     */
+    subscribe(subscriber: RvResourceServiceSubscriber): () => void;
+    unsubscribe(subscriber: RvResourceServiceSubscriber): void;
     subscribeSingle(resourceId: string, subscriber: RvResourceServiceSubscriber): () => void;
     unsubscribeSingle(resourceId: string, subscriber: RvResourceServiceSubscriber): void;
+    /**
+     * 订阅文件变化事件（ADD/REMOVE）
+     */
+    subscribeFile(subscriber: RvResourceServiceSubscriber): () => void;
+    unsubscribeFile(subscriber: RvResourceServiceSubscriber): void;
 }
 
 /**
@@ -6931,8 +6853,8 @@ export declare class SyncService {
      * // 访问场景步骤
      * const steps = SyncService.instance.state.steps
      *
-     * // 访问文件
-     * const files = SyncService.instance.state.files
+     * // 访问资源
+     * const resources = SyncService.instance.state.resources
      *
      * // 等待同步完成
      * await SyncService.instance.state.waitSynced()
@@ -7547,7 +7469,6 @@ export declare const attributeService: AttributeService
 export declare const awarenessService: AwarenessService
 export declare const historyService: HistoryService
 export declare const rvStepService: RvStepService
-export declare const rvFileService: RvFileService
 export declare const rvResourceService: RvResourceService
 export declare const rvSceneService: RvSceneService
 export declare const rvModelService: RvModelService

package/package.json

@@ -36,7 +36,7 @@
     "valtio": "2.1.7",
     "rhine-var": "2.4.3"
   },
-  "version": "0.27.11",
+  "version": "0.27.14",
   "author": "NextFlow",
   "license": "Apache-2.0",
   "keywords": [