// chain-cloud-ms-track-service entity/TrackEntity.java
@Data
@Document("cc_track")
public class TrackEntity {

    @Id @JsonIgnore private ObjectId id;

    @Indexed private String transportOrderId;          // 运单号

    /** 规划轨迹点线 */
    private GeoJsonLineString planGeoJsonLine;         // ← 不变

    /** 总距离，米 */
    private Double distance;

    /** 最新位置（x=经度，y=纬度） */
    private GeoJsonPoint lastPoint;                    // ← 覆盖更新

    private TrackStatusEnum status;                    // NEW(1) / COMPLETE(4)
    private TrackTypeEnum type;                        // DRIVER(2) / COURIER(3)

    private Long created;
    private Long updated;
}

如果设计成 pointList 数组追加：
  2400 个点 × 32 字节/点 ≈ 76KB → 远超 MongoDB 单文档 16MB 限制的风险，
  而且每次上报都要重写整个数组（更新放大）

设计成 lastPoint 覆盖：
  文档大小恒定，上报是 O(1) 的点更新
  → 读取时"历史轨迹"和"规划轨迹"分开取

{
  "type": "LineString",
  "coordinates": [
    [116.46, 39.92],
    [116.47, 39.93],
    ...
  ]
}

// chain-cloud-ms-track-service TrackServiceImpl#create
@Override
public boolean create(String transportOrderId) {
    Query query = Query.query(Criteria.where("transportOrderId").is(transportOrderId));
    TrackEntity trackEntity = this.mongoTemplate.findOne(query, TrackEntity.class);
    if (ObjectUtil.isNotEmpty(trackEntity)) {
        throw new CCException(TrackExceptionEnum.TRACK_ALREADY_EXISTS);   // 幂等
    }
    TrackEntity track = new TrackEntity();
    track.setTransportOrderId(transportOrderId);
    track.setCreated(System.currentTimeMillis());
    track.setUpdated(track.getCreated());
    track.setStatus(TrackStatusEnum.NEW);
    track.setPlanGeoJsonLine(this.queryPlanGeoJsonLineString(transportOrderId, track));
    this.mongoTemplate.save(track);
    return true;
}

@Document("cc_track")
public class TrackEntity {
    @Indexed(unique = true)                 // ← 加 unique
    private String transportOrderId;
}

// TrackServiceImpl#queryPlanGeoJsonLineString
// 通过运单号查询运单，将转运节点作为途经点
TransportOrderDTO transportOrderDTO = this.transportOrderFeign.findById(transportOrderId);
String transportLine = transportOrderDTO.getTransportLine();
String wayPoints = null;                        // 途经点，分号分割
if (StrUtil.isNotEmpty(transportLine)) {
    // transportLine 是亮点 2 里算出来的完整路径（JSON）
    // 从 nodeList 里取出每个节点的经纬度
    ... nodeList[*].longitude/latitude, 0 值 → "err" → filter ...
    wayPoints = StrUtil.join(";", pointList);
} else {
    // 收件人与发件人在同一个网点，没有转运路线
    // → 将当前机构id作为途经点
    OrganDTO organDTO = this.organFeign.queryById(transportOrderDTO.getCurrentAgencyId());
    if (ObjectUtil.isNotEmpty(organDTO)) {
        wayPoints = StrUtil.format("{},{}", organDTO.getLongitude(), organDTO.getLatitude());
    } else {
        //理论上没有这种情况，如果出现这种情况就不设置途经点了
    }
}

OrderLocationDTO orderLocationDTO = this.orderFeign.findOrderLocationByOrderId(transportOrderDTO.getOrderId());
Map<String, Object> param = MapUtil.<String, Object>builder()
        .put(ObjectUtil.isNotEmpty(wayPoints), "waypoints", wayPoints)
        .put("show_fields", "polyline")
        .build();

String driving = this.eagleMapTemplate.opsForDirection()
        .driving(ProviderEnum.AMAP, new Coordinate(origin), new Coordinate(destination), param);

用户下单时，亮点 2 已经在 Neo4j 里规划出了一条完整路径：
  北京朝阳网点 → 通州分拣中心 → 北京转运中心 → 天津转运中心 → 天津网点

现在要做轨迹，不能让高德"直线规划"，
而是要把这条路径上的【每个转运节点】作为途经点传给高德，
让高德沿着一整条真实运输路线画折线。

wayPoints = StrUtil.join(";", pointList);

// 0 值 → "err" → filter

JSONArray steps = jsonObject.getByPath("route.paths[0].steps", JSONArray.class);

