# 地址多格式帮助手册

## 1. 文档说明

本文档基于《地址多格式》需求文档整理，面向以下角色：

- 企业管理员
- 实施顾问
- 产品支持人员
- 业务配置人员

本文档用于说明地址多格式能力的功能定位、配置方法、前端展示规则、升级方式以及常见问题，帮助用户完成从国家/地区数据管理到动态地址字段落地的完整配置。

## 2. 功能概述

### 2.1 能力目标

地址多格式能力用于解决不同国家或地区地址结构差异较大的问题。系统可根据所选国家或地区，动态显示对应的地址字段、字段顺序、字段名称和拼接格式。

例如：

- 中国常见格式：省 / 市 / 区 / 详细地址 / 邮编
- 美国常见格式：Street / House Number / City / State / ZIP Code
- 日本常见格式：邮编 / 都道府县 / 市区町村 / 番地 / 号室
- 新加坡常见格式：Street / Building / Unit / Postal Code

### 2.2 适用场景

- 跨国企业录入客户地址、收货地址、账单地址
- 海外物流或清关场景，需要满足本地地址格式要求
- 海外支付场景，需要地址与支付机构校验规则一致
- 多区域业务系统，需要根据国家自动调整录入字段

### 2.3 核心能力

- 管理国家和地区主数据
- 配置一个国家或地区对应的一套或多套地址格式
- 在动态地址字段中按国家自动切换地址录入规则
- 保存时自动拼接格式化地址
- 支持将原有地区定位字段升级为动态地址字段

## 3. 功能结构

地址多格式能力主要由以下 3 部分组成：

### 3.1 国家和地区管理

用于维护国家或地区的基础信息，包括：

- 编码
- 名称
- 全称
- ISO 二字码
- ISO 三字码
- 数字编码
- 时区
- 区域格式
- 国际电话区号
- 状态

### 3.2 地址格式管理

用于配置不同国家或地区所使用的地址规则，包括：

- 基础信息
- 表单格式配置
- 文本拼接格式配置
- 默认格式设置

### 3.3 动态地址字段

用于业务对象中的实际录入和展示。动态地址字段会根据用户选择的国家或地区，动态加载相应的地址格式。

## 4. 国家和地区管理

### 4.1 功能定位

国家和地区管理将国家地区信息与行政区划信息拆分管理：

- `国家和地区`：管理国家或地区基础信息，可新建、编辑、启用、禁用
- `行政区划`：管理国家下的行政层级数据，只维护行政区划，不新建国家

### 4.2 可维护字段

一期支持以下字段：

| 字段 | 说明 | 是否必填 |
| --- | --- | --- |
| 编码 | 国家或地区编码 | 是 |
| 名称 | 国家或地区简称，用于界面显示 | 是 |
| 全称 | 国家或地区正式全称 | 否 |
| 二字码 | ISO 3166 二字码 | 否 |
| 三字码 | ISO 3166 三字码 | 否 |
| 数字编码 | ISO 3166 数字编码 | 否 |
| 时区 | 国家或地区默认时区 | 是 |
| 区域格式 | 国家或地区默认多区域格式 | 是 |
| 国际电话区号 | 国家或地区区号 | 是 |
| 状态 | 启用或禁用 | 否 |

说明：

- 国旗字段一期仅支持存储，不在管理页面中展示
- 英文简称、英文全称、语言、币种属于后续规划内容

### 4.3 列表页能力

国家和地区列表页支持：

- 按名称或编码搜索
- 对每一列进行筛选
- 新建国家和地区
- 编辑现有数据
- 启用或禁用
- 删除已禁用的数据

### 4.4 预置数据

系统按国际标准预置 249 个国家和地区数据，包括：

- 195 个主权国家
- 54 个地区

### 4.5 预置数据更新

如果系统中的预置国家地区数据与最新国际标准存在差异，可通过预置数据更新能力刷新到最新标准。

#### 典型调整场景

- 中国香港、中国澳门、中国台湾从原先的省级数据调整到国家和地区一级

#### 注意事项

- 使用了历史错误层级数据的企业可能需要灰度处理
- 历史统计结果可能因地区层级变化而受到影响
- 建议先确认哪些企业正在使用待调整的数据，再逐步刷新

## 5. 地址格式管理

### 5.1 功能定位

地址格式管理用于为国家或地区定义地址录入和展示规则。一个国家或地区可以关联多套地址格式，但同一国家或地区只能设置一套默认格式。

### 5.2 菜单位置

地址格式位于企业设置中的国家地区管理模块下。

