device-communication-node 1.0.0-beta.1

package/src/device/core/commDispatcherManager.js

@@ -0,0 +1,105 @@
+const serialFactory = require('./factories/serialFactory')
+const tcpFactory = require('./factories/tcpFactory')
+const udpFactory = require('./factories/udpFactory')
+const tcpserverFactory = require('./factories/tcpserverFactory')
+/**
+ * 调度器工厂 Map
+ */
+const factoryMap = new Map();
+/**
+ * 调度器 Map
+ */
+const dispatcherMap = new Map();
+
+/**
+ * 通信调度器管理（全局单例工具模块）
+ * * 支持的通信类型及地址格式规范：
+ * - "serial"    : 串口号@波特率                                    (例: "COM1@9600")
+ * - "tcp"       : IP地址:端口号                                    (例: "192.168.1.100:8080")
+ * - "udp"       : IP地址:端口号                                    (例: "192.168.1.100:8080")
+ * - "tcpserver" : IP地址:端口号 或 端口号 (例:"0.0.0.0:8080")       (例:"8080")
+ */
+const CommDispatcherManager = {
+
+    /**
+     * 初始化注册原生工厂
+     */
+    init() {
+        this.registerFactory(serialFactory)
+        this.registerFactory(tcpFactory)
+        this.registerFactory(udpFactory)
+        this.registerFactory(tcpserverFactory)
+    },
+
+    /** 动态注册新工厂 */
+    registerFactory(factory) {
+        if (factory && factory.getCommType) {
+            factoryMap.set(factory.getCommType().toLowerCase(), factory);
+        }
+    },
+
+    /**
+     * 仅创建不保存
+     * @param {*} commType 
+     * @param {*} commAddress 
+     * @returns 
+     */
+    create(commType, commAddress) {
+        if (!commType) throw new Error("通信类型不能为空");
+
+        const factory = factoryMap.get(commType.toLowerCase());
+        if (!factory) throw new Error(`不支持的通信类型: ${commType}`);
+
+        // 执行特定校验并创建
+        factory.validate(commAddress);
+        return factory.create(commAddress);
+    },
+
+    /**
+     * 获取或创建
+     * @param {*} commType 
+     * @param {*} commAddress 
+     * @returns 
+     */
+    getOrCreate(commType, commAddress) {
+        const key = this.buildKey(commType, commAddress);
+        if (!dispatcherMap.has(key)) {
+            const dispatcher = this.create(commType, commAddress);
+            dispatcherMap.set(key, dispatcher);
+        }
+        return dispatcherMap.get(key);
+    },
+
+    /**
+     * 移除并释放资源
+     * @param {*} commType 
+     * @param {*} commAddress 
+     */
+    async remove(commType, commAddress) {
+        const key = this.buildKey(commType, commAddress);
+        const dispatcher = dispatcherMap.get(key);
+        if (dispatcher) {
+            dispatcherMap.delete(key);
+            try {
+                await dispatcher.dispose();
+            } catch (err) {
+                console.error(`[CommDispatcherManager] 关闭通道失败 [${key}]:`, err.message);
+            }
+        }
+    },
+    /**
+     * 构建 key
+     * @param {*} commType 
+     * @param {*} commAddress 
+     * @returns 
+     */
+    buildKey(commType, commAddress) {
+        return `${commType.toLowerCase().trim()}:${commAddress.trim()}`;
+    }
+};
+
+// 执行初始化
+CommDispatcherManager.init();
+
+// 单例
+module.exports = CommDispatcherManager;

package/src/device/core/dispatchers/SerialDispatcher.js

@@ -0,0 +1,77 @@
+const CommDispatcher = require('../CommDispatcher');
+
+/**
+ * 串口调度器适配器
+ */
+class SerialDispatcher extends CommDispatcher {
+
+    /**
+     * @param {SerialChannel} serialChannel 串口通道实例
+     */
+    constructor(serialChannel) {
+        super(serialChannel);
+
+        this.serialChannel = serialChannel;
+
+        // 串口接收事件
+        this.serialChannel.onReceive = (port, data) => {
+            this.channelReceiveEvent(data);
+        };
+    }
+
+    /**
+     * 获取连接字符串
+     */
+    getConnectionString() {
+        const config = this.serialChannel.getConfig();
+
+        return `${config.path}@${config.baudRate}`;
+    }
+
+    /**
+     * 连接是否打开
+     */
+    isOpen() {
+        return this.serialChannel.getIsOpen();
+    }
+
+    /**
+     * 打开连接
+     */
+    async open() {
+        await this.serialChannel.open();
+    }
+
+    /**
+     * 关闭连接
+     */
+    async close() {
+        await this.serialChannel.close();
+    }
+
+    /**
+     * 执行底层写入
+     * @param {Task} task
+     */
+    async write(task) {
+        await this.serialChannel.send(task.writeBytes);
+    }
+
+    /**
+     * 获取字符集
+     */
+    getCharset() {
+        return this.serialChannel.charset || 'utf8';
+    }
+
+    /**
+     * 串口数据接收事件
+     * @param {Buffer} data
+     */
+    channelReceiveEvent(data) {
+
+        this.receive(data);
+    }
+}
+
+module.exports = SerialDispatcher;

