客户下单
  → 取出寄件地址和收件地址
  → 高德 geoCode(address) 得到经纬度          ← 外部依赖
  → ServiceScopeFeign.queryListByLocation(1, lng, lat)
  → MongoDB: {polygon: {$geoIntersects: point}, type: 1}
  → 命中多条时取第一条的 bid 作为网点 id
  → 没命中 → 抛「地址不在服务范围」→ 下单失败

// chain-cloud-ms-service-scope-service entity/ServiceScopeEntity.java
@Data
@Document("cc_service_scope")
public class ServiceScopeEntity {

    @Id @JsonIgnore private ObjectId id;

    /** 业务id，可以是机构或快递员 */
    @Indexed
    private Long bid;

    /** 类型 ServiceTypeEnum */
    @Indexed
    private Integer type;

    /** 多边形范围，是闭合的范围，开始经纬度与结束经纬度必须一样
     *  x: 经度，y: 纬度 */
    @GeoSpatialIndexed(type = GeoSpatialIndexType.GEO_2DSPHERE)
    private GeoJsonPolygon polygon;

    private Long created;
    private Long updated;
}

// ScopeServiceImpl#queryListByPoint
@Override
public List<ServiceScopeEntity> queryListByPoint(ServiceTypeEnum type, GeoJsonPoint point) {
    var query = Query.query(Criteria.where("polygon")
            .intersects(point)
            .and("type").is(type.getCode()));
    return this.mongoTemplate.find(query, ServiceScopeEntity.class);
}

db.cc_service_scope.find({
  polygon: { $geoIntersects: { $geometry: { type: "Point", coordinates: [ 116.46, 39.92 ] } } },
  type: 1
})

// ScopeServiceImpl#queryListByPoint(type, address)  —— 重载版本
@Override
public List<ServiceScopeEntity> queryListByPoint(ServiceTypeEnum type, String address) {
    // 根据详细地址查询坐标
    var geoResult = this.eagleMapTemplate.opsForBase().geoCode(ProviderEnum.AMAP, address, null);
    var coordinate = geoResult.getLocation();
    return this.queryListByPoint(type, new GeoJsonPoint(coordinate.getLongitude(), coordinate.getLatitude()));
}

queryListByPoint(type, address)          —— 字符串入口（内部做地理编码）
        ↓
queryListByPoint(type, GeoJsonPoint)     —— 空间入口（真正的查询）

// chain-cloud-ms-oms-service OrderServiceImpl#getAgencyId
private HashMap getAgencyId(String address) throws CCException {
    if (ObjectUtil.isEmpty(address)) {
        throw new CCException("下单时发货地址不能为空");
    }
    // 根据详细地址查询坐标
    GeoResult geoResult = this.eagleMapTemplate.opsForBase().geoCode(ProviderEnum.AMAP, address, null);
    Coordinate coordinate = geoResult.getLocation();
    if (ObjectUtil.isEmpty(coordinate)) {
        throw new CCException("地址无法定位");
    }
    double lng = coordinate.getLongitude();   // 经度
    double lat  = coordinate.getLatitude();   // 纬度
    DecimalFormat df = new DecimalFormat("#.######");
    String location = StrUtil.format("{},{}", df.format(lng), df.format(lat));

    // 反查网点
    List<ServiceScopeDTO> serviceScopeDTOS =
        agencyScopeFeign.queryListByLocation(1, coordinate.getLongitude(), coordinate.getLatitude());
    if (CollectionUtils.isEmpty(serviceScopeDTOS)) {
        throw new CCException("地址不在服务范围");
    }
    HashMap result = new HashMap();
    result.put("agencyId", serviceScopeDTOS.get(0).getBid());   // ← 命中多条时取第一条
    result.put("location", location);
    return result;
}

// 1. 在 Entity 上把约定写死在 Javadoc 里（现有代码做了这一步）
/** x: 经度，y: 纬度 */

// 2. 在 DTO 转换处集中做一次方向转换，不要在各处重复
public static ServiceScopeEntity toEntity(ServiceScopeDTO dto) {
    ...
    List<Point> pointList = dto.getPolygon().stream()
            // 注意：Coordinate(longitude, latitude) → Point(x=lng, y=lat)
            .map(c -> new Point(c.getLongitude(), c.getLatitude()))
            .collect(Collectors.toList());
    serviceScopeEntity.setPolygon(new GeoJsonPolygon(pointList));
    return serviceScopeEntity;
}

// 3. 启动时做一次数据体检（强烈建议加）
//    经度必须在 [-180, 180]，纬度必须在 [-90, 90]
//    一旦发现纬度 > 90 或经度 > 90，就是写反了

// 就近原则的实现（在 scope 服务里做，而不是让 OMS 排）
public ServiceScopeEntity queryNearestByPoint(ServiceTypeEnum type, GeoJsonPoint point) {
    var query = Query.query(Criteria.where("polygon").intersects(point)
            .and("type").is(type.getCode()));
    var list = mongoTemplate.find(query, ServiceScopeEntity.class);
    return list.stream()
            .min(Comparator.comparingDouble(e -> distance(point, e.getCentroid())))
            .orElse(null);
}

