@ray-js/robot-data-stream 0.0.15-beta.8 → 0.0.16-beta.1

package/lib/mqtt/type/protocols/zoneCleanProtocol.js

@@ -1,5 +1,7 @@
 import * as z from '../../../myLib/zod/mini';
+import { MqttError } from '../../promise';
 import { BaseResponseSchema, Point } from './base';
+const VALIDATION_ERROR_CODE = -2;
 const zoneSchema = z.object({
   // 区域点集
   points: z.array(Point),
@@ -20,10 +22,12 @@ export const setZoneCleanSchema = z.object({
   zones: z.array(zoneSchema),
   origin: Point,
   suctions: z.optional(z.array(z.string())),
-  cisterns: z.optional(z.array(z.string())),
+  cisterns: z.optional(z.array(z.union([z.string(), z.number()]))),
+  waterValues: z.optional(z.array(z.union([z.string(), z.number()]))),
   cleanCounts: z.optional(z.array(z.int())),
   yMops: z.optional(z.array(z.int())),
-  sweepMopModes: z.optional(z.array(z.string()))
+  sweepMopModes: z.optional(z.array(z.string())),
+  routePreferences: z.optional(z.array(z.string()))
 });
 
 // 划区清扫响应 Schema
@@ -35,15 +39,38 @@ const setZoneCleanResponseSchema = z.extend(BaseResponseSchema, {
   // 吸力， closed - 关闭 gentle - 安静 normal - 正常 strong - 强劲 max - 超强 ，默认值为''
   suctions: z.optional(z.array(z.string())),
   // 拖地水量 "closed"- 关闭,"low"-低,"middle"-中,"high"-高,默认值为''
-  cisterns: z.optional(z.array(z.string())),
+  cisterns: z.optional(z.array(z.union([z.string(), z.number()]))),
+  // 自定义拖地水量
+  waterValues: z.optional(z.array(z.union([z.string(), z.number()]))),
   // 清扫次数 默认值1
   cleanCounts: z.optional(z.array(z.int())),
   // 拖地模式 1:开启Y型拖地 0:关闭Y型拖地  -1 未设置 默认值-1
   yMops: z.optional(z.array(z.int())),
   // 扫拖模式 "only_sweep":仅扫,"only_mop"：仅拖,"both_work"：扫拖同时,"clean_before_mop"：先扫后拖，默认值为'only_sweep'
-  sweepMopModes: z.optional(z.array(z.string()))
+  sweepMopModes: z.optional(z.array(z.string())),
+  // 路线偏好
+  routePreferences: z.optional(z.array(z.string()))
 });
 
 // 类型导出
 
+export function validateSetZoneClean(data) {
+  const num = data.zones.length;
+  const validateLength = (name, value) => {
+    if (value && value.length !== num) {
+      throw new MqttError(`${name} length must be ${num}, actual is ${value.length}`, {
+        errCode: VALIDATION_ERROR_CODE,
+        reqType: 'set_zone_clean'
+      });
+    }
+  };
+  validateLength('suctions', data.suctions);
+  validateLength('cisterns', data.cisterns);
+  validateLength('waterValues', data.waterValues);
+  validateLength('cleanCounts', data.cleanCounts);
+  validateLength('yMops', data.yMops);
+  validateLength('sweepMopModes', data.sweepMopModes);
+  validateLength('routePreferences', data.routePreferences);
+}
+
 // 函数类型定义

package/lib/mqtt/useRoomProperty.js

@@ -1,8 +1,10 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import { useContext } from 'react';
 import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
 import { SingletonContext } from './mqttProvider';
 import { RoomPropertyEnum } from './type';
 import { validator } from './type/fun';
+import { normalizeWaterPreferencePayload } from './waterPreference';
 /**
  * 自定义 Hook，用于房间属性管理
  * @param devId 设备ID（可选，如果不提供则从 MqttProvider Context 获取）
@@ -45,7 +47,7 @@ export const useRoomProperty = () => {
     setRoomProperty: data => {
       return new Promise((resolve, reject) => {
         try {
-          var _data$num, _data$suctions, _data$cisterns, _data$cleanCounts, _data$yMops, _data$sweepMopModes, _data$names;
+          var _data$num, _data$suctions, _data$cleanCounts, _data$yMops, _data$sweepMopModes, _data$names, _data$routePreference;
           if (!useMqtt) {
             reject(new Error('useMqtt is not used'));
             return;
@@ -56,18 +58,19 @@ export const useRoomProperty = () => {
             ids
           } = data;
           const len = ids.length;
-          const sendData = {
+          const sendData = _objectSpread({
             num: (_data$num = data.num) !== null && _data$num !== void 0 ? _data$num : len,
             ids,
             suctions: (_data$suctions = data.suctions) !== null && _data$suctions !== void 0 ? _data$suctions : new Array(len).fill('closed'),
-            cisterns: (_data$cisterns = data.cisterns) !== null && _data$cisterns !== void 0 ? _data$cisterns : new Array(len).fill('closed'),
             cleanCounts: (_data$cleanCounts = data.cleanCounts) !== null && _data$cleanCounts !== void 0 ? _data$cleanCounts : new Array(len).fill(1),
             yMops: (_data$yMops = data.yMops) !== null && _data$yMops !== void 0 ? _data$yMops : new Array(len).fill(-1),
             sweepMopModes: (_data$sweepMopModes = data.sweepMopModes) !== null && _data$sweepMopModes !== void 0 ? _data$sweepMopModes : new Array(len).fill('only_sweep'),
             names: (_data$names = data.names) !== null && _data$names !== void 0 ? _data$names : new Array(len).fill(''),
+            nameLabels: data.nameLabels,
             floorTypes: data.floorTypes,
-            orders: data.orders
-          };
+            orders: data.orders,
+            routePreferences: (_data$routePreference = data.routePreferences) !== null && _data$routePreference !== void 0 ? _data$routePreference : new Array(len).fill('standard')
+          }, normalizeWaterPreferencePayload(data.cisterns, data.waterValues));
 
           // 使用 TypeBox Schema 进行参数验证（包含自定义验证逻辑）
           const validatedData = validator.validate('set_room_property', sendData);

package/lib/mqtt/useSchedule.js

@@ -1,8 +1,10 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.map.js";
 // 定时
 import { encodeDeviceTimer0x30 } from '@ray-js/robot-protocol';
 import { useContext } from 'react';
-import { CISTERN_MAP, CLEAN_MODE_MAP, SUCTION_MAP } from '../constant';
+import { CLEAN_MODE_MAP, SUCTION_MAP, ROUTE_PREFERENCE_MAP } from '../constant';
+import { normalizeWaterPreferencePayload, resolveWaterLevel } from './waterPreference';
 import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMessage';
 import { SingletonContext } from './mqttProvider';
 import { ScheduleEnum } from './type';
@@ -53,8 +55,16 @@ export const useSchedule = () => {
         try {
           // 使用 TypeBox Schema 进行参数验证
           const validatedData = validator.validate('set_schedule', message);
+          const list = validatedData.list.map(item => {
+            var _item$routePreference, _item$ids;
+            return _objectSpread(_objectSpread(_objectSpread({}, item), normalizeWaterPreferencePayload(item.cisterns, item.waterValues)), {}, {
+              routePreferences: (_item$routePreference = item.routePreferences) !== null && _item$routePreference !== void 0 ? _item$routePreference : new Array(((_item$ids = item.ids) === null || _item$ids === void 0 ? void 0 : _item$ids.length) || 1).fill('standard')
+            });
+          });
           if (useMqtt) {
-            sendStructuredMessage(ScheduleEnum.set, validatedData, resolve, error => reject(handleMqttError(error, 'Failed to set schedule')), ScheduleEnum.query // 响应类型是 query，不是 set
+            sendStructuredMessage(ScheduleEnum.set, _objectSpread(_objectSpread({}, validatedData), {}, {
+              list
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set schedule')), ScheduleEnum.query // 响应类型是 query，不是 set
             );
             return;
           }
@@ -63,7 +73,7 @@ export const useSchedule = () => {
           const command = encodeDeviceTimer0x30({
             version: commandVersion,
             number: validatedData.num,
-            list: validatedData.list.map(_ref => {
+            list: list.map(_ref => {
               let {
                 active,
                 suctions,
@@ -72,13 +82,15 @@ export const useSchedule = () => {
                 cleanCounts,
                 cycle,
                 cisterns,
-                time
+                waterValues,
+                time,
+                routePreferences
               } = _ref;
               return {
                 effectiveness: active,
                 cleanMode: CLEAN_MODE_MAP[(sweepMopModes === null || sweepMopModes === void 0 ? void 0 : sweepMopModes[0]) || ''],
                 fanLevel: SUCTION_MAP[(suctions === null || suctions === void 0 ? void 0 : suctions[0]) || ''],
-                waterLevel: CISTERN_MAP[(cisterns === null || cisterns === void 0 ? void 0 : cisterns[0]) || ''],
+                waterLevel: resolveWaterLevel(waterValues === null || waterValues === void 0 ? void 0 : waterValues[0], cisterns === null || cisterns === void 0 ? void 0 : cisterns[0]),
                 time: {
                   hour: time[0],
                   minute: time[1]
@@ -86,7 +98,8 @@ export const useSchedule = () => {
                 week: cycle,
                 sweepCount: (cleanCounts === null || cleanCounts === void 0 ? void 0 : cleanCounts[0]) || 1,
                 roomIds: ids || [],
-                roomNum: (ids === null || ids === void 0 ? void 0 : ids.length) || 0
+                roomNum: (ids === null || ids === void 0 ? void 0 : ids.length) || 0,
+                routePreference: ROUTE_PREFERENCE_MAP[(routePreferences === null || routePreferences === void 0 ? void 0 : routePreferences[0]) || 'standard']
               };
             })
           });
@@ -97,7 +110,7 @@ export const useSchedule = () => {
             reqType: ScheduleEnum.query,
             version: commandVersion,
             taskId: `${Date.now()}`,
-            list: validatedData.list,
+            list,
             num: validatedData.num
           });
         } catch (error) {

package/lib/mqtt/useSelectRoomClean.js

@@ -1,3 +1,4 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.constructor.js";
 import "core-js/modules/esnext.iterator.for-each.js";
 import "core-js/modules/esnext.iterator.map.js";
@@ -8,6 +9,7 @@ import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMess
 import { SingletonContext } from './mqttProvider';
 import { RoomCleanSetEnum } from './type';
 import { validator } from './type/fun';
+import { normalizeWaterPreferencePayload } from './waterPreference';
 /**
  * 自定义 Hook，用于选区清扫
  * @returns 包含 requestSelectRoomClean 和 setRoomClean 函数的对象
@@ -59,9 +61,11 @@ export const useSelectRoomClean = () => {
             ids: [],
             suctions: [],
             cisterns: [],
+            waterValues: [],
             cleanCounts: [],
             yMops: [],
-            sweepMopModes: []
+            sweepMopModes: [],
+            routePreferences: []
           });
         } catch (error) {
           reject(handleMqttError(error, 'Failed to request select room clean'));
@@ -77,28 +81,36 @@ export const useSelectRoomClean = () => {
           if (useMqtt) {
             const ids = [];
             const suctions = [];
-            const cisterns = [];
             const cleanCounts = [];
             const yMops = [];
             const sweepMopModes = [];
+            const routePreferences = [];
             rooms.forEach(room => {
-              var _room$suction, _room$cleanTimes, _room$yMop, _room$sweepMopMode;
+              var _room$suction, _room$cleanTimes, _room$yMop, _room$sweepMopMode, _room$routePreference;
               ids.push(room.roomId);
               suctions.push((_room$suction = room.suction) !== null && _room$suction !== void 0 ? _room$suction : '');
-              cisterns.push(room.cistern);
               cleanCounts.push((_room$cleanTimes = room.cleanTimes) !== null && _room$cleanTimes !== void 0 ? _room$cleanTimes : 1);
               yMops.push((_room$yMop = room.yMop) !== null && _room$yMop !== void 0 ? _room$yMop : -1);
               sweepMopModes.push((_room$sweepMopMode = room.sweepMopMode) !== null && _room$sweepMopMode !== void 0 ? _room$sweepMopMode : 'only_sweep');
+              routePreferences.push((_room$routePreference = room.routePreference) !== null && _room$routePreference !== void 0 ? _room$routePreference : 'standard');
             });
-            sendStructuredMessage(RoomCleanSetEnum.set, {
+            const waterPayload = normalizeWaterPreferencePayload(rooms.map(room => {
+              var _room$cistern;
+              return (_room$cistern = room.cistern) !== null && _room$cistern !== void 0 ? _room$cistern : '';
+            }), rooms.map(room => {
+              var _room$waterValue;
+              return (_room$waterValue = room.waterValue) !== null && _room$waterValue !== void 0 ? _room$waterValue : '';
+            }));
+            sendStructuredMessage(RoomCleanSetEnum.set, _objectSpread(_objectSpread({
               ids,
-              suctions,
-              cisterns,
+              suctions
+            }, waterPayload), {}, {
               cleanCounts,
               yMops,
               sweepMopModes,
+              routePreferences,
               num: rooms.length
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set room clean')), RoomCleanSetEnum.query // 响应类型是 query，不是 set
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set room clean')), RoomCleanSetEnum.query // 响应类型是 query，不是 set
             );
             return;
           }
@@ -115,7 +127,13 @@ export const useSelectRoomClean = () => {
             var _room$suction2;
             return (_room$suction2 = room.suction) !== null && _room$suction2 !== void 0 ? _room$suction2 : '';
           });
-          const cisterns = rooms.map(room => room.cistern);
+          const waterPayload = normalizeWaterPreferencePayload(rooms.map(room => {
+            var _room$cistern2;
+            return (_room$cistern2 = room.cistern) !== null && _room$cistern2 !== void 0 ? _room$cistern2 : '';
+          }), rooms.map(room => {
+            var _room$waterValue2;
+            return (_room$waterValue2 = room.waterValue) !== null && _room$waterValue2 !== void 0 ? _room$waterValue2 : '';
+          }));
           const cleanCounts = rooms.map(room => {
             var _room$cleanTimes2;
             return (_room$cleanTimes2 = room.cleanTimes) !== null && _room$cleanTimes2 !== void 0 ? _room$cleanTimes2 : 1;
@@ -128,19 +146,24 @@ export const useSelectRoomClean = () => {
             var _room$sweepMopMode2;
             return (_room$sweepMopMode2 = room.sweepMopMode) !== null && _room$sweepMopMode2 !== void 0 ? _room$sweepMopMode2 : 'only_sweep';
           });
-          resolve({
+          const routePreferences = rooms.map(room => {
+            var _room$routePreference2;
+            return (_room$routePreference2 = room.routePreference) !== null && _room$routePreference2 !== void 0 ? _room$routePreference2 : 'standard';
+          });
+          resolve(_objectSpread(_objectSpread({
             success: true,
             errCode: 0,
             reqType: RoomCleanSetEnum.query,
             version: commandVersion,
             taskId: `${Date.now()}`,
             ids,
-            suctions,
-            cisterns,
+            suctions
+          }, waterPayload), {}, {
             cleanCounts,
             yMops,
-            sweepMopModes
-          });
+            sweepMopModes,
+            routePreferences
+          }));
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set room clean'));
         }

package/lib/mqtt/useSpotClean.js

@@ -1,3 +1,4 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.map.js";
 // 定点清扫
 
@@ -8,6 +9,7 @@ import { encodeSpotClean0x16 } from '@ray-js/robot-protocol';
 import { pointsToString } from '../utils';
 import { useStructuredMessage, handleMqttError } from './hooks/useStructuredMessage';
 import { validator } from './type/fun';
+import { normalizeWaterPreferencePayload } from './waterPreference';
 /**
  * 自定义 Hook，用于定点清扫
  * @returns 包含 requestSpotClean 和 setSpotClean 函数的对象
@@ -57,25 +59,30 @@ export const useSpotClean = () => {
             origin
           } = validatedData;
           const num = spots.length;
+          const waterPayload = normalizeWaterPreferencePayload(validatedData.cisterns, validatedData.waterValues);
 
           // 为可选字段设置默认值
           const {
             suctions = new Array(num).fill(''),
-            cisterns = new Array(num).fill(''),
             cleanCounts = new Array(num).fill(1),
             yMops = new Array(num).fill(-1),
-            sweepMopModes = new Array(num).fill('only_sweep')
+            sweepMopModes = new Array(num).fill('only_sweep'),
+            routePreferences = new Array(num).fill('standard'),
+            names
           } = validatedData;
           if (useMqtt) {
-            sendStructuredMessage(SpotCleanEnum.set, {
+            sendStructuredMessage(SpotCleanEnum.set, _objectSpread(_objectSpread({
               num,
               polygons: spots.map(spot => pointsToString([spot], origin)),
-              suctions,
-              cisterns,
+              suctions
+            }, waterPayload), {}, {
               cleanCounts,
               yMops,
-              sweepMopModes
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set spot clean')), SpotCleanEnum.query // 响应类型是 query，不是 set
+              sweepMopModes,
+              routePreferences
+            }, names && {
+              names
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set spot clean')), SpotCleanEnum.query // 响应类型是 query，不是 set
             );
             return;
           }
@@ -87,19 +94,22 @@ export const useSpotClean = () => {
             point: spots[0]
           });
           devices.common.model.actions.command_trans.set(command);
-          resolve({
+          resolve(_objectSpread(_objectSpread({
             success: true,
             errCode: 0,
             reqType: SpotCleanEnum.query,
             version: commandVersion,
             taskId: `${Date.now()}`,
             polygons: spots.map(spot => pointsToString([spot], origin)),
-            suctions,
-            cisterns,
+            suctions
+          }, waterPayload), {}, {
             cleanCounts,
             yMops,
-            sweepMopModes
-          });
+            sweepMopModes,
+            routePreferences
+          }, names && {
+            names
+          }));
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set spot clean'));
         }

package/lib/mqtt/useWifiMap.js

@@ -18,7 +18,7 @@ export const useWifiMap = () => {
 
   /**
    * 设置 WiFi 地图
-   * @param data 包含 taskId 的参数对象（taskId 可选，不提供时自动生成）
+   * @param data 包含 taskId 的参数对象（taskId 可选，不提供时自动生成，switch 可选，默认）
    * @returns Promise<WifiMapResponse> 响应结果
    */
 
@@ -36,9 +36,11 @@ export const useWifiMap = () => {
       let data = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
       return new Promise((resolve, reject) => {
         try {
+          var _data$switch;
           // 如果没有提供 taskId，自动生成
           const wifiMapData = {
-            taskId: data.taskId || String(Date.now())
+            taskId: data.taskId || String(Date.now()),
+            switch: (_data$switch = data.switch) !== null && _data$switch !== void 0 ? _data$switch : true
           };
 
           // 使用 TypeBox Schema 进行参数验证

package/lib/mqtt/useZoneClean.js

@@ -1,3 +1,4 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
 import "core-js/modules/esnext.iterator.map.js";
 // 划区清扫
 import { encodeZoneClean0x3a, requestZoneClean0x3b } from '@ray-js/robot-protocol';
@@ -7,6 +8,7 @@ import { handleMqttError, useStructuredMessage } from './hooks/useStructuredMess
 import { SingletonContext } from './mqttProvider';
 import { ZoneCleanEnum } from './type';
 import { validator } from './type/fun';
+import { normalizeWaterPreferencePayload } from './waterPreference';
 /**
  * 自定义 Hook，用于划区清扫
  * @returns 包含 requestZoneClean 和 setZoneClean 函数的对象
@@ -73,16 +75,15 @@ export const useZoneClean = () => {
 
           // 将业务参数转换为协议数据格式
           const num = zones.length;
+          const waterPayload = normalizeWaterPreferencePayload(params.cisterns, params.waterValues);
           const {
             suctions = new Array(num).fill(''),
-            cisterns = new Array(num).fill(''),
             cleanCounts = new Array(num).fill(1),
             yMops = new Array(num).fill(-1),
-            sweepMopModes = new Array(num).fill('only_sweep')
+            sweepMopModes = new Array(num).fill('only_sweep'),
+            routePreferences = new Array(num).fill('standard')
           } = params;
-
-          // 构建符合 SetZoneCleanData 格式的数据
-          const zoneCleanData = {
+          const zoneCleanData = _objectSpread(_objectSpread({
             zones: zones.map(_ref => {
               let {
                 points,
@@ -96,41 +97,44 @@ export const useZoneClean = () => {
               };
             }),
             origin,
-            suctions,
-            cisterns,
+            suctions
+          }, waterPayload), {}, {
             cleanCounts,
             yMops,
-            sweepMopModes
-          };
+            sweepMopModes,
+            routePreferences
+          });
 
           // 使用 TypeBox Schema 进行参数验证
           const validatedData = validator.validate('set_zone_clean', zoneCleanData);
+          const polygons = zones.map(_ref2 => {
+            let {
+              points
+            } = _ref2;
+            return pointsToString(points, origin);
+          });
+          const names = zones.map(_ref3 => {
+            let {
+              name
+            } = _ref3;
+            return name || '';
+          });
+          const commonFields = _objectSpread(_objectSpread({
+            suctions: validatedData.suctions
+          }, waterPayload), {}, {
+            cleanCounts: validatedData.cleanCounts,
+            yMops: validatedData.yMops,
+            sweepMopModes: validatedData.sweepMopModes,
+            routePreferences: validatedData.routePreferences
+          });
           if (useMqtt) {
-            // 将 zones 转换为 polygons 字符串格式（用于 MQTT 消息）
-            const polygons = zones.map(_ref2 => {
-              let {
-                points
-              } = _ref2;
-              return pointsToString(points, origin);
-            });
-            const names = zones.map(_ref3 => {
-              let {
-                name
-              } = _ref3;
-              return name || '';
-            });
-            sendStructuredMessage(ZoneCleanEnum.set, {
-              num: zones.length,
+            sendStructuredMessage(ZoneCleanEnum.set, _objectSpread(_objectSpread({
+              num,
               switchGo: true,
-              polygons,
-              suctions: validatedData.suctions,
-              cisterns: validatedData.cisterns,
-              cleanCounts: validatedData.cleanCounts,
-              yMops: validatedData.yMops,
-              sweepMopModes: validatedData.sweepMopModes,
+              polygons
+            }, commonFields), {}, {
               names
-            }, resolve, error => reject(handleMqttError(error, 'Failed to set zone clean')), ZoneCleanEnum.query // 响应类型是 query，不是 set
-            );
+            }), resolve, error => reject(handleMqttError(error, 'Failed to set zone clean')), ZoneCleanEnum.query);
             return;
           }
 
@@ -146,19 +150,7 @@ export const useZoneClean = () => {
             }))
           });
           devices.common.model.actions.command_trans.set(command);
-          const polygons = zones.map(_ref4 => {
-            let {
-              points
-            } = _ref4;
-            return pointsToString(points, origin);
-          });
-          const names = zones.map(_ref5 => {
-            let {
-              name
-            } = _ref5;
-            return name || '';
-          });
-          resolve({
+          resolve(_objectSpread({
             success: true,
             errCode: 0,
             reqType: ZoneCleanEnum.query,
@@ -166,7 +158,7 @@ export const useZoneClean = () => {
             taskId: `${Date.now()}`,
             polygons,
             names
-          });
+          }, commonFields));
         } catch (error) {
           reject(handleMqttError(error, 'Failed to set zone clean'));
         }

package/lib/mqtt/waterPreference.d.ts

@@ -0,0 +1,20 @@
+export type WaterPreferenceValue = string | number;
+/**
+ * 将自定义水量 / 标准水量统一归一化为设备命令需要的数值。
+ * 优先使用 waterValue，其次回退到 cistern。
+ */
+export declare const resolveWaterLevel: (waterValue?: WaterPreferenceValue, cistern?: WaterPreferenceValue, fallback?: number) => number;
+export declare const hasPreferenceValue: (value?: WaterPreferenceValue | null) => boolean;
+/**
+ * MQTT 水量相关字段是可选的。
+ * 当数组里全是空字符串时，认为该字段未设置，避免把空 cisterns/waterValues 发给设备。
+ */
+export declare const normalizeOptionalPreferenceArray: <T extends WaterPreferenceValue>(values?: T[] | undefined) => T[] | undefined;
+/**
+ * 自定义水量优先于旧 cistern 水量。
+ * 当某一项存在自定义水量时，同位置的 cistern 会被清空；最终空数组字段会被省略。
+ */
+export declare const normalizeWaterPreferencePayload: (cisterns?: WaterPreferenceValue[], waterValues?: WaterPreferenceValue[]) => {
+    cisterns?: WaterPreferenceValue[] | undefined;
+    waterValues?: WaterPreferenceValue[] | undefined;
+};

package/lib/mqtt/waterPreference.js

@@ -0,0 +1,70 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.some.js";
+import { CISTERN_MAP } from '../constant';
+/**
+ * 将自定义水量 / 标准水量统一归一化为设备命令需要的数值。
+ * 优先使用 waterValue，其次回退到 cistern。
+ */
+export const resolveWaterLevel = function (waterValue, cistern) {
+  var _ref, _resolveValue;
+  let fallback = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : CISTERN_MAP.closed;
+  const resolveValue = value => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+    if (value in CISTERN_MAP) {
+      return CISTERN_MAP[value];
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  };
+  return (_ref = (_resolveValue = resolveValue(waterValue)) !== null && _resolveValue !== void 0 ? _resolveValue : resolveValue(cistern)) !== null && _ref !== void 0 ? _ref : fallback;
+};
+export const hasPreferenceValue = value => value !== '' && value !== null && value !== undefined;
+
+/**
+ * MQTT 水量相关字段是可选的。
+ * 当数组里全是空字符串时，认为该字段未设置，避免把空 cisterns/waterValues 发给设备。
+ */
+export const normalizeOptionalPreferenceArray = values => {
+  if (!values) {
+    return undefined;
+  }
+  return values.some(hasPreferenceValue) ? values : undefined;
+};
+
+/**
+ * 自定义水量优先于旧 cistern 水量。
+ * 当某一项存在自定义水量时，同位置的 cistern 会被清空；最终空数组字段会被省略。
+ */
+export const normalizeWaterPreferencePayload = (cisterns, waterValues) => {
+  var _cisterns$length, _waterValues$length;
+  const maxLength = Math.max((_cisterns$length = cisterns === null || cisterns === void 0 ? void 0 : cisterns.length) !== null && _cisterns$length !== void 0 ? _cisterns$length : 0, (_waterValues$length = waterValues === null || waterValues === void 0 ? void 0 : waterValues.length) !== null && _waterValues$length !== void 0 ? _waterValues$length : 0);
+  if (maxLength === 0) {
+    return {};
+  }
+  const normalizedCisterns = normalizeOptionalPreferenceArray(Array.from({
+    length: maxLength
+  }, (_, index) => {
+    var _cisterns$index;
+    if (hasPreferenceValue(waterValues === null || waterValues === void 0 ? void 0 : waterValues[index])) {
+      return '';
+    }
+    return (_cisterns$index = cisterns === null || cisterns === void 0 ? void 0 : cisterns[index]) !== null && _cisterns$index !== void 0 ? _cisterns$index : '';
+  }));
+  const normalizedWaterValues = normalizeOptionalPreferenceArray(Array.from({
+    length: maxLength
+  }, (_, index) => {
+    var _waterValues$index;
+    return (_waterValues$index = waterValues === null || waterValues === void 0 ? void 0 : waterValues[index]) !== null && _waterValues$index !== void 0 ? _waterValues$index : '';
+  }));
+  return _objectSpread(_objectSpread({}, normalizedCisterns ? {
+    cisterns: normalizedCisterns
+  } : {}), normalizedWaterValues ? {
+    waterValues: normalizedWaterValues
+  } : {});
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/robot-data-stream",
-  "version": "0.0.15-beta.8",
+  "version": "0.0.16-beta.1",
   "description": "扫地机P2P数据流标准化组件",
   "main": "lib/index",
   "files": [
@@ -28,7 +28,9 @@
     "start:wechat": "ray start ./example -t wechat --verbose",
     "start:web": "ray start ./example -t web",
     "prepublishOnly": "yarn build",
-    "release-it": "standard-version"
+    "release-it": "standard-version",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
   },
   "peerDependencies": {
     "@ray-js/log4js": "^0.0.4",
@@ -53,14 +55,15 @@
     "@ray-js/log4js": "^0.0.4",
     "@ray-js/ray": "1.8.0-beta.14",
     "@ray-js/robot-protocol": "^1.0.1",
+    "@types/lodash-es": "^4.17.12",
     "core-js": "^3.19.1",
     "eslint-config-tuya-panel": "^0.4.2",
     "husky": "^1.2.0",
     "lint-staged": "^10.2.11",
     "patch-package": "^8.0.0",
-    "@types/lodash-es": "^4.17.12",
     "prettier": "^3.8.0",
-    "standard-version": "9.3.2"
+    "standard-version": "9.3.2",
+    "vitepress": "^1.6.4"
   },
   "husky": {
     "hooks": {