next-flow-interface 0.24.8 → 0.24.9

package/README.md

@@ -1 +1 @@
-# next-flow-interface
+# next-flow-interface

package/index.d.ts

@@ -4895,19 +4895,180 @@ declare function stopPropagationListener(e: ReactEvent): void
 export declare type SupportAnimationTarget = Node_2 | Scene | Material | NodeMaterialBlock | ShadowGenerator
 
 /**
- * @description 管理协同数据的最基本服务
+ * 同步服务 - 管理多人协同数据的核心服务
+ *
+ * @description
+ * SyncService 是管理 Next Flow 所有协同数据的基础服务。
+ * 它负责初始化和协调 RhineVar 同步系统，管理客户端连接，
+ * 并编排所有子服务，包括文件、资源、模型、场景和插件等。
+ *
+ * 该服务采用单例模式，首次访问时自动初始化。
+ * 所有协同状态存储在 `state` 属性中，这是一个 RhineVar 代理对象，
+ * 会实时同步到所有连接的客户端。
+ *
+ * @example
+ * ```typescript
+ * // 获取同步服务实例
+ * const syncService = SyncService.instance
+ *
+ * // 为新实体生成唯一 ID
+ * const newId = syncService.generateId('model')
+ *
+ * // 访问协同状态
+ * const steps = syncService.state.steps
+ * ```
  *
  * @public
  */
 export declare class SyncService {
+  /**
+   * RhineVar 同步覆写模式标志
+   *
+   * @description
+   * 启用时，允许本地状态在初始化时覆盖远程状态。
+   * 通常仅用于开发或调试目的。
+   *
+   * @defaultValue false
+   * @public
+   */
   OVERWRITE_MODE: boolean
+  /**
+   * 启用 RhineVar 内部日志
+   *
+   * @description
+   * 启用时，打开 RhineVar 操作的详细日志。
+   * 用于调试同步问题。
+   *
+   * @defaultValue false
+   * @public
+   */
   ENABLE_RHINE_VAR_LOG: boolean
+  /**
+   * 获取 SyncService 的单例实例
+   *
+   * @description
+   * 返回 SyncService 的单例实例。如果不存在则创建新实例。
+   * 服务在首次访问时自动开始初始化。
+   *
+   * @returns SyncService 单例实例
+   *
+   * @example
+   * ```typescript
+   * const syncService = SyncService.instance
+   * ```
+   *
+   * @public
+   */
   static get instance(): SyncService
-  private constructor()
+  /**
+   * RhineVar 同步服务器的 WebSocket 地址
+   *
+   * @description
+   * 用于连接 RhineVar 同步服务器的 URL。
+   * 使用当前页面的项目 ID 构造而成。
+   *
+   * @public
+   */
   url: string
+  /**
+   * RhineVar 协同状态对象
+   *
+   * @description
+   * 在所有客户端之间同步的根协同状态对象。
+   * 该对象包含所有项目数据，包括场景步骤、文件、资源、模型、场景节点等。
+   * 对此状态的任何修改都会自动同步到所有连接的客户端。
+   *
+   * 配置选项：
+   * - 覆写模式（如果启用）
+   * - 撤销管理器用于历史记录跟踪
+   * - 协作感知用于跟踪其他用户
+   *
+   * @see {@link RvBase} 查看完整的状态结构
+   *
+   * @example
+   * ```typescript
+   * // 访问场景步骤
+   * const steps = SyncService.instance.state.steps
+   *
+   * // 访问文件
+   * const files = SyncService.instance.state.files
+   *
+   * // 等待同步完成
+   * await SyncService.instance.state.waitSynced()
+   * ```
+   *
+   * @public
+   */
   state: RecursiveObject<RvBase>
+  /**
+   * 客户端唯一标识符
+   *
+   * @description
+   * RhineVar 同步系统分配给此客户端的唯一数字 ID。
+   * 用于在所有连接的客户端中识别此客户端，并生成唯一的实体 ID。
+   *
+   * @public
+   */
   clientId: number
+  /**
+   * 使用指定前缀生成唯一 ID
+   *
+   * @description
+   * 通过组合以下内容生成唯一标识符：
+   * - 提供的前缀
+   * - 该前缀的自增计数器
+   * - 当前客户端 ID
+   *
+   * 这确保了 ID 在所有客户端和实体类型之间都是唯一的。
+   *
+   * @param prefix - 用于 ID 的前缀（例如：'model'、'step'、'file'）
+   * @returns 格式为 `{prefix}{counter}-{clientId}` 的唯一 ID 字符串
+   *
+   * @example
+   * ```typescript
+   * // 生成唯一的模型 ID
+   * const modelId = SyncService.instance.generateId('model')
+   * // 返回: "model0-12345" (其中 12345 是客户端 ID)
+   *
+   * // 再次生成模型 ID
+   * const modelId2 = SyncService.instance.generateId('model')
+   * // 返回: "model1-12345"
+   *
+   * // 生成场景步骤 ID
+   * const stepId = SyncService.instance.generateId('step')
+   * // 返回: "step0-12345"
+   * ```
+   *
+   * @public
+   */
   generateId(prefix: string): string
+  /**
+   * 重置所有协同数据
+   *
+   * @description
+   * **⚠️ 危险操作：这是一个破坏性操作！**
+   *
+   * 通过删除底层 RhineVar YMap 中的状态，完全清除所有协同数据。
+   * 这将影响所有连接的客户端，并且无法撤销。
+   *
+   * 请极其谨慎使用，通常仅用于：
+   * - 开发/测试目的
+   * - 从损坏的状态中恢复
+   * - 经过用户确认的有意项目重置
+   *
+   * @returns 如果重置成功返回 `true`，如果未找到基础映射表返回 `false`
+   *
+   * @example
+   * ```typescript
+   * // 重置所有数据（请谨慎使用！）
+   * const success = SyncService.instance.reset()
+   * if (success) {
+   *   console.log('All collaborative data has been cleared')
+   * }
+   * ```
+   *
+   * @public
+   */
   reset(): boolean
 }
 

package/package.json

@@ -37,7 +37,7 @@
     "valtio": "2.1.7",
     "rhine-var": "0.11.2"
   },
-  "version": "0.24.8",
+  "version": "0.24.9",
   "author": "NextFlow",
   "license": "Apache-2.0",
   "keywords": [