UHD_Media_Tool/apps/web/app/api/downloads.ts

import { keepPreviousData, useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import {
  AcquisitionPlan,
  cursorPage,
  Dashboard,
  DownloadBoard,
  type DownloadBoardState,
  DownloaderInstance,
  type DownloadStatus,
  DownloadTask,
  DownloadWhy,
  type PlanStatus,
} from "@umt/contracts";
import { z } from "zod";
import { TTL_SECOND } from "~/lib/api.ts";
import { apiMutate, apiParsed, cleanParams, fetchAllCursorPages } from "./parse.ts";

// 下载任务、计划(界面统称"下载")、缓存卷(W2-C:/download-tasks、/acquisition-plans、/download-cache/cleanup、/dashboard)

const DownloadPage = cursorPage(DownloadTask);
const PlanPage = cursorPage(AcquisitionPlan);

export type DownloadFilters = { status?: DownloadStatus; instanceId?: string; managed?: "true" | "false" };

export const downloadKeys = {
  all: ["downloads"] as const,
  list: (f: DownloadFilters) => ["downloads", "list", f] as const,
  one: (id: string) => ["downloads", "one", id] as const,
  plans: (status?: PlanStatus) => ["downloads", "plans", status ?? "all"] as const,
  plan: (id: string) => ["downloads", "plan", id] as const,
  why: (id: string) => ["downloads", "why", id] as const,
  cache: () => ["downloads", "cache"] as const,
  board: (state: DownloadBoardState) => ["downloads", "board", state] as const,
};

const ACTIVE: DownloadStatus[] = ["queued", "submitting", "downloading", "importing", "stalled"];

export function useDownloadTasks(f: DownloadFilters) {
  return useInfiniteQuery({
    queryKey: downloadKeys.list(f),
    initialPageParam: undefined as string | undefined,
    placeholderData: keepPreviousData,
    queryFn: ({ pageParam, signal }) =>
      apiParsed(DownloadPage, "/api/v1/download-tasks", {
        params: cleanParams({ ...f, cursor: pageParam, limit: 50 }),
        signal,
      }),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    // 有进行中的任务时 10 秒轮询进度(SSE download.progress 到达时也会失效重取)
    refetchInterval: (q) =>
      q.state.data?.pages.some((p) => p.items.some((t) => ACTIVE.includes(t.status))) ? 10 * TTL_SECOND : false,
  });
}

/** 下载面板轮询间隔:页面可见时刷新,标签页在后台时 React Query 自动暂停(refetchIntervalInBackground=false) */
export const BOARD_POLL_MS = 4 * TTL_SECOND;

/**
 * 下载面板(DL-2):分组列表 + 实时速度 + 两组计数 + 下载器总速度。
 * 不保留上一个分组的数据:两组列不同,切换时先显示加载态。
 */
export function useDownloadBoard(state: DownloadBoardState) {
  return useInfiniteQuery({
    queryKey: downloadKeys.board(state),
    initialPageParam: undefined as string | undefined,
    queryFn: ({ pageParam, signal }) =>
      apiParsed(DownloadBoard, "/api/v1/download-tasks/board", {
        params: cleanParams({ state, cursor: pageParam, limit: 50 }),
        signal,
      }),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    refetchInterval: BOARD_POLL_MS,
    refetchIntervalInBackground: false,
  });
}

/** 深链 ?plan=(DL-3):只取这个计划对应的面板行(等待中的计划或它的下载任务);没有行 = 已结束或不存在 */
export function useBoardPlanRow(planId: string | null) {
  return useQuery({
    queryKey: ["downloads", "board-plan", planId ?? ""],
    enabled: !!planId,
    queryFn: ({ signal }) =>
      apiParsed(DownloadBoard, "/api/v1/download-tasks/board", {
        params: { planId: planId ?? "", limit: 1 },
        signal,
      }).then((b) => b.items[0] ?? null),
  });
}

export function useDownloadTask(id: string | undefined) {
  return useQuery({
    queryKey: downloadKeys.one(id ?? ""),
    enabled: !!id,
    queryFn: ({ signal }) =>
      apiParsed(DownloadTask, "/api/v1/download-tasks/:id", { pathParams: { id: id ?? "" }, signal }),
  });
}

export function usePlans(status?: PlanStatus) {
  return useInfiniteQuery({
    queryKey: downloadKeys.plans(status),
    initialPageParam: undefined as string | undefined,
    placeholderData: keepPreviousData,
    queryFn: ({ pageParam, signal }) =>
      apiParsed(PlanPage, "/api/v1/acquisition-plans", {
        params: cleanParams({ status, cursor: pageParam, limit: 50 }),
        signal,
      }),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
  });
}

export function usePlan(id: string | null | undefined) {
  return useQuery({
    queryKey: downloadKeys.plan(id ?? ""),
    enabled: !!id,
    queryFn: ({ signal }) =>
      apiParsed(AcquisitionPlan, "/api/v1/acquisition-plans/:id", { pathParams: { id: id ?? "" }, signal }),
  });
}

/** 「为什么下这个」(DL-3):来源、目的、被替换的版本、选中理由要点与原始评估 */
export function usePlanWhy(id: string | null | undefined) {
  return useQuery({
    queryKey: downloadKeys.why(id ?? ""),
    enabled: !!id,
    staleTime: 60 * TTL_SECOND,
    queryFn: ({ signal }) =>
      apiParsed(DownloadWhy, "/api/v1/acquisition-plans/:id/why", { pathParams: { id: id ?? "" }, signal }),
  });
}

/** 取消还没提交的下载(已预留 / 草案);待批准的走拒绝审批,服务端随之取消 */
export function useCancelPlan() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (id: string) =>
      apiMutate("/api/v1/acquisition-plans/:id/cancel", { pathParams: { id } }).then((d) => AcquisitionPlan.parse(d)),
    onSuccess: () => qc.invalidateQueries({ queryKey: downloadKeys.all }),
  });
}

