CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

JMS 透析机 TCP 联机服务 — 管理与监控多台 GC-110N 透析设备。基于持久 TCP 长连接 + 定时 K 轮询，实时采集 32 项治疗参数，通过 MQTT / 阿里云 IoT 上传，并提供 Web 监控大屏。

运行命令

npm start                 # 启动联机服务 + Dashboard

架构

index.js (入口)
├── lib/logger.js            日志（单文件 service.YYYY-MM-DD.log，30 天保留）
├── lib/data-cache.js        内存数据缓存（Map<ip, deviceData>），变更时通知监听者
├── lib/device-manager.js    管理所有设备的启停，遍历 config.devices 创建连接
│   └── lib/device-connection.js  单设备 TCP 长连接 + K 轮询 + 重连
│       └── lib/protocol.js       GC-110N K 格式解析（无校验和、CRLF 切帧、顺序无关解析器）
├── lib/upload/index.js      上传总控（顺序执行 MQTT → 阿里云）
│   ├── lib/upload/mqtt-uploader.js    MQTT 单例客户端，topic: {prefix}/{deviceNo}
│   ├── lib/upload/aliyun-uploader.js  阿里云 IoT SDK 设备实例池，postProps 上报
│   │   └── lib/upload/tuple-api.js    HTTP 请求三元组 API（60s 失败冷却）
│   └── lib/upload/field-mapper.js     GC-110N ID → 阿里云 identifier 映射
└── dashboard/server.js      HTTP + WebSocket 服务，每 2s 推送快照
    └── dashboard/public/index.html   监控大屏单页

数据流

1. DeviceManager.startAll() 遍历 config.devices，为每台启用设备创建 DeviceConnection
2. DeviceConnection 建立 TCP 长连接 → 发 K 请求 → 定时轮询
3. 收到 K 响应后：解析 32 字段 → 写 DataCache → 调 UploadManager.upload()
4. UploadManager 将 items 按中文名映射为阿里云字段，构建 payload，顺序上传 MQTT 和阿里云
5. Dashboard 通过 WebSocket 每 2 秒推送全量快照（设备列表 + 汇总 + 上传状态）

协议要点 (GC-110N K 格式)

• 格式：K + 4位statusCode + [单字母ID + 定宽值]... + CRLF
• 无校验和，帧尾 \r\n 切包
• 32 个字段，S（血压测量时刻）变长（查下一个已知 ID 定界），其余字段固定宽度
• 解析器顺序无关——读 ID 字符 → 查宽度 → 取对应长度值，不依赖设备字段顺序

配置 (config.json)

• pollIntervalMs: K 轮询间隔（默认 10s）
• connectTimeoutMs: TCP 握手超时（手动计时，不用 socket timeout 以免切断长连接）
• reconnectBaseMs / reconnectMaxMs: 重连退避基数/上限
• devices: 设备列表（ip/port/serialNumber/enabled）
• mqtt.enabled / aliyun.enabled: 上传开关（默认禁用）

日志关键字

• → 发送 K 请求
• ← 收到 K 响应（含原始报文）
• ✂ TCP 断开
• ↻ 计划重连
• ↑ 上传成功
• [mqtt/...] / [aliyun/...] 上传通道事件

字段映射

GC-110N 单字母 ID 到阿里云物模型 identifier，按中文名称对应。映射表见 lib/upload/field-mapper.js。新增字段需两边同步——阿里云侧需先在物模型 TSL 中添加对应 identifier。