# 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 监控大屏。

## 运行命令

```bash
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。