feat(identity): lazy TMDB lookup and bounded identity pool (DEC-1)

RSS/list releases that match no subscription or local work no longer hit
TMDB or open a pending item; they go to the identity pool as `unmatched`.
TMDB is queried only on a local alias hit, a published new-title rule whose
prefilter passes, manual/Agent retry, search results, or when the new
setting identity.eagerTmdbLookup (default off) is on. Mirrors MoviePilot:
torrents are recognised only when matched to a subscription or searched,
and recognition failures are logged, not alerted.

- Pending items only for related releases (ambiguous after lookup, or
  related to a local work but unresolved); same source + normalized title
  merge into one decision ("来源「X」的 N 条资源待识别"), resolve/dismiss
  applies to the whole group, members detach as they get resolved.
- Pool governance: unmatched reviews capped (daily, 3x), title_alias
  insert trigger wakes similar entries, stale unmatched entries archived
  after identity.poolArchiveDays (30); review idempotency keys include the
  due time.
- Migration 0047_identity_pool: reason/outcome `unmatched`,
  identity_candidate.normalized_title (+trgm index), wake trigger, and
  cleanup of open identity_unresolved items with no related work
  (dismissed, resolution=moved_to_pool).
- Inbox: group by type + work/source with collapse, hide info-only items
  by default (minSeverity=warning), badge counts warning+ only; pool sheet
  gets manual TMDB/local-work assign and dismiss; settings card for the
  new identity settings.
- Runbook docs/runbook/identity.md.

Requires rebuild/restart (migration runs on start).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
rootandClaude Opus 5.5 committed 2026-09-29 15:05:39 +08:00
1 parent 524af64bec
commit 94fd48bff2
24 files changed
+1326 -153

No files matched your search

