开发文档

鲜花交易系统与鲜花交易平台(PHP / ThinkPHP 版)的研发记录:功能上线、架构演进与实施经验,按发布日期持续更新。

行政区划数据怎么做成"可维护":四级表 + 地图选点

区划不只是"省市县"三个下拉框

鲜花业务的地址有三类用法:

  • 收货地址:需要精确到区县,配送费按地区规则匹配;
  • 门店配送范围:以门店坐标为圆心,或按区划圈定可送范围;
  • 供应商产地:用于产地直供标签与物流估算。

这三类用法对区划的要求不一样:收货地址要稳定的编码,配送范围要坐标,产地要能按省聚合统计。因此区划表必须同时具备编码体系 + 层级关系 + 坐标能力。

表结构口径

区划表按四级组织:省 → 市 → 区县 → 街道/乡镇。每级一条记录,用父级业务号串起来,同时保留国家标准的行政区划编码。

几条落地口径:

  • 编码唯一,名称可重。同一个名字可能出现在不同省份("城关区"就是典型),按名称匹配一定出错,所有关联都走编码;
  • 层级用物化路径。每条记录带一份"从省到自己的路径",按省统计时用前缀匹配即可,不必递归查询;
  • 停用不删除。区划调整(撤县设区)在现实中经常发生,历史地址必须还能解析,因此旧记录保留并标记停用,新记录用新编码。

存量数据迁移的三条纪律

这次区划数据来自旧系统,迁移时守了三条纪律:

  1. 先对齐字段口径,再导数据。父级关系、编码、层级、排序、经纬度五个字段的语义必须逐条确认,否则导进去之后所有按省聚合的报表都会偏;
  2. 可重复执行的迁移脚本。导入按编码 upsert,跑第二遍不会产生重复行,也不会覆盖人工修订过的经纬度;
  3. 导入后立刻做对账:省/市/区县各级条数与源库比对,抽查若干条路径与父级关系,输出可核对的结果再收工。

区域维护:给运营一个入口

区划数据一旦要改,不能每次都找开发执行 SQL。所以后台提供「系统管理 → 区域维护」:

  • 列表按树展开,支持按名称/编码搜索;
  • 新增、编辑、停用;编辑时父级与层级联动校验,防止出现"孤儿节点";
  • 新增与编辑用右侧抽屉而不是居中弹窗——区划字段多,抽屉能容纳更长表单,也不会遮住背后的树。

这类"字典维护"页面的价值常被低估:它把一次开发工作量换成了运营自助,长期成本差异很大。

地图选点:坐标要能落库

门店与供应商都要填地址,纯文本地址没法算配送距离。于是接入了地图选点:搜索地址 → 地图定位 → 回填经纬度。

工程上注意四点:

  • 密钥走配置。地图服务密钥存在「云服务配置」里,与短信、AI 能力并列,不入代码库;
  • 经纬度精度。用定点小数存储(保留 6 位),不用浮点,避免边界判断出现 1 米级抖动;
  • 选点是可选的。没有坐标时业务仍能跑(按区划匹配运费),有坐标时才启用距离计算,避免把地图服务变成下单链路的硬依赖;
  • 逆地理在服务端兜底。前端选点失败时允许手填地址,服务端在保存时尝试补全坐标,缺坐标只记录不阻断。

为什么不用第三方区划接口

有现成的区划 API,为什么还要自己存一份?三个原因:私有化部署环境可能没有外网;区划数据变化不频繁,本地化后查询零延迟;配送费规则需要与区划编码强绑定,外部接口的编码口径未必一致。

区划是典型的"低频但高耦合"数据:改动少,但一旦口径错,运费、报表、配送范围会同时出问题。把它当地基而不是当字典,后面省下的排查时间远超投入。

本文属于「开发文档」系列,记录鲜花交易系统(PHP + ThinkPHP 8 + MySQL 8)的实际研发进展。想了解功能清单与报价,可前往系统报价或联系我们。