feat(clients,groups): client groups + sub-links export + dedicated groups page

Persistent client groups
- New ClientGroup model + client_groups table that holds empty
  (placeholder) groups so a user can define a label before any client
  references it. ListGroups merges these with the distinct group_name
  values already stored on clients and reports {name, clientCount}.
- ClientRecord gains group_name column; the model.Client wire shape
  gains a matching `group` JSON field that survives the
  inbound.settings → SyncInbound round-trip.
- Rename/Delete on a group mutates client_groups (rename row / delete
  row) AND propagates to all matching clients in ClientRecord and in
  every owning inbound's settings JSON, all in one transaction.

Bulk operations
- AssignGroup(emails, group) updates clients.group_name + patches each
  affected inbound's settings JSON in one read-modify-write per inbound.
  Empty group clears the label. Auto-creates the client_groups row when
  the user assigns to a brand-new name.
- BulkResetTraffic(emails) loops the existing single-reset path so the
  caller can zero traffic across a whole selection or a whole group.
- EmailsByGroup(name) returns just the email list (used by the groups
  page to fan a single bulk action over every member).

Endpoints (all under /panel/api/clients)
- GET  /groups                         — summaries with counts
- GET  /groups/:name/emails            — emails in a group
- POST /groups/create                  — empty placeholder group
- POST /groups/rename                  — rename (table + clients + JSON)
- POST /groups/delete                  — drop label everywhere (clients survive)
- POST /bulkAssignGroup                — assign N selected clients
- POST /bulkResetTraffic               — reset traffic on a list

Clients page UX
- New Group column (Actions → Client → Group → Inbounds → …) with a
  click-to-filter chip.
- FilterDrawer gains a multi-select Group filter whose options come
  from the new ClientPageResponse.groups field (sourced from ListGroups
  so empty/placeholder groups are pickable too).
- Single-client and bulk-add forms gain a Group AutoComplete pre-loaded
  with all known group names.
- New toolbar buttons when selection > 0: "Group ({n})" opens
  BulkAssignGroupModal, "Sub links ({n})" opens SubLinksModal.

Sub-links export modal (new SubLinksModal.tsx)
- Table of selected clients with their subscription URL (and JSON URL
  when subJsonEnable is on), per-row copy, Copy all, and Download as
  sub-links-<timestamp>.txt. Warns when subscription is disabled or
  none of the selected clients have a subId.

Dedicated Groups page (new pages/groups/GroupsPage.tsx)
- /groups route + sidebar entry (TagsOutlined icon) + page title key.
- Card-based layout matching Clients/Inbounds/Nodes — summary card with
  Total/Grouped/Empty stats, main card with Add Group button + table.
- Per-row More dropdown (icon-first column on the left): Sub links,
  Adjust (days+traffic), Reset traffic, Rename, Delete clients in
  group, Delete group (keep clients). Empty groups disable the
  client-targeted actions.
- Reuses SubLinksModal and ClientBulkAdjustModal — emails for the
  group are fetched on demand from GET /groups/:name/emails.

Other polish
- /groups + groups-page selectors added to page-shell.css and
  page-cards.css so the new page inherits the same background, padding,
  card borders, hover shadow, and summary-card padding.
- .card-toolbar gains a small vertical padding so the larger toolbar
  buttons (now default size, matching Inbounds) don't crowd the top of
  the card-head on Clients and Groups pages.

database/db.go

