分区管理模块开发设计文档

版本：V1.0.0
模块：DMS-LMS主数据管理-分区管理

一、模块概述

1.1 模块说明

分区管理用于维护运输系统中区域划分的基础数据，包含分区主表、分区邮编表、承运商分区邮编表三类数据，作为运输系统的核心主数据之一，为以下业务提供数据支持：

地址归属判定：通过邮编匹配订单地址所属分区
承运商匹配：根据分区+邮编区间匹配对应承运商
运费计算：按分区、邮编区间、承运商维度计费
路由规划：基于区域分区的路径优化

该模块属于主数据管理模块：

仅支持逻辑控制（通过 status 字段管理启用/禁用）
不允许物理删除，仅允许修改状态为禁用
支持启用 / 禁用控制
支持按状态、分区代码、邮编、承运商等条件查询

二、数据库表结构设计

2.1 表名

2.1.1 分区主表 `dms_delivery_zone`

作用：存储分区的基础信息（名称、代码、地理位置、状态等），作为分区数据的”主维度”。

CREATE TABLE dms_delivery_zone (
    delivery_zone_id           BIGINT       NOT NULL COMMENT "分区主键ID",
    delivery_zone_name         VARCHAR(64)  NULL COMMENT "分区名称",
    delivery_zone_code         VARCHAR(64)  NOT NULL COMMENT "分区代码",
    delivery_zone_status       TINYINT      NOT NULL DEFAULT 1 COMMENT "分区状态 1-启用 0-禁用",
    delivery_zone_country_id   INT          NULL COMMENT "分区所属国家ID",
    delivery_zone_country_code VARCHAR(32)  NULL COMMENT "分区所属国家代码",
    delivery_zone_state        VARCHAR(32)  NULL COMMENT "分区所属省州",
    delivery_zone_city         VARCHAR(32)  NULL COMMENT "分区所属城市",
    delivery_zone_district     VARCHAR(32)  NULL COMMENT "分区所属区",
    delivery_zone_street       VARCHAR(128) NULL COMMENT "分区所属街道",
    remark                     VARCHAR(256)  DEFAULT "" COMMENT "备注",
    over_flag                  TINYINT      NOT NULL DEFAULT "0" COMMENT "完结标识 0-未完结，1-已完结",
    create_user                BIGINT       NOT NULL COMMENT "创建人",
    create_time                DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT "创建时间",
    update_user                BIGINT                DEFAULT NULL COMMENT "更新人",
    update_time                DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT "更新时间",
    PRIMARY KEY (delivery_zone_id),
    KEY idx_delivery_zone_code (delivery_zone_code),
    KEY idx_create_time (create_time),
    KEY idx_update_time (create_time)
) ENGINE = INNODB
  DEFAULT CHARSET = utf8mb4 COMMENT = "分区表";

2.1.2 分区邮编表 `dms_delivery_zone_zipcode`

作用：存储分区下所有承运商的邮编区间合集（即”公共邮编池”），与 dms_delivery_zone 是一对多关系（一个分区对应多个邮编区间）。

CREATE TABLE dms_delivery_zone_zipcode (
    delivery_zone_zipcode_id BIGINT      NOT NULL COMMENT "分区邮编主键ID",
    delivery_zone_id         BIGINT      NOT NULL COMMENT "分区主键ID（关联dms_delivery_zone）",
    delivery_zone_code       VARCHAR(64) NOT NULL COMMENT "分区代码（冗余，便于查询）",
    start_zipcode            VARCHAR(32) NOT NULL COMMENT "起始邮编",
    end_zipcode              VARCHAR(32) NOT NULL COMMENT "结束邮编",
    remark                   VARCHAR(256)  DEFAULT "" COMMENT "备注",
    over_flag                TINYINT     NOT NULL DEFAULT "0" COMMENT "完结标识 0-未完结，1-已完结",
    create_user              BIGINT      NOT NULL COMMENT "创建人",
    create_time              DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT "创建时间",
    update_user              BIGINT               DEFAULT NULL COMMENT "更新人",
    update_time              DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT "更新时间",
    PRIMARY KEY (delivery_zone_zipcode_id),
    KEY idx_delivery_zone_id (delivery_zone_id),
    KEY idx_delivery_zone_code (delivery_zone_code),
    KEY idx_start_zipcode (start_zipcode),
    KEY idx_end_zipcode (end_zipcode),
    KEY idx_create_time (create_time),
    KEY idx_update_time (create_time)
) ENGINE = INNODB
  DEFAULT CHARSET = utf8mb4 COMMENT = "分区邮编表（分区下所有承运商的邮编合集）";

