@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/testcase/filters/field-configs.tsx

@@ -0,0 +1,748 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 用例筛选字段配置层（UI 对齐二期 TC-B 任务 21，照 bug/filters/field-configs
+// 同构装配 shared-kit/list-kit/filters 参数化工厂；旧 TestCaseFilterBar 三
+// Select 快速筛选由 FilterCondition 三段式取代）。五字段 key 恰为任务简报
+// 钉死集：state/type/priority/folder(单项目)/assigneeId——property 与
+// server/testcase/list-query.ts buildListWhere 的翻译分支一一对应。
+// 枚举值/label/图标引 components/testcase/constants.ts 的 META 表（模块级
+// 业务枚举分层）与既有 testcase_* i18n key，零新增文案。
+import { useState } from "react";
+import { m } from "@/paraglide/messages.js";
+import {
+  Check,
+  CircleDashed,
+  CircleFadingArrowUp,
+  CircleUser,
+  FolderOpen,
+  Target,
+  type LucideIcon,
+} from "lucide-react";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { UserAvatar } from "@/components/shared-kit";
+import { extractTextColors } from "@/components/shared-kit/list-kit/level-badge";
+import {
+  TEST_CASE_PRIORITY_VALUES,
+  TEST_CASE_STATE_VALUES,
+  TEST_CASE_TYPE_VALUES,
+  type TestCasePriority,
+  type TestCaseState,
+  type TestCaseType,
+} from "@/server/serverFns/testcase/constants";
+import {
+  TEST_CASE_PRIORITY_META,
+  TEST_CASE_STATE_META,
+  TEST_CASE_TYPE_META,
+} from "@/components/testcase/constants";
+import {
+  createDefaultCondition as createDefaultConditionIn,
+  deserializeFilters,
+  FilterFallbackValue,
+  FILTER_VALUE_CHIP_CLASS,
+  OPERATOR_LABELS,
+  generateConditionId,
+  type FilterValueChipContext,
+  type FilterValueEditorContext,
+  type FiltersModuleOptions,
+} from "@/components/shared-kit/list-kit/filters";
+import type {
+  FilterCondition as SharedFilterCondition,
+  FilterFieldConfig as SharedFilterFieldConfig,
+  FilterFolderLike,
+  FilterOperator,
+  FilterFieldType,
+  FilterUserLike,
+} from "@/components/shared-kit/list-kit/filters";
+import { cn } from "@/lib/utils";
+import type { UserBrief } from "@/components/story/types";
+
+export { serializeFilters, deserializeFilters, OPERATOR_LABELS, generateConditionId } from "@/components/shared-kit/list-kit/filters";
+export type { FilterOperator, FilterFieldType };
+
+export type TestcaseFilterKey =
+  | "state"
+  | "type"
+  | "priority"
+  | "folder"
+  | "assigneeId";
+
+export interface TestcaseFilterCondition extends SharedFilterCondition<TestcaseFilterKey> {}
+
+export interface TestcaseFilterFieldConfig extends SharedFilterFieldConfig<TestcaseFilterKey> {}
+
+const SELECT_OPERATORS: FilterOperator[] = ["is", "is_not", "is_any_of", "is_not_any_of", "is_empty", "is_not_empty"];
+const USER_OPERATORS: FilterOperator[] = ["is", "is_not", "is_any_of", "is_not_any_of", "is_empty", "is_not_empty"];
+
+// 字段键序 = 添加条件下拉的展示序（任务简报钉死：state/type/priority/folder/assigneeId）
+export const TESTCASE_FILTER_KEYS: readonly TestcaseFilterKey[] = [
+  "state",
+  "type",
+  "priority",
+  "folder",
+  "assigneeId",
+];
+
+// ---------------------------------------------------------------------------
+// 值 label 助手（自旧 filters/index.tsx 原样搬移；peek-panel/
+// inline-editors/grouped-list 经桶导出继续消费，import 路径不变）
+// ---------------------------------------------------------------------------
+
+export function stateLabel(state: TestCaseState): string {
+  switch (state) {
+    case "draft":
+      return m.testcase_state_draft();
+    case "in_review":
+      return m.testcase_state_in_review();
+    case "approved":
+      return m.testcase_state_approved();
+    case "deprecated":
+      return m.testcase_state_deprecated();
+  }
+}
+
+export function typeLabel(type: TestCaseType): string {
+  switch (type) {
+    case "functional":
+      return m.testcase_type_functional();
+    case "boundary":
+      return m.testcase_type_boundary();
+    case "exception":
+      return m.testcase_type_exception();
+    case "performance":
+      return m.testcase_type_performance();
+    case "security":
+      return m.testcase_type_security();
+    case "compatibility":
+      return m.testcase_type_compatibility();
+  }
+}
+
+export function priorityLabel(priority: TestCasePriority): string {
+  return priority.toUpperCase();
+}
+
+// ---------------------------------------------------------------------------
+// 值编辑器渲染器（EnumSelect/UserSelect 照 bug 同名件抄形状；FolderSelect 为
+// LabelSelect 的 id/name 裁剪版——模块树花名册经共享 folders 通道注入）
+// ---------------------------------------------------------------------------
+
+const compactBtn = "h-6 rounded-sm bg-muted px-2 text-xs font-normal";
+
+interface EnumOption {
+  value: string;
+  label: () => string;
+  colorToken?: string;
+  icon?: LucideIcon;
+}
+
+function renderValueEditor({ property, operator, value, onChange, multi, selected, toggleMultiValue, users, folders }: FilterValueEditorContext<TestcaseFilterKey>): React.ReactNode {
+  switch (property) {
+    case "state":
+      return (
+        <EnumSelect
+          options={TEST_CASE_STATE_VALUES.map((s) => ({ value: s, label: () => stateLabel(s), colorToken: TEST_CASE_STATE_META[s].color }))}
+          value={selected[0] ?? value}
+          onChange={(v) => onChange(v)}
+          mode={multi ? "multi" : "single"}
+          selected={selected}
+          onMultiChange={toggleMultiValue}
+          className={compactBtn}
+        />
+      );
+    case "type":
+      return (
+        <EnumSelect
+          options={TEST_CASE_TYPE_VALUES.map((t) => ({ value: t, label: () => typeLabel(t), icon: TEST_CASE_TYPE_META[t].icon }))}
+          value={selected[0] ?? value}
+          onChange={(v) => onChange(v)}
+          mode={multi ? "multi" : "single"}
+          selected={selected}
+          onMultiChange={toggleMultiValue}
+          className={compactBtn}
+        />
+      );
+    case "priority":
+      return (
+        <EnumSelect
+          options={TEST_CASE_PRIORITY_VALUES.map((p) => ({ value: p, label: () => priorityLabel(p), colorToken: TEST_CASE_PRIORITY_META[p].color, icon: TEST_CASE_PRIORITY_META[p].icon }))}
+          value={selected[0] ?? value}
+          onChange={(v) => onChange(v)}
+          mode={multi ? "multi" : "single"}
+          selected={selected}
+          onMultiChange={toggleMultiValue}
+          className={compactBtn}
+        />
+      );
+    case "folder":
+      return (
+        <FolderSelect
+          folders={folders ?? []}
+          value={!multi && selected[0] ? selected[0] : value}
+          onChange={(id) => onChange(id ?? "")}
+          mode={multi ? "multi" : "single"}
+          selected={selected}
+          onMultiChange={toggleMultiValue}
+          className={compactBtn}
+        />
+      );
+    case "assigneeId": {
+      const realSelected = selected.filter((id) => id !== "__none__");
+      const selectedUser = !multi && realSelected[0] ? users?.find((u) => u.id === realSelected[0]) ?? null : null;
+      return (
+        <UserSelect
+          value={selectedUser as UserBrief | null}
+          users={(users ?? []) as UserBrief[]}
+          onChange={(id) => onChange(id ?? "__none__")}
+          mode={multi ? "multi" : "single"}
+          selected={selected}
+          onMultiChange={toggleMultiValue}
+          className={compactBtn}
+        />
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+interface SelectRenderProps {
+  mode: "single" | "multi";
+  selected: string[];
+}
+
+/** 单/多选通用触发表chip：多选显示全部已选 chip（bug ChipTriggers 同款） */
+function ChipTriggers({ mode, selected, renderOption }: SelectRenderProps & { renderOption: (v: string) => React.ReactNode }) {
+  if (mode === "multi" && selected.length > 0) {
+    return (
+      <>{selected.map((s) => <span key={s}>{renderOption(s)}</span>)}</>
+    );
+  }
+  return null;
+}
+
+function EnumSelect({
+  options,
+  value,
+  onChange,
+  mode,
+  selected,
+  onMultiChange,
+  className,
+}: {
+  options: EnumOption[];
+  value: string;
+  onChange: (value: string) => void;
+  mode: "single" | "multi";
+  selected: string[];
+  onMultiChange?: (value: string) => void;
+  className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const isMulti = mode === "multi";
+
+  const renderChip = (v: string) => {
+    const opt = options.find((o) => o.value === v);
+    if (!opt) return <FallbackChip key={v} value={v} />;
+    const OptIcon = opt.icon;
+    return (
+      <span key={v} className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs">
+        {/* colorToken 为完整徽章 token（state META 含 bg-*）：icon-only 只取字色（任务 29 收编） */}
+        {OptIcon && <OptIcon className={cn("size-3 shrink-0", opt.colorToken ? extractTextColors(opt.colorToken) : "text-muted-foreground")} />}
+        <span className={cn("whitespace-nowrap rounded-sm px-1", opt.colorToken)}>{opt.label()}</span>
+      </span>
+    );
+  };
+
+  const current = options.find((o) => o.value === value);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {isMulti && selected.length > 0 ? (
+        <PopoverTrigger nativeButton={false} render={<div className="flex items-center gap-1" />}>
+          <ChipTriggers mode={mode} selected={selected} renderOption={renderChip} />
+        </PopoverTrigger>
+      ) : (
+        <PopoverTrigger render={<button type="button" className={cn("whitespace-nowrap transition-colors hover:bg-muted/80", className)} />}>
+          {current ? (
+            renderChip(current.value)
+          ) : (
+            <span className="text-muted-foreground">{value || "—"}</span>
+          )}
+        </PopoverTrigger>
+      )}
+      <PopoverContent className="w-40 p-1" align="start">
+        {options.map((opt) => {
+          const active = isMulti ? selected.includes(opt.value) : value === opt.value;
+          const OptIcon = opt.icon;
+          return (
+            <button
+              key={opt.value}
+              type="button"
+              onClick={() => {
+                if (isMulti) {
+                  onMultiChange?.(opt.value);
+                } else {
+                  onChange(opt.value);
+                  setOpen(false);
+                }
+              }}
+              className={cn(
+                "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs",
+                active ? "bg-accent font-medium" : "hover:bg-muted",
+              )}
+            >
+              {isMulti && (
+                <div className={cn("flex size-4 shrink-0 items-center justify-center rounded-sm border", active ? "border-primary bg-primary text-primary-foreground" : "border-input")}>
+                  {active && <Check className="size-3" />}
+                </div>
+              )}
+              {OptIcon && <OptIcon className="size-3.5 shrink-0 text-muted-foreground" />}
+              <span className={cn("rounded-sm px-1", opt.colorToken)}>{opt.label()}</span>
+              {!isMulti && active && <Check className="ml-auto size-3.5 shrink-0 text-primary" />}
+            </button>
+          );
+        })}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function FolderSelect({
+  folders,
+  value,
+  onChange,
+  mode,
+  selected,
+  onMultiChange,
+  className,
+}: {
+  folders: FilterFolderLike[];
+  value: string;
+  onChange: (id: string | null) => void;
+  mode: "single" | "multi";
+  selected: string[];
+  onMultiChange?: (value: string) => void;
+  className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const isMulti = mode === "multi";
+
+  const renderChip = (id: string) => {
+    const f = folders.find((folder) => folder.id === id);
+    if (!f) return <FallbackChip key={id} value={id} />;
+    return (
+      <span key={id} className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs">
+        <FolderOpen className="size-3 text-muted-foreground" />
+        <span className="whitespace-nowrap">{f.name}</span>
+      </span>
+    );
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {isMulti && selected.length > 0 ? (
+        <PopoverTrigger nativeButton={false} render={<div className="flex items-center gap-1" />}>
+          <ChipTriggers mode={mode} selected={selected} renderOption={renderChip} />
+        </PopoverTrigger>
+      ) : (
+        <PopoverTrigger render={<button type="button" className={cn("flex items-center gap-1 whitespace-nowrap transition-colors hover:bg-muted/80", className)} />}>
+          {value ? (
+            renderChip(value)
+          ) : (
+            <>
+              <FolderOpen className="size-3 text-muted-foreground" />
+              <span className="text-muted-foreground">{m.testcase_display_group_folder()}</span>
+            </>
+          )}
+        </PopoverTrigger>
+      )}
+      <PopoverContent className="w-48 p-1" align="start">
+        {folders.length === 0 ? (
+          <div className="px-2 py-3 text-center text-xs text-muted-foreground">{m.testcase_folderTree_ungrouped()}</div>
+        ) : (
+          folders.map((f) => {
+            const active = isMulti ? selected.includes(f.id) : value === f.id;
+            return (
+              <button
+                key={f.id}
+                type="button"
+                onClick={() => {
+                  if (isMulti) {
+                    onMultiChange?.(f.id);
+                  } else {
+                    onChange(f.id);
+                    setOpen(false);
+                  }
+                }}
+                className={cn(
+                  "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs",
+                  active ? "bg-accent font-medium" : "hover:bg-muted",
+                )}
+              >
+                {isMulti && (
+                  <div className={cn("flex size-4 shrink-0 items-center justify-center rounded-sm border", active ? "border-primary bg-primary text-primary-foreground" : "border-input")}>
+                    {active && <Check className="size-3" />}
+                  </div>
+                )}
+                <FolderOpen className="size-3.5 shrink-0 text-muted-foreground" />
+                <span className="truncate">{f.name}</span>
+                {!isMulti && active && <Check className="ml-auto size-3.5 shrink-0 text-primary" />}
+              </button>
+            );
+          })
+        )}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function UserSelect({
+  value,
+  users,
+  onChange,
+  mode,
+  selected,
+  onMultiChange,
+  className,
+}: {
+  value: UserBrief | null;
+  users: UserBrief[];
+  onChange: (id: string | null) => void;
+  mode: "single" | "multi";
+  selected: string[];
+  onMultiChange?: (value: string) => void;
+  className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const isMulti = mode === "multi";
+
+  const renderChip = (v: string) => {
+    if (v === "__none__") {
+      return (
+        <span key={v} className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs text-muted-foreground">
+          <CircleUser className="size-3" />
+          {m.testcase_storyCases_unassigned()}
+        </span>
+      );
+    }
+    const u = users.find((user) => user.id === v);
+    if (!u) return <FallbackChip key={v} value={v} />;
+    return (
+      <span key={v} className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 text-xs">
+        <UserAvatar avatarConfig={u.avatarConfig} bgShape="circle" bgColor={u.bgColor} name={u.username} size="xs" className="!w-3.5 !h-3.5" />
+        <span className="whitespace-nowrap">{u.username}</span>
+      </span>
+    );
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {isMulti && selected.length > 0 ? (
+        <PopoverTrigger nativeButton={false} render={<div className="flex items-center gap-1" />}>
+          <ChipTriggers mode={mode} selected={selected} renderOption={renderChip} />
+        </PopoverTrigger>
+      ) : (
+        <PopoverTrigger render={<button type="button" className={cn("flex items-center gap-1 whitespace-nowrap transition-colors hover:bg-muted/80", className)} />}>
+          {value ? (
+            <>
+              <UserAvatar avatarConfig={value.avatarConfig} bgShape="circle" bgColor={value.bgColor} name={value.username} size="xs" className="!w-3.5 !h-3.5" />
+              <span>{value.username}</span>
+            </>
+          ) : (
+            <>
+              <CircleUser className="size-3 text-muted-foreground" />
+              <span className="text-muted-foreground">{m.testcase_storyCases_unassigned()}</span>
+            </>
+          )}
+        </PopoverTrigger>
+      )}
+      <PopoverContent className="w-48 p-1" align="start">
+        <button
+          type="button"
+          onClick={() => {
+            if (isMulti) {
+              onMultiChange?.("__none__");
+            } else {
+              onChange(null);
+              setOpen(false);
+            }
+          }}
+          className={cn(
+            "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs",
+            selected.includes("__none__") ? "bg-accent font-medium" : "hover:bg-muted",
+          )}
+        >
+          {isMulti && (
+            <div className={cn("flex size-4 shrink-0 items-center justify-center rounded-sm border", selected.includes("__none__") ? "border-primary bg-primary text-primary-foreground" : "border-input")}>
+              {selected.includes("__none__") && <Check className="size-3" />}
+            </div>
+          )}
+          <CircleUser className="size-3.5 text-muted-foreground" />
+          {m.testcase_storyCases_unassigned()}
+        </button>
+        {users.map((u) => {
+          const active = isMulti ? selected.includes(u.id) : value?.id === u.id;
+          return (
+            <button
+              key={u.id}
+              type="button"
+              onClick={() => {
+                if (isMulti) {
+                  onMultiChange?.(u.id);
+                } else {
+                  onChange(u.id);
+                  setOpen(false);
+                }
+              }}
+              className={cn(
+                "flex w-full items-center gap-2 rounded px-2 py-1.5 text-xs",
+                active ? "bg-accent font-medium" : "hover:bg-muted",
+              )}
+            >
+              {isMulti && (
+                <div className={cn("flex size-4 shrink-0 items-center justify-center rounded-sm border", active ? "border-primary bg-primary text-primary-foreground" : "border-input")}>
+                  {active && <Check className="size-3" />}
+                </div>
+              )}
+              <UserAvatar avatarConfig={u.avatarConfig} bgShape="circle" bgColor={u.bgColor} name={u.username} size="xs" className="!w-4 !h-4" />
+              <span className="truncate">{u.username}</span>
+              {!isMulti && active && <Check className="ml-auto size-3.5 shrink-0 text-primary" />}
+            </button>
+          );
+        })}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function FallbackChip({ value }: { value: string }) {
+  return (
+    <span className="inline-flex items-center rounded-sm border border-border px-1.5 py-0.5 text-xs whitespace-nowrap">
+      {value}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 值 chip 渲染器（AppliedFilters 胶囊值段；META 色板/图标族单一来源）
+// ---------------------------------------------------------------------------
+
+function renderValueChip({ property, valueItem, users, folders }: FilterValueChipContext<TestcaseFilterKey>): React.ReactNode {
+  switch (property) {
+    case "state": {
+      const v = valueItem as TestCaseState;
+      return (
+        <span className={FILTER_VALUE_CHIP_CLASS}>
+          <span className={cn("whitespace-nowrap rounded-sm px-1", TEST_CASE_STATE_META[v]?.color)}>{stateLabel(v)}</span>
+        </span>
+      );
+    }
+    case "type": {
+      const v = valueItem as TestCaseType;
+      const Icon = TEST_CASE_TYPE_META[v]?.icon;
+      return (
+        <span className={FILTER_VALUE_CHIP_CLASS}>
+          {Icon && <Icon className="size-3 text-muted-foreground" />}
+          <span className="whitespace-nowrap">{typeLabel(v)}</span>
+        </span>
+      );
+    }
+    case "priority": {
+      const v = valueItem as TestCasePriority;
+      const meta = TEST_CASE_PRIORITY_META[v];
+      return (
+        <span className={FILTER_VALUE_CHIP_CLASS}>
+          {meta && <meta.icon className={cn("size-3", meta.color)} />}
+          <span className={cn("whitespace-nowrap", meta?.color)}>{priorityLabel(v)}</span>
+        </span>
+      );
+    }
+    case "folder": {
+      const f = folders?.find((folder) => folder.id === valueItem);
+      return (
+        <span className={FILTER_VALUE_CHIP_CLASS}>
+          <FolderOpen className="size-3 text-muted-foreground" />
+          <span className="whitespace-nowrap">{f?.name ?? valueItem}</span>
+        </span>
+      );
+    }
+    case "assigneeId": {
+      if (valueItem === "__none__") {
+        return (
+          <span className={FILTER_VALUE_CHIP_CLASS}>
+            <CircleUser className="size-3 text-muted-foreground" />
+            <span className="whitespace-nowrap text-muted-foreground">{m.testcase_storyCases_unassigned()}</span>
+          </span>
+        );
+      }
+      const u = users?.find((user) => user.id === valueItem);
+      if (!u) return <FilterFallbackValue value={valueItem} />;
+      return (
+        <span className={FILTER_VALUE_CHIP_CLASS}>
+          <UserAvatar
+            avatarConfig={u.avatarConfig}
+            bgShape="circle"
+            bgColor={u.bgColor}
+            name={u.username}
+            size="xs"
+            className="!w-4 !h-4"
+          />
+          <span className="whitespace-nowrap">{u.username}</span>
+        </span>
+      );
+    }
+    default:
+      return <FilterFallbackValue value={valueItem} />;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 字段配置表（键序 = TESTCASE_FILTER_KEYS = 添加下拉展示序；图标/色板引
+// components/testcase/constants.ts META 表——字段级图标取各枚举首项，与
+// display/dropdown GROUP_ICONS、bug 字段图标同「模块级业务枚举」分层）
+// ---------------------------------------------------------------------------
+
+export const TESTCASE_FILTER_FIELD_CONFIGS: Record<TestcaseFilterKey, TestcaseFilterFieldConfig> = {
+  state: {
+    key: "state",
+    label: m.testcase_filter_state,
+    icon: CircleDashed,
+    fieldType: "select",
+    operators: SELECT_OPERATORS,
+    defaultOperator: "is",
+    defaultValue: "draft",
+  },
+  type: {
+    key: "type",
+    label: m.testcase_filter_type,
+    icon: Target,
+    fieldType: "select",
+    operators: SELECT_OPERATORS,
+    defaultOperator: "is",
+    defaultValue: "functional",
+  },
+  priority: {
+    key: "priority",
+    label: m.testcase_filter_priority,
+    icon: CircleFadingArrowUp,
+    fieldType: "select",
+    operators: SELECT_OPERATORS,
+    defaultOperator: "is",
+    defaultValue: "p0",
+  },
+  folder: {
+    key: "folder",
+    label: m.testcase_display_group_folder,
+    icon: FolderOpen,
+    fieldType: "select",
+    operators: SELECT_OPERATORS,
+    defaultOperator: "is",
+  },
+  assigneeId: {
+    key: "assigneeId",
+    label: m.testcase_display_property_assignee,
+    icon: CircleUser,
+    fieldType: "user",
+    operators: USER_OPERATORS,
+    defaultOperator: "is",
+    defaultValue: "__none__",
+  },
+};
+
+// 消费方兼容：FILTER_FIELD_CONFIGS 数组（顺序 = 配置表声明序）
+export const FILTER_FIELD_CONFIGS: TestcaseFilterFieldConfig[] = Object.values(TESTCASE_FILTER_FIELD_CONFIGS);
+
+export const TESTCASE_FILTERS_MODULE_OPTIONS: FiltersModuleOptions<TestcaseFilterKey> = {
+  renderValueEditor,
+  renderValueChip,
+  toggleAriaLabel: m.list_kit_filter_toggleOpen,
+  // folder（模块）筛选仅单项目 scope 可达：全部项目聚合（projectId 缺省）从
+  // 添加下拉与属性切换隐藏——list-view 的 folder 条件 clamp effect 是第二道
+  // 保险（display resolveGroupKeys 同构，任务 20 先例）
+  resolveKeys: ({ projectId }) =>
+    projectId ? [...TESTCASE_FILTER_KEYS] : TESTCASE_FILTER_KEYS.filter((k) => k !== "folder"),
+};
+
+export function getFilterConfig(key: TestcaseFilterKey): TestcaseFilterFieldConfig {
+  // own-property 守卫：存量视图 JSON 的 property 可能撞上 Object.prototype 键名
+  // （如 "constructor"），直接索引会沿原型链取到 truthy 函数，必须回落首配置。
+  return Object.hasOwn(TESTCASE_FILTER_FIELD_CONFIGS, key)
+    ? TESTCASE_FILTER_FIELD_CONFIGS[key]
+    : FILTER_FIELD_CONFIGS[0];
+}
+
+export function getFilterLabel(key: TestcaseFilterKey): () => string {
+  return getFilterConfig(key).label;
+}
+
+export function getFilterIcon(key: TestcaseFilterKey): LucideIcon {
+  return getFilterConfig(key).icon;
+}
+
+export function createDefaultCondition(property: TestcaseFilterKey): TestcaseFilterCondition {
+  return createDefaultConditionIn(TESTCASE_FILTER_FIELD_CONFIGS, property);
+}
+
+/** 存量视图 filters.conditions 反序列化 + 五字段白名单收窄（脏 property 剔除） */
+export function deserializeTestcaseFilters(json: string | null | undefined): TestcaseFilterCondition[] {
+  return deserializeFilters(json ?? undefined).filter(
+    (c): c is TestcaseFilterCondition => Object.hasOwn(TESTCASE_FILTER_FIELD_CONFIGS, c.property),
+  );
+}
+
+/** 单值条件快速构造（存量扁平键 → 条件迁移用，操作符一律 is） */
+export function singleValueCondition(property: TestcaseFilterKey, value: string): TestcaseFilterCondition {
+  return { id: generateConditionId(), property, operator: "is", value };
+}
+
+/** 当前筛选条件的人读摘要（创建视图对话框 filterSummary 消费） */
+export function filterConditionSummary(
+  condition: TestcaseFilterCondition,
+  ctx: { users?: FilterUserLike[]; folders?: FilterFolderLike[] } = {},
+): string {
+  const config = getFilterConfig(condition.property);
+  const op = OPERATOR_LABELS[condition.operator]();
+  if (condition.operator === "is_empty" || condition.operator === "is_not_empty") {
+    return `${config.label()} ${op}`;
+  }
+  const labels = condition.value
+    .split(",")
+    .filter(Boolean)
+    .map((v) => conditionValueLabel(condition.property, v, ctx));
+  return `${config.label()} ${op} ${labels.join("、")}`;
+}
+
+function conditionValueLabel(
+  property: TestcaseFilterKey,
+  value: string,
+  ctx: { users?: FilterUserLike[]; folders?: FilterFolderLike[] },
+): string {
+  switch (property) {
+    case "state":
+      return stateLabel(value as TestCaseState);
+    case "type":
+      return typeLabel(value as TestCaseType);
+    case "priority":
+      return priorityLabel(value as TestCasePriority);
+    case "folder":
+      return ctx.folders?.find((f) => f.id === value)?.name ?? value;
+    case "assigneeId":
+      if (value === "__none__") return m.testcase_storyCases_unassigned();
+      return ctx.users?.find((u) => u.id === value)?.username ?? value;
+  }
+}