ks-app-employment-service/docs/企业地址选择功能说明.md

# 企业地址选择功能说明

## 功能概述

在企业信息补全页面（company-info.vue）中，点击"企业注册地点"字段的箭头时，会弹出一个五级联动选择器，用户可以选择省市区县街道社区的完整地址。

## 实现的功能

### 1. 五级联动选择
- **省级选择**：选择省/直辖市/自治区
- **市级选择**：根据选择的省，显示对应的市/地区
- **区县选择**：根据选择的市，显示对应的区/县
- **街道选择**：根据选择的区县，显示对应的街道/乡镇
- **社区选择**：根据选择的街道，显示对应的社区/居委会

### 2. 联动逻辑
- 当选择省级时，自动更新并重置市级及以下选项
- 当选择市级时，自动更新并重置区县及以下选项
- 当选择区县时，自动更新并重置街道及以下选项
- 当选择街道时，自动更新社区选项
- 所有联动过程均实时响应，无需额外操作

### 3. 地址格式
- 选择完成后，地址格式为：`省/市/区/街道/社区`
- 示例：`新疆维吾尔自治区/喀什地区/喀什市/学府街道/学府社区居委会`
- 地址各级信息都会保存，包括代码和名称

### 4. 数据存储
- 保存完整的地址字符串（`registeredAddress`）
- 保存各级行政区划代码和名称：
  - 省：`provinceCode`、`provinceName`
  - 市：`cityCode`、`cityName`
  - 区县：`districtCode`、`districtName`
  - 街道：`streetCode`、`streetName`
  - 社区：`communityCode`、`communityName`

## 技术实现

### 组件架构
- **组件名称**：`area-cascade-picker`
- **组件位置**：`components/area-cascade-picker/area-cascade-picker.vue`
- **依赖组件**：`uni-popup`（uni-app官方弹窗组件）

### 核心技术
- **picker-view**：uni-app的多列选择器组件
- **五级联动**：通过监听选择变化，动态更新下级选项
- **树形数据结构**：地区数据采用嵌套的树形结构，每级都有`children`属性

### 数据格式
```javascript
{
    code: '650000',           // 行政区划代码
    name: '新疆维吾尔自治区',  // 名称
    children: [               // 下级行政区
        {
            code: '653100',
            name: '喀什地区',
            children: [...]
        }
    ]
}
```

### 数据流程

1. **打开地址选择器**
   ```javascript
   // company-info.vue
   const selectLocation = () => {
       areaPicker.value?.open({
           title: '选择企业注册地点',
           maskClick: true,
           success: (addressData) => {
               // 处理选择结果
               formData.registeredAddress = addressData.address
               // 保存各级信息
               formData.provinceCode = addressData.province?.code
               formData.provinceName = addressData.province?.name
               // ... 其他字段
           }
       })
   }
   ```

2. **选择地址过程**
   ```javascript
   // area-cascade-picker.vue
   bindChange(e) {
       // 检测哪一级发生变化
       // 更新对应级别及其下级的选项列表
       // 触发change回调（可选）
   }
   ```

3. **确认选择**
   ```javascript
   // area-cascade-picker.vue
   confirm() {
       const addressData = {
           address: '新疆维吾尔自治区/喀什地区/喀什市/学府街道/学府社区居委会',
           province: { code: '650000', name: '新疆维吾尔自治区' },
           city: { code: '653100', name: '喀什地区' },
           district: { code: '653101', name: '喀什市' },
           street: { code: '65310101', name: '学府街道' },
           community: { code: '6531010101', name: '学府社区居委会' }
       }
       // 调用success回调
       callback(addressData)
   }
   ```

## 文件结构

```
components/
  └── area-cascade-picker/
      └── area-cascade-picker.vue         # 五级联动地址选择组件
pages/complete-info/
  └── company-info.vue                    # 企业信息补全页面
```

## 数据字段

在 `company-info.vue` 的 `formData` 中的地址相关字段：

- `registeredAddress`: string - 完整地址（格式：省/市/区/街道/社区）
- `registeredAddressName`: string - 地址名称
- `provinceCode`: string - 省级行政区划代码
- `provinceName`: string - 省级名称
- `cityCode`: string - 市级行政区划代码
- `cityName`: string - 市级名称
- `districtCode`: string - 区县行政区划代码
- `districtName`: string - 区县名称
- `streetCode`: string - 街道行政区划代码
- `streetName`: string - 街道名称
- `communityCode`: string - 社区行政区划代码
- `communityName`: string - 社区名称

## 使用方法

### 用户操作流程
1. 在企业信息页面，点击"企业注册地点"右侧的箭头图标
2. 弹出五级联动地址选择器
3. 依次选择：
   - 第一列：选择省/直辖市/自治区
   - 第二列：选择市/地区（根据第一列自动更新）
   - 第三列：选择区/县（根据第二列自动更新）
   - 第四列：选择街道/乡镇（根据第三列自动更新）
   - 第五列：选择社区/居委会（根据第四列自动更新）
4. 确认选择无误后，点击右上角"确认"按钮
5. 选择器关闭，地址自动填充到表单中

### 界面说明
- **顶部标题栏**：
  - 左侧"取消"按钮：关闭选择器，不保存
  - 中间标题：显示"选择企业注册地点"
  - 右侧"确认"按钮：确认选择并保存
- **五列选择器**：
  - 每列显示当前级别的所有选项
  - 可上下滑动选择
  - 选中项高亮显示
  - 各列之间自动联动

## 注意事项

1. **数据来源**：
   - 当前使用本地模拟数据，包含主要城市的五级地址
   - 生产环境建议接入后端API，提供完整的全国地址数据
   - 后端API接口：`/app/common/area/cascade`（需要实现）

2. **数据格式要求**：
   - 必须是树形结构，每级通过`children`属性嵌套
   - 每个节点必须包含`code`（行政区划代码）和`name`（名称）
   - 最深五级：省 → 市 → 区县 → 街道 → 社区

3. **性能考虑**：
   - 地址数据量大时，建议使用懒加载方式
   - 可以先加载省市区，街道和社区按需加载
   - 考虑使用缓存机制，避免重复加载

4. **兼容性**：
   - 支持H5、微信小程序等多端
   - 使用uni-app原生组件，兼容性好

## 后续优化建议

1. **数据优化**：
   - 接入后端API，提供完整的全国地址数据
   - 实现地址数据的懒加载
   - 添加地址数据缓存机制

2. **功能增强**：
   - 支持默认值回显（编辑时显示已选地址）
   - 添加搜索功能，快速定位地址
   - 支持手动输入详细地址（如门牌号）
   - 增加常用地址保存功能

3. **用户体验**：
   - 优化滑动选择的流畅度
   - 添加选择预览功能
   - 支持快速选择最近使用的地址

4. **数据扩展**：
   - 支持国际地址选择
   - 添加邮政编码自动填充
   - 提供经纬度坐标（结合地理编码服务）