@r2wa-org/eden 0.0.48

package/dist/src/file-storage/service.d.ts

@@ -0,0 +1,264 @@
+import type { ConfirmUploadInput, GenerateAccessUrlInput, GenerateBatchAccessUrlsInput, GenerateUploadUrlInput, ListFilesInput, VerifyFileInput } from "./dto.schemas";
+declare abstract class BaseFileStorageService {
+    protected static ensureFileExists<T>(file: T | undefined | null): asserts file is T;
+    protected static ensurePrivateOwnership(file: {
+        accessControl: string | null;
+        ownerId: string;
+    }, userId: string): void;
+    protected static ensureActive(file: {
+        status: string | null;
+    }): void;
+}
+export declare abstract class InternalFileStorageService extends BaseFileStorageService {
+    static generateUploadUrl(input: GenerateUploadUrlInput, userId: string): Promise<{
+        readonly fileId: string;
+        readonly uploadUrl: string;
+        readonly method: "PUT";
+        readonly headers: {
+            readonly "Content-Type": string;
+        };
+        readonly publicUrl: string | undefined;
+        readonly mimeType: string;
+        readonly expiresIn: number;
+        readonly expiresAt: number;
+    }>;
+    /**
+     * 确认上传完成
+     * 用户上传完成后调用此接口，更新文件状态
+     */
+    static confirmUpload(input: ConfirmUploadInput, userId: string): Promise<{
+        deletedAt: Date | null;
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        fileName: string | null;
+        fileSize: number | null;
+        mimeType: string | null;
+        fileExtension: string | null;
+        fileHash: string | null;
+        s3Bucket: string;
+        s3Key: string;
+        s3Region: string;
+        s3ETag: string | null;
+        businessType: "other" | "kyc_document" | "contract" | "financial_report" | "wallet_import" | "avatar" | "cover_image" | "notification_attachment" | "transaction_receipt" | "export_report" | "bank_verification" | "news_attachment";
+        businessId: string | null;
+        businessMetadata: string | null;
+        ownerId: string;
+        accessControl: "private" | "restricted" | "public" | null;
+        status: "uploading" | "active" | "archived" | "pending_deletion" | null;
+        publicUrl: string | null;
+        thumbnailUrl: string | null;
+        archivedAt: Date | null;
+        uploadCompletedAt: Date | null;
+        uploadIpAddress: string | null;
+        downloadCount: number | null;
+        lastDownloadedAt: Date | null;
+        isVerified: boolean | null;
+        verifiedBy: string | null;
+        verifiedAt: Date | null;
+        verificationNote: string | null;
+    } | undefined>;
+    /**
+     * 生成访问 URL（公开返回 publicUrl，私有/受限返回预签名）
+     */
+    static generateAccessUrl(input: GenerateAccessUrlInput, userId: string): Promise<{
+        expiresAt?: number | undefined;
+        id: string;
+        fileName: string | null;
+        url: string;
+    }>;
+    /**
+     * 批量生成访问 URL（公开文件返回公开地址，其他返回预签名地址）
+     */
+    static generateBatchAccessUrls(input: GenerateBatchAccessUrlsInput, userId: string): Promise<{
+        expiresAt?: number | undefined;
+        id: string;
+        fileName: string | null;
+        url: string;
+    }[]>;
+}
+export declare abstract class UserFileStorageService extends BaseFileStorageService {
+    /**
+     * 查询文件列表
+     */
+    static listFiles(filters: ListFilesInput, userId: string): Promise<{
+        data: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            deletedAt: Date | null;
+            fileName: string | null;
+            fileSize: number | null;
+            mimeType: string | null;
+            fileExtension: string | null;
+            fileHash: string | null;
+            s3Bucket: string;
+            s3Key: string;
+            s3Region: string;
+            s3ETag: string | null;
+            businessType: "other" | "kyc_document" | "contract" | "financial_report" | "wallet_import" | "avatar" | "cover_image" | "notification_attachment" | "transaction_receipt" | "export_report" | "bank_verification" | "news_attachment";
+            businessId: string | null;
+            businessMetadata: string | null;
+            ownerId: string;
+            accessControl: "private" | "restricted" | "public" | null;
+            status: "uploading" | "active" | "archived" | "pending_deletion" | null;
+            publicUrl: string | null;
+            thumbnailUrl: string | null;
+            archivedAt: Date | null;
+            uploadCompletedAt: Date | null;
+            uploadIpAddress: string | null;
+            downloadCount: number | null;
+            lastDownloadedAt: Date | null;
+            isVerified: boolean | null;
+            verifiedBy: string | null;
+            verifiedAt: Date | null;
+            verificationNote: string | null;
+        }[];
+        pagination: {
+            pageSize: number;
+            pageIndex: number;
+            total: number;
+            totalPages: number;
+            hasNextPage: boolean;
+        };
+    }>;
+    /**
+     * 获取文件详情
+     */
+    static getFileById(fileId: string, userId: string): Promise<{
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        deletedAt: Date | null;
+        fileName: string | null;
+        fileSize: number | null;
+        mimeType: string | null;
+        fileExtension: string | null;
+        fileHash: string | null;
+        s3Bucket: string;
+        s3Key: string;
+        s3Region: string;
+        s3ETag: string | null;
+        businessType: "other" | "kyc_document" | "contract" | "financial_report" | "wallet_import" | "avatar" | "cover_image" | "notification_attachment" | "transaction_receipt" | "export_report" | "bank_verification" | "news_attachment";
+        businessId: string | null;
+        businessMetadata: string | null;
+        ownerId: string;
+        accessControl: "private" | "restricted" | "public" | null;
+        status: "uploading" | "active" | "archived" | "pending_deletion" | null;
+        publicUrl: string | null;
+        thumbnailUrl: string | null;
+        archivedAt: Date | null;
+        uploadCompletedAt: Date | null;
+        uploadIpAddress: string | null;
+        downloadCount: number | null;
+        lastDownloadedAt: Date | null;
+        isVerified: boolean | null;
+        verifiedBy: string | null;
+        verifiedAt: Date | null;
+        verificationNote: string | null;
+    }>;
+    /**
+     * 删除文件（软删除）
+     */
+    static deleteFile(fileId: string, userId: string): Promise<{
+        success: boolean;
+    }>;
+}
+export declare abstract class AdminFileStorageService extends BaseFileStorageService {
+    /**
+     * 验证文件（管理员）
+     */
+    static verifyFile(input: VerifyFileInput, adminId: string): Promise<{
+        deletedAt: Date | null;
+        createdAt: Date;
+        updatedAt: Date;
+        id: string;
+        fileName: string | null;
+        fileSize: number | null;
+        mimeType: string | null;
+        fileExtension: string | null;
+        fileHash: string | null;
+        s3Bucket: string;
+        s3Key: string;
+        s3Region: string;
+        s3ETag: string | null;
+        businessType: "other" | "kyc_document" | "contract" | "financial_report" | "wallet_import" | "avatar" | "cover_image" | "notification_attachment" | "transaction_receipt" | "export_report" | "bank_verification" | "news_attachment";
+        businessId: string | null;
+        businessMetadata: string | null;
+        ownerId: string;
+        accessControl: "private" | "restricted" | "public" | null;
+        status: "uploading" | "active" | "archived" | "pending_deletion" | null;
+        publicUrl: string | null;
+        thumbnailUrl: string | null;
+        archivedAt: Date | null;
+        uploadCompletedAt: Date | null;
+        uploadIpAddress: string | null;
+        downloadCount: number | null;
+        lastDownloadedAt: Date | null;
+        isVerified: boolean | null;
+        verifiedBy: string | null;
+        verifiedAt: Date | null;
+        verificationNote: string | null;
+    } | undefined>;
+    /**
+     * 查询所有文件（管理员）
+     */
+    static listAllFiles(filters: ListFilesInput): Promise<{
+        data: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            deletedAt: Date | null;
+            fileName: string | null;
+            fileSize: number | null;
+            mimeType: string | null;
+            fileExtension: string | null;
+            fileHash: string | null;
+            s3Bucket: string;
+            s3Key: string;
+            s3Region: string;
+            s3ETag: string | null;
+            businessType: "other" | "kyc_document" | "contract" | "financial_report" | "wallet_import" | "avatar" | "cover_image" | "notification_attachment" | "transaction_receipt" | "export_report" | "bank_verification" | "news_attachment";
+            businessId: string | null;
+            businessMetadata: string | null;
+            ownerId: string;
+            accessControl: "private" | "restricted" | "public" | null;
+            status: "uploading" | "active" | "archived" | "pending_deletion" | null;
+            publicUrl: string | null;
+            thumbnailUrl: string | null;
+            archivedAt: Date | null;
+            uploadCompletedAt: Date | null;
+            uploadIpAddress: string | null;
+            downloadCount: number | null;
+            lastDownloadedAt: Date | null;
+            isVerified: boolean | null;
+            verifiedBy: string | null;
+            verifiedAt: Date | null;
+            verificationNote: string | null;
+            owner: {
+                email: string;
+                id: string;
+                name: string;
+            };
+            verifier: {
+                id: string;
+                name: string;
+            } | null;
+        }[];
+        pagination: {
+            pageSize: number;
+            pageIndex: number;
+            total: number;
+            totalPages: number;
+            hasNextPage: boolean;
+        };
+    }>;
+    /**
+     * 物理删除文件（管理员专用）
+     * 同时删除 S3 文件
+     */
+    static permanentlyDeleteFile(fileId: string): Promise<{
+        success: boolean;
+    }>;
+}
+export {};