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

import { keepPreviousData, useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import {
  cursorPage,
  type EnrichApplyInput,
  EnrichApplyResult,
  type EnrichRequest,
  EnrichStats,
  ExternalIdentity,
  type IdentityCandidateReason,
  type IdentityCandidateStatus,
  IdentityPoolItem,
  IdentityRevisionList,
  type IdentityStatus,
  MetadataEnrichOutput,
  type ReleaseIdentityAssign,
  ReleaseIdentityResult,
  TaskAccepted,
  TitleAlias,
  type TitleAliasCreate,
} from "@umt/contracts";
import { api } from "~/lib/api.ts";
import { getParsed, parseOrThrow } from "./library.ts";

// 身份与元数据:待识别池、外部身份与修订历史、别名(REQ §7.2、§7.5)

export const identityKeys = {
  all: ["identity"] as const,
  pool: (f: PoolFilters) => ["identity", "pool", f] as const,
  identities: (f: IdentityFilters) => ["identity", "external", f] as const,
  revisions: (id: string) => ["identity", "revisions", id] as const,
  aliases: (f: AliasFilters) => ["identity", "aliases", f] as const,
  enrichStats: (days: number) => ["identity", "enrich-stats", days] as const,
};

export type PoolFilters = { status?: IdentityCandidateStatus; reason?: IdentityCandidateReason; q?: string };
export type IdentityFilters = { mediaEntityId?: string; provider?: string; status?: IdentityStatus };
export type AliasFilters = { mediaEntityId?: string; q?: string };

const PoolPage = cursorPage(IdentityPoolItem);
const IdentityPage = cursorPage(ExternalIdentity);
const AliasPage = cursorPage(TitleAlias);

export function useIdentityPool(filters: PoolFilters) {
  return useInfiniteQuery({
    queryKey: identityKeys.pool(filters),
    initialPageParam: undefined as string | undefined,
    queryFn: ({ pageParam, signal }) =>
      getParsed(PoolPage, "/identity-pool", { ...filters, cursor: pageParam, limit: 50 }, signal),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    placeholderData: keepPreviousData,
  });
}

export function useExternalIdentities(filters: IdentityFilters) {
  return useInfiniteQuery({
    queryKey: identityKeys.identities(filters),
    initialPageParam: undefined as string | undefined,
    queryFn: ({ pageParam, signal }) =>
      getParsed(IdentityPage, "/external-identities", { ...filters, cursor: pageParam, limit: 50 }, signal),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    placeholderData: keepPreviousData,
  });
}

export function useIdentityRevisions(id: string | undefined) {
  return useQuery({
    queryKey: identityKeys.revisions(id ?? ""),
    enabled: !!id,
    queryFn: async ({ signal }) =>
      (await getParsed(IdentityRevisionList, `/external-identities/${id}/revisions`, undefined, signal)).items,
  });
}

export function useAliases(filters: AliasFilters, enabled = true) {
  return useInfiniteQuery({
    queryKey: identityKeys.aliases(filters),
    enabled,
    initialPageParam: undefined as string | undefined,
    queryFn: ({ pageParam, signal }) =>
      getParsed(AliasPage, "/title-aliases", { ...filters, cursor: pageParam, limit: 50 }, signal),
    getNextPageParam: (last) => last.nextCursor ?? undefined,
    placeholderData: keepPreviousData,
  });
}

function useInvalidate() {
  const qc = useQueryClient();
  return () => {
    void qc.invalidateQueries({ queryKey: identityKeys.all });
    void qc.invalidateQueries({ queryKey: ["library"] });
    void qc.invalidateQueries({ queryKey: ["decisions"] });
  };
}

/** 指定候选 / 本地作品 / 外部身份(三选一),默认加人工锁 */
export function useAssignPool() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: ({ id, ...body }: ReleaseIdentityAssign & { id: string }) =>
      api
        .post<unknown>(`/identity-pool/${id}/assign`, body)
        .then((d) => parseOrThrow(ReleaseIdentityResult, d, "/identity-pool/assign")),
    onSuccess: done,
  });
}

export function useDismissPool() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: (v: { id: string; note?: string }) =>
      api.post<unknown>(`/identity-pool/${v.id}/dismiss`, { note: v.note }),
    onSuccess: done,
  });
}

export function useRetryPool() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: (id: string) =>
      api
        .post<unknown>(`/identity-pool/${id}/retry`)
        .then((d) => parseOrThrow(TaskAccepted, d, "/identity-pool/retry")),
    onSuccess: done,
  });
}

/** 外部身份修订(锁定/解锁/改状态),乐观并发 */
export function useUpdateIdentity() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: (v: {
      id: string;
      expectedRevision: number;
      locked?: boolean;
      status?: IdentityStatus;
      reason?: string;
    }) => {
      const { id, ...body } = v;
      return api
        .patch<unknown>(`/external-identities/${id}`, body)
        .then((d) => parseOrThrow(ExternalIdentity, d, "/external-identities"));
    },
    onSuccess: done,
  });
}

export function useCreateAlias() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: (body: TitleAliasCreate) =>
      api.post<unknown>("/title-aliases", body).then((d) => parseOrThrow(TitleAlias, d, "/title-aliases")),
    onSuccess: done,
  });
}

export function useDeleteAlias() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: (id: string) => api.del<unknown>(`/title-aliases/${id}`),
    onSuccess: done,
  });
}

/** 元数据补全命中率(最近 N 天,按来源类别;META-2) */
export function useEnrichStats(days = 30) {
  return useQuery({
    queryKey: identityKeys.enrichStats(days),
    queryFn: ({ signal }) => getParsed(EnrichStats, "/identity/enrich-stats", { days }, signal),
    staleTime: 60_000,
  });
}

/** 元数据补全建议(metadata.enrich;不改作品,同一标题 7 天内返回上次结果) */
export function useEnrichPool() {
  return useMutation({
    mutationFn: ({ id, ...body }: EnrichRequest & { id: string }) =>
      api
        .post<unknown>(`/identity-pool/${id}/enrich`, body)
        .then((d) => parseOrThrow(MetadataEnrichOutput, d, "/identity-pool/enrich")),
  });
}

/** 应用补全建议:建本地临时作品(或并入同名作品)并关联待识别资源 */
export function useApplyEnrich() {
  const done = useInvalidate();
  return useMutation({
    mutationFn: ({ id, ...body }: Partial<EnrichApplyInput> & { id: string; enrichmentId: string }) =>
      api
        .post<unknown>(`/identity-pool/${id}/enrich/apply`, body)
        .then((d) => parseOrThrow(EnrichApplyResult, d, "/identity-pool/enrich/apply")),
    onSuccess: done,
  });
}

/** 补全海报经服务端代理(只取该补全记录里白名单网页给出的图片) */
export const enrichPosterUrl = (enrichmentId: string) => `/api/v1/img/enrich/${enrichmentId}`;