// 将所有的坐标点收集起来
List<Point> points = new ArrayList<>();
List<Object> polyLines = CollUtil.getFieldValues(steps, "polyline");
for (Object polyLine : polyLines) {
    List<GeoJsonPoint> list = StrUtil.split(Convert.toStr(polyLine), ';')
            .stream().map(coordinateStr -> {
                double[] ds = Convert.convert(double[].class, StrUtil.splitTrim(coordinateStr, ','));
                return new GeoJsonPoint(ds[0], ds[1]);
            }).collect(Collectors.toList());
    points.addAll(list);
}

//TODO 如果路线规则的节点比较多，可能会出现内存溢出的情况，学生思考下解决方案

return new GeoJsonLineString(points);

//TODO 如果路线规则的节点比较多，可能会出现内存溢出的情况，学生思考下解决方案

一次跨省长途（比如京藏线 1200km）：
  高德返回的 steps 可能有几千个
  每个 step 的 polyline 可能有几百个点
  总点数：几万到十几万个

每个 GeoJsonPoint 对象（JVM 内存开销约 40~60 字节）
  10 万个点 ≈ 5MB 对象 + 序列化过程中的临时字符串可能上百 MB

如果并发创建轨迹（多个司机同时上报），
  每个请求都持有一个几 MB 的 List
  → Tomcat 堆内存直接被打爆

// TrackServiceImpl#upload
private boolean upload(List<String> transportOrderIds, double lng, double lat,
                       TrackTypeEnum trackTypeEnum) {
    if (CollUtil.isEmpty(transportOrderIds)) return false;

    // 更新的条件
    Query query = Query.query(Criteria.where("transportOrderId")
            .in(transportOrderIds)
            .and("status").is(TrackStatusEnum.NEW));
    // 更新的数据
    Update update = Update.update("lastPoint", new GeoJsonPoint(lng, lat))
            .set("type", trackTypeEnum)
            .set("updated", System.currentTimeMillis());
    UpdateResult updateResult = this.mongoTemplate.updateMulti(query, update, TrackEntity.class);
    return updateResult.getModifiedCount() > 0;
}

// 一个运输任务对应多个运单
@Override
public boolean uploadFromTruck(Long transportTaskId, double lng, double lat) {
    // 通过运输任务查询订单号列表
    List<String> list = this.transportTaskFeign.queryTransportOrderIdListById(transportTaskId);
    return upload(list, lng, lat, TrackTypeEnum.DRIVER);
}

track：计算密集（调高德），数据量小（一个运单一条）
transport-info：写入密集（每个节点事件一条），数据量大，查询场景多

// TransportInfoMQListener
@RabbitListener(/* TRANSPORT_INFO_APPEND */)
public void listenTransportInfoAppend(String msg) {
    // 没有任何实现
}

// common/vo/TransportInfoMsg.java
public class TransportInfoMsg extends BaseMsg {
    private Long organId;           // ← 没有任何生产者设置它
    private String transportOrderId;
    private String status;
    private String info;
}

1. 高德最多支持 16 个途经点
   代码的 Javadoc 里写了"（高德地图最多支持16个途经点）"
   但代码【没有做截断】！
   超过 16 个的高德会报错，整条轨迹创建失败

2. 途经点只约束"经过哪些点"，不约束"走哪条边"
   从 A 中转场到 B 中转场，高德仍可能规划出另一条路

3. 如果中转节点的实际装货位置和节点坐标有偏差（比如网点很大），
   轨迹会有几十米的误差

// 1. 途经点截断 + 降级
private static final int MAX_WAYPOINTS = 15;   // 高德限制 16，留一个余量

private String buildWayPoints(List<OrganDTO> nodes) {
    List<String> points = nodes.stream()
            .filter(n -> n.getLongitude() != null && n.getLatitude() != null)
            .map(n -> StrUtil.format("{},{}", n.getLongitude(), n.getLatitude()))
            .collect(Collectors.toList());

    if (points.size() <= MAX_WAYPOINTS) {
        return StrUtil.join(";", points);
    }

    // 超过上限：均匀采样（保留首尾），并记录降级标记
    List<String> sampled = sampleEvenly(points, MAX_WAYPOINTS);
    log.warn("途经点 {} 个超过高德限制 {}，已均匀采样降级", points.size(), MAX_WAYPOINTS);
    return StrUtil.join(";", sampled);
}

// 2. 分段规划 + 拼接
//    如果途经点真的很多（比如跨 5 个省），
//    正确做法是【分成多段】逐段调高德，然后把折线拼接起来
List<GeoJsonLineString> segments = new ArrayList<>();
for (int i = 0; i < legPoints.size() - 1; i++) {
    String leg = callAmap(legPoints.get(i), legPoints.get(i + 1));
    segments.add(parse(leg));
}
return concat(segments);        // 拼接时去掉相邻段的重叠点

