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. 字段设计

ALTER TABLE visits ADD COLUMN vehicle_images JSON NULL COMMENT '货车图片id数组';

模型更新

Visit模型更新

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

// 类型转换
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文档

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
• 参数:

  {
      "action": "upload_vehicle",
      "vehicle_images": [123, 456, 789]
  }
  

Swagger文档更新

@OA\Property(property="vehicle_images", type="array", description="货车图片ID数组（上传货车图片时必填）", @OA\Items(type="integer"))

多语言支持

中文翻译 (lang/zh-CN/gate.php)

'invalid_vehicle_images' => '货车图片ID无效',

英文翻译 (lang/en/gate.php)

'invalid_vehicle_images' => 'Invalid vehicle image IDs',

使用方式

1. 上传货车图片

// 通过API上传
POST /api/gate/visits/123/update
{
    "action": "upload_vehicle",
    "vehicle_images": [123, 456, 789]
}

2. 获取货车图片

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

3. API返回数据格式

{
    "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. 多语言: 测试中英文错误提示

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