2.1.3 承运商分区邮编表 `dms_zone_carrier_zipcode`

作用：存储分区下特定承运商的邮编区间（即”承运商专属邮编池”），与 dms_delivery_zone 是一对多关系（一个分区对应多个承运商的邮编区间），与 dms_zone_carrier_zipcode 自身是多对多关系（一个承运商可对应多个邮编区间，一个邮编区间可属于多个承运商）。

CREATE TABLE dms_zone_carrier_zipcode (
    zone_provider_zipcode_id BIGINT      NOT NULL COMMENT "承运商分区邮编主键ID",
    delivery_zone_id         BIGINT      NOT NULL COMMENT "分区主键ID（关联dms_delivery_zone）",
    delivery_zone_code       VARCHAR(64) NOT NULL COMMENT "分区代码（冗余，便于查询）",
    carrier_id               BIGINT      NOT NULL COMMENT "承运商主键ID",
    carrier_code             VARCHAR(32) NOT NULL COMMENT "承运商编码",
    start_zipcode            VARCHAR(32) NOT NULL COMMENT "起始邮编",
    end_zipcode              VARCHAR(32) NOT NULL COMMENT "结束邮编",
    remark                   VARCHAR(256)  DEFAULT "" COMMENT "备注",
    over_flag                TINYINT     NOT NULL DEFAULT "0" COMMENT "完结标识 0-未完结，1-已完结",
    create_user              BIGINT      NOT NULL COMMENT "创建人",
    create_time              DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT "创建时间",
    update_user              BIGINT               DEFAULT NULL COMMENT "更新人",
    update_time              DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT "更新时间",
    PRIMARY KEY (zone_provider_zipcode_id),
    KEY idx_start_zipcode (start_zipcode),
    KEY idx_end_zipcode (end_zipcode),
    KEY idx_create_time (create_time),
    KEY idx_update_time (create_time)
) ENGINE = INNODB
  DEFAULT CHARSET = utf8mb4 COMMENT = "承运商分区邮编表（分区下特定承运商的邮编）";

三、表关系说明

dms_delivery_zone（主表） ↔ dms_delivery_zone_zipcode（附属表）：一对多。一个分区（delivery_zone_id）可对应多个邮编区间（如 SFO 分区可能有 92101-92110、92111-92120 等多个邮编段）。
dms_delivery_zone（主表） ↔ dms_zone_carrier_zipcode（附属表）：一对多。一个分区（delivery_zone_id）可对应多个承运商的邮编区间（如 SFO 分区下，D01 承运商可能有 92101-92110，D02 承运商可能有 92111-92120）。
dms_zone_carrier_zipcode 内部：多对多。一个承运商（carrier_id）可对应多个邮编区间（start_zipcode/end_zipcode），一个邮编区间也可属于多个承运商（如 92101-92110 可能同时被 D01 和 D02 承运商覆盖）。

四、业务规则设计

分区代码（delivery_zone_code）唯一，不可重复。
邮编区间（start_zipcode/end_zipcode）需满足 start_zipcode ≤ end_zipcode，且格式合法（如数字或带连字符的邮编）。
分区状态（delivery_zone_status）默认启用（1），禁用（0）后不可被业务逻辑调用。
不允许物理删除分区/邮编/承运商邮编记录，仅允许修改 over_flag 为 1（完结）或 status 为 0（禁用）。
更新时间（update_time）由数据库自动维护，无需业务层干预。

五、Feign接口设计

@FeignClient(
    value = AppConstant.APPLICATION_DMS_LMS_SERVICE_NAME,
    fallback = DmsZoneManageClientFallback.class
)
public interface IDmsZoneManageClient {

    String API_PREFIX = "/feign/client/zoneManage";

    /**
     * 获取分区信息列表（支持状态、分区代码、邮编模糊查询）
     * @param status 分区状态 0-禁用 1-启用
     * @param zoneCode 分区代码（模糊）
     * @param zipcode 邮编（模糊）
     * @return 分区列表（含关联邮编、承运商邮编）
     */
    @PostMapping(API_PREFIX + "/getDeliveryZones")
    R<List<DmsDeliveryZoneVO>> getDeliveryZones(
        @RequestParam(required = false) Integer status,
        @RequestParam(required = false) String zoneCode,
        @RequestParam(required = false) String zipcode
    );

    /**
     * 根据分区ID查询分区详情（含邮编、承运商邮编）
     * @param zoneId 分区主键ID
     * @return 分区详情VO
     */
    @GetMapping(API_PREFIX + "/getDeliveryZoneById")
    R<DmsDeliveryZoneVO> getDeliveryZoneById(@RequestParam("zoneId") Long zoneId);