/** 暂停(记为用户暂停)/ 恢复;阈值暂停在水位未回落前服务端拒绝恢复 */
export function useDownloadAction() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: ({ id, action }: { id: string; action: "pause" | "resume" }) =>
      apiMutate(`/api/v1/download-tasks/:id/${action}`, { pathParams: { id } }).then((d) => DownloadTask.parse(d)),
    onSuccess: (d) => {
      qc.setQueryData(downloadKeys.one(d.id), d);
      qc.invalidateQueries({ queryKey: ["downloads", "list"] });
    },
  });
}

/** 缓存卷用量/阈值:取首页聚合里的 cache 区块(同一统计口径) */
export function useCacheVolumes() {
  return useQuery({
    queryKey: downloadKeys.cache(),
    queryFn: ({ signal }) => apiParsed(Dashboard, "/api/v1/dashboard", { signal }),
    select: (d) => d.cache.volumes,
    refetchInterval: 30 * TTL_SECOND,
  });
}

/** 手动清理:服务端入队 cleanupDownloadCache(只清已验证入库且满足保留/H&R 的纳管任务),返回任务 id */
export function useCacheCleanup() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (downloaderInstanceId?: string) =>
      apiMutate("/api/v1/download-cache/cleanup", {
        body: downloaderInstanceId ? { downloaderInstanceId } : {},
      }).then((d) => z.object({ taskId: z.string(), runId: z.string() }).parse(d)),
    onSuccess: () => qc.invalidateQueries({ queryKey: downloadKeys.all }),
  });
}

/** 下载器实例名(列表展示用) */
export function useDownloaderNames() {
  return useQuery({
    queryKey: ["downloads", "instances"],
    staleTime: 5 * 60 * TTL_SECOND,
    queryFn: ({ signal }) =>
      fetchAllCursorPages((cursor) =>
        apiParsed(cursorPage(DownloaderInstance), "/api/v1/downloader-instances", {
          params: { limit: 200, cursor },
          signal,
        }),
      ),
    select: (d) => new Map(d.items.map((i) => [i.id, i.name])),
  });
}

export const DOWNLOAD_STATUS_LABEL: Record<DownloadStatus, string> = {
  queued: "排队",
  submitting: "提交中",
  downloading: "下载中",
  paused: "已暂停",
  stalled: "无进展",
  completed: "下载完成",
  importing: "入库中",
  imported: "已入库",
  failed: "失败",
  removed: "已移除",
  missing: "下载器中缺失",
};

export const DOWNLOAD_STATUS_TONE: Record<DownloadStatus, "success" | "warning" | "destructive" | "neutral"> = {
  queued: "neutral",
  submitting: "neutral",
  downloading: "neutral",
  paused: "warning",
  stalled: "warning",
  completed: "success",
  importing: "neutral",
  imported: "success",
  failed: "destructive",
  removed: "neutral",
  missing: "destructive",
};

export const PAUSE_REASON_LABEL = {
  user: "手动暂停",
  threshold: "下载盘满暂停",
  policy: "策略暂停",
  agent: "智能体暂停",
} as const;

export const PLAN_STATUS_LABEL: Record<PlanStatus, string> = {
  draft: "待批准",
  reserved: "已预留空间",
  submitted: "已提交",
  completed: "已完成",
  cancelled: "已取消",
  failed: "失败",
  expired: "已过期",
};