zd_product_document/40-平台与架构/基础平台/功能模块/12-城市管理.md

5.12 城市管理

本文档从《基础平台产品设计》第 5 章拆分而来，用于独立描述基础平台功能模块的业务需求、规则和验收标准。

上级文档：基础平台产品设计

5.12.1 功能说明

城市管理用于维护基础平台中的国家与行政区划主数据，为门店、组织、供应链、营销、结算、报表、门店选址规划系统等业务场景提供统一的地区引用来源。

城市管理首版解决以下问题：

• 管理国家主数据。
• 管理省份、城市、区县、街道四级行政层级。
• 维护内部城市编码、国家码和外部系统城市编码映射。
• 支持按国家浏览城市树。
• 支持按名称、编码、层级、状态查询城市节点。
• 支持新增、编辑、启用、停用和删除城市节点。
• 为后续业务系统引用国家与城市主数据提供稳定 ID、编码、层级和经纬度字段。

城市管理不负责：

• 门店、组织、人员等业务对象的城市归属维护。
• 第三方地图或地理编码 API 调用。
• 真实行政区划数据自动同步。
• 跨系统城市数据分发任务编排。
• 业务系统本地缓存刷新策略。
• 行政区划版本更新和批量导入，首版仅预留后续扩展。

5.12.2 功能范围

• 国家主数据维护
• 城市主数据维护
• 父子行政层级维护
• 城市编码维护
• 外部城市编码维护
• 经纬度基础信息维护
• 排序维护
• 启用 / 停用
• 删除前子级校验
• 删除前业务引用约束校验预留
• 城市树懒加载查询
• 城市分页查询
• 城市详情查询

5.12.3 管理对象

城市管理包含两个核心对象：国家和城市节点。

国家不作为城市树节点，国家通过页面顶部国家上下文进行选择。城市树只展示当前国家下的省、市、区县、街道四级节点。

城市节点层级固定为：

层级值	语义	说明
1	省份	城市树根节点
2	城市	省份下级
3	区县	城市下级
4	街道	区县下级，首版不允许继续新增子级

5.12.4 字段要求

5.12.4.1 国家字段

国家信息至少包括：

字段	说明	是否必填
国家名称	国家正式名称，例如中国	是
国家简称	国家简称	否
国家码	电话国家码，例如中国为 86	是
ISO Alpha-2	ISO 3166-1 alpha-2，例如 CN	否
ISO Alpha-3	ISO 3166-1 alpha-3，例如 CHN	否
排序	国家列表展示顺序	是
启用状态	启用、停用	是
创建时间	国家档案创建时间	是
更新时间	国家档案最近更新时间	是

5.12.4.2 城市节点字段

城市节点信息至少包括：

字段	说明	是否必填
父级城市	当前节点的父级城市；省份为空	条件必填
城市名称	省、市、区县、街道名称	是
城市简称	城市简称	否
国家码	当前城市所属国家码	是
城市编码	行政业务编码，固定 8 位	是
外部编码 1	外部系统城市编码 1	否
外部编码 2	外部系统城市编码 2	否
层级	省份、城市、区县、街道	是
经度	城市经度	否
纬度	城市纬度	否
排序	同级节点展示顺序	是
启用状态	启用、停用	是
创建时间	城市节点创建时间	是
更新时间	城市节点最近更新时间	是

5.12.5 编码规则

5.12.5.1 国家码

国家码用于表达国家或地区电话国家码，当前中国默认为 86。

业务规则：

• 国家码必填。
• 国家码只允许数字。
• 国家码全局唯一。
• 当前只维护中国城市主数据时，系统默认初始化中国 86。
• 已存在城市节点的国家，首版不允许修改国家码。

5.12.5.2 城市编码

城市编码用于表达行政业务编码，不拼接国家码，固定为 8 位数字。

编码规则：

节点类型	编码规则	示例
省份	省份 2 位 + 6 位补零	43000000
城市	省份 2 位 + 城市 2 位 + 4 位补零	43010000
区县	省份 2 位 + 城市 2 位 + 区县 2 位 + 2 位补零	43010200
街道	省份 2 位 + 城市 2 位 + 区县 2 位 + 街道 2 位	43010201

业务规则：

• 城市编码只允许数字，且固定 8 位。
• 城市编码不拼接国家码。
• 如接口或外部系统需要完整跨国编码，可由国家码 + 城市编码派生。
• 省直辖县级市等特殊行政编码需要保留有效行政码，避免压缩后丢失唯一性。
• 外部编码 1、外部编码 2 只用于外部系统城市编码映射，不参与行政层级判断。