// ScopeServiceImpl#saveOrUpdate
var query = Query.query(Criteria.where("bid").is(bid).and("type").is(type.getCode()));
var serviceScopeEntity = this.mongoTemplate.findOne(query, ServiceScopeEntity.class);
if (null == serviceScopeEntity) {
    // 新增
    serviceScopeEntity = new ServiceScopeEntity();
    ...
} else {
    // 更新
    serviceScopeEntity.setPolygon(polygon);
    ...
}
try {
    this.mongoTemplate.save(serviceScopeEntity);
    return true;
} catch (Exception e) {
    log.error("新增/更新服务范围数据失败！...", e);
}
return false;

线程 A: findOne → null      ┐
线程 B: findOne → null      ├ 两个线程都认为"要新增"
线程 A: save(新文档)        │
线程 B: save(新文档)        ┘ → 集合里出现两条 (bid, type) 相同的文档

@Indexed private Long bid;      // 非唯一
@Indexed private Integer type;  // 非唯一

出现两条重复文档
  → queryListByPoint 空间查询返回重复的网点 id  ← 结果"看起来"还行
  → queryByBidAndType 用 findOne
  → 如果两条都被命中，Spring Data 抛 IncorrectResultSizeDataAccessException
  → 保存 / 查询接口直接 500

// 第 1 层：加唯一复合索引（必须）
@CompoundIndex(name = "bid_type_uniq", def = "{'bid':1,'type':1}", unique = true)
@Document("cc_service_scope")
public class ServiceScopeEntity { ... }

// 第 2 层：改用 MongoDB 原生 upsert，彻底消除 check-then-act
public Boolean saveOrUpdate(Long bid, ServiceTypeEnum type, GeoJsonPolygon polygon) {
    Query query = Query.query(Criteria.where("bid").is(bid).and("type").is(type.getCode()));
    Update update = new Update()
            .set("polygon", polygon)
            .set("updated", System.currentTimeMillis())
            .setOnInsert("created", System.currentTimeMillis());
    UpdateResult result = mongoTemplate.upsert(query, update, ServiceScopeEntity.class);
    return result.getUpsertedCount() > 0 || result.getModifiedCount() >= 0;
}

// 第 3 层：历史重复数据清理
db.cc_service_scope.aggregate([
  { $group: { _id: "$bid", n: { $sum: 1 } } },
  { $match: { n: { $gt: 1 } } }
])

var geoResult = this.eagleMapTemplate.opsForBase().geoCode(ProviderEnum.AMAP, address, null);
var coordinate = geoResult.getLocation();      // geoResult 为 null → NPE
return this.queryListByPoint(type, new GeoJsonPoint(
        coordinate.getLongitude(), coordinate.getLatitude()));  // coordinate 为 null → NPE

var geoResult = this.eagleMapTemplate.opsForBase().geoCode(ProviderEnum.AMAP, address, null);
if (ObjectUtil.isEmpty(geoResult) || ObjectUtil.isEmpty(geoResult.getLocation())) {
    throw new CCException(ScopeExceptionEnum.ADDRESS_NOT_LOCATABLE);  // 业务异常 + 友好提示
}

// 正确的多边形：首尾同点
[
  [116.340064, 40.061245],
  [116.347081, 40.061836],
  [116.347510, 40.058420],
  [116.342446, 40.058092],
  [116.340064, 40.061245]    // ← 必须和第一个点一样
]

List<Point> pts = pointList;
if (!pts.isEmpty() && !pts.get(0).equals(pts.get(pts.size() - 1))) {
    // 自动闭合，而不是报错——对运营更友好
    pts = new ArrayList<>(pts);
    pts.add(pts.get(0));
}

// ScopeServiceImpl
@Override
public List<ServiceScopeEntity> queryAdjacentScopes(Double longitude, Double latitude,
                                                   ServiceTypeEnum type, Integer limit) {
    return null;      // ← 返回 null
}

// ScopeController
@GetMapping("recommend")
@ApiOperation(value = "智能推荐网点", notes = "基于AI智能推荐最优网点")
public ResponseEntity<ServiceScopeResponse> recommendAgency(@RequestParam("address") String address) {
    // TODO 待实现
    return null;
}

LangGraph 流程：
  地址模糊解析节点 → 高德地理编码 + 行政区划补全（"国贸三期" → 朝阳区 + 完整地址）
       ↓
  候选网点召回节点 → $geoNear 取周边 N 个网点（注意是 $near，这里正好合适）
       ↓
  边界判定节点 → 优先用 $geoIntersects 判断覆盖；覆盖内的直接给答案
       ↓
  兜底推荐节点 → 没覆盖时给最近网点 + 明说"该地址暂未覆盖，已推荐 XX 网点"
       ↓
  理由生成节点 → LLM 依据以上结构化事实生成一句人话

// 缓存 key 设计
String key = "geo:amap:" + DigestUtils.md5Hex(address.trim().replaceAll("\\s+", ""));
// 缓存策略：先查 Redis → 未命中调高德 → 回填，TTL 30 天
// 高德失败时不要缓存失败结果，但要加短 TTL 的"负缓存"防穿透（TTL 60s）