From 1ce4f80161865bb45f3b547978bd18b190e8701c Mon Sep 17 00:00:00 2001 From: lingniu Date: Wed, 1 Jul 2026 02:49:28 +0800 Subject: [PATCH] docs: align module flow with tdengine history --- docs/module-data-flow.html | 63 ++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/docs/module-data-flow.html b/docs/module-data-flow.html index 6b667828..74ac952d 100644 --- a/docs/module-data-flow.html +++ b/docs/module-data-flow.html @@ -259,12 +259,12 @@

当前项目不是业务库写入服务。它的核心职责是把 GB/T 32960、JT/T 808、JT/T 1078、JSATL12、 MQTT 等不同来源的车辆数据统一转换为 VehicleEvent 和全字段 TelemetrySnapshot， - 再通过 Kafka、原始报文归档、Parquet 明细文件库、Redis 热状态和独立统计模块交给下游业务。 + 再通过 Kafka、原始报文归档、TDengine 历史索引、Redis 热状态和独立统计模块交给下游业务。

接入方式 - Netty TCP、MQTT、HTTP Push、后续可扩展更多 Inbound Adapter。 + Netty TCP、MQTT、后续可扩展更多 Inbound Adapter；Xinda Push 不在默认生产面。
统一模型 @@ -272,7 +272,7 @@
输出方式 - Kafka Protobuf Envelope + 原始 bytes 冷存 + Parquet/DuckDB + Redis 热状态。 + Kafka Protobuf Envelope + 原始 bytes 冷存 + TDengine raw_frames/locations + Redis 热状态。
业务边界 @@ -307,7 +307,7 @@ flowchart TB subgraph protocolBase["核心与公共能力 modules/core"] codec["ingest-codec-common
BCD / CRC / BCC / bit 工具"] session["session-core
设备会话、命令分发接口、会话存储"] - identity["vehicle-identity
跨协议身份解析、外部标识绑定、文件持久化"] + identity["vehicle-identity
跨协议身份解析、MySQL 绑定表"] obs["observability
metrics / tracing / health"] api["ingest-api
ProtocolId / RawFrame / VehicleEvent / 注解 SPI"] registry["HandlerRegistry
按协议、命令、infoType 路由"] @@ -318,13 +318,14 @@ flowchart TB subgraph sink["输出与明细存储 modules/sinks"] mq["sink-mq
VehicleEvent 到 Protobuf Envelope 到 Kafka"] archive["sink-archive
RawArchive 到本地/S3/OSS 冷存"] - fileStore["event-file-store
VehicleEvent/RawArchive 索引到 Parquet，DuckDB 按日查询"] + tdengineStore["tdengine-history-store
TDengine raw_frames + locations"] + fileStore["event-file-store
Parquet/DuckDB 兼容可选"] end subgraph services["消费服务 modules/services"] - history["event-history-service
Kafka 全字段事件到历史查询/导出"] + history["event-history-service
Kafka event/raw 到 TDengine 历史查询"] state["vehicle-state-service
Kafka 全字段事件到 Redis 热状态"] - stat["vehicle-stat-service
Kafka 全字段事件到可配置日统计"] + stat["vehicle-stat-service
Kafka 全字段事件到指标表"] end subgraph apps["应用入口 modules/apps"] @@ -356,10 +357,11 @@ flowchart TB dispatcher --> bus bus --> mq bus --> archive - bus --> fileStore mq --> history mq --> state mq --> stat + history --> tdengineStore + history -.兼容可选.-> fileStore gateway --> session session --> jt808 @@ -375,7 +377,6 @@ flowchart TB bootall -.装配.-> mqtt bootall -.装配.-> mq bootall -.装配.-> archive - bootall -.装配.-> fileStore bootall -.装配.-> history bootall -.装配.-> state bootall -.装配.-> stat @@ -388,7 +389,7 @@ flowchart TB class gb,jt808,jt1078,jsatl12,mqtt,mqttProfile entry; class api,registry,dispatcher,bus,identity core; - class mq,archive,fileStore sink; + class mq,archive,tdengineStore,fileStore sink; class gateway,session command; class codec,obs,bootall support; @@ -408,17 +409,18 @@ flowchart TB sequenceDiagram autonumber participant Device as 车辆/平台 - participant Inbound as Inbound Adapter
Netty/MQTT/Push + participant Inbound as Inbound Adapter
Netty/MQTT participant Decoder as FrameDecoder
MessageDecoder participant Dispatcher as Dispatcher participant Handler as Protocol Handler
Mapper participant EventBus as DisruptorEventBus participant MQ as sink-mq
Kafka Envelope participant Archive as sink-archive
ArchiveStore - participant FileStore as event-file-store
Parquet + DuckDB + participant History as vehicle-history-app + participant TDengine as tdengine-history-store
raw_frames + locations participant Consumer as 下游业务消费者 - Device->>Inbound: 原始报文 bytes / MQTT message / HTTP payload + Device->>Inbound: 原始报文 bytes / MQTT message Inbound->>Decoder: 粘包拆帧、校验、协议体解析 Inbound->>Inbound: MQTT 按 endpoint profile 选择厂商解析器 Decoder->>Dispatcher: RawFrame(protocol, command, infoType, payload, rawBytes) @@ -429,11 +431,11 @@ sequenceDiagram Dispatcher->>Handler: 绑定 rawArchiveKey / rawArchiveUri Handler->>EventBus: VehicleEvent(Realtime / Location / Alarm / Login ...) EventBus->>MQ: 投递规整后的业务事件 - EventBus->>FileStore: 写入解析后明细事件 MQ->>MQ: EnvelopeMapper 转 Protobuf - MQ->>Consumer: Kafka topic，key=vin，单车有序 - FileStore->>Consumer: 按日期范围正序/倒序查询和导出 - Consumer->>Consumer: 历史明细查询、Redis 热状态、可配置日统计、告警工单 + MQ->>History: Kafka event/raw topic，key=vin，单车有序 + History->>TDengine: 写 raw_frames、locations 和 raw parsed JSON + TDengine->>Consumer: 分页历史查询、原始帧追溯、位置查询 + MQ->>Consumer: Redis 热状态、指标统计、告警工单等下游消费
@@ -526,9 +528,9 @@ flowchart LR modules/core/vehicle-identity - 跨协议车辆身份解析，维护 phone、deviceId、plate 到 VIN 的绑定关系；支持 memory 和 append-only JSONL file 后端，避免重启丢失绑定。 + 跨协议车辆身份解析，维护 phone、deviceId、plate 到 VIN 的绑定关系；生产运行使用 MySQL 绑定表，避免重启丢失绑定并保证多实例一致。 协议模块传入的外部标识。 - 稳定 VIN、解析来源、是否已命中绑定。 + 稳定 VIN、解析来源、是否已命中绑定、MySQL 绑定记录。 统计主键多协议归一持久化绑定 @@ -589,17 +591,24 @@ flowchart LR modules/sinks/event-file-store - 文件型明细库，使用 Parquet 存储解析后的事件明细和 RawArchive 可查询索引，使用 DuckDB 按日期范围正序/倒序查询；RawArchive 只存 archive:// 逻辑 URI、命令码、长度和 metadata，不嵌入原始 bytes，原始 bytes 本体仍由 sink-archive 管理；读取历史文件时未知 protocol 会降级为 UNKNOWN，避免查询中断。 + 兼容文件型明细库，使用 Parquet 存储解析后的事件明细和 RawArchive 可查询索引，使用 DuckDB 按日期范围正序/倒序查询；默认生产部署不启用，仅用于旧低层记录接口或本地调查场景。 VehicleEvent 或 EventFileRecord。 - protocol/date 分区的 Parquet 文件和查询结果。 - 按日查询导出字段配置 + protocol/date 分区的 Parquet 文件和兼容查询结果。 + 兼容查询默认关闭 + + + modules/sinks/tdengine-history-store + 生产历史库边界，负责 TDengine schema、raw_frames/location/telemetry field 行映射、批量写入和分页查询语句；raw_frames 保留完整 payloadJson.parsed，位置表保持轻量字段并通过 rawUri 关联原始帧。 + Kafka Protobuf Envelope、Raw Envelope。 + TDengine raw_frames、位置表、可选 telemetry field 表。 + 生产历史分页查询raw 追溯 modules/services/event-history-service - 消费 Kafka 全字段事件，写入文件型明细库，并提供历史查询和 CSV 导出边界；导出支持通过 fields 参数选择内部字段并平铺为 CSV 列，也支持 metadata.xxx 导出协议侧诊断、媒体归档、报警类型等 metadata 字段；未知 Envelope source 会进入 UNKNOWN 协议分区，并在 metadata 保留 originalSource 便于回溯；生产消费可使用 tryIngest 和自动装配的 EnvelopeConsumerProcessor 将坏 protobuf、缺快照和存储异常收敛为结构化结果，并通过 EnvelopeDeadLetterSink 发布死信，避免阻塞 Kafka 分区。 + 消费 32960、808、宇通 MQTT 的 Kafka event/raw topic，生产默认写入 TDengine raw_frames 和位置表，并提供 raw 帧、位置历史等分页查询边界；Raw 查询返回完整 parsed JSON，位置历史只保留核心字段并通过 rawUri 关联原始帧；生产消费可使用 tryIngest 和自动装配的 EnvelopeConsumerProcessor 将坏 protobuf、缺快照和存储异常收敛为结构化结果，并通过 EnvelopeDeadLetterSink 发布死信，避免阻塞 Kafka 分区。 Kafka Protobuf Envelope。 - EventFileRecord、查询结果、可配置字段 CSV。 - 历史明细多日导出字段配置 + TDengine raw_frames、位置分页结果、raw archive 逻辑引用。 + 历史明细分页查询raw JSON modules/services/vehicle-state-service @@ -681,8 +690,8 @@ flowchart LR 明细展示和导出 - event-file-store - 解析后的事件明细和 RawArchive 索引按 protocol/date 写 Parquet。DuckDB 查询时按日期范围读取，并按 event_time 正序或倒序返回。 + vehicle-history-app + tdengine-history-store + 生产查询通过 TDengine raw_frames、位置表和 rawUri 关联完成；Parquet/DuckDB 仅作为兼容文件型明细库，不进入默认热路径。