1、港口运力监控与找船

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

一、场景说明

业务视角：租船业务员围绕目标港口（示例：青岛港）做承运安排时，最头疼三件事——「这个港现在到底压了多少船？」「这堆候选船里哪条最适合我的货？」「选中的船现在真实位置在哪、能不能按时报到？」。过去靠船代电话和经验，看到的是「听说」「大概」「估计」。

本子场景把港口与船舶实时数据整合成租船决策工作台：左侧港口运力看板（KPI + 在泊 / 锚地 / 预抵清单），右侧候选船劳氏档案与未来 72 小时到港预测，中央港口海图呈现靠泊区、锚地与进港航道。从输入目标港口到输出可下单的候选船清单与运力评估，耗时从半天缩短到 10 分钟。

客户视角：物流公司租船部、贸易商执行部、船代操作部。

二、实现流程

步骤	阶段	使用接口	关键计算 / 业务逻辑
1.1 港口定位	① 数据获取	SearchPort	关键词模糊匹配 → `port_code`（如 CNTAO）
1.2 在泊扫描	① 数据获取	GetBerthShips	按 `port_code` 取当前靠泊船舶清单，固定传 `search_type=1`
1.3 锚地扫描	① 数据获取	GetAnchorShips	取锚地等待船舶清单（含 `stay_time_min`）
1.4 预抵扫描	① 数据获取	GetETAShips	取未来 7 天内预抵船舶清单
2.1 运力指标计算	② 计算处理	—	在泊 / 锚地 / 预抵计数；平均与峰值等待时长；锚泊超时识别
2.2 候选船筛选	② 计算处理	SearchShipParticular	货种 → 船型、货量 → DWT 区间、到港窗 → eta 区间、船龄、船东准入，五条件交集
2.3 位置核验	② 计算处理	GetSingleShip	单船实时经纬度 + 航行状态 + 目的港
3.1 供需匹配	③ 业务判断	—	需求船数 = ceil(单批货量 ÷ 候选船平均 DWT)；与可用供给比对
3.2 白名单核对	③ 业务判断	—	与内部准入船东名单比对
4.1 看板呈现	④ 输出应用	—	港口 KPI + 三类船舶清单
4.2 画像输出	④ 输出应用	—	候选船劳氏档案卡片 + 综合评分排序
4.3 海图落点	④ 输出应用	海图 GIS	船舶按 (lat,lng) 落入靠泊区 / 锚地 / 进港航道并分色

三、接口调用与响应

3.1 SearchPort 港口检索

{
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "port_code": "CNTAO",
      "port_cnname": "青岛港",
      "port_enname": "QINGDAO",
      "port_country": "中国",
      "port_lng": 120.314,
      "port_lat": 36.067
    }
  ]
}

参数：keywords 支持中文名 / 英文名 / 简拼模糊匹配；max 返回条数，建议 5–20。返回 port_code 是后续所有港口维度查询的唯一标识。

3.2 GetBerthShips 在泊船

{
  "code": 0,
  "data": [
    {
      "mmsi": 477221800,
      "ship_name_cn": "新海洲 18",
      "ship_name_en": "XIN HAI ZHOU 18",
      "ship_type_cn": "干散货船",
      "dwt": 76000,
      "arrival_time": 1726000000,
      "berth_time": 1726012000,
      "berth_name": "前湾 7 号泊位",
      "stay_time_min": 540
    }
  ]
}

参数：ship_type 可选，常见取值 干散货 / 集装箱 / 油轮 / LNG / LPG / 化学品 / 多用途；search_type=1 屏蔽长期未上报 AIS 的僵尸船舶，强烈建议固定传 1。

3.3 GetAnchorShips 锚地船

请求同 3.2（port_code 必填，ship_type 可选），返回字段多出 anchor_time（到锚时间）、anchor_area（锚地区域名）、stay_time_min（在锚分钟数）。

3.4 GetETAShips 预抵船

{
  "code": 0,
  "data": [
    {
      "mmsi": 477332200,
      "ship_name_en": "PACIFIC HOPE",
      "dwt": 82000,
      "preport_cnname": "黑德兰港",
      "preport_eta_time": 1726000000,
      "current_lng": 118.21,
      "current_lat": 35.42,
      "distance_nm": 142.5
    }
  ]
}

注意：start_time 与 end_time 间隔不超过 7 天，超过需拆分多次调用。

3.5 GetSingleShip 单船核验

{
  "code": 0,
  "data": {
    "mmsi": 477221800,
    "lat": 36.067,
    "lng": 120.314,
    "sog": 0.0,
    "cog": 0.0,
    "navistat": "锚泊",
    "dest": "QINGDAO",
    "last_time": 1726000100
  }
}

3.6 SearchShipParticular 船舶档案

