polish(admin): 抽出后台控件包并统一各页布局与交互

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/components/admin/AdminEmpty.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+
+/** 图标 + 主文案 + 辅文案 */
+export default function AdminEmpty({
+  icon,
+  title,
+  description,
+  className = "",
+}: {
+  icon: ReactNode;
+  title: string;
+  description?: string;
+  className?: string;
+}) {
+  return (
+    <div className={`text-center py-16 px-6 ${className}`.trim()}>
+      <span
+        className="inline-flex w-12 h-12 rounded-full items-center justify-center mb-3"
+        style={{ background: "var(--panel-2)", color: "var(--ink-3)" }}
+        aria-hidden
+      >
+        {icon}
+      </span>
+      <p className="text-[14.5px]" style={{ color: "var(--ink)" }}>
+        {title}
+      </p>
+      {description ? <p className="meta mt-1.5 text-[12.5px]">{description}</p> : null}
+    </div>
+  );
+}

frontend/components/admin/AdminIconButton.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import Link from "next/link";
+import type { ReactNode } from "react";
+
+type Tone = "default" | "accent" | "danger";
+
+const toneClass: Record<Tone, string> = {
+  default: "",
+  accent: "is-accent",
+  danger: "is-danger",
+};
+
+/** 32px 圆形行内操作；hover/focus 走 CSS，禁止 JS 改 style */
+export default function AdminIconButton({
+  children,
+  tip,
+  ariaLabel,
+  tone = "default",
+  className = "",
+  href,
+  disabled,
+  onClick,
+  type = "button",
+}: {
+  children: ReactNode;
+  tip?: string;
+  ariaLabel: string;
+  tone?: Tone;
+  className?: string;
+  href?: string;
+  disabled?: boolean;
+  onClick?: () => void;
+  type?: "button" | "submit";
+}) {
+  const cls = `admin-icon-btn ${toneClass[tone]} ${className}`.trim();
+
+  if (href && !disabled) {
+    return (
+      <Link href={href} className={cls} aria-label={ariaLabel} data-tip={tip}>
+        {children}
+      </Link>
+    );
+  }
+
+  return (
+    <button
+      type={type}
+      className={cls}
+      aria-label={ariaLabel}
+      data-tip={tip}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {children}
+    </button>
+  );
+}

frontend/components/admin/AdminPageHeader.tsx

@@ -0,0 +1,39 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+/** 后台统一页头：36px 图标槽 + 标题 + 说明 + 可选右侧 CTA */
+export default function AdminPageHeader({
+  icon: Icon,
+  title,
+  description,
+  actions,
+}: {
+  icon: LucideIcon;
+  title: string;
+  description?: ReactNode;
+  actions?: ReactNode;
+}) {
+  return (
+    <div className="mb-5 flex items-start justify-between gap-3 flex-wrap">
+      <div className="min-w-0">
+        <h1
+          className="text-[22px] sm:text-[26px] font-extrabold tracking-tight flex items-center gap-2.5"
+          style={{ color: "var(--ink)" }}
+        >
+          <span
+            className="w-9 h-9 rounded-xl flex items-center justify-center shrink-0"
+            style={{ background: "var(--accent-soft)", color: "var(--accent)" }}
+            aria-hidden
+          >
+            <Icon size={18} />
+          </span>
+          {title}
+        </h1>
+        {description != null && description !== "" && (
+          <p className="meta mt-1.5 text-[12.5px] leading-relaxed">{description}</p>
+        )}
+      </div>
+      {actions ? <div className="flex items-center gap-2 shrink-0 flex-wrap">{actions}</div> : null}
+    </div>
+  );
+}

frontend/components/admin/AdminPager.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+/** 紧凑上一页 / n / N / 下一页（客户端列表） */
+export default function AdminPager({
+  page,
+  total,
+  pageSize,
+  onChange,
+  loading,
+  summary,
+  className = "",
+}: {
+  page: number;
+  total: number;
+  pageSize: number;
+  onChange: (page: number) => void;
+  loading?: boolean;
+  /** 左侧摘要，默认「第 n / N 页」 */
+  summary?: string;
+  className?: string;
+}) {
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  if (totalPages <= 1 && total === 0) return null;
+  if (totalPages <= 1) return null;
+
+  return (
+    <div
+      className={`flex items-center justify-between gap-2 px-4 sm:px-5 py-3 ${className}`.trim()}
+      style={{ borderTop: "1px solid var(--line)" }}
+    >
+      <span className="meta text-[12px] tabular-nums" style={{ color: "var(--ink-3)" }}>
+        {summary ?? `第 ${page} / ${totalPages} 页`}
+      </span>
+      <div className="flex items-center gap-2">
+        <button
+          type="button"
+          onClick={() => onChange(page - 1)}
+          disabled={page <= 1 || loading}
+          className="btn btn-line btn-sm"
+          aria-label="上一页"
+        >
+          <ChevronLeft size={14} /> 上一页
+        </button>
+        <button
+          type="button"
+          onClick={() => onChange(page + 1)}
+          disabled={page >= totalPages || loading}
+          className="btn btn-line btn-sm"
+          aria-label="下一页"
+        >
+          下一页 <ChevronRight size={14} />
+        </button>
+      </div>
+    </div>
+  );
+}