5.12.6 业务规则

5.12.6.1 国家规则

• 国家管理首版不新增独立菜单，入口固定放在城市管理页顶部国家上下文右侧。
• 国家码必填且全局唯一。
• ISO Alpha-2、ISO Alpha-3 可为空，非空时必须全局唯一。
• 禁用国家后，不影响历史城市数据展示。
• 禁用国家后，不允许在该国家下新增城市节点。
• 删除国家前，必须校验该国家下是否存在未删除城市节点。
• 若国家下存在未删除城市节点，禁止删除国家。

5.12.6.2 城市层级规则

• 城市树根节点直接展示省份，不展示国家节点。
• 省份节点父级城市为空，层级必须为省份。
• 非省份节点必须选择父级城市。
• 非省份节点层级必须等于父级层级加 1。
• 非省份节点国家码必须与父节点一致。
• 街道节点不允许继续新增子级。
• 编辑城市节点时，首版不允许修改层级。
• 如后续需要调整城市层级或父级，应单独设计“移动城市节点”能力。

5.12.6.3 启停与删除规则

• 停用城市节点后，历史数据仍可展示。
• 停用城市节点后，不允许在该节点下新增子级。
• 停用节点在城市树中弱化展示，但不隐藏。
• 删除城市节点必须二次确认。
• 删除城市节点前，必须校验是否存在未删除子节点。
• 如存在未删除子节点，禁止删除。
• 删除城市节点前预留业务引用检查；当门店、组织、供应链、结算等系统已引用该城市时，禁止删除。

5.12.6.4 查询规则

• 国家上下文决定当前城市树和城市列表的数据范围。
• 当前只维护中国城市主数据时，页面默认显示中国 86。
• 存在多个启用国家时，页面展示国家下拉筛选器。
• 查询关键字支持匹配城市名称、简称、国家码、城市编码、外部编码 1、外部编码 2。
• 层级按省份、城市、区县、街道精确筛选。
• 状态按启用、停用精确筛选。
• 查询区支持按 Enter 键触发查询。

5.12.7 界面设计

5.12.7.1 功能入口与访问权限

城市管理作为基础平台基础资料管理功能，建议放置在基础平台左侧菜单：

基础平台
└── 城市管理

页面访问规则：

• 平台超级管理员可维护国家和城市主数据。
• 平台实施人员可按授权范围维护国家和城市主数据。
• 客户管理员默认不维护城市主数据，只能在业务系统中引用城市。
• 普通业务用户不可访问城市管理页面。
• 无城市管理权限的用户不展示城市管理菜单。

5.12.7.2 页面结构

城市管理采用“国家管理入口 + 国家上下文 + 查询区 + 左树右表 + 抽屉表单”的结构。

┌──────────────────────────────────────────────────────────────────────────────┐
│ 国家上下文：国家 = 中国（86）                                  [国家管理]   │
├──────────────────────────────────────────────────────────────────────────────┤
│ 关键字：[            ]  层级：[全部 v]  状态：[全部 v]           [查询]      │
├──────────────────────────┬───────────────────────────────────────────────────┤
│ 城市树                   │ 城市列表                                          │
│ - 湖南省 43000000        │ 名称 简称 编码 外部编码 层级 经纬度 状态 排序 操作 │
│   - 长沙市 43010000      │ 长沙市 长沙 43010000 ... 城市 ... 启用 1 编辑      │
│     - 芙蓉区 43010200    │                                                   │
├──────────────────────────┴───────────────────────────────────────────────────┤
│ 抽屉：新增 / 编辑城市节点                                                     │
└──────────────────────────────────────────────────────────────────────────────┘

页面区域规则：

• 国家上下文固定在页面顶部。
• 国家管理入口放在国家上下文右侧。
• 查询区位于国家上下文下方。
• 主体区域左侧为城市树，右侧为城市列表。
• 抽屉从右侧打开，用于新增和编辑城市节点。
• 移动端或窄屏下，左侧树可改为顶部下拉树选择器，列表仍作为主工作区。

5.12.7.3 国家管理弹窗

国家管理用于维护国家主数据，首版采用列表 + 表单弹窗方式。

展示方式：

• 查询区域 + 国家列表。
• 新增 / 编辑国家采用表单弹窗。

查询条件：