{
  "code": 0,
  "data": {
    "mmsi": 477221800,
    "imo": 9876543,
    "ship_name_en": "XIN HAI ZHOU 18",
    "ship_type": "Bulk Carrier",
    "deadweight": 76000,
    "gross_tonnage": 42000,
    "teu": 0,
    "speed_service": 14.0,
    "speed_max": 15.5,
    "class_society": "CCS",
    "shipowner": "中远海运",
    "manager": "中远海运管理",
    "build_year": 2015,
    "build_place": "上海外高桥造船"
  }
}

mmsi / imo / call_sign / ship_name 四选一，建议优先用 mmsi。仅 IMO 编号船舶有完整劳氏档案，无 IMO 的小型船字段会缺失，UI 需做降级提示。

四、计算逻辑

4.1 港口运力指标

中文说明：统计在泊船数、锚地船数与预抵船数三类基础计数；锚地等待时长取全体锚地船 stay_time_min 的均值与峰值，换算成小时；再以「锚地在泊比」「平均等待时长」「峰值等待时长」三项做阈值判定，输出港口拥堵提示。

N_berth  = 在泊船数
N_anchor = 锚地船数
N_eta    = 时间窗内预抵船数

avg_wait_hours  = mean(stay_time_min) / 60
peak_wait_hours = max(stay_time_min) / 60

指标	阈值	提示
`N_anchor / N_berth` > 0.4	港口拥堵	橙色 KPI
`avg_wait_hours` > 36	锚地压港	红色 KPI
`peak_wait_hours` > 72	严重压港	红色 KPI + 备选港建议

4.2 候选船筛选与评分

中文说明：把业务条件映射为接口参数后做多条件交集筛选——货种决定船型，货量决定 DWT 区间，期望到港窗决定 ETA 区间，船龄与船东白名单由劳氏档案校验；通过筛选的船按「载重匹配度 + 到港时效 + 船龄 + 船东准入」加权打分排序，得分最高的即为首选。

业务条件	接口参数 / 字段
货种 = 煤炭 / 铁矿砂	`ship_type = 干散货`
货种 = 原油 / 成品油	`ship_type = 油轮`
单批货量 = 15 万吨	候选船 `dwt ∈ [150000, 180000]`
期望到港窗 9/20–9/25	`eta ∈ [start_ts, end_ts]`
船龄 ≤ 10 年	`当前年 − build_year ≤ 10`

4.3 位置核验与可锁定判定

中文说明：对入选候选船逐条拉取实时位置；若船舶状态为「锚泊」且距锚地中心 5 海里以内，说明已经在港等待，可快速锁定；若目的港为目标港但仍在航，则需按剩余里程与航速估算到港时间后再判断；其余情况标记为需人工确认。

4.4 供需匹配测算

中文说明：用单批货量除以候选船平均 DWT 并向上取整，得到完成这批货需要的船次数；与「可锁定或在 7 天内预抵」的供给船数比对得到缺口；缺口为正时给出提前锁舱或调整卸货港的建议。

五、输出的应用形态

港口运力监控看板：港口 KPI 卡（在泊 / 锚地 / 预抵 / 平均等待）+ 三类船舶清单 + 港口海图（靠泊区绿、锚地橙、航道蓝）。

找船工具：上部筛选条件（货种 / 货量 / 到港窗 / 船龄），中部候选船卡片（船型、DWT、船龄、距港海里、ETA、评分），下部选中船劳氏档案与历史挂靠记录。

六、数据边界与常见问题

数据边界：船舶与港口数据来自船讯网；货种需求、货量计划、准入船东名单、合同模板来自内部系统，两者在「候选船画像卡」汇合。

Q1：search_type 应该传什么？
默认传 1，屏蔽长期未上报 AIS 的僵尸船舶，显著提升数据质量；若需保留全部上报记录可不传。

Q2：为什么 SearchShipParticular 返回字段不全？
仅当船舶有 IMO 编号（≥100 总吨国际航行船舶）时返回完整劳氏档案；无 IMO 的船字段会缺失，UI 需降级展示。

Q3：GetETAShips 时间窗超限怎么办？
单次不超过 7 天，按自然周拆分后合并去重。

1、港口运力监控与找船

一、场景说明#

二、实现流程#

三、接口调用与响应#

3.1 SearchPort 港口检索#

3.2 GetBerthShips 在泊船#

3.3 GetAnchorShips 锚地船#

3.4 GetETAShips 预抵船#

3.5 GetSingleShip 单船核验#

3.6 SearchShipParticular 船舶档案#

四、计算逻辑#

4.1 港口运力指标#

4.2 候选船筛选与评分#

4.3 位置核验与可锁定判定#

4.4 供需匹配测算#

五、输出的应用形态#

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