@@ -68,6 +68,7 @@ func initModels() error {
 		&model.ApiToken{},
 		&model.ClientRecord{},
 		&model.ClientInbound{},
+		&model.ClientGroup{},
 		&model.InboundFallback{},
 	}
 	for _, mdl := range models {

database/model/model.go

@@ -371,6 +371,7 @@ type Client struct {
 	Enable     bool           `json:"enable" form:"enable"`         // Whether the client is enabled
 	TgID       int64          `json:"tgId" form:"tgId"`             // Telegram user ID for notifications
 	SubID      string         `json:"subId" form:"subId"`           // Subscription identifier
+	Group      string         `json:"group,omitempty" form:"group"` // Logical grouping label
 	Comment    string         `json:"comment" form:"comment"`       // Client comment
 	Reset      int            `json:"reset" form:"reset"`           // Reset period in days
 	CreatedAt  int64          `json:"created_at,omitempty"`         // Creation timestamp
@@ -392,6 +393,7 @@ type ClientRecord struct {
 	ExpiryTime int64  `json:"expiryTime" gorm:"column:expiry_time"`
 	Enable     bool   `json:"enable" gorm:"default:true"`
 	TgID       int64  `json:"tgId" gorm:"column:tg_id"`
+	Group      string `json:"group" gorm:"column:group_name;default:''"`
 	Comment    string `json:"comment"`
 	Reset      int    `json:"reset" gorm:"default:0"`
 	CreatedAt  int64  `json:"createdAt" gorm:"autoCreateTime:milli"`
@@ -400,6 +402,15 @@ type ClientRecord struct {
 
 func (ClientRecord) TableName() string { return "clients" }
 
+type ClientGroup struct {
+	Id        int    `json:"id" gorm:"primaryKey;autoIncrement"`
+	Name      string `json:"name" gorm:"uniqueIndex;not null"`
+	CreatedAt int64  `json:"createdAt" gorm:"autoCreateTime:milli"`
+	UpdatedAt int64  `json:"updatedAt" gorm:"autoUpdateTime:milli"`
+}
+
+func (ClientGroup) TableName() string { return "client_groups" }
+
 // MarshalJSON emits the reverse column as a nested JSON object rather than an
 // escaped JSON-text string, matching the same convention Inbound uses for its
 // JSON-text columns. Empty storage renders as null.
@@ -472,6 +483,7 @@ func (c *Client) ToRecord() *ClientRecord {
 		ExpiryTime: c.ExpiryTime,
 		Enable:     c.Enable,
 		TgID:       c.TgID,
+		Group:      c.Group,
 		Comment:    c.Comment,
 		Reset:      c.Reset,
 		CreatedAt:  c.CreatedAt,
@@ -499,6 +511,7 @@ func (r *ClientRecord) ToClient() *Client {
 		ExpiryTime: r.ExpiryTime,
 		Enable:     r.Enable,
 		TgID:       r.TgID,
+		Group:      r.Group,
 		Comment:    r.Comment,
 		Reset:      r.Reset,
 		CreatedAt:  r.CreatedAt,
@@ -623,6 +636,12 @@ func MergeClientRecord(existing *ClientRecord, incoming *ClientRecord) []ClientM
 			existing.Comment = incoming.Comment
 		}
 	}
+	if existing.Group != incoming.Group && incoming.Group != "" {
+		if incomingNewer || existing.Group == "" {
+			keep("group", existing.Group, incoming.Group, incoming.Group)
+			existing.Group = incoming.Group
+		}
+	}
 	if existing.Enable != incoming.Enable {
 		if incoming.Enable {
 			if !existing.Enable {

frontend/public/openapi.json

@@ -2805,6 +2805,351 @@
         }
       }
     },
+    "/panel/api/clients/bulkAssignGroup": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Assign the given group label to many clients in one call. Updates clients.group_name and patches the matching client entry inside every owning inbound's settings JSON in a single transaction. Pass an empty group to clear the label. If the group name does not yet exist (in client_groups or as a derived label), it is auto-created as a persistent group.",
+        "operationId": "post_panel_api_clients_bulkAssignGroup",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "emails": [
+                  "alice",
+                  "bob"
+                ],
+                "group": "customer-a"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "affected": 2
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/bulkResetTraffic": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Zero up/down counters for many clients in one call. Loops the single-reset path so each client is re-enabled across its attached inbounds and pushed to Xray/remote nodes. Returns the count of successfully reset clients.",
+        "operationId": "post_panel_api_clients_bulkResetTraffic",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "emails": [
+                  "alice",
+                  "bob"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "affected": 2
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/groups": {
+      "get": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "List all client groups with their member counts. Merges persisted groups (rows in client_groups, including empty placeholders) with the distinct group_name values currently set on clients. Sorted alphabetically (case-insensitive).",
+        "operationId": "get_panel_api_clients_groups",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": [
+                    {
+                      "name": "customer-a",
+                      "clientCount": 5
+                    },
+                    {
+                      "name": "internal",
+                      "clientCount": 0
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/groups/{name}/emails": {
+      "get": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Return just the email list of clients that currently belong to the given group. Useful for fanning a single bulk action over an entire group without round-tripping the full client list.",
+        "operationId": "get_panel_api_clients_groups_name_emails",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "description": "Group name (URL-encoded).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": [
+                    "alice",
+                    "bob",
+                    "carol"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/groups/create": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Create a new empty (placeholder) group. The group becomes selectable in client forms and the filter drawer even before any client is assigned to it. Errors if a group with the same name already exists.",
+        "operationId": "post_panel_api_clients_groups_create",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "name": "customer-a"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "name": "customer-a"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/groups/rename": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Rename a group. The new name is applied to the client_groups row AND propagated to every matching client (both clients.group_name and the client entry inside every owning inbound's settings JSON) in a single transaction. Returns the number of clients whose label was updated.",
+        "operationId": "post_panel_api_clients_groups_rename",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "oldName": "customer-a",
+                "newName": "tier-1"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "affected": 5
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/panel/api/clients/groups/delete": {
+      "post": {
+        "tags": [
+          "Clients"
+        ],
+        "summary": "Remove a group. Deletes the client_groups row and clears the group label from every matching client (both clients.group_name and the inbound settings JSON). The clients themselves are NOT deleted — use /bulkDel after filtering by group for that. Returns the count of clients whose label was cleared.",
+        "operationId": "post_panel_api_clients_groups_delete",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {
+                "name": "customer-a"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {}
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "affected": 5
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/panel/api/clients/resetTraffic/{email}": {
       "post": {
         "tags": [

frontend/src/api/queryKeys.ts

@@ -21,6 +21,7 @@ export const keys = {
     list: (params: unknown) => ['clients', 'list', params] as const,
     onlines: () => ['clients', 'onlines'] as const,
     lastOnline: () => ['clients', 'lastOnline'] as const,
+    groups: () => ['clients', 'groups'] as const,
   },
   xray: {
     root: () => ['xray'] as const,

frontend/src/components/AppSidebar.css

@@ -18,7 +18,7 @@
   align-items: center;
   justify-content: space-between;
   gap: 8px;
-  padding: 14px 14px;
+  padding: 14px 16px 14px 24px;
   border-bottom: 1px solid var(--ant-color-border-secondary);
   user-select: none;
 }
@@ -32,29 +32,12 @@
 
 .brand-block {
   display: inline-flex;
-  flex-direction: column;
   align-items: center;
   min-width: 0;
   line-height: 1.1;
 }
 
-.brand-text {
-  display: block;
-}
-
-.brand-version {
-  display: block;
-  width: 100%;
-  text-align: center;
-  font-size: 10px;
-  font-weight: 500;
-  letter-spacing: 0;
-  opacity: 0.6;
-  margin-top: 2px;
-}
-
 .sider-brand-collapsed .brand-block {
-  align-items: center;
   flex: 0 0 auto;
 }
 
@@ -206,6 +189,46 @@
   border-top: 1px solid var(--ant-color-border-secondary);
 }
 
+.sider-footer {
+  flex: 0 0 auto;
+  padding: 8px 8px 12px;
+}
+
+.sider-version {
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 10px;
+  width: 100%;
+  padding: 8px 16px;
+  color: var(--ant-color-text-secondary);
+  font-size: 13px;
+  font-weight: 500;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  text-decoration: none;
+  transition: color 0.2s;
+}
+
+.sider-version .anticon {
+  font-size: 16px;
+}
+
+.sider-version:hover,
+.sider-version:focus-visible {
+  color: var(--ant-color-primary);
+  outline: none;
+}
+
+.sider-version.is-collapsed {
+  justify-content: center;
+  padding: 8px 0;
+}
+
+.drawer-footer {
+  flex: 0 0 auto;
+  padding: 8px 8px 12px;
+}
+
 @media (max-width: 768px) {
   .drawer-handle {
     display: inline-flex;

frontend/src/components/AppSidebar.tsx

@@ -9,6 +9,7 @@ import {
   ClusterOutlined,
   CloseOutlined,
   DashboardOutlined,
+  GithubOutlined,
   HeartOutlined,
   ImportOutlined,
   LogoutOutlined,
@@ -17,6 +18,7 @@ import {
   MoonOutlined,
   SettingOutlined,
   SunOutlined,
+  TagsOutlined,
   TeamOutlined,
   ToolOutlined,
 } from '@ant-design/icons';
@@ -27,14 +29,16 @@ import './AppSidebar.css';
 
 const SIDEBAR_COLLAPSED_KEY = 'isSidebarCollapsed';
 const DONATE_URL = 'https://donate.sanaei.dev/';
+const REPO_URL = 'https://github.com/MHSanaei/3x-ui';
 const LOGOUT_KEY = '__logout__';
 
-type IconName = 'dashboard' | 'inbound' | 'team' | 'setting' | 'tool' | 'cluster' | 'logout' | 'apidocs';
+type IconName = 'dashboard' | 'inbound' | 'team' | 'groups' | 'setting' | 'tool' | 'cluster' | 'logout' | 'apidocs';
 
 const iconByName: Record<IconName, ComponentType> = {
   dashboard: DashboardOutlined,
   inbound: ImportOutlined,
   team: TeamOutlined,
+  groups: TagsOutlined,
   setting: SettingOutlined,
   tool: ToolOutlined,
   cluster: ClusterOutlined,
@@ -65,6 +69,24 @@ function DonateButton({ ariaLabel }: { ariaLabel: string }) {
   );
 }
 
+function VersionBadge({ version, collapsed }: { version: string; collapsed?: boolean }) {
+  if (!version) return null;
+  const label = `v${version}`;
+  return (
+    <a
+      href={REPO_URL}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={`sider-version${collapsed ? ' is-collapsed' : ''}`}
+      aria-label={`GitHub ${label}`}
+      title={label}
+    >
+      <GithubOutlined />
+      {!collapsed && <span className="sider-version-text">{label}</span>}
+    </a>
+  );
+}
+
 function ThemeCycleButton({ id, isDark, isUltra, onCycle, ariaLabel }: {
   id: string;
   isDark: boolean;
@@ -103,6 +125,7 @@ export default function AppSidebar() {
     { key: '/', icon: 'dashboard', title: t('menu.dashboard') },
     { key: '/inbounds', icon: 'inbound', title: t('menu.inbounds') },
     { key: '/clients', icon: 'team', title: t('menu.clients') },
+    { key: '/groups', icon: 'groups', title: t('menu.groups') },
     { key: '/nodes', icon: 'cluster', title: t('menu.nodes') },
     { key: '/settings', icon: 'setting', title: t('menu.settings') },
     { key: '/xray', icon: 'tool', title: t('menu.xray') },
@@ -171,9 +194,6 @@ export default function AppSidebar() {
         <div className={`sider-brand${collapsed ? ' sider-brand-collapsed' : ''}`}>
           <div className="brand-block">
             <span className="brand-text">{collapsed ? '3X' : '3X-UI'}</span>
-            {!collapsed && panelVersion && (
-              <span className="brand-version">v{panelVersion}</span>
-            )}
           </div>
           {!collapsed && (
             <div className="brand-actions">
@@ -204,6 +224,9 @@ export default function AppSidebar() {
           items={toMenuItems(utilItems)}
           onClick={onMenuClick}
         />
+        <div className="sider-footer">
+          <VersionBadge version={panelVersion} collapsed={collapsed} />
+        </div>
       </Layout.Sider>
 
       <Drawer
@@ -222,7 +245,6 @@ export default function AppSidebar() {
         <div className="drawer-header">
           <div className="brand-block">
             <span className="drawer-brand">3X-UI</span>
-            {panelVersion && <span className="brand-version">v{panelVersion}</span>}
           </div>
           <div className="drawer-header-actions">
             <DonateButton ariaLabel={t('menu.donate') || 'Donate'} />
@@ -259,6 +281,9 @@ export default function AppSidebar() {
           items={toMenuItems(utilItems)}
           onClick={(info) => { onMenuClick(info); setDrawerOpen(false); }}
         />
+        <div className="drawer-footer">
+          <VersionBadge version={panelVersion} />
+        </div>
       </Drawer>
 
       {!drawerOpen && (

frontend/src/hooks/useClients.ts

@@ -55,6 +55,7 @@ export interface ClientQueryParams {
   autoRenew?: 'on' | 'off' | '';
   hasTgId?: 'yes' | 'no' | '';
   hasComment?: 'yes' | 'no' | '';
+  group?: string;
 }
 
 const DEFAULT_QUERY: ClientQueryParams = { page: 1, pageSize: 25 };
@@ -79,6 +80,7 @@ function buildQS(p: ClientQueryParams): string {
   if (p.autoRenew) sp.set('autoRenew', p.autoRenew);
   if (p.hasTgId) sp.set('hasTgId', p.hasTgId);
   if (p.hasComment) sp.set('hasComment', p.hasComment);
+  if (p.group) sp.set('group', p.group);
   return sp.toString();
 }
 
@@ -130,6 +132,7 @@ export function useClients() {
         && (prev.autoRenew ?? '') === (next.autoRenew ?? '')
         && (prev.hasTgId ?? '') === (next.hasTgId ?? '')
         && (prev.hasComment ?? '') === (next.hasComment ?? '')
+        && (prev.group ?? '') === (next.group ?? '')
       ) return prev;
       return next;
     });
@@ -169,6 +172,7 @@ export function useClients() {
   const total = listQuery.data?.total ?? 0;
   const filtered = listQuery.data?.filtered ?? 0;
   const summary = listQuery.data?.summary ?? DEFAULT_SUMMARY;
+  const allGroups = listQuery.data?.groups ?? [];
   const fetched = listQuery.data !== undefined;
   const loading = listQuery.isFetching;
 
@@ -230,6 +234,12 @@ export function useClients() {
     onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
   });
 
+  const bulkAssignGroupMut = useMutation({
+    mutationFn: (body: { emails: string[]; group: string }) =>
+      HttpUtil.post('/panel/api/clients/bulkAssignGroup', body, JSON_HEADERS),
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
+
   const updateMut = useMutation({
     mutationFn: ({ email, client }: { email: string; client: unknown }) =>
       HttpUtil.post(`/panel/api/clients/update/${encodeURIComponent(email)}`, client, JSON_HEADERS),
@@ -322,6 +332,10 @@ export function useClients() {
     if (!Array.isArray(emails) || emails.length === 0) return Promise.resolve(null);
     return bulkAdjustMut.mutateAsync({ emails, addDays, addBytes });
   }, [bulkAdjustMut]);
+  const bulkAssignGroup = useCallback((emails: string[], group: string) => {
+    if (!Array.isArray(emails) || emails.length === 0) return Promise.resolve(null);
+    return bulkAssignGroupMut.mutateAsync({ emails, group });
+  }, [bulkAssignGroupMut]);
   const attach = useCallback((email: string, inboundIds: number[]) => {
     if (!email) return Promise.resolve(null as unknown as Msg<unknown>);
     return attachMut.mutateAsync({ email, inboundIds });
@@ -407,6 +421,7 @@ export function useClients() {
     total,
     filtered,
     summary,
+    allGroups,
     hydrate,
     query,
     setQuery,
@@ -427,6 +442,7 @@ export function useClients() {
     remove,
     bulkDelete,
     bulkAdjust,
+    bulkAssignGroup,
     attach,
     detach,
     resetTraffic,

frontend/src/hooks/usePageTitle.ts

@@ -6,6 +6,7 @@ const TITLE_KEYS: Record<string, string> = {
   '/': 'menu.dashboard',
   '/inbounds': 'menu.inbounds',
   '/clients': 'menu.clients',
+  '/groups': 'menu.groups',
   '/nodes': 'menu.nodes',
   '/settings': 'menu.settings',
   '/xray': 'menu.xray',

frontend/src/pages/api-docs/endpoints.ts

@@ -535,6 +535,56 @@ export const sections: readonly Section[] = [
         body: '[\n  {\n    "client": {\n      "email": "alice@example.com",\n      "totalGB": 53687091200,\n      "expiryTime": 0,\n      "enable": true\n    },\n    "inboundIds": [7]\n  },\n  {\n    "client": {\n      "email": "bob@example.com",\n      "totalGB": 53687091200,\n      "expiryTime": 0,\n      "enable": true\n    },\n    "inboundIds": [7, 9]\n  }\n]',
         response: '{\n  "success": true,\n  "obj": {\n    "created": 2,\n    "skipped": [\n      { "email": "alice@example.com", "reason": "email already in use" }\n    ]\n  }\n}',
       },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/bulkAssignGroup',
+        summary: 'Assign the given group label to many clients in one call. Updates clients.group_name and patches the matching client entry inside every owning inbound\'s settings JSON in a single transaction. Pass an empty group to clear the label. If the group name does not yet exist (in client_groups or as a derived label), it is auto-created as a persistent group.',
+        body: '{\n  "emails": ["alice", "bob"],\n  "group": "customer-a"\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
+      },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/bulkResetTraffic',
+        summary: 'Zero up/down counters for many clients in one call. Loops the single-reset path so each client is re-enabled across its attached inbounds and pushed to Xray/remote nodes. Returns the count of successfully reset clients.',
+        body: '{\n  "emails": ["alice", "bob"]\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "affected": 2\n  }\n}',
+      },
+      {
+        method: 'GET',
+        path: '/panel/api/clients/groups',
+        summary: 'List all client groups with their member counts. Merges persisted groups (rows in client_groups, including empty placeholders) with the distinct group_name values currently set on clients. Sorted alphabetically (case-insensitive).',
+        response: '{\n  "success": true,\n  "obj": [\n    { "name": "customer-a", "clientCount": 5 },\n    { "name": "internal", "clientCount": 0 }\n  ]\n}',
+      },
+      {
+        method: 'GET',
+        path: '/panel/api/clients/groups/:name/emails',
+        summary: 'Return just the email list of clients that currently belong to the given group. Useful for fanning a single bulk action over an entire group without round-tripping the full client list.',
+        params: [
+          { name: 'name', in: 'path', type: 'string', desc: 'Group name (URL-encoded).' },
+        ],
+        response: '{\n  "success": true,\n  "obj": ["alice", "bob", "carol"]\n}',
+      },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/groups/create',
+        summary: 'Create a new empty (placeholder) group. The group becomes selectable in client forms and the filter drawer even before any client is assigned to it. Errors if a group with the same name already exists.',
+        body: '{\n  "name": "customer-a"\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "name": "customer-a"\n  }\n}',
+      },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/groups/rename',
+        summary: 'Rename a group. The new name is applied to the client_groups row AND propagated to every matching client (both clients.group_name and the client entry inside every owning inbound\'s settings JSON) in a single transaction. Returns the number of clients whose label was updated.',
+        body: '{\n  "oldName": "customer-a",\n  "newName": "tier-1"\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "affected": 5\n  }\n}',
+      },
+      {
+        method: 'POST',
+        path: '/panel/api/clients/groups/delete',
+        summary: 'Remove a group. Deletes the client_groups row and clears the group label from every matching client (both clients.group_name and the inbound settings JSON). The clients themselves are NOT deleted — use /bulkDel after filtering by group for that. Returns the count of clients whose label was cleared.',
+        body: '{\n  "name": "customer-a"\n}',
+        response: '{\n  "success": true,\n  "obj": {\n    "affected": 5\n  }\n}',
+      },
       {
         method: 'POST',
         path: '/panel/api/clients/resetTraffic/:email',

frontend/src/pages/clients/BulkAssignGroupModal.tsx

@@ -0,0 +1,83 @@
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { AutoComplete, Form, Modal, message } from 'antd';
+
+interface BulkAssignGroupModalProps {
+  open: boolean;
+  count: number;
+  groups: string[];
+  onOpenChange: (open: boolean) => void;
+  onSubmit: (group: string) => Promise<{ affected?: number } | null>;
+}
+
+export default function BulkAssignGroupModal({
+  open,
+  count,
+  groups,
+  onOpenChange,
+  onSubmit,
+}: BulkAssignGroupModalProps) {
+  const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
+  const [value, setValue] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+
+  useEffect(() => {
+    if (open) setValue('');
+  }, [open]);
+
+  async function submit() {
+    const next = value.trim();
+    setSubmitting(true);
+    try {
+      const result = await onSubmit(next);
+      if (result) {
+        const affected = result.affected ?? 0;
+        if (next === '') {
+          messageApi.success(t('pages.clients.assignGroupClearedToast', { count: affected }));
+        } else {
+          messageApi.success(t('pages.clients.assignGroupAssignedToast', { count: affected, group: next }));
+        }
+        onOpenChange(false);
+      }
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <>
+      {messageContextHolder}
+      <Modal
+        open={open}
+        title={t('pages.clients.assignGroupTitle', { count })}
+        okText={t('save')}
+        cancelText={t('cancel')}
+        confirmLoading={submitting}
+        onCancel={() => onOpenChange(false)}
+        onOk={submit}
+        destroyOnHidden
+      >
+        <Form layout="vertical">
+          <Form.Item
+            label={t('pages.clients.group')}
+            tooltip={t('pages.clients.assignGroupTooltip')}
+          >
+            <AutoComplete
+              value={value}
+              placeholder={t('pages.clients.assignGroupPlaceholder')}
+              options={groups.map((g) => ({ value: g }))}
+              onChange={(v) => setValue(v ?? '')}
+              filterOption={(input, option) =>
+                String(option?.value ?? '').toLowerCase().includes((input || '').toLowerCase())
+              }
+              allowClear
+              style={{ width: '100%' }}
+              autoFocus
+            />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </>
+  );
+}

frontend/src/pages/clients/ClientBulkAddModal.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Button, Form, Input, InputNumber, Modal, Select, Space, Switch, message } from 'antd';
+import { AutoComplete, Button, Form, Input, InputNumber, Modal, Select, Space, Switch, message } from 'antd';
 import { ReloadOutlined } from '@ant-design/icons';
 import dayjs from 'dayjs';
 import type { Dayjs } from 'dayjs';
@@ -21,6 +21,7 @@ interface ClientBulkAddModalProps {
   open: boolean;
   inbounds: InboundOption[];
   ipLimitEnable?: boolean;
+  groups?: string[];
   onOpenChange: (open: boolean) => void;
   onSaved?: () => void;
 }
@@ -36,6 +37,7 @@ function emptyForm(): FormState {
     emailPostfix: '',
     quantity: 1,
     subId: '',
+    group: '',
     comment: '',
     flow: '',
     limitIp: 0,
@@ -50,6 +52,7 @@ export default function ClientBulkAddModal({
   open,
   inbounds,
   ipLimitEnable = false,
+  groups = [],
   onOpenChange,
   onSaved,
 }: ClientBulkAddModalProps) {
@@ -157,6 +160,7 @@ export default function ClientBulkAddModal({
           expiryTime: form.expiryTime,
           reset: Number(form.reset) || 0,
           limitIp: Number(form.limitIp) || 0,
+          group: form.group,
           comment: form.comment,
           enable: true,
         },
@@ -263,6 +267,20 @@ export default function ClientBulkAddModal({
             </Space.Compact>
           </Form.Item>
 
+          <Form.Item label={t('pages.clients.group')} tooltip={t('pages.clients.groupDesc')}>
+            <AutoComplete
+              value={form.group}
+              placeholder={t('pages.clients.groupPlaceholder')}
+              options={groups.map((g) => ({ value: g }))}
+              onChange={(v) => update('group', v ?? '')}
+              filterOption={(input, option) =>
+                String(option?.value ?? '').toLowerCase().includes((input || '').toLowerCase())
+              }
+              allowClear
+              style={{ width: '100%' }}
+            />
+          </Form.Item>
+
           <Form.Item label={t('comment')}>
             <Input value={form.comment} onChange={(e) => update('comment', e.target.value)} />
           </Form.Item>

frontend/src/pages/clients/ClientFormModal.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
+  AutoComplete,
   Button,
   Col,
   Form,
@@ -61,6 +62,7 @@ interface ClientFormModalProps {
   attachedIds?: number[];
   ipLimitEnable?: boolean;
   tgBotEnable?: boolean;
+  groups?: string[];
   save: (
     payload: Record<string, unknown> | SaveCreatePayload,
     meta: SaveMetaEdit | SaveMetaCreate,
@@ -83,6 +85,7 @@ interface FormState {
   reset: number;
   limitIp: number;
   tgId: number;
+  group: string;
   comment: string;
   enable: boolean;
   inboundIds: number[];
@@ -104,6 +107,7 @@ function emptyForm(): FormState {
     reset: 0,
     limitIp: 0,
     tgId: 0,
+    group: '',
     comment: '',
     enable: true,
     inboundIds: [],
@@ -128,6 +132,7 @@ export default function ClientFormModal({
   attachedIds = [],
   ipLimitEnable = false,
   tgBotEnable = false,
+  groups = [],
   save,
   onOpenChange,
 }: ClientFormModalProps) {
@@ -163,6 +168,7 @@ export default function ClientFormModal({
         reset: Number(client.reset) || 0,
         limitIp: client.limitIp || 0,
         tgId: Number(client.tgId) || 0,
+        group: client.group || '',
         comment: client.comment || '',
         enable: !!client.enable,
         inboundIds: Array.isArray(attachedIds) ? [...attachedIds] : [],
@@ -287,6 +293,7 @@ export default function ClientFormModal({
       reset: form.reset,
       limitIp: form.limitIp,
       tgId: form.tgId,
+      group: form.group,
       comment: form.comment,
       enable: form.enable,
       inboundIds: form.inboundIds,
@@ -507,6 +514,21 @@ export default function ClientFormModal({
                 <Input value={form.comment} onChange={(e) => update('comment', e.target.value)} />
               </Form.Item>
             </Col>
+            <Col xs={24} md={12}>
+              <Form.Item label={t('pages.clients.group')} tooltip={t('pages.clients.groupDesc')}>
+                <AutoComplete
+                  value={form.group}
+                  placeholder={t('pages.clients.groupPlaceholder')}
+                  options={groups.map((g) => ({ value: g }))}
+                  onChange={(v) => update('group', v ?? '')}
+                  filterOption={(input, option) =>
+                    String(option?.value ?? '').toLowerCase().includes((input || '').toLowerCase())
+                  }
+                  allowClear
+                  style={{ width: '100%' }}
+                />
+              </Form.Item>
+            </Col>
           </Row>
 
           <Form.Item label={t('pages.clients.attachedInbounds')} required={!isEdit}>

frontend/src/pages/clients/ClientsPage.css

@@ -74,6 +74,7 @@
   align-items: center;
   gap: 8px;
   flex-wrap: wrap;
+  padding: 6px 0;
 }
 
 .email-cell {

frontend/src/pages/clients/ClientsPage.tsx

@@ -31,6 +31,7 @@ import {
   EditOutlined,
   FilterOutlined,
   InfoCircleOutlined,
+  LinkOutlined,
   MoreOutlined,
   PlusOutlined,
   QrcodeOutlined,
@@ -38,6 +39,7 @@ import {
   RetweetOutlined,
   SearchOutlined,
   SortAscendingOutlined,
+  TagsOutlined,
   TeamOutlined,
   UsergroupAddOutlined,
 } from '@ant-design/icons';
@@ -58,6 +60,8 @@ const ClientQrModal = lazy(() => import('./ClientQrModal'));
 const ClientBulkAddModal = lazy(() => import('./ClientBulkAddModal'));
 const ClientBulkAdjustModal = lazy(() => import('./ClientBulkAdjustModal'));
 const FilterDrawer = lazy(() => import('./FilterDrawer'));
+const SubLinksModal = lazy(() => import('./SubLinksModal'));
+const BulkAssignGroupModal = lazy(() => import('./BulkAssignGroupModal'));
 import { emptyFilters, activeFilterCount } from './filters';
 import type { ClientFilters } from './filters';
 import './ClientsPage.css';
@@ -97,6 +101,7 @@ function readFilterState(): PersistedFilterState {
         buckets: Array.isArray(fromRaw.buckets) ? fromRaw.buckets : [],
         protocols: Array.isArray(fromRaw.protocols) ? fromRaw.protocols : [],
         inboundIds: Array.isArray(fromRaw.inboundIds) ? fromRaw.inboundIds : [],
+        groups: Array.isArray(fromRaw.groups) ? fromRaw.groups : [],
       },
     };
   } catch {
@@ -140,10 +145,11 @@ export default function ClientsPage() {
   const {
     clients, filtered,
     summary: serverSummary,
+    allGroups,
     setQuery,
     inbounds, onlines, loading, fetched, subSettings,
     ipLimitEnable, tgBotEnable, expireDiff, trafficDiff, pageSize,
-    create, update, remove, bulkDelete, bulkAdjust, attach, detach,
+    create, update, remove, bulkDelete, bulkAdjust, bulkAssignGroup, attach, detach,
     resetTraffic, resetAllTraffics, delDepleted, setEnable,
     applyTrafficEvent, applyClientStatsEvent,
     hydrate,
@@ -165,6 +171,8 @@ export default function ClientsPage() {
   const [qrClient, setQrClient] = useState<ClientRecord | null>(null);
   const [bulkAddOpen, setBulkAddOpen] = useState(false);
   const [bulkAdjustOpen, setBulkAdjustOpen] = useState(false);
+  const [subLinksOpen, setSubLinksOpen] = useState(false);
+  const [bulkGroupOpen, setBulkGroupOpen] = useState(false);
   const [selectedRowKeys, setSelectedRowKeys] = useState<string[]>([]);
 
   const initial = readFilterState();
@@ -210,6 +218,7 @@ export default function ClientsPage() {
       autoRenew: filters.autoRenew || undefined,
       hasTgId: filters.hasTgId || undefined,
       hasComment: filters.hasComment || undefined,
+      group: filters.groups.join(',') || undefined,
       sort: sortColumn || undefined,
       order: sortOrder || undefined,
     });
@@ -236,6 +245,12 @@ export default function ClientsPage() {
     return [...values].sort();
   }, [inbounds]);
 
+  const groupOptions = useMemo(() => {
+    const values = new Set<string>(allGroups);
+    for (const g of filters.groups) values.add(g);
+    return [...values].sort((a, b) => a.localeCompare(b));
+  }, [allGroups, filters.groups]);
+
   const isOnline = useCallback((email: string) => !!email && onlineSet.has(email), [onlineSet]);
 
   function inboundLabel(id: number) {
@@ -562,6 +577,29 @@ export default function ClientsPage() {
         </div>
       ),
     },
+    {
+      title: t('pages.clients.group'),
+      key: 'group',
+      width: 130,
+      render: (_v, record) => {
+        if (!record.group) return <span style={{ color: 'rgba(0,0,0,0.45)' }}>—</span>;
+        const isActive = filters.groups.includes(record.group);
+        return (
+          <Tag
+            color="geekblue"
+            style={{ margin: 0, cursor: 'pointer', opacity: isActive ? 0.6 : 1 }}
+            onClick={(e) => {
+              e.stopPropagation();
+              if (!isActive) {
+                setFilters({ ...filters, groups: [...filters.groups, record.group!] });
+              }
+            }}
+          >
+            {record.group}
+          </Tag>
+        );
+      },
+    },
     {
       title: t('pages.clients.attachedInbounds'),
       key: 'inboundIds',
@@ -627,7 +665,7 @@ export default function ClientsPage() {
       ),
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  ], [t, togglingEmail, clientBucket, isOnline, inboundsById]);
+  ], [t, togglingEmail, clientBucket, isOnline, inboundsById, filters]);
 
   const tablePagination = {
     current: currentPage,
@@ -740,28 +778,56 @@ export default function ClientsPage() {
                       hoverable
                       title={
                         <div className="card-toolbar">
-                          <Button type="primary" size="small" icon={<PlusOutlined />} onClick={onAdd}>
+                          <Button type="primary" icon={<PlusOutlined />} onClick={onAdd}>
                             {!isMobile && t('pages.clients.addClients')}
                           </Button>
-                          <Button size="small" icon={<UsergroupAddOutlined />} onClick={() => setBulkAddOpen(true)}>
-                            {!isMobile && t('pages.clients.bulk')}
-                          </Button>
                           {selectedRowKeys.length > 0 && (
                             <>
-                              <Button size="small" icon={<ClockCircleOutlined />} onClick={() => setBulkAdjustOpen(true)}>
+                              <Button icon={<ClockCircleOutlined />} onClick={() => setBulkAdjustOpen(true)}>
                                 {t('pages.clients.adjustSelected', { count: selectedRowKeys.length })}
                               </Button>
-                              <Button danger size="small" icon={<DeleteOutlined />} onClick={onBulkDelete}>
+                              <Button icon={<TagsOutlined />} onClick={() => setBulkGroupOpen(true)}>
+                                {t('pages.clients.assignGroupSelected', { count: selectedRowKeys.length })}
+                              </Button>
+                              <Button icon={<LinkOutlined />} onClick={() => setSubLinksOpen(true)}>
+                                {t('pages.clients.subLinksSelected', { count: selectedRowKeys.length })}
+                              </Button>
+                              <Button danger icon={<DeleteOutlined />} onClick={onBulkDelete}>
                                 {t('pages.clients.deleteSelected', { count: selectedRowKeys.length })}
                               </Button>
                             </>
                           )}
-                          <Button size="small" icon={<RetweetOutlined />} onClick={onResetAllTraffics}>
-                            {!isMobile && t('pages.clients.resetAllTraffics')}
-                          </Button>
-                          <Button size="small" danger icon={<RestOutlined />} onClick={onDelDepleted}>
-                            {!isMobile && t('pages.clients.delDepleted')}
+                          <Dropdown
+                            trigger={['click']}
+                            placement="bottomRight"
+                            menu={{
+                              items: [
+                                {
+                                  key: 'bulk',
+                                  icon: <UsergroupAddOutlined />,
+                                  label: t('pages.clients.bulk'),
+                                  onClick: () => setBulkAddOpen(true),
+                                },
+                                {
+                                  key: 'resetAll',
+                                  icon: <RetweetOutlined />,
+                                  label: t('pages.clients.resetAllTraffics'),
+                                  onClick: onResetAllTraffics,
+                                },
+                                {
+                                  key: 'delDepleted',
+                                  icon: <RestOutlined />,
+                                  label: t('pages.clients.delDepleted'),
+                                  danger: true,
+                                  onClick: onDelDepleted,
+                                },
+                              ],
+                            }}
+                          >
+                            <Button icon={<MoreOutlined />}>
+                              {!isMobile && t('more')}
                             </Button>
+                          </Dropdown>
                         </div>
                       }
                     >
@@ -838,6 +904,16 @@ export default function ClientsPage() {
                               {inboundLabel(id)}
                             </Tag>
                           ))}
+                          {filters.groups.map((g) => (
+                            <Tag
+                              key={`g-${g}`}
+                              closable
+                              color="geekblue"
+                              onClose={() => setFilters({ ...filters, groups: filters.groups.filter((x) => x !== g) })}
+                            >
+                              {t('pages.clients.group')}: {g}
+                            </Tag>
+                          ))}
                           {(filters.expiryFrom || filters.expiryTo) && (
                             <Tag closable color="purple" onClose={() => clearOneFilter('expiryFrom')}>
                               {t('pages.clients.expiryTime')}: {filters.expiryFrom ? IntlUtil.formatDate(filters.expiryFrom, datepicker) : '…'}
@@ -1008,6 +1084,7 @@ export default function ClientsPage() {
             inbounds={inbounds}
             ipLimitEnable={ipLimitEnable}
             tgBotEnable={tgBotEnable}
+            groups={allGroups}
             save={onSave}
             onOpenChange={setFormOpen}
           />
@@ -1035,6 +1112,7 @@ export default function ClientsPage() {
             open={bulkAddOpen}
             inbounds={inbounds}
             ipLimitEnable={ipLimitEnable}
+            groups={allGroups}
             onOpenChange={setBulkAddOpen}
             onSaved={() => setBulkAddOpen(false)}
           />
@@ -1054,6 +1132,31 @@ export default function ClientsPage() {
             }}
           />
         </LazyMount>
+        <LazyMount when={subLinksOpen}>
+          <SubLinksModal
+            open={subLinksOpen}
+            emails={selectedRowKeys}
+            clients={clients}
+            subSettings={subSettings}
+            onOpenChange={setSubLinksOpen}
+          />
+        </LazyMount>
+        <LazyMount when={bulkGroupOpen}>
+          <BulkAssignGroupModal
+            open={bulkGroupOpen}
+            count={selectedRowKeys.length}
+            groups={allGroups}
+            onOpenChange={setBulkGroupOpen}
+            onSubmit={async (group) => {
+              const msg = await bulkAssignGroup([...selectedRowKeys], group);
+              if (msg?.success) {
+                setSelectedRowKeys([]);
+                return (msg.obj as { affected?: number } | undefined) ?? { affected: 0 };
+              }
+              return null;
+            }}
+          />
+        </LazyMount>
         <LazyMount when={filterDrawerOpen}>
           <FilterDrawer
             open={filterDrawerOpen}
@@ -1062,6 +1165,7 @@ export default function ClientsPage() {
             onChange={setFilters}
             inbounds={inbounds}
             protocols={protocolOptions}
+            groups={groupOptions}
           />
         </LazyMount>
       </Layout>

frontend/src/pages/clients/FilterDrawer.tsx

@@ -27,6 +27,7 @@ interface FilterDrawerProps {
   onChange: (next: ClientFilters) => void;
   inbounds: InboundOption[];
   protocols: string[];
+  groups: string[];
 }
 
 const BUCKET_KEYS = ['active', 'expiring', 'depleted', 'deactive', 'online'] as const;
@@ -38,6 +39,7 @@ export default function FilterDrawer({
   onChange,
   inbounds,
   protocols,
+  groups,
 }: FilterDrawerProps) {
   const { t } = useTranslation();
 
@@ -60,6 +62,11 @@ export default function FilterDrawer({
     [protocols],
   );
 
+  const groupOptions = useMemo(
+    () => groups.map((g) => ({ value: g, label: g })),
+    [groups],
+  );
+
   const dateRange: [Dayjs | null, Dayjs | null] = [
     filters.expiryFrom ? dayjs(filters.expiryFrom) : null,
     filters.expiryTo ? dayjs(filters.expiryTo) : null,
@@ -126,6 +133,21 @@ export default function FilterDrawer({
           />
         </Form.Item>
 
+        <Form.Item label={t('pages.clients.group')}>
+          <Select
+            mode="multiple"
+            value={filters.groups}
+            onChange={(v) => patch('groups', v as string[])}
+            options={groupOptions}
+            placeholder={t('pages.clients.groupPlaceholder')}
+            maxTagCount="responsive"
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            listHeight={220}
+          />
+        </Form.Item>
+
         <Form.Item label={t('pages.clients.expiryTime')}>
           <DatePicker.RangePicker
             value={dateRange}

frontend/src/pages/clients/SubLinksModal.tsx

@@ -0,0 +1,193 @@
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Alert, Button, Modal, Table, Tooltip, Typography, message } from 'antd';
+import type { TableColumnType } from 'antd';
+import { CopyOutlined, DownloadOutlined } from '@ant-design/icons';
+
+import type { ClientRecord } from '@/hooks/useClients';
+
+interface SubSettings {
+  enable: boolean;
+  subURI: string;
+  subJsonURI: string;
+  subJsonEnable: boolean;
+}
+
+interface SubLinksModalProps {
+  open: boolean;
+  emails: string[];
+  clients: ClientRecord[];
+  subSettings?: SubSettings;
+  onOpenChange: (open: boolean) => void;
+}
+
+interface Row {
+  key: string;
+  email: string;
+  subId: string;
+  link: string;
+  jsonLink: string;
+}
+
+export default function SubLinksModal({
+  open,
+  emails,
+  clients,
+  subSettings,
+  onOpenChange,
+}: SubLinksModalProps) {
+  const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
+
+  const enabled = !!subSettings?.enable && !!subSettings?.subURI;
+  const jsonEnabled = !!subSettings?.subJsonEnable && !!subSettings?.subJsonURI;
+
+  const rows = useMemo<Row[]>(() => {
+    if (!enabled) return [];
+    const byEmail = new Map(clients.map((c) => [c.email, c]));
+    const out: Row[] = [];
+    for (const email of emails) {
+      const c = byEmail.get(email);
+      if (!c?.subId) continue;
+      out.push({
+        key: email,
+        email,
+        subId: c.subId,
+        link: subSettings!.subURI + c.subId,
+        jsonLink: jsonEnabled ? subSettings!.subJsonURI + c.subId : '',
+      });
+    }
+    return out;
+  }, [emails, clients, enabled, jsonEnabled, subSettings]);
+
+  const allText = useMemo(
+    () => rows.map((r) => (jsonEnabled ? `${r.email}\t${r.link}\t${r.jsonLink}` : `${r.email}\t${r.link}`)).join('\n'),
+    [rows, jsonEnabled],
+  );
+
+  async function copy(text: string, label?: string) {
+    try {
+      await navigator.clipboard.writeText(text);
+      messageApi.success(label || t('copied'));
+    } catch {
+      messageApi.error(t('somethingWentWrong'));
+    }
+  }
+
+  function download() {
+    const blob = new Blob([allText], { type: 'text/plain;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    a.href = url;
+    a.download = `sub-links-${stamp}.txt`;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    URL.revokeObjectURL(url);
+  }
+
+  const columns: TableColumnType<Row>[] = [
+    {
+      title: t('pages.clients.client'),
+      dataIndex: 'email',
+      key: 'email',
+      width: 180,
+      ellipsis: true,
+    },
+    {
+      title: t('pages.clients.subLinkColumn'),
+      dataIndex: 'link',
+      key: 'link',
+      ellipsis: true,
+      render: (link: string) => (
+        <Tooltip title={link} placement="topLeft">
+          <Typography.Text copyable={false} ellipsis>{link}</Typography.Text>
+        </Tooltip>
+      ),
+    },
+    {
+      title: '',
+      key: 'actions',
+      width: 64,
+      render: (_v, row) => (
+        <Button size="small" type="text" icon={<CopyOutlined />} onClick={() => copy(row.link, t('copied'))} />
+      ),
+    },
+  ];
+
+  if (jsonEnabled) {
+    columns.splice(2, 0, {
+      title: t('pages.clients.subJsonLinkColumn'),
+      dataIndex: 'jsonLink',
+      key: 'jsonLink',
+      ellipsis: true,
+      render: (link: string) => (
+        <Tooltip title={link} placement="topLeft">
+          <Typography.Text copyable={false} ellipsis>{link}</Typography.Text>
+        </Tooltip>
+      ),
+    });
+  }
+
+  return (
+    <>
+      {messageContextHolder}
+      <Modal
+        open={open}
+        title={t('pages.clients.subLinksTitle', { count: rows.length })}
+        width={780}
+        footer={
+          <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+            <Button onClick={() => onOpenChange(false)}>{t('close')}</Button>
+            <div style={{ display: 'flex', gap: 8 }}>
+              <Button
+                icon={<CopyOutlined />}
+                disabled={rows.length === 0}
+                onClick={() => copy(allText, t('pages.clients.subLinksCopiedAll', { count: rows.length }))}
+              >
+                {t('pages.clients.subLinksCopyAll')}
+              </Button>
+              <Button
+                type="primary"
+                icon={<DownloadOutlined />}
+                disabled={rows.length === 0}
+                onClick={download}
+              >
+                {t('download')}
+              </Button>
+            </div>
+          </div>
+        }
+        onCancel={() => onOpenChange(false)}
+      >
+        {!enabled && (
+          <Alert
+            type="warning"
+            showIcon
+            message={t('pages.clients.subLinksDisabled')}
+            description={t('pages.clients.subLinksDisabledHint')}
+            style={{ marginBottom: 12 }}
+          />
+        )}
+        {enabled && rows.length === 0 && (
+          <Alert
+            type="info"
+            showIcon
+            message={t('pages.clients.subLinksEmpty')}
+            style={{ marginBottom: 12 }}
+          />
+        )}
+        {rows.length > 0 && (
+          <Table<Row>
+            dataSource={rows}
+            columns={columns}
+            size="small"
+            pagination={false}
+            scroll={{ y: 360 }}
+          />
+        )}
+      </Modal>
+    </>
+  );
+}

frontend/src/pages/clients/filters.ts

@@ -2,6 +2,7 @@ export interface ClientFilters {
   buckets: string[];
   protocols: string[];
   inboundIds: number[];
+  groups: string[];
   expiryFrom?: number;
   expiryTo?: number;
   usageFromGB?: number;
@@ -16,6 +17,7 @@ export function emptyFilters(): ClientFilters {
     buckets: [],
     protocols: [],
     inboundIds: [],
+    groups: [],
     autoRenew: '',
     hasTgId: '',
     hasComment: '',
@@ -27,6 +29,7 @@ export function activeFilterCount(f: ClientFilters): number {
   if (f.buckets.length) n++;
   if (f.protocols.length) n++;
   if (f.inboundIds.length) n++;
+  if (f.groups.length) n++;
   if (f.expiryFrom || f.expiryTo) n++;
   if (f.usageFromGB || f.usageToGB) n++;
   if (f.autoRenew) n++;

frontend/src/pages/groups/GroupsPage.tsx

@@ -0,0 +1,528 @@
+import { lazy, useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+  Button,
+  Card,
+  Col,
+  ConfigProvider,
+  Dropdown,
+  Form,
+  Input,
+  Layout,
+  Modal,
+  Row,
+  Space,
+  Spin,
+  Statistic,
+  Table,
+  Tag,
+  Tooltip,
+  message,
+} from 'antd';
+import type { MenuProps, TableColumnsType } from 'antd';
+import {
+  ClockCircleOutlined,
+  DeleteOutlined,
+  EditOutlined,
+  LinkOutlined,
+  MoreOutlined,
+  PlusOutlined,
+  RetweetOutlined,
+  TagsOutlined,
+  TeamOutlined,
+} from '@ant-design/icons';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+
+import { useTheme } from '@/hooks/useTheme';
+import { useMediaQuery } from '@/hooks/useMediaQuery';
+import { usePageTitle } from '@/hooks/usePageTitle';
+import { useClients } from '@/hooks/useClients';
+import { HttpUtil } from '@/utils';
+import { setMessageInstance } from '@/utils/messageBus';
+import AppSidebar from '@/components/AppSidebar';
+import LazyMount from '@/components/LazyMount';
+import { keys } from '@/api/queryKeys';
+import { GroupSummaryListSchema, type GroupSummary } from '@/schemas/client';
+import { parseMsg } from '@/utils/zodValidate';
+
+const SubLinksModal = lazy(() => import('../clients/SubLinksModal'));
+const ClientBulkAdjustModal = lazy(() => import('../clients/ClientBulkAdjustModal'));
+
+const JSON_HEADERS = { headers: { 'Content-Type': 'application/json' } } as const;
+
+async function fetchGroups(): Promise<GroupSummary[]> {
+  const msg = await HttpUtil.get('/panel/api/clients/groups', undefined, { silent: true });
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to load groups');
+  const validated = parseMsg(msg, GroupSummaryListSchema, 'clients/groups');
+  return validated.obj ?? [];
+}
+
+async function fetchEmailsForGroup(name: string): Promise<string[]> {
+  const msg = await HttpUtil.get<string[]>(
+    `/panel/api/clients/groups/${encodeURIComponent(name)}/emails`,
+    undefined,
+    { silent: true },
+  );
+  if (!msg?.success || !Array.isArray(msg.obj)) return [];
+  return msg.obj;
+}
+
+export default function GroupsPage() {
+  usePageTitle();
+  const { t } = useTranslation();
+  const { isDark, isUltra, antdThemeConfig } = useTheme();
+  const { isMobile } = useMediaQuery();
+  const [modal, modalContextHolder] = Modal.useModal();
+  const [messageApi, messageContextHolder] = message.useMessage();
+  useEffect(() => { setMessageInstance(messageApi); }, [messageApi]);
+  const queryClient = useQueryClient();
+
+  const { clients, subSettings, bulkAdjust, bulkDelete } = useClients();
+
+  const groupsQuery = useQuery({
+    queryKey: keys.clients.groups(),
+    queryFn: fetchGroups,
+  });
+  const groups = useMemo(() => groupsQuery.data ?? [], [groupsQuery.data]);
+  const loading = groupsQuery.isFetching;
+  const fetched = groupsQuery.data !== undefined;
+
+  const invalidate = useCallback(() => {
+    queryClient.invalidateQueries({ queryKey: keys.clients.root() });
+  }, [queryClient]);
+
+  const createMut = useMutation({
+    mutationFn: (body: { name: string }) =>
+      HttpUtil.post('/panel/api/clients/groups/create', body, JSON_HEADERS),
+    onSuccess: (msg) => { if (msg?.success) invalidate(); },
+  });
+
+  const renameMut = useMutation({
+    mutationFn: (body: { oldName: string; newName: string }) =>
+      HttpUtil.post('/panel/api/clients/groups/rename', body, JSON_HEADERS),
+    onSuccess: (msg) => { if (msg?.success) invalidate(); },
+  });
+
+  const deleteMut = useMutation({
+    mutationFn: (body: { name: string }) =>
+      HttpUtil.post('/panel/api/clients/groups/delete', body, JSON_HEADERS),
+    onSuccess: (msg) => { if (msg?.success) invalidate(); },
+  });
+
+  const bulkResetMut = useMutation({
+    mutationFn: (body: { emails: string[] }) =>
+      HttpUtil.post('/panel/api/clients/bulkResetTraffic', body, JSON_HEADERS),
+    onSuccess: (msg) => { if (msg?.success) invalidate(); },
+  });
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [createName, setCreateName] = useState('');
+
+  const [renameOpen, setRenameOpen] = useState(false);
+  const [renameTarget, setRenameTarget] = useState<GroupSummary | null>(null);
+  const [renameValue, setRenameValue] = useState('');
+
+  const [subLinksOpen, setSubLinksOpen] = useState(false);
+  const [adjustOpen, setAdjustOpen] = useState(false);
+  const [groupEmails, setGroupEmails] = useState<string[]>([]);
+  const [groupForAction, setGroupForAction] = useState<GroupSummary | null>(null);
+
+  const totalGroups = groups.length;
+  const totalClients = useMemo(
+    () => groups.reduce((acc, g) => acc + (g.clientCount || 0), 0),
+    [groups],
+  );
+  const emptyGroups = useMemo(
+    () => groups.filter((g) => (g.clientCount || 0) === 0).length,
+    [groups],
+  );
+
+  function openCreate() {
+    setCreateName('');
+    setCreateOpen(true);
+  }
+
+  async function confirmCreate() {
+    const name = createName.trim();
+    if (!name) return;
+    if (groups.some((g) => g.name.toLowerCase() === name.toLowerCase())) {
+      messageApi.error(t('pages.groups.renameCollision', { name }));
+      return;
+    }
+    const msg = await createMut.mutateAsync({ name });
+    if (msg?.success) {
+      messageApi.success(t('pages.groups.createSuccess', { name }));
+      setCreateOpen(false);
+    }
+  }
+
+  function openRename(g: GroupSummary) {
+    setRenameTarget(g);
+    setRenameValue(g.name);
+    setRenameOpen(true);
+  }
+
+  async function confirmRename() {
+    if (!renameTarget) return;
+    const next = renameValue.trim();
+    if (!next || next === renameTarget.name) {
+      setRenameOpen(false);
+      return;
+    }
+    if (groups.some((g) => g.name.toLowerCase() === next.toLowerCase() && g.name !== renameTarget.name)) {
+      messageApi.error(t('pages.groups.renameCollision', { name: next }));
+      return;
+    }
+    const msg = await renameMut.mutateAsync({ oldName: renameTarget.name, newName: next });
+    if (msg?.success) {
+      const affected = (msg.obj as { affected?: number } | undefined)?.affected ?? 0;
+      messageApi.success(t('pages.groups.renameSuccess', { count: affected }));
+      setRenameOpen(false);
+    }
+  }
+
+  function onDelete(g: GroupSummary) {
+    modal.confirm({
+      title: t('pages.groups.deleteConfirmTitle', { name: g.name }),
+      content: t('pages.groups.deleteConfirmContent', { count: g.clientCount }),
+      okText: t('delete'),
+      okType: 'danger',
+      cancelText: t('cancel'),
+      onOk: async () => {
+        const msg = await deleteMut.mutateAsync({ name: g.name });
+        if (msg?.success) {
+          const affected = (msg.obj as { affected?: number } | undefined)?.affected ?? 0;
+          messageApi.success(t('pages.groups.deleteSuccess', { count: affected }));
+        }
+      },
+    });
+  }
+
+  async function openSubLinksFor(g: GroupSummary) {
+    if (!g.clientCount) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    const emails = await fetchEmailsForGroup(g.name);
+    if (emails.length === 0) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    setGroupForAction(g);
+    setGroupEmails(emails);
+    setSubLinksOpen(true);
+  }
+
+  async function openAdjustFor(g: GroupSummary) {
+    if (!g.clientCount) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    const emails = await fetchEmailsForGroup(g.name);
+    if (emails.length === 0) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    setGroupForAction(g);
+    setGroupEmails(emails);
+    setAdjustOpen(true);
+  }
+
+  function onDeleteClients(g: GroupSummary) {
+    if (!g.clientCount) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    modal.confirm({
+      title: t('pages.groups.deleteClientsConfirmTitle', { name: g.name }),
+      content: t('pages.groups.deleteClientsConfirmContent', { count: g.clientCount }),
+      okText: t('delete'),
+      okType: 'danger',
+      cancelText: t('cancel'),
+      onOk: async () => {
+        const emails = await fetchEmailsForGroup(g.name);
+        if (emails.length === 0) return;
+        const msg = await bulkDelete(emails);
+        if (msg?.success) {
+          const ok = msg.obj?.deleted ?? 0;
+          const skipped = msg.obj?.skipped ?? [];
+          const failed = skipped.length;
+          if (failed === 0) {
+            messageApi.success(t('pages.groups.deleteClientsSuccess', { count: ok }));
+          } else {
+            const firstError = skipped[0]?.reason ?? msg?.msg ?? '';
+            messageApi.warning(firstError
+              ? `${t('pages.groups.deleteClientsMixed', { ok, failed })} — ${firstError}`
+              : t('pages.groups.deleteClientsMixed', { ok, failed }));
+          }
+        }
+      },
+    });
+  }
+
+  function onResetTraffic(g: GroupSummary) {
+    if (!g.clientCount) {
+      messageApi.info(t('pages.groups.emptyForAction'));
+      return;
+    }
+    modal.confirm({
+      title: t('pages.groups.resetConfirmTitle', { name: g.name }),
+      content: t('pages.groups.resetConfirmContent', { count: g.clientCount }),
+      okText: t('reset'),
+      okType: 'danger',
+      cancelText: t('cancel'),
+      onOk: async () => {
+        const emails = await fetchEmailsForGroup(g.name);
+        if (emails.length === 0) return;
+        const msg = await bulkResetMut.mutateAsync({ emails });
+        if (msg?.success) {
+          const affected = (msg.obj as { affected?: number } | undefined)?.affected ?? emails.length;
+          messageApi.success(t('pages.groups.resetSuccess', { count: affected }));
+        }
+      },
+    });
+  }
+
+  function rowActions(row: GroupSummary): MenuProps['items'] {
+    return [
+      {
+        key: 'subLinks',
+        icon: <LinkOutlined />,
+        label: t('pages.clients.subLinksSelected', { count: row.clientCount || 0 }),
+        disabled: !row.clientCount,
+        onClick: () => openSubLinksFor(row),
+      },
+      {
+        key: 'adjust',
+        icon: <ClockCircleOutlined />,
+        label: t('pages.clients.adjustSelected', { count: row.clientCount || 0 }),
+        disabled: !row.clientCount,
+        onClick: () => openAdjustFor(row),
+      },
+      {
+        key: 'reset',
+        icon: <RetweetOutlined />,
+        label: t('pages.groups.resetTraffic'),
+        disabled: !row.clientCount,
+        onClick: () => onResetTraffic(row),
+      },
+      { type: 'divider' },
+      {
+        key: 'rename',
+        icon: <EditOutlined />,
+        label: t('pages.groups.rename'),
+        onClick: () => openRename(row),
+      },
+      {
+        key: 'deleteClients',
+        icon: <DeleteOutlined />,
+        label: t('pages.groups.deleteClients'),
+        danger: true,
+        disabled: !row.clientCount,
+        onClick: () => onDeleteClients(row),
+      },
+      {
+        key: 'delete',
+        icon: <DeleteOutlined />,
+        label: t('pages.groups.deleteGroupOnly'),
+        danger: true,
+        onClick: () => onDelete(row),
+      },
+    ];
+  }
+
+  const columns: TableColumnsType<GroupSummary> = [
+    {
+      title: t('pages.clients.actions'),
+      key: 'actions',
+      width: 90,
+      render: (_v, row) => (
+        <Space size={4}>
+          <Dropdown trigger={['click']} menu={{ items: rowActions(row) }}>
+            <Button size="small" type="text" icon={<MoreOutlined />} />
+          </Dropdown>
+          <Tooltip title={t('pages.groups.rename')}>
+            <Button size="small" type="text" icon={<EditOutlined />} onClick={() => openRename(row)} />
+          </Tooltip>
+        </Space>
+      ),
+    },
+    {
+      title: t('pages.groups.name'),
+      dataIndex: 'name',
+      key: 'name',
+      render: (name: string) => <Tag color="geekblue" style={{ margin: 0, fontSize: 13 }}>{name}</Tag>,
+    },
+    {
+      title: t('pages.groups.clientCount'),
+      dataIndex: 'clientCount',
+      key: 'clientCount',
+      width: 180,
+      render: (count: number) => <span>{count || 0}</span>,
+    },
+  ];
+
+  const pageClass = useMemo(() => {
+    const classes = ['groups-page'];
+    if (isDark) classes.push('is-dark');
+    if (isUltra) classes.push('is-ultra');
+    return classes.join(' ');
+  }, [isDark, isUltra]);
+
+  return (
+    <ConfigProvider theme={antdThemeConfig}>
+      {messageContextHolder}
+      {modalContextHolder}
+      <Layout className={pageClass}>
+        <AppSidebar />
+        <Layout className="content-shell">
+          <Layout.Content id="content-layout" className="content-area">
+            <Spin spinning={!fetched} delay={200} description="Loading…" size="large">
+              {!fetched ? (
+                <div className="loading-spacer" />
+              ) : (
+                <Row gutter={[isMobile ? 8 : 16, isMobile ? 8 : 12]}>
+                  <Col span={24}>
+                    <Card size="small" hoverable className="summary-card">
+                      <Row gutter={[16, isMobile ? 16 : 12]}>
+                        <Col xs={12} sm={8} md={6}>
+                          <Statistic
+                            title={t('pages.groups.totalGroups')}
+                            value={String(totalGroups)}
+                            prefix={<TagsOutlined />}
+                          />
+                        </Col>
+                        <Col xs={12} sm={8} md={6}>
+                          <Statistic
+                            title={t('pages.groups.totalGroupedClients')}
+                            value={String(totalClients)}
+                            prefix={<TeamOutlined />}
+                          />
+                        </Col>
+                        <Col xs={12} sm={8} md={6}>
+                          <Statistic
+                            title={t('pages.groups.emptyGroups')}
+                            value={String(emptyGroups)}
+                          />
+                        </Col>
+                      </Row>
+                    </Card>
+                  </Col>
+
+                  <Col span={24}>
+                    <Card
+                      size="small"
+                      hoverable
+                      title={
+                        <div className="card-toolbar">
+                          <Button type="primary" icon={<PlusOutlined />} onClick={openCreate}>
+                            {!isMobile && t('pages.groups.addGroup')}
+                          </Button>
+                        </div>
+                      }
+                    >
+                      <Table<GroupSummary>
+                        dataSource={groups}
+                        columns={columns}
+                        rowKey="name"
+                        size="small"
+                        pagination={false}
+                        loading={loading}
+                        locale={{
+                          emptyText: (
+                            <div className="card-empty">
+                              <TagsOutlined style={{ fontSize: 32, marginBottom: 8 }} />
+                              <div>{t('noData')}</div>
+                            </div>
+                          ),
+                        }}
+                      />
+                    </Card>
+                  </Col>
+                </Row>
+              )}
+            </Spin>
+          </Layout.Content>
+        </Layout>
+
+        <Modal
+          open={createOpen}
+          title={t('pages.groups.addGroup')}
+          okText={t('create')}
+          cancelText={t('cancel')}
+          confirmLoading={createMut.isPending}
+          onCancel={() => setCreateOpen(false)}
+          onOk={confirmCreate}
+          destroyOnHidden
+        >
+          <Form layout="vertical">
+            <Form.Item label={t('pages.groups.name')}>
+              <Input
+                value={createName}
+                onChange={(e) => setCreateName(e.target.value)}
+                onPressEnter={confirmCreate}
+                placeholder={t('pages.clients.groupPlaceholder')}
+                autoFocus
+              />
+            </Form.Item>
+          </Form>
+        </Modal>
+
+        <Modal
+          open={renameOpen}
+          title={renameTarget ? t('pages.groups.renameTitle', { name: renameTarget.name }) : ''}
+          okText={t('save')}
+          cancelText={t('cancel')}
+          confirmLoading={renameMut.isPending}
+          onCancel={() => setRenameOpen(false)}
+          onOk={confirmRename}
+          destroyOnHidden
+        >
+          <Form layout="vertical">
+            <Form.Item label={t('pages.groups.name')}>
+              <Input
+                value={renameValue}
+                onChange={(e) => setRenameValue(e.target.value)}
+                onPressEnter={confirmRename}
+                placeholder={t('pages.clients.groupPlaceholder')}
+                autoFocus
+              />
+            </Form.Item>
+          </Form>
+        </Modal>
+
+        <LazyMount when={subLinksOpen}>
+          <SubLinksModal
+            open={subLinksOpen}
+            emails={groupEmails}
+            clients={clients}
+            subSettings={subSettings}
+            onOpenChange={setSubLinksOpen}
+          />
+        </LazyMount>
+
+        <LazyMount when={adjustOpen}>
+          <ClientBulkAdjustModal
+            open={adjustOpen}
+            count={groupEmails.length}
+            onOpenChange={setAdjustOpen}
+            onSubmit={async (addDays, addBytes) => {
+              const msg = await bulkAdjust(groupEmails, addDays, addBytes);
+              if (msg?.success) {
+                const obj = msg.obj ?? { adjusted: 0 };
+                messageApi.success(
+                  t('pages.groups.adjustSuccess', {
+                    count: obj.adjusted ?? 0,
+                    name: groupForAction?.name ?? '',
+                  }),
+                );
+                return obj;
+              }
+              return null;
+            }}
+          />
+        </LazyMount>
+      </Layout>
+    </ConfigProvider>
+  );
+}

frontend/src/routes.tsx

@@ -6,6 +6,7 @@ import PanelLayout from '@/layouts/PanelLayout';
 const IndexPage = lazy(() => import('@/pages/index/IndexPage'));
 const InboundsPage = lazy(() => import('@/pages/inbounds/InboundsPage'));
 const ClientsPage = lazy(() => import('@/pages/clients/ClientsPage'));
+const GroupsPage = lazy(() => import('@/pages/groups/GroupsPage'));
 const NodesPage = lazy(() => import('@/pages/nodes/NodesPage'));
 const SettingsPage = lazy(() => import('@/pages/settings/SettingsPage'));
 const XrayPage = lazy(() => import('@/pages/xray/XrayPage'));
@@ -23,6 +24,7 @@ const routes: RouteObject[] = [
       { index: true, element: withSuspense(<IndexPage />) },
       { path: 'inbounds', element: withSuspense(<InboundsPage />) },
       { path: 'clients', element: withSuspense(<ClientsPage />) },
+      { path: 'groups', element: withSuspense(<GroupsPage />) },
       { path: 'nodes', element: withSuspense(<NodesPage />) },
       { path: 'settings', element: withSuspense(<SettingsPage />) },
       { path: 'xray', element: withSuspense(<XrayPage />) },

frontend/src/schemas/client.ts

@@ -25,6 +25,7 @@ export const ClientRecordSchema = z.object({
   expiryTime: z.number().optional(),
   limitIp: z.number().optional(),
   tgId: z.union([z.number(), z.string()]).optional(),
+  group: z.string().optional(),
   comment: z.string().optional(),
   enable: z.boolean().optional(),
   reset: z.number().optional(),
@@ -63,6 +64,7 @@ export const ClientPageResponseSchema = z.object({
   page: z.number(),
   pageSize: z.number(),
   summary: ClientsSummarySchema.nullable().optional(),
+  groups: nullableStringArray.optional(),
 });
 
 export const ClientHydrateSchema = z.object({
@@ -97,6 +99,13 @@ export const DelDepletedResultSchema = z.object({
 
 export const OnlinesSchema = nullableStringArray;
 
+export const GroupSummarySchema = z.object({
+  name: z.string(),
+  clientCount: z.number(),
+});
+
+export const GroupSummaryListSchema = z.array(GroupSummarySchema).nullable().transform((v) => v ?? []);
+
 export const ClientFormSchema = z.object({
   email: z.string().trim().min(1, 'pages.clients.email'),
   subId: z.string(),
@@ -111,6 +120,7 @@ export const ClientFormSchema = z.object({
   reset: z.number().int().min(0),
   limitIp: z.number().int().min(0),
   tgId: z.number().int().min(0),
+  group: z.string(),
   comment: z.string(),
   enable: z.boolean(),
   inboundIds: z.array(z.number()),
@@ -137,6 +147,7 @@ export const ClientBulkAddFormSchema = z.object({
   emailPostfix: z.string(),
   quantity: z.number().int().min(1).max(100),
   subId: z.string(),
+  group: z.string(),
   comment: z.string(),
   flow: z.string(),
   limitIp: z.number().int().min(0),
@@ -158,3 +169,4 @@ export type BulkCreateResult = z.infer<typeof BulkCreateResultSchema>;
 export type ClientBulkAddFormValues = z.infer<typeof ClientBulkAddFormSchema>;
 export type ClientBulkAdjustFormValues = z.infer<typeof ClientBulkAdjustFormSchema>;
 export type ClientFormValues = z.infer<typeof ClientFormSchema>;
+export type GroupSummary = z.infer<typeof GroupSummarySchema>;

frontend/src/styles/page-cards.css

@@ -4,6 +4,7 @@
 .xray-page .ant-card,
 .settings-page .ant-card,
 .nodes-page .ant-card,
+.groups-page .ant-card,
 .api-docs-page .ant-card {
   border-radius: 12px;
   box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04);
@@ -16,6 +17,7 @@
 .xray-page.is-dark .ant-card,
 .settings-page.is-dark .ant-card,
 .nodes-page.is-dark .ant-card,
+.groups-page.is-dark .ant-card,
 .api-docs-page.is-dark .ant-card {
   box-shadow:
     0 1px 2px rgba(0, 0, 0, 0.4),
@@ -28,6 +30,7 @@
 .xray-page.is-dark.is-ultra .ant-card,
 .settings-page.is-dark.is-ultra .ant-card,
 .nodes-page.is-dark.is-ultra .ant-card,
+.groups-page.is-dark.is-ultra .ant-card,
 .api-docs-page.is-dark.is-ultra .ant-card {
   box-shadow:
     0 1px 2px rgba(0, 0, 0, 0.6),
@@ -40,6 +43,7 @@
 .xray-page .ant-card.ant-card-hoverable:hover,
 .settings-page .ant-card.ant-card-hoverable:hover,
 .nodes-page .ant-card.ant-card-hoverable:hover,
+.groups-page .ant-card.ant-card-hoverable:hover,
 .api-docs-page .ant-card.ant-card-hoverable:hover {
   transform: translateY(-2px);
   box-shadow: 0 6px 18px rgba(0, 0, 0, 0.08);
@@ -51,6 +55,7 @@
 .xray-page.is-dark .ant-card.ant-card-hoverable:hover,
 .settings-page.is-dark .ant-card.ant-card-hoverable:hover,
 .nodes-page.is-dark .ant-card.ant-card-hoverable:hover,
+.groups-page.is-dark .ant-card.ant-card-hoverable:hover,
 .api-docs-page.is-dark .ant-card.ant-card-hoverable:hover {
   box-shadow:
     0 8px 24px rgba(0, 0, 0, 0.5),
@@ -63,6 +68,7 @@
 .xray-page.is-dark.is-ultra .ant-card.ant-card-hoverable:hover,
 .settings-page.is-dark.is-ultra .ant-card.ant-card-hoverable:hover,
 .nodes-page.is-dark.is-ultra .ant-card.ant-card-hoverable:hover,
+.groups-page.is-dark.is-ultra .ant-card.ant-card-hoverable:hover,
 .api-docs-page.is-dark.is-ultra .ant-card.ant-card-hoverable:hover {
   box-shadow:
     0 8px 24px rgba(0, 0, 0, 0.75),
@@ -75,6 +81,7 @@
 .xray-page .ant-card .ant-card-actions,
 .settings-page .ant-card .ant-card-actions,
 .nodes-page .ant-card .ant-card-actions,
+.groups-page .ant-card .ant-card-actions,
 .api-docs-page .ant-card .ant-card-actions {
   background: transparent;
 }

frontend/src/styles/page-shell.css

@@ -4,6 +4,7 @@
 .xray-page,
 .settings-page,
 .nodes-page,
+.groups-page,
 .api-docs-page {
   --bg-page: #e6e8ec;
   --bg-card: #ffffff;
@@ -17,6 +18,7 @@
 .xray-page.is-dark,
 .settings-page.is-dark,
 .nodes-page.is-dark,
+.groups-page.is-dark,
 .api-docs-page.is-dark {
   --bg-page: #1a1b1f;
   --bg-card: #23252b;
@@ -28,6 +30,7 @@
 .xray-page.is-dark.is-ultra,
 .settings-page.is-dark.is-ultra,
 .nodes-page.is-dark.is-ultra,
+.groups-page.is-dark.is-ultra,
 .api-docs-page.is-dark.is-ultra {
   --bg-page: #000;
   --bg-card: #101013;
@@ -45,6 +48,8 @@
 .settings-page .ant-layout-content,
 .nodes-page .ant-layout,
 .nodes-page .ant-layout-content,
+.groups-page .ant-layout,
+.groups-page .ant-layout-content,
 .api-docs-page .ant-layout,
 .api-docs-page .ant-layout-content {
   background: transparent;
@@ -56,6 +61,7 @@
 .xray-page .content-shell,
 .settings-page .content-shell,
 .nodes-page .content-shell,
+.groups-page .content-shell,
 .api-docs-page .content-shell {
   background: transparent;
 }
@@ -65,14 +71,16 @@
 .inbounds-page .content-area,
 .xray-page .content-area,
 .settings-page .content-area,
-.nodes-page .content-area {
+.nodes-page .content-area,
+.groups-page .content-area {
   padding: 24px;
 }
 
 @media (max-width: 768px) {
   .clients-page .content-area,
   .inbounds-page .content-area,
-  .nodes-page .content-area {
+  .nodes-page .content-area,
+  .groups-page .content-area {
     padding: 8px;
   }
 }
@@ -130,14 +138,16 @@
 
 .clients-page .summary-card,
 .inbounds-page .summary-card,
-.nodes-page .summary-card {
+.nodes-page .summary-card,
+.groups-page .summary-card {
   padding: 16px;
 }
 
 @media (max-width: 768px) {
   .clients-page .summary-card,
   .inbounds-page .summary-card,
-  .nodes-page .summary-card {
+  .nodes-page .summary-card,
+  .groups-page .summary-card {
     padding: 8px;
   }
 }

web/controller/client.go

@@ -47,12 +47,20 @@ func (a *ClientController) initRouter(g *gin.RouterGroup) {
 	g.POST("/bulkAdjust", a.bulkAdjust)
 	g.POST("/bulkDel", a.bulkDelete)
 	g.POST("/bulkCreate", a.bulkCreate)
+	g.POST("/bulkAssignGroup", a.bulkAssignGroup)
 	g.POST("/resetTraffic/:email", a.resetTrafficByEmail)
 	g.POST("/updateTraffic/:email", a.updateTrafficByEmail)
 	g.POST("/ips/:email", a.getIps)
 	g.POST("/clearIps/:email", a.clearIps)
 	g.POST("/onlines", a.onlines)
 	g.POST("/lastOnline", a.lastOnline)
+
+	g.GET("/groups", a.listGroups)
+	g.GET("/groups/:name/emails", a.groupEmails)
+	g.POST("/groups/create", a.createGroup)
+	g.POST("/groups/rename", a.renameGroup)
+	g.POST("/groups/delete", a.deleteGroup)
+	g.POST("/bulkResetTraffic", a.bulkResetTraffic)
 }
 
 func (a *ClientController) list(c *gin.Context) {
@@ -210,6 +218,27 @@ type bulkDeleteRequest struct {
 	KeepTraffic bool     `json:"keepTraffic"`
 }
 
+type bulkAssignGroupRequest struct {
+	Emails []string `json:"emails"`
+	Group  string   `json:"group"`
+}
+
+func (a *ClientController) bulkAssignGroup(c *gin.Context) {
+	var req bulkAssignGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	affected, err := a.clientService.AssignGroup(req.Emails, req.Group)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	jsonObj(c, gin.H{"affected": affected}, nil)
+	a.xrayService.SetToNeedRestart()
+	notifyClientsChanged()
+}
+
 func (a *ClientController) bulkDelete(c *gin.Context) {
 	var req bulkDeleteRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -393,3 +422,101 @@ func (a *ClientController) detach(c *gin.Context) {
 	}
 	notifyClientsChanged()
 }
+
+func (a *ClientController) listGroups(c *gin.Context) {
+	rows, err := a.clientService.ListGroups()
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	jsonObj(c, rows, nil)
+}
+
+func (a *ClientController) groupEmails(c *gin.Context) {
+	name := c.Param("name")
+	emails, err := a.clientService.EmailsByGroup(name)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	jsonObj(c, emails, nil)
+}
+
+type bulkResetRequest struct {
+	Emails []string `json:"emails"`
+}
+
+func (a *ClientController) bulkResetTraffic(c *gin.Context) {
+	var req bulkResetRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	affected, err := a.clientService.BulkResetTraffic(&a.inboundService, req.Emails)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	jsonObj(c, gin.H{"affected": affected}, nil)
+	a.xrayService.SetToNeedRestart()
+	notifyClientsChanged()
+}
+
+type groupCreateBody struct {
+	Name string `json:"name"`
+}
+
+func (a *ClientController) createGroup(c *gin.Context) {
+	var body groupCreateBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	if err := a.clientService.CreateGroup(body.Name); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	jsonObj(c, gin.H{"name": body.Name}, nil)
+	notifyClientsChanged()
+}
+
+type groupRenameBody struct {
+	OldName string `json:"oldName"`
+	NewName string `json:"newName"`
+}
+
+func (a *ClientController) renameGroup(c *gin.Context) {
+	var body groupRenameBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	affected, err := a.clientService.RenameGroup(body.OldName, body.NewName)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	a.xrayService.SetToNeedRestart()
+	jsonObj(c, gin.H{"affected": affected}, nil)
+	notifyClientsChanged()
+}
+
+type groupDeleteBody struct {
+	Name string `json:"name"`
+}
+
+func (a *ClientController) deleteGroup(c *gin.Context) {
+	var body groupDeleteBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	affected, err := a.clientService.DeleteGroup(body.Name)
+	if err != nil {
+		jsonMsg(c, I18nWeb(c, "somethingWentWrong"), err)
+		return
+	}
+	a.xrayService.SetToNeedRestart()
+	jsonObj(c, gin.H{"affected": affected}, nil)
+	notifyClientsChanged()
+}

web/service/client.go

@@ -237,6 +237,7 @@ func (s *ClientService) SyncInbound(tx *gorm.DB, inboundId int, clients []model.
 			row.ExpiryTime = incoming.ExpiryTime
 			row.Enable = incoming.Enable
 			row.TgID = incoming.TgID
+			row.Group = incoming.Group
 			row.Comment = incoming.Comment
 			row.Reset = incoming.Reset
 			if incoming.CreatedAt > 0 && (row.CreatedAt == 0 || incoming.CreatedAt < row.CreatedAt) {
@@ -863,6 +864,7 @@ type ClientSlim struct {
 	ExpiryTime int64               `json:"expiryTime"`
 	LimitIP    int                 `json:"limitIp"`
 	Reset      int                 `json:"reset"`
+	Group      string              `json:"group,omitempty"`
 	Comment    string              `json:"comment,omitempty"`
 	InboundIds []int               `json:"inboundIds"`
 	Traffic    *xray.ClientTraffic `json:"traffic,omitempty"`
@@ -894,6 +896,7 @@ type ClientPageParams struct {
 	AutoRenew  string `form:"autoRenew"`
 	HasTgID    string `form:"hasTgId"`
 	HasComment string `form:"hasComment"`
+	Group      string `form:"group"`
 }
 
 // ClientPageResponse is the shape returned by ListPaged. `Total` is the
@@ -908,6 +911,7 @@ type ClientPageResponse struct {
 	Page     int            `json:"page"`
 	PageSize int            `json:"pageSize"`
 	Summary  ClientsSummary `json:"summary"`
+	Groups   []string       `json:"groups"`
 }
 
 // ClientsSummary collects per-bucket counts plus the matching email lists so
@@ -1017,6 +1021,9 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
 		if !clientMatchesHasComment(c, params.HasComment) {
 			continue
 		}
+		if !clientMatchesAnyGroup(c, params.Group) {
+			continue
+		}
 		filtered = append(filtered, c)
 	}
 
@@ -1038,6 +1045,15 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
 		items = append(items, toClientSlim(c))
 	}
 
+	groupRows, gErr := s.ListGroups()
+	if gErr != nil {
+		return nil, gErr
+	}
+	groups := make([]string, 0, len(groupRows))
+	for _, g := range groupRows {
+		groups = append(groups, g.Name)
+	}
+
 	return &ClientPageResponse{
 		Items:    items,
 		Total:    total,
@@ -1045,9 +1061,321 @@ func (s *ClientService) ListPaged(inboundSvc *InboundService, settingSvc *Settin
 		Page:     page,
 		PageSize: pageSize,
 		Summary:  summary,
+		Groups:   groups,
 	}, nil
 }
 
+type GroupSummary struct {
+	Name        string `json:"name"`
+	ClientCount int    `json:"clientCount"`
+}
+
+func (s *ClientService) ListGroups() ([]GroupSummary, error) {
+	db := database.GetDB()
+	var derived []GroupSummary
+	if err := db.Model(&model.ClientRecord{}).
+		Select("group_name AS name, COUNT(*) AS client_count").
+		Where("group_name <> ''").
+		Group("group_name").
+		Scan(&derived).Error; err != nil {
+		return nil, err
+	}
+	var stored []model.ClientGroup
+	if err := db.Find(&stored).Error; err != nil {
+		return nil, err
+	}
+	merged := make(map[string]int, len(derived)+len(stored))
+	for _, g := range stored {
+		merged[g.Name] = 0
+	}
+	for _, g := range derived {
+		merged[g.Name] = g.ClientCount
+	}
+	out := make([]GroupSummary, 0, len(merged))
+	for name, count := range merged {
+		out = append(out, GroupSummary{Name: name, ClientCount: count})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		return strings.ToLower(out[i].Name) < strings.ToLower(out[j].Name)
+	})
+	return out, nil
+}
+
+func (s *ClientService) EmailsByGroup(name string) ([]string, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return []string{}, nil
+	}
+	db := database.GetDB()
+	var emails []string
+	if err := db.Model(&model.ClientRecord{}).
+		Where("group_name = ?", name).
+		Order("email ASC").
+		Pluck("email", &emails).Error; err != nil {
+		return nil, err
+	}
+	if emails == nil {
+		emails = []string{}
+	}
+	return emails, nil
+}
+
+func (s *ClientService) BulkResetTraffic(inboundSvc *InboundService, emails []string) (int, error) {
+	if len(emails) == 0 {
+		return 0, nil
+	}
+	count := 0
+	for _, email := range emails {
+		if _, err := s.ResetTrafficByEmail(inboundSvc, email); err != nil {
+			return count, err
+		}
+		count++
+	}
+	return count, nil
+}
+
+func (s *ClientService) CreateGroup(name string) error {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return common.NewError("group name is required")
+	}
+	db := database.GetDB()
+	var count int64
+	if err := db.Model(&model.ClientGroup{}).Where("name = ?", name).Count(&count).Error; err != nil {
+		return err
+	}
+	if count > 0 {
+		return common.NewError("group already exists")
+	}
+	return db.Create(&model.ClientGroup{Name: name}).Error
+}
+
+func (s *ClientService) RenameGroup(oldName, newName string) (int, error) {
+	oldName = strings.TrimSpace(oldName)
+	newName = strings.TrimSpace(newName)
+	if oldName == "" {
+		return 0, common.NewError("old group name is required")
+	}
+	if newName == "" {
+		return 0, common.NewError("new group name is required")
+	}
+	if oldName == newName {
+		return 0, nil
+	}
+	return s.replaceGroupValue(oldName, newName)
+}
+
+func (s *ClientService) DeleteGroup(name string) (int, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return 0, common.NewError("group name is required")
+	}
+	return s.replaceGroupValue(name, "")
+}
+
+func (s *ClientService) AssignGroup(emails []string, group string) (int, error) {
+	group = strings.TrimSpace(group)
+	if len(emails) == 0 {
+		return 0, nil
+	}
+	db := database.GetDB()
+
+	if group != "" {
+		var exists int64
+		if err := db.Model(&model.ClientGroup{}).Where("name = ?", group).Count(&exists).Error; err != nil {
+			return 0, err
+		}
+		if exists == 0 {
+			var derived int64
+			if err := db.Model(&model.ClientRecord{}).Where("group_name = ?", group).Count(&derived).Error; err != nil {
+				return 0, err
+			}
+			if derived == 0 {
+				if err := db.Create(&model.ClientGroup{Name: group}).Error; err != nil {
+					return 0, err
+				}
+			}
+		}
+	}
+
+	var records []model.ClientRecord
+	if err := db.Where("email IN ?", emails).Find(&records).Error; err != nil {
+		return 0, err
+	}
+	if len(records) == 0 {
+		return 0, nil
+	}
+	affectedEmails := make([]string, 0, len(records))
+	for _, r := range records {
+		affectedEmails = append(affectedEmails, r.Email)
+	}
+
+	tx := db.Begin()
+	if err := tx.Model(&model.ClientRecord{}).
+		Where("email IN ?", affectedEmails).
+		UpdateColumn("group_name", group).Error; err != nil {
+		tx.Rollback()
+		return 0, err
+	}
+
+	var inboundIDs []int
+	if err := tx.Table("client_inbounds").
+		Joins("JOIN clients ON clients.id = client_inbounds.client_id").
+		Where("clients.email IN ?", affectedEmails).
+		Distinct("client_inbounds.inbound_id").
+		Pluck("inbound_id", &inboundIDs).Error; err != nil {
+		tx.Rollback()
+		return 0, err
+	}
+
+	emailSet := make(map[string]struct{}, len(affectedEmails))
+	for _, e := range affectedEmails {
+		emailSet[e] = struct{}{}
+	}
+
+	for _, ibID := range inboundIDs {
+		var ib model.Inbound
+		if err := tx.First(&ib, ibID).Error; err != nil {
+			tx.Rollback()
+			return 0, err
+		}
+		var settings map[string]any
+		if err := json.Unmarshal([]byte(ib.Settings), &settings); err != nil {
+			continue
+		}
+		clients, ok := settings["clients"].([]any)
+		if !ok {
+			continue
+		}
+		modified := false
+		for i := range clients {
+			cm, ok := clients[i].(map[string]any)
+			if !ok {
+				continue
+			}
+			email, _ := cm["email"].(string)
+			if _, hit := emailSet[email]; !hit {
+				continue
+			}
+			if group == "" {
+				delete(cm, "group")
+			} else {
+				cm["group"] = group
+			}
+			clients[i] = cm
+			modified = true
+		}
+		if modified {
+			settings["clients"] = clients
+			newSettings, err := json.Marshal(settings)
+			if err != nil {
+				continue
+			}
+			ib.Settings = string(newSettings)
+			if err := tx.Save(&ib).Error; err != nil {
+				tx.Rollback()
+				return 0, err
+			}
+		}
+	}
+
+	if err := tx.Commit().Error; err != nil {
+		return 0, err
+	}
+	return len(records), nil
+}
+
+func (s *ClientService) replaceGroupValue(oldName, newName string) (int, error) {
+	db := database.GetDB()
+	if newName == "" {
+		if err := db.Where("name = ?", oldName).Delete(&model.ClientGroup{}).Error; err != nil {
+			return 0, err
+		}
+	} else {
+		if err := db.Model(&model.ClientGroup{}).Where("name = ?", oldName).Update("name", newName).Error; err != nil {
+			return 0, err
+		}
+	}
+	var records []model.ClientRecord
+	if err := db.Where("group_name = ?", oldName).Find(&records).Error; err != nil {
+		return 0, err
+	}
+	if len(records) == 0 {
+		return 0, nil
+	}
+	affectedEmails := make([]string, 0, len(records))
+	for _, r := range records {
+		affectedEmails = append(affectedEmails, r.Email)
+	}
+
+	tx := db.Begin()
+	if err := tx.Model(&model.ClientRecord{}).
+		Where("group_name = ?", oldName).
+		UpdateColumn("group_name", newName).Error; err != nil {
+		tx.Rollback()
+		return 0, err
+	}
+
+	var inboundIDs []int
+	if err := tx.Table("client_inbounds").
+		Joins("JOIN clients ON clients.id = client_inbounds.client_id").
+		Where("clients.email IN ?", affectedEmails).
+		Distinct("client_inbounds.inbound_id").
+		Pluck("inbound_id", &inboundIDs).Error; err != nil {
+		tx.Rollback()
+		return 0, err
+	}
+
+	for _, ibID := range inboundIDs {
+		var ib model.Inbound
+		if err := tx.First(&ib, ibID).Error; err != nil {
+			tx.Rollback()
+			return 0, err
+		}
+		var settings map[string]any
+		if err := json.Unmarshal([]byte(ib.Settings), &settings); err != nil {
+			continue
+		}
+		clients, ok := settings["clients"].([]any)
+		if !ok {
+			continue
+		}
+		modified := false
+		for i := range clients {
+			cm, ok := clients[i].(map[string]any)
+			if !ok {
+				continue
+			}
+			if g, ok := cm["group"].(string); ok && g == oldName {
+				if newName == "" {
+					delete(cm, "group")
+				} else {
+					cm["group"] = newName
+				}
+				clients[i] = cm
+				modified = true
+			}
+		}
+		if modified {
+			settings["clients"] = clients
+			newSettings, err := json.Marshal(settings)
+			if err != nil {
+				continue
+			}
+			ib.Settings = string(newSettings)
+			if err := tx.Save(&ib).Error; err != nil {
+				tx.Rollback()
+				return 0, err
+			}
+		}
+	}
+
+	if err := tx.Commit().Error; err != nil {
+		return 0, err
+	}
+	return len(records), nil
+}
+
 func buildClientsSummary(all []ClientWithAttachments, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) ClientsSummary {
 	s := ClientsSummary{
 		Total:    len(all),
@@ -1096,6 +1424,7 @@ func toClientSlim(c ClientWithAttachments) ClientSlim {
 		ExpiryTime: c.ExpiryTime,
 		LimitIP:    c.LimitIP,
 		Reset:      c.Reset,
+		Group:      c.Group,
 		Comment:    c.Comment,
 		InboundIds: c.InboundIds,
 		Traffic:    c.Traffic,
@@ -1261,6 +1590,26 @@ func clientMatchesHasComment(c ClientWithAttachments, mode string) bool {
 	return true
 }
 
+func clientMatchesAnyGroup(c ClientWithAttachments, csv string) bool {
+	groups := parseCSVStrings(csv)
+	if len(groups) == 0 {
+		return true
+	}
+	current := strings.TrimSpace(c.Group)
+	for _, g := range groups {
+		if g == "" {
+			if current == "" {
+				return true
+			}
+			continue
+		}
+		if strings.EqualFold(g, current) {
+			return true
+		}
+	}
+	return false
+}
+
 func clientMatchesBucket(c ClientWithAttachments, bucket string, onlineSet map[string]struct{}, nowMs, expireDiffMs, trafficDiffBytes int64) bool {
 	if bucket == "" {
 		return true

web/translation/en-US.json

@@ -102,6 +102,7 @@
     "dashboard": "Overview",
     "inbounds": "Inbounds",
     "clients": "Clients",
+    "groups": "Groups",
     "nodes": "Nodes",
     "settings": "Panel Settings",
     "xray": "Xray Configs",
@@ -482,6 +483,9 @@
       "subId": "Subscription ID",
       "online": "Online",
       "email": "Email",
+      "group": "Group",
+      "groupDesc": "Logical label used to bucket related clients (e.g. team, customer, region). Filterable from the toolbar.",
+      "groupPlaceholder": "e.g. customer-a",
       "comment": "Comment",
       "traffic": "Traffic",
       "offline": "Offline",
@@ -509,6 +513,21 @@
       "deleteConfirmContent": "This removes the client from every attached inbound and drops its traffic record. This cannot be undone.",
       "deleteSelected": "Delete ({count})",
       "adjustSelected": "Adjust ({count})",
+      "subLinksSelected": "Sub links ({count})",
+      "assignGroupSelected": "Group ({count})",
+      "assignGroupTitle": "Assign group to {count} client(s)",
+      "assignGroupTooltip": "Pick an existing group or type a new name. Leave blank to clear the group on the selected clients.",
+      "assignGroupPlaceholder": "Group name (leave blank to clear)",
+      "assignGroupAssignedToast": "Assigned {count} client(s) to {group}",
+      "assignGroupClearedToast": "Cleared group from {count} client(s)",
+      "subLinksTitle": "Sub links ({count})",
+      "subLinkColumn": "Subscription URL",
+      "subJsonLinkColumn": "Subscription JSON URL",
+      "subLinksCopyAll": "Copy all",
+      "subLinksCopiedAll": "Copied {count} link(s)",
+      "subLinksEmpty": "None of the selected clients have a subscription ID.",
+      "subLinksDisabled": "Subscription service is disabled.",
+      "subLinksDisabledHint": "Enable subscription in Panel Settings → Subscription to generate links.",
       "bulkDeleteConfirmTitle": "Delete {count} clients?",
       "bulkDeleteConfirmContent": "Each selected client is removed from every attached inbound and its traffic record is dropped. This cannot be undone.",
       "bulkAdjustTitle": "Adjust {count} clients",
@@ -543,6 +562,35 @@
         "delDepleted": "{count} depleted clients deleted"
       }
     },
+    "groups": {
+      "title": "Groups",
+      "name": "Name",
+      "clientCount": "Clients in group",
+      "totalGroups": "Total groups",
+      "totalGroupedClients": "Clients with a group",
+      "emptyGroups": "Empty groups",
+      "addGroup": "Add Group",
+      "createSuccess": "Group \"{name}\" created.",
+      "rename": "Rename",
+      "renameTitle": "Rename {name}",
+      "renameCollision": "A group named \"{name}\" already exists.",
+      "renameSuccess": "Renamed group on {count} client(s).",
+      "deleteConfirmTitle": "Delete group {name}?",
+      "deleteConfirmContent": "This removes the group and clears its label from {count} client(s). The clients themselves are not deleted.",
+      "deleteSuccess": "Cleared group from {count} client(s).",
+      "resetTraffic": "Reset traffic",
+      "resetConfirmTitle": "Reset traffic for group {name}?",
+      "resetConfirmContent": "This zeros up/down for all {count} client(s) in this group.",
+      "resetSuccess": "Reset traffic for {count} client(s).",
+      "adjustSuccess": "Adjusted {count} client(s) in {name}.",
+      "emptyForAction": "This group has no clients yet.",
+      "deleteGroupOnly": "Delete group (keep clients)",
+      "deleteClients": "Delete clients in group",
+      "deleteClientsConfirmTitle": "Delete all clients in {name}?",
+      "deleteClientsConfirmContent": "This permanently removes {count} client(s) along with their traffic records. The group label is cleared too. This cannot be undone.",
+      "deleteClientsSuccess": "Deleted {count} client(s).",
+      "deleteClientsMixed": "{ok} deleted, {failed} skipped"
+    },
     "nodes": {
       "title": "Nodes",
       "addNode": "Add Node",