@zucker-framework/things 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,560 @@
+import { AggregationQuery, AggregationResult, TimeSeriesService } from '@zucker-framework/timeseries';
+
+/**
+ * 物模型数据类型系统 — 对应 jetlinks DataType / DataTypes
+ *
+ * 描述属性、事件参数、功能参数的值类型。
+ */
+type DataTypeId = 'string' | 'int' | 'long' | 'float' | 'double' | 'boolean' | 'enum' | 'date' | 'object' | 'array' | 'geo' | 'password' | 'file';
+/**
+ * 枚举元素 — 对应 jetlinks EnumType.Element
+ */
+interface EnumElement {
+    value: string | number;
+    text: string;
+    description?: string;
+}
+/**
+ * 地理坐标 — 对应 jetlinks GeoType
+ */
+interface GeoPoint {
+    lat: number;
+    lon: number;
+}
+interface BaseDataType {
+    id: DataTypeId;
+    description?: string;
+}
+interface StringDataType extends BaseDataType {
+    id: 'string';
+    maxLength?: number;
+    unit?: string;
+}
+interface IntDataType extends BaseDataType {
+    id: 'int';
+    max?: number;
+    min?: number;
+    unit?: string;
+}
+interface LongDataType extends BaseDataType {
+    id: 'long';
+    max?: number;
+    min?: number;
+    unit?: string;
+}
+interface FloatDataType extends BaseDataType {
+    id: 'float';
+    max?: number;
+    min?: number;
+    unit?: string;
+    scale?: number;
+}
+interface DoubleDataType extends BaseDataType {
+    id: 'double';
+    max?: number;
+    min?: number;
+    unit?: string;
+    scale?: number;
+}
+interface BooleanDataType extends BaseDataType {
+    id: 'boolean';
+    trueText?: string;
+    falseText?: string;
+    trueValue?: string;
+    falseValue?: string;
+}
+interface EnumDataType extends BaseDataType {
+    id: 'enum';
+    elements: EnumElement[];
+}
+interface DateDataType extends BaseDataType {
+    id: 'date';
+    /** 日期格式，默认 'yyyy-MM-dd HH:mm:ss' */
+    format?: string;
+    timeZone?: string;
+}
+interface ObjectDataType extends BaseDataType {
+    id: 'object';
+    properties?: PropertyMetadataInput[];
+}
+interface ArrayDataType extends BaseDataType {
+    id: 'array';
+    elementType: DataType;
+}
+interface GeoDataType extends BaseDataType {
+    id: 'geo';
+}
+interface PasswordDataType extends BaseDataType {
+    id: 'password';
+}
+interface FileDataType extends BaseDataType {
+    id: 'file';
+    bodyType?: 'url' | 'base64' | 'binary';
+}
+type DataType = StringDataType | IntDataType | LongDataType | FloatDataType | DoubleDataType | BooleanDataType | EnumDataType | DateDataType | ObjectDataType | ArrayDataType | GeoDataType | PasswordDataType | FileDataType;
+/** 属性元数据输入（用于 ObjectDataType.properties，不能自引用完整类型） */
+interface PropertyMetadataInput {
+    id: string;
+    name: string;
+    dataType: DataType;
+    description?: string;
+}
+/**
+ * 将原始值转换为对应数据类型的 JavaScript 表示 — 对应 jetlinks DataType.convert()
+ */
+declare function convertValue(type: DataType, raw: unknown): unknown;
+
+/**
+ * 物模型元数据 — 对应 jetlinks ThingMetadata / DeviceMetadata
+ *
+ * 定义一类物（设备）的属性、事件、功能三元素。
+ */
+
+/**
+ * 属性读写权限 — 对应 jetlinks PropertyMetadata.AccessMode
+ */
+declare enum PropertyAccessMode {
+    /** 只读 */
+    READ = "r",
+    /** 只写 */
+    WRITE = "w",
+    /** 读写 */
+    READ_WRITE = "rw"
+}
+/**
+ * 属性元数据 — 对应 jetlinks PropertyMetadata
+ */
+interface PropertyMetadata {
+    /** 属性唯一标识 */
+    id: string;
+    /** 属性名称 */
+    name: string;
+    /** 数据类型 */
+    dataType: DataType;
+    /** 读写权限，默认可读写 */
+    accessMode?: PropertyAccessMode;
+    /** 描述 */
+    description?: string;
+    /** 存储到时序数据库时的指标名（默认使用 thingType.id） */
+    storageMetric?: string;
+    /** 是否忽略存储 */
+    ignoreStorage?: boolean;
+    /** 扩展属性 */
+    expands?: Record<string, unknown>;
+}
+/**
+ * 功能参数 — 对应 jetlinks FunctionMetadata.Parameter / InputOutput
+ */
+interface FunctionParameter {
+    id: string;
+    name: string;
+    dataType: DataType;
+    description?: string;
+}
+/**
+ * 功能元数据 — 对应 jetlinks FunctionMetadata
+ */
+interface FunctionMetadata {
+    id: string;
+    name: string;
+    /** 输入参数 */
+    inputs: FunctionParameter[];
+    /** 输出参数（返回值定义） */
+    output?: FunctionParameter[];
+    /** 是否为异步功能（下行指令，无立即返回值） */
+    async?: boolean;
+    description?: string;
+}
+/**
+ * 事件级别 — 对应 jetlinks EventMetadata.EventType
+ */
+declare enum EventLevel {
+    /** 普通上报 */
+    OTHER = "other",
+    /** 告警 */
+    WARN = "warn",
+    /** 故障 */
+    ERROR = "error"
+}
+/**
+ * 事件元数据 — 对应 jetlinks EventMetadata
+ */
+interface EventMetadata {
+    id: string;
+    name: string;
+    /** 事件携带的数据结构 */
+    valueType: DataType;
+    /** 事件级别 */
+    level?: EventLevel;
+    description?: string;
+    /** 是否存储到时序数据库 */
+    storeInTimeSeries?: boolean;
+}
+/**
+ * 物模型元数据 — 对应 jetlinks ThingMetadata
+ */
+interface ThingMetadata {
+    /** 属性列表 */
+    properties: PropertyMetadata[];
+    /** 功能列表 */
+    functions: FunctionMetadata[];
+    /** 事件列表 */
+    events: EventMetadata[];
+    /** 标签列表（自定义键值对，不参与时序存储） */
+    tags?: PropertyMetadata[];
+}
+/**
+ * 合并两份 ThingMetadata — 对应 jetlinks SimpleThingMetadata.merge()
+ *
+ * 后者属性覆盖前者（以 id 为键）。
+ */
+declare function mergeMetadata(base: ThingMetadata, patch: Partial<ThingMetadata>): ThingMetadata;
+/**
+ * 工厂：从简单描述创建 ThingMetadata
+ */
+declare function createMetadata(partial?: Partial<ThingMetadata>): ThingMetadata;
+
+/**
+ * 物类型 & 物实例 — 对应 jetlinks ThingType / Thing
+ *
+ * ThingType  = 设备产品（定义一类设备的元数据模板）
+ * Thing      = 设备实例（具体的一台设备）
+ */
+
+/**
+ * 物类型 — 对应 jetlinks ThingType / ProductInfo
+ */
+interface ThingType {
+    /** 类型唯一 ID（如 product ID） */
+    id: string;
+    /** 名称 */
+    name: string;
+    /** 物模型元数据 */
+    metadata: ThingMetadata;
+    /** 协议（protocol ID，用于选择对应的网关解码器） */
+    protocol?: string;
+    /** 传输方式（对应 network Transport） */
+    transport?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 扩展属性 */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 物状态 — 对应 jetlinks DeviceState
+ */
+declare enum ThingState {
+    /** 未激活（从未在线） */
+    INACTIVE = "notActive",
+    /** 离线 */
+    OFFLINE = "offline",
+    /** 在线 */
+    ONLINE = "online"
+}
+/**
+ * 物实例 — 对应 jetlinks Thing / DeviceInfo
+ */
+interface Thing {
+    /** 实例唯一 ID */
+    id: string;
+    /** 名称 */
+    name: string;
+    /** 所属物类型 ID */
+    thingTypeId: string;
+    /** 当前状态 */
+    state: ThingState;
+    /** 上次在线时间戳 */
+    onlineTime?: number;
+    /** 上次离线时间戳 */
+    offlineTime?: number;
+    /** 自定义标签（非时序属性） */
+    tags?: Record<string, unknown>;
+    /** 实例级元数据覆盖（优先于 ThingType 的 metadata） */
+    metadataPatch?: Partial<ThingMetadata>;
+    /** 所属父设备 ID（子设备场景） */
+    parentId?: string;
+    /** 扩展属性 */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 物管理器接口 — 对应 jetlinks ThingManager / DeviceRegistry
+ */
+interface ThingManager {
+    /** 获取物类型 */
+    getThingType(typeId: string): Promise<ThingType | undefined>;
+    /** 注册物类型 */
+    registerThingType(type: ThingType): Promise<void>;
+    /** 获取物实例 */
+    getThing(thingId: string): Promise<Thing | undefined>;
+    /** 注册/更新物实例 */
+    registerThing(thing: Thing): Promise<void>;
+    /** 注销物实例 */
+    unregisterThing(thingId: string): Promise<void>;
+    /** 更新物状态 */
+    updateState(thingId: string, state: ThingState, timestamp?: number): Promise<void>;
+    /** 获取物实例的有效元数据（合并 ThingType + 实例覆盖） */
+    getEffectiveMetadata(thingId: string): Promise<ThingMetadata | undefined>;
+}
+
+declare class InMemoryThingManager implements ThingManager {
+    private readonly types;
+    private readonly things;
+    getThingType(typeId: string): Promise<ThingType | undefined>;
+    registerThingType(type: ThingType): Promise<void>;
+    getThing(thingId: string): Promise<Thing | undefined>;
+    registerThing(thing: Thing): Promise<void>;
+    unregisterThing(thingId: string): Promise<void>;
+    updateState(thingId: string, state: ThingState, timestamp?: number): Promise<void>;
+    getEffectiveMetadata(thingId: string): Promise<ThingMetadata | undefined>;
+    /** 获取指定类型的所有实例 */
+    getThingsByType(typeId: string): Thing[];
+    /** 获取所有在线实例数量 */
+    countOnline(): number;
+}
+
+/**
+ * 物消息体系 — 对应 jetlinks ThingMessage / DeviceMessage
+ *
+ * 所有设备上行/下行消息的类型定义。
+ * 设计原则：消息类型通过 messageType 字符串区分，便于序列化和路由。
+ */
+type ThingMessageType = 'ReportProperty' | 'Event' | 'FunctionReply' | 'Register' | 'Unregister' | 'Online' | 'Offline' | 'ReportTags' | 'UpdateMetadata' | 'StateCheck' | 'ReadPropertyReply' | 'ReadProperty' | 'WriteProperty' | 'FunctionInvoke';
+/**
+ * 消息基类 — 对应 jetlinks ThingMessage
+ */
+interface ThingMessage {
+    /** 消息类型 */
+    messageType: ThingMessageType;
+    /** 消息 ID，用于请求-响应关联 */
+    messageId: string;
+    /** 物（设备）ID */
+    thingId: string;
+    /** 物类型 ID */
+    thingType: string;
+    /** 时间戳（毫秒） */
+    timestamp: number;
+    /** 消息头（扩展元数据） */
+    headers?: Record<string, unknown>;
+}
+/**
+ * 属性上报 — 对应 jetlinks ReportPropertyMessage
+ */
+interface ReportPropertyMessage extends ThingMessage {
+    messageType: 'ReportProperty';
+    /** 属性键值对，key 为属性 ID */
+    properties: Record<string, unknown>;
+    /** 各属性的上报时间（可选，key 与 properties 一致） */
+    propertySourceTimes?: Record<string, number>;
+    /** 各属性的状态（可选，'success' | 'error' | 'noReport'） */
+    propertyStates?: Record<string, string>;
+}
+/**
+ * 事件上报 — 对应 jetlinks EventMessage
+ */
+interface EventMessage extends ThingMessage {
+    messageType: 'Event';
+    /** 事件 ID */
+    event: string;
+    /** 事件数据 */
+    data: unknown;
+}
+/**
+ * 功能调用回复 — 对应 jetlinks FunctionInvokeReplyMessage
+ */
+interface FunctionReplyMessage extends ThingMessage {
+    messageType: 'FunctionReply';
+    /** 关联的下行消息 ID */
+    correlationKey?: string;
+    /** 功能 ID */
+    functionId: string;
+    /** 返回值 */
+    output?: unknown;
+    /** 是否成功 */
+    success: boolean;
+    /** 错误信息 */
+    errorMessage?: string;
+    /** 错误码 */
+    errorCode?: string;
+}
+/**
+ * 设备注册 — 对应 jetlinks RegisterMessage
+ */
+interface RegisterMessage extends ThingMessage {
+    messageType: 'Register';
+}
+/**
+ * 设备注销 — 对应 jetlinks UnRegisterMessage
+ */
+interface UnregisterMessage extends ThingMessage {
+    messageType: 'Unregister';
+}
+/**
+ * 设备上线 — 对应 jetlinks DeviceOnlineMessage
+ */
+interface OnlineMessage extends ThingMessage {
+    messageType: 'Online';
+}
+/**
+ * 设备离线 — 对应 jetlinks DeviceOfflineMessage
+ */
+interface OfflineMessage extends ThingMessage {
+    messageType: 'Offline';
+}
+/**
+ * 标签上报 — 对应 jetlinks ReportTagsMessage
+ */
+interface ReportTagsMessage extends ThingMessage {
+    messageType: 'ReportTags';
+    tags: Record<string, unknown>;
+}
+/**
+ * 读属性回复 — 对应 jetlinks ReadPropertyMessageReply
+ */
+interface ReadPropertyReplyMessage extends ThingMessage {
+    messageType: 'ReadPropertyReply';
+    correlationKey?: string;
+    properties: Record<string, unknown>;
+    success: boolean;
+    errorMessage?: string;
+}
+/**
+ * 读属性指令 — 对应 jetlinks ReadPropertyMessage
+ */
+interface ReadPropertyMessage extends ThingMessage {
+    messageType: 'ReadProperty';
+    /** 要读取的属性 ID 列表 */
+    properties: string[];
+}
+/**
+ * 写属性指令 — 对应 jetlinks WritePropertyMessage
+ */
+interface WritePropertyMessage extends ThingMessage {
+    messageType: 'WriteProperty';
+    properties: Record<string, unknown>;
+}
+/**
+ * 功能调用指令 — 对应 jetlinks FunctionInvokeMessage
+ */
+interface FunctionInvokeMessage extends ThingMessage {
+    messageType: 'FunctionInvoke';
+    /** 功能 ID */
+    functionId: string;
+    /** 输入参数 */
+    inputs: Record<string, unknown>;
+    /** 是否同步等待回复 */
+    sync?: boolean;
+}
+type UpstreamMessage = ReportPropertyMessage | EventMessage | FunctionReplyMessage | RegisterMessage | UnregisterMessage | OnlineMessage | OfflineMessage | ReportTagsMessage | ReadPropertyReplyMessage;
+type DownstreamMessage = ReadPropertyMessage | WritePropertyMessage | FunctionInvokeMessage;
+/**
+ * 创建消息 ID — 对应 jetlinks IDGenerator.SNOW_FLAKE_STRING
+ */
+declare function createMessageId(): string;
+/**
+ * 创建属性上报消息
+ */
+declare function createReportPropertyMessage(thingId: string, thingType: string, properties: Record<string, unknown>, extra?: Partial<ReportPropertyMessage>): ReportPropertyMessage;
+/**
+ * 创建事件消息
+ */
+declare function createEventMessage(thingId: string, thingType: string, event: string, data: unknown): EventMessage;
+
+/**
+ * 属性日志记录
+ */
+interface PropertyLog {
+    /** 属性 ID */
+    property: string;
+    /** 属性值 */
+    value: unknown;
+    /** 物 ID */
+    thingId: string;
+    /** 物类型 ID */
+    thingType: string;
+    /** 时间戳（毫秒） */
+    timestamp: number;
+    /** 上报状态 */
+    state?: string;
+}
+/**
+ * 事件日志记录
+ */
+interface EventLog {
+    /** 事件 ID */
+    event: string;
+    /** 事件数据（JSON 序列化后存储） */
+    data: unknown;
+    /** 物 ID */
+    thingId: string;
+    /** 物类型 ID */
+    thingType: string;
+    /** 时间戳（毫秒） */
+    timestamp: number;
+}
+/**
+ * 属性/事件日志查询条件
+ */
+interface ThingLogQuery {
+    thingId: string;
+    thingType: string;
+    /** 属性 ID 或 事件 ID */
+    id: string;
+    from: number;
+    to: number;
+    limit?: number;
+    order?: 'asc' | 'desc';
+}
+/**
+ * 物数据服务接口 — 对应 jetlinks ThingsDataService
+ */
+interface ThingsDataService {
+    /**
+     * 保存属性上报
+     * 对应 jetlinks ThingsDataService.save(DeviceMessage)
+     */
+    saveProperties(message: ReportPropertyMessage): Promise<void>;
+    /**
+     * 保存事件
+     */
+    saveEvent(message: EventMessage): Promise<void>;
+    /**
+     * 查询属性历史
+     */
+    queryPropertyLogs(query: ThingLogQuery): Promise<PropertyLog[]>;
+    /**
+     * 查询事件历史
+     */
+    queryEventLogs(query: ThingLogQuery): Promise<EventLog[]>;
+    /**
+     * 聚合查询属性数据
+     */
+    aggregateProperties(thingId: string, thingType: string, property: string, aggQuery: Omit<AggregationQuery, 'metric'>): Promise<AggregationResult[]>;
+}
+/**
+ * 基于 TimeSeriesService 的默认实现
+ *
+ * 指标命名约定：
+ *   属性：`thing_property_{thingType}`
+ *   事件：`thing_event_{thingType}_{eventId}`
+ */
+declare class DefaultThingsDataService implements ThingsDataService {
+    private readonly tsService;
+    constructor(tsService: TimeSeriesService);
+    private propertyMetric;
+    private eventMetric;
+    saveProperties(message: ReportPropertyMessage): Promise<void>;
+    saveEvent(message: EventMessage): Promise<void>;
+    queryPropertyLogs(query: ThingLogQuery): Promise<PropertyLog[]>;
+    queryEventLogs(query: ThingLogQuery): Promise<EventLog[]>;
+    aggregateProperties(thingId: string, thingType: string, property: string, aggQuery: Omit<AggregationQuery, 'metric'>): Promise<AggregationResult[]>;
+}
+
+/**
+ * ThingsModule — 物模型 NestJS 模块
+ *
+ * 默认使用内存实现。生产环境可覆盖 ThingManager 提供者。
+ */
+declare class ThingsModule {
+}
+
+export { type ArrayDataType, type BooleanDataType, type DataType, type DataTypeId, type DateDataType, DefaultThingsDataService, type DoubleDataType, type DownstreamMessage, type EnumDataType, type EnumElement, EventLevel, type EventLog, type EventMessage, type EventMetadata, type FileDataType, type FloatDataType, type FunctionInvokeMessage, type FunctionMetadata, type FunctionParameter, type FunctionReplyMessage, type GeoDataType, type GeoPoint, InMemoryThingManager, type IntDataType, type LongDataType, type ObjectDataType, type OfflineMessage, type OnlineMessage, type PasswordDataType, PropertyAccessMode, type PropertyLog, type PropertyMetadata, type PropertyMetadataInput, type ReadPropertyMessage, type ReadPropertyReplyMessage, type RegisterMessage, type ReportPropertyMessage, type ReportTagsMessage, type StringDataType, type Thing, type ThingLogQuery, type ThingManager, type ThingMessage, type ThingMessageType, type ThingMetadata, ThingState, type ThingType, type ThingsDataService, ThingsModule, type UnregisterMessage, type UpstreamMessage, type WritePropertyMessage, convertValue, createEventMessage, createMessageId, createMetadata, createReportPropertyMessage, mergeMetadata };