From 6ba5667895e42b09c86781b69f02b1f2440a8d07 Mon Sep 17 00:00:00 2001
From: CIOI <rhkr9693@gmail.com>
Date: Mon, 18 May 2026 21:24:50 +0900
Subject: [PATCH] feat(admin): improve group member management UI

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/agent/web-routes-and-features.md         |   2 +-
 .../group-members/__tests__/page.test.tsx     |  69 +-
 .../app/admin/entities/group-members/page.tsx | 672 ++++++++++++++++--
 .../api/admin/entities/group-members/route.ts | 350 ++++++++-
 packages/web/lib/api/admin/entities.ts        | 125 +++-
 5 files changed, 1137 insertions(+), 81 deletions(-)

diff --git a/docs/agent/web-routes-and-features.md b/docs/agent/web-routes-and-features.md
index 7d091a03..f7a59539 100644
--- a/docs/agent/web-routes-and-features.md
+++ b/docs/agent/web-routes-and-features.md
@@ -40,7 +40,7 @@ App Router 기준 (`packages/web/app/`). 작업 시 이 표와 실제 `app/` 트
 | `/admin/seed/post-spots`        | 시드 포스트 스팟                                                                                                            |
 | `/admin/entities/artists`       | 아티스트 관리 (CRUD, paginated, searchable)                                                                                 |
 | `/admin/entities/brands`        | 브랜드 관리 (CRUD)                                                                                                          |