frontend/components/admin/AdminSearchField.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { Search, X } from "lucide-react";
+import type { FormEvent } from "react";
+
+/** 左图标、可清除、Enter 提交；不要再并排「搜索」按钮 */
+export default function AdminSearchField({
+  value,
+  onChange,
+  onSubmit,
+  onClear,
+  placeholder,
+  ariaLabel,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  onSubmit?: () => void;
+  onClear?: () => void;
+  placeholder?: string;
+  ariaLabel: string;
+}) {
+  const handleSubmit = (e: FormEvent) => {
+    e.preventDefault();
+    onSubmit?.();
+  };
+
+  const clear = () => {
+    onChange("");
+    onClear?.();
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="relative flex-1 min-w-0" role="search">
+      <Search
+        size={15}
+        className="absolute left-3.5 top-1/2 -translate-y-1/2 pointer-events-none"
+        style={{ color: "var(--ink-3)" }}
+        aria-hidden
+      />
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        aria-label={ariaLabel}
+        className="field pl-10 pr-9 py-2.5"
+      />
+      {value ? (
+        <button
+          type="button"
+          onClick={clear}
+          aria-label="清除搜索"
+          className="absolute right-2.5 top-1/2 -translate-y-1/2 w-6 h-6 inline-flex items-center justify-center rounded-full transition-colors hover:bg-[var(--panel-2)]"
+          style={{ color: "var(--ink-3)" }}
+        >
+          <X size={14} />
+        </button>
+      ) : null}
+    </form>
+  );
+}

frontend/components/admin/AdminSection.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+
+/** 控制台模块：标题 / 说明 / 右上 extra；列表页一张表一块 */
+export default function AdminSection({
+  title,
+  description,
+  extra,
+  children,
+  className = "",
+  bodyClassName = "",
+  flush = false,
+}: {
+  title?: ReactNode;
+  description?: ReactNode;
+  extra?: ReactNode;
+  children: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+  /** 无内边距，适合表格/列表铺满 */
+  flush?: boolean;
+}) {
+  const hasHead = title != null || description != null || extra != null;
+  return (
+    <section className={`panel overflow-hidden ${className}`.trim()}>
+      {hasHead && (
+        <div
+          className="px-4 sm:px-5 py-3.5 flex items-start justify-between gap-3 flex-wrap"
+          style={{ borderBottom: "1px solid var(--line)" }}
+        >
+          <div className="min-w-0">
+            {title != null && (
+              <h2 className="font-medium text-[15px]" style={{ color: "var(--ink)" }}>
+                {title}
+              </h2>
+            )}
+            {description != null && description !== "" && (
+              <p className="meta text-[12.5px] mt-0.5 leading-relaxed">{description}</p>
+            )}
+          </div>
+          {extra != null && <div className="shrink-0">{extra}</div>}
+        </div>
+      )}
+      <div className={`${flush ? "" : "p-4 sm:p-5"} ${bodyClassName}`.trim()}>{children}</div>
+    </section>
+  );
+}

