订单

2026-04-15 16:31:25 +08:00
parent 906684c1ed
commit 3d9c5dd8f5
47 changed files with 7963 additions and 10 deletions
@@ -0,0 +1,179 @@
+# 收货地址省市区功能实现
+
+## 概述
+为处方业务订单编辑表单添加省/市/区选择器，将地址信息结构化存储。
+
+## 数据库变更
+
+### 新增字段
+在 `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. 考虑添加邮政编码字段