crm-backend-matt/.scratch/clue-module/issues/02-行政区划数据源调研.md

省/市/区行政区划数据源与"负责市场"存储形态

Type: research Status: resolved

Question

公海池归属含"省份 + 负责市场（多城市/区，可多选）"，线索也带省份/城市字段。需先摸清行政区划数据在本系统的既有形态（只读调查）：

1. 仓库里是否已有行政区划（省/市/区）数据源？表？字典分组（crm-dict）？三方？
2. 前端下拉"选择省份→联动城市→区县"的数据当前从哪个接口取？
3. 若走 crm-dict：省/市/区是几个字典分组还是一个带层级的分组？crm-dict 是否支持层级？
4. 若无既存：给出候选方案，供决策 ticket 参考，不在此拍板。

产出：结论落在本 ticket ## Answer，供"公海池归属与省市区建模"ticket 消费。

Answer

仓库内只读扫描结论：

1. 无行政区划（省/市/区）数据源。既无区划表，crm-dict 也无省市区分组。
2. 前端联动下拉当前无对应后端接口（模块未建）。
3. crm-dict 是两级平铺、不支持层级（DictGroup 无 parent/level/children 字段，CONTEXT 明确"两级平铺"）。行政区划有天然三级层级（省→市→区），平铺字典表达不了。
4. crm-dict 现有种子分组仅三个：lead_source(客户来源，6 项粗分类)、customer_status、industry(8 项)。原型里"渠道=展会/知乎/京东…"远比 lead_source 细，渠道字典是复用还是扩充留给 ticket 06。

候选方案（不在此拍板，供 ticket 04 决策）：

• (A) 新建行政区划表（sys_region，含 parent/level，或采用 GB/T 2260 标准行政区划码）——推荐，层级天然、可复用于线索/客户/商机。
• (B) crm-dict 破例支持一个层级分组——违背"两级平铺"约定，不推荐。
• (C) 引入三方行政区划数据静态导入。

存储形态待定：公海池"负责市场"多城市/区多选 → 存区划码列表（关联表 or JSON）；线索省份/城市 → 存区划码。均依赖 (A/B/C) 的选择。

对地图的影响：ticket 04（公海池归属）需先吃掉这个方案选择；已在 04 的 Blocked by 中列入 02。区划方案本身若需独立决策，可能从 04 里分裂出一张子 ticket。

Amendment（08 追加）—— sys_region 表结构定稿

原选定 1a（新建 sys_region）但未定表结构。因 08 地区字段/06 省市字段均改为存国标 code + LIKE 前缀祖先查询，本次一并定稿：

sys_region
├─ id         bigint PK
├─ code       varchar(12)  UNIQUE  NOT NULL   -- 国标 GB/T 2260 行政区划代码, 6 位或 12 位
├─ name       varchar(50)  NOT NULL
├─ parent_id  bigint                          -- 上级 region_id (可选, code 前缀已能推层级)
├─ level      tinyint      NOT NULL           -- 1=省 2=市 3=区
└─ INDEX (parent_id)

关键约束：

• code = 国标 GB/T 2260，层级严格前缀嵌套（省=6位，市=前4位=省+2位数字，区=前4位=市+2位数字）
• UNIQUE(code) = B-Tree 索引，天然支持前缀 LIKE 祖先查询
• 不需要 ancestors 字段 —— 国标 code 前缀已完全表达层级

祖先查询模式：

• 查广州市及下辖所有区：WHERE region_code LIKE '4401%'（命中 440100 广州市本级 + 4401xx 所有区）
• 查广东省及下辖所有市区：WHERE region_code LIKE '44%'

数据源：民政部/国家统计局官方 CSV，一次性导入初始化。

下游一致性：

• crm-lead lead.province_code / lead.city_code 存 code（见 06 Amendment）
• crm-opportunity 商机 region_code 存 code（见 08 Answer）
• 存 code 不存 id，与 crm-dict 存 code 的既有约定对齐