mbt-hj212

    HJ 212 报文 → 可入库的时序数据:流式分帧、分包重组、协议无关数据模型、规则校验引擎、JSON/CSV/InfluxDB 导出与端到端管道。核心零依赖。

    hj212
    time-series
    data-quality
    protocol
    codec
    etl
    iot
    cli
    Download zip
    Author
    Version
    0.2.0
    License
    MIT
    Last updated
    15 hours ago
    Downloads
    32

    #mbt-hj212

    把 HJ 212 报文变成能直接入库的时序数据。

    ##0140QN=...;CP=&&DataTime=...;a34013-Rtd=1.52&&3647\r\n │ ├ 分帧 ── TCP 字节流 → 一条条完整帧(跨 read 保持状态) ├ 解码 ── 长度 / CRC / 包尾校验,分包按包号重组 ├ 数据点 ── 帧 → Point{时间, 来源, 测量, 字段},与协议无关 ├ 校验 ── 规则引擎,输出「哪个字段、为什么」而不是一个布尔值 └ 导出 ── JSON / NDJSON / CSV / InfluxDB line protocol

    核心库零依赖,只用 MoonBit 标准库。

    #这个库分两层,只有一层跟环保有关

    协议细节在 HJ 212 上:长度字段按 UTF-8 字节算、CP 取值自己也用 ; 分隔、TCP 粘包半包。这些坑必须踩对,踩错了不会报错,只会静默丢数据。

    但报文解开之后要做的事,跟环保没有关系。record.mbt / quality.mbt / sink.mbt / pipeline.mbt 这四个模块不认识 HJ 212 的任何字段:

    模块内容谁能用
    record.mbtPoint / Field / Value / Quality,缺失与零严格分开任何时序采集:传感器、日志事件、指标
    quality.mbt规则引擎:量程、必填、数值类型、取值白名单,含文本规则配置任何需要判断「这个数可信吗」的场景
    sink.mbtJSON / NDJSON / CSV / InfluxDB line protocol,手写转义任何要把数据交给下游系统的场景
    pipeline.mbt上面几步串成一次 feed,附全程计数抓包回放、离线批处理、在线流处理

    Frame::to_point() 是唯一的适配函数——把一条 HJ 212 帧翻译成通用的 Point。换一种协议,只需要再写一个这样的函数,后面的校验与导出原样复用。

    let p = @hj212.Point::new("2024-01-15T10:30:00", "sensor-01", "cpu")
    p.add("load", @hj212.Num(0.5))
    p.add("status", @hj212.Text("N"))
    p.add("spare", @hj212.Missing) // 缺失,不是 0

    let (rules, _) = @hj212.RuleSet::from_text(
    "range load 0 1\nrequired status\nallowed status N,T,B,D\n",
    )
    for f in rules.check(p) {
    println(f.text()) // [warning] status: 未登记的取值 "Z"
    }
    println(p.to_json()) // {"timestamp":...,"fields":{"load":[0.5],...}}
    println(p.to_influx_line()) // cpu,source=sensor-01 load=0.5,status="N"

    #为什么值得单独做一个

    HJ 212 是国内污染源在线监测联网的强制标准,全国每一台数采仪都在按它往生态环境部门的平台报送数据。协议本身不难,难的是它有三处地方特别容易实现错:

    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 之类。这些不影响解码,只作为提示返回。

    DecodeError::kind() 给出稳定的错误标识("BadCrc"、"Truncated"……),适合写日志或做分支;message() 是给人看的中文描述;stage() 说明错误落在哪一层——帧层出错整条必须丢弃,数据段层和数据区层的报文边界是好的,可以单独排查。

    #取数据项

    let cp = frame.segment.cp cp.get("a34013-Rtd") // Some("1.52") cp.get_float("a34013-Rtd") // Some(1.52) cp.get_int("RtdInterval") // Some(30) cp.get_or("Info", "(无备注)") // 缺失时的默认值

    get_float / get_int 在取值是 N(标准里表示无有效数据)时返回 None,不会变成 0——0 是一个合法的监测值,两者不能混。

    #转成数据点

    let point = frame.to_point()
    point.timestamp // QN 解析成 "2024-01-15 10:30:00.123",解析不了就保留原文
    point.source // MN
    point.measurement // CN
    point.quality // Good / Suspect / Invalid
    point.number("a34013-Rtd") // Some(1.52)

    point.to_json() // 一行 JSON
    point.to_csv_row(cols) // 一行 CSV
    point.to_influx_line() // 一行 InfluxDB line protocol

    三个判断写在这里,都不静默丢数据:

    • N 与空值映射成 Value::Missing,不是 0。采集现场最常见的错就是把缺失当 0 入库,之后所有统计被悄悄拉偏。
    • 语义有问题(MN 长度不对、分包声明不一致)降级为 Suspect,照样输出;只有整帧一个有效值都没有才标 Invalid。
    • 同名多值不覆盖,Field::values 保留全部。实时数据里一项多采是常态,只取第一个就丢数据。

    #规则校验

    let (rules, errors) = @hj212.RuleSet::from_text(
    "range a34013-Rtd 0 500\nrequired DataTime\nallowed a34013-Flag N,T,B,D,F,S\n",
    )
    let findings = rules.check(point)
    for f in findings {
    println(f.text()) // [error] a34013-Rtd: 数值 812.5 超出允许区间 [0, 500]
    }

    输出是问题清单而不是布尔值。缺字段时只报一次「缺少必需字段」,不会再报一遍「越界」——同一个根因报两遍,报告反而看不出根因。文本配置写错的行会被原样报出来,不静默忽略。

    #端到端管道

    let pipe = @hj212.Pipeline::new(rules, @hj212.Ndjson, [])
    for chunk in chunks {
    for out in pipe.feed(chunk) {
    save(out.line) // 已渲染好的一行
    log(out.findings) // 这条数据的全部问题
    }
    }
    println(pipe.stats().text()) // 帧 / 拒绝 / 数据点 / 问题 / 溢出 / 未完成分包组

    分包帧不会逐片吐数据点:先送进重组器,收齐后拼成一条完整记录再输出,上层拿到的永远是逻辑完整的一条。

    #流式分帧

    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) => () // 日志前缀、半包残片
    }
    }
    }

    feed 返回的是数组,一次喂入可能吐出多条帧。不足一帧的部分留在 framer.pending() 里等下一次。

    缓冲区有上限(默认 16 KiB)。对端声明了长度却始终补不齐数据时,超限会得到 Overflow 事件并清空残留,不会无限攒下去。

    #分包重组

    历史数据动辄几十包,Flag 的分包位 + PNUM / PNO 标识分包。Reassembler 负责按包号拼回去:

    let r = @hj212.Reassembler::new() for frame in frames { match r.push(frame) { @hj212.NotSplit => () // 不是分包帧 @hj212.Pending(got, n) => println("\{got}/\{n}") @hj212.Complete(area) => save(area) // 收齐,按包号升序拼接 @hj212.Conflict(reason) => log(reason) } } r.missing() // 还缺哪些包号 r.dropped() // 因换组而丢弃的未完成组数

    组键是 MN + CN + QN:同一台设备、同一种命令、同一时刻的多帧才属于同一条逻辑报文。分包协议本身不含重传,丢包只能由上层重新请求,所以 dropped() 必须让调用方看得见。

    #构造报文

    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())

    encode 会重新生成数据段(而不是复用输入原文),所以输出是规范形式:字段顺序固定、&& 包装一定存在、CRC 与长度一定自洽。

    #命令行

    mbt-hj212 explain <报文|文件> 逐字段解释一条报文 mbt-hj212 check <报文|文件> 只校验,不合法时退出码 1 mbt-hj212 frames <报文|文件> 按 TCP 流分帧,逐条列出 mbt-hj212 pack <报文|文件> 把分包帧按包号重组成完整数据区 mbt-hj212 convert <报文|文件> [选项] 转成 JSON / NDJSON / CSV / InfluxDB mbt-hj212 quality <报文|文件> [选项] 按规则校验,列出问题清单 mbt-hj212 stats <报文|文件> [选项] 输出全链路处理统计 mbt-hj212 encode [选项] 构造一条报文 mbt-hj212 crc <数据段> 算数据段的 CRC 与字节长度

    convert / quality / stats 共用 --format、--columns、--rules 三个选项,所以「转换出来的数据」和「校验判定」不会各说各话。

    $ mbt-hj212 convert corpus/good/2011__real-time-gas.frame --format csv \ --columns DataTime,a34013-Rtd,a34013-Flag timestamp,source,measurement,quality,DataTime,a34013-Rtd,a34013-Flag 2024-01-15 10:30:00.123,010000A8900016F000169DC0,2011,good,20240115103000,1.52,N $ mbt-hj212 quality corpus/edge/many-items.frame --rules corpus/rules/demo.rules 2024-01-15 10:30:00.123 010000A8900016F000169DC0 CN=2011 [good] [error] DataTime: 缺少必需字段 数据点 1 · 问题 1(错误 1,警告 0,提示 0)· 解码失败 0

    convert 只把数据写进标准输出,不掺统计行,方便直接重定向或接管道。quality 有 Error 级问题时退出码 1,能直接当 CI 门禁。

    explain 把一条报文摊成表,每一行都标出来源:

    $ 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

    命令行直接粘报文时末尾的 \r\n 常被终端吃掉,explain/check/frames 会自动补一次;库层保持严格,不做这种妥协。

    #语料自检

    moon run cmd/verify

    corpus/ 下的帧是文件,不是代码里的字符串常量。自检会:

    1. 合法帧必须能解码,且长度、CRC 与算法一致;
    2. 解码再编码必须与原文件字节相同(往返一致);
    3. 非法帧必须被拒绝,且错误类型要与文件名前缀一致(BadCrc__xxx.frame 就必须报 BadCrc);
    4. split/ 下同前缀的分包帧必须能重组成一条完整数据区;
    5. stream/ 下混着正常帧、坏帧、分包与噪声的整段流,用管道跑一遍,核对帧数 / 拒绝数 / 数据点数;
    6. rules/ 下的规则配置必须零语法错误,且对已知有问题的报文必须命中期数量的错误。

    第 3 条是这个命令的价值所在。它把"我以为它会报错"变成了可执行断言。开发过程中它抓出了两个真实缺陷——重复字段被静默接受、缺少 && 包装的 CP 被当成合法数据区。

    语料由 corpus/generate.py 生成。这个脚本不复用 MoonBit 实现,而是用 Python 重写一遍 CRC16/MODBUS,让校验码来自一套独立实现。两边算得不一样,生成阶段就会暴露。

    #适用范围与已知偏差

    关于标准附录的 CRC 示例。 HJ 212-2017 附录 A 的示例报文,数据段是 QN=20160801085857223;...;CP=&&RtdInterval=30&&,标注的校验码是 1C80。按附录 A 自己给出的算法(初值 0xFFFF、反向多项式 0xA001、无最终异或)算同一段,得到的是 0759。穷举初值、多项式、正向/反向、最终异或、多种子串切片都无法得到 0x1C80。判断是示例沿用了旧稿。

    本库以算法为准,因此会拒绝 1C80 并报出正确值 0759。这一条写在测试里(标准附录示例的校验码与算法不一致),不是悄悄绕过。

    命令表与系统编码表。 逐条对照 HJ 212-2017 表 9 与表 5 录入,没有采用现场口头叫法。例如 2011 是「污染物实时数据」(取与上传共用同一码),2041 是「设备运行时间日历史数据」而不是又一个「日数据」;ST=32 是「地表水体环境污染源」(水质),烟气是 ST=31,烟气工况是 ST=51。这三处都是常见误记,代码里有专门的回归测试盯着。

    版本号。 Flag 的 V5–V0 位:000000 是 HJ/T 212-2005,000001 是 HJ 212-2017,000010 是 HJ 212-2025。注意 2017 与 2025 两次修订把最后两位的字母换过名(2017 写作 D=分包、A=应答,2025 写作 A=分包、D=应答),位权没变。本库只按位权判断,不引用字母。

    没有做的部分。 监测因子编码表(附录 B,水/气各数百项)没有收录——那是查表数据而不是协议逻辑,塞进库只会让包变大。数据区里的因子名按不透明字符串处理,DataArea::get("a34013-Rtd") 照样能用。规则引擎也不预置任何行业规则:量程该设多少是现场的事,不是库的事。

    #项目结构

    record.mbt 协议无关数据模型:Point / Field / Value / Quality quality.mbt 规则引擎:量程 / 必填 / 数值类型 / 取值白名单 + 文本配置 sink.mbt 导出:JSON / NDJSON / CSV / InfluxDB,手写转义 pipeline.mbt 端到端管道:一次 feed 走完全流程,附计数 types.mbt 公共类型:Version、Flag、DecodeError、ErrorStage、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 帧编解码 + 流式分帧器 reassemble.mbt 分包重组 commands.mbt 命令码表(表 9) explain.mbt 逐字段解释,供 CLI 使用 corpus/ 语料、规则配置、生成脚本 cmd/main/ 命令行 cmd/verify/ 语料与管道自检

    前四个文件不 import 任何协议概念,可以单独拿去做别的采集场景。

    #测试

    moon test # 97 个单元测试(含对抗性测试) moon run cmd/verify # 32 个语料用例(含 2 组分包重组、1 段混合流、1 份规则配置) moon check --deny-warn # 零告警

    #开发历程

    选题为什么从文本换行换到 HJ 212、为什么第二次又把重心从「协议解析」挪到「数据管道」、AI 在哪儿帮了倒忙、测试抓出过哪三个真 bug,都记在 DEVLOG.md。

    #许可

    MIT

    CommandInfo

    pub(all) struct CommandInfo {
    code : String
    name : String
    direction : Direction
    note : String
    }

    CommandInfo::text

    fn CommandInfo::text(self : CommandInfo) -> String

    DataArea

    pub(all) struct DataArea {
    items : Array[DataItem]
    }

    指令参数(CP)的数据区。

    序列化时按标准约定:同项多值用 , 连接,不同项用 ; 连接。

    DataArea::get

    fn DataArea::get(self : DataArea, name : String) -> String?

    取某个字段的第一个值。

    DataArea::get_all

    fn DataArea::get_all(self : DataArea, name : String) -> Array[String]

    取某个字段的全部值。

    DataArea::get_float

    fn DataArea::get_float(self : DataArea, name : String) -> Double?

    把字段值当浮点数读。

    监测值形如 1.52、-3.00、0;无有效数据时现场会写 N,此时返回 None。不接受科学计数法——标准里的数值类型(N14.2 等)没有这种写法, 放进来只会掩盖「对方发的不是这个字段」的问题。

    DataArea::get_int

    fn DataArea::get_int(self : DataArea, name : String) -> Int?

    把字段值当整数读。

    常见于 RtdInterval、Flag 一类整数字段。返回 None 有两种情况: 字段不存在,或者取值不是整数——包括标准里用 N / U 表示 「无有效数据」的那种写法,此时上层应当按缺失处理而不是当成 0。

    DataArea::get_or

    fn DataArea::get_or(self : DataArea, name : String, fallback : String) -> String

    取某个字段的值,不存在时返回给定的默认值。

    DataArea::has

    fn DataArea::has(self : DataArea, name : String) -> Bool

    字段是否出现。

    DataArea::length

    fn DataArea::length(self : DataArea) -> Int

    字段个数。

    DataArea::new

    fn DataArea::new() -> DataArea

    DataArea::parse

    fn DataArea::parse(text : String) -> Result[DataArea, DecodeError]

    解析数据区文本。

    接受带 &&...&& 包装的形式,也接受裸数据区(便于单独测试数据区)。

    DataArea::remove

    fn DataArea::remove(self : DataArea, name : String) -> Bool

    删除某个字段,返回是否真的删掉了。

    DataArea::set

    fn DataArea::set(self : DataArea, name : String, value : String) -> Unit

    追加或覆盖一个单值字段。

    DataArea::set_values

    fn DataArea::set_values(self : DataArea, name : String, values : Array[String]) -> Unit

    追加或覆盖一个多值字段。

    DataArea::text

    fn DataArea::text(self : DataArea) -> String

    渲染成规范形式(不含 && 包装)。

    DataArea::wrapped_text

    fn DataArea::wrapped_text(self : DataArea) -> String

    渲染成报文里的 CP 取值,带 && 包装。

    DataItem

    pub(all) struct DataItem {
    name : String
    values : Array[String]
    }

    数据区中的一项:名称=值,同一项可以有多个用 , 分隔的值。

    DecodeError

    pub(all) enum DecodeError {
    MissingHeader
    BadLengthField(String)
    Truncated(Int, Int)
    BadCrc(String, String)
    BadTail(String)
    EmptySegment
    MissingField(String)
    DuplicateField(String)
    BadField(String)
    BadFieldValue(String, String)
    BadDataArea(String)
    TrailingGarbage(String)
    }

    解码失败的原因。

    结构性错误(包头、长度、CRC、包尾)一律视为失败并拒绝该帧; 字段取值是否符合行业惯例属于语义问题,交由 Segment::validate 报告, 两者刻意分开。

    DecodeError::is_structural

    fn DecodeError::is_structural(self : DecodeError) -> Bool

    是否为帧层错误。

    帧层出错意味着连「这条报文到哪里结束」都不可信,因此不能继续复用 这条报文里的任何字段;其余两层的报文边界是好的,字段或数据区可以 单独排查。

    DecodeError::kind

    fn DecodeError::kind(self : DecodeError) -> String

    稳定的错误码,供上层程序分支判断或写日志用。

    与 message() 的区别:message() 是给人看的中文描述,措辞可能随版本调整; kind() 是给程序看的标识,一旦发布就不再变化。

    DecodeError::message

    fn DecodeError::message(self : DecodeError) -> String

    DecodeError::stage

    fn DecodeError::stage(self : DecodeError) -> ErrorStage

    错误所在的层。

    Direction

    pub(all) enum Direction {
    Down
    Up
    Both
    }

    Direction::label

    fn Direction::label(self : Direction) -> String

    ErrorStage

    pub(all) enum ErrorStage {
    FrameLayer
    SegmentLayer
    DataAreaLayer
    }

    错误发生在哪一层。

    分层不是为了分类好看,而是因为三层的处置方式完全不同: 帧层出错说明字节流已经不可信,这条报文必须整条丢弃; 数据段层出错说明帧的边界是对的、字段内容有问题; 数据区层出错说明字段都在,只是 CP 里面的结构不对。 网关通常只关心第一层,数据中心三层都要记。

    ErrorStage::label

    fn ErrorStage::label(self : ErrorStage) -> String

    Field

    pub(all) struct Field {
    name : String
    values : Array[Value]
    }

    一个数据项:名称 + 一个或多个取值。

    允许多个取值,因为现场协议里同一项的多次采样用逗号分隔, 擅自只取第一个会丢数据。

    Field::first

    fn Field::first(self : Field) -> Value

    Field::new

    fn Field::new(name : String) -> Field

    Field::numbers

    fn Field::numbers(self : Field) -> Array[Double]

    这一项的全部数值(非数值取值被跳过)。

    FieldType

    pub(all) enum FieldType {
    Chars(Int)
    Number(Int, Int)
    Year
    Month
    Day
    Hour
    Minute
    Second
    Millisecond
    }

    数据项的数据类型,对应标准 6.3.3.2.2 的类型定义表。

    • C4 表示最多 4 位的字符串;
    • N5 表示最多 5 位数字;
    • N14.2 表示 14 位整数与 2 位小数,带符号,最大长度 18;
    • YYYY / MM / DD / hh / mm / ss / zzz 表示时间片段。

    FieldType::check

    fn FieldType::check(self : FieldType, value : String) -> String?

    校验取值是否满足类型;满足返回 None,否则返回原因。

    FieldType::parse

    fn FieldType::parse(text : String) -> FieldType?

    解析类型字符串,例如 C4、N5、N14.2、YYYY。

    FieldType::text

    fn FieldType::text(self : FieldType) -> String

    把类型渲染回字符串形式。

    Finding

    pub(all) struct Finding {
    severity : Severity
    field : String
    message : String
    }

    一条校验结果。

    Finding::text

    fn Finding::text(self : Finding) -> String

    Flag

    pub(all) struct Flag {
    raw : Int
    }

    报文的 Flag 字段,一个 8 位无符号整数。

    位布局(高位到低位):V5 V4 V3 V2 V1 V0 | 分包位 | 应答位

    • V5..V0:标准版本号,000000 = 2005 版,000001 = 2017 版,000010 = 2025 版;
    • bit1:数据段是否携带 PNUM / PNO 分包序号;
    • bit0:本条命令是否需要应答。

    注意:这两位的字母在两次修订里换过名。2017 版写作 D(分包) 与 A(应答),2025 版写作 A(分包)与 D(应答)。位权没有变, 变的只是字母,这也是最容易抄错的一处;本库只按位权判断,不引用字母。

    例:Flag=9 即 00001001,表示 2025 版、不分包、需要应答。

    Flag::from_raw

    fn Flag::from_raw(raw : Int) -> Flag

    Flag::is_split

    fn Flag::is_split(self : Flag) -> Bool

    Flag::needs_ack

    fn Flag::needs_ack(self : Flag) -> Bool

    Flag::new

    fn Flag::new(version : Version, split : Bool, ack : Bool) -> Flag

    Flag::text

    fn Flag::text(self : Flag) -> String

    Flag::version

    fn Flag::version(self : Flag) -> Version

    Format

    pub(all) enum Format {
    Json
    Ndjson
    Csv
    Influx
    }

    impl Eq for Format

    Format::equal

    fn Format::equal(self : Format, other : Format) -> Bool

    Format::label

    fn Format::label(self : Format) -> String

    Format::not_equal

    fn Format::not_equal(x : Format, y : Format) -> Bool

    Format::parse

    fn Format::parse(text : String) -> Format?

    Frame

    pub(all) struct Frame {
    segment : Segment
    }

    一条完整的报文。

    Frame::check

    fn Frame::check(text : String) -> Result[Int, DecodeError]

    只做校验,成功时返回数据段长度。

    Frame::decode

    fn Frame::decode(text : String) -> Result[Frame, DecodeError]

    解码一条报文。

    严格校验:包头、长度、CRC、包尾全部通过才算成功。字段取值范围是否 符合行业惯例不在这一步判断,交给 Segment::validate。

    Frame::encode

    fn Frame::encode(self : Frame) -> String

    编码一条报文。

    数据段由字段重新生成(而不是复用输入原文),因此输出是规范形式, 空格、字段顺序、&& 包装都会被归一化。

    Frame::explain

    fn Frame::explain(self : Frame) -> String

    一条报文的逐字段解释。

    Frame::summary

    fn Frame::summary(self : Frame) -> String

    一条报文的单行摘要,适合日志与批量扫描。

    Frame::to_point

    fn Frame::to_point(self : Frame) -> Point

    把一条 HJ 212 报文转成协议无关的数据点。

    FrameEvent

    pub(all) enum FrameEvent {
    Good(Frame)
    Bad(DecodeError, String)
    Noise(String)
    Overflow(Int)
    }

    流式分帧的结果。

    Framer

    pub(all) struct Framer {
    buffer : String
    max_pending : Int
    }

    增量分帧器。

    现场设备按 TCP 流发送,一次 read 可能拿到半条报文,也可能拿到三条半。 分帧器负责在任意切分点保持状态:喂进去一段文本,吐出这段文本里能确认的 全部事件,剩下的留在缓冲区里等下一段。

    关于缓冲区上限:不含 ## 的字节会立刻作为 Noise 抛出、不留在缓冲区, 所以脏流本身撑不爆它。会堆积的是另一种情形——对端声明了长度却始终补不齐 数据(例如 ##9999 之后只发了几个字节),缓冲区会一直等到声明长度。 长度字段上限 9999,理论上界约 10 KB;max_pending 是把这件事写成显式 契约,超限即丢弃并抛出 Overflow,避免逻辑改动后悄悄退化成无界缓存。

    Framer::feed

    fn Framer::feed(self : Framer, chunk : String) -> Array[FrameEvent]

    喂入一段文本,返回能确认的事件。

    Framer::limit

    fn Framer::limit(self : Framer) -> Int

    缓冲区上限。

    Framer::new

    fn Framer::new() -> Framer

    Framer::pending

    fn Framer::pending(self : Framer) -> Int

    缓冲区里尚未成帧的字节数。

    Framer::reset

    fn Framer::reset(self : Framer) -> Int

    主动清空缓冲区里无法成帧的残留,返回丢弃的字节数。

    调用方发现 pending() 长期不下降时可以调用,例如在连接空闲超时、 或者已经判定对端不是 HJ 212 设备时。

    Framer::with_limit

    fn Framer::with_limit(max_pending : Int) -> Framer

    指定缓冲区上限(字节)。小于 1024 会被抬到 1024, 因为再小就装不下一条中等长度的合法报文了。

    Output

    pub(all) struct Output {
    point : Point
    findings : Array[Finding]
    line : String
    }

    一条产出:数据点、校验结果、按目标格式渲染好的一行。

    Part

    pub(all) struct Part {
    pno : Int
    cp : DataArea
    }

    一个已收到的分包。

    Pipeline

    pub struct Pipeline {
    framer : Framer
    reassembler : Reassembler
    rules : RuleSet
    format : Format
    columns : Array[String]
    stats : Stats
    group_meta : Point?
    }

    管道本体。构造后反复 feed 即可,内部保留分帧与重组的残余状态。

    Pipeline::feed

    fn Pipeline::feed(self : Pipeline, chunk : String) -> Array[Output]

    喂入一段文本,返回这段文本里能确认的全部产出。

    分包帧不会逐片出数据点:会先送进重组器,收齐后按包号拼成一条 完整数据点再输出。这样上层拿到的永远是逻辑完整的一条记录。

    Pipeline::format

    fn Pipeline::format(self : Pipeline) -> Format

    Pipeline::header

    fn Pipeline::header(self : Pipeline) -> String

    Pipeline::new

    fn Pipeline::new(rules : RuleSet, format : Format, columns : Array[String]) -> Pipeline

    Pipeline::run

    fn Pipeline::run(self : Pipeline, text : String) -> String

    一次性处理整段文本,返回渲染结果。

    刻意复用 feed,而不是另写一遍:统计口径与流式调用必须完全一致, 否则「批量跑一遍看看」和「上线跑流」会得到两套数字。

    Pipeline::stats

    fn Pipeline::stats(self : Pipeline) -> Stats

    Point

    pub(all) struct Point {
    timestamp : String
    source : String
    measurement : String
    fields : Array[Field]
    quality : Quality
    }

    一个时序数据点:某一时刻、某个来源、某类测量下的一组字段。

    字段名不预设任何行业字典:a34013-Rtd、cpu_load、temp_c 在这里地位相同。上层想解释监测因子编码,是上层的事。

    Point::add

    fn Point::add(self : Point, name : String, value : Value) -> Unit

    追加一个取值。同名项会归到同一个 Field 下,不覆盖先前的值。

    Point::add_area

    fn Point::add_area(self : Point, area : DataArea) -> Unit

    把一个数据区的全部项追加进来(分包重组后的合并数据区用得上)。

    Point::count_values

    fn Point::count_values(self : Point) -> Int

    Point::field

    fn Point::field(self : Point, name : String) -> Field?

    Point::field_count

    fn Point::field_count(self : Point) -> Int

    Point::new

    fn Point::new(timestamp : String, source : String, measurement : String) -> Point

    Point::number

    fn Point::number(self : Point, name : String) -> Double?

    取某个字段的第一个数值。缺失、文本、字段不存在都返回 None。

    Point::set_quality

    fn Point::set_quality(self : Point, quality : Quality) -> Unit

    Point::to_csv_row

    fn Point::to_csv_row(self : Point, columns : Array[String]) -> String

    CSV 数据行(不含表头)。

    Point::to_influx_line

    fn Point::to_influx_line(self : Point) -> String

    渲染成一行 InfluxDB line protocol。

    刻意不带时间戳:QN 是本地时钟且精度只有毫秒,硬转成纳秒会制造 一个看起来精确、实际不可信的时间。需要原始采样时间请用 NDJSON, 时间戳保留在 timestamp 字段里。

    Point::to_json

    fn Point::to_json(self : Point) -> String

    渲染成一行 JSON 对象。

    QnTime

    pub(all) struct QnTime {
    year : Int
    month : Int
    day : Int
    hour : Int
    minute : Int
    second : Int
    millis : Int
    }

    QnTime::parse

    fn QnTime::parse(qn : String) -> QnTime?

    QnTime::text

    fn QnTime::text(self : QnTime) -> String

    渲染成 YYYY-MM-DD hh:mm:ss.zzz。

    QnTime::to_qn

    fn QnTime::to_qn(self : QnTime) -> String

    由分段时间构造 QN。

    Quality

    pub(all) enum Quality {
    Good
    Suspect
    Invalid
    }

    整条数据的可信程度。
    impl Eq for Quality

    Quality::equal

    fn Quality::equal(self : Quality, other : Quality) -> Bool

    Quality::label

    fn Quality::label(self : Quality) -> String

    Quality::not_equal

    fn Quality::not_equal(x : Quality, y : Quality) -> Bool

    ReassembleResult

    pub(all) enum ReassembleResult {
    NotSplit
    Pending(Int, Int)
    Complete(DataArea)
    Conflict(String)
    }

    分包重组的结果。

    Reassembler

    pub(all) struct Reassembler {
    key : String
    total : Int
    parts : Array[Part]
    dropped : Int
    }

    分包重组器。

    同一组分包由 MN + CN + QN 三者共同标识:同一台设备(MN)、 同一种命令(CN)、同一时刻(QN)上报的多帧才属于同一条逻辑报文。 三者中任一变化即视为新的一组。

    Reassembler::dropped

    fn Reassembler::dropped(self : Reassembler) -> Int

    因换组而丢弃的未完成组数。

    上一组还没收齐,下一组的帧就到了——说明中间有丢包或乱序跨越了组边界。 这个计数让调用方能区分「正常处理」和「一直在丢」。

    Reassembler::missing

    fn Reassembler::missing(self : Reassembler) -> Array[Int]

    当前组还缺哪些包号,按升序返回。未开始收包时返回空数组。

    Reassembler::new

    Reassembler::push

    fn Reassembler::push(self : Reassembler, frame : Frame) -> ReassembleResult

    推入一帧。

    Reassembler::received

    fn Reassembler::received(self : Reassembler) -> Int

    已收到但尚未拼成完整报文的组数(0 或 1)。

    Reassembler::reset

    fn Reassembler::reset(self : Reassembler) -> Unit

    清空当前组。

    Reassembler::total

    fn Reassembler::total(self : Reassembler) -> Int

    当前组声明的总包数,未开始收包时为 0。

    Rule

    pub(all) enum Rule {
    Range(String, Double, Double)
    Required(String)
    Numeric(String)
    AllowedText(String, Array[String])
    }

    一条规则。

    Rule::text

    fn Rule::text(self : Rule) -> String

    RuleSet

    pub(all) struct RuleSet {
    rules : Array[Rule]
    }

    一组规则。

    RuleSet::add

    fn RuleSet::add(self : RuleSet, rule : Rule) -> Unit

    RuleSet::check

    fn RuleSet::check(self : RuleSet, point : Point) -> Array[Finding]

    校验一个数据点,返回全部发现的问题。

    分工:Range 只管数值越界,Required 只管缺失,Numeric 只管类型。 缺字段时 Range 不重复报一次「越界」,否则同一个问题会在报告里 出现两遍,反而看不出根因。

    RuleSet::from_text

    fn RuleSet::from_text(text : String) -> (RuleSet, Array[String])

    解析文本配置。语法不对的行原样跳过并返回说明,不静默忽略。

    RuleSet::length

    fn RuleSet::length(self : RuleSet) -> Int

    RuleSet::new

    fn RuleSet::new() -> RuleSet

    Segment

    pub(all) struct Segment {
    qn : String
    st : String
    cn : String
    pw : String
    mn : String
    flag : Flag
    pnum : Int?
    pno : Int?
    cp : DataArea
    extra : Array[DataItem]
    }

    数据段:一条命令的固定头部加上指令参数。

    字段顺序按标准固定为 QN;ST;CN;PW;MN;Flag;PNUM;PNO;CP。 pnum / pno 只在 Flag 的 D 位为 1 时出现;extra 用来保留 现场设备自行追加的扩展字段,保证解码后再编码不会丢信息。

    Segment::parse

    fn Segment::parse(text : String) -> Result[Segment, DecodeError]

    Segment::text

    fn Segment::text(self : Segment) -> String

    渲染成规范的数据段文本。

    Segment::validate

    fn Segment::validate(self : Segment) -> Array[String]

    语义检查。

    结构性问题在 parse 阶段就会失败;这里报的是「能解析但不符合行业惯例」 的情况,例如 MN 长度与版本不匹配、Flag 声明分包却没有包号。 返回空数组表示没有发现问题。

    Severity

    pub(all) enum Severity {
    Info
    Warning
    Error
    }

    impl Eq for Severity

    Severity::equal

    fn Severity::equal(self : Severity, other : Severity) -> Bool

    Severity::label

    fn Severity::label(self : Severity) -> String

    Severity::not_equal

    fn Severity::not_equal(x : Severity, y : Severity) -> Bool

    Stats

    pub struct Stats {
    frames : Int
    rejected : Int
    points : Int
    findings : Int
    errors : Int
    overflow : Int
    dropped_groups : Int
    pending_parts : Int
    }

    全链路计数。字段对外只读,通过访问器取值,避免调用方直接改统计。

    Stats::dropped_groups

    fn Stats::dropped_groups(self : Stats) -> Int

    Stats::errors

    fn Stats::errors(self : Stats) -> Int

    Stats::findings

    fn Stats::findings(self : Stats) -> Int

    Stats::frames

    fn Stats::frames(self : Stats) -> Int

    Stats::new

    fn Stats::new() -> Stats

    Stats::overflow

    fn Stats::overflow(self : Stats) -> Int

    Stats::pending_parts

    fn Stats::pending_parts(self : Stats) -> Int

    Stats::points

    fn Stats::points(self : Stats) -> Int

    Stats::rejected

    fn Stats::rejected(self : Stats) -> Int

    Stats::text

    fn Stats::text(self : Stats) -> String

    Stats::to_json

    fn Stats::to_json(self : Stats) -> String

    Value

    pub(all) enum Value {
    Num(Double)
    Text(String)
    Missing
    }

    一个字段的取值。
    impl Eq for Value

    Value::equal

    fn Value::equal(self : Value, other : Value) -> Bool

    Value::is_missing

    fn Value::is_missing(self : Value) -> Bool

    Value::not_equal

    fn Value::not_equal(x : Value, y : Value) -> Bool

    Value::number

    fn Value::number(self : Value) -> Double?

    Value::text

    fn Value::text(self : Value) -> String

    渲染成可读文本,供日志与 CSV 使用。

    Version

    pub(all) enum Version {
    V2005
    V2017
    V2025
    Unknown(Int)
    }

    标准版本。

    版本号编码在报文 Flag 字段的 V5–V0 位里。现场设备并不统一: 2005 版与 2017 版的数采仪可能挂在同一条链路上,因此解析器 必须读完 Flag 才知道该用哪套字段规则去解释这条报文。

    Version::code

    fn Version::code(self : Version) -> Int

    Version::from_code

    fn Version::from_code(code : Int) -> Version

    Version::label

    fn Version::label(self : Version) -> String

    all_commands

    fn all_commands() -> Array[CommandInfo]

    全部已登记的命令,顺序与标准表 9 一致。

    command_group

    fn command_group(code : String) -> String

    命令码所属的段。

    command_name

    fn command_name(code : String) -> String?

    命令码的中文名,查不到时返回 None。

    count_severity

    fn count_severity(findings : Array[Finding], level : Severity) -> Int

    crc16_bytes

    fn crc16_bytes(data : Array[Byte]) -> Int

    计算一段字节的 CRC16。

    crc16_hex

    fn crc16_hex(text : String) -> String

    计算 CRC 并格式化成报文里的 4 位大写十六进制。

    crc16_text

    fn crc16_text(text : String) -> Int

    计算一段文本的 CRC16(按 UTF-8 字节)。

    csv_header

    fn csv_header(columns : Array[String]) -> String

    CSV 表头。columns 是调用方指定的字段列,顺序即输出顺序。

    decode_all

    fn decode_all(text : String) -> Array[FrameEvent]

    一次性解码多帧文本,返回全部事件。

    lookup_command

    fn lookup_command(code : String) -> CommandInfo?

    按命令码查表。

    pad_display

    fn pad_display(s : String, width : Int) -> String

    按显示宽度右补空格。

    points_from_frames

    fn points_from_frames(frames : Array[Frame]) -> Array[Point]

    批量转换,跳过解不出来或重组后不完整的报文。

    render_all

    fn render_all(points : Array[Point], format : Format, columns : Array[String]) -> String

    按格式批量渲染。

    render_line

    fn render_line(point : Point, format : Format, columns : Array[String]) -> String

    按格式渲染单个数据点的一行。

    to_csv

    fn to_csv(points : Array[Point], columns : Array[String]) -> String

    完整 CSV(含表头,每行以 \r\n 结尾,符合 RFC 4180)。

    to_ndjson

    fn to_ndjson(points : Array[Point]) -> String

    每个数据点一行 JSON,适合流式写入日志文件。

    utf8_len

    fn utf8_len(s : String) -> Int

    字符串的 UTF-8 字节数。

    报文的长度字段按字节计,且 CRC 也按字节计算;两者必须使用同一套计数, 否则含中文的数据区会算错。

    worst

    fn worst(findings : Array[Finding]) -> Severity?

    一组发现里最严重的级别。没有问题时返回 None。