<?php

namespace App\Service\common\upload;

/**
 * 对象键规整
 *
 * 五个驱动在列举 / 删除时对 key 的处理完全一致（补 path_prefix、压斜杠、拼 domain），
 * 抽出来免得同一段逻辑在五个文件里各写一遍、各改一半。
 * 使用方需要有 $this->config（由 OssRuntimeConfigService 注入，含 path_prefix / domain）。
 */
trait ObjectKeyNormalizeTrait
{
    /**
     * 补上 path_prefix 并压平重复斜杠
     *
     * 为什么必须压平：uploads//spa/a.jpg 与 uploads/spa/a.jpg 在 OSS 上是两个对象，
     * 但拼出来的访问地址会被 CDN 归一成同一个。素材库按 path 建索引，
     * 不统一就会落成两条记录，回收删掉其中一条后另一条变成指向已删对象的幽灵。
     */
    protected function normalizeObjectKey(string $key): string
    {
        $key = ltrim((string) preg_replace('#/{2,}#', '/', trim($key)), '/');
        if ($key === '') {
            return '';
        }
        $prefix = trim((string) ($this->config['path_prefix'] ?? ''), '/');
        if ($prefix !== '' && $key !== $prefix && !str_starts_with($key, $prefix . '/')) {
            $key = $prefix . '/' . $key;
        }
        return $key;
    }

    /**
     * 列举前缀：调用方没给就退回 path_prefix
     *
     * 同一个 bucket 常常被多个项目共用，不加这层兜底会把别人的对象也拉进素材库，
     * 之后走回收流程就等于跨项目删文件。
     */
    protected function scopedListPrefix(string $prefix): string
    {
        $prefix = trim($prefix);
        if ($prefix !== '') {
            return $this->normalizeObjectKey($prefix);
        }
        $base = trim((string) ($this->config['path_prefix'] ?? ''), '/');
        return $base === '' ? '' : $base . '/';
    }

    /**
     * 拼公开访问地址；未配置 domain 时回落到调用方给的默认地址
     */
    protected function publicUrlOf(string $key, string $fallback = ''): string
    {
        $domain = rtrim((string) ($this->config['domain'] ?? ''), '/');
        return $domain !== '' ? $domain . '/' . $key : $fallback;
    }

    /**
     * 单页列举条数收口，避免上游把 limit 传成 0 或者十万
     */
    protected function boundedLimit(int $limit): int
    {
        return max(1, min($limit, 1000));
    }
}