feat(web): W3-2 library, subscriptions and rules, preferences, decisions inbox, identity and metadata

- library list (kind/status/search, cursor paging) and detail: paths and roots, external identity
  mapping with lock, field-level metadata sources and locks, slot cards with rejection reasons,
  content units (provisional flag), downloads with verification; remap/lock/refresh/merge actions
- subscriptions: list/create/update, slot rules editor (hard/soft/upgrade/completion),
  policy revision draft -> preview -> publish (grant warning) -> rollback
- preferences: tag CRUD, disable/enable, suppression records and lift, history timeline
- inbox: grouped by entity and kind, evidence/suggestion/impact/preview, resolve options, SSE refresh
- identity: pool assign/dismiss/retry, external identity revisions and lock, title alias management
- all responses validated against contracts zod schemas

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/web/app/api/identity.ts

@@ -0,0 +1,154 @@
+import { keepPreviousData, useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  cursorPage,
+  ExternalIdentity,
+  type IdentityCandidateReason,
+  type IdentityCandidateStatus,
+  IdentityPoolItem,
+  IdentityRevision,
+  type IdentityStatus,
+  type ReleaseIdentityAssign,
+  TitleAlias,
+  type TitleAliasCreate,
+} from "@umt/contracts";
+import { z } from "zod";
+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,
+};
+
+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);
+/** 服务端返回 { items }(无 nextCursor);兼容数组与分页两种形状 */
+const RevisionList = z.union([z.array(IdentityRevision), z.object({ items: z.array(IdentityRevision) })]);
+
+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 }) => {
+      const r = await getParsed(RevisionList, `/external-identities/${id}/revisions`, undefined, signal);
+      return Array.isArray(r) ? r : r.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),
+    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`),
+    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,
+  });
+}