feat(episode-mapping): 映射规则接口与模拟预览、待处理确认 / 忽略、作品页集数映射分区与订阅摘要

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cxwgnn2pbzQ7rXv3rq7fei

apps/web/app/api/episode-mapping.ts

@@ -0,0 +1,75 @@
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  EpisodeMappingPreview,
+  type EpisodeMappingPreviewInput,
+  type EpisodeMappingRuleCreate,
+  EpisodeMappingRuleList,
+  type EpisodeMappingRuleUpdate,
+  EpisodeMappingRuleWriteResult,
+} from "@umt/contracts";
+import { api } from "~/lib/api.ts";
+import { decisionKeys } from "./decisions.ts";
+import { getParsed, libraryKeys, parseOrThrow } from "./library.ts";
+
+// 集数映射:作品的规则列表 / 增改停删(写入后服务端按作品重算)/ 模拟预览(纯读)。
+
+export const episodeMappingKeys = {
+  all: ["episode-mapping"] as const,
+  rules: (entityId: string) => ["episode-mapping", "rules", entityId] as const,
+  preview: (entityId: string, input: EpisodeMappingPreviewInput) =>
+    ["episode-mapping", "preview", entityId, input] as const,
+};
+
+export function useEpisodeMappingRules(entityId: string | undefined) {
+  return useQuery({
+    queryKey: episodeMappingKeys.rules(entityId ?? ""),
+    enabled: !!entityId,
+    queryFn: ({ signal }) =>
+      getParsed(EpisodeMappingRuleList, `/media-entities/${entityId}/episode-mapping-rules`, undefined, signal),
+  });
+}
+
+export function useEpisodeMappingPreview(
+  entityId: string | null | undefined,
+  input: EpisodeMappingPreviewInput,
+  enabled = true,
+) {
+  return useQuery({
+    queryKey: episodeMappingKeys.preview(entityId ?? "", input),
+    enabled: !!entityId && enabled,
+    placeholderData: keepPreviousData,
+    queryFn: async () =>
+      parseOrThrow(
+        EpisodeMappingPreview,
+        await api.post<unknown>(`/media-entities/${entityId}/episode-mapping/preview`, input),
+        "/media-entities/{id}/episode-mapping/preview",
+      ),
+  });
+}
+
+type WriteVars =
+  | { op: "create"; entityId: string; body: EpisodeMappingRuleCreate }
+  | { op: "update"; id: string; body: EpisodeMappingRuleUpdate }
+  | { op: "delete"; id: string };
+
+/** 规则写入:成功后刷新规则、预览、待处理与作品详情(季集可能变了) */
+export function useEpisodeMappingWrite(entityId: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (v: WriteVars) => {
+      const data =
+        v.op === "create"
+          ? await api.post<unknown>(`/media-entities/${v.entityId}/episode-mapping-rules`, v.body)
+          : v.op === "update"
+            ? await api.patch<unknown>(`/episode-mapping-rules/${v.id}`, v.body)
+            : await api.del<unknown>(`/episode-mapping-rules/${v.id}`);
+      return parseOrThrow(EpisodeMappingRuleWriteResult, data, "/episode-mapping-rules");
+    },
+    onSuccess: () => {
+      void qc.invalidateQueries({ queryKey: episodeMappingKeys.all });
+      void qc.invalidateQueries({ queryKey: decisionKeys.all });
+      void qc.invalidateQueries({ queryKey: libraryKeys.detail(entityId) });
+      void qc.invalidateQueries({ queryKey: libraryKeys.entity(entityId) });
+    },
+  });
+}

apps/web/app/components/episode-mapping/decision.test.ts

@@ -0,0 +1,97 @@
+import type { Decision, EpisodeMappingPreview } from "@umt/contracts";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { EpisodeDecisionBody, episodeDecisionView, simulationText } from "./decision.tsx";
+
+const ENTITY = "7d3f7f5e-8a8c-4b8e-9f0a-1b2c3d4e5f60";
+const decision = (over: Partial<Decision> = {}): Decision =>
+  ({
+    id: "11111111-1111-4111-8111-111111111111",
+    kind: "episode_mapping",
+    status: "open",
+    severity: "warning",
+    title: "集数待确认：药屋少女的呢喃 第 1 季 · Lilith-Raws",
+    summary: "来源 S01E41：集数超出作品季表，也换算不出对应的季集（共 2 条资源）",
+    subjectType: "media_entity",
+    subjectId: ENTITY,
+    dedupeKey: `episode_mapping:${ENTITY}:1:lilith-raws`,
+    evidence: {
+      mediaEntityId: ENTITY,
+      season: 1,
+      releaseGroup: "Lilith-Raws",
+      count: 2,
+      releases: [
+        {
+          sourceReleaseId: "a",
+          title: "[Lilith-Raws] X - 40",
+          source: { season: 1, episodes: { start: 40, end: 40 } },
+        },
+        {
+          sourceReleaseId: "b",
+          title: "[Lilith-Raws] X - 41",
+          source: { season: 1, episodes: { start: 41, end: 41 } },
+        },
+      ],
+      suggestion: {
+        expression: "EP-30",
+        targetSeason: 2,
+        samples: [
+          {
+            source: { start: 40, end: 40 },
+            target: { season: 2, episode: 10 },
+            publishedAt: "x",
+            airDate: "2025-03-14",
+          },
+        ],
+      },
+    },
+    options: [
+      { key: "confirm_suggestion", label: "确认建议规则", description: "按 EP-30 换算到第 2 季" },
+      { key: "ignore_rule", label: "忽略并建忽略规则" },
+    ],
+    ...over,
+  }) as Decision;
+
+describe("待处理「集数待确认」", () => {
+  it("从证据取范围、来源季集、建议规则与可用操作", () => {
+    const v = episodeDecisionView(decision());
+    expect(v).toMatchObject({ entityId: ENTITY, season: 1, releaseGroup: "Lilith-Raws", count: 2 });
+    expect(v.releases.map((r) => r.source)).toEqual(["S01E40", "S01E41"]);
+    expect(v.suggestion?.expression).toBe("EP-30");
+    expect(v.confirm?.key).toBe("confirm_suggestion");
+    expect(v.ignoreRule?.key).toBe("ignore_rule");
+    const none = episodeDecisionView(decision({ options: [], evidence: { mediaEntityId: ENTITY, suggestion: null } }));
+    expect(none).toMatchObject({ confirm: null, ignoreRule: null, suggestion: null, season: null });
+  });
+
+  it("渲染来源季集、建议规则样本与模拟结果", () => {
+    const html = renderToStaticMarkup(
+      createElement(EpisodeDecisionBody, { view: episodeDecisionView(decision()), simulation: "套用后 2 条都对得上" }),
+    );
+    expect(html).toContain("第 1 季 · Lilith-Raws");
+    expect(html).toContain("S01E40");
+    expect(html).toContain("EP-30");
+    expect(html).toContain("第 2 季");
+    expect(html).toContain("S02E10");
+    expect(html).toContain("套用后 2 条都对得上");
+  });
+
+  it("没有建议时提示到作品页手动建", () => {
+    const html = renderToStaticMarkup(
+      createElement(EpisodeDecisionBody, {
+        view: episodeDecisionView(decision({ evidence: { mediaEntityId: ENTITY, suggestion: null } })),
+        simulation: null,
+      }),
+    );
+    expect(html).toContain("到作品页手动建");
+  });
+
+  it("模拟结果一句话", () => {
+    const p = (vals: string[]) =>
+      ({ items: vals.map((validation) => ({ validation })) }) as unknown as EpisodeMappingPreview;
+    expect(simulationText(p(["pass", "pass"]))).toBe("套用后 2 条都对得上");
+    expect(simulationText(p(["pass", "fail"]))).toBe("套用后 1 条对得上，1 条仍对不上");
+    expect(simulationText(p([]))).toBeNull();
+  });
+});

apps/web/app/components/episode-mapping/decision.tsx

