<?php

namespace App\Service\common\oss;

/**
 * OSS 存储驱动统一契约：工厂按 driver 返回实现类，UploadService 只依赖本接口
 */
interface OssStorageInterface
{
    /**
     * 注入本请求的运行时配置（密钥已解密）
     *
     * @param array $config OssRuntimeConfigService::getActiveConfig()
     */
    public function withConfig(array $config): static;

    /**
     * 上传图片对象
     *
     * @param mixed $filePath 本地路径或 UploadedFile
     * @param string $key 对象键
     * @return array{key:string,url:string}|false
     */
    public function uploadImage($filePath, string $key): bool|array;

    /**
     * 上传视频/通用文件对象
     *
     * @param mixed $filePath 本地路径或 UploadedFile
     * @param string $key 对象键
     * @return array{key:string,url:string}|false
     */
    public function uploadVideo($filePath, string $key): bool|array;

    /**
     * 分页列举对象
     *
     * 素材库靠 marker 一页一页往回补：bucket 上万对象时一次拉全量必然打穿
     * PHP 的执行时限，所以约定「调用方拿着 next_marker 继续要下一页」。
     *
     * @param string $prefix 只列举该前缀，留空时退回配置里的 path_prefix
     * @param string $marker 上一页返回的 next_marker，首页传空串
     * @param int $limit 单页条数
     * @return array{items: array<int, array{key:string,size:int,hash:string,last_modified:int,url:string}>, next_marker: string, finished: bool}
     */
    public function listObjects(string $prefix = '', string $marker = '', int $limit = 100): array;

    /**
     * 删除对象
     *
     * @param string $key 对象键（缺 path_prefix 时由实现补齐）
     */
    public function deleteObject(string $key): bool;
}