查询项	控件类型	值来源 / 录入方式	说明
关键字	文本输入框	人工录入	匹配国家名称、简称、国家码、ISO2、ISO3
启用状态	下拉框	全部、启用、停用	默认全部
查询	按钮	用户点击	作为查询区域最后一个表单元素

列表字段：

字段	说明
国家名称	国家正式名称
国家简称	国家简称
国家码	电话国家码
ISO Alpha-2	ISO 2 位编码
ISO Alpha-3	ISO 3 位编码
启用状态	启用、停用
排序	展示顺序
操作	编辑、启用、停用、删除

表单字段：

字段	控件类型	值来源 / 录入方式	说明
国家名称	文本输入框	人工录入	必填
国家简称	文本输入框	人工录入	选填
国家码	文本输入框	人工录入	必填，全局唯一
ISO Alpha-2	文本输入框	人工录入	选填，非空唯一
ISO Alpha-3	文本输入框	人工录入	选填，非空唯一
启用状态	Radio	启用、停用	必填
排序	数字输入框	人工录入	默认 1

5.12.7.4 国家上下文

国家上下文用于展示和限定当前城市树所属国家。

展示规则：

• 当前只维护中国城市主数据时，显示只读文本：中国（86）。
• 存在多个启用国家时，展示国家下拉选择器。
• 切换国家后，左侧城市树和右侧列表整体刷新。
• 所有树查询、列表查询、新增、编辑请求都携带当前国家码。
• 新增省份时，表单自动带入当前国家码。
• 新增市、区县、街道时，表单继承父节点国家码。

5.12.7.5 查询区

查询区用于在当前国家范围内检索城市节点。

查询条件：

查询项	控件类型	值来源 / 录入方式	说明
关键字	文本输入框	人工录入	匹配名称、简称、国家码、城市编码、外部编码
层级	下拉框	全部、省份、城市、区县、街道	可为空
启用状态	下拉框	全部、启用、停用	默认全部
查询	按钮	用户点击	作为查询区域最后一个表单元素

页面规则：

• 查询区不提供重置按钮。
• 支持按 Enter 键触发查询。

5.12.7.6 城市树区

城市树用于展示当前国家下的城市层级结构。

展示方式：

• 树形结构。
• 懒加载直接子级。
• 树节点展示城市名称，辅助展示城市编码。

页面规则：

• 默认只加载当前国家下的省份节点。
• 默认按层级、排序、城市编码排序。
• 点击树节点后，右侧列表默认查询该节点的直接子级。
• 展开某个树节点时，只请求该节点直接子级。
• 停用节点弱化展示，但不从树中隐藏。
• 街道节点不展示展开控件。

5.12.7.7 城市列表区

城市列表用于维护当前筛选范围下的城市节点。

列表字段：

字段	说明
城市名称	城市节点名称
城市简称	城市简称
城市编码	8 位行政业务编码
国家码	所属国家码
外部编码 1	外部系统城市编码 1
外部编码 2	外部系统城市编码 2
层级	省份、城市、区县、街道
经度	城市经度
纬度	城市纬度
启用状态	启用、停用
排序	同级展示顺序
操作	新增子级、编辑、启用 / 停用、删除

页面规则：

• 默认每页 20 条。
• 支持切换每页条数。
• 空状态文案为：暂无城市数据。
• 删除必须二次确认。
• 街道节点不展示新增子级操作。

5.12.7.8 城市新增 / 编辑抽屉

城市新增 / 编辑抽屉用于维护单个城市节点。

展示方式：

• 右侧抽屉。
• 表单方式展示。
• 底部固定操作按钮：取消、保存。

表单字段：

字段	控件类型	值来源 / 录入方式	说明
父级城市	树形选择器 / 只读文本	当前城市树	新增子级时自动带入
层级	只读文本 / 下拉框	根据父级自动计算	编辑时只读
城市名称	文本输入框	人工录入	必填
城市简称	文本输入框	人工录入	选填
城市编码	文本输入框	人工录入	必填，8 位数字
国家码	只读文本	当前国家上下文或父节点	必填
外部编码 1	文本输入框	人工录入	选填
外部编码 2	文本输入框	人工录入	选填
经度	数字输入框	人工录入	选填
纬度	数字输入框	人工录入	选填
启用状态	Radio	启用、停用	必填
排序	数字输入框	人工录入	默认 1

表单规则：

• 从新增子级进入时，父级城市自动带入，层级自动等于父级层级加 1。
• 新增省份时，父级城市为空，层级只能为省份。
• 编辑时不允许随意修改层级。
• 状态使用 Radio。
• 排序默认值为 1。

