@cloudbase/manager-node 5.8.0-beta.2 → 5.8.1

package/types/storage/type.d.ts

@@ -288,6 +288,121 @@ export interface IUploadObjectBySignHttpOptions {
 export interface IUploadObjectBySignHttpResult {
     Key: string;
 }
+/** 本地 manifest 条目：待发布文件的内容摘要 */
+export interface ILocalManifestItem {
+    /** 云端 Key */
+    key: string;
+    /** 本地文件内容 MD5（32 位小写十六进制） */
+    md5: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 本地文件绝对路径 */
+    localPath: string;
+}
+/** 远端 manifest 条目：远端 COS 对象信息 */
+export interface IRemoteManifestItem {
+    /** 云端 Key */
+    key: string;
+    /** 对象 ETag（去除首尾引号后） */
+    etag: string;
+    /** 对象大小（字节） */
+    size: number;
+}
+/** manifest 差异结果：用于回滚判定与发布后清理 */
+export interface IManifestDiffResult {
+    /** 本地有、远端无 —— 本次新增 */
+    added: string[];
+    /** 本地有、远端也有 —— 本次覆盖 */
+    overwritten: string[];
+    /** 远端有、本地无 —— 可作为 prune 候选 */
+    removed: string[];
+}
+/** manifest 校验结果：用于发布后确认远端内容是否与本地一致 */
+export interface IManifestVerifyResult {
+    /** 是否校验通过 */
+    ok: boolean;
+    /** 本地有但远端不存在的 Key */
+    missing: string[];
+    /** 远端存在但摘要或大小不匹配的 Key */
+    mismatched: string[];
+}
+/** 上传进度回调（与 StorageService 上传回调语义一致） */
+export type IConsistentUploadProgress = (progressData: {
+    loaded: number;
+    total: number;
+    speed: number;
+    percent: number;
+}) => void;
+/** 单文件上传完成回调（与 StorageService 的 onFileFinish 语义一致） */
+export type IConsistentUploadFileFinish = (error: Error, res: any, fileData: any) => void;
+/** 一致性发布上传选项 */
+export interface IConsistentUploadOptions {
+    /** 本地待发布目录（绝对或相对路径） */
+    localPath: string;
+    /** 云端目标前缀，无前导斜杠（如 'dist'）；为空表示桶根 */
+    cloudPath?: string;
+    /** 目标桶 */
+    bucket: string;
+    /** 目标地域 */
+    region: string;
+    /** 忽略规则，语义与现有 uploadDirectoryCustom 的 ignore 一致 */
+    ignore?: string | string[];
+    /** 是否获取文件 fileId */
+    fileId?: boolean;
+    /** 并发数量 */
+    parallel?: number;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 重试时间间隔（毫秒） */
+    retryInterval?: number;
+    /** 上传进度回调 */
+    onProgress?: IConsistentUploadProgress;
+    /** 单文件上传完成回调（error / res / fileData，与普通上传语义一致） */
+    onFileFinish?: IConsistentUploadFileFinish;
+    /** 发布后校验远端与本地产物一致 */
+    verify?: boolean;
+    /** 安全发布：发布前快照备份 + 失败自动回滚 */
+    safe?: boolean;
+    /**
+     * ⚠️ 危险参数：发布后清理远端多余文件。
+     * 会删除云端 cloudPath 下、本地构建中不存在的全部文件。
+     * 若误传错误的 localPath/cloudPath，整个目录都会被判定为冗余而删除。
+     * 发布成功后备份默认保留，prune 误删的文件可从备份前缀人工恢复；
+     * 调用方（CLI）必须经用户二次确认后才可开启。
+     */
+    prune?: boolean;
+    /**
+     * 入口文件列表。
+     * 为相对 localPath 的相对路径，如 'index.html'、'admin/index.html'。
+     * 未指定时默认识别所有层级下的 index.html。
+     */
+    entries?: string[];
+}
+/** 远端多余文件清理结果 */
+export interface IPruneResult {
+    /** 成功删除的云端 Key */
+    deletedKeys: string[];
+    /** 删除失败的文件及原因 */
+    failedKeys: {
+        key: string;
+        error: string;
+    }[];
+}
+/** 一致性发布结果 */
+export interface IConsistentUploadResult {
+    /** 本次成功上传的云端 Key */
+    uploadedKeys: string[];
+    /** 是否执行了发布后校验 */
+    verified: boolean;
+    /**
+     * 发布前备份前缀，仅 safe 开启时返回，如 .cloudbase-backup/1724073600000/。
+     * 备份一律不由编排自动清理（发布成功与回滚后均保留）：prune 误删或需要
+     * 人工核查时可从中恢复；调用方确认无误后应通过 cleanupBackup 显式清理。
+     */
+    backupPrefix?: string;
+    /** 远端多余文件清理结果，仅 prune 开启时存在 */
+    prune?: IPruneResult;
+}
 /** 下载方法，仅支持 GET / HEAD */
 export type IDownloadObjectHttpMethod = 'GET' | 'HEAD';
 /** 下载对象公共参数 */