frontend/components/admin/AdminSegmented.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+export type AdminSegmentOption<T extends string = string> = {
+  key: T;
+  label: string;
+  icon?: ReactNode;
+  count?: number | string;
+  disabled?: boolean;
+};
+
+/** 分段筛选：可带 count / icon；选中态走 --nav-active-* */
+export default function AdminSegmented<T extends string = string>({
+  options,
+  value,
+  onChange,
+  ariaLabel,
+  size = "md",
+  role = "tablist",
+}: {
+  options: AdminSegmentOption<T>[];
+  value: T;
+  onChange: (key: T) => void;
+  ariaLabel: string;
+  size?: "md" | "sm";
+  role?: "tablist" | "group";
+}) {
+  const useTabs = role === "tablist";
+  return (
+    <div
+      className="flex items-center gap-1.5 flex-wrap"
+      role={role}
+      aria-label={ariaLabel}
+    >
+      {options.map((opt) => {
+        const active = value === opt.key;
+        return (
+          <button
+            key={opt.key}
+            type="button"
+            role={useTabs ? "tab" : undefined}
+            aria-selected={useTabs ? active : undefined}
+            aria-pressed={!useTabs ? active : undefined}
+            disabled={opt.disabled}
+            onClick={() => {
+              if (!active) onChange(opt.key);
+            }}
+            className={`admin-seg ${size === "sm" ? "admin-seg-sm" : ""}`.trim()}
+          >
+            {opt.icon}
+            {opt.label}
+            {opt.count != null && <span className="admin-seg-count">{opt.count}</span>}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

frontend/components/admin/AdminSettingRow.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+
+/** 「标题 + 说明 | 控件」一行，设置页与内容策略共用 */
+export default function AdminSettingRow({
+  title,
+  description,
+  control,
+  children,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  control?: ReactNode;
+  /** 展开区（如阈值输入），画在分隔线下方 */
+  children?: ReactNode;
+}) {
+  return (
+    <div className="panel p-4 sm:p-5">
+      <div className="flex items-start justify-between gap-4 flex-wrap">
+        <div className="min-w-0 flex-1">
+          <h2 className="text-[15px] font-semibold flex items-center gap-1.5" style={{ color: "var(--ink)" }}>
+            {title}
+          </h2>
+          {description != null && description !== "" && (
+            <p className="meta text-[12.5px] mt-1 leading-relaxed">{description}</p>
+          )}
+        </div>
+        {control != null && <div className="shrink-0">{control}</div>}
+      </div>
+      {children != null && (
+        <div className="mt-4 pt-4" style={{ borderTop: "1px solid var(--line)" }}>
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/components/admin/AdminStatCard.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+
+/** KPI：图标软底 + 数字 + 说明 */
+export default function AdminStatCard({
+  label,
+  value,
+  sub,
+  hint,
+  icon,
+  color = "var(--accent)",
+  soft = "var(--accent-soft)",
+}: {
+  label: string;
+  value: ReactNode;
+  sub?: string;
+  hint?: string;
+  icon: ReactNode;
+  color?: string;
+  soft?: string;
+}) {
+  return (
+    <div className="panel p-4 sm:p-5 flex items-center gap-3">
+      <span
+        className="w-9 h-9 rounded-lg flex items-center justify-center shrink-0"
+        style={{ background: soft, color }}
+        aria-hidden
+      >
+        {icon}
+      </span>
+      <div className="min-w-0 leading-tight">
+        <p className="text-[11.5px] truncate" style={{ color: "var(--ink-3)" }}>
+          {label}
+        </p>
+        <p className="text-[19px] sm:text-[22px] font-extrabold tabular-nums leading-none mt-1" style={{ color: "var(--ink)" }}>
+          {value}
+          {sub ? (
+            <span className="ml-1.5 text-[11px] font-medium" style={{ color: "var(--ink-3)" }}>
+              {sub}
+            </span>
+          ) : null}
+        </p>
+        {hint ? <p className="meta text-[12px] mt-1.5">{hint}</p> : null}
+      </div>
+    </div>
+  );
+}

frontend/components/admin/AdminStatusChip.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+
+export type AdminStatusTone = "ok" | "warn" | "danger" | "muted" | "accent";
+
+const toneClass: Record<AdminStatusTone, string> = {
+  ok: "is-ok",
+  warn: "is-warn",
+  danger: "is-danger",
+  muted: "is-muted",
+  accent: "is-accent",
+};
+
+/** 待审 / 已发布 / 已拒绝 / 草稿 / 已删除 等状态粒 */
+export default function AdminStatusChip({
+  children,
+  tone = "muted",
+  className = "",
+}: {
+  children: ReactNode;
+  tone?: AdminStatusTone;
+  className?: string;
+}) {
+  return (
+    <span className={`admin-status ${toneClass[tone]} ${className}`.trim()}>{children}</span>
+  );
+}
+
+/** 内容状态 → 文案 + tone */
+export function contentStatusChip(
+  status: string,
+  deleted: boolean
+): { label: string; tone: AdminStatusTone } {
+  if (deleted) return { label: "已删除", tone: "danger" };
+  if (status === "pending") return { label: "待审", tone: "warn" };
+  if (status === "rejected") return { label: "已拒绝", tone: "danger" };
+  if (status === "published") return { label: "已发布", tone: "ok" };
+  return { label: status, tone: "muted" };
+}

frontend/components/admin/AdminSwitch.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+/** 后台唯一开关控件 */
+export default function AdminSwitch({
+  checked,
+  disabled,
+  onChange,
+  label,
+}: {
+  checked: boolean;
+  disabled?: boolean;
+  onChange: () => void;
+  label: string;
+}) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      aria-label={label}
+      disabled={disabled}
+      onClick={onChange}
+      className="admin-switch"
+    >
+      <span className="admin-switch-knob" aria-hidden />
+    </button>
+  );
+}

frontend/components/admin/index.ts

@@ -0,0 +1,13 @@
+export { default as AdminPageHeader } from "./AdminPageHeader";
+export { default as AdminSection } from "./AdminSection";
+export { default as AdminSwitch } from "./AdminSwitch";
+export { default as AdminSettingRow } from "./AdminSettingRow";
+export { default as AdminSegmented } from "./AdminSegmented";
+export type { AdminSegmentOption } from "./AdminSegmented";
+export { default as AdminSearchField } from "./AdminSearchField";
+export { default as AdminPager } from "./AdminPager";
+export { default as AdminEmpty } from "./AdminEmpty";
+export { default as AdminStatCard } from "./AdminStatCard";
+export { default as AdminIconButton } from "./AdminIconButton";
+export { default as AdminStatusChip, contentStatusChip } from "./AdminStatusChip";
+export type { AdminStatusTone } from "./AdminStatusChip";