4、大宗航运态势分析与经营决策大屏

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

一、场景说明

业务视角：前面三个子场景解决的是「一条船、一个港、一个航次」的执行问题。但集团管理层与贸易决策层关心的是市场：未来两周青岛—日照—连云港这个港口群到港运力是松还是紧？Capesize 与 Panamax 的到港结构有没有变化？主流航线的运量是不是在往某个港转移？锚地拥堵是在恶化还是缓解？现在该不该锁船、该不该把货挪到备选港？

过去这些数据要靠外部咨询机构的周报，贵、慢、口径还不一致。本子场景用船讯网港口历史挂靠 + 三类实时清单 + 航线规划 + 船舶档案四类接口，自己建立一套运力统计口径，输出一张经营决策大屏：

现状层：港口群运力快照（在泊 / 锚地 / 预抵 / 船型结构 / 港口拥堵指数）；
趋势层：近 90 天到港量、在泊时长、等泊时长的时序演化；
预测层：未来 7 / 14 天到港节奏预测（含置信区间）、运力供需缺口预测、拥堵指数演化预测；
决策层：租船时机建议、备选港建议、运力锁定建议。

客户视角：贸易商研究部、物流集团运力采购中心、集团经营管理层。

与 A1 的区别：A1 是单点作业工具（业务员找一个港的船），A4 是市场研判系统（多港、长时间窗、统计口径、带预测），A4 的结论会直接下发给 A1 作为筛选策略与阈值。

二、实现流程

fig-A4-实现流程.png

步骤	阶段	使用接口	关键计算 / 业务逻辑
1.1 港口群定位	① 数据获取	SearchPort	批量解析港口五位码，建立港口群定义
1.2 历史挂靠采集	① 数据获取	GetPortofCallByPort	逐港、逐 7 天窗口拉历史挂靠，累计 90 天
1.3 实时清单采集	① 数据获取	GetBerthShips / GetAnchorShips / GetETAShips	当前在泊 / 锚地 / 未来预抵
1.4 船舶画像补全	① 数据获取	SearchShipParticular	DWT / 船型 / 船龄 / 船东，用于分桶统计
1.5 航线里程	① 数据获取	PlanRouteByPort	航距 → 航次周转周期 → 有效运力折算
1.6 实际航速校验	① 数据获取	GetShipTrack	抽样航迹测实际航速，修正周转周期
2.1 拥堵指数 PCI	② 计算处理	—	锚泊比 + 平均等泊 + 到港密度三项归一化加权
2.2 供给指数 CSI	② 计算处理	—	未来窗内预抵总 DWT ÷ 历史同期基准
2.3 船型结构分析	② 计算处理	—	按 DWT 分桶（Cape/Panamax/Supra/Handy）占比
2.4 到港节奏预测	② 计算处理	—	泊松强度估计 + Holt 二次指数平滑 → 期望值与区间
2.5 周转周期推算	② 计算处理	—	往返航距 ÷ 平均航速 + 在泊时长 + 等泊时长
2.6 供需缺口	③ 业务判断	—	内部货量计划 ÷ 单船运力 vs 预测供给
3.1 决策建议	③ 业务判断	—	锁船 / 观望 / 改港 / 分批
4.1 大屏呈现	④ 输出应用	海图 GIS	港口群气泡图 + 航线流量热力 + 时序图
4.2 预测卡片	④ 输出应用	—	到港节奏带置信区间的预测卡
4.3 下发策略	④ 输出应用	—	把筛选阈值与推荐港口回写 A1

三、接口调用与响应

3.1 GetPortofCallByPort 港口历史挂靠（本场景核心）

GET https://api.shipxy.com/apicall/v3/GetPortofCallByPort?key=YOUR_KEY&port_code=CNTAO&start_time=1725400000&end_time=1726004800

{
  "code": 0,
  "data": [
    {
      "mmsi": 477221800,
      "ship_name_en": "XIN HAI ZHOU 18",
      "ship_type_cn": "干散货船",
      "dwt": 76000,
      "ata": 1725900000,
      "atb": 1725912000,
      "atd": 1726100000,
      "berth_name": "前湾 7 号泊位",
      "stay_time_min": 3120,
      "draft_arrival": 14.2,
      "draft_departure": 8.6
    }
  ]
}

参数与边界：port_code 必填；start_time / end_time 单次跨度 ≤ 7 天，30 天内按连续窗口拆分并对 mmsi + ata 去重；更长历史需联系商务开通历史深度。返回字段中的 ata / atb / atd 构成本场景全部时间统计的基础，draft_arrival 与 draft_departure 的差值还可反推装载量，用于货量侧校验。

3.2 GetETAShips 预抵（未来供给）