package/src/device/core/dispatchers/TcpDispatcher.js

@@ -0,0 +1,72 @@
+const CommDispatcher = require('../CommDispatcher');
+
+/**
+ * TCP 调度器适配器
+ */
+class TcpDispatcher extends CommDispatcher {
+    /**
+     * @param {TcpChannel} tcpChannel TCP 通道实例
+     */
+    constructor(tcpChannel) {
+        super(tcpChannel);
+
+        this.tcpChannel = tcpChannel;
+
+        this.tcpChannel.onReceive = (socket, data) => {
+            this.channelReceiveEvent(data);
+        };
+    }
+
+    /**
+     * 获取连接字符串
+     */
+    getConnectionString() {
+        return `${this.tcpChannel.host}:${this.tcpChannel.port}`;
+    }
+
+    /**
+     * 连接是否打开
+     */
+    isOpen() {
+        return this.tcpChannel.getIsOpen();
+    }
+
+    /**
+     * 打开连接
+     */
+    async open() {
+        await this.tcpChannel.open();
+    }
+
+    /**
+     * 关闭连接
+     */
+    async close() {
+        await this.tcpChannel.close();
+    }
+
+    /**
+     * 执行底层写入
+     * @param {Task} task 
+     */
+    async write(task) {
+        await this.tcpChannel.send(task.writeBytes);
+    }
+
+    /**
+     * 获取编码格式
+     */
+    getCharset() {
+        return this.tcpChannel.charset || 'utf8';
+    }
+
+    /**
+     * TCP 数据接收事件（流式）
+     * @param {Buffer} data 
+     */
+    channelReceiveEvent(data) {
+        this.receive(data);
+    }
+}
+
+module.exports = TcpDispatcher;

package/src/device/core/dispatchers/TcpServerDispatcher.js

@@ -0,0 +1,99 @@
+const CommDispatcher = require('../CommDispatcher');
+
+/**
+ * TCP Server 调度器适配器（支持多客户端管理与广播/定向发送）
+ */
+class TcpServerDispatcher extends CommDispatcher {
+    /**
+     * @param {TcpServerChannel} tcpServerChannel TCP 服务端通道实例
+     */
+    constructor(tcpServerChannel) {
+        super(tcpServerChannel);
+
+        this.tcpServerChannel = tcpServerChannel;
+
+        // 核心改动 1：TCP Server 的 onReceive 会多带一个 socket 参数
+        this.tcpServerChannel.onReceive = (socket, data) => {
+            this.channelReceiveEvent(socket, data);
+        };
+    }
+
+    /**
+     * 获取连接字符串（服务端自身监听的地址）
+     */
+    getConnectionString() {
+        return `${this.tcpServerChannel.host}:${this.tcpServerChannel.port}`;
+    }
+
+    /**
+     * 获取某个具体客户端连接的唯一标识
+     * @param {net.Socket} socket 
+     */
+    getClientConnectionString(socket) {
+        if (!socket || socket.destroyed) return 'Unknown';
+        return `${socket.remoteAddress}:${socket.remotePort}`;
+    }
+
+    /**
+     * 服务端是否打开
+     */
+    isOpen() {
+        return this.tcpServerChannel.getIsOpen();
+    }
+
+    /**
+     * 开启服务端监听
+     */
+    async open() {
+        await this.tcpServerChannel.open();
+    }
+
+    /**
+     * 关闭服务端并断开所有客户端
+     */
+    async close() {
+        await this.tcpServerChannel.close();
+    }
+
+    /**
+     * 执行底层写入
+     * @param {Task} task 任务对象
+     */
+    async write(task) {
+        const targetSocket = task.socket || task.context?.socket;
+
+        if (targetSocket) {
+            // 定向发送给特定客户端
+            await this.tcpServerChannel.send(task.writeBytes, targetSocket);
+        } else {
+            // 未指定则默认广播给所有客户端
+            await this.tcpServerChannel.send(task.writeBytes);
+        }
+    }
+
+    /**
+     * 获取编码格式
+     */
+    getCharset() {
+        return this.tcpServerChannel.charset || 'utf8';
+    }
+
+    /**
+     * TCP 数据接收事件
+     * @param {net.Socket} socket 触发数据的客户端套接字
+     * @param {Buffer} data 
+     */
+    channelReceiveEvent(socket, data) {
+        // 核心改动 3：如果基类的 this.receive(data) 无法携带上下文，
+        // 建议检查底层 CommDispatcher 是否支持附加信息。
+        // 如果支持，可以将 socket 注入到解析链路中，方便业务层回包时知道该发给谁：
+        if (typeof this.receiveWithContext === 'function') {
+            this.receiveWithContext(data, { socket });
+        } else {
+            // 降级使用标准设计，但通常需要在 task 层面能够绑定源 socket
+            this.receive(data);
+        }
+    }
+}
+
+module.exports = TcpServerDispatcher;

