业务词汇表

设备与定位

设备（Device）

接入平台的硬件实体，包括车载设备、摄像头、GPS Tracker。以 productID + deviceName 唯一标识；设备上线后由 Go 侧维护在线状态（Redis things:device:status:{productID}:{deviceName}）。

产品（Product）

设备的品类定义，包含物模型、协议、接入方式等元数据；一个产品下挂多个设备。产品密钥与设备密钥属于敏感信息，不得写入日志。

物模型（Thing Model）

描述设备属性、事件、服务的标准 JSON 结构。GPS 私有协议载荷经 gpscodecsvr 解码后转换为标准物模型，再进入业务链路。

设备影子（Device Shadow）

设备期望状态与上报状态的缓存副本，支持离线指令缓存：设备离线期间下发的指令先写入影子，上线后同步执行（Go dmsvr 的 shadowIndexLogic）。

GPS 原始点

设备上报的未经清洗的坐标点，是轨迹计算的证据源；保留在 TDengine，不应与清洗后的轨迹混用。

清洗轨迹

对原始点进行坐标纠偏（WGS84→GCJ02）、抽稀、去噪后的轨迹；离线补传数据必须按设备时间戳排序，避免影响里程与行程计算。

行程 / 停留（Trip / Stay）

基于轨迹计算出的行驶段与停留段；Go tripsvr 离线检测后写入行程摘要表，供 Java 侧地图回放与报表查询。

地理围栏（Geofence）

虚拟区域，设备进出围栏触发告警；Java prod-gps 维护围栏配置并通过 gRPC 暴露给外部（ProdGpsGeofenceService）。

订阅、支付与 SIM

订阅（Subscription）

用户购买的套餐，包含若干权益；subscription_active 表达当前生效订阅，subscription_record 记录变更历史，不能只读一张表判断完整订阅状态。

权益（Entitlement / Capability）

套餐赋予的能力，如 DATA_REPORT、FAMILY_SHARING；通过 SubscriptionEntitlementService gRPC 供 Go 侧校验设备能力。

Seat

权益的具体占用席位（设备或成员）；subscription_seat 对已占用 session/device 建立唯一约束，释放后恢复占用。

SIM Profile / eSIM

SIM 卡资费与网络配置档案；SIM 模块管理 profile、供应商、绑定、回调与用量快照，供应商同步必须幂等。

支付订单（Pay Order）

业务侧的支付订单事实；pay_order 对租户内订单号与 app_id + merchant_order_id 建立唯一约束。

支付尝试（Payment Attempt）

一次与支付提供商的交互记录；pay_payment_attempt 对公开 attempt ID、客户端幂等键、提供商幂等键建立唯一约束。不能仅凭订单状态推断提供商状态。

对账（Reconciliation）

以提供商流水为准核对业务事实；Pay 模块有独立的对账事实表与 PayReconciliationCaseJob 处理差异。

通知 / 消息任务

站内信、推送、短信、邮件等发送动作由消息任务承载并跟踪状态；告警"规则命中"与"通知送达"是两个不同事实。

消息、任务与治理

事件（Event）

设备或系统产生的事件流，用于规则匹配与分发；典型如设备上线（device.up.status.connected）、物模型上报、碰撞告警。

告警（Alert）

满足规则条件后生成的告警记录，属于业务事实。规则由"触发器（trigger）+ 过滤器（filter）+ 动作（action）"组成，配置在 Java alarm，判断在 Go alertsvr。

Outbox

本地事务 + 消息队列的可靠发布模式：业务写库的同时写 outbox 表，由 Job（如 PayOutboxPublishJob、IotBindingOutboxJob）异步发布，保证不丢消息。

Saga

跨服务的长事务编排：IoT 绑定 + 订阅 Seat 占位通过 RocketMQ 事件（topic entrax-subscription-binding-saga-v1）串联多个服务，任何一步失败走补偿（释放 Seat）。

幂等键

防止重复处理的关键约束：绑定任务 task_no、支付 attempt 客户端幂等键、SIM 回调幂等键等，均在表上建唯一索引。

OTA

设备固件远程升级：Java 创建升级任务，经 NATS device.down.ota 下发，Go otasvr 跟踪升级状态，结果以设备上报为准。

MCP

AI 能力接入协议；Java 侧 /mcp 走独立 Connector 端口（49202），供 AI Agent 复用平台业务能力。

H3 索引

用于风险区域匹配的空间索引（六边形网格），Go risksvr 用它判断设备是否进入/离开风险区域。

WebRTC / SIP INVITE

实时视频采用 WebRTC 拉流；Go videosvr 校验权限后向设备发 SIP INVITE 唤醒推流，全程不占用 Java 服务 IO。

fail-closed

安全默认策略：鉴权或关键实时依赖不可用时，wssvr 拒绝连接而不是放行。

术语使用约定