model-action 2.1.0 → 2.2.1

package/dist/modules/Window.d.ts

@@ -1,18 +1,71 @@
 /**
- * 点POI打开外部弹窗
- * 用来让UE抛出POI位置
+ * 弹框：三维内置弹框或外部弹框（返回屏幕坐标比例供前端自绘，可随锚点移动）。
+ * 内置样式需按项目单独开发，本包只负责协议与发送。
  */
 import { Action } from "./Action";
+/** create / remove / update / move */
+export type WindowCrudAction = "create" | "remove" | "update" | "move";
+export type WindowActionType = WindowCrudAction | "getWindowDetails";
+/** buildIn：三维内弹框；buildOut：前端弹框（接收屏幕坐标比例） */
+export type WindowPopType = "buildIn" | "buildOut";
+/** 弹框详情行：属性 / 事件 / 服务 */
+export type WindowDetailRowType = "attr" | "event" | "service";
+/** windowInfo.params 单项 */
+export interface WindowDetailParam {
+    /** 默认 attr；为空时三维会按 attr 处理 */
+    type?: WindowDetailRowType;
+    id?: string;
+    value?: string;
+    name?: string;
+    unit?: string;
+    textColor?: string;
+    textSize?: number;
+    /** 文本是否有背景（协议字段名如此） */
+    hasBlackground?: boolean;
+    alertIs?: boolean;
+    alertTime?: string;
+}
+/** 弹框主体配置 */
+export interface WindowInfo {
+    /** 设备所在场景编码，按项目约定，非必须 */
+    sceneCode?: string;
+    /** 弹框唯一 id，不传由三维生成 */
+    id?: string;
+    /** 绑定的三维资产模型 id */
+    linkAssetId?: string;
+    /** 标题 */
+    name?: string;
+    /** 设备/弹框类型 */
+    type?: string;
+    /** 世界坐标；不传则可用 linkAssetId 对应资产坐标 */
+    position?: string;
+    /** 相对锚点偏移，用于微调 */
+    localPosition?: string;
+    /** 详情内容；列表时每项一行 */
+    params?: WindowDetailParam[];
+}
+export type WindowPayload = {
+    action: WindowCrudAction;
+    popType: WindowPopType;
+    windowInfo: WindowInfo;
+} | {
+    action: "getWindowDetails";
+    /** 如机柜、机柜设备 */
+    type: string;
+    id: string;
+    /** 注意：与 windowInfo.sceneCode 不同，此处协议字段名为 senceCode */
+    senceCode: string;
+};
 export declare class WindowAction extends Action {
+    private static crud;
+    static createWindow(popType: WindowPopType, windowInfo: WindowInfo): Promise<any>;
+    static removeWindow(popType: WindowPopType, windowInfo: WindowInfo): Promise<any>;
+    static updateWindow(popType: WindowPopType, windowInfo: WindowInfo): Promise<any>;
+    static moveWindow(popType: WindowPopType, windowInfo: WindowInfo): Promise<any>;
     /**
-      * 打开外部弹窗
-      * @param {*} attendId (必须）弹框的三维物体的唯一ID)
-      */
-    static openOut(attendId: string): void;
-    /**
-     * 关闭外部弹窗
-     * @param {*} attendId (必须）弹框的三维物体的唯一ID)
+     * 查询弹框详情（按设备类型、设备 id、场景）
+     * @param senceCode 协议字段名与 sceneCode 拼写不一致，与三维约定保持一致
      */
-    static closeOut(attendId: string): void;
+    static getWindowDetails(type: string, id: string, senceCode: string): Promise<any>;
 }
 //# sourceMappingURL=Window.d.ts.map