double[] ds = Convert.convert(double[].class, StrUtil.splitTrim(coordinateStr, ','));
return new GeoJsonPoint(ds[0], ds[1]);

一次 doc 更新 = 读 3MB + 改 3MB + 写 3MB
每 30 秒一次上报 × 几百个车辆
→ MongoDB 的 IO 和网络开销都会非常大

cc_track       —— 轻量，高频更新
  { _id, transportOrderId, lastPoint, type, status, updated }

cc_track_plan  —— 重量，写一次读多次
  { transportOrderId, planGeoJsonLine, distance }

超过阈值（比如 1000 个点）时：
  1. 把完整的折线序列化后上传到对象存储 / GridFS
  2. cc_track_plan 里只存一个引用 key + 包围盒（bounding box）
  3. 查询时按需拉取，地图缩放到一定级别时只下发抽稀后的简化版

一条跨省路线的原始折线：10 万个点 ≈ 3MB
用户实际能看到的：整个屏幕就那么几个像素宽度
→ 传到前端也画不出区别，只是浪费带宽和卡顿

抽稀后：1000 个点 ≈ 30KB，形状几乎无损

/**
 * Douglas-Peucker 折线抽稀
 * @param points 原始点集
 * @param epsilon 阈值（度）。约 1e-5 ≈ 1 米
 */
public static List<GeoJsonPoint> simplify(List<GeoJsonPoint> points, double epsilon) {
    if (points == null || points.size() < 3) return points;

    boolean[] keep = new boolean[points.size()];
    keep[0] = true;
    keep[points.size() - 1] = true;      // 首尾必须保留

    simplifySection(points, 0, points.size() - 1, epsilon, keep);

    List<GeoJsonPoint> result = new ArrayList<>();
    for (int i = 0; i < points.size(); i++) {
        if (keep[i]) result.add(points.get(i));
    }
    return result;
}

private static void simplifySection(List<GeoJsonPoint> pts, int first, int last,
                                    double epsilon, boolean[] keep) {
    if (last <= first + 1) return;

    // 找到偏离首尾连线最远的点
    double maxDist = 0;
    int index = -1;
    GeoJsonPoint a = pts.get(first);
    GeoJsonPoint b = pts.get(last);
    for (int i = first + 1; i < last; i++) {
        double d = perpendicularDistance(pts.get(i), a, b);
        if (d > maxDist) { maxDist = d; index = i; }
    }

    // 偏离超过阈值就保留，并递归处理两侧
    if (maxDist > epsilon && index != -1) {
        keep[index] = true;
        simplifySection(pts, first, index, epsilon, keep);
        simplifySection(pts, index, last, epsilon, keep);
    }
}

/** 点到线段的垂距（简化版：点到直线） */
private static double perpendicularDistance(GeoJsonPoint p, GeoJsonPoint a, GeoJsonPoint b) {
    double x = a.getX(), y = a.getY();
    double dx = b.getX() - x, dy = b.getY() - y;
    if (dx == 0 && dy == 0) return DistanceCalculator.calculateDistance(
            p.getX(), p.getY(), x, y);

    double t = ((p.getX() - x) * dx + (p.getY() - y) * dy) / (dx * dx + dy * dy);
    t = Math.max(0, Math.min(1, t));            // 投影到线段上
    double projX = x + t * dx, projY = y + t * dy;
    return DistanceCalculator.calculateDistance(p.getX(), p.getY(), projX, projY);
}

// 地图缩放到全国级别时给 500 个点
// 缩放到城市级别时给 5000 个点
// 缩放到街道级别时给 50000 个点
public List<GeoJsonPoint> pointsForZoom(int zoomLevel) {
    double epsilon = switch (zoomLevel) {
        case 0, 1, 2, 3 -> 1e-3;      // 全国：约 100 米精度
        case 4, 5, 6    -> 1e-4;      // 城市：约 10 米
        case 7, 8, 9    -> 1e-5;      // 街道：约 1 米
        default         -> 0.0;       // 最高级别：全量
    };
    return simplify(originalPoints, epsilon);
}

//TODO 如果路线规则的节点比较多，可能会出现内存溢出的情况，学生思考下解决方案
return new GeoJsonLineString(points);

// 方案 A：抽稀（在写入前就把点数降下来）—— 首选
// 解决 90% 的问题，成本最低

