Workerman不支持串口通信，需用php_serial扩展或fopen+stream_select；POS机TCP通信须自定义协议解析器防粘包；入库需防重复与丢包，采集与业务逻辑必须分离。

硬件串口通信不能直接用Workerman内置组件

Workerman本身不提供串口（RS232/RS485）驱动能力，Workerman\Mqtt\Client、Workerman\MySQL\Connection 这类组件只覆盖网络协议栈。刷卡机/POS机若通过串口（如/dev/ttyUSB0）输出原始数据，必须借助PHP的fopen + fgets/stream_select，或更可靠的php_serial扩展（需编译安装）。直接在onWorkerStart里阻塞式fopen('/dev/ttyUSB0')会导致整个Worker进程卡死——这是最常踩的坑。

• 串口设备需提前配置好波特率、数据位、停止位、校验位（常见为9600-8-N-1），用stty -F /dev/ttyUSB0 9600 cs8 -cstopb -parenb验证
• 不要在onMessage或事件回调中做串口读写；应单独起一个子进程或用pcntl_fork隔离，避免阻塞EventLoop
• POS机若走TCP长连接（如银联标准TCP报文），可直接用Worker('tcp://0.0.0.0:8888')监听，此时Workerman原生支持

POS机TCP心跳与粘包必须手动处理

多数商用POS机上报数据时采用自定义TCP协议：无分隔符、定长头+变长体、或长度前缀（如前4字节为body长度）。Workerman默认的onMessage触发条件是收到完整TCP包，但网络层不保证“一次send对应一次recv”，容易把两条刷卡记录拼成一条乱码。

• 务必在Worker构造时指定protocol参数，例如new Worker('tcp://0.0.0.0:9001', ['protocol' => \Workerman\Protocols\Tcp::class])
• 继承\Workerman\Protocols\ProtocolInterface实现自定义解析器，重点重写input()方法：按长度头截取完整包，不足则返回0等待下一批数据
• 心跳检测不能依赖$connection->lastPingTime，POS机通常用固定字符串（如"HEARTBEAT"）或空包保活，需在onMessage里识别并$connection->send("PONG")

刷卡数据入库要防重复和丢包

硬件设备掉线重连时，POS机可能重发上一条交易（尤其金融类），而Workerman的onConnect回调里重建数据库连接，若直接INSERT会写入重复记录。同时，MySQL连接异常时$db->query()失败，错误被静默吞掉——线上环境常见“数据消失”现象。

• 给每条刷卡记录加唯一业务ID（如POS流水号+终端号），建UNIQUE KEY (pos_id, trace_no)，用INSERT IGNORE或ON DUPLICATE KEY UPDATE
• 数据库操作必须判空：if ($insert_id === false) { error_log("DB insert failed: " . $db->getError()); return; }
• 关键字段（金额、卡号）进库前做基础校验：is_numeric($amount)、strlen($card_no) >= 16，避免脏数据污染表结构

生产环境必须分离采集与业务逻辑

直接在onMessage里连MySQL、调第三方API、生成PDF小票，会导致Worker响应延迟升高，新连接排队，最终POS机因超时断连。Workerman的count设再高也救不了同步阻塞操作。

• 采集层只做：接收原始数据 → 解析成数组 → 推入Redis队列（LPUSH pos_raw_queue）→ 立即返回
• 另起一个独立的Worker进程（如processor.php）消费队列：BRPOP pos_raw_queue 0，再执行落库、通知、风控等耗时操作
• 用Worker::$pidFile区分进程角色，避免php processor.php restart误杀采集进程

串口设备的不可靠性远高于网络设备，所有读写操作都要带超时和重试，别相信“硬件稳定”这种说法。真正上线前，拿真实POS机连续跑48小时压力测试，重点看ps aux | grep php里Worker进程是否存活、Redis队列LEN是否持续增长。