-| `/admin/entities/group-members` | 그룹 멤버 관리                                                                                                              |
+| `/admin/entities/group-members` | 그룹 멤버 관리 — group별 artist membership 조회·추가·수정·삭제                                                             |
 | `/admin/raw-post-sources`       | 수집 소스 등록/관리 (Pinterest 등 — #327)                                                                                   |
 | `/admin/raw-posts`              | **검증 큐** (#333) — assets 의 raw_posts 를 status 탭(COMPLETED/IN_PROGRESS/ERROR/VERIFIED) 으로 필터링, "검증" 버튼으로 prod posts 반영 |
 | `/admin/data-pipeline/instagram-accounts` | Instagram tagged account enrichment queue, Gemini grounding quota, scheduler controls, manual entity review. See [`docs/database/entity-enrichment-pipeline.md`](../database/entity-enrichment-pipeline.md). |
diff --git a/packages/web/app/admin/entities/group-members/__tests__/page.test.tsx b/packages/web/app/admin/entities/group-members/__tests__/page.test.tsx
index 3e9a9e67..1205e540 100644
--- a/packages/web/app/admin/entities/group-members/__tests__/page.test.tsx
+++ b/packages/web/app/admin/entities/group-members/__tests__/page.test.tsx
@@ -1,10 +1,7 @@
 /**
  * @vitest-environment jsdom
  *
- * GroupMembersPage empty / loading / error state tests.
- *
- * Group members has no search/status filter, so isEmpty is simply:
- * not loading AND not error AND no rows.
+ * GroupMembersPage group list / member table state tests.
  */
 import React from "react";
 import { describe, test, expect, vi, beforeEach } from "vitest";
@@ -19,44 +16,87 @@ vi.mock("next/navigation", () => ({
 
 // --- Mock the data hooks ---
 const useGroupMemberListMock = vi.fn();
+const mutateMock = vi.fn();
 
 vi.mock("@/lib/api/admin/entities", () => ({
   useGroupMemberList: (...args: unknown[]) => useGroupMemberListMock(...args),
+  useGroupMemberArtistSearch: () => ({ data: { data: [] }, isLoading: false }),
+  useCreateGroupMember: () => ({ mutate: mutateMock, isPending: false }),
+  useUpdateGroupMember: () => ({ mutate: mutateMock, isPending: false }),
+  useDeleteGroupMember: () => ({ mutate: mutateMock, isPending: false }),
 }));
 
 import GroupMembersPage from "../page";
 
 beforeEach(() => {
   useGroupMemberListMock.mockReset();
+  mutateMock.mockReset();
 });
 
 describe("GroupMembersPage — empty state", () => {
   test("renders AdminEmptyState when no data", () => {
     useGroupMemberListMock.mockReturnValue({
-      data: { data: [], pagination: undefined },
+      data: {
+        data: [],
+        groups: [],
+        selected_group: null,
+        pagination: undefined,
+      },
       isLoading: false,
       isError: false,
     });
 
     render(<GroupMembersPage />);
 
-    expect(screen.getByText("No group members")).toBeInTheDocument();
+    expect(screen.getByText("No groups")).toBeInTheDocument();
     expect(
       screen.getByText(
-        "Artist–group relationships will appear here once they are seeded."
+        "Groups created by entity enrichment or manual admin actions will appear here."
       )
     ).toBeInTheDocument();
   });
 
-  test("renders table when data has rows", () => {
+  test("renders selected group and member rows", () => {
     useGroupMemberListMock.mockReturnValue({
       data: {
+        groups: [
+          {
+            id: "group-uuid-5678",
+            name_en: "BLACKPINK",
+            name_ko: "블랙핑크",
+            profile_image_url: null,
+            primary_instagram_account_id: null,
+            primary_instagram_account: null,
+            member_count: 1,
+            total_member_count: 1,
+            metadata: null,
+          },
+        ],
+        selected_group: {
+          id: "group-uuid-5678",
+          name_en: "BLACKPINK",
+          name_ko: "블랙핑크",
+          profile_image_url: null,
+          primary_instagram_account_id: null,
+          primary_instagram_account: null,
+          member_count: 1,
+          total_member_count: 1,
+          metadata: null,
+        },
         data: [
           {
             artist_id: "artist-uuid-1234",
             group_id: "group-uuid-5678",
             is_active: true,
             metadata: null,
+            artist: {
+              id: "artist-uuid-1234",
+              name_en: "Jennie",
+              name_ko: "제니",
+              profile_image_url: null,
+              primary_instagram_account_id: null,
+              primary_instagram_account: { username: "jennierubyjane" },
+            },
           },
         ],
         pagination: {
@@ -72,9 +112,10 @@ describe("GroupMembersPage — empty state", () => {
 
     render(<GroupMembersPage />);
 
-    expect(screen.queryByText("No group members")).not.toBeInTheDocument();
-    // row data is rendered (truncated artist_id prefix)
-    expect(screen.getByText("artist-u…")).toBeInTheDocument();
+    expect(screen.queryByText("No groups")).not.toBeInTheDocument();
+    expect(screen.getAllByText("BLACKPINK").length).toBeGreaterThan(0);
+    expect(screen.getByText("Jennie")).toBeInTheDocument();
+    expect(screen.getByText("@jennierubyjane")).toBeInTheDocument();
   });
 
   test("renders error state when fetch fails", () => {
@@ -87,10 +128,8 @@ describe("GroupMembersPage — empty state", () => {
     render(<GroupMembersPage />);
 
     expect(
-      screen.getByText(
-        "Failed to load group members. Please try refreshing the page."
-      )
+      screen.getByText("Failed to load groups. Please try refreshing the page.")
     ).toBeInTheDocument();
-    expect(screen.queryByText("No group members")).not.toBeInTheDocument();
+    expect(screen.queryByText("No groups")).not.toBeInTheDocument();
   });
 });
diff --git a/packages/web/app/admin/entities/group-members/page.tsx b/packages/web/app/admin/entities/group-members/page.tsx
index 41e4a67b..493dbe26 100644
--- a/packages/web/app/admin/entities/group-members/page.tsx
+++ b/packages/web/app/admin/entities/group-members/page.tsx
@@ -1,16 +1,351 @@
 "use client";
 
-import { useCallback, Suspense } from "react";
+import { useCallback, useEffect, useRef, useState, Suspense } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
-import { Users } from "lucide-react";
+import {
+  Check,
+  Pencil,
+  Plus,
+  Search,
+  Trash2,
+  UserPlus,
+  Users,
+  X,
+} from "lucide-react";
 import {
   AdminDataTable,
   type Column,
+  AdminImagePreview,
   AdminStatusBadge,
   AdminPagination,
   AdminEmptyState,
 } from "@/lib/components/admin/common";
-import { useGroupMemberList, type GroupMember } from "@/lib/api/admin/entities";
+import {
+  useCreateGroupMember,
+  useDeleteGroupMember,
+  useGroupMemberArtistSearch,
+  useGroupMemberList,
+  useUpdateGroupMember,
+  type GroupMember,
+  type GroupMemberArtist,
+  type GroupSummary,
+} from "@/lib/api/admin/entities";
+
+function displayName(entity: {
+  name_en: string | null;
+  name_ko: string | null;
+}) {
+  return entity.name_en || entity.name_ko || "Untitled";
+}
+
+function secondaryName(entity: {
+  name_en: string | null;
+  name_ko: string | null;
+}) {
+  return entity.name_en && entity.name_ko ? entity.name_ko : null;
+}
+
+function metadataToText(metadata: Record<string, unknown> | null | undefined) {
+  if (!metadata || Object.keys(metadata).length === 0) return "";
+  return JSON.stringify(metadata, null, 2);
+}
+
+function parseMetadata(text: string) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  const parsed = JSON.parse(trimmed);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Metadata must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+interface AddMemberPanelProps {
+  group: GroupSummary | null;
+  onCancel: () => void;
+}
+
+function AddMemberPanel({ group, onCancel }: AddMemberPanelProps) {
+  const [artistSearch, setArtistSearch] = useState("");
+  const [selectedArtist, setSelectedArtist] =
+    useState<GroupMemberArtist | null>(null);
+  const [isActive, setIsActive] = useState(true);
+  const [metadataText, setMetadataText] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const createMember = useCreateGroupMember();
+  const artistOptions = useGroupMemberArtistSearch(
+    artistSearch,
+    group?.id ?? ""
+  );
+
+  const handleSubmit = () => {
+    if (!group || !selectedArtist) return;
+    try {
+      createMember.mutate(
+        {
+          group_id: group.id,
+          artist_id: selectedArtist.id,
+          is_active: isActive,
+          metadata: parseMetadata(metadataText),
+        },
+        {
+          onSuccess: () => {
+            setArtistSearch("");
+            setSelectedArtist(null);
+            setMetadataText("");
+            setIsActive(true);
+            setError(null);
+            onCancel();
+          },
+          onError: (err) =>
+            setError(
+              err instanceof Error ? err.message : "Failed to add member"
+            ),
+        }
+      );
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Invalid metadata JSON");
+    }
+  };
+
+  return (
+    <div className="rounded-xl border border-primary/40 bg-card/60 p-4 space-y-4">
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          <h2 className="text-sm font-semibold text-gray-100">
+            Add artist to {group ? displayName(group) : "group"}
+          </h2>
+          <p className="text-xs text-muted-foreground mt-1">
+            Search by artist name or Instagram username.
+          </p>
+        </div>
+        <button
+          onClick={onCancel}
+          className="rounded-lg p-1.5 text-muted-foreground hover:bg-gray-700 hover:text-gray-100"
+          aria-label="Cancel add member"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+
+      <div>
+        <label className="block text-xs text-muted-foreground mb-1">
+          Artist search
+        </label>
+        <div className="relative">
+          <Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <input
+            value={artistSearch}
+            onChange={(event) => {
+              setArtistSearch(event.target.value);
+              setSelectedArtist(null);
+            }}
+            className="w-full rounded-lg bg-gray-700 border border-border pl-9 pr-3 py-2 text-sm text-gray-100 focus:outline-none focus:border-primary"
+            placeholder="Search artists or @username"
+          />
+        </div>
+      </div>
+
+      {artistSearch && !selectedArtist && (
+        <div className="max-h-56 overflow-y-auto rounded-lg border border-border bg-gray-900/40">
+          {artistOptions.isLoading ? (
+            <p className="px-3 py-3 text-xs text-muted-foreground">
+              Searching…
+            </p>
+          ) : artistOptions.data?.data.length ? (
+            artistOptions.data.data.map((artist) => (
+              <button
+                key={artist.id}
+                onClick={() => setSelectedArtist(artist)}
+                className="flex w-full items-center gap-3 px-3 py-2 text-left hover:bg-gray-800"
+              >
+                {artist.profile_image_url ? (
+                  <AdminImagePreview
+                    src={artist.profile_image_url}
+                    alt={displayName(artist)}
+                    size="sm"
+                  />
+                ) : (
+                  <div className="h-10 w-10 rounded-lg bg-gray-700" />
+                )}
+                <span>
+                  <span className="block text-sm text-gray-100">
+                    {displayName(artist)}
+                  </span>
+                  <span className="block text-xs text-muted-foreground">
+                    {artist.primary_instagram_account?.username
+                      ? `@${artist.primary_instagram_account.username}`
+                      : artist.id.slice(0, 8)}
+                  </span>
+                </span>
+              </button>
+            ))
+          ) : (
+            <p className="px-3 py-3 text-xs text-muted-foreground">
+              No matching artists found.
+            </p>
+          )}
+        </div>
+      )}
+
+      {selectedArtist && (
+        <div className="rounded-lg border border-border bg-gray-800/50 p-3">
+          <p className="text-sm font-medium text-gray-100">
+            {displayName(selectedArtist)}
+          </p>
+          <p className="text-xs text-muted-foreground">
+            {selectedArtist.primary_instagram_account?.username
+              ? `@${selectedArtist.primary_instagram_account.username}`
+              : selectedArtist.id}
+          </p>
+        </div>
+      )}
+
+      <label className="flex items-center gap-2 text-sm text-gray-200">
+        <input
+          type="checkbox"
+          checked={isActive}
+          onChange={(event) => setIsActive(event.target.checked)}
+          className="rounded border-input"
+        />
+        Active membership
+      </label>
+
+      <div>
+        <label className="block text-xs text-muted-foreground mb-1">
+          Metadata JSON
+        </label>
+        <textarea
+          value={metadataText}
+          onChange={(event) => setMetadataText(event.target.value)}
+          className="min-h-24 w-full rounded-lg bg-gray-700 border border-border px-3 py-2 font-mono text-xs text-gray-100 focus:outline-none focus:border-primary"
+          placeholder='{"source":"manual"}'
+        />
+      </div>
+
+      {error && <p className="text-xs text-red-400">{error}</p>}
+
+      <div className="flex justify-end gap-2">
+        <button
+          onClick={onCancel}
+          className="rounded-lg px-3 py-1.5 text-sm text-muted-foreground hover:bg-gray-700 hover:text-gray-100"
+        >
+          Cancel
+        </button>
+        <button
+          onClick={handleSubmit}
+          disabled={!selectedArtist || createMember.isPending}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-primary px-4 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+        >
+          <Check className="h-4 w-4" />
+          {createMember.isPending ? "Adding…" : "Add member"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+interface EditMemberPanelProps {
+  member: GroupMember;
+  onCancel: () => void;
+}
+
+function EditMemberPanel({ member, onCancel }: EditMemberPanelProps) {
+  const [isActive, setIsActive] = useState(member.is_active);
+  const [metadataText, setMetadataText] = useState(
+    metadataToText(member.metadata)
+  );
+  const [error, setError] = useState<string | null>(null);
+  const updateMember = useUpdateGroupMember();
+
+  const handleSubmit = () => {
+    try {
+      updateMember.mutate(
+        {
+          group_id: member.group_id,
+          artist_id: member.artist_id,
+          is_active: isActive,
+          metadata: parseMetadata(metadataText),
+        },
+        {
+          onSuccess: () => {
+            setError(null);
+            onCancel();
+          },
+          onError: (err) =>
+            setError(
+              err instanceof Error ? err.message : "Failed to update member"
+            ),
+        }
+      );
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Invalid metadata JSON");
+    }
+  };
+
+  return (
+    <div className="rounded-xl border border-primary/40 bg-card/60 p-4 space-y-4">
+      <div className="flex items-start justify-between gap-3">
+        <div>
+          <h2 className="text-sm font-semibold text-gray-100">
+            Edit {member.artist ? displayName(member.artist) : member.artist_id}
+          </h2>
+          <p className="text-xs text-muted-foreground mt-1">
+            Update membership status and metadata.
+          </p>
+        </div>
+        <button
+          onClick={onCancel}
+          className="rounded-lg p-1.5 text-muted-foreground hover:bg-gray-700 hover:text-gray-100"
+          aria-label="Cancel edit member"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+
+      <label className="flex items-center gap-2 text-sm text-gray-200">
+        <input
+          type="checkbox"
+          checked={isActive}
+          onChange={(event) => setIsActive(event.target.checked)}
+          className="rounded border-input"
+        />
+        Active membership
+      </label>
+
+      <div>
+        <label className="block text-xs text-muted-foreground mb-1">
+          Metadata JSON
+        </label>
+        <textarea
+          value={metadataText}
+          onChange={(event) => setMetadataText(event.target.value)}
+          className="min-h-24 w-full rounded-lg bg-gray-700 border border-border px-3 py-2 font-mono text-xs text-gray-100 focus:outline-none focus:border-primary"
+          placeholder='{"source":"manual"}'
+        />
+      </div>
+
+      {error && <p className="text-xs text-red-400">{error}</p>}
+
+      <div className="flex justify-end gap-2">
+        <button
+          onClick={onCancel}
+          className="rounded-lg px-3 py-1.5 text-sm text-muted-foreground hover:bg-gray-700 hover:text-gray-100"
+        >
+          Cancel
+        </button>
+        <button
+          onClick={handleSubmit}
+          disabled={updateMember.isPending}
+          className="inline-flex items-center gap-1.5 rounded-lg bg-primary px-4 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+        >
+          <Check className="h-4 w-4" />
+          {updateMember.isPending ? "Saving…" : "Save"}
+        </button>
+      </div>
+    </div>
+  );
+}
 
 // ─── Inner page ───────────────────────────────────────────────────────────────
 
@@ -19,6 +354,13 @@ function GroupMembersPageContent() {
   const router = useRouter();
 
   const currentPage = Number(searchParams.get("page") ?? 1);
+  const searchQuery = searchParams.get("search") ?? "";
+  const selectedGroupId = searchParams.get("group_id") ?? "";
+
+  const [inputValue, setInputValue] = useState(searchQuery);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [showAdd, setShowAdd] = useState(false);
+  const [editingMember, setEditingMember] = useState<GroupMember | null>(null);
 
   const updateUrl = useCallback(
     (params: Record<string, string | undefined>) => {
@@ -32,30 +374,86 @@ function GroupMembersPageContent() {
     [searchParams, router]
   );
 
-  const { data, isLoading, isError } = useGroupMemberList(currentPage, 20);
+  const handleSearchChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const value = event.target.value;
+    setInputValue(value);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => {
+      updateUrl({ search: value || undefined, page: "1", group_id: undefined });
+    }, 300);
+  };
+
+  useEffect(() => {
+    setInputValue(searchQuery);
+  }, [searchQuery]);
+
+  const { data, isLoading, isError } = useGroupMemberList(
+    currentPage,
+    20,
+    searchQuery,
+    selectedGroupId
+  );
+  const deleteMember = useDeleteGroupMember();
+
+  const groups = data?.groups ?? [];
+  const selectedGroup = data?.selected_group ?? null;
+  const members = data?.data ?? [];
+  const pagination = data?.pagination;
+  const isEmpty = !isLoading && !isError && groups.length === 0;
+
+  const handleSelectGroup = (group: GroupSummary) => {
+    setShowAdd(false);
+    setEditingMember(null);
+    updateUrl({ group_id: group.id });
+  };
+
+  const handleDelete = (member: GroupMember) => {
+    const artistName = member.artist
+      ? displayName(member.artist)
+      : member.artist_id;
+    if (!window.confirm(`Remove "${artistName}" from this group?`)) return;
+    deleteMember.mutate({
+      group_id: member.group_id,
+      artist_id: member.artist_id,
+    });
+  };
 
   const columns: Column<GroupMember>[] = [
     {
-      key: "artist_id",
-      label: "Artist ID",
+      key: "artist",
+      label: "Artist",
       render: (row) => (
-        <span
-          className="font-mono text-xs text-muted-foreground"
-          title={row.artist_id}
-        >
-          {row.artist_id.slice(0, 8)}…
-        </span>
+        <div className="flex items-center gap-3">
+          {row.artist?.profile_image_url ? (
+            <AdminImagePreview
+              src={row.artist.profile_image_url}
+              alt={displayName(row.artist)}
+              size="sm"
+            />
+          ) : (
+            <div className="h-10 w-10 rounded-lg bg-gray-700 flex items-center justify-center text-xs text-muted-foreground">
+              N/A
+            </div>
+          )}
+          <div>
+            <p className="font-medium text-gray-100">
+              {row.artist ? displayName(row.artist) : "Unknown artist"}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              {row.artist?.primary_instagram_account?.username
+                ? `@${row.artist.primary_instagram_account.username}`
+                : row.artist_id.slice(0, 8)}
+            </p>
+          </div>
+        </div>
       ),
     },
     {
-      key: "group_id",
-      label: "Group ID",
+      key: "name_ko",
+      label: "Name (KO)",
       render: (row) => (
-        <span
-          className="font-mono text-xs text-muted-foreground"
-          title={row.group_id}
-        >
-          {row.group_id.slice(0, 8)}…
+        <span className="text-sm text-gray-200">
+          {row.artist?.name_ko || "—"}
         </span>
       ),
     },
@@ -79,65 +477,229 @@ function GroupMembersPageContent() {
           <span className="text-muted-foreground text-xs">—</span>
         ),
     },
+    {
+      key: "actions",
+      label: "Actions",
+      className: "text-right",
+      render: (row) => (
+        <div className="flex items-center justify-end gap-2">
+          <button
+            onClick={() => {
+              setShowAdd(false);
+              setEditingMember(row);
+            }}
+            className="rounded-lg p-1.5 text-muted-foreground hover:bg-gray-700 hover:text-gray-100"
+            aria-label="Edit group member"
+          >
+            <Pencil className="h-4 w-4" />
+          </button>
+          <button
+            onClick={() => handleDelete(row)}
+            disabled={deleteMember.isPending}
+            className="rounded-lg p-1.5 text-muted-foreground hover:bg-red-900/30 hover:text-red-300 disabled:opacity-50"
+            aria-label="Delete group member"
+          >
+            <Trash2 className="h-4 w-4" />
+          </button>
+        </div>
+      ),
+    },
   ];
 
-  const members = data?.data ?? [];
-  const pagination = data?.pagination;
-  const isEmpty = !isLoading && !isError && members.length === 0;
-
   return (
     <div className="space-y-6">
-      {/* Header */}
-      <div>
-        <h1 className="text-2xl font-semibold text-gray-100">Group Members</h1>
-        <p className="text-sm text-muted-foreground mt-1">
-          Read-only view of artist–group relationships
-          {pagination && (
-            <span className="ml-2 text-muted-foreground">
-              ({pagination.total_items} total)
-            </span>
-          )}
-        </p>
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-end lg:justify-between">
+        <div>
+          <h1 className="text-2xl font-semibold text-gray-100">Groups</h1>
+          <p className="text-sm text-muted-foreground mt-1">
+            Manage artist membership for each group.
+            {pagination && (
+              <span className="ml-2 text-muted-foreground">
+                ({pagination.total_items} groups)
+              </span>
+            )}
+          </p>
+        </div>
+        <div className="relative w-full lg:w-80">
+          <Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <input
+            value={inputValue}
+            onChange={handleSearchChange}
+            className="w-full rounded-lg bg-gray-700 border border-border pl-9 pr-3 py-2 text-sm text-gray-100 focus:outline-none focus:border-primary"
+            placeholder="Search groups"
+          />
+        </div>
       </div>
 
-      {/* Error state */}
       {isError && (
         <div className="rounded-xl border border-red-800/40 bg-red-900/10 py-12 text-center">
           <p className="text-sm text-red-400">
-            Failed to load group members. Please try refreshing the page.
+            Failed to load groups. Please try refreshing the page.
           </p>
         </div>
       )}
 
-      {/* Empty state */}
       {isEmpty && (
         <div className="border border-border dark:border-border rounded-lg">
           <AdminEmptyState
             icon={<Users className="w-12 h-12" />}
-            title="No group members"
-            description="Artist–group relationships will appear here once they are seeded."
+            title="No groups"
+            description="Groups created by entity enrichment or manual admin actions will appear here."
           />
         </div>
       )}
 
-      {/* Table */}
       {!isError && !isEmpty && (
-        <AdminDataTable
-          columns={columns}
-          data={members}
-          rowKey={(row) => `${row.artist_id}:${row.group_id}`}
-          isLoading={isLoading}
-          emptyMessage="No group members found"
-        />
-      )}
+        <div className="grid gap-6 lg:grid-cols-[320px_minmax(0,1fr)]">
+          <aside className="space-y-3">
+            <div className="rounded-xl border border-border bg-card">
+              <div className="border-b border-border px-4 py-3">
+                <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                  Group list
+                </p>
+              </div>
+              <div className="max-h-[640px] overflow-y-auto p-2">
+                {isLoading ? (
+                  <p className="px-3 py-4 text-sm text-muted-foreground">
+                    Loading groups…
+                  </p>
+                ) : (
+                  groups.map((group) => {
+                    const active = selectedGroup?.id === group.id;
+                    return (
+                      <button
+                        key={group.id}
+                        onClick={() => handleSelectGroup(group)}
+                        className={`w-full rounded-lg px-3 py-3 text-left transition-colors ${
+                          active
+                            ? "bg-primary/15 text-gray-100"
+                            : "text-gray-200 hover:bg-gray-800"
+                        }`}
+                      >
+                        <div className="flex items-center gap-3">
+                          {group.profile_image_url ? (
+                            <AdminImagePreview
+                              src={group.profile_image_url}
+                              alt={displayName(group)}
+                              size="sm"
+                            />
+                          ) : (
+                            <div className="h-10 w-10 rounded-lg bg-gray-700 flex items-center justify-center text-xs text-muted-foreground">
+                              G
+                            </div>
+                          )}
+                          <div className="min-w-0 flex-1">
+                            <p className="truncate text-sm font-medium">
+                              {displayName(group)}
+                            </p>
+                            {secondaryName(group) && (
+                              <p className="truncate text-xs text-gray-300">
+                                {secondaryName(group)}
+                              </p>
+                            )}
+                            <p className="truncate text-xs text-muted-foreground">
+                              {group.primary_instagram_account?.username
+                                ? `@${group.primary_instagram_account.username}`
+                                : group.id.slice(0, 8)}
+                            </p>
+                          </div>
+                          <span className="rounded-full bg-gray-800 px-2 py-0.5 text-xs text-muted-foreground">
+                            {group.member_count}
+                          </span>
+                        </div>
+                      </button>
+                    );
+                  })
+                )}
+              </div>
+            </div>
 
-      {/* Pagination */}
-      {pagination && (
-        <AdminPagination
-          currentPage={pagination.current_page}
-          totalPages={pagination.total_pages}
-          onPageChange={(page) => updateUrl({ page: String(page) })}
-        />
+            {pagination && (
+              <AdminPagination
+                currentPage={pagination.current_page}
+                totalPages={pagination.total_pages}
+                onPageChange={(page) =>
+                  updateUrl({ page: String(page), group_id: undefined })
+                }
+              />
+            )}
+          </aside>
+
+          <section className="space-y-4">
+            <div className="rounded-xl border border-border bg-card p-4">
+              <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                <div>
+                  <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                    Selected group
+                  </p>
+                  <h2 className="mt-1 text-xl font-semibold text-gray-100">
+                    {selectedGroup
+                      ? displayName(selectedGroup)
+                      : "No group selected"}
+                  </h2>
+                  {selectedGroup && (
+                    <div className="mt-1 space-y-1">
+                      {secondaryName(selectedGroup) && (
+                        <p className="text-sm text-gray-300">
+                          {secondaryName(selectedGroup)}
+                        </p>
+                      )}
+                      <p className="text-sm text-muted-foreground">
+                        {selectedGroup.member_count} active members
+                        {selectedGroup.total_member_count !==
+                          selectedGroup.member_count &&
+                          ` / ${selectedGroup.total_member_count} total`}
+                      </p>
+                    </div>
+                  )}
+                </div>
+                <button
+                  onClick={() => {
+                    setEditingMember(null);
+                    setShowAdd((prev) => !prev);
+                  }}
+                  disabled={!selectedGroup}
+                  className="inline-flex items-center justify-center gap-1.5 rounded-lg bg-primary px-4 py-2 text-sm font-medium text-white disabled:opacity-50"
+                >
+                  <Plus className="h-4 w-4" />
+                  Add member
+                </button>
+              </div>
+            </div>
+
+            {showAdd && (
+              <AddMemberPanel
+                group={selectedGroup}
+                onCancel={() => setShowAdd(false)}
+              />
+            )}
+
+            {editingMember && (
+              <EditMemberPanel
+                member={editingMember}
+                onCancel={() => setEditingMember(null)}
+              />
+            )}
+
+            {selectedGroup && members.length === 0 && !isLoading ? (
+              <div className="border border-border dark:border-border rounded-lg">
+                <AdminEmptyState
+                  icon={<UserPlus className="w-12 h-12" />}
+                  title="No artists in this group"
+                  description="Search for an artist and add the first membership."
+                />
+              </div>
+            ) : (
+              <AdminDataTable
+                columns={columns}
+                data={members}
+                rowKey={(row) => `${row.group_id}:${row.artist_id}`}
+                isLoading={isLoading}
+                emptyMessage="No group members found"
+              />
+            )}
+          </section>
+        </div>
       )}
     </div>
   );
diff --git a/packages/web/app/api/admin/entities/group-members/route.ts b/packages/web/app/api/admin/entities/group-members/route.ts
index 58a786e2..e77ab0c4 100644
--- a/packages/web/app/api/admin/entities/group-members/route.ts
+++ b/packages/web/app/api/admin/entities/group-members/route.ts
@@ -2,31 +2,231 @@
 import { NextRequest, NextResponse } from "next/server";
 import { createSupabaseServerClient } from "@/lib/supabase/server";
 import { checkIsAdmin } from "@/lib/supabase/admin";
+import { writeAuditLog } from "@/lib/api/admin/audit-log";
 
-export async function GET(req: NextRequest) {
-  const supabase = await createSupabaseServerClient();
+type SupabaseClient = Awaited<ReturnType<typeof createSupabaseServerClient>>;
+
+async function requireAdmin(supabase: SupabaseClient) {
   const {
     data: { user },
   } = await supabase.auth.getUser();
-  if (!user || !(await checkIsAdmin(supabase, user.id))) {
+  if (!user || !(await checkIsAdmin(supabase, user.id))) return null;
+  return user;
+}
+
+function compactIds(ids: Array<string | null | undefined>) {
+  return [...new Set(ids.filter((id): id is string => Boolean(id)))];
+}
+
+async function fetchInstagramAccounts(supabase: SupabaseClient, ids: string[]) {
+  if (ids.length === 0) return new Map<string, any>();
+  const { data } = await (supabase as any)
+    .from("instagram_accounts")
+    .select("id, username, display_name, profile_image_url")
+    .in("id", ids);
+  return new Map((data ?? []).map((account: any) => [account.id, account]));
+}
+
+async function attachInstagramAccounts(
+  supabase: SupabaseClient,
+  artists: any[]
+) {
+  const accountMap = await fetchInstagramAccounts(
+    supabase,
+    compactIds(artists.map((artist) => artist.primary_instagram_account_id))
+  );
+  return artists.map((artist) => ({
+    ...artist,
+    primary_instagram_account:
+      accountMap.get(artist.primary_instagram_account_id) ?? null,
+  }));
+}
+
+async function listArtistOptions(req: NextRequest, supabase: SupabaseClient) {
+  const { searchParams } = req.nextUrl;
+  const search = searchParams.get("search")?.trim() ?? "";
+  const groupId = searchParams.get("group_id") ?? "";
+  const limit = Math.min(Number(searchParams.get("limit") ?? 12), 30);
+
+  let matchingAccountIds: string[] = [];
+  if (search) {
+    const { data: accounts } = await (supabase as any)
+      .from("instagram_accounts")
+      .select("id")
+      .ilike("username", `%${search}%`)
+      .limit(limit);
+    matchingAccountIds = (accounts ?? []).map((account: any) => account.id);
+  }
+
+  let query = (supabase as any)
+    .from("artists")
+    .select(
+      "id, name_en, name_ko, profile_image_url, primary_instagram_account_id"
+    )
+    .order("name_en", { ascending: true })
+    .limit(limit);
+
+  if (search) {
+    const clauses = [`name_en.ilike.%${search}%`, `name_ko.ilike.%${search}%`];
+    if (matchingAccountIds.length > 0) {
+      clauses.push(
+        `primary_instagram_account_id.in.(${matchingAccountIds.join(",")})`
+      );
+    }
+    query = query.or(clauses.join(","));
+  }
+
+  const { data, error } = await query;
+  if (error)
+    return NextResponse.json({ error: error.message }, { status: 500 });
+
+  let existingArtistIds = new Set<string>();
+  if (groupId) {
+    const { data: existing } = await (supabase as any)
+      .from("group_members")
+      .select("artist_id")
+      .eq("group_id", groupId);
+    existingArtistIds = new Set(
+      (existing ?? []).map((row: any) => row.artist_id)
+    );
+  }
+
+  const artists = await attachInstagramAccounts(
+    supabase,
+    (data ?? []).filter((artist: any) => !existingArtistIds.has(artist.id))
+  );
+  return NextResponse.json({ data: artists });
+}
+
+export async function GET(req: NextRequest) {
+  const supabase = await createSupabaseServerClient();
+  const user = await requireAdmin(supabase);
+  if (!user) {
     return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
   }
 
+  if (req.nextUrl.searchParams.get("mode") === "artist-search") {
+    return listArtistOptions(req, supabase);
+  }
+
   const { searchParams } = req.nextUrl;
   const page = Number(searchParams.get("page") ?? 1);
   const perPage = Number(searchParams.get("per_page") ?? 20);
+  const search = searchParams.get("search")?.trim() ?? "";
+  const requestedGroupId = searchParams.get("group_id") ?? "";
 
-  const { data, count, error } = await (supabase as any)
-    .from("group_members")
+  let groupsQuery = (supabase as any)
+    .from("groups")
     .select("*", { count: "exact" })
-    .order("artist_id", { ascending: true })
+    .order("name_en", { ascending: true, nullsFirst: false })
     .range((page - 1) * perPage, page * perPage - 1);
 
+  if (search) {
+    groupsQuery = groupsQuery.or(
+      `name_en.ilike.%${search}%,name_ko.ilike.%${search}%`
+    );
+  }
+
+  const { data: groupRows, count, error } = await groupsQuery;
   if (error)
     return NextResponse.json({ error: error.message }, { status: 500 });
 
+  const groupIds = (groupRows ?? []).map((group: any) => group.id);
+  const selectedGroupId = requestedGroupId || groupIds[0] || "";
+
+  const [{ data: countRows }, groupAccountMap] = await Promise.all([
+    groupIds.length
+      ? (supabase as any)
+          .from("group_members")
+          .select("group_id, is_active")
+          .in("group_id", groupIds)
+      : Promise.resolve({ data: [] }),
+    fetchInstagramAccounts(
+      supabase,
+      compactIds(
+        (groupRows ?? []).map(
+          (group: any) => group.primary_instagram_account_id
+        )
+      )
+    ),
+  ]);
+
+  const countMap = new Map<string, { total: number; active: number }>();
+  for (const row of countRows ?? []) {
+    const current = countMap.get(row.group_id) ?? { total: 0, active: 0 };
+    current.total += 1;
+    if (row.is_active) current.active += 1;
+    countMap.set(row.group_id, current);
+  }
+
+  let selectedGroup =
+    (groupRows ?? []).find((group: any) => group.id === selectedGroupId) ??
+    null;
+  if (!selectedGroup && requestedGroupId) {
+    const { data } = await (supabase as any)
+      .from("groups")
+      .select("*")
+      .eq("id", requestedGroupId)
+      .maybeSingle();
+    selectedGroup = data;
+  }
+
+  const memberResult = selectedGroupId
+    ? await (supabase as any)
+        .from("group_members")
+        .select(
+          "group_id, artist_id, is_active, metadata, created_at, updated_at, artist:artists(id, name_en, name_ko, profile_image_url, primary_instagram_account_id)"
+        )
+        .eq("group_id", selectedGroupId)
+        .order("is_active", { ascending: false })
+        .order("artist_id", { ascending: true })
+    : { data: [], error: null };
+
+  if (memberResult.error) {
+    return NextResponse.json(
+      { error: memberResult.error.message },
+      { status: 500 }
+    );
+  }
+
+  const memberArtists = await attachInstagramAccounts(
+    supabase,
+    (memberResult.data ?? [])
+      .map((member: any) => member.artist)
+      .filter(Boolean)
+  );
+  const memberArtistMap = new Map(
+    memberArtists.map((artist: any) => [artist.id, artist])
+  );
+
+  const groups = (groupRows ?? []).map((group: any) => ({
+    ...group,
+    primary_instagram_account:
+      groupAccountMap.get(group.primary_instagram_account_id) ?? null,
+    member_count: countMap.get(group.id)?.active ?? 0,
+    total_member_count: countMap.get(group.id)?.total ?? 0,
+  }));
+
+  const members = (memberResult.data ?? []).map((member: any) => ({
+    ...member,
+    artist: memberArtistMap.get(member.artist_id) ?? member.artist ?? null,
+  }));
+
   return NextResponse.json({
-    data,
+    data: members,
+    groups,
+    selected_group: selectedGroup
+      ? {
+          ...selectedGroup,
+          primary_instagram_account:
+            groupAccountMap.get(selectedGroup.primary_instagram_account_id) ??
+            null,
+          member_count:
+            countMap.get(selectedGroup.id)?.active ?? members.length,
+          total_member_count:
+            countMap.get(selectedGroup.id)?.total ?? members.length,
+        }
+      : null,
     pagination: {
       current_page: page,
       per_page: perPage,
@@ -35,3 +235,139 @@ export async function GET(req: NextRequest) {
     },
   });
 }
+
+export async function POST(req: NextRequest) {
+  const supabase = await createSupabaseServerClient();
+  const user = await requireAdmin(supabase);
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const body = await req.json();
+  if (!body.group_id || !body.artist_id) {
+    return NextResponse.json(
+      { error: "group_id and artist_id are required" },
+      { status: 400 }
+    );
+  }
+
+  const payload = {
+    group_id: body.group_id,
+    artist_id: body.artist_id,
+    is_active: body.is_active ?? true,
+    metadata: body.metadata ?? null,
+  };
+
+  const { data, error } = await (supabase as any)
+    .from("group_members")
+    .upsert(payload, { onConflict: "group_id,artist_id" })
+    .select()
+    .single();
+
+  if (error)
+    return NextResponse.json({ error: error.message }, { status: 500 });
+
+  await writeAuditLog({
+    adminUserId: user.id,
+    action: "create",
+    targetTable: "group_members",
+    targetId: `${data.group_id}:${data.artist_id}`,
+    afterState: data,
+  });
+
+  return NextResponse.json({ data });
+}
+
+export async function PATCH(req: NextRequest) {
+  const supabase = await createSupabaseServerClient();
+  const user = await requireAdmin(supabase);
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const body = await req.json();
+  if (!body.group_id || !body.artist_id) {
+    return NextResponse.json(
+      { error: "group_id and artist_id are required" },
+      { status: 400 }
+    );
+  }
+
+  const { data: before } = await (supabase as any)
+    .from("group_members")
+    .select("*")
+    .eq("group_id", body.group_id)
+    .eq("artist_id", body.artist_id)
+    .maybeSingle();
+
+  const patch = {
+    ...(typeof body.is_active === "boolean"
+      ? { is_active: body.is_active }
+      : {}),
+    ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+  };
+
+  const { data, error } = await (supabase as any)
+    .from("group_members")
+    .update(patch)
+    .eq("group_id", body.group_id)
+    .eq("artist_id", body.artist_id)
+    .select()
+    .single();
+
+  if (error)
+    return NextResponse.json({ error: error.message }, { status: 500 });
+
+  await writeAuditLog({
+    adminUserId: user.id,
+    action: "update",
+    targetTable: "group_members",
+    targetId: `${data.group_id}:${data.artist_id}`,
+    beforeState: before,
+    afterState: data,
+  });
+
+  return NextResponse.json({ data });
+}
+
+export async function DELETE(req: NextRequest) {
+  const supabase = await createSupabaseServerClient();
+  const user = await requireAdmin(supabase);
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const body = await req.json();
+  if (!body.group_id || !body.artist_id) {
+    return NextResponse.json(
+      { error: "group_id and artist_id are required" },
+      { status: 400 }
+    );
+  }
+
+  const { data: before } = await (supabase as any)
+    .from("group_members")
+    .select("*")
+    .eq("group_id", body.group_id)
+    .eq("artist_id", body.artist_id)
+    .maybeSingle();
+
+  const { error } = await (supabase as any)
+    .from("group_members")
+    .delete()
+    .eq("group_id", body.group_id)
+    .eq("artist_id", body.artist_id);
+
+  if (error)
+    return NextResponse.json({ error: error.message }, { status: 500 });
+
+  await writeAuditLog({
+    adminUserId: user.id,
+    action: "delete",
+    targetTable: "group_members",
+    targetId: `${body.group_id}:${body.artist_id}`,
+    beforeState: before,
+  });
+
+  return NextResponse.json({ ok: true });
+}
diff --git a/packages/web/lib/api/admin/entities.ts b/packages/web/lib/api/admin/entities.ts
index c33a4af4..eda7e09a 100644
--- a/packages/web/lib/api/admin/entities.ts
+++ b/packages/web/lib/api/admin/entities.ts
@@ -159,16 +159,74 @@ export interface GroupMember {
   group_id: string;
   is_active: boolean;
   metadata: Record<string, unknown> | null;
+  created_at?: string;
+  updated_at?: string;
+  artist?: GroupMemberArtist | null;
 }
 
-export function useGroupMemberList(page: number, perPage = 20) {
-  return useQuery<EntityListResponse<GroupMember>>({
-    queryKey: ["admin", "group-members", "list", page, perPage],
+export interface InstagramAccountSummary {
+  id: string;
+  username: string;
+  display_name: string | null;
+  profile_image_url: string | null;
+}
+
+export interface GroupMemberArtist {
+  id: string;
+  name_en: string | null;
+  name_ko: string | null;
+  profile_image_url: string | null;
+  primary_instagram_account_id: string | null;
+  primary_instagram_account?: InstagramAccountSummary | null;
+}
+
+export interface GroupSummary {
+  id: string;
+  name_en: string | null;
+  name_ko: string | null;
+  profile_image_url: string | null;
+  primary_instagram_account_id: string | null;
+  primary_instagram_account?: InstagramAccountSummary | null;
+  member_count: number;
+  total_member_count: number;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface GroupMemberListResponse extends EntityListResponse<GroupMember> {
+  groups: GroupSummary[];
+  selected_group: GroupSummary | null;
+}
+
+export interface GroupMemberPayload {
+  group_id: string;
+  artist_id: string;
+  is_active?: boolean;
+  metadata?: Record<string, unknown> | null;
+}
+
+export function useGroupMemberList(
+  page: number,
+  perPage = 20,
+  search = "",
+  groupId = ""
+) {
+  return useQuery<GroupMemberListResponse>({
+    queryKey: [
+      "admin",
+      "group-members",
+      "list",
+      page,
+      perPage,
+      search,
+      groupId,
+    ],
     queryFn: ({ signal }) => {
       const params = new URLSearchParams({
         page: String(page),
         per_page: String(perPage),
       });
+      if (search) params.set("search", search);
+      if (groupId) params.set("group_id", groupId);
       return adminFetch(`/api/admin/entities/group-members?${params}`, {
         signal,
       });
@@ -177,3 +235,64 @@ export function useGroupMemberList(page: number, perPage = 20) {
     placeholderData: keepPreviousData,
   });
 }
+
+export function useGroupMemberArtistSearch(search: string, groupId = "") {
+  return useQuery<{ data: GroupMemberArtist[] }>({
+    queryKey: ["admin", "group-members", "artist-search", search, groupId],
+    queryFn: ({ signal }) => {
+      const params = new URLSearchParams({
+        mode: "artist-search",
+        limit: "12",
+      });
+      if (search) params.set("search", search);
+      if (groupId) params.set("group_id", groupId);
+      return adminFetch(`/api/admin/entities/group-members?${params}`, {
+        signal,
+      });
+    },
+    enabled: search.trim().length >= 1,
+    staleTime: 30_000,
+  });
+}
+
+export function useCreateGroupMember() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (body: GroupMemberPayload) =>
+      adminFetch("/api/admin/entities/group-members", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      }),
+    onSuccess: () =>
+      qc.invalidateQueries({ queryKey: ["admin", "group-members"] }),
+  });
+}
+
+export function useUpdateGroupMember() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (body: GroupMemberPayload) =>
+      adminFetch("/api/admin/entities/group-members", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      }),
+    onSuccess: () =>
+      qc.invalidateQueries({ queryKey: ["admin", "group-members"] }),
+  });
+}
+
+export function useDeleteGroupMember() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (body: Pick<GroupMemberPayload, "group_id" | "artist_id">) =>
+      adminFetch("/api/admin/entities/group-members", {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      }),
+    onSuccess: () =>
+      qc.invalidateQueries({ queryKey: ["admin", "group-members"] }),
+  });
+}