ss-visit/FILE_FIELDS_SUMMARY.md

文件字段修正总结

修正内容

根据要求，已对所有涉及文件上传的字段进行了修正，确保：

1. 多文件字段：设计成json类型，存储uploads表的id数组
2. 单文件字段：设计成int类型，直接存储uploads表的id
3. 模型关联：json类型通过getFilesAttribute方法自动关联uploads表，int类型直接通过belongsTo关联

修正的模型和字段

1. Visit模型 (visits表)

字段修正：

• accept_admin_sign (string → unsignedBigInteger) - 被访人签字图片id（单文件）
• file (json) - 附件id数组（多文件）

关联关系：

// 单文件关联
public function acceptAdminSign()
{
    return $this->belongsTo(Upload::class, 'accept_admin_sign');
}

// 多文件关联
public function getFilesAttribute()
{
    if (!$this->file) {
        return [];
    }
    return Upload::whereIn('id', $this->file)->get();
}

2. Study模型 (studies表)

字段：

• file (json) - 文件id数组（多文件）

关联关系：

// 多文件关联
public function getFilesAttribute()
{
    if (!$this->file) {
        return [];
    }
    return Upload::whereIn('id', $this->file)->get();
}

3. Blacklist模型 (blacklists表)

字段：

• file (json) - 附件id数组（多文件）

关联关系：

// 多文件关联
public function getFilesAttribute()
{
    if (!$this->file) {
        return [];
    }
    return Upload::whereIn('id', $this->file)->get();
}

控制器更新

1. VisitController

• 在show方法中添加了 acceptAdminSign 关联关系
• 确保返回数据时包含签字图片信息

2. GateController

• 在visits和visitDetail方法中添加了 acceptAdminSign 关联关系
• 确保门岗端也能获取到签字图片信息

数据库迁移

1. 字段类型修正

创建了迁移文件 2025_09_09_111215_fix_accept_admin_sign_field_type_in_visits_table.php：

• 将 accept_admin_sign 字段从 string 类型改为 unsignedBigInteger 类型
• 确保单文件字段使用正确的数据类型

使用方式

1. 单文件字段使用

// 获取签字图片
$visit = Visit::with('acceptAdminSign')->find(1);
$signImage = $visit->acceptAdminSign; // 返回Upload模型实例

// 设置签字图片
$visit->accept_admin_sign = 123; // 直接设置uploads表的id
$visit->save();

2. 多文件字段使用

// 获取附件文件列表
$visit = Visit::find(1);
$files = $visit->files; // 返回Upload模型集合

// 设置附件文件
$visit->file = [123, 456, 789]; // 设置uploads表的id数组
$visit->save();

3. API返回数据格式

{
    "id": 1,
    "name": "访客姓名",
    "accept_admin_sign": {
        "id": 123,
        "original_name": "signature.jpg",
        "url": "http://domain.com/uploads/signature.jpg"
    },
    "files": [
        {
            "id": 456,
            "original_name": "document1.pdf",
            "url": "http://domain.com/uploads/document1.pdf"
        },
        {
            "id": 789,
            "original_name": "document2.pdf",
            "url": "http://domain.com/uploads/document2.pdf"
        }
    ]
}

验证结果

1. ✅ 字段类型正确：单文件使用int类型，多文件使用json类型
2. ✅ 关联关系完整：所有文件字段都有对应的关联关系
3. ✅ 控制器更新：相关控制器已更新with方法包含文件关联
4. ✅ 数据库迁移：字段类型已通过迁移文件修正
5. ✅ 类型转换：模型中的casts配置正确

注意事项

1. 文件存储：所有文件都存储在uploads表中，通过id关联
2. URL生成：Upload模型自动生成文件访问URL
3. 关联加载：使用with()方法预加载文件关联，避免N+1查询
4. 数据验证：上传文件时需要验证文件id是否存在于uploads表中
5. 软删除：文件删除时使用软删除，保持数据完整性

所有文件字段已按照要求修正完成，可以正常使用！