From ca7c3f27f0919f1d81c190222cd0ef8f204e3b51 Mon Sep 17 00:00:00 2001
From: linkeyu <linkeyu@wonderable.ai>
Date: Fri, 31 Jul 2026 17:08:13 +0800
Subject: [PATCH] =?UTF-8?q?=E5=8A=9F=E8=83=BD=EF=BC=9A=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=E7=BB=9F=E4=B8=80=E9=99=90=E5=88=B6=E7=99=BD=E5=90=8D=E5=8D=95?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E9=A1=B5=E9=9D=A2=20(#99)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 需求背景
新增统一白名单管理页面，让运营人员能够查看和调整全局限制，并按手机号或设备批量配置临时不限或风险免告警。

## 主要改动
- 新增白名单导航与完整管理页面
- 全局限制按五类分页展示并支持修改
- 白名单按主体聚合，展示各分类数量及悬浮明细
- 支持手机号与设备搜索、批量多选限制项和统一有效期
- 支持手动筛选、十条分页、主体点击编辑及启用开关
- 风控监控增加快捷加入白名单入口
- 旧引导视频配置页与统一限制入口保持一致

## 验证
- Next.js 生产构建通过
- TypeScript 类型检查通过
- 共 26 个页面完成静态/动态构建
- 已与后端 PR #207 配套验证

---------

Co-authored-by: linkeyu <798648091@qq.com>
Reviewed-on: https://gitea.shaguabijia.com/WonderableAI/shaguabijia-admin-web/pulls/99
Co-authored-by: linkeyu <linkeyu@wonderable.ai>
Co-committed-by: linkeyu <linkeyu@wonderable.ai>
---
 src/app/(main)/config/GuideVideoConfig.tsx |  116 ++-
 src/app/(main)/layout.tsx                  |    2 +
 src/app/(main)/limit-whitelist/page.tsx    | 1053 ++++++++++++++++++++
 src/app/(main)/risk-monitor/page.tsx       |   81 +-
 src/lib/types.ts                           |   81 +-
 src/lib/usePagedList.ts                    |    9 +-
 6 files changed, 1313 insertions(+), 29 deletions(-)
 create mode 100644 src/app/(main)/limit-whitelist/page.tsx

diff --git a/src/app/(main)/config/GuideVideoConfig.tsx b/src/app/(main)/config/GuideVideoConfig.tsx
index 706a636..c6cd7d8 100644
--- a/src/app/(main)/config/GuideVideoConfig.tsx
+++ b/src/app/(main)/config/GuideVideoConfig.tsx
@@ -1,7 +1,18 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { Button, Card, InputNumber, Space, Spin, Switch, Tag, Typography, Upload, message } from 'antd';
+import {
+  Button,
+  Card,
+  InputNumber,
+  Space,
+  Spin,
+  Switch,
+  Tag,
+  Typography,
+  Upload,
+  message,
+} from 'antd';
 import { DeleteOutlined, UploadOutlined } from '@ant-design/icons';
 import { api, errMsg } from '@/lib/api';
 import { canDo } from '@/lib/auth';
@@ -38,7 +49,9 @@ function SceneConfig({ scene }: { scene: Scene }) {
   const load = async () => {
     setLoading(true);
     try {
-      const { data } = await api.get<GuideCfg>('/admin/api/guide-video', { params: { scene } });
+      const { data } = await api.get<GuideCfg>('/admin/api/guide-video', {
+        params: { scene },
+      });
       sync(data);
     } catch (e) {
       message.error(errMsg(e));
@@ -56,7 +69,11 @@ function SceneConfig({ scene }: { scene: Scene }) {
     try {
       const { data } = await api.patch<GuideCfg>(
         '/admin/api/guide-video',
-        { enabled, max_plays: maxPlays, reward_coin: rewardCoin },
+        {
+          enabled,
+          reward_coin: rewardCoin,
+          ...(scene === 'comparison' ? { max_plays: maxPlays } : {}),
+        },
         { params: { scene } },
       );
       sync(data);
@@ -121,11 +138,20 @@ function SceneConfig({ scene }: { scene: Scene }) {
       size="small"
       title={meta.title}
       style={{ marginBottom: 16 }}
-      extra={cfg?.updated_at ? <Text type="secondary">更新于 {new Date(cfg.updated_at).toLocaleString('zh-CN')}</Text> : null}
+      extra={
+        cfg?.updated_at ? (
+          <Text type="secondary">
+            更新于 {new Date(cfg.updated_at).toLocaleString('zh-CN')}
+          </Text>
+        ) : null
+      }
     >
       <p style={{ color: '#777', marginTop: 0 }}>
-        Android 用户点击「{meta.action}」后，前若干次在等候浮层广告位播放本视频并奖励金币。
-        次数按账号、按功能分别计算；开播即计次，播完或中途关闭均发放当次配置的金币。
+        Android 用户点击「{meta.action}」后，前 {cfg?.max_plays ?? 3}{' '}
+        次在等候浮层广告位播放本视频并奖励金币。次数按账号、按功能分别计算；
+        开播即计次，播完或中途关闭均发放当次配置的金币。
+        {scene === 'coupon' &&
+          '领券引导视频的播放次数上限请在「监控审计 → 限制策略」中调整。'}
       </p>
       {loading || !cfg ? (
         <Spin style={{ display: 'block', margin: '24px 0' }} />
@@ -137,10 +163,24 @@ function SceneConfig({ scene }: { scene: Scene }) {
               <video
                 src={mediaUrl(cfg.video_url)}
                 controls
-                style={{ width: 240, maxHeight: 420, borderRadius: 12, background: '#000' }}
+                style={{
+                  width: 240,
+                  maxHeight: 420,
+                  borderRadius: 12,
+                  background: '#000',
+                }}
               />
             ) : (
-              <div style={{ height: 280, border: '1px dashed #d9d9d9', borderRadius: 12, display: 'grid', placeItems: 'center', color: '#aaa' }}>
+              <div
+                style={{
+                  height: 280,
+                  border: '1px dashed #d9d9d9',
+                  borderRadius: 12,
+                  display: 'grid',
+                  placeItems: 'center',
+                  color: '#aaa',
+                }}
+              >
                 未上传视频
               </div>
             )}
@@ -148,22 +188,51 @@ function SceneConfig({ scene }: { scene: Scene }) {
           <Space direction="vertical" size="middle" style={{ minWidth: 390 }}>
             <Space>
               <span>启用：</span>
-              <Switch checked={enabled} disabled={!canEdit} onChange={setEnabled} />
+              <Switch
+                checked={enabled}
+                disabled={!canEdit}
+                onChange={setEnabled}
+              />
               {!enabled && <Tag color="orange">已关闭</Tag>}
             </Space>
-            <Space>
-              <span>播放次数：</span>
-              <InputNumber min={0} max={50} precision={0} value={maxPlays} disabled={!canEdit} onChange={(v) => setMaxPlays(v ?? 0)} />
-              <Text type="secondary">每个账号前 N 次（默认 3）</Text>
-            </Space>
+            {scene === 'comparison' && (
+              <Space>
+                <span>播放次数：</span>
+                <InputNumber
+                  min={0}
+                  max={50}
+                  precision={0}
+                  value={maxPlays}
+                  disabled={!canEdit}
+                  onChange={(value) => setMaxPlays(value ?? 0)}
+                />
+                <Text type="secondary">每个账号前 N 次（默认 3）</Text>
+              </Space>
+            )}
             <Space>
               <span>每次金币：</span>
-              <InputNumber min={0} max={10000} precision={0} value={rewardCoin} disabled={!canEdit} onChange={(v) => setRewardCoin(v ?? 0)} />
+              <InputNumber
+                min={0}
+                max={10000}
+                precision={0}
+                value={rewardCoin}
+                disabled={!canEdit}
+                onChange={(value) => setRewardCoin(value ?? 0)}
+              />
               <Text type="secondary">默认 100</Text>
             </Space>
             <Space wrap>
-              <Upload accept="video/mp4,.mp4" showUploadList={false} beforeUpload={beforeUpload} disabled={!canEdit}>
-                <Button icon={<UploadOutlined />} loading={uploading} disabled={!canEdit}>
+              <Upload
+                accept="video/mp4,.mp4"
+                showUploadList={false}
+                beforeUpload={beforeUpload}
+                disabled={!canEdit}
+              >
+                <Button
+                  icon={<UploadOutlined />}
+                  loading={uploading}
+                  disabled={!canEdit}
+                >
                   {cfg.video_url ? '更换视频' : '上传视频'}
                 </Button>
               </Upload>
@@ -174,8 +243,17 @@ function SceneConfig({ scene }: { scene: Scene }) {
               )}
               <Text type="secondary">MP4（H.264），≤100MB</Text>
             </Space>
-            <Button type="primary" loading={saving} disabled={!canEdit} onClick={save}>保存配置</Button>
-            <Text type="secondary">累计播放 {cfg.total_plays} 次，已发币 {cfg.granted_plays} 次</Text>
+            <Button
+              type="primary"
+              loading={saving}
+              disabled={!canEdit}
+              onClick={save}
+            >
+              保存配置
+            </Button>
+            <Text type="secondary">
+              累计播放 {cfg.total_plays} 次，已发币 {cfg.granted_plays} 次
+            </Text>
           </Space>
         </Space>
       )}
diff --git a/src/app/(main)/layout.tsx b/src/app/(main)/layout.tsx
index 24160dc..44a555a 100644
--- a/src/app/(main)/layout.tsx
+++ b/src/app/(main)/layout.tsx
@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from 'react';
 import { usePathname, useRouter } from 'next/navigation';
 import {
   BarChartOutlined,
+  ControlOutlined,
   DashboardOutlined,
   DatabaseOutlined,
   FileSearchOutlined,
@@ -105,6 +106,7 @@ const NAV_GROUPS: NavGroup[] = [
       { key: '/analytics-health', icon: <LineChartOutlined />, label: '埋点成功率' },
       { key: '/event-logs', icon: <DatabaseOutlined />, label: '埋点日志' },
       { key: '/audit-logs', icon: <FileSearchOutlined />, label: '审计日志' },
+      { key: '/limit-whitelist', icon: <ControlOutlined />, label: '限制策略' },
     ],
   },
 ];
diff --git a/src/app/(main)/limit-whitelist/page.tsx b/src/app/(main)/limit-whitelist/page.tsx
new file mode 100644
index 0000000..f720e76
--- /dev/null
+++ b/src/app/(main)/limit-whitelist/page.tsx
@@ -0,0 +1,1053 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import {
+  Alert,
+  App,
+  Button,
+  Card,
+  Checkbox,
+  DatePicker,
+  Form,
+  Input,
+  InputNumber,
+  Modal,
+  Popover,
+  Select,
+  Space,
+  Switch,
+  Table,
+  Tag,
+  Tabs,
+  Typography,
+} from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { EditOutlined, PlusOutlined, SearchOutlined } from '@ant-design/icons';
+import dayjs, { type Dayjs } from 'dayjs';
+
+import { api, errMsg } from '@/lib/api';
+import { formatUtcTime, utcDayjs } from '@/lib/format';
+import { usePagedList } from '@/lib/usePagedList';
+import type {
+  LimitOverride,
+  LimitRule,
+  LimitSubject,
+  LimitSubjectList,
+  LimitSubjectType,
+} from '@/lib/types';
+
+const { Text, Title } = Typography;
+
+const RULE_GROUPS = ['比价', '短信与登录', '广告', '引导与账号', '风控免告警'];
+
+const STATUS_META: Record<
+  LimitOverride['status'],
+  { label: string; color: string }
+> = {
+  active: { label: '生效中', color: 'success' },
+  scheduled: { label: '待生效', color: 'processing' },
+  expired: { label: '已失效', color: 'default' },
+  disabled: { label: '已停用', color: 'warning' },
+};
+
+interface OverrideFormValue {
+  subject_type: LimitSubjectType;
+  subject_value: string;
+  rule_codes: string[];
+  enabled?: boolean;
+  valid_range?: [number, number] | null;
+  reason?: string;
+}
+
+interface CreatePreset {
+  subject_type: LimitSubjectType;
+  subject_value: string;
+  rule_code: string;
+}
+
+interface WhitelistFilters {
+  keyword: string;
+  subjectType?: LimitSubjectType;
+  ruleCode?: string;
+}
+
+const asIso = (value?: number | null) =>
+  value ? dayjs(value).toISOString() : null;
+const showTime = (value: string | null) => formatUtcTime(value);
+const normalizeSubjectValue = (
+  subjectType: LimitSubjectType,
+  value: string,
+) =>
+  subjectType === 'phone'
+    ? value.replace(/\D/g, '')
+    : value.trim();
+
+interface RuleSelectorProps {
+  value?: string[];
+  onChange?: (value: string[]) => void;
+  rules: LimitRule[];
+  subjectType: LimitSubjectType;
+  activeGroup: string;
+  onActiveGroupChange: (group: string) => void;
+}
+
+function RuleSelector({
+  value = [],
+  onChange,
+  rules,
+  subjectType,
+  activeGroup,
+  onActiveGroupChange,
+}: RuleSelectorProps) {
+  return (
+    <Tabs
+      size="small"
+      activeKey={activeGroup}
+      onChange={onActiveGroupChange}
+      items={RULE_GROUPS.map((group) => {
+        const groupRules = rules.filter((rule) => rule.group === group);
+        const groupCodeSet = new Set(groupRules.map((rule) => rule.code));
+        const groupValues = value.filter((code) => groupCodeSet.has(code));
+        return {
+          key: group,
+          label: `${group}${groupValues.length ? ` (${groupValues.length})` : ''}`,
+          children: (
+            <Checkbox.Group
+              value={groupValues}
+              onChange={(values) => {
+                const otherGroupCodes = value.filter(
+                  (code) => !groupCodeSet.has(code),
+                );
+                const nextCodes = [
+                  ...otherGroupCodes,
+                  ...(values as string[]),
+                ];
+                onChange?.(nextCodes);
+              }}
+            >
+              <Space direction="vertical" size={10}>
+                {groupRules.map((rule) => {
+                  return (
+                    <Checkbox
+                      key={rule.code}
+                      value={rule.code}
+                      disabled={!rule.subject_types.includes(subjectType)}
+                    >
+                      {rule.label}
+                    </Checkbox>
+                  );
+                })}
+              </Space>
+            </Checkbox.Group>
+          ),
+        };
+      })}
+    />
+  );
+}
+
+export default function LimitWhitelistPage() {
+  const { message, modal } = App.useApp();
+  const [rules, setRules] = useState<LimitRule[]>([]);
+  const [keyword, setKeyword] = useState('');
+  const [subjectType, setSubjectType] = useState<LimitSubjectType | undefined>();
+  const [ruleFilter, setRuleFilter] = useState<string | undefined>();
+  const [appliedFilters, setAppliedFilters] = useState<WhitelistFilters>({
+    keyword: '',
+  });
+  const [editing, setEditing] = useState<LimitSubject | null>(null);
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [subjectInputSession, setSubjectInputSession] = useState(0);
+  const [editorRuleCodes, setEditorRuleCodes] = useState<string[]>([]);
+  const [ruleSelectionError, setRuleSelectionError] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [togglingSubject, setTogglingSubject] = useState<string | null>(null);
+  const [createPreset, setCreatePreset] = useState<CreatePreset | null>(null);
+  const [globalGroup, setGlobalGroup] = useState(RULE_GROUPS[0]);
+  const [editorRuleGroup, setEditorRuleGroup] = useState(RULE_GROUPS[0]);
+  const [globalRule, setGlobalRule] = useState<LimitRule | null>(null);
+  const [globalValue, setGlobalValue] = useState<number | null>(null);
+  const [globalSaving, setGlobalSaving] = useState(false);
+  const [form] = Form.useForm<OverrideFormValue>();
+  const watchedSubjectType = Form.useWatch('subject_type', form);
+  const effectiveSubjectType =
+    watchedSubjectType ||
+    editing?.subject_type ||
+    createPreset?.subject_type ||
+    'phone';
+
+  const subjectFilters = useMemo(
+    () => ({
+      keyword: appliedFilters.keyword.trim() || undefined,
+      subject_type: appliedFilters.subjectType,
+      rule_code: appliedFilters.ruleCode,
+    }),
+    [appliedFilters],
+  );
+  const {
+    items: rows,
+    total,
+    page,
+    pageSize,
+    loading,
+    onChange: onPageChange,
+    reload: reloadSubjects,
+  } = usePagedList<LimitSubject>(
+    '/admin/api/limit-whitelist/subjects',
+    subjectFilters,
+    10,
+    'offset',
+  );
+
+  useEffect(() => {
+    let active = true;
+    void api
+      .get<LimitRule[]>('/admin/api/limit-whitelist/rules')
+      .then((response) => {
+        if (active) setRules(response.data);
+      })
+      .catch((error) => {
+        if (active) message.error(errMsg(error, '限制规则加载失败'));
+      });
+    return () => {
+      active = false;
+    };
+  }, [message]);
+
+  const applyFilters = () => {
+    setAppliedFilters({
+      keyword,
+      subjectType,
+      ruleCode: ruleFilter,
+    });
+  };
+
+  const openCreate = () => {
+    setCreatePreset(null);
+    setEditing(null);
+    setEditorRuleGroup(RULE_GROUPS[0]);
+    setEditorRuleCodes([]);
+    setRuleSelectionError(false);
+    setSubjectInputSession((value) => value + 1);
+    setEditorOpen(true);
+  };
+
+  const openEdit = (row: LimitSubject) => {
+    setEditing(row);
+    const firstSelectedGroup = RULE_GROUPS.find(
+      (group) => (row.group_counts[group] || 0) > 0,
+    );
+    setEditorRuleGroup(firstSelectedGroup || RULE_GROUPS[0]);
+    setEditorRuleCodes(row.items.map((item) => item.rule_code));
+    setRuleSelectionError(false);
+    setSubjectInputSession((value) => value + 1);
+    setEditorOpen(true);
+  };
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (params.get('create') !== '1') return;
+    const subjectType = params.get('subject_type');
+    const subjectValue = params.get('subject_value');
+    const ruleCode = params.get('rule_code');
+    if (
+      (subjectType === 'phone' || subjectType === 'device') &&
+      subjectValue &&
+      ruleCode
+    ) {
+      setCreatePreset({
+        subject_type: subjectType,
+        subject_value: subjectValue,
+        rule_code: ruleCode,
+      });
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!createPreset || rules.length === 0 || editorOpen) return;
+    const presetRule = rules.find(
+      (rule) => rule.code === createPreset.rule_code,
+    );
+    setEditorRuleGroup(presetRule?.group || RULE_GROUPS[0]);
+    setEditing(null);
+    setEditorRuleCodes([createPreset.rule_code]);
+    setRuleSelectionError(false);
+    setSubjectInputSession((value) => value + 1);
+    setEditorOpen(true);
+  }, [createPreset, editorOpen, rules]);
+
+  const editorInitialValues = useMemo<Partial<OverrideFormValue>>(() => {
+    if (editing) {
+      const startsAt = editing.items
+        .map((item) => item.starts_at)
+        .filter((value): value is string => Boolean(value))
+        .sort();
+      const expiresAt = editing.items
+        .map((item) => item.expires_at)
+        .filter((value): value is string => Boolean(value))
+        .sort()
+        .at(-1);
+      const reasons = new Set(editing.items.map((item) => item.reason || ''));
+      return {
+        subject_type: editing.subject_type,
+        subject_value: editing.subject_value,
+        enabled: editing.items.every((item) => item.enabled),
+        valid_range: expiresAt
+          ? [
+              startsAt[0] ? utcDayjs(startsAt[0]).valueOf() : Date.now(),
+              utcDayjs(expiresAt).valueOf(),
+            ]
+          : null,
+        reason: reasons.size === 1 ? Array.from(reasons)[0] : '',
+      };
+    }
+    if (createPreset) {
+      return {
+        subject_type: createPreset.subject_type,
+        subject_value: createPreset.subject_value,
+        valid_range: [Date.now(), dayjs().add(1, 'month').valueOf()],
+      };
+    }
+    return {
+      subject_type: 'phone',
+      valid_range: [Date.now(), dayjs().add(1, 'month').valueOf()],
+    };
+  }, [createPreset, editing, editorOpen]);
+
+  const saveOverride = async () => {
+    let value: OverrideFormValue;
+    try {
+      value = await form.validateFields();
+    } catch {
+      return;
+    }
+    if (editorRuleCodes.length === 0) {
+      setRuleSelectionError(true);
+      message.error('请选择解除限制项');
+      return;
+    }
+    value.rule_codes = editorRuleCodes;
+    const normalizedSubjectValue = normalizeSubjectValue(
+      value.subject_type,
+      value.subject_value,
+    );
+    if (!normalizedSubjectValue) {
+      message.error(
+        value.subject_type === 'phone'
+          ? '请输入有效手机号'
+          : '请输入有效设备 ID',
+      );
+      return;
+    }
+    if (!editing) {
+      setSaving(true);
+      let existingSubject: LimitSubject | undefined;
+      try {
+        const response = await api.get<LimitSubjectList>(
+          '/admin/api/limit-whitelist/subjects',
+          {
+            params: {
+              subject_type: value.subject_type,
+              keyword: normalizedSubjectValue,
+              offset: 0,
+              limit: 100,
+            },
+          },
+        );
+        existingSubject = response.data.items.find(
+          (item) =>
+            item.subject_type === value.subject_type &&
+            item.subject_value === normalizedSubjectValue,
+        );
+      } catch (error) {
+        message.error(errMsg(error, '白名单重复配置检查失败'));
+        return;
+      } finally {
+        setSaving(false);
+      }
+
+      if (existingSubject) {
+        const isPhone = value.subject_type === 'phone';
+        const confirmed = await new Promise<boolean>((resolve) => {
+          modal.confirm({
+            title: isPhone
+              ? '该手机号已有白名单配置'
+              : '该设备已有白名单配置',
+            content: isPhone
+              ? '该手机号已有白名单配置，新增配置是以追加配置的方式；有效期将统一为本次配置的有效期。'
+              : '该设备已有白名单配置，新增配置是以追加配置的方式；有效期将统一为本次配置的有效期。',
+            okText: '确认追加',
+            cancelText: '取消',
+            onOk: () => resolve(true),
+            onCancel: () => resolve(false),
+          });
+        });
+        if (!confirmed) return;
+      }
+    }
+
+    setSaving(true);
+    try {
+      const [startsAt, expiresAt] = value.valid_range || [];
+      const enabled = editing ? value.enabled : true;
+      if (editing) {
+        await api.put('/admin/api/limit-whitelist/subjects', {
+          subject_type: value.subject_type,
+          subject_value: normalizedSubjectValue,
+          rule_codes: value.rule_codes,
+          enabled,
+          starts_at: asIso(startsAt),
+          expires_at: asIso(expiresAt),
+          reason: value.reason || '',
+        });
+      } else {
+        await api.post('/admin/api/limit-whitelist/bulk', {
+          subject_type: value.subject_type,
+          subject_value: normalizedSubjectValue,
+          rule_codes: value.rule_codes,
+          enabled,
+          starts_at: asIso(startsAt),
+          expires_at: asIso(expiresAt),
+          reason: value.reason || '',
+        });
+      }
+      message.success(
+        editing
+          ? '白名单配置已更新'
+          : `已新增 ${value.rule_codes.length} 条白名单配置`,
+      );
+      setEditorOpen(false);
+      setCreatePreset(null);
+      if (new URLSearchParams(window.location.search).get('create') === '1') {
+        window.history.replaceState({}, '', window.location.pathname);
+      }
+      await reloadSubjects();
+    } catch (error) {
+      message.error(errMsg(error));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const saveGlobal = async () => {
+    if (!globalRule || globalValue == null) return;
+    setGlobalSaving(true);
+    try {
+      await api.patch(`/admin/api/limit-whitelist/rules/${globalRule.code}`, {
+        value: globalValue,
+      });
+      message.success('全局限制已更新，业务接口即时读取新值');
+      setGlobalRule(null);
+      const response = await api.get<LimitRule[]>(
+        '/admin/api/limit-whitelist/rules',
+      );
+      setRules(response.data);
+    } catch (error) {
+      message.error(errMsg(error));
+    } finally {
+      setGlobalSaving(false);
+    }
+  };
+
+  const toggleSubject = async (row: LimitSubject, enabled: boolean) => {
+    const subjectKey = `${row.subject_type}:${row.subject_value}`;
+    setTogglingSubject(subjectKey);
+    try {
+      await api.patch('/admin/api/limit-whitelist/subjects/enabled', {
+        subject_type: row.subject_type,
+        subject_value: row.subject_value,
+        enabled,
+      });
+      message.success(enabled ? '白名单已启用' : '白名单已停用');
+      await reloadSubjects();
+    } catch (error) {
+      message.error(errMsg(error, '白名单启用状态更新失败'));
+      await reloadSubjects();
+    } finally {
+      setTogglingSubject(null);
+    }
+  };
+
+  const ruleColumns: ColumnsType<LimitRule> = [
+    {
+      title: '限制项',
+      key: 'rule',
+      render: (_, row) => <Text strong>{row.label}</Text>,
+    },
+    { title: '统计窗口', dataIndex: 'window_label', width: 180 },
+    {
+      title: '全局值',
+      dataIndex: 'global_limit',
+      width: 110,
+      render: (value) => <Text strong>{value}</Text>,
+    },
+    {
+      title: '可识别主体',
+      dataIndex: 'subject_types',
+      width: 150,
+      render: (values: LimitSubjectType[]) => (
+        <Space size={4}>
+          {values.map((value) => (
+            <Tag key={value}>{value === 'phone' ? '手机号' : '设备'}</Tag>
+          ))}
+        </Space>
+      ),
+    },
+    {
+      title: '操作',
+      width: 90,
+      render: (_, row) => (
+        <Button
+          type="link"
+          icon={<EditOutlined />}
+          onClick={() => {
+            setGlobalRule(row);
+            setGlobalValue(row.global_limit);
+          }}
+        >
+          修改
+        </Button>
+      ),
+    },
+  ];
+
+  const columns: ColumnsType<LimitSubject> = [
+    {
+      title: '类型',
+      dataIndex: 'subject_type',
+      width: 110,
+      render: (value: LimitSubjectType) => (
+        <Tag color={value === 'device' ? 'cyan' : 'blue'}>
+          {value === 'device' ? '设备 ID' : '手机号'}
+        </Tag>
+      ),
+    },
+    {
+      title: '手机号 / 设备 ID',
+      dataIndex: 'subject_value',
+      width: 220,
+      render: (value: string) => <Text>{value}</Text>,
+    },
+    {
+      title: '解除限制项',
+      key: 'rule',
+      render: (_, row) => {
+        const groupCounts = row.group_counts;
+        return (
+          <Popover
+            trigger={['hover', 'click']}
+            placement="topLeft"
+            mouseEnterDelay={0.15}
+            title="解除限制项明细"
+            content={
+              <div
+                style={{
+                  width: 380,
+                  maxHeight: 420,
+                  overflowY: 'auto',
+                  paddingRight: 4,
+                }}
+              >
+                {RULE_GROUPS.map((group, groupIndex) => {
+                  const items = row.items.filter(
+                    (item) => item.rule_group === group,
+                  );
+                  return (
+                    <div
+                      key={group}
+                      style={{
+                        paddingBlock: 8,
+                        borderTop:
+                          groupIndex === 0 ? undefined : '1px solid #f0f0f0',
+                      }}
+                    >
+                      <div
+                        style={{
+                          display: 'flex',
+                          alignItems: 'center',
+                          justifyContent: 'space-between',
+                          marginBottom: items.length ? 4 : 0,
+                        }}
+                      >
+                        <Text strong>{group}</Text>
+                        <Text type="secondary">{items.length} 项</Text>
+                      </div>
+                      {items.length ? (
+                        items.map((item) => (
+                          <div
+                            key={item.id}
+                            style={{
+                              display: 'flex',
+                              alignItems: 'center',
+                              justifyContent: 'space-between',
+                              gap: 12,
+                              minHeight: 30,
+                              paddingLeft: 12,
+                            }}
+                          >
+                            <Text>{item.rule_label}</Text>
+                            <Tag
+                              color={STATUS_META[item.status].color}
+                              style={{ flexShrink: 0, marginInlineEnd: 0 }}
+                            >
+                              {STATUS_META[item.status].label}
+                            </Tag>
+                          </div>
+                        ))
+                      ) : (
+                        <Text type="secondary" style={{ paddingLeft: 12 }}>
+                          暂无配置
+                        </Text>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            }
+          >
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                flexWrap: 'wrap',
+                gap: '8px 18px',
+                cursor: 'help',
+              }}
+            >
+              {RULE_GROUPS.map((group) => {
+                const count = groupCounts[group] || 0;
+                return (
+                  <span
+                    key={group}
+                    style={{
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      gap: 6,
+                      whiteSpace: 'nowrap',
+                    }}
+                  >
+                    {group}
+                    <span
+                      style={{
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        minWidth: 22,
+                        height: 22,
+                        padding: '0 6px',
+                        borderRadius: 6,
+                        border: '1px solid #d9d9d9',
+                        background: '#fafafa',
+                        color: 'rgba(0, 0, 0, 0.65)',
+                        fontSize: 12,
+                        lineHeight: 1,
+                      }}
+                    >
+                      {count}
+                    </span>
+                  </span>
+                );
+              })}
+            </div>
+          </Popover>
+        );
+      },
+    },
+    {
+      title: '有效期',
+      key: 'time',
+      width: 190,
+      render: (_, row) => {
+        const startsAt = Array.from(
+          new Set(row.items.map((item) => item.starts_at)),
+        );
+        const expiresAt = Array.from(
+          new Set(row.items.map((item) => item.expires_at)),
+        ).sort();
+        if (startsAt.length === 1 && expiresAt.length === 1) {
+          return (
+            <Space direction="vertical" size={0}>
+              <Text>{showTime(startsAt[0])}</Text>
+              <Text type="secondary">至 {showTime(expiresAt[0])}</Text>
+            </Space>
+          );
+        }
+        return (
+          <Space direction="vertical" size={0}>
+            <Text>共 {row.total_rules} 条配置</Text>
+            <Text type="secondary">
+              最早失效 {showTime(expiresAt[0] || null)}
+            </Text>
+            <Text type="secondary">
+              最晚失效 {showTime(expiresAt.at(-1) || null)}
+            </Text>
+          </Space>
+        );
+      },
+    },
+    {
+      title: '状态',
+      key: 'status',
+      width: 190,
+      render: (_, row) => {
+        const counts = row.items.reduce<
+          Partial<Record<LimitOverride['status'], number>>
+        >((result, item) => {
+          result[item.status] = (result[item.status] || 0) + 1;
+          return result;
+        }, {});
+        return (
+          <Space size={[0, 4]} wrap>
+            {Object.entries(STATUS_META).map(([status, meta]) =>
+              counts[status as LimitOverride['status']] ? (
+                <Tag key={status} color={meta.color}>
+                  {meta.label}
+                </Tag>
+              ) : null,
+            )}
+          </Space>
+        );
+      },
+    },
+    {
+      title: '备注',
+      key: 'reason',
+      width: 220,
+      render: (_, row) => {
+        const reasons = Array.from(
+          new Set(
+            row.items
+              .map((item) => item.reason)
+              .filter((value): value is string => Boolean(value)),
+          ),
+        );
+        const text =
+          reasons.length <= 1
+            ? reasons[0] || '-'
+            : `${reasons[0]} 等 ${reasons.length} 种`;
+        return <Text ellipsis={{ tooltip: reasons.join('；') }}>{text}</Text>;
+      },
+    },
+    {
+      title: '启用',
+      key: 'enabled',
+      width: 90,
+      render: (_, row) => {
+        const subjectKey = `${row.subject_type}:${row.subject_value}`;
+        return (
+          <Switch
+            size="small"
+            checked={row.items.every((item) => item.enabled)}
+            loading={togglingSubject === subjectKey}
+            onChange={(enabled) => void toggleSubject(row, enabled)}
+          />
+        );
+      },
+    },
+    {
+      title: '编辑',
+      key: 'edit',
+      width: 90,
+      fixed: 'right',
+      render: (_, row) => (
+        <Button
+          type="link"
+          icon={<EditOutlined />}
+          onClick={() => openEdit(row)}
+        >
+          编辑
+        </Button>
+      ),
+    },
+  ];
+
+  return (
+    <div>
+      <Space align="start" style={{ width: '100%', marginBottom: 16 }}>
+        <div>
+          <Title level={2} style={{ marginBottom: 4 }}>
+            限制策略与白名单
+          </Title>
+          <Text type="secondary">
+            统一管理限制全局值，并按手机号或设备设置临时白名单。
+          </Text>
+        </div>
+      </Space>
+
+      <Card title="全局限制" style={{ marginBottom: 16 }}>
+        <Tabs
+          activeKey={globalGroup}
+          onChange={setGlobalGroup}
+          items={RULE_GROUPS.map((group) => ({
+            key: group,
+            label: group,
+            children: (
+              <Table<LimitRule>
+                size="small"
+                rowKey="code"
+                pagination={false}
+                columns={ruleColumns}
+                dataSource={rules.filter((rule) => rule.group === group)}
+              />
+            ),
+          }))}
+        />
+      </Card>
+
+      <Card
+        title={
+          <Space size={12}>
+            <span>白名单配置</span>
+            <Button
+              type="primary"
+              size="small"
+              icon={<PlusOutlined />}
+              onClick={openCreate}
+            >
+              新增白名单
+            </Button>
+          </Space>
+        }
+        extra={
+          <Space wrap>
+            <Select
+              allowClear
+              placeholder="类型"
+              style={{ width: 120 }}
+              value={subjectType}
+              onChange={setSubjectType}
+              options={[
+                { value: 'phone', label: '手机号' },
+                { value: 'device', label: '设备 ID' },
+              ]}
+            />
+            <Select
+              allowClear
+              showSearch
+              optionFilterProp="label"
+              placeholder="解除限制项"
+              style={{ width: 240 }}
+              value={ruleFilter}
+              onChange={setRuleFilter}
+              options={rules.map((rule) => ({
+                value: rule.code,
+                label: rule.label,
+              }))}
+            />
+            <Input
+              allowClear
+              placeholder="搜索手机号或设备"
+              style={{ width: 240 }}
+              value={keyword}
+              onChange={(event) => setKeyword(event.target.value)}
+              onPressEnter={applyFilters}
+            />
+            <Button
+              type="primary"
+              icon={<SearchOutlined />}
+              onClick={applyFilters}
+            >
+              筛选
+            </Button>
+          </Space>
+        }
+      >
+        <Table<LimitSubject>
+          rowKey={(row) => `${row.subject_type}:${row.subject_value}`}
+          loading={loading}
+          columns={columns}
+          dataSource={rows}
+          scroll={{ x: 1700 }}
+          pagination={{
+            current: page,
+            pageSize,
+            total,
+            showSizeChanger: true,
+            pageSizeOptions: [10, 20, 50],
+            showTotal: (count) => `共 ${count} 个主体`,
+            onChange: onPageChange,
+          }}
+        />
+      </Card>
+
+      <Modal
+        title={editing ? '编辑白名单配置' : '新增白名单配置'}
+        open={editorOpen}
+        okText="保存"
+        cancelText="取消"
+        confirmLoading={saving}
+        onOk={() => void saveOverride()}
+        onCancel={() => {
+          setEditorOpen(false);
+          setCreatePreset(null);
+          if (
+            new URLSearchParams(window.location.search).get('create') === '1'
+          ) {
+            window.history.replaceState({}, '', window.location.pathname);
+          }
+        }}
+        destroyOnHidden
+      >
+        <Form
+          form={form}
+          layout="vertical"
+          preserve={false}
+          autoComplete="off"
+          initialValues={editorInitialValues}
+        >
+          <Form.Item
+            name="subject_type"
+            label="主体类型"
+            rules={[{ required: true }]}
+          >
+            <Select
+              disabled={!!editing}
+              onChange={(value: LimitSubjectType) => {
+                setSubjectInputSession((session) => session + 1);
+                form.resetFields(['subject_value']);
+                const compatibleCodes = new Set(
+                  rules
+                    .filter((rule) => rule.subject_types.includes(value))
+                    .map((rule) => rule.code),
+                );
+                const nextCodes = editorRuleCodes.filter((code) =>
+                  compatibleCodes.has(code),
+                );
+                setEditorRuleCodes(nextCodes);
+                setRuleSelectionError(false);
+              }}
+              options={[
+                { value: 'phone', label: '手机号' },
+                { value: 'device', label: '设备 ID' },
+              ]}
+            />
+          </Form.Item>
+          <Form.Item
+            name="subject_value"
+            label={effectiveSubjectType === 'phone' ? '手机号' : '设备 ID'}
+            rules={[
+              {
+                required: true,
+                message:
+                  effectiveSubjectType === 'phone'
+                    ? '请输入手机号'
+                    : '请输入设备 ID',
+              },
+            ]}
+          >
+            <Input
+              key={`${effectiveSubjectType}-${subjectInputSession}`}
+              id={`limit-whitelist-${effectiveSubjectType}-${subjectInputSession}`}
+              name={`limit-whitelist-${effectiveSubjectType}-${subjectInputSession}`}
+              disabled={!!editing}
+              autoComplete="off"
+              aria-label={
+                effectiveSubjectType === 'phone' ? '手机号' : '设备 ID'
+              }
+              aria-autocomplete="none"
+              data-lpignore="true"
+              data-1p-ignore="true"
+              maxLength={effectiveSubjectType === 'phone' ? 20 : 128}
+              placeholder={
+                effectiveSubjectType === 'phone'
+                  ? '请输入手机号'
+                  : '请输入设备 ID'
+              }
+            />
+          </Form.Item>
+          <Form.Item
+            name="valid_range"
+            label="有效期"
+            getValueProps={(value?: [number, number] | null) => ({
+              value: value
+                ? [dayjs(value[0]), dayjs(value[1])]
+                : null,
+            })}
+            getValueFromEvent={(value: [Dayjs, Dayjs] | null) =>
+              value
+                ? [value[0].valueOf(), value[1].valueOf()]
+                : null
+            }
+            rules={[
+              { required: true, message: '请选择生效和结束时间' },
+              {
+                validator: async (_, value?: [number, number]) => {
+                  if (!value?.[0] || !value?.[1]) {
+                    throw new Error('请选择完整的生效和结束时间');
+                  }
+                  if (value[1] <= value[0]) {
+                    throw new Error('结束时间必须晚于生效时间');
+                  }
+                  if (value[1] <= Date.now()) {
+                    throw new Error('结束时间必须晚于当前时间');
+                  }
+                },
+              },
+            ]}
+          >
+            <DatePicker.RangePicker
+              showTime
+              style={{ width: '100%' }}
+              placeholder={['生效时间', '结束时间']}
+            />
+          </Form.Item>
+          <Form.Item
+            label="解除限制项"
+            required
+            validateStatus={ruleSelectionError ? 'error' : undefined}
+            help={ruleSelectionError ? '请选择解除限制项' : undefined}
+          >
+            <RuleSelector
+              value={editorRuleCodes}
+              onChange={(value) => {
+                setEditorRuleCodes(value);
+                setRuleSelectionError(false);
+              }}
+              rules={rules}
+              subjectType={effectiveSubjectType}
+              activeGroup={editorRuleGroup}
+              onActiveGroupChange={setEditorRuleGroup}
+            />
+          </Form.Item>
+          {editing && (
+            <Form.Item name="enabled" label="启用" valuePropName="checked">
+              <Switch />
+            </Form.Item>
+          )}
+          <Form.Item name="reason" label="备注">
+            <Input.TextArea maxLength={256} showCount rows={3} />
+          </Form.Item>
+        </Form>
+      </Modal>
+
+      <Modal
+        title={`修改全局限制：${globalRule?.label || ''}`}
+        open={!!globalRule}
+        okText="保存"
+        cancelText="取消"
+        confirmLoading={globalSaving}
+        onOk={() => void saveGlobal()}
+        onCancel={() => setGlobalRule(null)}
+      >
+        <Alert
+          type="warning"
+          showIcon
+          style={{ marginBottom: 16 }}
+          message="保存后所有未覆盖该规则的用户立即使用新值。"
+        />
+        <InputNumber
+          value={globalValue}
+          min={globalRule?.min_value}
+          max={globalRule?.max_value}
+          precision={0}
+          style={{ width: '100%' }}
+          onChange={setGlobalValue}
+        />
+        <Text type="secondary">
+          允许范围：{globalRule?.min_value}～{globalRule?.max_value}；系统初始值：
+          {globalRule?.default_limit}
+        </Text>
+      </Modal>
+    </div>
+  );
+}
diff --git a/src/app/(main)/risk-monitor/page.tsx b/src/app/(main)/risk-monitor/page.tsx
index 3d46201..272f2fe 100644
--- a/src/app/(main)/risk-monitor/page.tsx
+++ b/src/app/(main)/risk-monitor/page.tsx
@@ -19,10 +19,12 @@ import {
   CopyOutlined,
   DownOutlined,
   EditOutlined,
+  PlusCircleOutlined,
   ReloadOutlined,
   RightOutlined,
 } from '@ant-design/icons';
 import dayjs from 'dayjs';
+import { useRouter } from 'next/navigation';
 import { api, errMsg } from '@/lib/api';
 import { formatUtcTime, utcDayjs } from '@/lib/format';
 import type {
@@ -69,8 +71,8 @@ type IncidentStatus = 'open' | 'blocked';
 const RULE_LIMITS: Record<RiskKind, { min: number; max: number; help: string }> = {
   sms: {
     min: 1,
-    max: 5,
-    help: '统计成功下发；最高5次，与现有每设备每小时发送上限一致。',
+    max: 100000,
+    help: '统计成功下发；告警阈值与短信硬限制分别配置。',
   },
   oneclick: {
     min: 1,
@@ -79,8 +81,8 @@ const RULE_LIMITS: Record<RiskKind, { min: number; max: number; help: string }>
   },
   compare: {
     min: 1,
-    max: 100,
-    help: '同一账户按北京时间自然日累计；最高100次，与比价每日上限一致。',
+    max: 100000,
+    help: '同一账户按北京时间自然日累计；告警阈值与比价硬限制分别配置。',
   },
 };
 const utcTime = (value: string | null, withDate = true) =>
@@ -271,6 +273,7 @@ function DetailTable({
 }
 
 export default function RiskMonitorPage() {
+  const router = useRouter();
   const { message, modal } = App.useApp();
   const [summary, setSummary] = useState<RiskMonitorSummary | null>(null);
   const [lists, setLists] = useState<Partial<Record<RiskKind, RiskIncidentPage>>>({});
@@ -597,6 +600,40 @@ export default function RiskMonitorPage() {
     [lists, loadAll, message, modal],
   );
 
+  const addToWhitelist = useCallback(
+    (row: RiskIncidentItem) => {
+      const isCompare = row.kind === 'compare';
+      const subjectValue = isCompare ? row.phone : row.subject_id;
+      if (!isCompare && subjectValue?.startsWith('legacy-ip:')) {
+        void message.error(
+          '旧客户端未上报真实设备 ID，无法加入设备白名单，请升级客户端后重试',
+        );
+        return;
+      }
+      if (!subjectValue) {
+        void message.error(
+          isCompare
+            ? '该风险记录没有关联手机号，暂时无法加入白名单'
+            : '该风险记录没有设备 ID，暂时无法加入白名单',
+        );
+        return;
+      }
+      const ruleCode: Record<RiskKind, string> = {
+        sms: 'risk.sms.hourly',
+        oneclick: 'risk.oneclick.daily',
+        compare: 'risk.compare.daily',
+      };
+      const params = new URLSearchParams({
+        create: '1',
+        subject_type: isCompare ? 'phone' : 'device',
+        subject_value: subjectValue,
+        rule_code: ruleCode[row.kind],
+      });
+      router.push(`/limit-whitelist?${params.toString()}`);
+    },
+    [message, router],
+  );
+
   const columns = useCallback(
     (kind: RiskKind): ColumnsType<RiskIncidentItem> => {
       const actionColumn = {
@@ -604,9 +641,18 @@ export default function RiskMonitorPage() {
         key: 'actions',
         align: 'right' as const,
         fixed: 'right' as const,
-        width: 180,
+        width: 280,
         render: (_: unknown, row: RiskIncidentItem) => {
           const open = expanded.has(row.incident_id);
+          const whitelistUnavailableReason =
+            row.kind === 'compare'
+              ? row.phone
+                ? undefined
+                : '该风险记录没有关联手机号，暂时无法加入白名单'
+              : row.subject_id.startsWith('legacy-ip:')
+                ? '旧客户端未上报真实设备 ID，无法加入设备白名单'
+                : undefined;
+          const canAddToWhitelist = !whitelistUnavailableReason;
           return (
             <span className={styles.actionGroup}>
               <Button
@@ -618,6 +664,20 @@ export default function RiskMonitorPage() {
               >
                 {open ? '收起' : '展开'}
               </Button>
+              <Tooltip
+                title={whitelistUnavailableReason}
+              >
+                <span>
+                  <Button
+                    size="small"
+                    icon={<PlusCircleOutlined />}
+                    disabled={!canAddToWhitelist}
+                    onClick={() => addToWhitelist(row)}
+                  >
+                    加入白名单
+                  </Button>
+                </span>
+              </Tooltip>
               {row.status === 'open' && (
                 <>
                   <Button
@@ -700,7 +760,16 @@ export default function RiskMonitorPage() {
         actionColumn,
       ];
     },
-    [acting, copy, detailLoading, expanded, revokeRestriction, runAction, toggle],
+    [
+      acting,
+      addToWhitelist,
+      copy,
+      detailLoading,
+      expanded,
+      revokeRestriction,
+      runAction,
+      toggle,
+    ],
   );
 
   const cards = useMemo(() => {
diff --git a/src/lib/types.ts b/src/lib/types.ts
index de37144..584b35c 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -414,14 +414,14 @@ export interface FeedbackQrConfig {
   updated_at: string | null;
 }
 
-/** 领券等候浮层的「新手引导视频」配置(前 3 次用它替代广告,每次固定 120 金币)。
+/** 领券等候浮层的「新手引导视频」配置(前 3 次用它替代广告,默认每次固定 100 金币)。
  *  后台只开放 enabled + 换片;下面几个字段接口仍返回,但页面不展示、也不回传。 */
 export interface GuideVideoConfig {
   scene: 'coupon' | 'comparison';
   enabled: boolean;
   video_url: string | null; // /media/guide_video/xxx.mp4;null = 未配片(浮层照旧只放广告)
   max_plays: number; // 每个账号前 N 次浮层放引导视频(服务端默认 3,后台不开放调整)
-  reward_coin: number; // 每次固定金币(服务端默认 120,播完 / 中途关闭都发)
+  reward_coin: number; // 每次固定金币(服务端默认 100,播完 / 中途关闭都发)
   updated_at: string | null;
   total_plays: number; // 只读统计:全站已播次数(后台不再展示)
   granted_plays: number; // 只读统计:其中已发币次数(后台不再展示)
@@ -895,3 +895,80 @@ export interface HealthTrendPoint extends HealthMetrics {
 export interface HealthBreakdownRow extends HealthMetrics {
   key: string; // 维度值(event 名 / app_ver / oem);缺失为 "(unknown)"
 }
+
+// ===== 统一限制策略 / 白名单 =====
+export type LimitSubjectType = 'phone' | 'device';
+export type LimitPolicyMode =
+  | 'inherit'
+  | 'override'
+  | 'unlimited'
+  | 'suppress_alert';
+
+export interface LimitRule {
+  code: string;
+  label: string;
+  group: string;
+  global_limit: number;
+  default_limit: number;
+  window_label: string;
+  subject_types: LimitSubjectType[];
+  allowed_modes: LimitPolicyMode[];
+  min_value: number;
+  max_value: number;
+  supports_reset: boolean;
+  alert_only: boolean;
+}
+
+export interface LimitDeviceCandidate {
+  device_id: string;
+  source: string;
+  source_label: string;
+  user_id: number | null;
+  username: string | null;
+  phone: string | null;
+  nickname: string | null;
+  device_model: string | null;
+  last_active_at: string;
+}
+
+export interface LimitOverride {
+  id: number;
+  subject_type: LimitSubjectType;
+  subject_value: string;
+  rule_code: string;
+  rule_label: string;
+  rule_group: string;
+  mode: LimitPolicyMode;
+  limit_value: number | null;
+  global_limit: number;
+  effective_limit: number | null;
+  enabled: boolean;
+  starts_at: string | null;
+  expires_at: string | null;
+  reset_at: string | null;
+  reason: string | null;
+  status: 'active' | 'scheduled' | 'expired' | 'disabled';
+  created_by_admin_id: number | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface LimitOverrideList {
+  items: LimitOverride[];
+  total: number;
+}
+
+export interface LimitSubject {
+  subject_type: LimitSubjectType;
+  subject_value: string;
+  group_counts: Record<string, number>;
+  total_rules: number;
+  items: LimitOverride[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface LimitSubjectList {
+  items: LimitSubject[];
+  total: number;
+}
diff --git a/src/lib/usePagedList.ts b/src/lib/usePagedList.ts
index 00cad8f..697a390 100644
--- a/src/lib/usePagedList.ts
+++ b/src/lib/usePagedList.ts
@@ -15,6 +15,7 @@ export function usePagedList<T>(
   url: string,
   filters: Record<string, unknown>,
   initialPageSize = 20,
+  offsetParam: 'cursor' | 'offset' = 'cursor',
 ) {
   const [items, setItems] = useState<T[]>([]);
   const [total, setTotal] = useState(0);
@@ -31,7 +32,11 @@ export function usePagedList<T>(
       requestSeq.current = seq;
       setLoading(true);
       try {
-        const params = { ...JSON.parse(filtersKey), limit: ps, cursor: (p - 1) * ps };
+        const params = {
+          ...JSON.parse(filtersKey),
+          limit: ps,
+          [offsetParam]: (p - 1) * ps,
+        };
         const { data } = await api.get<CursorPage<T>>(url, { params });
         if (requestSeq.current !== seq) return; // 丢弃过期响应(快速切页/筛选)
         setItems(data.items);
@@ -40,7 +45,7 @@ export function usePagedList<T>(
         if (requestSeq.current === seq) setLoading(false);
       }
     },
-    [url, filtersKey],
+    [url, filtersKey, offsetParam],
   );
 
   // 筛选变化:回第 1 页重载