@@ -0,0 +1,229 @@
+import type { Decision, DecisionOption, EpisodeMappingPreview, EpisodeResolutionView } from "@umt/contracts";
+import { BellOff, Check, PencilLine } from "lucide-react";
+import { useId, useState } from "react";
+import { Link } from "react-router";
+import { toast } from "sonner";
+import { useResolveDecision } from "~/api/decisions.ts";
+import { useEpisodeMappingPreview } from "~/api/episode-mapping.ts";
+import { ConfirmDialog } from "~/components/console/confirm-dialog.tsx";
+import { consolePath } from "~/components/console/nav.ts";
+import { Button } from "~/components/ui/button.tsx";
+import { Switch } from "~/components/ui/switch.tsx";
+import { errorMessage } from "~/lib/api.ts";
+import { episodeCode, mappingHref, scopeText, sourceText } from "./model.ts";
+
+// 待处理中心里的「集数待确认」(episode_mapping):来源季集、原因、建议规则与它的模拟结果;
+// 操作「确认」(建建议规则并重算)、「修改」(跳作品页集数映射并预填草稿)、「忽略」(可同时建忽略规则)。
+
+export const EPISODE_CONFIRM_KEY = "confirm_suggestion";
+export const EPISODE_IGNORE_RULE_KEY = "ignore_rule";
+
+interface Suggestion {
+  expression: string;
+  targetSeason: number;
+  samples: { source: { start: number; end: number }; target: { season: number; episode: number }; airDate: string }[];
+}
+
+export interface EpisodeDecisionView {
+  entityId: string | null;
+  season: number | null;
+  releaseGroup: string | null;
+  releases: { id: string; title: string; source: string }[];
+  count: number;
+  suggestion: Suggestion | null;
+  confirm: DecisionOption | null;
+  ignoreRule: DecisionOption | null;
+}
+
+const UUID = /^[0-9a-f-]{36}$/;
+
+/** 从事项证据里取界面要的字段(后端 writeEpisodeDecision 写入的结构) */
+export function episodeDecisionView(d: Decision): EpisodeDecisionView {
+  const e = d.evidence as Record<string, unknown>;
+  const entity = typeof e.mediaEntityId === "string" && UUID.test(e.mediaEntityId) ? e.mediaEntityId : null;
+  const releases = Array.isArray(e.releases)
+    ? (e.releases as { sourceReleaseId?: string; title?: string; source?: EpisodeResolutionView["source"] | null }[])
+        .filter((r) => r.sourceReleaseId)
+        .map((r) => ({
+          id: r.sourceReleaseId!,
+          title: r.title ?? "",
+          source: r.source ? sourceText({ source: r.source }) : "—",
+        }))
+    : [];
+  const s = e.suggestion as Suggestion | null | undefined;
+  return {
+    entityId: entity ?? (d.subjectType === "media_entity" ? d.subjectId : null),
+    season: typeof e.season === "number" ? e.season : null,
+    releaseGroup: typeof e.releaseGroup === "string" ? e.releaseGroup : null,
+    releases,
+    count: typeof e.count === "number" ? e.count : releases.length,
+    suggestion: s && typeof s.expression === "string" ? s : null,
+    confirm: d.options.find((o) => o.key === EPISODE_CONFIRM_KEY) ?? null,
+    ignoreRule: d.options.find((o) => o.key === EPISODE_IGNORE_RULE_KEY) ?? null,
+  };
+}
+
+/** 建议规则套用到同季同组近期资源的结果一句话 */
+export function simulationText(p: EpisodeMappingPreview | undefined): string | null {
+  if (!p) return null;
+  const total = p.items.length;
+  if (!total) return null;
+  const fail = p.items.filter((i) => i.validation === "fail").length;
+  return fail ? `套用后 ${total - fail} 条对得上，${fail} 条仍对不上` : `套用后 ${total} 条都对得上`;
+}
+
+/** 展示部分(纯渲染,单测直接渲染) */
+export function EpisodeDecisionBody({ view, simulation }: { view: EpisodeDecisionView; simulation: string | null }) {
+  const shown = view.releases.slice(-5);
+  return (
+    <dl className="grid gap-1.5 text-caption sm:grid-cols-[5rem_1fr]">
+      <dt className="text-muted-foreground">范围</dt>
+      <dd className="text-foreground">{scopeText(view.season, view.releaseGroup)}</dd>
+      <dt className="text-muted-foreground">来源季集</dt>
+      <dd className="min-w-0 text-foreground">
+        <ul className="space-y-0.5">
+          {shown.map((r) => (
+            <li key={r.id} className="break-all">
+              <span className="font-mono tabular-nums">{r.source}</span>
+              <span className="ml-2 text-meta text-muted-foreground">{r.title}</span>
+            </li>
+          ))}
+          {view.count > shown.length ? (
+            <li className="text-meta text-muted-foreground">另有 {view.count - shown.length} 条</li>
+          ) : null}
+        </ul>
+      </dd>
+      <dt className="text-muted-foreground">建议规则</dt>
+      <dd className="min-w-0 text-foreground">
+        {view.suggestion ? (
+          <>
+            <span className="font-mono">{view.suggestion.expression}</span> → 第 {view.suggestion.targetSeason} 季
+            <ul className="mt-0.5 space-y-0.5 text-meta text-muted-foreground">
+              {view.suggestion.samples.slice(0, 3).map((s) => (
+                <li key={`${s.source.start}-${s.target.episode}`} className="font-mono tabular-nums">
+                  E{String(s.source.start).padStart(2, "0")} →{" "}
+                  {episodeCode(s.target.season, { start: s.target.episode, end: s.target.episode })}
+                  （播出 {s.airDate}）
+                </li>
+              ))}
+            </ul>
+            {simulation ? <div className="mt-0.5 text-meta text-muted-foreground">{simulation}</div> : null}
+          </>
+        ) : (
+          <span className="text-muted-foreground">样本不够推出唯一的规则，到作品页手动建</span>
+        )}
+      </dd>
+    </dl>
+  );
+}
+
+function IgnoreButton({ d, view }: { d: Decision; view: EpisodeDecisionView }) {
+  const resolve = useResolveDecision();
+  const id = useId();
+  const [withRule, setWithRule] = useState(false);
+  return (
+    <ConfirmDialog
+      trigger={
+        <Button variant="ghost" size="sm">
+          <BellOff />
+          忽略
+        </Button>
+      }
+      title="忽略这条事项？"
+      description="只关闭提醒，这些资源仍是集数待确认，不会下载和整理；同组出现新的待确认资源时会重新提出。"
+      confirmLabel="忽略"
+      onConfirm={() =>
+        resolve
+          .mutateAsync(
+            withRule && view.ignoreRule ? { id: d.id, optionKey: view.ignoreRule.key } : { id: d.id, dismiss: true },
+          )
+          .then(
+            () => toast.success(withRule ? "已忽略，并建了忽略规则" : "已忽略"),
+            (err) => {
+              toast.error(errorMessage(err, "操作失败"));
+              throw err;
+            },
+          )
+      }
+    >
+      {view.ignoreRule ? (
+        <label htmlFor={id} className="flex items-center gap-2 text-caption text-foreground">
+          <Switch id={id} checked={withRule} onCheckedChange={setWithRule} />
+          同时建「忽略」规则：{scopeText(view.season, view.releaseGroup)}的资源以后不参与集数解析
+        </label>
+      ) : null}
+    </ConfirmDialog>
+  );
+}
+
+/** 集数待确认事项的证据与操作 */
+export function EpisodeDecision({ d, open }: { d: Decision; open: boolean }) {
+  const view = episodeDecisionView(d);
+  const resolve = useResolveDecision();
+  const sug = view.suggestion;
+  const preview = useEpisodeMappingPreview(
+    view.entityId,
+    sug
+      ? {
+          season: view.season,
+          releaseGroup: view.releaseGroup,
+          draft: {
+            season: view.season,
+            releaseGroup: view.releaseGroup,
+            kind: "expression",
+            expression: sug.expression,
+            targetSeason: sug.targetSeason,
+          },
+          limit: 50,
+        }
+      : {},
+    open && !!sug,
+  );
+  const modifyHref = view.entityId
+    ? mappingHref(consolePath("library", view.entityId), {
+        season: view.season,
+        releaseGroup: view.releaseGroup,
+        ...(sug ? { expression: sug.expression, targetSeason: sug.targetSeason } : {}),
+      })
+    : null;
+  return (
+    <div className="space-y-3">
+      <EpisodeDecisionBody view={view} simulation={sug ? simulationText(preview.data) : null} />
+      {open ? (
+        <div className="flex flex-wrap items-center gap-2">
+          {view.confirm ? (
+            <ConfirmDialog
+              trigger={
+                <Button size="sm">
+                  <Check />
+                  确认
+                </Button>
+              }
+              title="按建议规则处理？"
+              description={`${view.confirm.description ?? ""}。规则在作品页的集数映射里可以再改。`}
+              confirmLabel="确认"
+              onConfirm={() =>
+                resolve.mutateAsync({ id: d.id, optionKey: view.confirm!.key }).then(
+                  () => toast.success("已建规则并重算"),
+                  (err) => {
+                    toast.error(errorMessage(err, "处理失败"));
+                    throw err;
+                  },
+                )
+              }
+            />
+          ) : null}
+          {modifyHref ? (
+            <Button asChild variant="outline" size="sm">
+              <Link to={modifyHref}>
+                <PencilLine />
+                修改
+              </Link>
+            </Button>
+          ) : null}
+          <IgnoreButton d={d} view={view} />
+        </div>
+      ) : null}
+    </div>
+  );
+}