GET https://api.shipxy.com/apicall/v3/GetETAShips?key=YOUR_KEY&port_code=CNTAO&start_time=1726000000&end_time=1726604800

返回的 dwt 与 preport_eta_time 构成未来供给的原子数据。

3.3 SearchShipParticular 船型补全

GET https://api.shipxy.com/apicall/v3/SearchShipParticular?key=YOUR_KEY&mmsi=477221800

用于把港口清单里缺 DWT 的船补全，并按 ship_type / deadweight / build_year 做结构分析。建议对高频出现的 MMSI 做长期缓存（30 天）。

3.4 PlanRouteByPort 航距

GET https://api.shipxy.com/apicall/v3/PlanRouteByPort?key=YOUR_KEY&start_port_code=CNTAO&end_port_code=AUPHE

返回 distance（海里）用于推算单船往返周期，进而把「船数」折算成「有效运力」。

四、计算逻辑

4.1 港口拥堵指数 PCI

中文说明：拥堵不是单看锚地船数，而是三个维度叠加——锚地在泊比（反映排队强度）、平均等泊时长（反映消化速度）、到港密度（反映到达强度）。三项各自用历史 90 天的 P95 做归一化截断（避免极端值主导），再按 0.4 / 0.4 / 0.2 加权得到 0–100 的指数，≥70 为严重、50–70 为拥堵、30–50 为偏紧、<30 为通畅。

def norm(x, cap):
    return min(x / cap, 1.0) if cap > 0 else 0.0


def port_congestion_index(berth_list, anchor_list, arrivals_24h, baseline):
    """
    baseline: 近 90 天统计得到的 {'ratio_p95','wait_p95_h','density_p95'}
    """
    n_berth, n_anchor = len(berth_list), len(anchor_list)
    ratio = (n_anchor / n_berth) if n_berth else (3.0 if n_anchor else 0.0)

    waits = [s['stay_time_min'] for s in anchor_list if s.get('stay_time_min')]
    avg_wait_h = (sum(waits) / len(waits) / 60) if waits else 0.0

    pci = 100 * (0.4 * norm(ratio, baseline['ratio_p95'])
                 + 0.4 * norm(avg_wait_h, baseline['wait_p95_h'])
                 + 0.2 * norm(arrivals_24h, baseline['density_p95']))

    level = ('SEVERE' if pci >= 70 else
             'CONGESTED' if pci >= 50 else
             'TIGHT' if pci >= 30 else 'SMOOTH')
    return round(pci, 1), level

4.2 运力供给指数 CSI

中文说明：把统计窗内的预抵船按 DWT 求和，得到未来可投放的总吨位；与过去 8 周同一口径的中位数（基准）相除得到供给指数；>1.15 表示供给宽松（租船议价空间大），0.85–1.15 为正常，<0.85 表示供给偏紧（应提前锁船）。同时按船型分桶给出结构指数，因为「Capesize 紧但 Handysize 松」对 15 万吨的货没有意义。

def supply_index(eta_list, baseline_dwt_sum, band=None):
    pool = eta_list if band is None else [s for s in eta_list if dwt_band(s.get('dwt', 0)) == band]
    dwt_sum = sum(s.get('dwt', 0) for s in pool)
    if baseline_dwt_sum <= 0:
        return None
    csi = dwt_sum / baseline_dwt_sum
    state = ('宽松' if csi > 1.15 else '偏紧' if csi < 0.85 else '正常')
    return {'dwt_sum': dwt_sum, 'csi': round(csi, 3), 'state': state}

4.3 到港节奏预测（泊松 + Holt 二次指数平滑）

中文说明：到港是典型的计数过程，短期预测用两段组合——基线强度用近 28 天日均到港数（泊松强度 λ），趋势用 Holt 线性二次指数平滑捕捉升降方向；最终预测值取两者加权，并用泊松分布给出 80% 置信区间（用正态近似：λ ± 1.28√λ）。这样大屏上显示的不是「下周来 12 条船」这种假精确，而是「10–15 条，中位 12 条」。

import math

def holt_forecast(series, horizon, alpha=0.4, beta=0.1):
    """series: 按天升序的到港数列表；返回 horizon 天的预测列表"""
    if len(series) < 3:
        return [sum(series) / max(len(series), 1)] * horizon
    level, trend = series[0], series[1] - series[0]
    for y in series[1:]:
        prev_level = level
        level = alpha * y + (1 - alpha) * (level + trend)
        trend = beta * (level - prev_level) + (1 - beta) * trend
    return [max(level + k * trend, 0.0) for k in range(1, horizon + 1)]


