#mbt-hj212

##0140QN=20240115103000123;ST=31;CN=2011;PW=123456;MN=0100...DC0;Flag=5;CP=&&DataTime=...;a34013-Rtd=1.52&&3647\r\n
└┬─┘└──┘└──────────────────── 数据段 ────────────────────┘└──┘└─┘
包头 长度                                                 CRC  包尾

#为什么值得单独做一个

1. 长度字段按 UTF-8 字节数算，不是字符数。 数据区里出现一个中文（比如 Info=备用通道），按字符数算就会少 6 个字节，接收端随之错位到 CRC，整帧被丢。这个库里长度、CRC 共用同一套字节计数。
2. CP 的取值自己也用 ; 分隔字段。 把数据段直接按 ; 切开再找 CP，数据区会被撕成碎片。必须先定位 CP=，之前的按 ; 切字段，之后的整体交给数据区。
3. TCP 是字节流，粘包半包是常态。 一次 read 可能拿到两条半报文，也可能只拿到 ##01。分帧器必须能跨 read 保持状态。

#安装

moon add Mr-Houjie/mbt-hj212

#用法

#解码一条报文

match @hj212.Frame::decode(raw) {
  Ok(frame) => {
    println(frame.segment.cn)              // "2011"
    println(frame.segment.cp.get("a34013-Rtd"))  // Some("1.52")
  }
  Err(error) => println(error.message())   // 直接给人看的中文描述
}

• Frame::decode 只管结构——包头、长度、CRC、包尾。任何一项不对就拒绝整帧，绝不"尽力而为"地猜。
• Segment::validate 只管语义——MN 长度与版本是否匹配、Flag 声明分包却没带 PNUM/PNO 之类。这些不影响解码，只作为提示返回。

#流式分帧

let framer = @hj212.Framer::new()
for chunk in chunks {
  for event in framer.feed(chunk) {
    match event {
      @hj212.Good(frame) => handle(frame)
      @hj212.Bad(error, raw) => log(error, raw)
      @hj212.Noise(text) => ()          // 日志前缀、半包残片
    }
  }
}

#构造报文

let frame : @hj212.Frame = {
  segment: {
    qn: "20240115103000123",
    st: "31",
    cn: "2011",
    pw: "123456",
    mn: "010000A8900016F000169DC0",
    flag: @hj212.Flag::new(@hj212.V2017, false, true),
    pnum: None,
    pno: None,
    cp: @hj212.DataArea::new()
      ..set("DataTime", "20240115103000")
      ..set("a34013-Rtd", "1.52"),
    extra: [],
  },
}
println(frame.encode())

#命令行

mbt-hj212 explain <报文|文件>     逐字段解释一条报文
mbt-hj212 check   <报文|文件>     只校验，不合法时退出码 1
mbt-hj212 frames  <报文|文件>     按 TCP 流分帧，逐条列出
mbt-hj212 encode  [选项]          构造一条报文
mbt-hj212 crc     <数据段>        算数据段的 CRC 与字节长度

$ mbt-hj212 explain '##0140QN=20240115103000123;ST=31;CN=2011;PW=123456;MN=010000A8900016F000169DC0;Flag=5;CP=&&DataTime=20240115103000;a34013-Rtd=1.52;a34013-Flag=N&&3647'

长度    140 字节（数据段）
CRC     3647                          校验通过
版本    HJ 212-2017
Flag    5                             版本位 000001 · 不分包 · 需应答
QN      20240115103000123             2024-01-15 10:30:00.123
ST      31                            大气环境污染源
CN      2011                          污染物实时数据 · 双向
PW      123456
MN      010000A8900016F000169DC0      24 位
CP      3 项
  DataTime          20240115103000
  a34013-Rtd        1.52
  a34013-Flag       N

#语料自检

moon run cmd/verify

1. 合法帧必须能解码，且长度、CRC 与算法一致；
2. 解码再编码必须与原文件字节相同（往返一致）；
3. 非法帧必须被拒绝，且错误类型要与文件名前缀一致（BadCrc__xxx.frame 就必须报 BadCrc）。

#适用范围与已知偏差

#项目结构

types.mbt        公共类型：Version、Flag、DecodeError、Segment、Frame
text.mbt         字符/字节工具：UTF-8 计数、十六进制、显示宽度对齐
crc.mbt          CRC16/MODBUS
field_type.mbt   数据类型表：C4、N5、N14.2、YYYY/MM/DD/hh/mm/ss/zzz
data_area.mbt    数据区：&& 包装、名称=值、逗号分隔多值
segment.mbt      数据段：字段切分（先定位 CP=）、序列化、语义校验
time.mbt         QN 时间戳
frame.mbt        帧编解码 + 流式分帧器
commands.mbt     命令码表（表 9）
explain.mbt      逐字段解释，供 CLI 使用
corpus/          语料与生成脚本
cmd/main/        命令行
cmd/verify/      语料自检

#测试

moon test              # 20 个单元测试
moon run cmd/verify    # 26 个语料用例

#许可