nolo-cli 0.1.26 → 0.1.29

package/server/handlers/appDeployFlow.ts

@@ -0,0 +1,876 @@
+import { authenticateRequest, CORS_HEADERS_AUTH } from "../../auth/utils";
+import { Mutex } from "async-mutex";
+import {
+  saveAppCode,
+  getAppRecord,
+  listUserApps,
+  type AppSourceSnapshot,
+  type AppRecord,
+} from "./appSandboxHandler";
+import { bundleWorkerCode, type BundleFile } from "../appBundler";
+import { validateWorkerCode, validateWorkerFiles } from "../workerValidator";
+import { ulid } from "ulid";
+import {
+  buildReactSpaApp,
+  validateReactAppFiles,
+  type ReactAppValidationIssue,
+} from "../reactAppBuilder";
+import { pushEvent } from "./eventBus";
+import {
+  createAppDeployJob,
+  createInitialAppDeploySteps,
+  getAppDeployJob,
+  getLatestAppDeployJobId,
+  patchAppDeployJob,
+  resolveLatestAppDeployJobId,
+  type AppDeployJobStep,
+} from "./appDeployStatusStore";
+import { addAppToSpace, hasSpaceRole, normalizeSpaceId } from "./appSpaceAccess";
+import { buildOwnerScopedAppKey } from "../../app/utils/appKeys";
+import {
+  type AppDeployAuthContext,
+  type AppDeployProgressReporter,
+  normalizeDeployBody,
+  canAccessAppRecord,
+  verifyDeployedUrl,
+  createDeployError,
+  STEP_STATUS_RANK,
+  appDeployEventChannel,
+  checkAuthAndConfig,
+  getAppBaseUrl,
+  jsonAccepted,
+  jsonError,
+  jsonOk,
+  looksLikeReactSource,
+} from "./appDeployShared";
+
+const deployLocks = new Map<string, Mutex>();
+const activeDeployTasks = new Set<Promise<void>>();
+
+type AppDeployIssueCode =
+  | "missing-code"
+  | "missing-name"
+  | "react-worker-misuse"
+  | "worker-validation"
+  | "missing-files"
+  | "missing-entry-file"
+  | "invalid-file"
+  | "invalid-file-path"
+  | "css-import-disallowed"
+  | "unsupported-import"
+  | "invalid-icon-import";
+
+interface AppDeployIssue {
+  code: AppDeployIssueCode;
+  message: string;
+  file?: string;
+  importSpecifier?: string;
+  symbol?: string;
+  suggestion?: string;
+}
+
+interface AppPreflightResult {
+  ok: boolean;
+  framework: "worker" | "react-spa";
+  summary: string;
+  issues: AppDeployIssue[];
+  warnings: string[];
+  entryFile?: string;
+  externalImports?: string[];
+}
+
+function buildPreflightSummary(result: AppPreflightResult): string {
+  if (result.ok) {
+    const parts = [`预检通过（${result.framework === "react-spa" ? "React SPA" : "Worker"}）`];
+    if (result.entryFile) parts.push(`入口: ${result.entryFile}`);
+    if (result.warnings.length > 0) parts.push(`警告 ${result.warnings.length} 条`);
+    return parts.join(" · ");
+  }
+  return `预检失败：${result.issues.length} 个问题，${result.warnings.length} 个警告`;
+}
+
+function toGenericIssues(
+  errors: string[],
+  code: AppDeployIssueCode = "worker-validation"
+): AppDeployIssue[] {
+  return errors.map((message) => ({ code, message }));
+}
+
+function hydratePreflightBodyFromRecord(body: any, record: AppRecord | null): any {
+  if (!record) return body;
+  const normalized = normalizeDeployBody(body);
+  if (normalized.code || normalized.files?.length) return body;
+
+  if (record.source?.kind === "react-spa") {
+    return {
+      ...body,
+      framework: "react-spa",
+      files: record.source.files,
+    };
+  }
+
+  if (record.source?.kind === "worker-files") {
+    return {
+      ...body,
+      framework: body?.framework ?? "worker",
+      files: record.source.files,
+    };
+  }
+
+  return {
+    ...body,
+    framework: body?.framework ?? "worker",
+    code: record.source?.kind === "worker-code" ? record.source.code : record.code,
+  };
+}
+
+async function runAppPreflight(body: any): Promise<AppPreflightResult> {
+  const normalized = normalizeDeployBody(body);
+
+  if (normalized.framework === "react-spa") {
+    if (!normalized.files?.length) {
+      return {
+        ok: false,
+        framework: "react-spa",
+        summary: "预检失败：缺少 React SPA files",
+        issues: [
+          {
+            code: "missing-files",
+            message:
+              'React SPA 模式必须提供 files 参数（至少 main.tsx + App.tsx）。如果你当前拿到的是 pages 字段，也可以直接传，服务端会自动兼容。',
+          },
+        ],
+        warnings: [],
+      };
+    }
+    const validation = validateReactAppFiles(normalized.files);
+    const result: AppPreflightResult = {
+      ok: validation.ok,
+      framework: "react-spa",
+      summary: "",
+      issues: validation.issues,
+      warnings: validation.warnings,
+      entryFile: validation.entryFile,
+      externalImports: validation.externalImports,
+    };
+    result.summary = buildPreflightSummary(result);
+    return result;
+  }
+
+  if (normalized.files?.length) {
+    const validation = validateWorkerFiles(normalized.files);
+    const result: AppPreflightResult = {
+      ok: validation.ok,
+      framework: "worker",
+      summary: "",
+      issues: toGenericIssues(validation.errors),
+      warnings: validation.warnings,
+    };
+    result.summary = buildPreflightSummary(result);
+    return result;
+  }
+
+  if (normalized.code && typeof normalized.code === "string") {
+    if (!normalized.framework && looksLikeReactSource(normalized.code)) {
+      const result: AppPreflightResult = {
+        ok: false,
+        framework: "worker",
+        summary: "",
+        issues: [
+          {
+            code: "react-worker-misuse",
+            message:
+              '检测到 React 组件/依赖代码，但当前请求走的是单文件 Worker 模式。请改用 framework="react-spa" + files（例如 main.tsx 和 App.tsx）；如果你只想返回静态 HTML，请移除 react/react-dom/react-icons import。',
+          },
+        ],
+        warnings: [],
+      };
+      result.summary = buildPreflightSummary(result);
+      return result;
+    }
+    const validation = await validateWorkerCode(normalized.code);
+    const result: AppPreflightResult = {
+      ok: validation.ok,
+      framework: "worker",
+      summary: "",
+      issues: toGenericIssues(validation.errors),
+      warnings: validation.warnings,
+    };
+    result.summary = buildPreflightSummary(result);
+    return result;
+  }
+
+  const result: AppPreflightResult = {
+    ok: false,
+    framework: normalized.framework === "react-spa" ? "react-spa" : "worker",
+    summary: "",
+    issues: [
+      {
+        code: normalized.rawName || normalized.appId ? "missing-code" : "missing-name",
+        message:
+          normalized.rawName || normalized.appId
+            ? "需要提供 code 或 files 参数；如果你生成的是 pages 字段，也可以直接传。"
+            : "必须提供 name 参数（新建应用时必填；更新已有应用时可省略，服务端从 appId 记录中自动补充）",
+      },
+    ],
+    warnings: [],
+  };
+  result.summary = buildPreflightSummary(result);
+  return result;
+}
+
+function normalizeAppNameForReuse(name: string): string {
+  return name.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function getDeployLockKey(params: { userId: string; appId?: string; name: string }): string {
+  if (params.appId) return `app:${params.appId}`;
+  return `name:${params.userId}:${normalizeAppNameForReuse(params.name)}`;
+}
+
+function getDeployLock(lockKey: string): Mutex {
+  let lock = deployLocks.get(lockKey);
+  if (!lock) {
+    lock = new Mutex();
+    deployLocks.set(lockKey, lock);
+  }
+  return lock;
+}
+
+function pickOwnedAppForImplicitReuse(
+  apps: Array<AppRecord & { appId?: string }>,
+  name: string
+): (AppRecord & { appId: string }) | null {
+  const normalizedName = normalizeAppNameForReuse(name);
+  const matches = apps.filter(
+    (app): app is AppRecord & { appId: string } =>
+      typeof app?.appId === "string" &&
+      !!app.appId &&
+      typeof app?.name === "string" &&
+      normalizeAppNameForReuse(app.name) === normalizedName
+  );
+  if (matches.length === 0) return null;
+  if (matches.length === 1) return matches[0];
+  throw createDeployError(
+    409,
+    `存在多个同名应用"${name}"，请改为传 appId 更新目标应用`,
+    "AMBIGUOUS_APP_NAME"
+  );
+}
+
+async function performAppDeploy(
+  auth: AppDeployAuthContext,
+  body: any,
+  appBaseUrl: string,
+  reportProgress: AppDeployProgressReporter
+): Promise<any> {
+  const {
+    rawName,
+    code,
+    files,
+    appId,
+    spaceId: requestedSpaceId,
+    framework,
+  } = normalizeDeployBody(body);
+
+  let redeployRecord: any = null;
+  if (appId && !code && !files) {
+    redeployRecord = await getAppRecord(appId);
+    if (!redeployRecord) throw createDeployError(404, "应用不存在", "APP_NOT_FOUND");
+    if (!(await canAccessAppRecord(auth.userId, redeployRecord, "member"))) {
+      throw createDeployError(403, "无权限", "FORBIDDEN");
+    }
+  }
+
+  let existingAppRecord: AppRecord | null = redeployRecord;
+  if (appId && !existingAppRecord) {
+    existingAppRecord = await getAppRecord(appId);
+    if (existingAppRecord && !(await canAccessAppRecord(auth.userId, existingAppRecord, "member"))) {
+      throw createDeployError(403, "无权限", "FORBIDDEN");
+    }
+  }
+
+  const effectiveSpaceId =
+    existingAppRecord?.spaceId
+      ? normalizeSpaceId(existingAppRecord.spaceId)
+      : requestedSpaceId;
+
+  if (existingAppRecord?.spaceId && requestedSpaceId && requestedSpaceId !== normalizeSpaceId(existingAppRecord.spaceId)) {
+    throw createDeployError(400, "暂不支持在重部署时迁移应用所属空间", "SPACE_MOVE_UNSUPPORTED");
+  }
+
+  if (effectiveSpaceId && !(await hasSpaceRole(auth.userId, effectiveSpaceId, "member"))) {
+    throw createDeployError(403, "当前用户不是目标空间成员", "FORBIDDEN");
+  }
+
+  const name = rawName ?? redeployRecord?.name ?? existingAppRecord?.name;
+  if (!name || typeof name !== "string") {
+    throw createDeployError(
+      400,
+      "必须提供 name 参数（新建应用时必填；更新已有应用时可省略，服务端从 appId 记录中自动补充）",
+      "MISSING_NAME"
+    );
+  }
+
+  await reportProgress({
+    stepId: "preflight",
+    summary: "正在预检代码…",
+    detail: framework === "react-spa" ? "检查 React SPA 文件、依赖与图标约束" : "检查 Worker 代码与部署参数",
+    jobStatus: "running",
+  });
+
+  const preflightBody = hydratePreflightBodyFromRecord(body, redeployRecord);
+  const preflight = await runAppPreflight(preflightBody);
+  if (!preflight.ok) {
+    const preflightError = createDeployError(400, preflight.summary, "PREFLIGHT_FAILED") as Error & {
+      details?: unknown;
+    };
+    preflightError.details = {
+      framework: preflight.framework,
+      issues: preflight.issues,
+      warnings: preflight.warnings,
+      entryFile: preflight.entryFile,
+      externalImports: preflight.externalImports,
+    };
+    throw preflightError;
+  }
+
+  await reportProgress({
+    stepId: "preflight",
+    status: "succeeded",
+    summary: preflight.summary,
+    detail:
+      preflight.framework === "react-spa"
+        ? `React SPA 预检通过${preflight.entryFile ? `，入口 ${preflight.entryFile}` : ""}`
+        : "Worker 预检通过",
+    jobStatus: "running",
+  });
+
+  await reportProgress({
+    stepId: "build",
+    summary: "正在打包应用…",
+    detail: framework === "react-spa" ? "服务器正在构建 React SPA" : "服务器正在校验并打包代码",
+    jobStatus: "running",
+  });
+
+  let finalCode: string;
+  let bundleWarnings: string[] = [];
+  let source: AppSourceSnapshot;
+  let resolvedFramework: "worker" | "react-spa" =
+    framework === "react-spa" ? "react-spa" : "worker";
+
+  if (redeployRecord) {
+    if (redeployRecord.source?.kind === "react-spa") {
+      try {
+        const reactBuild = await buildReactSpaApp(redeployRecord.source.files, {
+          appName: name,
+        });
+        finalCode = reactBuild.workerCode;
+        bundleWarnings.push(...reactBuild.warnings);
+        source = {
+          kind: "react-spa",
+          files: redeployRecord.source.files,
+          entryFile: reactBuild.entryFile,
+          externalImports: reactBuild.externalImports,
+        };
+        resolvedFramework = "react-spa";
+      } catch (err: any) {
+        throw createDeployError(400, `React 应用打包失败: ${err.message}`, "BUNDLE_ERROR");
+      }
+    } else if (redeployRecord.source?.kind === "worker-files") {
+      const fileValidation = validateWorkerFiles(redeployRecord.source.files);
+      if (!fileValidation.ok) {
+        throw createDeployError(400, fileValidation.errors.join("\n"), "INVALID_CODE");
+      }
+      bundleWarnings.push(...fileValidation.warnings);
+      try {
+        const result = await bundleWorkerCode(redeployRecord.source.files);
+        finalCode = result.code;
+        bundleWarnings.push(...result.warnings);
+        source = {
+          kind: "worker-files",
+          files: redeployRecord.source.files,
+        };
+      } catch (err: any) {
+        throw createDeployError(400, `打包失败: ${err.message}`, "BUNDLE_ERROR");
+      }
+    } else {
+      const reValidation = await validateWorkerCode(redeployRecord.code);
+      if (!reValidation.ok) {
+        throw createDeployError(
+          400,
+          `存量代码不满足当前安全规则：${reValidation.errors.join("\n")}`,
+          "INVALID_CODE"
+        );
+      }
+      bundleWarnings.push(...reValidation.warnings);
+      finalCode = redeployRecord.code;
+      source =
+        redeployRecord.source ?? { kind: "worker-code", code: redeployRecord.code };
+    }
+  } else if (framework === "react-spa") {
+    if (!files || !Array.isArray(files) || files.length === 0) {
+      throw createDeployError(
+        400,
+        'React SPA 模式必须提供 files 参数（至少 main.tsx + App.tsx）。如果你当前拿到的是 pages 字段，也可以直接传，服务端会自动兼容。',
+        "MISSING_CODE"
+      );
+    }
+    try {
+      const reactBuild = await buildReactSpaApp(files, { appName: name });
+      finalCode = reactBuild.workerCode;
+      bundleWarnings.push(...reactBuild.warnings);
+      source = {
+        kind: "react-spa",
+        files,
+        entryFile: reactBuild.entryFile,
+        externalImports: reactBuild.externalImports,
+      };
+      resolvedFramework = "react-spa";
+    } catch (err: any) {
+      throw createDeployError(400, `React 应用打包失败: ${err.message}`, "BUNDLE_ERROR");
+    }
+  } else if (files && Array.isArray(files) && files.length > 0) {
+    const bundleFiles: BundleFile[] = files;
+    const fileValidation = validateWorkerFiles(bundleFiles);
+    if (!fileValidation.ok) {
+      throw createDeployError(400, fileValidation.errors.join("\n"), "INVALID_CODE");
+    }
+    bundleWarnings.push(...fileValidation.warnings);
+    try {
+      const result = await bundleWorkerCode(bundleFiles);
+      finalCode = result.code;
+      bundleWarnings.push(...result.warnings);
+      source = {
+        kind: "worker-files",
+        files: bundleFiles,
+      };
+    } catch (err: any) {
+      throw createDeployError(400, `打包失败: ${err.message}`, "BUNDLE_ERROR");
+    }
+  } else if (code && typeof code === "string") {
+    if (looksLikeReactSource(code)) {
+      throw createDeployError(
+        400,
+        '检测到 React 组件/依赖代码，但当前请求走的是单文件 Worker 模式。请改用 framework="react-spa" + files（例如 main.tsx 和 App.tsx）；如果你只想返回静态 HTML，请移除 react/react-dom/react-icons import。',
+        "INVALID_CODE"
+      );
+    }
+    const codeValidation = await validateWorkerCode(code);
+    if (!codeValidation.ok) {
+      throw createDeployError(400, codeValidation.errors.join("\n"), "INVALID_CODE");
+    }
+    bundleWarnings.push(...codeValidation.warnings);
+    finalCode = code;
+    source = { kind: "worker-code", code };
+  } else {
+    throw createDeployError(
+      400,
+      "需要提供 code 或 files 参数；如果你生成的是 pages 字段，也可以直接传。",
+      "MISSING_CODE"
+    );
+  }
+
+  resolvedFramework =
+    resolvedFramework ?? (redeployRecord?.framework === "react-spa" ? "react-spa" : "worker");
+
+  const credentialUserId = existingAppRecord?.userId ?? auth.userId;
+
+  await reportProgress({
+    stepId: "deploy",
+    summary: "正在发布站点…",
+    detail: "写入平台运行时与应用记录",
+    jobStatus: "running",
+  });
+
+  const persistResolvedApp = async (params: {
+    resolvedAppId: string;
+    credentialUserId: string;
+    effectiveSpaceId?: string;
+  }) => {
+    const resolvedAppKey = buildOwnerScopedAppKey({
+      userId: params.credentialUserId,
+      appId: params.resolvedAppId,
+      spaceId: params.effectiveSpaceId,
+    });
+
+    const [savedRecord] = await Promise.all([
+      saveAppCode(params.resolvedAppId, finalCode, {
+        userId: params.credentialUserId,
+        name,
+        deployMode: "platform",
+        source,
+        framework: resolvedFramework,
+        versionServerOrigin: appBaseUrl,
+        spaceId: params.effectiveSpaceId,
+      }),
+      params.effectiveSpaceId
+        ? addAppToSpace({
+            spaceId: params.effectiveSpaceId,
+            appId: params.resolvedAppId,
+            appKey: resolvedAppKey,
+            title: name,
+          })
+        : Promise.resolve(),
+    ]);
+
+    return {
+      resolvedAppId: params.resolvedAppId,
+      resolvedAppKey,
+      savedRecord,
+    };
+  };
+
+  let resolvedAppId: string;
+  let resolvedAppKey: string;
+  let savedRecord: Awaited<ReturnType<typeof saveAppCode>>;
+
+  const deployLockKey = getDeployLockKey({
+    userId: auth.userId,
+    appId: appId ?? undefined,
+    name,
+  });
+
+  ({
+    resolvedAppId,
+    resolvedAppKey,
+    savedRecord,
+  } = await getDeployLock(deployLockKey).runExclusive(async () => {
+    if (appId) {
+      const existing = await getAppRecord(appId);
+      if (existing && !(await canAccessAppRecord(auth.userId, existing, "member"))) {
+        throw createDeployError(403, "appId 已被其他用户使用", "FORBIDDEN");
+      }
+      return persistResolvedApp({
+        resolvedAppId: appId,
+        credentialUserId,
+        effectiveSpaceId,
+        });
+    }
+
+    const lockedExistingAppRecord = pickOwnedAppForImplicitReuse(
+      await listUserApps(auth.userId),
+      name
+    );
+    const lockedEffectiveSpaceId =
+      lockedExistingAppRecord?.spaceId
+        ? normalizeSpaceId(lockedExistingAppRecord.spaceId)
+        : requestedSpaceId;
+
+    if (
+      lockedExistingAppRecord?.spaceId &&
+      requestedSpaceId &&
+      requestedSpaceId !== normalizeSpaceId(lockedExistingAppRecord.spaceId)
+    ) {
+      throw createDeployError(400, "暂不支持在重部署时迁移应用所属空间", "SPACE_MOVE_UNSUPPORTED");
+    }
+
+    if (
+      lockedEffectiveSpaceId &&
+      !(await hasSpaceRole(auth.userId, lockedEffectiveSpaceId, "member"))
+    ) {
+      throw createDeployError(403, "当前用户不是目标空间成员", "FORBIDDEN");
+    }
+
+    return persistResolvedApp({
+      resolvedAppId: lockedExistingAppRecord?.appId ?? ulid(),
+      credentialUserId: lockedExistingAppRecord?.userId ?? auth.userId,
+      effectiveSpaceId: lockedEffectiveSpaceId,
+    });
+  }));
+
+  const primaryUrl = `${appBaseUrl}/apps/${resolvedAppId}/`;
+  const preferredCustomUrl = savedRecord?.customUrl?.trim() || undefined;
+  await reportProgress({
+    stepId: "verify",
+    summary: "部署已完成，正在验证访问…",
+    detail: primaryUrl,
+    jobStatus: "running",
+  });
+  const previewCheck = await verifyDeployedUrl(primaryUrl);
+
+  return {
+    success: true,
+    url: primaryUrl,
+    customUrl: preferredCustomUrl,
+    previewReady: previewCheck.ready,
+    modifiedOn: new Date().toISOString(),
+    userFriendlyName: name,
+    appId: resolvedAppId,
+    appKey: resolvedAppKey,
+    bundleWarnings,
+    deployMode: "platform",
+    framework: resolvedFramework,
+    previewCheck,
+    appUrl: preferredCustomUrl ?? primaryUrl,
+    appRecord: savedRecord?.record ?? null,
+  };
+}
+
+export async function handleAppDeploy(req: Request): Promise<Response> {
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: CORS_HEADERS_AUTH });
+  }
+
+  const auth = await checkAuthAndConfig(req);
+  if (auth instanceof Response) return auth;
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return jsonError(400, "请求体必须是合法的 JSON", "INVALID_JSON");
+  }
+
+  const normalized = normalizeDeployBody(body);
+  if (!normalized.rawName && !normalized.appId) {
+    return jsonError(
+      400,
+      "必须提供 name 参数（新建应用时必填；更新已有应用时可省略，服务端从 appId 记录中自动补充）",
+      "MISSING_NAME"
+    );
+  }
+  if (normalized.framework === "react-spa" && normalized.code && !normalized.files?.length) {
+    return jsonError(
+      400,
+      'React SPA 模式必须提供 files 参数（至少 main.tsx + App.tsx）。如果你当前拿到的是 pages 字段，也可以直接传，服务端会自动兼容。',
+      "MISSING_CODE"
+    );
+  }
+  if (
+    normalized.code &&
+    typeof normalized.code === "string" &&
+    !normalized.framework &&
+    looksLikeReactSource(normalized.code)
+  ) {
+    return jsonError(
+      400,
+      '检测到 React 组件/依赖代码，但当前请求走的是单文件 Worker 模式。请改用 framework="react-spa" + files（例如 main.tsx 和 App.tsx）；如果你只想返回静态 HTML，请移除 react/react-dom/react-icons import。',
+      "INVALID_CODE"
+    );
+  }
+  if (!normalized.appId && !normalized.code && !normalized.files?.length) {
+    return jsonError(
+      400,
+      "需要提供 code 或 files 参数；如果你生成的是 pages 字段，也可以直接传。",
+      "MISSING_CODE"
+    );
+  }
+  if (normalized.deployTarget && normalized.deployTarget !== "platform") {
+    return jsonError(
+      400,
+      "App 部署已不再支持 Cloudflare 目标，请使用平台托管。",
+      "DEPLOY_TARGET_REMOVED"
+    );
+  }
+
+  const jobId = ulid();
+  const steps = createInitialAppDeploySteps();
+  await createAppDeployJob({
+    jobId,
+    userId: auth.userId,
+    name: normalized.rawName,
+    steps,
+  });
+  pushEvent(appDeployEventChannel(jobId), {
+    type: "app-deploy-progress",
+    jobId,
+    status: "pending",
+    summary: "部署请求已接收，正在服务端排队执行…",
+    steps,
+  });
+
+  const appBaseUrl = getAppBaseUrl(req);
+  const task = (async () => {
+    let currentStepId: AppDeployJobStep["id"] = "prepare";
+    let currentSteps = steps;
+    const stepOrder: AppDeployJobStep["id"][] = ["prepare", "preflight", "build", "deploy", "verify"];
+    const reportProgress: AppDeployProgressReporter = async ({
+      stepId,
+      status = "running",
+      summary,
+      detail,
+      jobStatus = "running",
+      result,
+      error,
+    }) => {
+      currentStepId = stepId;
+      const currentIndex = stepOrder.indexOf(stepId);
+      currentSteps = currentSteps.map((step, index) => {
+        if (index < currentIndex) {
+          return STEP_STATUS_RANK[step.status] >= STEP_STATUS_RANK.succeeded
+            ? step
+            : { ...step, status: "succeeded" };
+        }
+        if (step.id === stepId) {
+          return STEP_STATUS_RANK[status] < STEP_STATUS_RANK[step.status]
+            ? step
+            : { ...step, status, detail };
+        }
+        if (index > currentIndex) {
+          return step.status === "pending" ? { ...step, detail: undefined } : step;
+        }
+        return step;
+      });
+      const patched = await patchAppDeployJob(jobId, {
+        status: jobStatus,
+        summary,
+        steps: currentSteps,
+        ...(result === undefined ? {} : { result }),
+        ...(error === undefined ? {} : { error }),
+      });
+      if (!patched) {
+        console.warn(`[appDeploy] job ${jobId} not found or expired, progress update dropped`);
+      } else {
+        pushEvent(appDeployEventChannel(jobId), {
+          type: "app-deploy-progress",
+          jobId,
+          status: jobStatus,
+          summary,
+          steps: currentSteps,
+          ...(result === undefined ? {} : { result }),
+          ...(error === undefined ? {} : { error }),
+        });
+      }
+    };
+
+    try {
+      const result = await performAppDeploy(auth, body, appBaseUrl, reportProgress);
+      const previewCheck = result?.previewCheck;
+      await reportProgress({
+        stepId: "verify",
+        status: "succeeded",
+        summary:
+          previewCheck?.ready
+            ? "部署完成，访问验证通过"
+            : "部署完成，可继续在预览卡中等待页面载入",
+        detail: previewCheck?.ready
+          ? `已在第 ${previewCheck.attempts} 次探测返回 ${previewCheck.status ?? 200}`
+          : "预览地址尚未在探测窗口内稳定返回，通常是冷启动或首次加载较慢",
+        jobStatus: "succeeded",
+        result,
+      });
+    } catch (error: any) {
+      try {
+        await reportProgress({
+          stepId: currentStepId,
+          status: "failed",
+          summary: error?.message || "部署失败",
+          detail: "服务端任务执行失败",
+          jobStatus: "failed",
+          error: {
+            message: error?.message || "部署失败",
+            code: error?.code,
+            details: error?.details,
+          },
+        });
+      } catch (reportError: any) {
+        console.error(`[appDeploy] failed to report error status for job ${jobId}:`, reportError);
+      }
+    }
+  })().finally(() => {
+    activeDeployTasks.delete(task);
+  });
+  activeDeployTasks.add(task);
+
+  return jsonAccepted({
+    success: true,
+    jobId,
+    eventChannel: appDeployEventChannel(jobId),
+    status: "pending",
+    summary: "部署请求已接收，正在服务端排队执行…",
+    steps,
+  });
+}
+
+export async function waitForActiveAppDeployTasks(): Promise<void> {
+  const pending = [...activeDeployTasks];
+  if (pending.length === 0) return;
+  await Promise.allSettled(pending);
+}
+
+export async function handleAppPreflight(req: Request): Promise<Response> {
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: CORS_HEADERS_AUTH });
+  }
+
+  const auth = await checkAuthAndConfig(req);
+  if (auth instanceof Response) return auth;
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return jsonError(400, "请求体必须是合法的 JSON", "INVALID_JSON");
+  }
+
+  let effectiveBody = body;
+  if (body?.appId) {
+    const existingRecord = await getAppRecord(body.appId);
+    if (!existingRecord) {
+      return jsonError(404, "应用不存在", "APP_NOT_FOUND");
+    }
+    if (!(await canAccessAppRecord(auth.userId, existingRecord, "member"))) {
+      return jsonError(403, "无权限", "FORBIDDEN");
+    }
+    effectiveBody = hydratePreflightBodyFromRecord(body, existingRecord);
+  }
+
+  const result = await runAppPreflight(effectiveBody);
+  return jsonOk({
+    success: result.ok,
+    ok: result.ok,
+    framework: result.framework,
+    summary: result.summary,
+    issues: result.issues,
+    warnings: result.warnings,
+    entryFile: result.entryFile,
+    externalImports: result.externalImports,
+  });
+}
+
+export async function handleAppDeployStatus(req: Request): Promise<Response> {
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: CORS_HEADERS_AUTH });
+  }
+
+  const auth = await authenticateRequest(req);
+  if (auth instanceof Response) return auth;
+
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return jsonError(400, "请求体必须是合法的 JSON", "INVALID_JSON");
+  }
+
+  const requestedJobId = typeof body?.jobId === "string" ? body.jobId : "";
+  let jobId = requestedJobId;
+  if (!jobId) {
+    const latest = await resolveLatestAppDeployJobId(auth.userId);
+    if (latest.ambiguous) {
+      return jsonError(
+        409,
+        "当前有多个进行中的部署任务，无法自动判断要恢复哪一个，请传入 jobId 查询具体任务。",
+        "AMBIGUOUS_JOB_ID"
+      );
+    }
+    jobId = latest.jobId || (await getLatestAppDeployJobId(auth.userId)) || "";
+  }
+  if (!jobId) return jsonError(400, "缺少 jobId 参数", "MISSING_JOB_ID");
+
+  const job = await getAppDeployJob(jobId);
+  if (!job) return jsonError(404, "部署任务不存在或已过期", "JOB_NOT_FOUND");
+  if (job.userId !== auth.userId) return jsonError(403, "无权限", "FORBIDDEN");
+
+  return jsonOk({
+    success: true,
+    jobId: job.jobId,
+    status: job.status,
+    summary: job.summary,
+    steps: job.steps,
+    result: job.result,
+    error: job.error,
+    updatedAt: job.updatedAt,
+  });
+}