# 收货地址省市区功能实现

## 概述
为处方业务订单编辑表单添加省/市/区选择器，将地址信息结构化存储。

## 数据库变更

### 新增字段
在 `zyt_tcm_prescription_order` 表中添加三个字段：

```sql
ALTER TABLE `zyt_tcm_prescription_order`
ADD COLUMN `shipping_province` varchar(50) NOT NULL DEFAULT '' COMMENT '收货省份' AFTER `recipient_phone`,
ADD COLUMN `shipping_city` varchar(50) NOT NULL DEFAULT '' COMMENT '收货城市' AFTER `shipping_province`,
ADD COLUMN `shipping_district` varchar(50) NOT NULL DEFAULT '' COMMENT '收货区县' AFTER `shipping_city`;
```

**执行方式：**
```bash
mysql -u用户名 -p数据库名 < add_shipping_region_fields.sql
```

## 后端变更

### 文件：`server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php`

在 `edit()` 方法中添加省市区字段处理：

```php
// 处理省市区字段
if (isset($params['shipping_province'])) {
    $order->shipping_province = (string) $params['shipping_province'];
}
if (isset($params['shipping_city'])) {
    $order->shipping_city = (string) $params['shipping_city'];
}
if (isset($params['shipping_district'])) {
    $order->shipping_district = (string) $params['shipping_district'];
}
```

## 前端变更

### 文件：`admin/src/views/consumer/prescription/order_list.vue`

#### 1. 数据结构
在 `editForm` 中添加 `region` 字段：
```typescript
const editForm = reactive({
    // ... 其他字段
    region: [] as string[],  // 新增
    shipping_address: '',
    // ...
})
```

#### 2. UI 组件
在收货手机下方添加省市区选择器：
```vue
<el-form-item label="省/市/区" prop="region">
    <el-cascader
        v-model="editForm.region"
        :options="regionOptions"
        placeholder="请选择省/市/区"
        clearable
        class="w-full"
    />
</el-form-item>
```

#### 3. 数据提交
在 `submitEdit()` 中将 region 数组拆分为三个字段：
```typescript
if (editForm.region && editForm.region.length > 0) {
    payload.shipping_province = editForm.region[0] || ''
    payload.shipping_city = editForm.region[1] || ''
    payload.shipping_district = editForm.region[2] || ''
} else {
    payload.shipping_province = ''
    payload.shipping_city = ''
    payload.shipping_district = ''
}
```

#### 4. 数据加载
在 `openEdit()` 中从后端数据填充 region：
```typescript
const province = d.shipping_province || ''
const city = d.shipping_city || ''
const district = d.shipping_district || ''
if (province || city || district) {
    editForm.region = [province, city, district].filter(v => v !== '')
} else {
    editForm.region = []
}
```

## 省市区数据

当前使用简化的示例数据，包含：
- 四川省（成都市、绵阳市）
- 北京市
- 上海市
- 广东省（广州市、深圳市）

### 生产环境建议

**方案 1：使用完整数据集**
- 集成中国行政区划完整数据（约 3000+ 区县）
- 推荐数据源：
  - [element-china-area-data](https://www.npmjs.com/package/element-china-area-data)
  - [china-division](https://github.com/modood/Administrative-divisions-of-China)

**方案 2：使用 API 服务**
- 调用第三方地址 API（如高德地图、腾讯地图）
- 优点：数据实时更新，减少前端体积
- 缺点：依赖网络，需要 API Key

## 使用流程

1. **执行数据库迁移**
   ```bash
   mysql -u用户名 -p数据库名 < add_shipping_region_fields.sql
   ```

2. **重启后端服务**（如需要）

3. **测试功能**
   - 打开处方业务订单列表
   - 点击"编辑"按钮
   - 选择省/市/区
   - 填写详细地址
   - 保存并验证数据已正确存储

## 数据结构

### 前端存储格式
```typescript
region: ['四川省', '成都市', '武侯区']
```

### 后端存储格式
```php
[
    'shipping_province' => '四川省',
    'shipping_city' => '成都市',
    'shipping_district' => '武侯区',
    'shipping_address' => '天府大道中段123号'  // 详细地址
]
```

### 数据库存储
```
shipping_province: 四川省
shipping_city: 成都市
shipping_district: 武侯区
shipping_address: 天府大道中段123号
```

## 注意事项

1. **向后兼容**：旧数据的省市区字段为空字符串，不影响现有功能
2. **可选字段**：省市区选择器可清空，允许用户只填写详细地址
3. **数据验证**：前端使用 cascader 确保选择的层级关系正确
4. **字段长度**：省市区字段各限制 50 字符

## 相关文件

- `add_shipping_region_fields.sql` - 数据库迁移文件
- `admin/src/views/consumer/prescription/order_list.vue` - 前端订单列表页面
- `server/app/adminapi/logic/tcm/PrescriptionOrderLogic.php` - 后端业务逻辑

## 后续优化建议

1. 在订单详情页面也显示省市区信息
2. 在订单列表的收货人列中显示省市信息
3. 添加按省市区筛选订单的功能
4. 集成完整的中国行政区划数据
5. 考虑添加邮政编码字段