apps/web/app/components/episode-mapping/mapping-panel.tsx

@@ -0,0 +1,451 @@
+import type {
+  EpisodeMappingPreview,
+  EpisodeMappingPreviewInput,
+  EpisodeMappingRuleRow,
+  EpisodeMappingRuleSpec,
+  EpisodeSpecialKind,
+  EpisodeSuggestion,
+} from "@umt/contracts";
+import { Pause, PencilLine, Play, Plus, Trash2, Wand2 } from "lucide-react";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { useLocation, useSearchParams } from "react-router";
+import { toast } from "sonner";
+import { useEpisodeMappingPreview, useEpisodeMappingRules, useEpisodeMappingWrite } from "~/api/episode-mapping.ts";
+import { ConfirmDialog } from "~/components/console/confirm-dialog.tsx";
+import { ErrorState, LoadingState } from "~/components/console/empty-state.tsx";
+import { FormField } from "~/components/console/form-field.tsx";
+import { StatusBadge } from "~/components/console/status-badge.tsx";
+import { Chip, Panel } from "~/components/library/parts.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 { Textarea } from "~/components/ui/textarea.tsx";
+import { errorMessage } from "~/lib/api.ts";
+import { actorText } from "~/lib/labels.ts";
+import {
+  disabledReasonText,
+  draftFromSearch,
+  draftOfRule,
+  EMPTY_DRAFT,
+  groupMethodsText,
+  MAPPING_ANCHOR,
+  RULE_KIND_LABEL,
+  type RuleDraft,
+  reresolveToast,
+  ruleText,
+  SPECIAL_LABEL,
+  scopeText,
+  specOfDraft,
+} from "./model.ts";
+import { PreviewTable } from "./preview-table.tsx";
+
+// 作品页「集数映射」分区(批次 4):季表摘要、规则列表(增改停删)、草稿规则边改边预览、应用后提示重算了多少条。
+
+/** 草稿改动后等这么久再预览 */
+const PREVIEW_DEBOUNCE_MS = 400;
+
+function useDebounced<T>(value: T, ms: number): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+function SeasonSummary({ p }: { p: EpisodeMappingPreview["seasons"] }) {
+  const main = p.seasons.filter((s) => s.season >= 1);
+  if (!main.length) return <p className="text-caption text-muted-foreground">还没有季表，刷新元数据后出现。</p>;
+  return (
+    <div className="flex flex-wrap items-center gap-1.5">
+      {main.map((s) => (
+        <Chip key={s.season}>
+          第 {s.season} 季 · {s.total != null ? `${s.total} 集` : "总集数未知"}
+          {s.season === p.latestSeason ? " · 最新" : ""}
+        </Chip>
+      ))}
+      <span className="text-meta text-muted-foreground">{p.ended ? "已完结" : "未完结"}</span>
+    </div>
+  );
+}
+
+function RuleRow({
+  rule,
+  editing,
+  onEdit,
+  write,
+}: {
+  rule: EpisodeMappingRuleRow;
+  editing: boolean;
+  onEdit: () => void;
+  write: ReturnType<typeof useEpisodeMappingWrite>;
+}) {
+  const reason = disabledReasonText(rule);
+  const run = (vars: Parameters<typeof write.mutateAsync>[0], verb: string) =>
+    write.mutateAsync(vars).then(
+      (r) => toast.success(reresolveToast(r.reresolve, verb)),
+      (e) => {
+        toast.error(errorMessage(e));
+        throw e;
+      },
+    );
+  return (
+    <li className="flex flex-wrap items-start gap-x-3 gap-y-1.5 border-t border-border/60 py-2.5 first:border-t-0">
+      <div className="min-w-0 flex-1">
+        <div className="flex flex-wrap items-center gap-2">
+          <span className="text-caption font-medium text-foreground">{scopeText(rule.season, rule.releaseGroup)}</span>
+          <StatusBadge tone={rule.status === "active" ? "success" : "neutral"}>
+            {rule.status === "active" ? "启用" : "停用"}
+          </StatusBadge>
+          {editing ? <span className="text-meta text-muted-foreground">修改中</span> : null}
+        </div>
+        <div className="mt-0.5 text-meta text-muted-foreground">
+          {RULE_KIND_LABEL[rule.kind]}：<span className="font-mono text-foreground">{ruleText(rule)}</span>
+          {" · "}
+          {actorText(rule.createdById ? `${rule.createdByType}:${rule.createdById}` : rule.createdByType)}
+        </div>
+        {reason ? <div className="mt-0.5 text-meta text-muted-foreground">{reason}</div> : null}
+      </div>
+      <div className="flex flex-wrap items-center gap-1.5">
+        <Button variant="outline" size="sm" onClick={onEdit}>
+          <PencilLine />
+          修改
+        </Button>
+        {rule.status === "active" ? (
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={write.isPending}
+            onClick={() =>
+              void run({ op: "update", id: rule.id, body: { status: "disabled" } }, "已停用").catch(() => {})
+            }
+          >
+            <Pause />
+            停用
+          </Button>
+        ) : (
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={write.isPending}
+            onClick={() =>
+              void run({ op: "update", id: rule.id, body: { status: "active" } }, "已启用").catch(() => {})
+            }
+          >
+            <Play />
+            启用
+          </Button>
+        )}
+        <ConfirmDialog
+          trigger={
+            <Button variant="ghost" size="sm" aria-label="删除规则">
+              <Trash2 />
+            </Button>
+          }
+          title="删除这条规则？"
+          description={`删除后按作品重算：「${scopeText(rule.season, rule.releaseGroup)}」的资源回到自动判定。不能恢复。`}
+          confirmLabel="删除"
+          destructive
+          onConfirm={() => run({ op: "delete", id: rule.id }, "已删除")}
+        />
+      </div>
+    </li>
+  );
+}
+
+function DraftEditor({
+  draft,
+  onChange,
+  error,
+  groups,
+}: {
+  draft: RuleDraft;
+  onChange: (d: RuleDraft) => void;
+  error: string | null;
+  groups: string[];
+}) {
+  const id = useId();
+  const f = (k: string) => `${id}-${k}`;
+  const set = (patch: Partial<RuleDraft>) => onChange({ ...draft, ...patch });
+  return (
+    <div className="grid gap-x-3 sm:grid-cols-2 lg:grid-cols-4">
+      <FormField label="来源季" htmlFor={f("season")} hint="空着 = 任意季">
+        <Input
+          id={f("season")}
+          inputMode="numeric"
+          value={draft.season}
+          onChange={(e) => set({ season: e.target.value })}
+        />
+      </FormField>
+      <FormField label="发布组" htmlFor={f("group")} hint="空着 = 任意发布组">
+        <Input
+          id={f("group")}
+          list={f("groups")}
+          value={draft.releaseGroup}
+          onChange={(e) => set({ releaseGroup: e.target.value })}
+        />
+        <datalist id={f("groups")}>
+          {groups.map((g) => (
+            <option key={g} value={g} />
+          ))}
+        </datalist>
+      </FormField>
+      <FormField label="类型" htmlFor={f("kind")}>
+        <Select value={draft.kind} onValueChange={(v) => set({ kind: v as RuleDraft["kind"] })}>
+          <SelectTrigger id={f("kind")} className="w-full">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {(Object.keys(RULE_KIND_LABEL) as RuleDraft["kind"][]).map((k) => (
+              <SelectItem key={k} value={k}>
+                {RULE_KIND_LABEL[k]}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FormField>
+      {draft.kind === "expression" ? (
+        <FormField label="目标季" htmlFor={f("target")} hint="空着 = 来源季">
+          <Input
+            id={f("target")}
+            inputMode="numeric"
+            value={draft.targetSeason}
+            onChange={(e) => set({ targetSeason: e.target.value })}
+          />
+        </FormField>
+      ) : draft.kind === "special" ? (
+        <FormField label="映射为" htmlFor={f("special")}>
+          <Select value={draft.special} onValueChange={(v) => set({ special: v as EpisodeSpecialKind })}>
+            <SelectTrigger id={f("special")} className="w-full">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {(Object.keys(SPECIAL_LABEL) as EpisodeSpecialKind[]).map((k) => (
+                <SelectItem key={k} value={k}>
+                  {SPECIAL_LABEL[k]}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </FormField>
+      ) : (
+        <div />
+      )}
+      {draft.kind === "expression" ? (
+        <FormField
+          label="偏移表达式"
+          htmlFor={f("expr")}
+          className="sm:col-span-2 lg:col-span-4"
+          error={error}
+          hint="EP 是来源集号：EP-12 表示减 12，EP*2-1 表示双集拆分"
+        >
+          <Input
+            id={f("expr")}
+            className="font-mono"
+            value={draft.expression}
+            onChange={(e) => set({ expression: e.target.value })}
+            aria-invalid={!!error}
+          />
+        </FormField>
+      ) : draft.kind === "table" ? (
+        <FormField
+          label="对照表"
+          htmlFor={f("table")}
+          className="sm:col-span-2 lg:col-span-4"
+          error={error}
+          hint="每行一条：26=S02E01，区间写 27-28=S02E02"
+        >
+          <Textarea
+            id={f("table")}
+            className="font-mono"
+            rows={4}
+            value={draft.table}
+            onChange={(e) => set({ table: e.target.value })}
+            aria-invalid={!!error}
+          />
+        </FormField>
+      ) : error ? (
+        <p className="text-meta text-destructive sm:col-span-2 lg:col-span-4">{error}</p>
+      ) : null}
+    </div>
+  );
+}
+
+function GroupStats({
+  groups,
+  onUseSuggestion,
+}: {
+  groups: EpisodeMappingPreview["groups"];
+  onUseSuggestion: (s: EpisodeSuggestion) => void;
+}) {
+  if (!groups.length) return null;
+  return (
+    <ul className="space-y-1.5">
+      {groups.map((g) => (
+        <li key={g.releaseGroup ?? "-"} className="flex flex-wrap items-center gap-x-3 gap-y-1 text-caption">
+          <span className="text-foreground">{groupMethodsText(g)}</span>
+          {g.pending ? <StatusBadge tone="warning">待确认 {g.pending} 条</StatusBadge> : null}
+          {g.suggestion ? (
+            <Button variant="ghost" size="sm" onClick={() => onUseSuggestion(g.suggestion!)}>
+              <Wand2 />
+              试试建议 {g.suggestion.expression} → 第 {g.suggestion.targetSeason} 季
+            </Button>
+          ) : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function EpisodeMappingPanel({ entityId }: { entityId: string }) {
+  const [sp] = useSearchParams();
+  const location = useLocation();
+  const rules = useEpisodeMappingRules(entityId);
+  const write = useEpisodeMappingWrite(entityId);
+  const [draft, setDraft] = useState<RuleDraft | null>(() => draftFromSearch(sp));
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const ref = useRef<HTMLDivElement>(null);
+
+  // 从待处理「修改」跳来:预填草稿并滚到这里
+  useEffect(() => {
+    const d = draftFromSearch(sp);
+    if (d) {
+      setDraft(d);
+      setEditingId(null);
+    }
+    if (location.hash === `#${MAPPING_ANCHOR}`) ref.current?.scrollIntoView({ block: "start" });
+  }, [sp, location.hash]);
+
+  const parsed = useMemo(() => (draft ? specOfDraft(draft) : { spec: null, error: null }), [draft]);
+  const input: EpisodeMappingPreviewInput = useMemo(() => {
+    const spec = parsed.spec;
+    if (!draft) return {};
+    return {
+      ...(spec ? { draft: spec, season: spec.season ?? null, releaseGroup: spec.releaseGroup ?? null } : {}),
+      ...(editingId ? { replaceRuleId: editingId } : {}),
+    };
+  }, [draft, parsed.spec, editingId]);
+  const debounced = useDebounced(input, PREVIEW_DEBOUNCE_MS);
+  const preview = useEpisodeMappingPreview(entityId, debounced);
+  const groupNames = useMemo(
+    () => (preview.data?.groups ?? []).map((g) => g.releaseGroup).filter((g): g is string => !!g),
+    [preview.data],
+  );
+
+  const startNew = () => {
+    setEditingId(null);
+    setDraft({ ...EMPTY_DRAFT });
+  };
+  const cancel = () => {
+    setDraft(null);
+    setEditingId(null);
+  };
+  const apply = (spec: EpisodeMappingRuleSpec) =>
+    write
+      .mutateAsync(editingId ? { op: "update", id: editingId, body: spec } : { op: "create", entityId, body: spec })
+      .then(
+        (r) => {
+          toast.success(reresolveToast(r.reresolve));
+          cancel();
+        },
+        (e) => toast.error(errorMessage(e, "应用失败")),
+      );
+  const adoptSuggestion = (s: EpisodeSuggestion) => {
+    setEditingId(null);
+    setDraft({
+      ...EMPTY_DRAFT,
+      season: s.season != null ? String(s.season) : "",
+      releaseGroup: s.releaseGroup ?? "",
+      expression: s.expression,
+      targetSeason: String(s.targetSeason),
+    });
+  };
+
+  const list = rules.data?.items ?? [];
+  return (
+    <div id={MAPPING_ANCHOR} ref={ref} className="scroll-mt-4">
+      <Panel
+        title="集数映射"
+        description="发布者写的季集对不上作品季表时，按规则换成媒体库用的季集"
+        actions={
+          draft ? null : (
+            <Button variant="outline" size="sm" onClick={startNew}>
+              <Plus />
+              新建规则
+            </Button>
+          )
+        }
+        bodyClassName="space-y-4"
+      >
+        {preview.data ? <SeasonSummary p={preview.data.seasons} /> : null}
+
+        {rules.isPending ? (
+          <LoadingState rows={2} />
+        ) : rules.isError ? (
+          <ErrorState plain error={rules.error} onRetry={() => rules.refetch()} />
+        ) : list.length ? (
+          <ul>
+            {list.map((r) => (
+              <RuleRow
+                key={r.id}
+                rule={r}
+                editing={editingId === r.id}
+                write={write}
+                onEdit={() => {
+                  setEditingId(r.id);
+                  setDraft(draftOfRule(r));
+                }}
+              />
+            ))}
+          </ul>
+        ) : (
+          <p className="text-caption text-muted-foreground">
+            还没有规则。资源的集数先按原号、绝对集号和播出日期自动判定，对不上的进待处理。
+          </p>
+        )}
+
+        {draft ? (
+          <div className="rounded-xl border border-border/60 px-4 pt-3 pb-2">
+            <div className="mb-2 text-caption font-medium text-foreground">{editingId ? "修改规则" : "新建规则"}</div>
+            <DraftEditor draft={draft} onChange={setDraft} error={parsed.error} groups={groupNames} />
+            <div className="flex flex-wrap items-center gap-2 pb-1">
+              <Button
+                size="sm"
+                disabled={!parsed.spec || write.isPending}
+                onClick={() => parsed.spec && void apply(parsed.spec)}
+              >
+                应用
+              </Button>
+              <Button variant="outline" size="sm" onClick={cancel}>
+                取消
+              </Button>
+              {preview.data && parsed.spec ? (
+                <span className="text-meta text-muted-foreground">预览里 {preview.data.changed} 条会变化</span>
+              ) : null}
+            </div>
+          </div>
+        ) : null}
+
+        {preview.data ? <GroupStats groups={preview.data.groups} onUseSuggestion={adoptSuggestion} /> : null}
+      </Panel>
+      <Panel
+        className="mt-3"
+        title={draft ? "模拟预览" : "近期资源"}
+        description={draft ? "按草稿规则试算，不会保存；应用后才按作品重算" : "最近 100 条已绑定资源按当前规则的判定"}
+        bodyClassName="p-0 sm:p-0"
+      >
+        {preview.isPending ? (
+          <div className="p-4">
+            <LoadingState rows={3} />
+          </div>
+        ) : preview.isError ? (
+          <div className="p-4">
+            <ErrorState plain error={preview.error} onRetry={() => preview.refetch()} />
+          </div>
+        ) : (
+          <PreviewTable items={preview.data.items} hasDraft={!!input.draft} />
+        )}
+      </Panel>
+    </div>
+  );
+}

apps/web/app/components/episode-mapping/model.test.ts

@@ -0,0 +1,169 @@
+import type { EpisodeMappingPreview, EpisodeMappingRuleRow } from "@umt/contracts";
+import { describe, expect, it } from "vitest";
+import { EXCLUDE_REASON } from "../organize-wizard/model.ts";
+import {
+  absoluteGroups,
+  canonicalText,
+  disabledReasonText,
+  draftFromSearch,
+  draftOfRule,
+  EMPTY_DRAFT,
+  groupMethodsText,
+  METHOD_LABEL,
+  mappingHref,
+  methodText,
+  parseTable,
+  reresolveToast,
+  ruleText,
+  sourceText,
+  specOfDraft,
+} from "./model.ts";
+
+describe("集数映射文案", () => {
+  it("方式名称给人话,覆盖全部方式", () => {
+    expect(METHOD_LABEL).toEqual({
+      raw: "原号",
+      rule: "按规则",
+      absolute_in_season: "季内绝对集号",
+      absolute_cross_season: "跨季绝对集号",
+      air_date: "按播出日期",
+      unverified: "元数据未覆盖，先按原号",
+      unresolved: "待确认",
+      skipped: "不适用",
+    });
+    expect(methodText({ method: "rule", special: "ignore" })).toBe("按规则：忽略");
+    expect(methodText(null)).toBe("未解析");
+  });
+
+  it("季集写法:原始 / 规范 / 特别篇 / 播出日期", () => {
+    expect(sourceText({ source: { season: 1, episodes: { start: 25, end: 25 } } })).toBe("S01E25");
+    expect(sourceText({ source: { episodes: { start: 13, end: 14 } } })).toBe("E13-E14");
+    expect(sourceText({ source: { airDate: "20250314" } })).toBe("2025-03-14");
+    expect(
+      canonicalText({ method: "absolute_cross_season", canonical: { season: 2, episodes: { start: 1, end: 1 } } }),
+    ).toBe("S02E01");
+    expect(canonicalText({ method: "rule", canonical: null, special: "extra" })).toBe("花絮");
+    expect(canonicalText({ method: "unresolved", canonical: null })).toBe("—");
+  });
+
+  it("整理向导的排除原因有「集数待确认」与特典花絮", () => {
+    expect(EXCLUDE_REASON.episode_unresolved).toBe("集数待确认");
+    expect(EXCLUDE_REASON.special_extra).toBeTruthy();
+  });
+
+  it("停用原因:手动 / 规则失效", () => {
+    const rule = { status: "disabled", disabledReason: JSON.stringify({ manual: true }) } as EpisodeMappingRuleRow;
+    expect(disabledReasonText(rule)).toBe("手动停用");
+    expect(
+      disabledReasonText({
+        ...rule,
+        disabledReason: JSON.stringify({ source: { season: 2, episodes: { start: 30, end: 30 } }, evidence: [] }),
+      }),
+    ).toBe("规则算出的集数对不上季表（来源 S02E30），已自动停用");
+    expect(disabledReasonText({ ...rule, status: "active" })).toBeNull();
+  });
+});
+
+describe("对照表与草稿", () => {
+  it("对照表文本解析与回写", () => {
+    const t = parseTable("26=S02E01\n27-28 = s2e2\n");
+    expect(t.error).toBeNull();
+    expect(t.entries).toEqual([
+      { from: { start: 26, end: 26 }, to: { season: 2, episode: 1 } },
+      { from: { start: 27, end: 28 }, to: { season: 2, episode: 2 } },
+    ]);
+    expect(ruleText({ kind: "table", tableEntries: t.entries })).toBe("26=S02E01 等 2 行");
+    expect(parseTable("26->").error).toContain("第 1 行");
+    expect(parseTable("28-27=S02E01").error).toContain("写反");
+  });
+
+  it("草稿 → 规则内容:不完整时给错误,不发预览", () => {
+    expect(specOfDraft({ ...EMPTY_DRAFT, expression: "" }).error).toContain("偏移表达式");
+    expect(specOfDraft({ ...EMPTY_DRAFT, season: "x", expression: "EP-12" }).error).toContain("来源季");
+    expect(specOfDraft({ ...EMPTY_DRAFT, season: "2", releaseGroup: " ANi ", expression: "EP-12" }).spec).toEqual({
+      season: 2,
+      releaseGroup: "ANi",
+      kind: "expression",
+      expression: "EP-12",
+      targetSeason: null,
+    });
+    expect(specOfDraft({ ...EMPTY_DRAFT, kind: "special", special: "extra" }).spec).toMatchObject({
+      kind: "special",
+      special: "extra",
+      season: null,
+      releaseGroup: null,
+    });
+  });
+
+  it("规则 → 草稿 → 规则内容 保持一致", () => {
+    const row = {
+      season: 1,
+      releaseGroup: "Lilith-Raws",
+      kind: "expression",
+      expression: "EP-30",
+      targetSeason: 2,
+      tableEntries: null,
+      special: null,
+    } as EpisodeMappingRuleRow;
+    expect(specOfDraft(draftOfRule(row)).spec).toEqual({
+      season: 1,
+      releaseGroup: "Lilith-Raws",
+      kind: "expression",
+      expression: "EP-30",
+      targetSeason: 2,
+    });
+  });
+
+  it("待处理「修改」的跳转地址能读回预填草稿", () => {
+    const href = mappingHref("/console/library/x", {
+      season: 1,
+      releaseGroup: "ANi",
+      expression: "EP-12",
+      targetSeason: 2,
+    });
+    expect(href).toBe("/console/library/x?mapSeason=1&mapGroup=ANi&mapExpr=EP-12&mapTarget=2#episode-mapping");
+    const sp = new URLSearchParams(href.slice(href.indexOf("?") + 1, href.indexOf("#")));
+    expect(draftFromSearch(sp)).toMatchObject({
+      season: "1",
+      releaseGroup: "ANi",
+      expression: "EP-12",
+      targetSeason: "2",
+    });
+    expect(draftFromSearch(new URLSearchParams())).toBeNull();
+  });
+});
+
+describe("按发布组统计", () => {
+  const preview = {
+    groups: [
+      {
+        releaseGroup: "ANi",
+        total: 5,
+        pending: 0,
+        suggestion: null,
+        methods: [
+          { method: "raw", count: 1 },
+          { method: "absolute_cross_season", count: 4 },
+        ],
+      },
+      { releaseGroup: null, total: 1, pending: 1, suggestion: null, methods: [{ method: "unresolved", count: 1 }] },
+    ],
+  } as unknown as EpisodeMappingPreview;
+  it("一句话统计按数量排序", () => {
+    expect(groupMethodsText(preview.groups[0]!)).toBe("ANi：跨季绝对集号 4、原号 1");
+    expect(groupMethodsText(preview.groups[1]!)).toBe("未知发布组：待确认 1");
+  });
+  it("找出用绝对集号的发布组", () => {
+    expect(absoluteGroups(preview)).toEqual(["ANi"]);
+    expect(absoluteGroups(undefined)).toEqual([]);
+  });
+});
+
+describe("应用后的提示", () => {
+  it("只列非零项", () => {
+    expect(reresolveToast({ releases: 12, changed: 2, resolved: 2 })).toBe(
+      "已应用：重算 12 条资源，2 条有变化，2 条待确认已解决",
+    );
+    expect(reresolveToast({ releases: 3, changed: 0, resolved: 0 }, "已停用")).toBe("已停用：重算 3 条资源");
+  });
+});

apps/web/app/components/episode-mapping/model.ts

@@ -0,0 +1,264 @@
+import type {
+  EpisodeMappingPreview,
+  EpisodeMappingRuleRow,
+  EpisodeMappingRuleSpec,
+  EpisodeMappingRuleWriteResult,
+  EpisodeMappingTableEntry,
+  EpisodeResolutionMethod,
+  EpisodeResolutionView,
+  EpisodeSpecialKind,
+  EpisodeValidationState,
+} from "@umt/contracts";
+import type { StatusTone } from "~/components/console/status-badge.tsx";
+
+// 集数映射的界面文案与纯函数(docs/plan/episode-resolution.md 批次 4):方式名称、季集写法、规则摘要、
+// 表格规则的文本格式、作品页「集数映射」分区的地址。
+
+/** 识别方式的人话 */
+export const METHOD_LABEL: Record<EpisodeResolutionMethod, string> = {
+  raw: "原号",
+  rule: "按规则",
+  absolute_in_season: "季内绝对集号",
+  absolute_cross_season: "跨季绝对集号",
+  air_date: "按播出日期",
+  unverified: "元数据未覆盖，先按原号",
+  unresolved: "待确认",
+  skipped: "不适用",
+};
+
+export const SPECIAL_LABEL: Record<EpisodeSpecialKind, string> = {
+  special: "特别篇",
+  extra: "花絮",
+  ignore: "忽略",
+};
+
+export const RULE_KIND_LABEL: Record<EpisodeMappingRuleSpec["kind"], string> = {
+  expression: "偏移表达式",
+  table: "对照表",
+  special: "特别篇 / 花絮 / 忽略",
+};
+
+/** 校验状态:状态色只表示状态 */
+export const VALIDATION: Record<EpisodeValidationState, { label: string; tone: StatusTone }> = {
+  pass: { label: "对得上", tone: "success" },
+  unverified: { label: "未核对", tone: "warning" },
+  fail: { label: "对不上", tone: "destructive" },
+  special: { label: "不按集入库", tone: "neutral" },
+  skipped: { label: "不适用", tone: "neutral" },
+};
+
+/** 方式名称:按规则映射成特别篇等时写具体去向 */
+export function methodText(r: Pick<EpisodeResolutionView, "method" | "special"> | null | undefined): string {
+  if (!r) return "未解析";
+  if (r.special) return `按规则：${SPECIAL_LABEL[r.special]}`;
+  return METHOD_LABEL[r.method] ?? r.method;
+}
+
+/** 绝对集号类方式:订阅表单据此提示「这个发布组用的是绝对集号」 */
+export const isAbsoluteMethod = (m: EpisodeResolutionMethod) =>
+  m === "absolute_in_season" || m === "absolute_cross_season";
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** 季集写法:S01E25、S02E01-E02;只有集号没季号写 E25 */
+export function episodeCode(season: number | null | undefined, episodes: { start: number; end: number } | undefined) {
+  if (!episodes) return season != null ? `S${pad(season)}` : "";
+  const s = season != null ? `S${pad(season)}` : "";
+  const e =
+    episodes.start === episodes.end ? `E${pad(episodes.start)}` : `E${pad(episodes.start)}-E${pad(episodes.end)}`;
+  return `${s}${e}`;
+}
+
+/** 发布者声称的季集(原始) */
+export function sourceText(r: Pick<EpisodeResolutionView, "source"> | null | undefined): string {
+  if (!r) return "—";
+  const { season, episodes, airDate } = r.source;
+  if (episodes) return episodeCode(season, episodes);
+  if (airDate) return airDate.replace(/^(\d{4})(\d{2})(\d{2})$/, "$1-$2-$3");
+  return "—";
+}
+
+/** 媒体库应当使用的季集(规范);按规则去特别篇等写去向,换不出写「—」 */
+export function canonicalText(r: Pick<EpisodeResolutionView, "canonical" | "special" | "method"> | null | undefined) {
+  if (!r) return "—";
+  if (r.special) return SPECIAL_LABEL[r.special];
+  if (r.canonical) return episodeCode(r.canonical.season, r.canonical.episodes);
+  return "—";
+}
+
+export const scopeText = (season: number | null | undefined, group: string | null | undefined) =>
+  `${season == null ? "任意季" : `第 ${season} 季`} · ${group?.trim() || "任意发布组"}`;
+
+/** 规则内容一句话 */
+export function ruleText(
+  r: Pick<EpisodeMappingRuleSpec, "kind" | "expression" | "targetSeason" | "tableEntries" | "special">,
+) {
+  if (r.kind === "expression") {
+    return `${r.expression ?? ""}${r.targetSeason != null ? ` → 第 ${r.targetSeason} 季` : ""}`;
+  }
+  if (r.kind === "table") {
+    const n = r.tableEntries?.length ?? 0;
+    const first = r.tableEntries?.[0];
+    return first ? `${tableLine(first)}${n > 1 ? ` 等 ${n} 行` : ""}` : "空对照表";
+  }
+  return r.special ? `映射为${SPECIAL_LABEL[r.special]}` : "未选去向";
+}
+
+/** 停用原因:手动停用 / 规则失效(带当时的来源季集) */
+export function disabledReasonText(rule: Pick<EpisodeMappingRuleRow, "status" | "disabledReason">): string | null {
+  if (rule.status !== "disabled") return null;
+  if (!rule.disabledReason) return "已停用";
+  try {
+    const v = JSON.parse(rule.disabledReason) as {
+      manual?: boolean;
+      source?: EpisodeResolutionView["source"];
+    };
+    if (v.manual) return "手动停用";
+    if (v.source) return `规则算出的集数对不上季表（来源 ${sourceText({ source: v.source })}），已自动停用`;
+  } catch {
+    // 旧格式:原样显示
+  }
+  return rule.disabledReason;
+}
+
+// ── 对照表的文本格式:每行 `26=S02E01` 或 `27-28=S02E02` ──
+
+export function tableLine(e: EpisodeMappingTableEntry): string {
+  const from = e.from.start === e.from.end ? `${e.from.start}` : `${e.from.start}-${e.from.end}`;
+  return `${from}=S${pad(e.to.season)}E${pad(e.to.episode)}`;
+}
+
+export const formatTable = (entries: readonly EpisodeMappingTableEntry[] | null | undefined) =>
+  (entries ?? []).map(tableLine).join("\n");
+
+/** 解析对照表文本;有错返回第一处错误 */
+export function parseTable(text: string): { entries: EpisodeMappingTableEntry[]; error: string | null } {
+  const entries: EpisodeMappingTableEntry[] = [];
+  const lines = text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (const [i, line] of lines.entries()) {
+    const m = line.match(/^(\d{1,4})(?:\s*-\s*(\d{1,4}))?\s*(?:=|→|->)\s*S(\d{1,3})\s*E(\d{1,4})$/i);
+    if (!m) return { entries, error: `第 ${i + 1} 行格式不对，写成 26=S02E01 或 27-28=S02E02` };
+    const start = Number(m[1]);
+    const end = m[2] ? Number(m[2]) : start;
+    if (end < start) return { entries, error: `第 ${i + 1} 行的区间写反了` };
+    entries.push({ from: { start, end }, to: { season: Number(m[3]), episode: Number(m[4]) } });
+  }
+  return { entries, error: null };
+}
+
+// ── 草稿 ──
+
+export interface RuleDraft {
+  season: string;
+  releaseGroup: string;
+  kind: EpisodeMappingRuleSpec["kind"];
+  expression: string;
+  targetSeason: string;
+  table: string;
+  special: EpisodeSpecialKind;
+}
+
+export const EMPTY_DRAFT: RuleDraft = {
+  season: "",
+  releaseGroup: "",
+  kind: "expression",
+  expression: "",
+  targetSeason: "",
+  table: "",
+  special: "ignore",
+};
+
+export function draftOfRule(r: EpisodeMappingRuleRow): RuleDraft {
+  return {
+    season: r.season != null ? String(r.season) : "",
+    releaseGroup: r.releaseGroup ?? "",
+    kind: r.kind,
+    expression: r.expression ?? "",
+    targetSeason: r.targetSeason != null ? String(r.targetSeason) : "",
+    table: formatTable(r.tableEntries),
+    special: r.special ?? "ignore",
+  };
+}
+
+const intOrNull = (s: string) => (/^\d{1,3}$/.test(s.trim()) ? Number(s.trim()) : null);
+
+/** 草稿 → 接口的规则内容;不完整时返回错误(预览不发请求) */
+export function specOfDraft(d: RuleDraft): { spec: EpisodeMappingRuleSpec | null; error: string | null } {
+  if (d.season.trim() && intOrNull(d.season) === null) return { spec: null, error: "来源季写数字，空着表示任意季" };
+  if (d.targetSeason.trim() && intOrNull(d.targetSeason) === null) return { spec: null, error: "目标季写数字" };
+  const base = { season: intOrNull(d.season), releaseGroup: d.releaseGroup.trim() || null };
+  if (d.kind === "expression") {
+    if (!d.expression.trim()) return { spec: null, error: "填偏移表达式，如 EP-12" };
+    return {
+      spec: { ...base, kind: "expression", expression: d.expression.trim(), targetSeason: intOrNull(d.targetSeason) },
+      error: null,
+    };
+  }
+  if (d.kind === "table") {
+    const t = parseTable(d.table);
+    if (t.error) return { spec: null, error: t.error };
+    if (!t.entries.length) return { spec: null, error: "对照表至少写一行" };
+    return { spec: { ...base, kind: "table", tableEntries: t.entries }, error: null };
+  }
+  return { spec: { ...base, kind: "special", special: d.special }, error: null };
+}
+
+// ── 作品页「集数映射」分区的地址(待处理「修改」跳转并预填草稿) ──
+
+export const MAPPING_ANCHOR = "episode-mapping";
+
+export function mappingHref(
+  libraryPath: string,
+  prefill?: { season?: number | null; releaseGroup?: string | null; expression?: string; targetSeason?: number },
+): string {
+  const qs = new URLSearchParams();
+  if (prefill?.season != null) qs.set("mapSeason", String(prefill.season));
+  if (prefill?.releaseGroup) qs.set("mapGroup", prefill.releaseGroup);
+  if (prefill?.expression) qs.set("mapExpr", prefill.expression);
+  if (prefill?.targetSeason != null) qs.set("mapTarget", String(prefill.targetSeason));
+  const s = qs.toString();
+  return `${libraryPath}${s ? `?${s}` : ""}#${MAPPING_ANCHOR}`;
+}
+
+/** 从地址读预填草稿;没有任何预填返回 null */
+export function draftFromSearch(sp: URLSearchParams): RuleDraft | null {
+  const season = sp.get("mapSeason");
+  const group = sp.get("mapGroup");
+  const expr = sp.get("mapExpr");
+  const target = sp.get("mapTarget");
+  if (season === null && group === null && expr === null) return null;
+  return {
+    ...EMPTY_DRAFT,
+    season: season ?? "",
+    releaseGroup: group ?? "",
+    expression: expr ?? "",
+    targetSeason: target ?? "",
+  };
+}
+
+// ── 统计 ──
+
+/** 按发布组的方式统计一句话:`ANi：跨季绝对集号 12、原号 3`(只列非零) */
+export function groupMethodsText(g: EpisodeMappingPreview["groups"][number]): string {
+  const parts = [...g.methods].sort((a, b) => b.count - a.count).map((m) => `${METHOD_LABEL[m.method]} ${m.count}`);
+  return `${g.releaseGroup ?? "未知发布组"}：${parts.join("、")}`;
+}
+
+/** 用绝对集号的发布组(订阅表单提示用) */
+export function absoluteGroups(p: EpisodeMappingPreview | undefined): string[] {
+  if (!p) return [];
+  return p.groups
+    .filter((g) => g.methods.some((m) => isAbsoluteMethod(m.method)))
+    .map((g) => g.releaseGroup ?? "未知发布组");
+}
+
+/** 规则写入后的提示:只列非零项 */
+export function reresolveToast(r: EpisodeMappingRuleWriteResult["reresolve"], verb = "已应用"): string {
+  const parts = [`重算 ${r.releases} 条资源`];
+  if (r.changed) parts.push(`${r.changed} 条有变化`);
+  if (r.resolved) parts.push(`${r.resolved} 条待确认已解决`);
+  return `${verb}：${parts.join("，")}`;
+}

apps/web/app/components/episode-mapping/preview-table.test.ts

@@ -0,0 +1,72 @@
+import type { EpisodeMappingPreviewItem } from "@umt/contracts";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { PreviewTable } from "./preview-table.tsx";
+
+const item = (over: Partial<EpisodeMappingPreviewItem>): EpisodeMappingPreviewItem => ({
+  sourceReleaseId: "7d3f7f5e-8a8c-4b8e-9f0a-1b2c3d4e5f60",
+  title: "[Lilith-Raws] Kusuriya no Hitorigoto - 40",
+  publishedAt: "2025-03-14T15:00:00.000Z",
+  releaseGroup: "Lilith-Raws",
+  current: {
+    method: "unresolved",
+    source: { season: 1, episodes: { start: 40, end: 40 } },
+    canonical: null,
+    evidence: [],
+  },
+  preview: {
+    method: "rule",
+    source: { season: 1, episodes: { start: 40, end: 40 } },
+    canonical: { season: 2, episodes: { start: 10, end: 10 } },
+    ruleId: "draft",
+    evidence: [],
+  },
+  validation: "pass",
+  changed: true,
+  ...over,
+});
+
+describe("模拟预览表格", () => {
+  it("原始 → 当前 → 套用后、方式、校验;有变化的行高亮", () => {
+    const html = renderToStaticMarkup(createElement(PreviewTable, { items: [item({})], hasDraft: true }));
+    expect(html).toContain("套用后");
+    expect(html).toContain("S01E40");
+    expect(html).toContain("待确认");
+    expect(html).toContain("S02E10");
+    expect(html).toContain("按规则");
+    expect(html).toContain("对得上");
+    expect(html).toContain("有变化");
+    expect(html).toContain('data-changed="true"');
+  });
+
+  it("没变化不高亮;校验不通过显示对不上;没有草稿时列名是重算", () => {
+    const html = renderToStaticMarkup(
+      createElement(PreviewTable, {
+        items: [
+          item({
+            changed: false,
+            validation: "fail",
+            preview: {
+              method: "unresolved",
+              source: { season: 1, episodes: { start: 40, end: 40 } },
+              canonical: null,
+              evidence: [],
+            },
+          }),
+        ],
+        hasDraft: false,
+      }),
+    );
+    expect(html).toContain("重算");
+    expect(html).toContain("对不上");
+    expect(html).not.toContain("data-changed");
+    expect(html).not.toContain("有变化");
+  });
+
+  it("没有资源时显示空态", () => {
+    expect(renderToStaticMarkup(createElement(PreviewTable, { items: [], hasDraft: false }))).toContain(
+      "还没有绑定的资源",
+    );
+  });
+});

apps/web/app/components/episode-mapping/preview-table.tsx

@@ -0,0 +1,73 @@
+import type { EpisodeMappingPreviewItem } from "@umt/contracts";
+import { ArrowRight } from "lucide-react";
+import { StatusBadge } from "~/components/console/status-badge.tsx";
+import { cn, formatDateTime } from "~/lib/utils.ts";
+import { canonicalText, methodText, sourceText, VALIDATION } from "./model.ts";
+
+// 模拟预览表格:原始季集 → 当前结果 → 套用草稿后的结果、方式、校验;与当前不同的行高亮并标「有变化」。
+
+export function PreviewTable({
+  items,
+  hasDraft,
+  empty = "这部作品还没有绑定的资源。",
+}: {
+  items: EpisodeMappingPreviewItem[];
+  /** 有草稿时列名写「套用后」,否则写「重算」 */
+  hasDraft: boolean;
+  empty?: string;
+}) {
+  if (!items.length) return <p className="px-4 py-6 text-caption text-muted-foreground sm:px-5">{empty}</p>;
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full min-w-[44rem] text-caption">
+        <thead>
+          <tr className="border-b border-border/60 text-left text-meta text-muted-foreground">
+            <th className="px-4 py-2 font-medium">资源</th>
+            <th className="px-3 py-2 font-medium">原始</th>
+            <th className="px-3 py-2 font-medium">当前</th>
+            <th className="px-3 py-2 font-medium">{hasDraft ? "套用后" : "重算"}</th>
+            <th className="px-3 py-2 font-medium">方式</th>
+            <th className="px-4 py-2 font-medium">校验</th>
+          </tr>
+        </thead>
+        <tbody>
+          {items.map((it) => {
+            const v = VALIDATION[it.validation];
+            return (
+              <tr
+                key={it.sourceReleaseId}
+                data-changed={it.changed || undefined}
+                className={cn("border-b border-border/60 last:border-b-0", it.changed && "bg-foreground/[0.04]")}
+              >
+                <td className="max-w-[22rem] px-4 py-2 align-top">
+                  <div className="font-mono text-meta break-all text-foreground">{it.title}</div>
+                  <div className="mt-0.5 text-meta text-muted-foreground">
+                    {[it.releaseGroup, formatDateTime(it.publishedAt)].filter(Boolean).join(" · ")}
+                  </div>
+                </td>
+                <td className="px-3 py-2 align-top font-mono tabular-nums">{sourceText(it.preview)}</td>
+                <td className="px-3 py-2 align-top">
+                  <div className="font-mono tabular-nums">{canonicalText(it.current)}</div>
+                  <div className="text-meta text-muted-foreground">{methodText(it.current)}</div>
+                </td>
+                <td className="px-3 py-2 align-top">
+                  <div className="inline-flex items-center gap-1 font-mono tabular-nums">
+                    {it.changed ? <ArrowRight aria-hidden className="h-3 w-3 text-muted-foreground" /> : null}
+                    <span className={cn(it.changed && "font-semibold text-foreground")}>
+                      {canonicalText(it.preview)}
+                    </span>
+                  </div>
+                  {it.changed ? <div className="text-meta text-muted-foreground">有变化</div> : null}
+                </td>
+                <td className="px-3 py-2 align-top">{methodText(it.preview)}</td>
+                <td className="px-4 py-2 align-top">
+                  <StatusBadge tone={v.tone}>{v.label}</StatusBadge>
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}

apps/web/app/components/episode-mapping/subscription-summary.tsx

@@ -0,0 +1,80 @@
+import { ChevronRight, Info } from "lucide-react";
+import { Link } from "react-router";
+import { useEpisodeMappingPreview } from "~/api/episode-mapping.ts";
+import { useEntityDetail } from "~/api/library.ts";
+import { consolePath } from "~/components/console/nav.ts";
+import { StatusBadge } from "~/components/console/status-badge.tsx";
+import { Panel } from "~/components/library/parts.tsx";
+import { absoluteGroups, groupMethodsText, mappingHref } from "./model.ts";
+
+// 订阅详情的集数映射摘要 + 订阅表单的绝对集号提示(批次 4)。数据来自模拟预览(不带草稿 = 当前规则)。
+
+/** 订阅的季:有季单元取它的季号,否则不按季过滤 */
+function useSubscriptionSeason(entityId: string, seasonUnitId: string | null | undefined): number | null {
+  const entity = useEntityDetail(seasonUnitId ? entityId : undefined);
+  if (!seasonUnitId) return null;
+  return entity.data?.contentUnits.find((u) => u.id === seasonUnitId)?.seasonNumber ?? null;
+}
+
+export function SubscriptionMappingSummary({
+  entityId,
+  seasonUnitId,
+}: {
+  entityId: string;
+  seasonUnitId?: string | null;
+}) {
+  const season = useSubscriptionSeason(entityId, seasonUnitId);
+  const preview = useEpisodeMappingPreview(entityId, season != null ? { season } : {});
+  const p = preview.data;
+  if (!p?.applicable || (p.groups.length === 0 && p.seasons.seasons.length === 0)) return null;
+  const pending = p.groups.reduce((n, g) => n + g.pending, 0);
+  return (
+    <Panel
+      title="集数映射"
+      description={`${season != null ? `第 ${season} 季` : "全部季"}最近资源按发布组的识别方式`}
+      actions={
+        <Link
+          to={mappingHref(consolePath("library", entityId))}
+          className="inline-flex items-center text-meta text-muted-foreground hover:text-foreground hover:underline"
+        >
+          到作品页调整
+          <ChevronRight className="h-3 w-3" />
+        </Link>
+      }
+    >
+      {p.groups.length ? (
+        <ul className="space-y-1 text-caption text-foreground">
+          {p.groups.map((g) => (
+            <li key={g.releaseGroup ?? "-"}>{groupMethodsText(g)}</li>
+          ))}
+        </ul>
+      ) : (
+        <p className="text-caption text-muted-foreground">还没有绑定到这一季的资源。</p>
+      )}
+      {pending ? (
+        <div className="mt-2">
+          <StatusBadge tone="warning">待确认 {pending} 条</StatusBadge>
+        </div>
+      ) : null}
+    </Panel>
+  );
+}
+
+/** 订阅表单:作品的近期资源里有发布组用绝对集号时提示一句,不阻塞 */
+export function AbsoluteNumberingHint({ entityId }: { entityId: string | null }) {
+  const preview = useEpisodeMappingPreview(entityId, {});
+  const groups = absoluteGroups(preview.data);
+  if (!entityId || !groups.length) return null;
+  return (
+    <p className="flex items-start gap-1.5 text-meta text-muted-foreground">
+      <Info aria-hidden className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+      <span>
+        {groups.map((g) => `「${g}」`).join("")}用的是绝对集号，已自动换算成季内集号；不对的话到
+        <Link className="mx-0.5 underline-offset-4 hover:underline" to={mappingHref(consolePath("library", entityId))}>
+          作品页的集数映射
+        </Link>
+        调整。
+      </span>
+    </p>
+  );
+}

apps/web/app/components/organize-wizard/model.ts

@@ -368,6 +368,7 @@ export const EXCLUDE_REASON: Record<string, string> = {
   orphan_sidecar: "孤立附属文件",
   no_episode: "解析不出集号",
   special_extra: "特典/花絮",
+  episode_unresolved: "集数待确认",
   extra_content: "额外内容",
   no_target_dir: "没有目标目录",
   naming_failed: "命名失败",

apps/web/app/components/subscriptions/subscription-form.tsx

@@ -28,6 +28,7 @@ import {
 } from "~/api/subscriptions.ts";
 import { FormField } from "~/components/console/form-field.tsx";
 import { consolePath } from "~/components/console/nav.ts";
+import { AbsoluteNumberingHint } from "~/components/episode-mapping/subscription-summary.tsx";
 import { PRIORITY, SEASON_SCOPE, SUB_MODE } from "~/components/library/labels.ts";
 import { ChipToggleGroup } from "~/components/library/parts.tsx";
 import { Button } from "~/components/ui/button.tsx";
@@ -624,6 +625,7 @@ export function SubscriptionFormDialog({
               {d.mode === "continuous" && d.seasonScope === "following_seasons" && !isMovie ? (
                 <p className="text-meta text-muted-foreground">特别篇、衍生节目和同名重启不算作下一季。</p>
               ) : null}
+              {isMovie ? null : <AbsoluteNumberingHint entityId={entityId} />}
             </Section>
 
             <Section title="下载">

apps/web/app/routes/console/inbox.tsx

@@ -15,6 +15,7 @@ import { PageHeader } from "~/components/console/page-header.tsx";
 import { StatusBadge } from "~/components/console/status-badge.tsx";
 import { TechInfo } from "~/components/console/tech-info.tsx";
 import { useListPagination } from "~/components/console/use-list-pagination.ts";
+import { EpisodeDecision } from "~/components/episode-mapping/decision.tsx";
 import { EntityPicker, type PickedEntity } from "~/components/library/identity-entity-picker.tsx";
 import { DECISION_KIND, DECISION_STATUS, opts, SEVERITY } from "~/components/library/labels.ts";
 import { Chip, relTime, Tone } from "~/components/library/parts.tsx";
@@ -363,6 +364,8 @@ function DismissButton({ d }: { d: Decision }) {
 function DecisionCard({ d }: { d: Decision }) {
   const open = OPEN.includes(d.status);
   const identity = IDENTITY_KINDS.includes(d.kind);
+  // 集数待确认:证据与「确认 / 修改 / 忽略」由 EpisodeDecision 渲染
+  const episode = d.kind === "episode_mapping";
   // 身份类:手动 TMDB / 选本地作品两个选项并进「指定作品」
   const options = d.options.filter(
     (o) =>
@@ -383,11 +386,16 @@ function DecisionCard({ d }: { d: Decision }) {
       {d.summary ? (
         <p className="mt-1 text-caption break-words text-muted-foreground">{humanizeReason(d.summary)}</p>
       ) : null}
-      <GroupReleases d={d} />
+      {episode ? null : <GroupReleases d={d} />}
+      {episode ? (
+        <div className="mt-3">
+          <EpisodeDecision d={d} open={open} />
+        </div>
+      ) : null}
       <div className="mt-3">
         <Evidence d={d} />
       </div>
-      {open ? (
+      {open && !episode ? (
         <div className="mt-3 flex flex-wrap items-center gap-2">
           {identity ? <AssignWorkButton d={d} /> : null}
           {options.map((o) => (
@@ -404,7 +412,7 @@ function DecisionCard({ d }: { d: Decision }) {
             </Link>
           ) : null}
         </div>
-      ) : (
+      ) : open ? null : (
         <p className="mt-3 text-meta text-muted-foreground">
           {d.resolvedBy ? `${actorText(d.resolvedBy)} ` : ""}于 {formatDateTime(d.resolvedAt)}
           {resolution?.optionKey

apps/web/app/routes/console/library.$id.tsx

@@ -48,6 +48,7 @@ import { PaginatedList } from "~/components/console/paginated-list.tsx";
 import { StatusBadge } from "~/components/console/status-badge.tsx";
 import { TechInfo } from "~/components/console/tech-info.tsx";
 import { DROPPED_STATUS, droppedReason, PURPOSE_LABEL } from "~/components/downloads/plan-format.ts";
+import { EpisodeMappingPanel } from "~/components/episode-mapping/mapping-panel.tsx";
 import { evidenceLabel, FieldLockDialog, IdentityDialog, MergeDialog } from "~/components/library/entity-dialogs.tsx";
 import {
   CONTENT_TYPE,
@@ -1215,6 +1216,7 @@ export default function LibraryDetailPage() {
         {e.kind !== "movie" ? <EpisodesPanel detail={d} units={entity.data?.contentUnits ?? []} /> : null}
         {e.kind === "movie" ? <MovieVersionsPanel entityId={e.id} /> : null}
         <SlotsPanel detail={d} units={entity.data?.contentUnits ?? []} />
+        {e.kind === "series" || e.kind === "variety" ? <EpisodeMappingPanel entityId={e.id} /> : null}
         <div className="grid gap-5 xl:grid-cols-2">
           <IdentityPanel detail={d} />
           <MetadataPanel detail={d} entity={entity.data} />

apps/web/app/routes/console/subscriptions.$id.tsx

@@ -12,6 +12,7 @@ import { ErrorState, LoadingState } from "~/components/console/empty-state.tsx";
 import { KvList } from "~/components/console/kv-list.tsx";
 import { consolePath } from "~/components/console/nav.ts";
 import { StatusBadge } from "~/components/console/status-badge.tsx";
+import { SubscriptionMappingSummary } from "~/components/episode-mapping/subscription-summary.tsx";
 import { PRIORITY, SEASON_SCOPE, SUB_MODE, SUB_ORIGIN, SUB_STATUS } from "~/components/library/labels.ts";
 import { CoverPlaceholder, Panel, relTime, Tone } from "~/components/library/parts.tsx";
 import { SlotsPanel } from "~/components/library/subscriptions-slots.tsx";
@@ -215,6 +216,10 @@ export default function SubscriptionDetailPage() {
 
         {sub.mediaEntityId ? <SlotPanel sub={sub} cov={cov} item={item} canFill={tracking} /> : null}
 
+        {sub.mediaEntityId && sub.mediaKind !== "movie" ? (
+          <SubscriptionMappingSummary entityId={sub.mediaEntityId} seasonUnitId={sub.seasonUnitId} />
+        ) : null}
+
         <div className="grid gap-5 lg:grid-cols-2">
           <Panel title="订阅信息">
             <KvList