### 5.3 列表页能力

地址格式列表页支持：

- 查看格式编码、名称、适用国家或地区、默认格式、状态、是否预置
- 搜索地址格式名称
- 对每一列筛选
- 新建地址格式
- 启用或禁用地址格式
- 删除已禁用地址格式

### 5.4 基础信息配置

创建地址格式时，需要配置以下内容：

| 字段 | 说明 | 是否必填 |
| --- | --- | --- |
| 编码 | 地址格式编码 | 是 |
| 名称 | 地址格式名称 | 是 |
| API Name | 保存时生成，可修改，保存后不可修改 | 是 |
| 国家和地区 | 关联适用的国家或地区，可多选 | 是 |
| 默认格式 | 是否设置为默认格式 | 否 |

### 5.5 默认格式规则

如果一个国家或地区配置了多套启用中的地址格式，则必须且只能有一套默认格式。

保存时若发生冲突，系统应提示该国家或地区已存在默认格式。

## 6. 表单格式配置

### 6.1 功能说明

表单格式用于控制动态地址字段在新建页和编辑页中的展示效果，包括：

- 字段是否显示
- 字段是否必填
- 字段显示顺序
- 是否从该字段开始换行
- 字段显示名称
- 字段长度是通栏还是多栏

### 6.2 可选字段范围

地址格式可使用的字段包括：

- 国家和地区
- 州/省
- 市
- 区/县
- 乡/镇
- 村
- 详细地址
- 邮编
- 定位
- 街道
- 门牌号
- 建筑名
- 房间号
- 楼层
- 邮箱号

说明：

- `村` 字段只有开通特殊灰度能力的企业才显示
- `经度`、`纬度`、`自定义地址1`、`自定义地址2` 为后续规划项

### 6.3 可配置项说明

| 配置项 | 说明 |
| --- | --- |
| 显示 | 是否在前端展示该字段 |
| 必填 | 展示后是否为必填 |
| 另起一行 | 从该字段开始换行展示 |
| 自定义显示名称 | 可为字段设置在不同国家下的别名 |
| 长度 | 可设置为通栏或多栏 |

### 6.4 显示名称示例

同一个字段在不同国家下可以展示为不同名称。例如：

- 中国：省
- 美国：州
- 日本：都道府县

### 6.5 预览能力

表单格式支持预览，可模拟：

- 1 列布局
- 2 列布局
- 3 列布局
- 4 列布局

预览时第一行固定展示：

- 国家/地区
- 地址格式

## 7. 文本拼接格式配置

### 7.1 功能说明

文本拼接格式用于将动态地址中的各个字段自动拼接为一个格式化地址文本，并存储到字段组中的 `格式化地址` 子字段中。

### 7.2 可配置内容

每个字段支持以下配置：

| 配置项 | 说明 |
| --- | --- |
| 是否包含 | 拼接时是否包含该字段 |
| 另起一行 | 当前字段后是否换行 |
| 使用属性替代 | 可将国家/地区替换为编码、名称、全称、二字码、三字码、数字编码等 |
| 前缀 | 在字段内容前增加固定文本 |
| 后缀 | 在字段内容后增加固定文本 |
| 空格分隔符 | 当前字段后是否增加空格 |

### 7.3 示例

#### 中国示例

拼接效果可为：

`浙江省 杭州市 西湖区`

`文三路 90 号`

`邮编 310000`

#### 美国示例

拼接效果可为：

`Amphitheatre Parkway`

`#1600`

`Mountain View, California 94043`

### 7.4 生效规则

- 文本拼接格式在保存时生效
- 编辑文本拼接规则后，仅对新数据生效
- 历史数据不会自动刷新，可通过函数或数据处理方式批量更新

## 8. 动态地址字段

### 8.1 字段定位

动态地址是一种新的字段类型，用于支持国际化地址多格式场景。

适用建议：

- `地区定位组件`：适用于仅需国家、省、市、区简单录入的场景
- `动态地址组件`：适用于需要按国家动态切换地址规则的场景

### 8.2 字段组结构

动态地址字段组中可包含以下子字段：

- 国家/地区
- 地址格式
- 州/省
- 市
- 区/县
- 乡/镇
- 村
- 详细地址
- 街道
- 邮编
- 门牌号
- 定位
- 建筑名
- 房间号
- 楼层
- 格式化地址

### 8.3 配置说明

每个子字段可单独配置：

- 字段名称
- API Name
- 安全等级
- 提示信息
- 默认值

补充说明：

