/**
 * 持久化存储 SPI 接口定义
 *
 * 统一抽象任务产出的文件和结构化数据的持久化能力，
 * 支持多种存储后端：本地文件系统、S3/COS 对象存储、DB 等。
 *
 * 设计原则：
 * - 接口只定义存储语义，不包含具体 SDK 细节
 * - Provider 实现可插拔，通过路由规则按需选择后端
 * - 沙箱内 S3 能力（@fefeding/common）与宿主侧持久化统一配置入口
 *
 * 使用方式（上层应用）：
 * ```ts
 * // 注册自定义 Provider
 * PersistenceManager.registerProvider('my-backend', new MyProvider());
 *
 * // 保存文件，自动路由到合适的 Provider
 * const result = await PersistenceManager.saveFile('report.pdf', buffer, {
 *   artifactType: 'report',
 *   contentType: 'application/pdf',
 * });
 * ```
 */
/** 文件元数据 */
export interface FileMeta {
    /** MIME 类型 */
    contentType?: string;
    /** 原始文件名 */
    filename?: string;
    /** 文件大小（字节） */
    size?: number;
    /** 产物类型标签 */
    artifactType?: string;
    /** 自定义标签 */
    tags?: Record<string, string>;
}
/** 结构化数据元数据 */
export interface DataMeta {
    /** MIME 类型 */
    contentType?: string;
    /** 自定义标签 */
    tags?: Record<string, string>;
}
/** 持久化后的文件结果 */
export interface PersistedFile {
    /** 存储键 */
    key: string;
    /** 内部引用 URI: s3://bucket/key | local://path | db://table/id */
    uri: string;
    /** 可访问 URL（COS 返回签名/公开 URL，本地返回 HTTP 路径） */
    url: string;
    /** 文件大小（字节） */
    size: number;
    /** MIME 类型 */
    contentType?: string;
    /** Provider 名称 */
    provider: string;
    /** 创建时间 */
    createdAt: string;
    /** ETag（对象存储返回） */
    etag?: string;
}
/** 持久化后的结构化数据结果 */
export interface PersistedData {
    /** 存储键 */
    key: string;
    /** 内部引用 URI */
    uri: string;
    /** Provider 名称 */
    provider: string;
    /** 创建时间 */
    createdAt: string;
}
/**
 * 持久化存储提供者接口
 *
 * 每种存储后端（LocalFS / S3 / COS / DB）实现此接口。
 * 通过 PersistenceManager 统一管理，按路由规则分发。
 */
export interface PersistenceProvider {
    /** Provider 唯一名称: 'local' | 's3' | 'cos' | 'db' | 自定义 */
    readonly name: string;
    /**
     * 保存文件（Buffer 或 Stream），返回可访问的 URI 和 URL
     * @param key    存储键（如 'artifacts/report_2024.pdf'）
     * @param content 文件内容
     * @param meta   文件元数据
     */
    saveFile(key: string, content: Buffer | NodeJS.ReadableStream, meta?: FileMeta): Promise<PersistedFile>;
    /**
     * 保存结构化数据（JSON / 对象），返回引用 ID
     * @param key 存储键
     * @param data 数据对象
     * @param meta 数据元数据
     */
    saveData(key: string, data: unknown, meta?: DataMeta): Promise<PersistedData>;
    /** 读取文件内容 */
    readFile(key: string): Promise<Buffer>;
    /** 读取结构化数据 */
    readData<T = unknown>(key: string): Promise<T>;
    /** 删除文件或数据 */
    delete(key: string): Promise<void>;
    /** 检查是否存在 */
    exists(key: string): Promise<boolean>;
    /**
     * 获取可访问 URL
     * - COS/S3: 返回签名 URL（可设置过期时间）
     * - Local: 返回 HTTP 路径
     * - DB: 返回数据 URI
     * @param key       存储键
     * @param expirySec URL 有效期（秒），仅对象存储有效
     */
    getAccessibleUrl(key: string, expirySec?: number): Promise<string>;
}
/**
 * 持久化路由规则：按数据类型/标签/大小选择 Provider
 *
 * 路由匹配按顺序执行，第一个匹配的规则生效。
 * 未匹配任何规则时使用 defaultProvider。
 */
export interface PersistenceRoute {
    /** 匹配条件（所有条件为 AND 关系，空对象 = 匹配所有） */
    match: {
        /** MIME 类型列表（任一匹配即可） */
        contentType?: string[];
        /** 产物类型标签 */
        artifactType?: string[];
        /** 自定义标签匹配（值需精确匹配） */
        tags?: Record<string, string>;
        /** 最小文件大小（字节），大于此值才匹配 */
        minSize?: number;
        /** 最大文件大小（字节），小于此值才匹配 */
        maxSize?: number;
    };
    /** 使用的 Provider 名称 */
    provider: string;
    /** key 前缀（组织目录结构，如 'artifacts/'） */
    keyPrefix?: string;
}
/** Local FS Provider 配置 */
export interface LocalFsProviderConfig {
    /** 根目录 */
    rootDir: string;
    /** URL 前缀（用于生成可访问 URL） */
    urlPrefix?: string;
}
/** S3/COS Provider 配置 */
export interface S3ProviderConfig {
    /** 存储桶名称 */
    bucket: string;
    /** 区域 */
    region: string;
    /** Access Key ID */
    accessKeyId?: string;
    /** Secret Access Key */
    secretAccessKey?: string;
    /** 临时会话 Token */
    sessionToken?: string;
    /** 自定义端点（MinIO / COS 等） */
    endpoint?: string;
    /** 是否使用 path-style（MinIO 需要 true） */
    forcePathStyle?: boolean;
    /** key 前缀 */
    keyPrefix?: string;
    /** 自定义域名（用于生成可访问 URL） */
    customDomain?: string;
    /** @fefeding/common S3 库路径（自动解析，通常无需手动设置） */
    libPath?: string;
}
/** DB Provider 配置 */
export interface DbProviderConfig {
    /** 表名 */
    tableName: string;
    /** 最大存储大小（字节），超过则拒绝 */
    maxSize: number;
}
/** 持久化总配置 */
export interface PersistenceConfig {
    /** 默认 Provider 名称 */
    defaultProvider: string;
    /** 路由规则列表 */
    routes: PersistenceRoute[];
    /** Provider 配置 */
    providers: {
        local?: LocalFsProviderConfig;
        s3?: S3ProviderConfig;
        cos?: S3ProviderConfig;
        db?: DbProviderConfig;
        [key: string]: unknown;
    };
}
export declare const PERSISTENCE_SPI_BINDINGS: {
    /** 自定义 PersistenceProvider 实现（用于 MidwayJS IoC 绑定） */
    readonly PersistenceProvider: "PersistenceProvider";
    /** 自定义 DbPersistenceProvider 实现 */
    readonly DbPersistenceProvider: "DbPersistenceProvider";
};
//# sourceMappingURL=persistence-interfaces.d.ts.map