+8 -5
View File
@@ -15,10 +15,13 @@ import { getParsed, parseOrThrow } from "./library.ts";
export const decisionKeys = {
all: ["decisions"] as const,
list: (f: DecisionFilters) => ["decisions", "list", f] as const,
summary: (status?: DecisionStatus) => ["decisions", "summary", status ?? "open"] as const,
summary: (status?: DecisionStatus, minSeverity?: MinSeverity) =>
["decisions", "summary", status ?? "open", minSeverity ?? "info"] as const,
};
export type DecisionFilters = { status?: DecisionStatus; kind?: DecisionKind };
/** 只看不低于此级别的事项;收件箱缺省 warning(隐藏"仅信息"类) */
export type MinSeverity = "info" | "warning" | "critical";
export type DecisionFilters = { status?: DecisionStatus; kind?: DecisionKind; minSeverity?: MinSeverity };
/** /decisions/summary(合同 DecisionSummary) */
export { DecisionSummary };
@@ -37,10 +40,10 @@ export function useDecisions(filters: DecisionFilters, enabled = true) {
});
}
export function useDecisionSummary(status?: DecisionStatus) {
export function useDecisionSummary(status?: DecisionStatus, minSeverity?: MinSeverity) {
return useQuery({
queryKey: decisionKeys.summary(status),
queryFn: ({ signal }) => getParsed(DecisionSummary, "/decisions/summary", { status }, signal),
queryKey: decisionKeys.summary(status, minSeverity),
queryFn: ({ signal }) => getParsed(DecisionSummary, "/decisions/summary", { status, minSeverity }, signal),
});
}
@@ -12,6 +12,8 @@ import { useSse } from "~/lib/sse.ts";
import { cn } from "~/lib/utils.ts";
// 顶栏收件箱(IA-3):待处理不进侧栏,铃铛 + 未决角标;下拉按问题类型列最近事项,点开进待处理页。
// 角标只算需要你处理的事项(警告及以上):"仅信息"类(巡检报告、旧版本待处置等)不计入,在待处理页可展开查看。
// 身份类事项已按来源 + 标题合并,一条事项可能代表多条资源(标题里写明 N 条)。
const RECENT = 8;
const DOT = { info: "bg-muted-foreground/60", warning: "bg-warning", critical: "bg-destructive" } as const;
@@ -27,7 +29,7 @@ export function useLiveDecisions() {
void qc.invalidateQueries({ queryKey: decisionKeys.all });
}, 800);
});
return useDecisionSummary();
return useDecisionSummary(undefined, "warning");
}
export const inboxPath = (kind?: string) => (kind ? `/console/inbox?kind=${kind}` : "/console/inbox");
@@ -35,7 +37,7 @@ export const inboxPath = (kind?: string) => (kind ? `/console/inbox?kind=${kind}
export function InboxBell() {
const summary = useLiveDecisions();
const [open, setOpen] = useState(false);
const list = useDecisions({}, open);
const list = useDecisions({ minSeverity: "warning" }, open);
const navigate = useNavigate();
const total = summary.data?.total ?? 0;
@@ -1,21 +1,27 @@
import type { IdentityPoolItem, PoolCandidate } from "@umt/contracts";
import { ArrowRight, ExternalLink, LoaderCircle, RotateCw } from "lucide-react";
import { ArrowRight, BellOff, ExternalLink, LoaderCircle, RotateCw } from "lucide-react";
import { useId, useState } from "react";
import { Link } from "react-router";
import { toast } from "sonner";
import { useRetryPool } from "~/api/identity.ts";
import { useAssignPool, useDismissPool, useRetryPool } from "~/api/identity.ts";
import { DetailSection, DetailSheet } from "~/components/console/detail-sheet.tsx";
import { FormField } from "~/components/console/form-field.tsx";
import { JsonView } from "~/components/console/json-view.tsx";
import { KvList } from "~/components/console/kv-list.tsx";
import { consolePath } from "~/components/console/nav.ts";
import { EntityPicker, type PickedEntity } from "~/components/library/identity-entity-picker.tsx";
import { Button } from "~/components/ui/button.tsx";
import { Input } from "~/components/ui/input.tsx";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "~/components/ui/select.tsx";
import { errorMessage } from "~/lib/api.ts";
import { formatDateTime } from "~/lib/utils.ts";
import { EVIDENCE_LEVEL, POOL_REASON, POOL_STATUS } from "./labels.ts";
import { Chip, Tone } from "./parts.tsx";
// 待识别资源详情(只读):候选证据 + 重新识别。选候选、忽略在待处理里做(判定只在待处理与作品详情)。
// 待识别资源详情:候选证据 + 重新识别 + 手动指定。进了待处理的(与订阅相关的歧义 / 无结果)在待处理里选候选;
// 没进待处理的(unmatched:未命中订阅,惰性识别没查 TMDB)在这里手动指定 TMDB ID / 本地作品,或忽略。
/** 多个候选 / 待确认的资源开"待确认身份"事项;没有候选的(无结果、复查耗尽)开"待识别"事项 */
/** 与订阅 / 本地作品相关的歧义开"待确认身份"事项,相关却无结果开"待识别"事项(同来源同标题合并);unmatched 不进待处理 */
export function inInbox(item: Pick<IdentityPoolItem, "status" | "reason" | "candidates" | "decisionId">): boolean {
return item.status === "pending" && (item.decisionId !== null || hasCandidates(item));
}
@@ -85,6 +91,97 @@ function CandidateRow({ c, index }: { c: PoolCandidate; index: number }) {
);
}
/** 手动指定(复用 /identity-pool/{id}/assign,加人工锁)与忽略 */
function ManualAssign({ item }: { item: IdentityPoolItem }) {
const uid = useId();
const assign = useAssignPool();
const dismiss = useDismissPool();
const [tmdbType, setTmdbType] = useState<"movie" | "tv">(item.query.season != null ? "tv" : "movie");
const [tmdbId, setTmdbId] = useState("");
const [entity, setEntity] = useState<PickedEntity | null>(null);
const tmdbOk = /^\d{1,10}$/.test(tmdbId.trim());
const run = async (body: Parameters<typeof assign.mutateAsync>[0], ok: string) => {
try {
await assign.mutateAsync(body);
toast.success(ok);
} catch (err) {
toast.error(errorMessage(err, "指定失败"));
}
};
return (
<DetailSection title="手动指定">
<div className="grid gap-x-2 sm:grid-cols-[8rem_minmax(0,1fr)_auto] sm:items-end">
<FormField label="类型" htmlFor={`${uid}-type`}>
<Select value={tmdbType} onValueChange={(v) => setTmdbType(v as "movie" | "tv")}>
<SelectTrigger id={`${uid}-type`} className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="movie">电影</SelectItem>
<SelectItem value="tv">剧集</SelectItem>
</SelectContent>
</Select>
</FormField>
<FormField label="TMDB ID" htmlFor={`${uid}-tmdb`} hint="纯数字,如 872585">
<Input
id={`${uid}-tmdb`}
inputMode="numeric"
value={tmdbId}
onChange={(e) => setTmdbId(e.target.value)}
aria-invalid={tmdbId.trim() !== "" && !tmdbOk}
/>
</FormField>
<Button
variant="outline"
className="mb-4"
disabled={!tmdbOk || assign.isPending}
onClick={() =>
run(
{
id: item.id,
external: { provider: "tmdb", entityType: tmdbType, externalId: tmdbId.trim() },
lock: true,
},
"已按 TMDB ID 指定",
)
}
>
指定
</Button>
</div>
<div className="grid gap-x-2 sm:grid-cols-[minmax(0,1fr)_auto] sm:items-end">
<FormField label="或选本地作品">
<EntityPicker value={entity} onChange={setEntity} />
</FormField>
<Button
variant="outline"
className="mb-4"
disabled={!entity || assign.isPending}
onClick={() => entity && run({ id: item.id, mediaEntityId: entity.id, lock: true }, "已关联本地作品")}
>
关联
</Button>
</div>
<Button
variant="ghost"
size="sm"
disabled={dismiss.isPending}
onClick={async () => {
try {
await dismiss.mutateAsync({ id: item.id });
toast.success("已忽略");
} catch (err) {
toast.error(errorMessage(err, "操作失败"));
}
}}
>
<BellOff />
忽略此资源
</Button>
</DetailSection>
);
}
export function PoolSheet({ item, onClose }: { item: IdentityPoolItem | null; onClose: () => void }) {
const retry = useRetryPool();
if (!item) return null;
@@ -144,6 +241,8 @@ export function PoolSheet({ item, onClose }: { item: IdentityPoolItem | null; on
]}
/>
{item.status !== "resolved" && !queued ? <ManualAssign item={item} /> : null}
<DetailSection title={`候选(${item.candidates.length})`}>
{item.candidates.length ? (
<ul className="space-y-2">
@@ -152,7 +251,11 @@ export function PoolSheet({ item, onClose }: { item: IdentityPoolItem | null; on
))}
</ul>
) : (
<p className="text-caption text-muted-foreground">没有候选。有新证据时自动重试。</p>
<p className="text-caption text-muted-foreground">
{item.reason === "unmatched"
? "没有命中订阅或本地作品,未查询 TMDB。点「重新识别」会查一次 TMDB;新增相近别名时自动重试。"
: "没有候选。有新证据时自动重试。"}
</p>
)}
</DetailSection>
@@ -149,7 +149,7 @@ export function PoolTab() {
empty={{
icon: SearchX,
title: filtered ? "没有符合条件的待识别资源" : "没有待识别资源",
description: "证据不足或冲突的资源会出现在这里,有新证据时自动重试。",
description: "未命中订阅、证据不足或冲突的资源会出现在这里;新增相近别名时自动重试,也可手动指定。",
}}
hasMore={pool.hasNextPage}
onLoadMore={() => pool.fetchNextPage()}
@@ -164,6 +164,7 @@ export const POOL_REASON: Record<IdentityCandidateReason, ToneLabel> = {
no_match: { label: "没有匹配", tone: "neutral" },
proposed: { label: "待确认", tone: "warning" },
lookup_failed: { label: "查询失败", tone: "destructive" },
unmatched: { label: "未命中订阅", tone: "neutral" },
};
export const POOL_STATUS: Record<string, ToneLabel> = {
@@ -180,6 +180,39 @@ function ImageCacheStatus() {
);
}
// 身份识别(DEC-1 惰性识别,对照 MP:RSS / 列表资源只在匹配订阅或用户搜索时识别)
const IDENTITY_CARD: CardSpec = {
anchor: "identity",
title: "资源识别",
description:
"缺省只在资源命中订阅或本地作品别名、新作品收录规则前置条件通过、你手动识别或搜索时查 TMDB;其余进待识别池,不进待处理。",
fields: [
{
name: "identity.eagerTmdbLookup",
label: "每条新资源都查 TMDB",
kind: "switch",
hint: "旧行为。每条资源约 1–2 次搜索 + 命中时 1 次详情(识别缓存命中为 0);每小时 100 条的 RSS 约每天 2400–7200 次请求,站点独有的短剧 / 综艺多半查不到",
wide: true,
},
{
name: "identity.poolArchiveDays",
label: "待识别池归档(天)",
kind: "number",
hint: "未命中订阅的条目超过这么多天没有新证据就归档,仍可筛出并手动指定",
},
],
fromSettings: (s) => ({
"identity.eagerTmdbLookup": s.identity.eagerTmdbLookup,
"identity.poolArchiveDays": n(s.identity.poolArchiveDays),
}),
toPatch: (v) => ({
identity: {
eagerTmdbLookup: v["identity.eagerTmdbLookup"] === true,
poolArchiveDays: Number(v["identity.poolArchiveDays"]),
},
}),
};
export function MetadataSection() {
return (
<SettingsGate>
@@ -187,6 +220,7 @@ export function MetadataSection() {
<>
<SettingsCard section="metadata" spec={TMDB_CARD} settings={s} />
<SettingsCard section="metadata" spec={TMDB_CACHE_CARD} settings={s} />
<SettingsCard section="metadata" spec={IDENTITY_CARD} settings={s} />
<SettingsCard section="metadata" spec={IMAGES_CARD} settings={s} />
</>
)}
+90 -14
View File
@@ -1,6 +1,6 @@
import { useQueryClient } from "@tanstack/react-query";
import type { Decision, DecisionKind, DecisionOption, DecisionStatus } from "@umt/contracts";
import { BellOff, Bot, CheckCheck, ChevronRight, Inbox, Radio, RotateCw } from "lucide-react";
import { BellOff, Bot, CheckCheck, ChevronDown, ChevronRight, Inbox, Radio, RotateCw } from "lucide-react";
import { type ReactNode, useId, useMemo, useRef, useState } from "react";
import { Link, useSearchParams } from "react-router";
import { toast } from "sonner";
@@ -26,8 +26,10 @@ import { actorText } from "~/lib/labels.ts";
import { useSse, useSseStatus } from "~/lib/sse.ts";
import { formatDateTime } from "~/lib/utils.ts";
// 待处理(REQ §13.1):按作品与问题类型合并;每项给证据、建议、影响范围与预览;
// 待处理(REQ §13.1):按问题类型 + 作品 / 来源合并并可折叠;每项给证据、建议、影响范围与预览;
// 处理选项来自后端 decision.options;SSE 收到 decision.* 事件即刷新。
// 缺省只看需要你处理的事项(警告及以上),"仅信息"类在"级别"筛选里展开。身份类事项后端已按来源 + 标题合并,
// 卡片里列出组内资源,选候选 / 指定 / 忽略对整组生效。
const OPEN: DecisionStatus[] = ["open", "investigating", "awaiting_user"];
const STATUS_FILTER = [
@@ -36,9 +38,55 @@ const STATUS_FILTER = [
{ value: "expired", label: "已过期" },
];
const SEV_RANK = { info: 0, warning: 1, critical: 2 } as const;
const SEV_FILTER = [{ value: "all", label: "含仅信息" }];
/** 缺省展开的组数;其余折叠 */
const OPEN_GROUPS = 3;
/** 证据里约定俗成的字段(Agent/后端写入);其余原样放进"原始证据" */
const str = (v: unknown) => (typeof v === "string" && v.trim() ? v : null);
/** 身份类合并事项的来源分组(后端 evidence.group) */
function sourceGroupOf(d: Decision): { siteId: string; siteName: string | null } | null {
const g = d.evidence.group as { siteId?: unknown; siteName?: unknown } | undefined;
return g && typeof g.siteId === "string" ? { siteId: g.siteId, siteName: str(g.siteName) } : null;
}
/** 合并事项的组内资源 */
function GroupReleases({ d }: { d: Decision }) {
const list = Array.isArray(d.evidence.releases)
? (d.evidence.releases as { sourceReleaseId?: string; title?: string }[])
: [];
const count = typeof d.evidence.count === "number" ? d.evidence.count : list.length;
const [open, setOpen] = useState(false);
if (count <= 1) return null;
return (
<div className="mt-2">
<button
type="button"
onClick={() => setOpen((v) => !v)}
className="inline-flex cursor-pointer items-center gap-1 text-meta text-muted-foreground hover:text-foreground"
aria-expanded={open}
>
{open ? <ChevronDown className="h-3.5 w-3.5" /> : <ChevronRight className="h-3.5 w-3.5" />}
{open ? "收起" : "展开"}组内 {count} 条资源
</button>
{open ? (
<ul className="mt-1.5 space-y-1 border-l border-border/60 pl-3">
{list.map((r) => (
<li key={r.sourceReleaseId} className="font-mono text-meta break-all text-muted-foreground">
{r.title}
</li>
))}
{count > list.length ? (
<li className="text-meta text-muted-foreground">
另有 {count - list.length} 条,可在媒体概览 → 待识别按标题检索
</li>
) : null}
</ul>
) : null}
</div>
);
}
function entityOf(d: Decision): string | null {
const m = d.evidence.mediaEntityId;
if (typeof m === "string" && /^[0-9a-f-]{36}$/.test(m)) return m;
@@ -240,6 +288,7 @@ function DecisionCard({ d }: { d: Decision }) {
</div>
<h3 className="mt-2 text-body font-medium break-words text-foreground">{d.title}</h3>
{d.summary ? <p className="mt-1 text-caption break-words text-muted-foreground">{d.summary}</p> : null}
<GroupReleases d={d} />
<div className="mt-3">
<Evidence d={d} />
</div>
@@ -272,12 +321,20 @@ function DecisionCard({ d }: { d: Decision }) {
);
}
type Group = { key: string; entityId: string | null; kind: DecisionKind; items: Decision[] };
type Group = {
key: string;
entityId: string | null;
source: { siteId: string; siteName: string | null } | null;
kind: DecisionKind;
items: Decision[];
};
export default function InboxPage() {
const [sp, setSp] = useSearchParams();
const status = (sp.get("status") ?? "") as DecisionStatus | "";
const kind = (sp.get("kind") ?? "") as DecisionKind | "";
const sev = sp.get("sev") ?? "";
const minSeverity = sev === "all" ? undefined : "warning";
const set = (k: string, v: string) =>
setSp(
(prev) => {
@@ -289,8 +346,8 @@ export default function InboxPage() {
{ replace: true },
);
const summary = useDecisionSummary(status || undefined);
const list = useDecisions({ status: status || undefined, kind: kind || undefined });
const summary = useDecisionSummary(status || undefined, minSeverity);
const list = useDecisions({ status: status || undefined, kind: kind || undefined, minSeverity });
const rows = list.data?.pages.flatMap((p) => p.items);
// SSE:decision.created / decision.updated → 刷新(合并 500ms 内的多条事件)
@@ -324,13 +381,14 @@ export default function InboxPage() {
return [...m.entries()].sort((a, b) => SEV_RANK[b[1].sev] - SEV_RANK[a[1].sev] || b[1].count - a[1].count);
}, [summary.data]);
// 按作品 + 问题类型合并;组内按严重度、时间
// 按问题类型 + 作品 / 来源合并;组内按严重度、时间
const groups = useMemo(() => {
const m = new Map<string, Group>();
for (const d of rows ?? []) {
const entityId = entityOf(d);
const key = `${entityId ?? `subject:${d.subjectType ?? "none"}`}|${d.kind}`;
const g = m.get(key) ?? { key, entityId, kind: d.kind, items: [] };
const source = entityId ? null : sourceGroupOf(d);
const key = `${entityId ?? (source ? `site:${source.siteId}` : `subject:${d.subjectType ?? "none"}`)}|${d.kind}`;
const g = m.get(key) ?? { key, entityId, source, kind: d.kind, items: [] };
g.items.push(d);
m.set(key, g);
}
@@ -339,6 +397,9 @@ export default function InboxPage() {
}, [rows]);
const isOpenView = !status;
// 折叠状态:缺省前 OPEN_GROUPS 组展开;用户点过的组按用户的来
const [toggled, setToggled] = useState<Record<string, boolean>>({});
const isExpanded = (key: string, index: number) => toggled[key] ?? index < OPEN_GROUPS;
return (
<>
<PageHeader
@@ -388,7 +449,7 @@ export default function InboxPage() {
</div>
)}
<FilterBar onReset={status || kind ? () => setSp(new URLSearchParams(), { replace: true }) : undefined}>
<FilterBar onReset={status || kind || sev ? () => setSp(new URLSearchParams(), { replace: true }) : undefined}>
<FilterSelect
label="状态"
value={status}
@@ -397,6 +458,7 @@ export default function InboxPage() {
allLabel="未关闭"
/>
<FilterSelect label="问题类型" value={kind} onChange={(v) => set("kind", v)} options={opts(DECISION_KIND)} />
<FilterSelect label="级别" value={sev} onChange={(v) => set("sev", v)} options={SEV_FILTER} allLabel="需处理" />
</FilterBar>
{list.isPending ? (
@@ -413,15 +475,27 @@ export default function InboxPage() {
/>
) : (
<div className="space-y-4">
{groups.map((g) => {
{groups.map((g, index) => {
const title = g.entityId ? titles.get(g.entityId) : null;
const expanded = isExpanded(g.key, index);
const maxSev = g.items.reduce<keyof typeof SEV_RANK>(
(a, d) => (SEV_RANK[d.severity] > SEV_RANK[a] ? d.severity : a),
"info",
);
return (
<section key={g.key} className="pg-slab min-w-0 overflow-hidden rounded-xl">
<header className="flex flex-wrap items-center gap-2 border-b border-border/60 px-4 py-3 sm:px-5">
<header
className={`flex flex-wrap items-center gap-2 px-4 py-3 sm:px-5 ${expanded ? "border-b border-border/60" : ""}`}
>
<button
type="button"
onClick={() => setToggled((t) => ({ ...t, [g.key]: !expanded }))}
className="inline-flex cursor-pointer items-center text-muted-foreground hover:text-foreground"
aria-expanded={expanded}
aria-label={expanded ? "折叠" : "展开"}
>
{expanded ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
</button>
<StatusBadge tone={SEVERITY[maxSev].tone}>{DECISION_KIND[g.kind]}</StatusBadge>
{g.entityId ? (
<Link
@@ -430,6 +504,10 @@ export default function InboxPage() {
>
{title ?? "关联作品"}
</Link>
) : g.source ? (
<span className="min-w-0 truncate text-body font-semibold text-foreground">
来源「{g.source.siteName ?? "未知站点"}」
</span>
) : (
<span className="text-body font-semibold text-muted-foreground">
{g.kind === "identity_ambiguous" || g.kind === "identity_unresolved" ? "尚未归属作品" : "系统级"}
@@ -437,9 +515,7 @@ export default function InboxPage() {
)}
<span className="ml-auto text-meta text-muted-foreground">{g.items.length} 项</span>
</header>
{g.items.map((d) => (
<DecisionCard key={d.id} d={d} />
))}
{expanded ? g.items.map((d) => <DecisionCard key={d.id} d={d} />) : null}
</section>
);
})}