package/src/device/core/dispatchers/UdpDispatcher.js

@@ -0,0 +1,77 @@
+const CommDispatcher = require('../CommDispatcher');
+
+/**
+ * UDP 调度器适配器
+ */
+class UdpDispatcher extends CommDispatcher {
+    /**
+     * @param {UdpChannel} udpChannel UDP 通道实例
+     */
+    constructor(udpChannel) {
+        super(udpChannel);
+
+        this.udpChannel = udpChannel;
+
+        this.udpChannel.onReceive = (rinfo, data) => {
+            this.channelReceiveEvent(rinfo, data);
+        };
+    }
+
+    /**
+     * 获取连接字符串
+     */
+    getConnectionString() {
+        return `${this.udpChannel.localPort}:${this.udpChannel.remoteHost}:${this.udpChannel.remotePort}`;
+    }
+
+    /**
+     * 连接是否打开
+     */
+    isOpen() {
+        return this.udpChannel.getIsOpen();
+    }
+
+    /**
+     * 打开连接
+     */
+    async open() {
+        await this.udpChannel.open();
+    }
+
+    /**
+     * 关闭连接
+     */
+    async close() {
+        await this.udpChannel.close();
+    }
+
+    /**
+     * 执行底层写入
+     * @param {Task} task 
+     */
+    async write(task) {
+        // 调用 UdpChannel 的 send 方法
+        await this.udpChannel.send(task.writeBytes);
+    }
+
+    /**
+     * 获取编码格式
+     */
+    getCharset() {
+        // 优先使用通道定义的编码，没有则默认 utf8
+        return this.udpChannel.charset || 'utf8';
+    }
+
+    /**
+     * 处理通道接收到的原始数据
+     * @param {Object} rinfo 远程信息 (address, port, family, size)
+     * @param {Buffer} data 原始数据
+     */
+    channelReceiveEvent(rinfo, data) {
+        // 调用基类 CommDispatcher 的 receive 方法进行帧匹配和逻辑分发
+        // data 在 Node UDP 中已经是 Buffer 对象
+        this.receive(data);
+    }
+}
+
+module.exports = UdpDispatcher;

package/src/device/core/factories/serialFactory.js

@@ -0,0 +1,32 @@
+const SerialDispatcher = require('../dispatchers/SerialDispatcher');
+const SerialChannel = require('../../channel/SerialChannel');
+
+module.exports = {
+    getCommType() {
+        return "serial";
+    },
+
+    validate(commAddress) {
+        if (!commAddress) throw new Error("地址不能为空");
+
+        const parts = commAddress.split("@");
+        if (parts.length !== 2) throw new Error("地址格式必须为路径:波特率(例如 COM1@9600)");
+
+        const [path, baudRateStr] = parts;
+        if (!path) throw new Error("串口路径不能为空");
+
+        const baudRate = parseInt(baudRateStr, 10);
+        if (isNaN(baudRate) || baudRate <= 0) {
+            throw new Error(`无效的波特率: ${baudRateStr}`);
+        }
+    },
+
+    create(commAddress) {
+        this.validate(commAddress);
+
+        const [path, baudRateStr] = commAddress.split(":");
+        const baudRate = parseInt(baudRateStr, 10);
+
+        return new SerialDispatcher(new SerialChannel(path, baudRate));
+    }
+};

package/src/device/core/factories/tcpFactory.js

@@ -0,0 +1,24 @@
+const TcpDispatcher = require('../dispatchers/TcpDispatcher');
+const TcpChannel = require('../../channel/TcpChannel');
+
+module.exports = {
+    getCommType() {
+        return "tcp";
+    },
+
+    validate(commAddress) {
+        if (!commAddress) throw new Error("地址不能为空");
+        const parts = commAddress.split(":");
+        if (parts.length !== 2) throw new Error("地址格式必须为 ip:port");
+
+        const port = parseInt(parts[1], 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            throw new Error(`无效端口: ${parts[1]}`);
+        }
+    },
+
+    create(commAddress) {
+        const [ip, port] = commAddress.split(":");
+        return new TcpDispatcher(new TcpChannel(ip, parseInt(port, 10)));
+    }
+};