5.12.8 字段校验

5.12.8.1 国家字段校验

字段	校验规则
国家名称	必填，长度 1-255
国家简称	可空，最大长度 64
国家码	必填，允许 1-3 位数字，全局唯一
ISO Alpha-2	可空，非空时必须为 2 位大写字母，且全局唯一
ISO Alpha-3	可空，非空时必须为 3 位大写字母，且全局唯一
排序	必填，必须大于等于 0
启用状态	必填，只允许启用或停用

5.12.8.2 城市字段校验

字段	校验规则
父级城市	省份可为空；非省份必填且必须是同国家下已存在父级城市
城市名称	必填，长度 1-255
城市简称	可空，最大长度 64
国家码	必填，允许 1-3 位数字
城市编码	固定 8 位数字
外部编码 1	可空，最大长度 64
外部编码 2	可空，最大长度 64
层级	必填，只允许省份、城市、区县、街道
排序	必填，必须大于等于 0
经度	可空，范围 -180 到 180，保留 6 位小数
纬度	可空，范围 -90 到 90，保留 6 位小数
启用状态	必填，只允许启用或停用

5.12.9 使用导航

5.12.9.1 维护国家

操作路径：

基础平台 > 城市管理 > 国家管理

操作步骤：

1. 进入城市管理页面。
2. 点击国家管理。
3. 查询国家列表。
4. 新增、编辑、启用、停用或删除国家。
5. 系统校验国家码唯一性和城市引用关系。
6. 系统保存国家信息并记录操作日志。

5.12.9.2 查询城市

操作路径：

基础平台 > 城市管理

操作步骤：

1. 进入城市管理页面。
2. 确认当前国家上下文。
3. 按关键字、层级、状态查询城市。
4. 在左侧城市树选择节点。
5. 在右侧列表查看该节点的直接子级或查询结果。

5.12.9.3 新增城市节点

操作路径：

基础平台 > 城市管理 > 城市列表 > 新增子级

操作步骤：

1. 进入城市管理页面。
2. 在城市树或城市列表中选择父级节点。
3. 点击新增子级。
4. 系统打开城市新增 / 编辑抽屉。
5. 系统自动带入父级城市、层级和国家码。
6. 填写城市名称、编码、外部编码、经纬度、状态和排序。
7. 保存城市节点。
8. 系统刷新城市树和城市列表，并记录操作日志。

5.12.9.4 编辑城市节点

操作路径：

基础平台 > 城市管理 > 城市列表 > 编辑

操作步骤：

1. 查询目标城市节点。
2. 点击编辑。
3. 系统打开城市新增 / 编辑抽屉。
4. 修改城市名称、简称、外部编码、经纬度、状态或排序。
5. 保存城市节点。
6. 系统刷新城市树和城市列表，并记录操作日志。

5.12.9.5 启用 / 停用城市节点

操作路径：

基础平台 > 城市管理 > 城市列表 > 启用 / 停用

操作步骤：

1. 查询目标城市节点。
2. 点击启用或停用。
3. 停用时，系统提示停用影响。
4. 确认操作。
5. 系统更新城市状态，并记录操作日志。

5.12.9.6 删除城市节点

操作路径：

基础平台 > 城市管理 > 城市列表 > 删除

操作步骤：

1. 查询目标城市节点。
2. 点击删除。
3. 系统二次确认删除操作。
4. 系统校验是否存在未删除子节点。
5. 系统预留校验是否存在业务引用。
6. 校验通过后删除城市节点，并记录操作日志。

5.12.10 验收标准

• 可维护国家主数据。
• 中国 86 可作为首版默认国家。
• 城市树根节点直接展示省份，不展示国家节点。
• 城市支持省份、城市、区县、街道四级层级。
• 城市树支持懒加载直接子级。
• 点击树节点后，右侧列表展示直接子级。
• 可按关键字、层级、状态查询城市节点。
• 可新增、编辑、启用、停用、删除城市节点。
• 街道节点不可新增子级。
• 停用节点在树中弱化展示但不隐藏。
• 删除国家时，如存在城市节点，则禁止删除。
• 删除城市节点时，如存在未删除子节点，则禁止删除。
• 城市编码必须为 8 位数字。
• 经度、纬度校验范围正确。
• 无权限用户不可见国家管理和城市管理相关按钮。
• 直接调用无权限接口时应被拒绝。
• 国家新增、编辑、启用、停用、删除，以及城市新增、编辑、启用、停用、删除均生成操作日志。