- 格式化地址用于存储自动拼接结果
- 地址格式字段用于存储当前记录实际使用的地址格式
- 一期不支持在字段配置中禁用字段组内单个字段

### 8.4 字段数量限制

一个对象仅允许创建 1 个动态地址字段。

如果超出上限，系统应提示：

`该类型字段仅允许添加 1 个，当前已有 1 个（含禁用字段）`

## 9. 新建和编辑页展示规则

### 9.1 初始状态

新建或编辑页中，动态地址字段的第一行固定展示：

- 国家/地区
- 地址格式

格式化地址字段默认不在新建和编辑页展示，而是在保存时自动拼接。

### 9.2 国家为空时的展示逻辑

当国家/地区尚未选择时，系统按以下顺序确定默认展示格式：

1. 优先按当前登录人的个人多区域设置匹配地址格式
2. 如果个人设置为空，则按企业默认区域匹配
3. 如果仍未匹配到，则回退到国际标准地址规则

### 9.3 选择国家后的展示逻辑

当用户选择某个国家或地区后：

1. 系统匹配该国家下已启用的地址格式
2. 如果存在多套格式，默认选中其中的默认格式
3. 用户也可以切换为其他已启用格式
4. 页面按选定格式动态刷新字段顺序、字段名称、必填状态和换行方式

### 9.4 布局列数适配

字段展示会结合页面布局列数与地址格式规则共同决定：

- 布局中设置为几列，前端按该列数自动排布
- 如果地址格式中某字段设置为“另起一行”，则从该字段开始换行
- 如果字段设置为“通栏”，则独占整行

### 9.5 定位回填

定位回填不仅支持国家、省、市、区、乡镇等选项型字段，还应支持邮编字段回填。

### 9.6 无可用地址格式时

若所选国家或地区下没有可用的地址格式，系统应在地址格式字段下方显示强提示：

`当前国家或地区没有可用的地址格式，请联系管理员增加地址格式后再试`

## 10. 详情页和列表页展示规则

### 10.1 详情页

#### 有值时

- 按当前记录所选国家或地区对应的地址格式展示
- 使用该地址格式中定义的字段名称
- 同一字段在不同国家下显示名称可能不同

#### 无值时

- 按个人区域设置或企业默认区域对应的地址格式展示
- 个人区域优先于企业设置

### 10.2 列表页

- 列表页中动态地址通常按一个字段展示
- 展示内容可使用格式化地址或按存储值显示
- 组件内部字段的显示和筛选能力由字段开放情况决定

## 11. 按钮入参规则

### 11.1 配置页展示规则

在按钮配置页面中，动态地址字段以字段组形式展示：

- 默认显示字段组名称
- 不直接展示组内字段供单独选择
- 鼠标悬停时可查看字段组和组内字段清单

### 11.2 必填规则

- 仅支持按字段组设置是否必填
- 不支持在按钮入参中单独设置组内某个字段为必填

### 11.3 运行态规则

前端点击按钮后：

- 按字段组展示动态地址
- 在弹框中以一列方式展示组内字段
- 用户填写后，系统自动按顺序拼接并显示

## 12. 主从同时新建页规则

动态地址字段在主从同时新建页中支持两种展示方式：

### 12.1 列表布局

- 表头仅展示动态地址这一个字段
- 点击输入区域后，弹层中展开字段组
- 弹层中字段默认一列展示
- 确认后自动将已有值拼接回列表展示区

### 12.2 平铺布局

- 与主对象逻辑一致
- 字段组内所有字段直接平铺展示

## 13. 预置字段升级为动态地址

### 13.1 适用范围

以下字段支持升级：

- 预置对象上的预置地区定位字段
- 自定义地区定位字段

### 13.2 升级入口

在字段编辑页增加 `升级为动态地址` 开关。

### 13.3 升级前置校验

点击升级前，系统需先校验以下内容：

- 是否有按钮将当前字段作为输入内容字段
- 是否有布局规则将当前字段作为控制字段

若存在上述依赖，不允许升级，并提示用户先处理相关配置。

### 13.4 升级确认提示

系统需提示：

- 开启后默认将此字段刷为动态地址类型字段
- 可根据所选国家/地区动态显示地址相关字段
- 此操作不能撤回，请谨慎操作

### 13.5 升级后的保留项

升级后保留以下配置不变：

- 字段名称
- 默认值
- 提示信息
- 历史字段值

### 13.6 升级后效果

- 原字段转为动态地址字段
- 页面刷新为动态地址字段配置页面
- 历史上基于该字段配置的插件、UI 事件、布局规则、验证规则等仍应正常生效