package/dist/modules/Window.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Window.d.ts","sourceRoot":"","sources":["../../src/modules/Window.ts"],"names":[],"mappings":"AACA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAG,MAAM,UAAU,CAAC;AAEnC,qBAAa,YAAa,SAAQ,MAAM;IACpC;;;QAGI;IACJ,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM;IAY/B;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM;CAWnC"}
+{"version":3,"file":"Window.d.ts","sourceRoot":"","sources":["../../src/modules/Window.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAa,MAAM,UAAU,CAAC;AAE7C,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAEnD,yBAAyB;AACzB,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAE/D,2BAA2B;AAC3B,MAAM,WAAW,iBAAiB;IAC9B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,aAAa;AACb,MAAM,WAAW,UAAU;IACvB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS;IACT,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GACnB;IACI,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;CAC1B,GACD;IACI,MAAM,EAAE,kBAAkB,CAAC;IAC3B,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAOR,qBAAa,YAAa,SAAQ,MAAM;IACpC,OAAO,CAAC,MAAM,CAAC,IAAI;IAiBnB,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU;IAIlE,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU;IAIlE,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU;IAIlE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU;IAIhE;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM;CAaxB"}

package/dist/modules/Window.js

@@ -1,38 +1,41 @@
 /**
- * 点POI打开外部弹窗
- * 用来让UE抛出POI位置
+ * 弹框：三维内置弹框或外部弹框（返回屏幕坐标比例供前端自绘，可随锚点移动）。
+ * 内置样式需按项目单独开发，本包只负责协议与发送。
  */
-import { Action, } from "./Action";
+import { Action } from "./Action";
 export class WindowAction extends Action {
-    /**
-      * 打开外部弹窗
-      * @param {*} attendId (必须）弹框的三维物体的唯一ID)
-      */
-    static openOut(attendId) {
-        const param = {
-            cmd: "window",
-            data: {
-                action: 'pop',
-                type: 'builtOut',
-                attendId,
-            }
+    static crud(action, popType, windowInfo, log) {
+        const data = {
+            action,
+            popType,
+            windowInfo
         };
-        this.sendParam(param, '打开外部弹窗');
+        return this.sendParam({ cmd: "window", data }, log);
+    }
+    static createWindow(popType, windowInfo) {
+        return this.crud("create", popType, windowInfo, `弹框创建 - ${popType}`);
+    }
+    static removeWindow(popType, windowInfo) {
+        return this.crud("remove", popType, windowInfo, `弹框移除 - ${popType}`);
+    }
+    static updateWindow(popType, windowInfo) {
+        return this.crud("update", popType, windowInfo, `弹框更新 - ${popType}`);
+    }
+    static moveWindow(popType, windowInfo) {
+        return this.crud("move", popType, windowInfo, `弹框移动 - ${popType}`);
     }
     /**
-     * 关闭外部弹窗
-     * @param {*} attendId (必须）弹框的三维物体的唯一ID)
+     * 查询弹框详情（按设备类型、设备 id、场景）
+     * @param senceCode 协议字段名与 sceneCode 拼写不一致，与三维约定保持一致
      */
-    static closeOut(attendId) {
-        const param = {
-            cmd: "window",
-            data: {
-                action: 'remove',
-                type: 'builtOut',
-                attendId,
-            }
+    static getWindowDetails(type, id, senceCode) {
+        const data = {
+            action: "getWindowDetails",
+            type,
+            id,
+            senceCode
         };
-        this.sendParam(param, '关闭外部弹窗');
+        return this.sendParam({ cmd: "window", data }, `获取弹框详情 - type: ${type} id: ${id}`);
     }
 }
 //# sourceMappingURL=Window.js.map

package/dist/modules/Window.js.map

@@ -1 +1 @@
-{"version":3,"file":"Window.js","sourceRoot":"","sources":["../../src/modules/Window.ts"],"names":[],"mappings":"AACA;;;GAGG;AACH,OAAO,EAAE,MAAM,GAAG,MAAM,UAAU,CAAC;AAEnC,MAAM,OAAO,YAAa,SAAQ,MAAM;IACpC;;;QAGI;IACJ,MAAM,CAAC,OAAO,CAAC,QAAgB;QAC3B,MAAM,KAAK,GAAQ;YACf,GAAG,EAAE,QAAQ;YACb,IAAI,EAAE;gBACF,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,UAAU;gBAChB,QAAQ;aACX;SACJ,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACnC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAgB;QAC5B,MAAM,KAAK,GAAQ;YACf,GAAG,EAAE,QAAQ;YACb,IAAI,EAAE;gBACF,MAAM,EAAE,QAAQ;gBAChB,IAAI,EAAE,UAAU;gBAChB,QAAQ;aACX;SACJ,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IACnC,CAAC;CACJ"}
+{"version":3,"file":"Window.js","sourceRoot":"","sources":["../../src/modules/Window.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAa,MAAM,UAAU,CAAC;AAqE7C,MAAM,OAAO,YAAa,SAAQ,MAAM;IAC5B,MAAM,CAAC,IAAI,CACf,MAAwB,EACxB,OAAsB,EACtB,UAAsB,EACtB,GAAW;QAEX,MAAM,IAAI,GAAyD;YAC/D,MAAM;YACN,OAAO;YACP,UAAU;SACb,CAAC;QACF,OAAO,IAAI,CAAC,SAAS,CACjB,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAqB,EAC1C,GAAG,CACN,CAAC;IACN,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAAsB,EAAE,UAAsB;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAAsB,EAAE,UAAsB;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAAsB,EAAE,UAAsB;QAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,OAAsB,EAAE,UAAsB;QAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CACnB,IAAY,EACZ,EAAU,EACV,SAAiB;QAEjB,MAAM,IAAI,GAA2D;YACjE,MAAM,EAAE,kBAAkB;YAC1B,IAAI;YACJ,EAAE;YACF,SAAS;SACZ,CAAC;QACF,OAAO,IAAI,CAAC,SAAS,CACjB,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAqB,EAC1C,kBAAkB,IAAI,QAAQ,EAAE,EAAE,CACrC,CAAC;IACN,CAAC;CACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-action",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "与三维交互api",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -8,9 +8,42 @@ export { StatusAction } from './modules/Status'
 export { CameraViewAction } from './modules/CameraView'
 export { FocusAction } from './modules/Focus'
 export { SceneAction } from './modules/Scene'
+export { SceneAssetAction } from './modules/SceneAsset'
 export { GameModeAction } from './modules/GameMode'
 export { AnimationAction } from './modules/Animation'
 export { EffectAction } from './modules/Effect'
 export { InitAction } from './modules/Init'
 export { VideoFusionAction } from './modules/VideoFusion'
+export { WindowAction } from './modules/Window'
+export { SingleMeshAction } from './modules/SingleMesh'
+export type {
+    SceneAssetActionType,
+    SceneAssetType,
+    RoomMapLocationParam,
+    PoiMapLocationParam,
+    SceneAssetMapLocationPayload,
+    SceneAssetPayload,
+    SceneAssetOnAssetSelectedData,
+    SceneAssetOnEditAssetData,
+    SceneAssetPushData,
+    SceneAssetPushMessage
+} from './modules/SceneAsset'
+export type {
+    WindowActionType,
+    WindowCrudAction,
+    WindowPopType,
+    WindowDetailRowType,
+    WindowDetailParam,
+    WindowInfo,
+    WindowPayload
+} from './modules/Window'
+export type {
+    SingleMeshOp,
+    SingleMeshSceneType,
+    SingleMeshDeviceModelType,
+    SingleMeshDeviceCategory,
+    SingleMeshDevice,
+    SingleMeshScene,
+    SingleMeshPayload
+} from './modules/SingleMesh'
 export type { InitVideoOptions } from './modules/Init'

package/src/modules/Action.ts

@@ -15,12 +15,21 @@ interface PendingRequest {
     timeout: ReturnType<typeof setTimeout>;
 }
 
+/** 三维大包分包：首包 -S、中间 -I、末包 -E，拼接后为完整 JSON 字符串（与未分包时一致） */
+interface ChunkAssembly {
+    buffer: string;
+    requestId: string | null;
+}
+
 export class Action {
     // 存储待处理的请求，key 为 requestId
     private static pendingRequests = new Map<string, PendingRequest>();
-    
+
+    /** 正在组装的分包（同一时间仅处理一条分包流；并行多条需三维在每段携带 requestId，见 tryExtractRequestId） */
+    private static chunkAssembly: ChunkAssembly | null = null;
+
     // 默认超时时间（毫秒）
-    private static defaultTimeout = 30000;
+    private static defaultTimeout = 10000;
 
     /**
      * 生成唯一请求ID
@@ -34,6 +43,85 @@ export class Action {
      * 注意：三维系统保证在响应中返回 requestId，因此通过 requestId 精确匹配请求
      * @param responseData 响应数据，必须包含 requestId 字段
      */
+    /**
+     * 从 JSON 片段中尽早解析 requestId（用于日志；分包并行时需首段或中段出现该字段）
+     */
+    private static tryExtractRequestId(jsonPrefix: string): string | null {
+        const m = jsonPrefix.match(/"requestId"\s*:\s*"([^"]+)"/);
+        return m ? m[1] : null;
+    }
+
+    /**
+     * 处理 peer-stream 收到的一条原始消息（支持未分包 JSON 与 -S/-I/-E 分包）
+     * @param raw 字符串：整段 JSON，或以 -S / -I / -E 开头的分包片段
+     * @param onMessage 与 Init 中一致的业务回调（收到完整一条 JSON 后调用一次）
+     */
+    static handleIncomingRawMessage(raw: string | object, onMessage?: (data: any) => void) {
+        if (typeof raw !== 'string') {
+            const data = raw as any;
+            this.handleResponse(data);
+            onMessage?.(data);
+            return;
+        }
+
+        const isChunk = raw.startsWith('-S') || raw.startsWith('-I') || raw.startsWith('-E');
+        if (!isChunk) {
+            let data: any;
+            try {
+                data = JSON.parse(raw);
+            } catch (e) {
+                console.error('解析消息失败:', e);
+                return;
+            }
+            this.handleResponse(data);
+            onMessage?.(data);
+            return;
+        }
+
+        const tag = raw.slice(0, 2);
+        const body = raw.slice(2);
+
+        if (tag === '-S') {
+            if (this.chunkAssembly) {
+                console.warn('分包消息: 收到新的 -S，丢弃未拼完的上一包');
+            }
+            this.chunkAssembly = { buffer: body, requestId: this.tryExtractRequestId(body) };
+            return;
+        }
+
+        if (tag === '-I') {
+            if (!this.chunkAssembly) {
+                console.error('分包消息: 收到 -I 但缺少前置 -S');
+                return;
+            }
+            this.chunkAssembly.buffer += body;
+            if (!this.chunkAssembly.requestId) {
+                this.chunkAssembly.requestId = this.tryExtractRequestId(this.chunkAssembly.buffer);
+            }
+            return;
+        }
+
+        if (tag === '-E') {
+            if (!this.chunkAssembly) {
+                console.error('分包消息: 收到 -E 但缺少前置 -S');
+                return;
+            }
+            this.chunkAssembly.buffer += body;
+            const fullJson = this.chunkAssembly.buffer;
+            this.chunkAssembly = null;
+
+            let data: any;
+            try {
+                data = JSON.parse(fullJson);
+            } catch (e) {
+                console.error('分包消息 JSON 解析失败:', e);
+                return;
+            }
+            this.handleResponse(data);
+            onMessage?.(data);
+        }
+    }
+
     static handleResponse(responseData: any) {
         // 通过 requestId 精确匹配请求（三维系统保证返回 requestId）
         if (responseData.requestId && this.pendingRequests.has(responseData.requestId)) {
@@ -52,20 +140,20 @@ export class Action {
 
     /**
      * 发送到model
-     * @param {SendParam} param 发送的参数
-     * @param {string} msg 打印的信息
-     * @param {number} timeout 超时时间（毫秒），默认 30 秒
-     * @returns {Promise<any>} 返回 Promise，在收到响应时 resolve
+     * @param param 发送的参数
+     * @param msg 打印的信息
+     * @param timeout 超时时间（毫秒），默认 10 秒
+     * @returns 收到响应时 resolve 为三维数据；超时时 resolve `{ timedOut: true, requestId }`（不 reject）
      */
     static sendParam<T extends SendParam>(
-        param: T, 
+        param: T,
         msg: string = '',
         timeout: number = this.defaultTimeout
     ): Promise<any> {
         return new Promise((resolve, reject) => {
             // 生成唯一请求ID
             const requestId = this.generateRequestId();
-            
+
             // 在请求参数中添加 requestId
             const paramWithId = {
                 ...param,
@@ -73,11 +161,11 @@ export class Action {
             };
 
             console.log(`发送给三维|${msg}`, JSON.stringify(paramWithId));
-            
-            // 创建超时定时器
+
             const timeoutHandle = setTimeout(() => {
                 this.pendingRequests.delete(requestId);
-                reject(new Error(`请求超时: ${msg}`));
+                console.warn(`请求等待超时(三维可能不返回): ${msg}`);
+                resolve({ timedOut: true, requestId });
             }, timeout);
 
             // 存储待处理的请求（通过 requestId 匹配）

package/src/modules/Init.ts

@@ -4,8 +4,6 @@
 import { Action } from "./Action";
 // 导入 peer-stream.js 以确保自定义元素在使用前被注册
 import "../peer-stream.js";
-import { VideoFusionAction } from "./VideoFusion";
-
 // 初始化配置选项
 export interface InitVideoOptions {
     /** 视频容器元素（DOM元素或ref） */
@@ -56,26 +54,14 @@ export class InitAction extends Action {
             ps.registerMouseHoverEvents();
         }
 
-        // 监听消息事件
-        if (options.onMessage) {
-            ps.addEventListener("message", (e: any) => {
-                try {
-                    const data = JSON.parse(e.detail);
-                    // 先处理 Promise 响应
-                    Action.handleResponse(data);
-                    // 然后调用用户自定义的回调
-                    options.onMessage!(data);
-                    //视频融合初始化的返回。我这里先自动处理一波，外面可以不处理了
-                    // if (data.code === '0' && data.cmd === 'videoFusion' && data.message.includes("初始化")) {
-                    //     //获取当前所有融合点位ID
-
-                    //     VideoFusionAction.get();
-                    // }
-                } catch (error) {
-                    console.error("解析消息失败:", error);
-                }
-            });
-        }
+        // 监听消息事件（含三维大包 -S/-I/-E 分包拼包后，再 handleResponse + onMessage）
+        ps.addEventListener("message", (e: any) => {
+            try {
+                Action.handleIncomingRawMessage(e.detail, options.onMessage);
+            } catch (error) {
+                console.error("解析消息失败:", error);
+            }
+        });
 
         // 监听元数据加载完成
         ps.addEventListener("loadedmetadata", () => {

package/src/modules/SceneAsset.ts

@@ -0,0 +1,242 @@
+/**
+ * 场景资产操作方法（上图、房间/资产与三维场景绑定等）
+ */
+import { Action, SendParam } from "./Action";
+
+/** 前端发往三维的 action */
+export type SceneAssetActionType =
+    | "mapLocation"
+    | "editSave"
+    | "editCancel"
+    | "disableSceneEdit";
+
+/** 资产大类：房间、POI 等 */
+export type SceneAssetType = "Room" | "POI" | string;
+
+/** 地图定位 — 房间在单层下的条目 */
+export interface RoomMapLocationParam {
+    /** 房间等业务唯一标识，必须 */
+    id: string;
+    /** 三维场景内唯一 id，初始可空，上图后由三维回写 */
+    sceneId?: string;
+    /** 展示名称，必须 */
+    name: string;
+    /** 如 `X=0.0,Y=0.0,Z=0.0`；空或省略则使用楼层分层默认定位 */
+    location?: string;
+    description?: string;
+    /** 是否已上图；也可由后台根据坐标是否为空推断 */
+    alreadyMap?: boolean;
+}
+
+/** POI 打点 — 单条参数（与 Room 的 params 结构不同） */
+export interface PoiMapLocationParam {
+    /** POI 子类型，用于区分展示样式，如 Camera */
+    type: string;
+    /** 非必须；前端有唯一值可传给三维，否则由三维生成并回传 */
+    sceneId?: string;
+    /** 业务关联 ID，必须 */
+    linkId: string;
+    /** 有则建议传入 */
+    name?: string;
+    /** 非必须；不传时三维可取当前鼠标在场景中的坐标 */
+    location?: string;
+}
+
+export type SceneAssetMapLocationPayload =
+    | {
+          action: "mapLocation";
+          type: "Room";
+          buildingId: string;
+          floor: string;
+          params: RoomMapLocationParam[];
+      }
+    | {
+          action: "mapLocation";
+          type: "POI";
+          /** 不传或空：室外打点；传入时三维会与当前分层校验 */
+          buildingId?: string;
+          floor?: string;
+          params: PoiMapLocationParam[];
+      };
+
+export type SceneAssetPayload =
+    | SceneAssetMapLocationPayload
+    | {
+          action: "editSave";
+          type: SceneAssetType;
+          /** 三维返回的 sceneId */
+          id: string;
+      }
+    | {
+          action: "editCancel";
+          type: SceneAssetType;
+          id: string;
+      }
+    | {
+          action: "disableSceneEdit";
+      };
+
+/** 三维推送：编辑模式下选中资产，前端可据此弹出编辑框 */
+export interface SceneAssetOnAssetSelectedData {
+    action: "OnAssetSelected";
+    type: SceneAssetType;
+    /** POI 场景下为前端下发的 linkId */
+    id: string;
+    /** 三维生成的唯一 id，需入库 */
+    sceneId: string;
+    /** POI 所在位置描述，需入库与三维一致 */
+    place?: string;
+    location: string;
+}
+
+/** 三维推送：单个资产修改后的结果 */
+export interface SceneAssetOnEditAssetData {
+    action: "OnEditAsset";
+    type: SceneAssetType;
+    id: string;
+    sceneId: string;
+    location: string;
+}
+
+export type SceneAssetPushData =
+    | SceneAssetOnAssetSelectedData
+    | SceneAssetOnEditAssetData;
+
+/** 三维经 sceneAsset 推送的通用消息壳（无 requestId） */
+export interface SceneAssetPushMessage<
+    T extends SceneAssetPushData = SceneAssetPushData
+> {
+    code: string;
+    message: string;
+    cmd: "sceneAsset";
+    data: T;
+}
+
+type SceneAssetParamType = SendParam & {
+    cmd: "sceneAsset";
+    data: SceneAssetPayload;
+};
+
+function appendPoiBuildingFloor(
+    data: Extract<SceneAssetMapLocationPayload, { type: "POI" }>,
+    buildingId?: string,
+    floor?: string
+) {
+    const b = buildingId?.trim();
+    const f = floor?.trim();
+    if (b) data.buildingId = b;
+    if (f) data.floor = f;
+}
+
+export class SceneAssetAction extends Action {
+    /**
+     * 房间等在指定建筑、楼层上地图定位（上图）
+     * @param buildingId 建筑唯一 ID
+     * @param floor 楼层，如 1F、B1
+     */
+    static mapRoomLocation(
+        buildingId: string,
+        floor: string,
+        params: RoomMapLocationParam[]
+    ) {
+        const data: Extract<SceneAssetMapLocationPayload, { type: "Room" }> = {
+            action: "mapLocation",
+            type: "Room",
+            buildingId,
+            floor,
+            params
+        };
+
+        const sendParam: SceneAssetParamType = {
+            cmd: "sceneAsset",
+            data
+        };
+        return this.sendParam(
+            sendParam,
+            `场景资产房间上图 - buildingId: ${buildingId} floor: ${floor}`
+        );
+    }
+
+    /**
+     * POI 打点上图。不传 `buildingId`、`floor`（或仅空白）视为室外；
+     * 传入时三维会与当前分层匹配，不匹配则打点失败，前端需提示先分层到目标楼层。
+     */
+    static mapPoiLocation(
+        params: PoiMapLocationParam[],
+        buildingId?: string,
+        floor?: string
+    ) {
+        const data: Extract<SceneAssetMapLocationPayload, { type: "POI" }> = {
+            action: "mapLocation",
+            type: "POI",
+            params
+        };
+        appendPoiBuildingFloor(data, buildingId, floor);
+
+        const sendParam: SceneAssetParamType = {
+            cmd: "sceneAsset",
+            data
+        };
+        const scope =
+            buildingId?.trim() && floor?.trim()
+                ? `buildingId: ${buildingId} floor: ${floor}`
+                : "室外";
+        return this.sendParam(sendParam, `场景资产 POI 上图 - ${scope}`);
+    }
+
+    /**
+     * 前端编辑框「保存」后通知三维
+     * @param id 三维返回的 sceneId
+     */
+    static editSave(id: string, type: SceneAssetType = "Room") {
+        const data: Extract<SceneAssetPayload, { action: "editSave" }> = {
+            action: "editSave",
+            type,
+            id
+        };
+
+        const sendParam: SceneAssetParamType = {
+            cmd: "sceneAsset",
+            data
+        };
+        return this.sendParam(
+            sendParam,
+            `场景资产编辑保存 - ${type} sceneId: ${id}`
+        );
+    }
+
+    /**
+     * 前端编辑框「取消」后通知三维
+     * @param id 三维返回的 sceneId
+     */
+    static editCancel(id: string, type: SceneAssetType = "Room") {
+        const data: Extract<SceneAssetPayload, { action: "editCancel" }> = {
+            action: "editCancel",
+            type,
+            id
+        };
+
+        const sendParam: SceneAssetParamType = {
+            cmd: "sceneAsset",
+            data
+        };
+        return this.sendParam(
+            sendParam,
+            `场景资产编辑取消 - ${type} sceneId: ${id}`
+        );
+    }
+
+    /** 退出整个资产管理编辑模块 */
+    static disableSceneEdit() {
+        const data: Extract<SceneAssetPayload, { action: "disableSceneEdit" }> =
+            {
+                action: "disableSceneEdit"
+            };
+
+        const sendParam: SceneAssetParamType = {
+            cmd: "sceneAsset",
+            data
+        };
+        return this.sendParam(sendParam, "退出场景资产编辑模块");
+    }
+}