def arrival_forecast(daily_counts, horizon=7, weight_holt=0.6):
    lam_base = sum(daily_counts) / len(daily_counts)          # 泊松基线强度
    holt = holt_forecast(daily_counts, horizon)
    out = []
    for k in range(horizon):
        point = max((1 - weight_holt) * lam_base + weight_holt * holt[k], 0.0)
        sd = math.sqrt(point)                                  # 泊松方差 = 均值
        out.append({'day': k + 1,
                    'p50': round(point, 1),
                    'lo80': round(max(point - 1.28 * sd, 0), 1),
                    'hi80': round(point + 1.28 * sd, 1)})
    return out

4.4 航次周转周期与有效运力

中文说明：一条船在一条航线上一年能跑几趟，取决于「往返航距 ÷ 实际航速 + 港内作业时长 + 等泊时长」。往返航距由 PlanRouteByPort 给出（单程 × 2，空载段可按 0.95 系数折减），实际航速用抽样轨迹的航速中位数修正（AIS 上报航速往往低于设计航速），港内时长与等泊时长用 GetPortofCallByPort 的历史分位数。得到单船年航次数后，乘 DWT 与满载率即为单船年有效运力，再乘船数得到总有效运力。

def voyage_cycle_days(one_way_nm, actual_speed_kn, port_days_p50, wait_days_p50,
                      ballast_factor=0.95):
    sea_days = one_way_nm * (1 + ballast_factor) / max(actual_speed_kn * 24, 1e-6)
    return sea_days + port_days_p50 + wait_days_p50


def effective_capacity(ship_count, dwt, cycle_days, load_factor=0.92, year_days=350):
    trips = year_days / cycle_days
    return ship_count * dwt * load_factor * trips

4.5 供需缺口与决策建议

中文说明：把内部未来 N 天的货量计划，除以候选船平均 DWT 得到需求船数；供给船数取「预测到港且船型匹配」的船数按到港日累加；逐日比较得到缺口时序。决策规则：缺口连续 3 天为正且 CSI < 0.85 → 建议立即锁船；缺口为正但 CSI > 1.15 → 建议观望 3 天再锁；缺口为负 → 建议分批装运或压价谈判。备选港建议取同货种、PCI 最低且 CSI 最高的邻近港口。

def supply_demand_series(demand_tons_by_day, supply_ships_by_day, mean_dwt):
    series = []
    cum_demand, cum_supply = 0.0, 0.0
    for day, tons in demand_tons_by_day.items():
        cum_demand += tons / mean_dwt
        cum_supply += supply_ships_by_day.get(day, 0)
        series.append({'day': day, 'cum_demand': round(cum_demand, 2),
                       'cum_supply': round(cum_supply, 2),
                       'gap': round(cum_demand - cum_supply, 2)})
    return series


def procurement_advice(gap_series, csi, alt_ports=None):
    pos_days = sum(1 for g in gap_series if g['gap'] > 0)
    if pos_days >= 3 and csi < 0.85:
        return 'IMMEDIATE', '运力偏紧且缺口持续，建议立即锁定舱位'
    if pos_days >= 3 and csi > 1.15:
        return 'WAIT', '供给宽松，建议观望 3 天后再锁，争取更优费率'
    if pos_days == 0:
        return 'NEGOTIATE', '运力充足，建议分批装运并压价谈判'
    return 'PARTIAL', '缺口阶段性出现，建议分批锁定'

五、输出的应用形态

港口群态势大屏：中央海图以气泡表示各港（气泡大小 = 在泊 + 锚地运力，颜色 = PCI 等级），航线以流量宽度表示 OD 运量；左侧为港口群 KPI 与排名表；右侧为时序演化（90 天到港量、等泊时长、PCI 曲线）与预测卡片。
到港节奏预测卡：未来 7 天逐日预测条带（P50 实线 + 80% 区间浅带），叠加历史实际值做回测对比。
供需缺口看板：逐日累计需求与供给的双折线 + 缺口柱，附决策建议条。

大宗物流运输-态势决策大屏.png

六、数据边界与常见问题

数据边界：港口历史挂靠、实时清单、船舶档案、航线里程来自船讯网；货量计划、采购策略、内部运力（自有船）来自内部系统；以「港口五位码 + 统计日」为主键聚合。

Q1：GetPortofCallByPort 只能查 7 天，90 天趋势怎么来？
用 7 天窗口滚动调用 13 次并去重即可覆盖 90 天；建议做成离线定时任务写入本地统计表，大屏只读统计表，不要实时扇出 13 次请求。

Q2：为什么预测要给区间而不是单值？
船舶到港是随机过程，单值必然有偏差。给出 80% 区间能让业务方理解不确定性，也便于对预测做回测校准（看实际值落在区间内的比例是否接近 80%）。

Q3：自有船要不要算进供给？
要。自有船的有效运力按 4.4 的周转周期折算后计入供给，避免重复租船。