// 方案 B：流式处理，减少中间对象
private static void parsePolyline(String polyline, List<GeoJsonPoint> target) {
    int len = polyline.length();
    int start = 0;
    for (int i = 0; i <= len; i++) {
        if (i == len || polyline.charAt(i) == ';') {
            target.add(parsePoint(polyline, start, i));
            start = i + 1;
        }
    }
}
private static GeoJsonPoint parsePoint(String s, int start, int end) {
    int comma = -1;
    for (int i = start; i < end; i++) {
        if (s.charAt(i) == ',') { comma = i; break; }
    }
    if (comma < 0) return null;                    // ← 防御：格式不对就跳过
    return new GeoJsonPoint(
        Double.parseDouble(s.substring(start, comma)),
        Double.parseDouble(s.substring(comma + 1, end)));
}

// 方案 C：拆集合（解决文档过大）—— 见难点 2

// TransportInfoMQListener.java
@RabbitListener(bindings = @QueueBinding(
        value = @Queue(name = Constants.MQ.Queues.TRANSPORT_INFO_APPEND),
        exchange = @Exchange(name = Constants.MQ.Exchanges.TRANSPORT_INFO,
                             type = ExchangeTypes.TOPIC, delayed = Constants.MQ.DELAYED),
        key = Constants.MQ.RoutingKeys.TRANSPORT_INFO_APPEND))
public void listenTransportInfoAppend(String msg) {
    // 空方法体
}

// work / web-courier 构造 TransportInfoMsg 时
// 只设置了 transportOrderId / status / info，没设置 organId

// 建议在 common 里加一个消息契约测试
// 遍历所有 TransportInfoMsg 的生产者，断言必填字段都有值
@Test
void 物流跟踪消息必须包含机构id() {
    TransportInfoMsg msg = buildTransportInfoMsg(order);
    assertThat(msg.getOrganId()).isNotNull();
    assertThat(msg.getTransportOrderId()).isNotBlank();
}

if (ObjectUtil.isNotEmpty(trackEntity)) {
    throw new CCException(TrackExceptionEnum.TRACK_ALREADY_EXISTS);
}

MQ 消费场景下，"已存在"恰恰说明【这条消息是重复投递】，
应该直接【跳过并 ack】，而不是抛异常。

抛异常 → 消费者重试 3 次 → 每次都抛"已存在"
  → 重试耗尽 → 进死信队列
  → 运维去死信队列里一看：全是"轨迹已存在"的正常情况

@Override
public boolean create(String transportOrderId) {
    // 直接用 upsert，不存在才计算轨迹（因为计算轨迹要调高德，很贵）
    Query query = Query.query(Criteria.where("transportOrderId").is(transportOrderId));
    if (mongoTemplate.exists(query, TrackEntity.class)) {
        log.info("运单 {} 的轨迹已存在，跳过", transportOrderId);
        return true;                       // ← 正常返回，不抛异常
    }
    TrackEntity track = new TrackEntity();
    ...
    try {
        mongoTemplate.insert(track);
        return true;
    } catch (DuplicateKeyException e) {
        return true;                       // ← 唯一索引兜底，视为成功
    }
}

Coordinate origin = new Coordinate(originLng, originLat);      // 来自 order_location
Coordinate destination = new Coordinate(destLng, destLat);    // 来自 order_location

// OrderServiceImpl#getAgencyId
DecimalFormat df = new DecimalFormat("#.######");
String location = StrUtil.format("{},{}", df.format(lng), df.format(lat));
// → "116.460000,39.920000"（字符串，逗号分隔）

String[] split = orderLocation.getSendLocation().split(",");
double lnt = Double.parseDouble(split[0]);
double lat = Double.parseDouble(split[1]);

方案 A：存两个独立字段（推荐）
  send_longitude DECIMAL(10,7)
  send_latitude  DECIMAL(10,7)

方案 B：存 GeoJSON Point 类型的 JSON
  send_location = {"type":"Point","coordinates":[116.4600000,39.9200000]}

方案 C：保持字符串，但加字段名分隔符
  "lng:116.460000,lat:39.920000"

// 运单上存着亮点 2 算出来的完整路径（JSON）
String transportLine = transportOrderDTO.getTransportLine();
// 提取每个节点的经纬度，拼成高德的 waypoints 格式
wayPoints = StrUtil.join(";", pointList);

params.put("waypoints", wayPoints);
params.put("show_fields", "polyline");

Query query = Query.query(Criteria.where("transportOrderId")
        .in(transportOrderIds)              // 批量：一个司机的多个包裹
        .and("status").is(TrackStatusEnum.NEW));   // ★ 只更新未完成的
Update update = Update.update("lastPoint", new GeoJsonPoint(lng, lat))
        .set("type", trackTypeEnum)
        .set("updated", System.currentTimeMillis());
mongoTemplate.updateMulti(query, update, TrackEntity.class);

if (ObjectUtil.isNotEmpty(trackEntity)) {
    throw new CCException(TrackExceptionEnum.TRACK_ALREADY_EXISTS);
}