所属：大宗物流运输智能决策平台

A2 船队货运跟踪与 ETA

一、场景说明

业务视角：合同签完、船开出去之后，「我的货现在到哪了？什么时候到港？」成为每天被问最多的问题。过去靠船代打电话、船代再问船员微信群，层层转述、信息滞后。

本子场景把船讯网的船队推送体系（实时船位、动态 ETA、到离港事件三类）整合为全天候跟踪工作台：每条航次一张进度卡（已航 / 剩余 / ETA），右侧是航次详情与到离港事件流，中央海图叠加规划航线与实际航迹及实时船位。ETA 每 10 分钟滚动更新，到离港事件自动闭合每个港口节点，全程无需人工上报。

客户视角：货主供应链部门、船东运营部、物流公司操作部。

二、实现流程

步骤	阶段	使用接口	关键计算 / 业务逻辑
1.1 创建船队	① 数据获取	船队管理 9.1	创建船队 → `fleet_id`
1.2 船舶入队	① 数据获取	船队管理 9.1	mmsi 批量加入船队
1.3 绑定推送 URL	① 数据获取	控制台	船位 / ETA / 到离港三类推送 URL 配置
1.4 接收推送	① 数据获取	9.4 / 9.6 / 9.5	服务端每 10 分钟 POST 一包
1.5 航线基准	① 数据获取	PlanRouteByPort	生成 `route` 折线 + `distance`
1.6 轨迹查询	① 数据获取	GetShipTrack	分钟级轨迹回放与核对
2.1 航次进度计算	② 计算处理	—	`sailed_distance / distance` = 进度百分比
2.2 偏航检测	② 计算处理	—	轨迹点到航线折线垂距，连续 K 点超阈值判定偏航
2.3 ETA 序列管理	② 计算处理	—	保存 (时间戳, eta) 序列，支撑趋势分析
2.4 事件归档	② 计算处理	—	到离港事件按航次归属
3.1 延误判定	③ 业务判断	—	最新 eta − 合同 ETA → 延误等级
3.2 偏航分级	③ 业务判断	—	偏距 + 偏航时长 → 红 / 橙 / 黄
4.1 进度条渲染	④ 输出应用	—	进度百分比 → UI 进度条
4.2 地图叠加	④ 输出应用	海图 GIS	规划航线虚线 + 实际航迹实线 + 船位
4.3 事件流	④ 输出应用	—	ATA / ATB / ATD 归档进时间轴

三、接口调用与响应

3.1 船队管理（创建）

{"code": 0, "data": {"fleet_id": "FLEET_2026_散货A", "fleet_name": "中远海自有散货船队", "create_time": 1726000000}}

fleet_id 是全部推送类服务（9.4 / 9.5 / 9.6 / 9.7 / 9.8）的订阅单元。

3.2 GetFleetShip 船队快照

{"code": 0, "data": [{"mmsi": 477221800, "ship_name_en": "XIN HAI ZHOU 18", "lat": 36.067, "lng": 120.314, "sog": 12.5, "cog": 95, "navistat": "在航", "dest": "CNSHA", "last_time": 1726000100}]}

用途：推送通道健康度核对（推送与快照差异过大说明推送未达），以及冷启动时一次性补齐船队数据。

3.3 实时船位推送（9.4，10 分钟一包）

{
  "msg_type": "realtime_position",
  "fleet_id": "FLEET_2026_散货A",
  "push_time": 1726000800,
  "ships": [
    {"mmsi": 477221800, "ship_name_en": "XIN HAI ZHOU 18", "lat": 36.07, "lng": 120.32,
     "sog": 12.5, "cog": 95, "navistat": "在航", "dest": "CNSHA", "last_time": 1726000700}
  ]
}

3.4 GetSingleETAPrecise 精确 ETA

{"code": 0, "data": {"nextport": "CNSHA", "nextport_cnname": "上海港", "sailed_distance": 4230.5,
 "remaining_distance": 145.8, "distance": 4376.3, "ais_speed": 12.3, "speed": 12.0,
 "eta": 1726012100, "eta_cn": "2026-09-15 14:28:00"}}

speed 可选，不传则用 AIS 实测航速 ais_speed 计算；指定 speed 可用于「假设我降速到 11 节，ETA 会变成几点」的情景推演（A6 航速优化会用到）。

3.5 动态 ETA 推送（9.6）

{"msg_type": "dynamic_eta", "fleet_id": "FLEET_2026_散货A", "push_time": 1726000800,
 "items": [{"mmsi": 477221800, "dest_port_code": "CNSHA", "sailed_distance": 4230.5,
            "remaining_distance": 145.8, "eta": 1726012100}]}

