ss-visit/VEHICLE_IMAGES_IMPLEMENTATION.md

# 货车图片上传功能实现总结

## 实现内容

根据要求，已在拜访预约表（visits表）中增加了json字段来存储货车图片，并完善了相关的上传逻辑。

## 数据库变更

### 1. 新增字段
- **字段名**: `vehicle_images`
- **类型**: `json`
- **说明**: 存储货车图片的uploads表id数组
- **迁移文件**: `2025_09_09_112040_add_vehicle_images_to_visits_table.php`

### 2. 字段设计
```sql
ALTER TABLE visits ADD COLUMN vehicle_images JSON NULL COMMENT '货车图片id数组';
```

## 模型更新

### Visit模型更新
1. **类型转换**: 在`$casts`中添加了`'vehicle_images' => 'array'`
2. **关联关系**: 添加了`getVehicleImagesAttribute()`方法

```php
// 类型转换
protected $casts = [
    'vehicle_images' => 'array',
    // ... 其他字段
];

// 获取货车图片列表（多文件）
public function getVehicleImagesAttribute()
{
    if (!$this->vehicle_images) {
        return [];
    }
    return Upload::whereIn('id', $this->vehicle_images)->get();
}
```

## 控制器更新

### GateController更新
1. **添加Upload模型引用**
2. **完善upload_vehicle操作逻辑**
3. **更新Swagger文档**

```php
case 'upload_vehicle':
    // 上传货车图片
    if ($visit->type != Visit::TYPE_LOGISTICS_CAR) {
        return $this->error(__('gate.only_logistics_cars_can_upload_images'));
    }

    $vehicleImages = $request->input('vehicle_images', []);
    if (empty($vehicleImages)) {
        return $this->error(__('gate.vehicle_images_required'));
    }

    // 验证图片ID是否存在于uploads表中
    $existingImages = Upload::whereIn('id', $vehicleImages)->pluck('id')->toArray();
    if (count($existingImages) !== count($vehicleImages)) {
        return $this->error(__('gate.invalid_vehicle_images'));
    }

    // 存储货车图片ID数组到vehicle_images字段
    $visit->vehicle_images = $vehicleImages;
    $visit->save();

    // 记录日志
    $this->createVisitLog($visit, VisitLog::TYPE_ENTER, __('gate.upload_vehicle_images_log', ['count' => count($vehicleImages)]));

    break;
```

## API接口

### 上传货车图片接口
- **路径**: `POST /api/gate/visits/{id}/update`
- **参数**:
  ```json
  {
      "action": "upload_vehicle",
      "vehicle_images": [123, 456, 789]
  }
  ```

### Swagger文档更新
```php
@OA\Property(property="vehicle_images", type="array", description="货车图片ID数组（上传货车图片时必填）", @OA\Items(type="integer"))
```

## 多语言支持

### 中文翻译 (lang/zh-CN/gate.php)
```php
'invalid_vehicle_images' => '货车图片ID无效',
```

### 英文翻译 (lang/en/gate.php)
```php
'invalid_vehicle_images' => 'Invalid vehicle image IDs',
```

## 使用方式

### 1. 上传货车图片
```php
// 通过API上传
POST /api/gate/visits/123/update
{
    "action": "upload_vehicle",
    "vehicle_images": [123, 456, 789]
}
```

### 2. 获取货车图片
```php
// 获取拜访记录及货车图片
$visit = Visit::with('acceptAdminSign')->find(123);
$vehicleImages = $visit->vehicle_images; // 返回Upload模型集合
```

### 3. API返回数据格式
```json
{
    "id": 123,
    "name": "访客姓名",
    "type": 3,
    "vehicle_images": [
        {
            "id": 123,
            "original_name": "vehicle1.jpg",
            "url": "http://domain.com/uploads/vehicle1.jpg"
        },
        {
            "id": 456,
            "original_name": "vehicle2.jpg", 
            "url": "http://domain.com/uploads/vehicle2.jpg"
        }
    ]
}
```

## 验证逻辑

1. **类型验证**: 只有物流车辆（type=3）才能上传货车图片
2. **必填验证**: vehicle_images参数不能为空
3. **存在性验证**: 验证所有图片ID是否存在于uploads表中
4. **数据存储**: 将验证通过的图片ID数组存储到vehicle_images字段

## 日志记录

上传货车图片时会自动记录操作日志：
- **日志类型**: VisitLog::TYPE_ENTER
- **日志内容**: "上传货车图片：{图片数量}张"

## 注意事项

1. **文件存储**: 所有图片都存储在uploads表中，通过id关联
2. **权限控制**: 只有物流车辆类型的拜访才能上传货车图片
3. **数据验证**: 严格验证图片ID的有效性
4. **日志记录**: 所有操作都有完整的日志记录
5. **多语言**: 支持中英双语错误提示

## 测试建议

1. **正常上传**: 测试物流车辆上传多张货车图片
2. **权限验证**: 测试非物流车辆尝试上传图片
3. **数据验证**: 测试无效的图片ID
4. **空值处理**: 测试空的vehicle_images参数
5. **多语言**: 测试中英文错误提示

货车图片上传功能已完整实现，符合所有要求！