feat: add multi-channel subscription blocking UI and admin management

- Channel subscription blocking screen with per-channel status display - Safe URL handling with protocol validation (no open redirect) - Race-condition-safe subscription check with useRef guard - Admin channel management page with create, toggle, delete - Error handlers on all admin mutations with haptic feedback - Proper type guard for channel subscription error detection - Accessibility: aria-labels on icon-only buttons - Localization: en, ru, zh, fa translations
2026-07-28 09:33:46 +00:00 · 2026-02-24 02:50:52 +03:00
parent 8ea9a1d6a0
commit a767fe96d3
12 changed files with 758 additions and 113 deletions
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -87,6 +87,7 @@ const AdminUserDetail = lazy(() => import('./pages/AdminUserDetail'));
 const AdminBroadcastDetail = lazy(() => import('./pages/AdminBroadcastDetail'));
 const AdminPinnedMessages = lazy(() => import('./pages/AdminPinnedMessages'));
 const AdminPinnedMessageCreate = lazy(() => import('./pages/AdminPinnedMessageCreate'));
+const AdminChannelSubscriptions = lazy(() => import('./pages/AdminChannelSubscriptions'));
 const AdminEmailTemplatePreview = lazy(() => import('./pages/AdminEmailTemplatePreview'));

 function ProtectedRoute({ children }: { children: React.ReactNode }) {
@@ -854,6 +855,16 @@ function App() {
            </AdminRoute>
          }
        />
+        <Route
+          path="/admin/channel-subscriptions"
+          element={
+            <AdminRoute>
+              <LazyPage>
+                <AdminChannelSubscriptions />
+              </LazyPage>
+            </AdminRoute>
+          }
+        />
        <Route
          path="/admin/email-templates/preview/:type/:lang"
          element={
--- a/src/api/adminChannels.ts
+++ b/src/api/adminChannels.ts
@@ -0,0 +1,68 @@
+import apiClient from './client';
+
+// Types
+export interface RequiredChannel {
+  id: number;
+  channel_id: string;
+  channel_link: string | null;
+  title: string | null;
+  is_active: boolean;
+  sort_order: number;
+}
+
+export interface ChannelListResponse {
+  items: RequiredChannel[];
+  total: number;
+}
+
+export interface CreateChannelRequest {
+  channel_id: string;
+  channel_link?: string;
+  title?: string;
+}
+
+export interface UpdateChannelRequest {
+  channel_id?: string;
+  channel_link?: string;
+  title?: string;
+  is_active?: boolean;
+  sort_order?: number;
+}
+
+export const adminChannelsApi = {
+  list: async (): Promise<ChannelListResponse> => {
+    const { data } = await apiClient.get<ChannelListResponse>(
+      '/cabinet/admin/channel-subscriptions',
+    );
+    return data;
+  },
+
+  create: async (req: CreateChannelRequest): Promise<RequiredChannel> => {
+    const { data } = await apiClient.post<RequiredChannel>(
+      '/cabinet/admin/channel-subscriptions',
+      req,
+    );
+    return data;
+  },
+
+  update: async (id: number, req: UpdateChannelRequest): Promise<RequiredChannel> => {
+    const { data } = await apiClient.patch<RequiredChannel>(
+      `/cabinet/admin/channel-subscriptions/${id}`,
+      req,
+    );
+    return data;
+  },
+
+  toggle: async (id: number): Promise<RequiredChannel> => {
+    const { data } = await apiClient.post<RequiredChannel>(
+      `/cabinet/admin/channel-subscriptions/${id}/toggle`,
+    );
+    return data;
+  },
+
+  delete: async (id: number): Promise<void> => {
+    await apiClient.delete(`/cabinet/admin/channel-subscriptions/${id}`);
+  },
+};
+
+export default adminChannelsApi;
--- a/src/api/client.ts
+++ b/src/api/client.ts
@@ -133,6 +133,12 @@ export interface ChannelSubscriptionError {
  code: 'channel_subscription_required';
  message: string;
  channel_link?: string;
+  channels?: Array<{
+    channel_id: string;
+    channel_link?: string;
+    title?: string;
+    is_subscribed: boolean;
+  }>;
 }

 export interface BlacklistedError {
@@ -189,6 +195,7 @@ apiClient.interceptors.response.use(
      useBlockingStore.getState().setChannelSubscription({
        message: detail.message,
        channel_link: detail.channel_link,
+        channels: detail.channels,
      });
      return Promise.reject(error);
    }
--- a/src/api/index.ts
+++ b/src/api/index.ts
@@ -12,6 +12,7 @@ export { infoApi } from './info';
 export { adminSettingsApi } from './adminSettings';
 export { adminApi, statsApi } from './admin';
 export { adminAppsApi } from './adminApps';
+export { adminChannelsApi } from './adminChannels';
 export { adminBroadcastsApi } from './adminBroadcasts';
 export { adminEmailTemplatesApi } from './adminEmailTemplates';
 export { adminPaymentMethodsApi } from './adminPaymentMethods';
--- a/src/components/blocking/ChannelSubscriptionScreen.tsx
+++ b/src/components/blocking/ChannelSubscriptionScreen.tsx
@@ -1,10 +1,22 @@
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useBlockingStore } from '../../store/blocking';
-import { apiClient } from '../../api/client';
+import { apiClient, isChannelSubscriptionError } from '../../api/client';

 const CHECK_COOLDOWN_SECONDS = 5;

+function safeOpenUrl(url: string | undefined | null): void {
+  if (!url) return;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === 'https:' || parsed.protocol === 'http:') {
+      window.open(url, '_blank', 'noopener,noreferrer');
+    }
+  } catch {
+    // invalid URL, do nothing
+  }
+}
+
 export default function ChannelSubscriptionScreen() {
  const { t } = useTranslation();
  const channelInfo = useBlockingStore((state) => state.channelInfo);
@@ -12,6 +24,7 @@ export default function ChannelSubscriptionScreen() {
  const [isChecking, setIsChecking] = useState(false);
  const [cooldown, setCooldown] = useState(0);
  const [error, setError] = useState<string | null>(null);
+  const isCheckingRef = useRef(false);

  // Cooldown timer
  useEffect(() => {
@@ -30,43 +43,30 @@ export default function ChannelSubscriptionScreen() {
    return () => clearInterval(timer);
  }, [cooldown]);

-  const openChannel = useCallback(() => {
-    if (channelInfo?.channel_link) {
-      window.open(channelInfo.channel_link, '_blank');
-    }
-  }, [channelInfo?.channel_link]);
+  const channels = channelInfo?.channels ?? [];

  const checkSubscription = useCallback(async () => {
-    if (isChecking || cooldown > 0) return;
-
+    if (isCheckingRef.current) return;
+    isCheckingRef.current = true;
    setIsChecking(true);
    setError(null);

    try {
-      // Make any authenticated request - if channel check passes, it will succeed
      await apiClient.get('/cabinet/auth/me');
-      // If we get here, subscription is valid - reload page
      clearBlocking();
      window.location.reload();
    } catch (err: unknown) {
-      // Check if it's still a channel subscription error
-      const error = err as {
-        response?: { status?: number; data?: { detail?: { code?: string } } };
-      };
-      if (
-        error.response?.status === 403 &&
-        error.response?.data?.detail?.code === 'channel_subscription_required'
-      ) {
+      if (isChannelSubscriptionError(err)) {
        setError(t('blocking.channel.notSubscribed'));
      } else {
-        // Other error - might be network issue
        setError(t('blocking.channel.checkError'));
      }
    } finally {
+      isCheckingRef.current = false;
      setIsChecking(false);
      setCooldown(CHECK_COOLDOWN_SECONDS);
    }
-  }, [isChecking, cooldown, clearBlocking, t]);
+  }, [clearBlocking, t]);

  return (
    <div className="fixed inset-0 z-[100] flex flex-col items-center justify-center bg-dark-950 p-6">
@@ -84,98 +84,125 @@ export default function ChannelSubscriptionScreen() {
        <h1 className="mb-4 text-2xl font-bold text-white">{t('blocking.channel.title')}</h1>

        {/* Message */}
-        <p className="mb-8 text-lg text-gray-400">
+        <p className="mb-6 text-lg text-gray-400">
          {channelInfo?.message || t('blocking.channel.defaultMessage')}
        </p>

+        {/* Channel list */}
+        {channels.length > 0 && (
+          <div className="mb-6 space-y-3">
+            {channels.map((ch) => (
+              <div
+                key={ch.channel_id}
+                className={`flex items-center justify-between rounded-xl border p-3 ${
+                  ch.is_subscribed
+                    ? 'border-green-500/30 bg-green-500/10'
+                    : 'border-red-500/30 bg-red-500/10'
+                }`}
+              >
+                <span className="text-sm font-medium text-white">{ch.title || ch.channel_id}</span>
+                <div className="flex items-center gap-2">
+                  {ch.is_subscribed ? (
+                    <span className="text-xs text-green-400">
+                      {t('blocking.channel.subscribed')}
+                    </span>
+                  ) : (
+                    ch.channel_link && (
+                      <button
+                        onClick={() => safeOpenUrl(ch.channel_link)}
+                        className="rounded-lg bg-blue-500/20 px-3 py-1 text-xs font-medium text-blue-400 hover:bg-blue-500/30"
+                      >
+                        {t('blocking.channel.openChannel')}
+                      </button>
+                    )
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+
+        {/* Fallback: single channel (legacy) */}
+        {channels.length === 0 && channelInfo?.channel_link && (
+          <button
+            onClick={() => safeOpenUrl(channelInfo.channel_link)}
+            className="mb-6 flex w-full items-center justify-center gap-3 rounded-xl bg-gradient-to-r from-blue-500 to-cyan-500 px-6 py-4 font-semibold text-white transition-all duration-200 hover:from-blue-600 hover:to-cyan-600"
+          >
+            {t('blocking.channel.openChannel')}
+          </button>
+        )}
+
        {/* Error message */}
        {error && (
-          <div className="mb-6 rounded-xl border border-red-500/30 bg-red-500/10 p-4">
+          <div className="mb-4 rounded-xl border border-red-500/30 bg-red-500/10 p-3">
            <p className="text-sm text-red-400">{error}</p>
          </div>
        )}

-        {/* Buttons */}
-        <div className="space-y-4">
-          {/* Open channel button */}
-          <button
-            onClick={openChannel}
-            disabled={!channelInfo?.channel_link}
-            className="flex w-full items-center justify-center gap-3 rounded-xl bg-gradient-to-r from-blue-500 to-cyan-500 px-6 py-4 font-semibold text-white transition-all duration-200 hover:from-blue-600 hover:to-cyan-600 disabled:from-gray-600 disabled:to-gray-600"
-          >
-            <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
-              <path d="M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z" />
-            </svg>
-            {t('blocking.channel.openChannel')}
-          </button>
-
-          {/* Check subscription button */}
-          <button
-            onClick={checkSubscription}
-            disabled={isChecking || cooldown > 0}
-            className="flex w-full items-center justify-center gap-3 rounded-xl bg-dark-800 px-6 py-4 font-semibold text-white transition-all duration-200 hover:bg-dark-700 disabled:bg-dark-800 disabled:opacity-60"
-          >
-            {isChecking ? (
-              <>
-                <svg
-                  className="h-5 w-5 animate-spin"
-                  xmlns="http://www.w3.org/2000/svg"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                >
-                  <circle
-                    className="opacity-25"
-                    cx="12"
-                    cy="12"
-                    r="10"
-                    stroke="currentColor"
-                    strokeWidth="4"
-                  ></circle>
-                  <path
-                    className="opacity-75"
-                    fill="currentColor"
-                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-                  ></path>
-                </svg>
-                {t('blocking.channel.checking')}
-              </>
-            ) : cooldown > 0 ? (
-              <>
-                <svg
-                  className="h-5 w-5 text-gray-500"
-                  fill="none"
-                  viewBox="0 0 24 24"
+        {/* Check subscription button */}
+        <button
+          onClick={checkSubscription}
+          disabled={isChecking || cooldown > 0}
+          className="flex w-full items-center justify-center gap-3 rounded-xl bg-dark-800 px-6 py-4 font-semibold text-white transition-all duration-200 hover:bg-dark-700 disabled:bg-dark-800 disabled:opacity-60"
+        >
+          {isChecking ? (
+            <>
+              <svg
+                className="h-5 w-5 animate-spin"
+                xmlns="http://www.w3.org/2000/svg"
+                fill="none"
+                viewBox="0 0 24 24"
+              >
+                <circle
+                  className="opacity-25"
+                  cx="12"
+                  cy="12"
+                  r="10"
                  stroke="currentColor"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"
-                  />
-                </svg>
-                {t('blocking.channel.waitSeconds', {
-                  seconds: cooldown,
-                })}
-              </>
-            ) : (
-              <>
-                <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M5 13l4 4L19 7"
-                  />
-                </svg>
-                {t('blocking.channel.checkSubscription')}
-              </>
-            )}
-          </button>
-        </div>
+                  strokeWidth="4"
+                />
+                <path
+                  className="opacity-75"
+                  fill="currentColor"
+                  d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                />
+              </svg>
+              {t('blocking.channel.checking')}
+            </>
+          ) : cooldown > 0 ? (
+            <>
+              <svg
+                className="h-5 w-5 text-gray-500"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"
+                />
+              </svg>
+              {t('blocking.channel.waitSeconds', { seconds: cooldown })}
+            </>
+          ) : (
+            <>
+              <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                  d="M5 13l4 4L19 7"
+                />
+              </svg>
+              {t('blocking.channel.checkSubscription')}
+            </>
+          )}
+        </button>

        {/* Hint */}
-        <p className="mt-6 text-sm text-gray-500">{t('blocking.channel.hint')}</p>
+        <p className="mt-4 text-sm text-gray-500">{t('blocking.channel.hint')}</p>
      </div>
    </div>
  );
--- a/src/locales/en.json
+++ b/src/locales/en.json
@@ -861,7 +861,8 @@
      "updates": "Updates",
      "pinnedMessages": "Pinned Messages",
      "partners": "Partners",
-      "withdrawals": "Withdrawals"
+      "withdrawals": "Withdrawals",
+      "channelSubscriptions": "Required Channels"
    },
    "panel": {
      "title": "Admin Panel",
@@ -888,7 +889,8 @@
      "updatesDesc": "Bot & cabinet versions",
      "pinnedMessagesDesc": "Manage pinned messages for users",
      "partnersDesc": "Manage partner applications and commissions",
-      "withdrawalsDesc": "Review and process withdrawal requests"
+      "withdrawalsDesc": "Review and process withdrawal requests",
+      "channelSubscriptionsDesc": "Manage required channel subscriptions"
    },
    "trafficUsage": {
      "title": "Traffic Usage",
@@ -1297,6 +1299,28 @@
      "editMessage": "Edit",
      "cantDeleteActive": "Cannot delete active message"
    },
+    "channelSubscriptions": {
+      "title": "Required Channels",
+      "subtitle": "Users must subscribe to these channels",
+      "addChannel": "Add Channel",
+      "empty": "No channels configured",
+      "enabled": "Enabled",
+      "disabled": "Disabled",
+      "enable": "Enable",
+      "disable": "Disable",
+      "delete": "Delete",
+      "deleteConfirm": "Delete this channel?",
+      "sortOrder": "Order",
+      "form": {
+        "title": "Display Name",
+        "channelId": "Channel ID",
+        "channelIdHint": "@username or -100XXXXXXXXXX",
+        "channelLink": "Channel Link",
+        "channelLinkHint": "https://t.me/channel",
+        "submit": "Add",
+        "cancel": "Cancel"
+      }
+    },
    "settings": {
      "title": "System Settings",
      "allCategories": "All categories",
@@ -3144,7 +3168,9 @@
      "waitSeconds": "Wait {{seconds}} sec.",
      "hint": "Click check button after subscribing",
      "notSubscribed": "You haven't subscribed to the channel yet",
-      "checkError": "Check failed. Please try again later."
+      "checkError": "Check failed. Please try again later.",
+      "subscribed": "Subscribed",
+      "channelsRequired": "Subscribe to all channels below to continue"
    },
    "blacklisted": {
      "title": "Access Denied",
--- a/src/locales/fa.json
+++ b/src/locales/fa.json
@@ -741,7 +741,8 @@
      "updates": "به‌روزرسانی‌ها",
      "pinnedMessages": "پیام‌های سنجاق‌شده",
      "partners": "شرکا",
-      "withdrawals": "برداشت‌ها"
+      "withdrawals": "برداشت‌ها",
+      "channelSubscriptions": "کانال‌های اجباری"
    },
    "panel": {
      "title": "پنل مدیریت",
@@ -768,7 +769,8 @@
      "updatesDesc": "نسخه‌های ربات و کابینت",
      "pinnedMessagesDesc": "مدیریت پیام‌های سنجاق‌شده",
      "partnersDesc": "مدیریت درخواست‌های شراکت و کمیسیون‌ها",
-      "withdrawalsDesc": "بررسی و پردازش درخواست‌های برداشت"
+      "withdrawalsDesc": "بررسی و پردازش درخواست‌های برداشت",
+      "channelSubscriptionsDesc": "مدیریت اشتراک‌های اجباری کانال"
    },
    "trafficUsage": {
      "title": "مصرف ترافیک",
@@ -1000,6 +1002,28 @@
      "editMessage": "Edit",
      "cantDeleteActive": "Cannot delete active message"
    },
+    "channelSubscriptions": {
+      "title": "کانال‌های اجباری",
+      "subtitle": "کاربران باید در این کانال‌ها عضو شوند",
+      "addChannel": "افزودن کانال",
+      "empty": "کانالی تنظیم نشده",
+      "enabled": "فعال",
+      "disabled": "غیرفعال",
+      "enable": "فعال‌سازی",
+      "disable": "غیرفعال‌سازی",
+      "delete": "حذف",
+      "deleteConfirm": "این کانال حذف شود؟",
+      "sortOrder": "ترتیب",
+      "form": {
+        "title": "نام نمایشی",
+        "channelId": "شناسه کانال",
+        "channelIdHint": "@username یا -100XXXXXXXXXX",
+        "channelLink": "لینک کانال",
+        "channelLinkHint": "https://t.me/channel",
+        "submit": "افزودن",
+        "cancel": "لغو"
+      }
+    },
    "payments": {
      "title": "تأیید پرداخت",
      "description": "پرداخت‌های معلق در ۲۴ ساعت گذشته",
@@ -2759,7 +2783,9 @@
      "waitSeconds": "{{seconds}} ثانیه صبر کنید",
      "hint": "پس از عضویت دکمه بررسی را بزنید",
      "notSubscribed": "شما هنوز در کانال عضو نشده‌اید",
-      "checkError": "بررسی ناموفق بود. لطفاً بعداً دوباره امتحان کنید."
+      "checkError": "بررسی ناموفق بود. لطفاً بعداً دوباره امتحان کنید.",
+      "subscribed": "عضو شده",
+      "channelsRequired": "برای ادامه در همه کانال‌های زیر عضو شوید"
    },
    "blacklisted": {
      "title": "دسترسی ممنوع",
--- a/src/locales/ru.json
+++ b/src/locales/ru.json
@@ -883,7 +883,8 @@
      "updates": "Обновления",
      "pinnedMessages": "Закреплённые",
      "partners": "Партнёры",
-      "withdrawals": "Выводы"
+      "withdrawals": "Выводы",
+      "channelSubscriptions": "Обязательные каналы"
    },
    "panel": {
      "title": "Панель администратора",
@@ -910,7 +911,8 @@
      "updatesDesc": "Версии бота и кабинета",
      "pinnedMessagesDesc": "Управление закреплёнными сообщениями",
      "partnersDesc": "Управление заявками партнёров и комиссиями",
-      "withdrawalsDesc": "Проверка и обработка заявок на вывод"
+      "withdrawalsDesc": "Проверка и обработка заявок на вывод",
+      "channelSubscriptionsDesc": "Управление обязательными подписками на каналы"
    },
    "trafficUsage": {
      "title": "Расход трафика",
@@ -1323,6 +1325,28 @@
      "editMessage": "Редактировать",
      "cantDeleteActive": "Нельзя удалить активное сообщение"
    },
+    "channelSubscriptions": {
+      "title": "Обязательные каналы",
+      "subtitle": "Пользователи должны подписаться на эти каналы",
+      "addChannel": "Добавить канал",
+      "empty": "Каналы не настроены",
+      "enabled": "Активен",
+      "disabled": "Отключён",
+      "enable": "Включить",
+      "disable": "Отключить",
+      "delete": "Удалить",
+      "deleteConfirm": "Удалить этот канал?",
+      "sortOrder": "Порядок",
+      "form": {
+        "title": "Название",
+        "channelId": "ID канала",
+        "channelIdHint": "@username или -100XXXXXXXXXX",
+        "channelLink": "Ссылка на канал",
+        "channelLinkHint": "https://t.me/channel",
+        "submit": "Добавить",
+        "cancel": "Отмена"
+      }
+    },
    "settings": {
      "title": "Настройки системы",
      "allCategories": "Все категории",
@@ -3699,7 +3723,9 @@
      "waitSeconds": "Подождите {{seconds}} сек.",
      "hint": "После подписки нажмите кнопку проверки",
      "notSubscribed": "Вы ещё не подписались на канал",
-      "checkError": "Ошибка проверки. Попробуйте позже."
+      "checkError": "Ошибка проверки. Попробуйте позже.",
+      "subscribed": "Подписан",
+      "channelsRequired": "Подпишитесь на все каналы ниже для продолжения"
    },
    "blacklisted": {
      "title": "Доступ запрещён",
--- a/src/locales/zh.json
+++ b/src/locales/zh.json
@@ -741,7 +741,8 @@
      "updates": "更新",
      "pinnedMessages": "置顶消息",
      "partners": "合作伙伴",
-      "withdrawals": "提现"
+      "withdrawals": "提现",
+      "channelSubscriptions": "必订频道"
    },
    "panel": {
      "title": "管理面板",
@@ -768,7 +769,8 @@
      "updatesDesc": "机器人和面板版本",
      "pinnedMessagesDesc": "管理用户置顶消息",
      "partnersDesc": "管理合作伙伴申请和佣金",
-      "withdrawalsDesc": "审核和处理提现请求"
+      "withdrawalsDesc": "审核和处理提现请求",
+      "channelSubscriptionsDesc": "管理必订频道订阅"
    },
    "trafficUsage": {
      "title": "流量使用",
@@ -1052,6 +1054,28 @@
      "editMessage": "编辑",
      "cantDeleteActive": "无法删除活跃消息"
    },
+    "channelSubscriptions": {
+      "title": "必订频道",
+      "subtitle": "用户必须订阅这些频道",
+      "addChannel": "添加频道",
+      "empty": "未配置频道",
+      "enabled": "已启用",
+      "disabled": "已禁用",
+      "enable": "启用",
+      "disable": "禁用",
+      "delete": "删除",
+      "deleteConfirm": "删除此频道？",
+      "sortOrder": "排序",
+      "form": {
+        "title": "显示名称",
+        "channelId": "频道ID",
+        "channelIdHint": "@username 或 -100XXXXXXXXXX",
+        "channelLink": "频道链接",
+        "channelLinkHint": "https://t.me/channel",
+        "submit": "添加",
+        "cancel": "取消"
+      }
+    },
    "settings": {
      "title": "系统设置",
      "allCategories": "所有分类",
@@ -2640,7 +2664,9 @@
      "waitSeconds": "请等待 {{seconds}} 秒",
      "hint": "订阅后点击检查按钮",
      "notSubscribed": "您还没有订阅该频道",
-      "checkError": "检查失败。请稍后重试。"
+      "checkError": "检查失败。请稍后重试。",
+      "subscribed": "已订阅",
+      "channelsRequired": "请订阅以下所有频道以继续"
    },
    "blacklisted": {
      "title": "访问被拒绝",
--- a/src/pages/AdminChannelSubscriptions.tsx
+++ b/src/pages/AdminChannelSubscriptions.tsx
@@ -0,0 +1,408 @@
+import { useState } from 'react';
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { useTranslation } from 'react-i18next';
+import { useHaptic, useNotify } from '../platform';
+import {
+  adminChannelsApi,
+  type RequiredChannel,
+  type CreateChannelRequest,
+} from '../api/adminChannels';
+import { AdminBackButton } from '../components/admin';
+
+// Icons
+const ChannelIcon = () => (
+  <svg className="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M10.34 15.84c-.688-.06-1.386-.09-2.09-.09H7.5a4.5 4.5 0 110-9h.75c.704 0 1.402-.03 2.09-.09m0 9.18c.253.962.584 1.892.985 2.783.247.55.06 1.21-.463 1.511l-.657.38c-.551.318-1.26.117-1.527-.461a20.845 20.845 0 01-1.44-4.282m3.102.069a18.03 18.03 0 01-.59-4.59c0-1.586.205-3.124.59-4.59m0 9.18a23.848 23.848 0 018.835 2.535M10.34 6.66a23.847 23.847 0 008.835-2.535m0 0A23.74 23.74 0 0018.795 3m.38 1.125a23.91 23.91 0 011.014 5.395m-1.014 8.855c-.118.38-.245.754-.38 1.125m.38-1.125a23.91 23.91 0 001.014-5.395m0-3.46c.495.413.811 1.035.811 1.73 0 .695-.316 1.317-.811 1.73m0-3.46a24.347 24.347 0 010 3.46"
+    />
+  </svg>
+);
+
+const PlusIcon = () => (
+  <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path strokeLinecap="round" strokeLinejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
+  </svg>
+);
+
+const RefreshIcon = () => (
+  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0l3.181 3.183a8.25 8.25 0 0013.803-3.7M4.031 9.865a8.25 8.25 0 0113.803-3.7l3.181 3.182m0-4.991v4.99"
+    />
+  </svg>
+);
+
+const TrashIcon = () => (
+  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M14.74 9l-.346 9m-4.788 0L9.26 9m9.968-3.21c.342.052.682.107 1.022.166m-1.022-.165L18.16 19.673a2.25 2.25 0 01-2.244 2.077H8.084a2.25 2.25 0 01-2.244-2.077L4.772 5.79m14.456 0a48.108 48.108 0 00-3.478-.397m-12 .562c.34-.059.68-.114 1.022-.165m0 0a48.11 48.11 0 013.478-.397m7.5 0v-.916c0-1.18-.91-2.164-2.09-2.201a51.964 51.964 0 00-3.32 0c-1.18.037-2.09 1.022-2.09 2.201v.916m7.5 0a48.667 48.667 0 00-7.5 0"
+    />
+  </svg>
+);
+
+const CheckIcon = () => (
+  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+  </svg>
+);
+
+const XIcon = () => (
+  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+  </svg>
+);
+
+const LinkIcon = () => (
+  <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m9.86-2.239a4.5 4.5 0 00-1.242-7.244l-4.5-4.5a4.5 4.5 0 00-6.364 6.364L4.5 8.688"
+    />
+  </svg>
+);
+
+// Channel card component
+function ChannelCard({
+  channel,
+  onToggle,
+  onDelete,
+}: {
+  channel: RequiredChannel;
+  onToggle: (id: number) => void;
+  onDelete: (id: number) => void;
+}) {
+  const { t } = useTranslation();
+
+  const displayName = channel.title || channel.channel_id;
+  const hasLink = !!channel.channel_link;
+
+  return (
+    <div
+      className={`rounded-xl border p-4 transition-all ${
+        channel.is_active
+          ? 'border-success-500/50 bg-success-500/5'
+          : 'border-dark-700 bg-dark-800/50'
+      }`}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          {/* Status + sort order */}
+          <div className="mb-2 flex flex-wrap items-center gap-2">
+            <span
+              className={`rounded-full px-2 py-1 text-xs font-medium ${
+                channel.is_active
+                  ? 'bg-success-500/20 text-success-400'
+                  : 'bg-dark-500/20 text-dark-400'
+              }`}
+            >
+              {channel.is_active
+                ? t('admin.channelSubscriptions.enabled')
+                : t('admin.channelSubscriptions.disabled')}
+            </span>
+            <span className="text-xs text-dark-400">#{channel.id}</span>
+            <span className="text-xs text-dark-500">
+              {t('admin.channelSubscriptions.sortOrder')}: {channel.sort_order}
+            </span>
+          </div>
+
+          {/* Title / channel_id */}
+          <p className="text-sm font-medium text-dark-100">{displayName}</p>
+
+          {/* Channel ID (if title exists, show ID separately) */}
+          {channel.title && <p className="mt-0.5 text-xs text-dark-400">{channel.channel_id}</p>}
+
+          {/* Link */}
+          {hasLink && (
+            <div className="mt-1.5 flex items-center gap-1 text-xs text-accent-400">
+              <LinkIcon />
+              <a
+                href={channel.channel_link!}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="truncate hover:underline"
+              >
+                {channel.channel_link}
+              </a>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Action buttons */}
+      <div className="mt-3 flex flex-wrap gap-2 border-t border-dark-700/50 pt-3">
+        {channel.is_active ? (
+          <button
+            onClick={() => onToggle(channel.id)}
+            className="flex items-center gap-1.5 rounded-lg bg-warning-500/20 px-3 py-1.5 text-xs text-warning-400 transition-colors hover:bg-warning-500/30"
+          >
+            <XIcon />
+            {t('admin.channelSubscriptions.disable')}
+          </button>
+        ) : (
+          <button
+            onClick={() => onToggle(channel.id)}
+            className="flex items-center gap-1.5 rounded-lg bg-success-500/20 px-3 py-1.5 text-xs text-success-400 transition-colors hover:bg-success-500/30"
+          >
+            <CheckIcon />
+            {t('admin.channelSubscriptions.enable')}
+          </button>
+        )}
+
+        <button
+          onClick={() => onDelete(channel.id)}
+          className="flex items-center gap-1.5 rounded-lg bg-error-500/20 px-3 py-1.5 text-xs text-error-400 transition-colors hover:bg-error-500/30"
+        >
+          <TrashIcon />
+          {t('admin.channelSubscriptions.delete')}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// Add channel form component
+function AddChannelForm({
+  onSubmit,
+  onCancel,
+  isLoading,
+}: {
+  onSubmit: (data: CreateChannelRequest) => void;
+  onCancel: () => void;
+  isLoading: boolean;
+}) {
+  const { t } = useTranslation();
+  const [channelId, setChannelId] = useState('');
+  const [channelLink, setChannelLink] = useState('');
+  const [title, setTitle] = useState('');
+
+  const handleSubmit = () => {
+    if (!channelId.trim()) return;
+    onSubmit({
+      channel_id: channelId.trim(),
+      channel_link: channelLink.trim() || undefined,
+      title: title.trim() || undefined,
+    });
+  };
+
+  return (
+    <div className="rounded-xl border border-accent-500/30 bg-dark-800/50 p-4">
+      <div className="space-y-3">
+        {/* Channel ID (required) */}
+        <div>
+          <label className="mb-1 block text-xs font-medium text-dark-300">
+            {t('admin.channelSubscriptions.form.channelId')} *
+          </label>
+          <input
+            type="text"
+            value={channelId}
+            onChange={(e) => setChannelId(e.target.value)}
+            placeholder={t('admin.channelSubscriptions.form.channelIdHint')}
+            className="w-full rounded-lg border border-dark-600 bg-dark-700 px-3 py-2 text-sm text-dark-100 placeholder-dark-500 outline-none transition-colors focus:border-accent-500"
+            autoFocus
+          />
+        </div>
+
+        {/* Title (optional) */}
+        <div>
+          <label className="mb-1 block text-xs font-medium text-dark-300">
+            {t('admin.channelSubscriptions.form.title')}
+          </label>
+          <input
+            type="text"
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+            placeholder={t('admin.channelSubscriptions.form.title')}
+            className="w-full rounded-lg border border-dark-600 bg-dark-700 px-3 py-2 text-sm text-dark-100 placeholder-dark-500 outline-none transition-colors focus:border-accent-500"
+          />
+        </div>
+
+        {/* Channel Link (optional) */}
+        <div>
+          <label className="mb-1 block text-xs font-medium text-dark-300">
+            {t('admin.channelSubscriptions.form.channelLink')}
+          </label>
+          <input
+            type="text"
+            value={channelLink}
+            onChange={(e) => setChannelLink(e.target.value)}
+            placeholder={t('admin.channelSubscriptions.form.channelLinkHint')}
+            className="w-full rounded-lg border border-dark-600 bg-dark-700 px-3 py-2 text-sm text-dark-100 placeholder-dark-500 outline-none transition-colors focus:border-accent-500"
+          />
+        </div>
+
+        {/* Buttons */}
+        <div className="flex gap-2 pt-1">
+          <button
+            onClick={handleSubmit}
+            disabled={!channelId.trim() || isLoading}
+            className="flex items-center gap-2 rounded-lg bg-accent-500 px-4 py-2 text-sm text-white transition-colors hover:bg-accent-600 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <CheckIcon />
+            {t('admin.channelSubscriptions.form.submit')}
+          </button>
+          <button
+            onClick={onCancel}
+            disabled={isLoading}
+            className="flex items-center gap-2 rounded-lg bg-dark-700 px-4 py-2 text-sm text-dark-300 transition-colors hover:bg-dark-600 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <XIcon />
+            {t('admin.channelSubscriptions.form.cancel')}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Main component
+export default function AdminChannelSubscriptions() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+  const haptic = useHaptic();
+  const notify = useNotify();
+  const [showAddForm, setShowAddForm] = useState(false);
+
+  // Fetch channels
+  const { data, isLoading, refetch } = useQuery({
+    queryKey: ['admin-channels'],
+    queryFn: adminChannelsApi.list,
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: (id: number) => adminChannelsApi.toggle(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-channels'] });
+      haptic.impact('light');
+    },
+    onError: () => {
+      haptic.notification('error');
+      notify.error(t('common.error'));
+    },
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: number) => adminChannelsApi.delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-channels'] });
+      haptic.impact('medium');
+    },
+    onError: () => {
+      haptic.notification('error');
+      notify.error(t('common.error'));
+    },
+  });
+
+  const createMutation = useMutation({
+    mutationFn: (req: CreateChannelRequest) => adminChannelsApi.create(req),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['admin-channels'] });
+      setShowAddForm(false);
+      haptic.impact('light');
+    },
+    onError: () => {
+      haptic.notification('error');
+      notify.error(t('common.error'));
+    },
+  });
+
+  const handleToggle = (id: number) => {
+    toggleMutation.mutate(id);
+  };
+
+  const handleDelete = (id: number) => {
+    if (window.confirm(t('admin.channelSubscriptions.deleteConfirm'))) {
+      deleteMutation.mutate(id);
+    }
+  };
+
+  const handleCreate = (data: CreateChannelRequest) => {
+    createMutation.mutate(data);
+  };
+
+  const channels = data?.items ?? [];
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <AdminBackButton />
+          <div className="flex items-center gap-3">
+            <div className="rounded-lg bg-accent-500/20 p-2 text-accent-400">
+              <ChannelIcon />
+            </div>
+            <div>
+              <h1 className="text-xl font-bold text-dark-100">
+                {t('admin.channelSubscriptions.title')}
+              </h1>
+              <p className="text-sm text-dark-400">{t('admin.channelSubscriptions.subtitle')}</p>
+            </div>
+          </div>
+        </div>
+        <div className="flex gap-2">
+          <button
+            onClick={() => refetch()}
+            aria-label={t('common.refresh')}
+            className="rounded-lg bg-dark-800 p-2 text-dark-400 transition-colors hover:text-dark-100"
+          >
+            <RefreshIcon />
+          </button>
+          {!showAddForm && (
+            <button
+              onClick={() => setShowAddForm(true)}
+              aria-label={t('admin.channelSubscriptions.addChannel')}
+              className="flex items-center gap-2 rounded-lg bg-accent-500 px-4 py-2 text-white transition-colors hover:bg-accent-600"
+            >
+              <PlusIcon />
+              <span className="hidden sm:inline">{t('admin.channelSubscriptions.addChannel')}</span>
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Add form */}
+      {showAddForm && (
+        <AddChannelForm
+          onSubmit={handleCreate}
+          onCancel={() => setShowAddForm(false)}
+          isLoading={createMutation.isPending}
+        />
+      )}
+
+      {/* Channel list */}
+      {isLoading ? (
+        <div className="rounded-xl border border-dark-700 bg-dark-800/50 p-8 text-center text-dark-400">
+          <div className="mx-auto mb-2 w-fit animate-spin">
+            <RefreshIcon />
+          </div>
+          <p>{t('common.loading')}</p>
+        </div>
+      ) : channels.length === 0 ? (
+        <div className="rounded-xl border border-dark-700 bg-dark-800/50 p-8 text-center text-dark-400">
+          <div className="mx-auto mb-2 w-fit">
+            <ChannelIcon />
+          </div>
+          <p>{t('admin.channelSubscriptions.empty')}</p>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          {channels.map((channel: RequiredChannel) => (
+            <ChannelCard
+              key={channel.id}
+              channel={channel}
+              onToggle={handleToggle}
+              onDelete={handleDelete}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
--- a/src/pages/AdminPanel.tsx
+++ b/src/pages/AdminPanel.tsx
@@ -482,6 +482,12 @@ export default function AdminPanel() {
      iconBg: 'bg-violet-500/20',
      iconColor: 'text-violet-400',
      items: [
+        {
+          to: '/admin/channel-subscriptions',
+          icon: <MegaphoneIcon />,
+          title: t('admin.nav.channelSubscriptions'),
+          description: t('admin.panel.channelSubscriptionsDesc'),
+        },
        {
          to: '/admin/settings',
          icon: <CogIcon />,
--- a/src/store/blocking.ts
+++ b/src/store/blocking.ts
@@ -7,9 +7,22 @@ interface MaintenanceInfo {
  reason?: string;
 }

+/**
+ * User-facing channel subscription status returned by the blocking 403 response.
+ * Intentionally separate from `RequiredChannel` (api/adminChannels.ts) which
+ * represents the admin CRUD entity with `is_active` / `sort_order` fields.
+ */
+interface ChannelInfo {
+  channel_id: string;
+  channel_link?: string;
+  title?: string;
+  is_subscribed: boolean;
+}
+
 interface ChannelSubscriptionInfo {
  message: string;
  channel_link?: string;
+  channels?: ChannelInfo[];
 }

 interface BlacklistedInfo {