charging-cabinet/tasks/003-tcp-server.md

任务003：TCP通讯服务

目标

实现TCP长连接服务，处理设备登录、签名验证、数据上报、指令下发。

技术栈

• Rust + Tokio
• TCP长连接

协议规范

通信规则

• 长连接，无需PING包
• 空闲1分钟上报，充电15秒上报
• 超时5000ms
• JSON去空格回车省流量，LF处理粘包
• dev_id：IMEI（10进制）
• sub_device_id：485 ID
• msg_id：自增会话ID

签名机制

• 设备首次连接调 auth_str 接口获取8位安全码（仅一次）
• sign = SHA256(dev_id + auth_str + timestamp).substring(56, 63)
• 时间戳秒级，平台校验±60秒

接口清单

动作	方向	说明
login	设备→平台	登录（需sign签名+timestamp）
auth_str	设备→平台	获取安全码（仅首次）
off	双向	停止供电
status_post	设备→平台	定时状态上报（rssi/status）
on	平台→设备	开始供电
open	平台→设备	开门（错误码63=门锁故障）
status_get	平台→设备	读取仓板状态
reset	平台→设备	设备重启
pow_fail	设备→平台	停电上报

实现要求

TCP Server

• 监听端口：3002（可配置）
• 连接管理：维护设备连接池
• 心跳检测：5000ms超时断开
• 粘包处理：LF分隔

登录流程

1. 设备发送 {"act":"login","dev_id":"IMEI","msg_id":1,"timestamp":xxx,"sign":"xxx"}
2. 平台验证签名
3. 验证通过 → 返回 {"suc":1,"msg_id":1}
4. 验证失败 → 返回 {"suc":0,"err":"签名错误"}

数据上报处理

• status_post：解析status HEX数据，存入Redis（实时）+ MySQL（持久化）
• pow_fail：记录停电日志

指令下发

• 提供API接口供HTTP服务调用
• 通过设备连接池下发指令
• 设备不在线时返回错误

项目结构

software/server/src/
├── tcp/
│   ├── mod.rs           # TCP服务入口
│   ├── server.rs        # TCP Server实现
│   ├── connection.rs    # 连接管理
│   ├── protocol.rs      # 协议解析
│   ├── handler.rs       # 消息处理
│   └── commands.rs      # 指令下发

质量约束

1. 完成代码后执行 cargo check，必须零报错、零警告
2. 分层拆分，单函数≤80行，命名语义化，完整注释
3. 所有外部IO/网络请求异常捕获，禁止裸panic
4. 分支逻辑全覆盖，不遗漏兜底分支
5. 常量抽离，不使用废弃API
6. Rust内存安全，合理管理所有权，禁用unsafe无合理理由