## 14. 相关影响点

### 14.1 字段配置

地址格式控制字段显示时，优先级为：

1. 字段配置
2. 布局配置
3. 地址格式配置

### 14.2 布局排序

如果布局中对字段组内字段做了排序，则优先按布局排序展示，再结合地址格式规则。

### 14.3 布局规则和 UI 事件

- 动态地址中的单个字段可作为触发条件
- 字段显隐、只读、必填等规则应正常执行

### 14.4 按钮

- 动态地址字段组可作为按钮入参
- 组内单个字段可用于按钮条件判断

### 14.5 导入导出

- 动态地址字段支持导入导出
- 一期导入时暂不校验地址格式中的动态显隐和必填逻辑

### 14.6 Open API 与函数创建数据

- 一期不校验地址格式规则
- 如通过接口或函数创建数据，仍需业务侧自行保证数据完整性

## 15. 推荐配置流程

建议管理员按以下顺序完成配置：

### 步骤 1：确认国家和地区数据

- 检查目标国家或地区是否已存在
- 若不存在，先新增国家或地区
- 若已有预置数据不符合业务要求，可评估是否刷新预置数据

### 步骤 2：维护行政区划

- 按业务需要维护州、省、市、区等行政区划数据
- 确保地址格式依赖的行政级别已具备可选值

### 步骤 3：新建地址格式

- 维护基础信息
- 选择适用国家或地区
- 设置是否为默认格式

### 步骤 4：配置表单格式

- 确定需要显示哪些字段
- 为字段设置别名
- 设置必填项和换行逻辑
- 根据页面布局设置通栏或多栏

### 步骤 5：配置文本拼接规则

- 确定格式化地址是否需要换行
- 设置字段前后缀
- 确认是否使用编码、名称等属性替代原值

### 步骤 6：在对象中创建或升级动态地址字段

- 新建动态地址字段
- 或将已有地区定位字段升级为动态地址字段

### 步骤 7：验证前端效果

- 检查不同国家下字段顺序是否正确
- 检查字段别名是否正确
- 检查必填逻辑是否正确
- 检查格式化地址拼接结果是否符合预期

## 16. 常见问题

### 16.1 为什么选择了国家，但字段顺序没有变化？

可能原因：

- 当前国家没有启用中的地址格式
- 当前记录未命中默认格式
- 布局配置中对字段做了强排序
- 使用的不是动态地址字段，而是旧的地区定位字段

### 16.2 为什么某个字段在地址格式里配置了，但页面没有显示？

可能原因：

- 字段在字段配置中未开启
- 字段在布局中被隐藏
- 企业未开通相关灰度能力，例如 `村` 字段

### 16.3 编辑地址格式后，历史数据为什么没有变化？

因为地址格式修改默认只对新数据生效。历史记录不会自动重刷，只有再次编辑该条数据时，才会按新规则展示。

### 16.4 一个国家为什么可以配置多套地址格式？

因为同一国家可能对应不同业务场景。例如：

- 账单地址
- 物流地址
- 法务地址

系统允许一个国家有多套格式，但只能有一个默认格式。

### 16.5 升级为动态地址后还能退回吗？

不能。该操作是不可撤回的，建议升级前先确认按钮配置、布局规则和下游使用情况。

### 16.6 为什么接口导入的数据没有触发地址格式校验？

一期设计中，Open API 和函数创建数据暂不校验地址格式，因此接口侧需自行保证数据有效性。

## 17. 使用建议

- 面向纯国内业务时，优先使用原地区定位组件，降低配置复杂度
- 面向国际业务时，优先使用动态地址组件，避免人工适配不同国家格式
- 同一国家如果存在多个业务场景，建议拆分多套地址格式并明确默认规则
- 在正式上线前，建议至少对中国、美国、日本、新加坡等代表性国家做完整验证
- 如果涉及历史字段升级，建议先在测试环境验证按钮、布局规则、导入导出和接口兼容性

## 18. 附录：建议验证清单

上线前建议至少检查以下项目：

- 国家和地区数据是否完整
- 行政区划层级是否正确
- 每个重点国家是否至少配置一套启用格式
- 多套格式国家是否仅有一个默认格式
- 新建页字段顺序是否正确
- 字段显示名称是否符合当地习惯
- 必填校验是否正确
- 格式化地址拼接是否正确
- 详情页展示是否正确
- 按钮入参弹层展示是否正确
- 历史字段升级后的规则是否兼容
- 导入导出和接口调用是否满足当前业务要求