# NewLife.JT808 需求文档 > 版本：v1.4 | 日期：2026-07-15 本文档描述 NewLife.JT808 的愿景、核心目标和功能方向。完成状态在[功能清单](/NewLife/NewLife.JT808/Blob/master/Doc/功能清单.md)中追踪，详细设计在[架构设计](/NewLife/NewLife.JT808/Blob/master/Doc/架构设计.md)中展开。 ## 1. 背景与愿景 ### 1.1 系统定位 NewLife.JT808 是一套完整的 JT/T 808 道路运输车辆卫星定位系统协议栈及服务平台，包含协议编解码库、TCP 网关服务、后台管理 Web 和 Worker 消费服务。 | 维度 | 说明 | |------|------| | **使用者** | 车联网平台开发者、GPS 监控系统集成商、车队管理系统运维 | | **解决的问题** | 提供从协议解析→设备接入→数据持久化→Web 管理的全链路解决方案 | | **定位** | 协议库（NuGet 包）+ 服务平台（Server/Web/Worker） | ### 1.2 愿景 成为 .NET 生态中最完整的 JT/T 808 协议实现和车联网接入平台，对标 GPS808 中通科技成熟方案，覆盖设备管理、位置服务、报警体系、指令下发、平台管理全场景。 ## 2. 核心目标 | 编号 | 目标 | 所属层级 | 一句话描述 | |------|------|----------|------------| | M1 | 核心协议层 | 协议基础设施 | 消息帧解析、转义处理、校验、分包，支持 2011/2013/2019 三版本 | | M2 | 标准消息体 | 业务模型 | 覆盖 JT/T 808 全部标准消息体（终端上行 + 平台下行），双模式序列化 | | M3 | 网络通信层 | 传输层 | TCP 粘包编解码、客户端封装、分包合并、消息处理器路由、文件传输 | | M4 | 苏标扩展 | 扩展协议 | 苏标主动安全（ADAS/DSM/TPMS/BSD）、外设状态、报警附件协议 | | M5 | 辅助工具 | 基础设施 | 枚举定义、BCD/GBK 编码辅助、JSON 序列化、调试输出、会话抽象 | | M6 | 音视频扩展 | 扩展协议 | JT/T 1078 音视频基础消息体（不含视频流编解码） | | M7 | 行车记录仪 | 扩展协议 | JT/T 19056 汽车行驶记录仪上下行数据包编解码 | | M8 | Web API 管理接口 | 基础设施 | RESTful API 管理会话、指令下发、黑名单和统计 | | M9 | 消息队列抽象 | 基础设施 | Pub/Sub 接口体系，解耦消息生产与消费 | | M10 | 客户端增强 | 传输层 | 自动重连、心跳管理、收发统计 | | M11 | 基础设施与观测 | 基础设施 | XTrace 日志拦截、StarCloud 星尘注册、Redis 分布式缓存 | | M12 | 数据层（核心域） | 数据层 | 设备/产品/位置/报警/媒体/指令/在线等核心业务实体 | | M13 | 数据层（安全域） | 数据层 | 主动安全（ADAS/DSM/BSD/TPMS）报警事件实体 | | M14 | 数据层（平台域） | 数据层 | 转发服务/流媒体/监管/车辆清单/物联网卡等平台管理实体 | | M15 | JT808 网关服务 | 服务层 | TCP 协议网关、指令处理器链、业务服务、Redis 消息生产 | | M16 | Web 管理后台 | 表现层 | NewLife.Cube 框架，6 个功能 Area，CRUD + 指令下发 + 统计 | | M17 | Worker 消费服务 | 服务层 | Redis Stream 消费者，异步处理位置/传感器/报警数据 | | M18 | 粤标扩展 | 扩展协议 | 粤标主动安全（0x1FC4 报警上报、USB 外设透传、位置附加信息、专用参数设置），广东省主动安全标准 | | M19 | RocketMQ 消息队列 | 基础设施 | 基于 NewLife.RocketMQ 的生产者/消费者适配器，替代 Redis Stream 的跨进程消息解耦方案 | ## 3. 功能需求 ### 3.1 M1 核心协议层 - **M1-1 消息帧解析**：解析 0x7E 帧头尾、0x7D 转义（0x7D01→0x7D, 0x7D02→0x7E）、异或校验，输出原始消息体和元数据。 - **M1-2 消息帧构建**：将消息体封装为完整帧，自动添加转义、校验和、0x7E 标识。 - **M1-3 版本识别**：从消息体属性第14位识别协议版本（0=2013, 1=2019），设置 `JTMessage.Version`。 - **M1-4 分包支持**：识别分包标志，解析总包数/包序号，支持分包载荷的缓存与合并。 - **M1-5 消息类型注册**：通过 `[MessageKind]` 特性自动扫描注册消息类型，支持外部程序集注册。 - **M1-6 外部程序集注册**：`MessageFactory.Register(Assembly)` 支持加载第三方扩展程序集中的消息类型。 - **M1-7 自定义消息映射**：`SetMap<T>()` / `SetMap(kind, type)` 支持覆盖已有消息类型映射，用于厂商自定义协议。 - **M1-8 协议配置类**：`JT808Config` 集中管理协议版本、校验开关、加密密钥。 - **M1-9 版本枚举**：`JT808Version` 枚举（JT2011/JT2013/JT2019），统一版本标识。 - **M1-10 2011版字段标记**：`[JT2011]` 特性标记仅 JT/T 808-2011 版本使用的字段。 - **M1-11 枚举大小标注**：`KindSizeAttribute` 标注 TLV/KLV 枚举字段对应的字节大小。 ### 3.2 M2 标准消息体 - **M2-1 终端上行消息**：实现全部终端→平台标准消息体（0x0001~0x0FFF），包含通用应答、心跳、注册、鉴权、位置汇报、报警、多媒体、透传等。 - **M2-2 平台下行消息**：实现全部平台→终端标准消息体（0x8001~0x8FFF），包含通用应答、参数设置、终端控制、文本下发、区域设置等。 - **M2-3 反射序列化**：简单属性消息体使用 `Binary.TryRead/TryWrite` 反射自动序列化，支持 `[FieldSize]` 等特性。 - **M2-4 IAccessor 手动序列化**：复杂消息体实现 `IAccessor` 接口，手写 `Read/Write` 方法精确控制编解码。 - **M2-5 版本条件字段**：通过 `[JT2019]` 特性标记仅 2019 版存在的字段，非 2019 版自动跳过。 - **M2-6 BCD 编码字段**：`[BCDString]`、`[BCDTime]` 特性支持 BCD 编码的字符串和时间字段。 - **M2-7 剩余数据读取**：`[FullBytes]` / `[FullString2]` 特性将数据流剩余部分整体读取。 - **M2-8 位置附加信息结构化解析**：KLV 格式的位置附加信息（里程/油量/报警等）到强类型对象。 - **M2-9 多媒体类型枚举**：`MediaTypes` 定义图像/音频/视频等多媒体类型。 - **M2-10 终端RSA公钥**：`T0A00` 消息体（0x0A00），含指数e和模数n。 ### 3.3 M3 网络通信层 - **M3-1 粘包编解码器**：实现 `PacketCodec` 模式处理 TCP 粘包/半包，根据 0x7E 边界分割数据流。 - **M3-2 TCP 客户端**：封装 TCP 连接管理、消息收发、处理器注册，一行代码发送消息并等待应答。 - **M3-3 消息处理器路由**：`[MessageKind]` 特性驱动消息→处理器自动路由，支持泛型强类型回调。 - **M3-4 分包合并**：自动缓存未完成的分包序列，集齐后合并为完整消息并触发处理器。 - **M3-5 协议配置**：集中管理版本、校验和、加密密钥等配置项。 - **M3-6 文件传输编解码**：`FileCodec` 告警文件粘包编解码器，处理文件上传/下载的帧边界。 - **M3-7 会话接口**：`IJT808Session` 定义会话抽象（`Mobile`/`Send`/`SendAsync`），解耦客户端与具体实现。 - **M3-8 消息处理器接口**：`IJT808Handler` 标记接口 + `MessageHandler` 委托定义。 ### 3.4 M4 苏标扩展 - **M4-1 ADAS 报警信息**：前向碰撞、车道偏离、车距过近、行人碰撞、道路标志识别等高级驾驶辅助报警。 - **M4-2 DSM 报警信息**：疲劳驾驶、打电话、抽烟、分神、探头遮挡等驾驶员状态监测报警。 - **M4-3 TPMS 报警信息**：胎压、胎温、漏气等胎压监测报警。 - **M4-4 BSD 报警信息**：盲区监测报警。 - **M4-5 外设信息**：外设工作状态、系统信息（厂商/型号/版本）、外设类型枚举。 - **M4-6 报警附件协议**：文件上传/完成通知、附件服务器指令（T1210/T1211/T9208）。 - **M4-7 音视频资源列表**：T1205/T1206 音视频资源列表和文件上传完成通知。 - **M4-8 文件传输消息**：`FileMessage` 报警附件文件消息体编解码。 - **M4-9 车辆状态/码流枚举**：`CarStatus` 车辆状态、`BitStreams` 音视频码流类型枚举。 ### 3.5 M5 辅助工具 - **M5-1 GBK 编解码**：自动注册 GBK 编码，提供中文字符串读写扩展方法。 - **M5-2 版本感知 Reader/Writer**：根据消息版本号自动设置 `Binary.Version`，驱动条件序列化。 - **M5-3 JSON 序列化**：`ToJsonJT808` 扩展，枚举输出中文名、字节数组输出十六进制。 - **M5-4 TLV 解析**：Type-Length-Value 通用结构编解码，支持强类型字典转换。 - **M5-5 KLV 解析**：Kind-Length-Value 通用结构编解码，用于位置附加信息。 - **M5-6 枚举定义**：报警标志、状态位、车牌颜色、参数ID、位置附加类型等完整枚举。 - **M5-7 快速反序列化**：`FastRead<T>` 从字节数组直接反序列化消息体。 - **M5-8 Writer 尾部截零**：`CreateWriter` 方法设置 `TrimZero=true`，写入时自动去除尾部空字节。 ### 3.6 M6 音视频扩展 - **M6-1 音视频属性消息**：`T1003` 终端上传音视频属性。 - **M6-2 实时音视频控制**：`T9101` 实时音视频传输请求、`T9102` 音视频实时传输控制。 - **M6-3 远程录像回放**：`T9201` 平台下发远程录像控制、`T9202` 回放请求。 - **M6-4 资源列表查询**：`T9205` 查询音视频资源列表。 - **M6-5 音视频参数定义**：`T9003` 实时音视频传输控制（下行）。 - **M6-6 音视频枚举**：音频编码方式、视频编码方式、码流类型、存储类型等完整枚举。 ### 3.7 M7 行车记录仪 - **M7-1 上行数据包**：`UpPackage` 汽车行驶记录仪上行数据包编解码（0x557A 头标识）。 - **M7-2 下行数据包**：`DownPackage` 下行命令数据包编解码。 - **M7-3 数据体模型**：`UpBody`/`DownBody` 上下行数据体结构定义。 - **M7-4 序列化器**：`Serializer` 使用 NewLife 二进制序列化器读写数据包。 ### 3.8 M8 Web API 管理接口 - **M8-1 统一下发指令**：`POST /api/jt808/command` 向指定终端下发 JT808 消息体。 - **M8-2 会话列表查询**：`GET /api/jt808/sessions` 查看当前在线终端列表。 - **M8-3 会话详情查询**：`GET /api/jt808/session/{mobile}` 查看指定终端会话详情。 - **M8-4 会话移除**：`DELETE /api/jt808/session/{mobile}` 强制移除终端会话。 - **M8-5 黑名单管理**：`GET/POST/DELETE /api/jt808/blacklist` 管理设备黑名单。 - **M8-6 服务器统计**：`GET /api/jt808/stats` 查看服务器连接数和消息统计。 - **M8-7 认证鉴权**：可选的 Token 鉴权机制保护管理 API。 ### 3.9 M9 消息队列抽象 - **M9-1 消息生产者/消费者**：`IMsgProducer`/`IMsgConsumer` 接口定义，解耦消息处理。 - **M9-2 会话通知接口**：`ISessionProducer`/`ISessionConsumer` 接口，在线/离线事件通知。 - **M9-3 下行消息处理**：`IDownMessageHandler` 接口，处理外部系统下发的指令。 - **M9-4 默认内存实现**：基于内存队列的默认实现，无需外部依赖。 - **M9-5 Redis Stream 实现**：基于 Redis Stream 的生产者/消费者实现，支持消费组和 ACK 机制，用于跨进程消息解耦。 - **M9-6 RocketMQ 实现**：基于 NewLife.RocketMQ 的生产者/消费者适配器，支持通过 RocketMQ 主题进行跨进程消息解耦，可作为 Redis Stream 的替代方案。 ### 3.10 M10 客户端增强 - **M10-1 自动重连**：终端掉线后自动重新连接服务器。 - **M10-2 心跳管理**：内置心跳线程，自动发送心跳保活。 - **M10-3 发送/接收统计**：计数器追踪消息收发数量。 ### 3.11 M11 基础设施与观测 - **M11-1 XTrace 日志拦截**：所有可执行项目在 Main 入口第一行调用 `XTrace.UseConsole()` 或 `XTrace.UseWinForm()`，拦截全部日志输出。 - **M11-2 StarCloud 星尘注册**：每个可执行项目通过 `AddStardust()` 注册到星尘服务治理平台，实现配置中心、服务注册、心跳检测。 - **M11-3 Redis 分布式缓存**：通过 `ICacheProvider` + `RedisCacheProvider` 启用 Redis 缓存，用于设备在线状态、会话管理等高频访问场景。 - **M11-4 Redis 消息队列**：使用 Redis Stream（`IProducerConsumer`）替代原有内存队列和 StarFactory 事件总线，实现跨进程消息解耦。 - **M11-5 多数据源配置**：支持通过连接字符串配置多数据域（GPS/Safety/Platform），通过 `MapTo` 机制共享物理库或分离独立库。 ### 3.12 M12 数据层（核心域） - **M12-1 产品管理**：`Product` 实体，终端设备型号分类，含制造商ID、终端型号、启用状态。 - **M12-2 设备管理**：`Device` 实体扩展，增加车牌号、分组、证书、协议版本、主动安全版本、在线状态、挂厢、线路等字段。 - **M12-3 设备分组**：`DeviceGroup` 实体，设备分组管理，树形结构。 - **M12-4 设备参数**：`DeviceParameter` 实体，终端参数配置记录。 - **M12-5 设备在线**：`DeviceOnline` 实体，设备在线会话信息，含实时位置、速度、方向、地址。 - **M12-6 设备历史**：`DeviceHistory` 实体，设备上下线历史记录。 - **M12-7 位置数据**：`PositionData` 实体扩展，增加 WGS84/GCJ02/BD09 三重坐标、里程、油量、附加信息 JSON。 - **M12-8 原始报文**：`RawData` 实体，原始报文存储，用于调试和审计。 - **M12-9 报警信息**：`Alarm` 实体，终端上报的报警事件，含报警类型、位置、时间、内容。 - **M12-10 媒体信息**：`MediaInfo` 实体，多媒体文件信息，含媒体类型、格式、文件路径。 - **M12-11 媒体记录**：`MediaRecord` 实体，媒体文件上传记录。 - **M12-12 指令记录**：`DeviceCommand` 实体，下行指令记录，含指令类型、流水号、状态（已下发/已应答/超时）、结果。 - **M12-13 驾驶员**：`Driver` 实体扩展，增加从业资格证、身份证号、插拔卡历史。 - **M12-14 胎压数据**：`TirePressure` 实体，轮胎压力和温度监测数据。 ### 3.13 M13 数据层（安全域） - **M13-1 报警事件**：`AlarmEvent` 实体，报警事件聚合，按设备+编码唯一，累计次数，开始/结束标记。 - **M13-2 ADAS 报警**：`ADASAlarm` 实体，前向碰撞、车道偏离、车距过近等高级驾驶辅助报警。 - **M13-3 DSM 报警**：`DSMAlarm` 实体，疲劳驾驶、打电话、分神等驾驶员状态监测报警。 - **M13-4 BSD 报警**：`BSDAlarm` 实体，盲区监测报警。 - **M13-5 TPMS 报警**：`TPMSAlarm` 实体，胎压异常报警。 - **M13-6 报警附件**：`AlarmFile` 实体，报警关联的图片/视频/音频文件。 - **M13-7 媒体资源**：`MediaResource` 实体，主动安全多媒体资源索引。 ### 3.14 M14 数据层（平台域） - **M14-1 转发服务**：`ForwardServer` 实体，数据转发目标配置（TCP/RocketMQ/Redis）。 - **M14-2 流媒体服务**：`MediaServer` 实体，音视频流媒体服务节点配置。 - **M14-3 监管服务**：`SuperviseServer` 实体，JT809 监管平台对接配置（主从链路）。 - **M14-4 监管在线**：`SuperviseOnline` 实体，监管平台在线状态。 - **M14-5 车辆清单**：`CarList` 实体，平台接入车辆白名单。 - **M14-6 物联网卡**：`SimCard` 实体，SIM 卡信息管理。 ### 3.15 M15 JT808 网关服务 - **M15-1 设备注册/鉴权**：接收终端注册消息（T0100），分配鉴权码，验证终端鉴权（T0102），结果持久化。 - **M15-2 终端注销**：处理终端注销消息，更新在线状态。 - **M15-3 位置上报处理**：接收位置信息汇报（T0200），解析附加信息，写入 PositionData 表，推入 Redis Stream。 - **M15-4 参数查询/设置**：接收参数查询（T0104/0107）和设置指令，响应终端参数请求。 - **M15-5 多媒体事件处理**：接收多媒体事件（T0800），处理媒体上传和存储检索。 - **M15-6 文件上传/补传**：接收报警附件文件上传（T1210/T1211/T9208），处理文件存储。 - **M15-7 在线状态维护**：定时检查设备心跳超时，更新 DeviceOnline 在线状态表。 - **M15-8 Redis 消息生产**：将位置/传感器/事件/ADAS/DSM/BSD 数据推入 Redis Stream 对应主题。 - **M15-9 指令下发**：通过 Redis 队列接收 Web 端下发的指令，路由到目标终端会话执行下发，记录指令状态。 - **M15-10 预热机制**：服务启动前预热加载关键数据（白名单、产品信息等），防止连接冲击。 - **M15-11 数据过期清理**：定期清理过期位置/原始报文/报警数据，可配置保留天数。 - **M15-12 JT808Server 生命周期管理**：`GpsHostedService` 管理 JT808Server 的启动和停止，优雅处理服务中断。 - **M15-13 缓存清理 HostedService**：`ClearHostedService` 定时清理实体缓存，防止内存泄漏。 ### 3.16 M16 Web 管理后台 - **M16-1 设备管理**：Cube 列表页展示设备信息，支持手机号/车牌号搜索，设备详情查看和编辑，在线状态标识。 - **M16-2 产品管理**：产品型号 CRUD，配置制造商ID和终端型号。 - **M16-3 位置数据查询**：按设备和时间范围查询历史轨迹，地图轨迹回放（简化版）。 - **M16-4 在线设备监控**：实时在线设备列表，会话详情查看，强制移除会话。 - **M16-5 指令记录查询**：查看下行指令历史、状态和应答结果。 - **M16-6 报警事件管理**：报警事件列表，按设备/类型/时间筛选，报警详情查看。 - **M16-7 原始报文查看**：终端原始报文 HEX 显示和解析。 - **M16-8 指令下发页面**：在设备详情页选择指令类型、填充参数，下发到终端并查看应答。 - **M16-9 平台管理**：转发服务、流媒体服务、监管服务配置页面。 - **M16-10 设备分组管理**：设备分组树形管理页面，支持分组 CRUD。 - **M16-11 设备上下线历史**：设备上下线历史记录查询，按设备和时间筛选。 - **M16-12 设备参数管理**：终端参数配置记录查看和管理。 - **M16-13 驾驶员信息管理**：驾驶员信息查询、编辑和管理。 - **M16-14 多媒体信息管理**：终端多媒体文件信息查询和管理。 - **M16-15 媒体记录管理**：媒体文件上传记录查询。 - **M16-16 胎压数据管理**：轮胎压力和温度监测数据查询。 - **M16-17 报警附件管理**：报警关联的图片/视频/音频文件查询管理（Safety Area）。 - **M16-18 媒体资源管理**：主动安全多媒体资源索引查询管理（Safety Area）。 - **M16-19 设备统计**：在线设备数、今日活跃数、报警统计等看板。 ### 3.17 M17 Worker 消费服务 - **M17-1 位置数据消费**：消费 Redis Stream `PositionData` 主题，处理里程计算、坐标转换。 - **M17-2 传感器数据消费**：消费 `SensorData` 主题，处理传感器数据。 - **M17-3 事件数据消费**：消费 `EventData` 主题，处理设备事件。 - **M17-4 ADAS 报警消费**：消费 `ADASAlarm` 主题，ADAS 报警持久化和聚合。 - **M17-5 DSM 报警消费**：消费 `DSMAlarm` 主题，DSM 报警持久化和聚合。 - **M17-6 BSD 报警消费**：消费 `BSDAlarm` 主题，BSD 报警持久化和聚合。 - **M17-7 胎压数据消费**：消费 `TirePressure` 主题，胎压数据处理。 ### 3.18 M18 粤标扩展 - **M18-1 粤标主动安全报警上报**：T1FC4 消息（0x1FC4）粤标核心报警消息，终端→平台，含 ADAS/DSM/TPMS/BSD 报警数据。 - **M18-2 位置附加信息-安装异常**：T0200_F1 消息（0x0200 附加类型 0xF1），标识终端外设安装异常状态。 - **M18-3 位置附加信息-算法异常**：T0200_F2 消息（0x0200 附加类型 0xF2），标识主动安全算法异常状态。 - **M18-4 USB 外设状态上报**：T0900_F7 消息（0x0900 子类型 0xF7），终端上报 USB 外设工作状态。 - **M18-5 USB 外设信息上报**：T0900_F8 消息（0x0900 子类型 0xF8），终端上报 USB 外设详细信息（厂商/型号/版本）。 - **M18-6 USB 外设状态查询**：T8900_F7 消息（0x8900 子类型 0xF7），平台查询终端 USB 外设状态。 - **M18-7 USB 外设信息查询**：T8900_F8 消息（0x8900 子类型 0xF8），平台查询终端 USB 外设详细信息。 - **M18-8 粤标参数设置**：T8103_F364~F370 参数定义，覆盖 ADAS/车道偏离/疲劳驾驶/BSD 等粤标专用参数。 - **M18-9 粤标终端ID自适应**：`AlarmDevice` 自动识别苏标（7字节）和粤标（30字节）终端ID长度，无感适配。 - **M18-10 粤标报警标识号适配**：报警标识号长度苏标 16 字节 vs 粤标 40 字节，`AlarmDevice` 条件读写处理。 ### 3.19 M19 RocketMQ 消息队列 - **M19-1 RocketMQ 生产者适配器**：`RocketMQProducer<T>` 实现 `IMsgProducer<T>`，将 mobile 编码到消息 keys 中，支持同步/异步发送。 - **M19-2 RocketMQ 消费者适配器**：`RocketMQConsumer<T>` 实现 `IMsgConsumer<T>`，从消息 keys 提取 mobile，JSON 反序列化消息体。 - **M19-3 会话通知适配器**：`RocketMQSessionAdapter` 实现 `ISessionProducer`，终端上下线事件通过 RocketMQ 主题广播。 - **M19-4 下行指令适配器**：`RocketMQDownHandler` 实现 `IDownMessageHandler`，消费 RocketMQ 指令队列中的下行指令。 - **M19-5 云厂商适配**：支持阿里云（实例 ID）、华为云（SSL/TLS）、腾讯云（Namespace）、Apache ACL 四种云厂商认证模式。 ## 6. 不做什么 - 不实现 JT/T 1078 音视频流编解码：仅保留消息体模型和枚举定义，不做 H.264/ADPCM/G.711 等编解码，流媒体服务列为后续迭代。 - 不实现 JT/T 809 监管上报：监管平台对接列为后续迭代。 - 不实现加密算法细节：仅预留加密接口，具体算法由使用者注入。 - 不实现厂商自定义协议：锐明等厂商的私有扩展不纳入核心库，可通过 `SetMap` 扩展。 - 不实现音视频实时推流：GpsVideo 等效的 FLV/FMp4 实时转码列为后续迭代。 - 不实现地理编码（逆地址解析）：百度/高德地图对接列为后续迭代，当前仅保存原始坐标。