3.6 PlanRouteByPort 航线基准

{"code": 0, "data": {"distance": 437.6, "duration_days": 1.5,
 "route": [{"lng": 120.314, "lat": 36.067}, {"lng": 122.5, "lat": 35.0}, {"lng": 124.0, "lat": 33.5}, {"lng": 125.4, "lat": 31.9}]}}

3.7 GetShipTrack 历史轨迹

{"code": 0, "data": [{"utc": 1725903600, "lat": 35.20, "lng": 121.05, "sog": 12.1, "cog": 88, "data_source": "AIS"}]}

data_source 区分 AIS（真实上报）与 PRED（预测补点），统计类计算需分离。

3.8 到离港事件推送（9.5）

{"msg_type": "portcall_event", "fleet_id": "FLEET_2026_散货A",
 "items": [{"mmsi": 477221800, "event_type": 1, "event_type_cn": "到锚地",
            "event_time": 1726012000, "port_code": "CNSHA", "port_cnname": "上海港",
            "lat": 31.20, "lng": 122.10}]}

event_type	中文	说明
1	ATA 到锚地	船舶抵达港口锚地区域
2	ATB 靠泊	船舶完成靠泊
3	ATD 离港	船舶离开港口

四、计算逻辑

4.1 航次进度

中文说明：以「已航海里 ÷ 总航程」得到进度百分比；剩余里程与 ETA 直接取 ETA 接口返回值；当 ETA 接口不可用时，用剩余里程除以当前 AIS 航速兜底估算。

4.2 偏航与绕航检测

中文说明：把规划航线当作一条折线，逐点计算轨迹点到折线的最短垂距（先把经纬度换算成以航线起点为原点的海里平面坐标，纬度 1° ≈ 60 海里，经度需乘 cos(纬度) 修正）；垂距超过阈值且连续 N 个点仍超阈值，判定为一段偏航，记录起止时间、最大偏距与持续时长；绕航带来的额外时间成本用「绕行新增里程 ÷ 航速」估算。

4.3 ETA 延误监测与趋势

中文说明：把最新 ETA 与合同约定的到港时间做差，得到延误小时数并按 6 小时、24 小时两个台阶划分为正常、轻度延误、严重延误三级；同时对 ETA 序列做趋势分析——用最新 ETA 减去 24 小时前的 ETA，正值为延误加重、负值为在赶回。严重延误自动联动下游接卸与库场计划。

4.4 到港节点闭环

中文说明：用状态机维护每船的 ATA / ATB / ATD 三个时间点，事件推送到达时推进状态；ATD 触发即视为航次完成，把三个时间点回写结算系统；航次结束后再调 GetPortofCallByShip 核对全链条，若发现缺失节点则生成人工补录任务。

五、输出的应用形态

船队货运总览：左侧航次列表（含进度条），右侧选中航次详情与事件流，中央多航线海图（规划航线蓝虚线 + 实际航迹橙实线）。

单航次详情：上部航次概要（航次号、起讫港、剩余里程、ETA、延误等级），中部计划 / 实际 / 预计三轨时间轴，下部航速与航向时序图。

六、数据边界与常见问题

数据边界：船舶动态、航线、轨迹、ETA、到离港事件来自船讯网；合同约定到港时间、货量货种、结算规则、滞期与速遣费率来自内部系统；以「内部航次号 ↔ mmsi + 时间窗」关联。

Q1：推送频率能调整吗？ 默认 10 分钟一包，需要 5 分钟或 1 分钟需联系商务确认。

Q2：ATA 什么时候触发？ 船舶 AIS 位置进入船讯网维护的港口锚地多边形时触发，与「实际抛锚」可能有几分钟到几十分钟偏差。

Q3：推送通道断了怎么办？ 以 GetFleetShip 快照做健康度对账，超过 30 分钟未收到推送即降级为 10 分钟轮询并告警。

2、船队货运跟踪与 ETA

A2 船队货运跟踪与 ETA#

一、场景说明#

二、实现流程#

三、接口调用与响应#

3.1 船队管理（创建）#

3.2 GetFleetShip 船队快照#

3.3 实时船位推送（9.4，10 分钟一包）#

3.4 GetSingleETAPrecise 精确 ETA#

3.5 动态 ETA 推送（9.6）#

3.6 PlanRouteByPort 航线基准#

3.7 GetShipTrack 历史轨迹#

3.8 到离港事件推送（9.5）#

四、计算逻辑#

4.1 航次进度#

4.2 偏航与绕航检测#

4.3 ETA 延误监测与趋势#

4.4 到港节点闭环#

五、输出的应用形态#

六、数据边界与常见问题#