    /**
     * 根据分区代码查询分区
     * @param zoneCode 分区代码
     * @return 分区VO
     */
    @GetMapping(API_PREFIX + "/getDeliveryZoneByCode")
    R<DmsDeliveryZoneVO> getDeliveryZoneByCode(@RequestParam("zoneCode") String zoneCode);

    /**
     * 根据邮编查询所属分区及承运商
     * @param zipcode 邮编
     * @return 分区+承运商匹配结果
     */
    @GetMapping(API_PREFIX + "/getZoneByZipcode")
    R<List<DmsZoneCarrierMatchVO>> getZoneByZipcode(@RequestParam("zipcode") String zipcode);
}

六、实体对象设计（示例）

6.1 分区主实体 `DmsDeliveryZone`

@Data
@TableName("dms_delivery_zone")
public class DmsDeliveryZone extends BasePo {

    @TableId
    private Long deliveryZoneId;

    private String deliveryZoneName;

    private String deliveryZoneCode;

    /**
     * 0-禁用 1-启用
     */
    private Integer deliveryZoneStatus;

    private Integer deliveryZoneCountryId;

    private String deliveryZoneCountryCode;

    private String deliveryZoneState;

    private String deliveryZoneCity;

    private String deliveryZoneDistrict;

    private String deliveryZoneStreet;

    private String remark;

    /**
     * 0-未完结 1-已完结
     */
    private Integer overFlag;
}

6.2 分区邮编实体 `DmsDeliveryZoneZipcode`

@Data
@TableName("dms_delivery_zone_zipcode")
public class DmsDeliveryZoneZipcode extends BasePo {

    @TableId
    private Long deliveryZoneZipcodeId;

    private Long deliveryZoneId;

    private String deliveryZoneCode;

    private String startZipcode;

    private String endZipcode;

    private String remark;

    /**
     * 0-未完结 1-已完结
     */
    private Integer overFlag;
}

6.3 承运商分区邮编实体 `DmsZoneCarrierZipcode`

@Data
@TableName("dms_zone_carrier_zipcode")
public class DmsZoneCarrierZipcode extends BasePo {

    @TableId
    private Long zoneProviderZipcodeId;

    private Long deliveryZoneId;

    private String deliveryZoneCode;

    private Long carrierId;

    private String carrierCode;

    private String startZipcode;

    private String endZipcode;

    private String remark;

    /**
     * 0-未完结 1-已完结
     */
    private Integer overFlag;
}

七、JSON结构设计（示例）

7.1 单分区详情（含邮编、承运商邮编）

{
  "deliveryZoneId": 10001,
  "deliveryZoneName": "SFO分区",
  "deliveryZoneCode": "SFO",
  "deliveryZoneStatus": 1,
  "deliveryZoneCountryId": 1,
  "deliveryZoneCountryCode": "US",
  "deliveryZoneState": "CA",
  "deliveryZoneCity": "San Francisco",
  "deliveryZoneDistrict": "",
  "deliveryZoneStreet": "",
  "remark": "旧金山分区",
  "overFlag": 0,
          "carrierZipcodes": [
            {
              "zoneProviderZipcodeId": 30001,
              "deliveryZoneId": 10001,
              "deliveryZoneCode": "SFO",
              "carrierId": 1,
              "carrierCode": "D01",
              "startZipcode": "92101",
              "endZipcode": "92105",
              "remark": "",
              "overFlag": 0
            },
            {
              "zoneProviderZipcodeId": 30002,
              "deliveryZoneId": 10001,
              "deliveryZoneCode": "SFO",
              "carrierId": 2,
              "carrierCode": "D02",
              "startZipcode": "92106",
              "endZipcode": "92106",
              "remark": "",
              "overFlag": 0
            }
          ],
  "createUser": 1,
  "createTime": "2026-03-01T09:45:00",
  "updateUser": 1,
  "updateTime": "2026-03-01T09:45:00"
}

7.2 分区列表（简略版）

[
  {
    "deliveryZoneId": 10001,
    "deliveryZoneName": "SFO分区",
    "deliveryZoneCode": "SFO",
    "deliveryZoneStatus": 1,
    "deliveryZoneCountryCode": "US",
    "deliveryZoneState": "CA",
    "deliveryZoneCity": "San Francisco",
    "overFlag": 0,
    "createTime": "2026-03-01T09:45:00"
  }
]

作者：陆飞创建时间：2026-03-02 15:49
最后编辑：陆飞更新时间：2026-03-03 10:08

分区管理