package/src/device/core/factories/tcpserverFactory.js

@@ -0,0 +1,61 @@
+const TcpServerDispatcher = require('../dispatchers/TcpServerDispatcher');
+const TcpServerChannel = require('../../channel/TcpServerChannel');
+
+module.exports = {
+    /**
+     * 获取通信类型标识
+     */
+    getCommType() {
+        return "tcpserver";
+    },
+
+    /**
+     * 验证通信地址格式
+     * 支持两种格式: "ip:port" (如 0.0.0.0:9000) 或 单独的 "port" (如 9000)
+     */
+    validate(commAddress) {
+        if (!commAddress) throw new Error("地址不能为空");
+
+        const parts = commAddress.split(":");
+        let portStr = "";
+
+        if (parts.length === 1) {
+            portStr = parts[0];
+        } else if (parts.length === 2) {
+            portStr = parts[1];
+        } else {
+            throw new Error("地址格式错误，应为 port 或 ip:port");
+        }
+
+        const port = parseInt(portStr, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            throw new Error(`无效端口: ${portStr}`);
+        }
+    },
+
+    /**
+     * 创建 TcpServer 调度器适配器实例
+     */
+    create(commAddress) {
+        this.validate(commAddress);
+
+        const parts = commAddress.split(":");
+        let host = '0.0.0.0';
+        let port = 9000;
+
+        if (parts.length === 1) {
+            // 仅提供了端口号
+            port = parseInt(parts[0], 10);
+        } else {
+            // 提供了 ip 和 端口号
+            host = parts[0];
+            port = parseInt(parts[1], 10);
+        }
+
+        // 实例化服务端通道
+        const channel = new TcpServerChannel(port, host);
+
+        // 返回服务端调度器
+        return new TcpServerDispatcher(channel);
+    }
+};

package/src/device/core/factories/udpFactory.js

@@ -0,0 +1,47 @@
+const UdpDispatcher = require('../dispatchers/UdpDispatcher');
+const UdpChannel = require('../../channel/UdpChannel');
+
+module.exports = {
+    getCommType() {
+        return "udp";
+    },
+
+    validate(commAddress) {
+        if (!commAddress) {
+            throw new Error("地址不能为空");
+        }
+
+        const parts = commAddress.split(":");
+        if (parts.length !== 3) {
+            throw new Error("地址格式必须为 localPort:ip:remotePort");
+        }
+
+        const localPort = parseInt(parts[0], 10);
+        const ip = parts[1];
+        const remotePort = parseInt(parts[2], 10);
+
+        if (isNaN(localPort) || localPort < 0 || localPort > 65535) {
+            throw new Error(`无效本地端口: ${parts[0]}`);
+        }
+
+        if (!ip) {
+            throw new Error("远程IP不能为空");
+        }
+
+        if (isNaN(remotePort) || remotePort < 1 || remotePort > 65535) {
+            throw new Error(`无效远程端口: ${parts[2]}`);
+        }
+    },
+
+    create(commAddress) {
+        const [localPort, remoteHost, remotePort] = commAddress.split(":");
+
+        return new UdpDispatcher(
+            new UdpChannel(
+                remoteHost,
+                parseInt(remotePort, 10),
+                parseInt(localPort, 10)
+            )
+        );
+    }
+};

package/src/device/model/InteractionPattern.js

@@ -0,0 +1,16 @@
+/**
+ * 任务交互模式 (Interaction Pattern)
+ * 决定了单个发送任务的生命周期和行为
+ */
+const InteractionPattern = Object.freeze({
+    /** 
+     * [请求-响应] 发送并等待设备应答
+     */
+    WAIT_RESPONSE: 'WAIT_RESPONSE',
+
+    /** 
+     * [单向发送] 触发即忘，只发不管
+     */
+    FIRE_AND_FORGET: 'FIRE_AND_FORGET'
+});
+module.exports = InteractionPattern

package/src/device/model/SchedulingStrategy.js

@@ -0,0 +1,13 @@
+/**
+ * 队列调度策略 (Scheduling Strategy)
+ * 决定了任务在队列中如何排序和出队
+ */
+const SchedulingStrategy = Object.freeze({
+    /** 顺序调度 (先进先出 FIFO) */
+    FIFO: 'FIFO',
+
+    /** 优先级调度 (按 Priority 字段排序) */
+    PRIORITY: 'PRIORITY'
+});
+
+module.exports = SchedulingStrategy