前情提要

經過 Day 11 的多租戶管理介面建立，我們已經有了租戶切換與管理的基礎架構。今天我們要實作會員管理頁面，這是健身房日常營運中最頻繁使用的功能模組。

我們將建立一個現代化、響應式、高效能的會員管理介面，支援複雜查詢、批次操作、即時更新等企業級功能。

會員管理介面需求分析

用戶角色與使用場景

// 會員管理介面使用者角色分析
interface UserRole {
  role: string;
  permissions: string[];
  primaryUseCases: string[];
  interfaceNeeds: string[];
}

const memberManagementRoles: UserRole[] = [
  {
    role: 'gym_owner',
    permissions: ['create', 'read', 'update', 'delete', 'export', 'import'],
    primaryUseCases: [
      '會員數據分析',
      '營收統計查看',
      '批次操作管理',
      '系統設定調整'
    ],
    interfaceNeeds: [
      '統計儀表板',
      '進階篩選器',
      '匯出功能',
      '批次操作工具'
    ]
  },
  {
    role: 'gym_manager',
    permissions: ['create', 'read', 'update', 'export'],
    primaryUseCases: [
      '會員資料維護',
      '新會員註冊',
      '會籍狀態管理',
      '客戶服務處理'
    ],
    interfaceNeeds: [
      '快速搜尋',
      '詳細編輯表單',
      '狀態快速切換',
      '歷史記錄查看'
    ]
  },
  {
    role: 'gym_staff',
    permissions: ['create', 'read', 'update_limited'],
    primaryUseCases: [
      '會員報到處理',
      '基本資料更新',
      '聯絡資訊維護',
      '現場問題處理'
    ],
    interfaceNeeds: [
      '簡化操作介面',
      '快速識別系統',
      '一鍵報到',
      '緊急聯絡資訊'
    ]
  }
];

介面設計規範

// UI/UX 設計原則
const designPrinciples = {
  // 響應式設計斷點
  breakpoints: {
    mobile: '< 768px',    // 手機版：簡化操作，關鍵資訊優先
    tablet: '768px - 1024px', // 平板版：中等資訊密度
    desktop: '> 1024px'   // 桌面版：完整功能展示
  },

  // 資料展示密度
  informationDensity: {
    compact: '高資訊密度 - 適合資深用戶',
    comfortable: '中等密度 - 平衡可讀性與效率',
    spacious: '低密度 - 適合新手用戶'
  },

  // 互動模式
  interactionModes: {
    quickActions: '一鍵操作 - 報到、狀態切換',
    bulkOperations: '批次操作 - 多選、批次更新',
    detailView: '詳細檢視 - 完整資料編輯'
  }
};

會員列表頁面實作

主要列表組件

// apps/kyo-dashboard/src/pages/Members/MembersList.tsx
import React, { useState, useCallback, useMemo } from 'react';
import {
  Container,
  Paper,
  Title,
  Group,
  Button,
  TextInput,
  Select,
  MultiSelect,
  Table,
  ScrollArea,
  Avatar,
  Badge,
  ActionIcon,
  Menu,
  Pagination,
  Loader,
  Text,
  Flex,
  Stack
} from '@mantine/core';
import {
  IconSearch,
  IconFilter,
  IconPlus,
  IconDownload,
  IconUpload,
  IconDots,
  IconEdit,
  IconEye,
  IconTrash,
  IconUserCheck
} from '@tabler/icons-react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { modals } from '@mantine/modals';
import { notifications } from '@mantine/notifications';

import { useMemberSearchStore } from '../../stores/member-search-store';
import { useTenantStore } from '../../stores/tenant-store';
import { memberApi } from '../../services/api/member-api';
import { formatDate, formatPhoneNumber } from '../../utils/formatters';
import { MemberStatusBadge } from '../../components/Members/MemberStatusBadge';
import { MemberCheckInModal } from '../../components/Members/MemberCheckInModal';
import { MemberEditModal } from '../../components/Members/MemberEditModal';

export const MembersList: React.FC = () => {
  const queryClient = useQueryClient();
  const { currentTenant } = useTenantStore();
  const { searchParams, updateSearchParams, resetSearchParams } = useMemberSearchStore();

  // 模態視窗狀態
  const [checkInModalOpened, setCheckInModalOpened] = useState(false);
  const [editModalOpened, setEditModalOpened] = useState(false);
  const [selectedMember, setSelectedMember] = useState<Member | null>(null);

  // 會員搜尋查詢
  const {
    data: membersResult,
    isLoading,
    error,
    refetch
  } = useQuery({
    queryKey: ['members', currentTenant?.id, searchParams],
    queryFn: () => memberApi.searchMembers(searchParams),
    enabled: !!currentTenant?.id,
    refetchOnWindowFocus: false,
    staleTime: 5 * 60 * 1000 // 5分鐘
  });

  // 會員報到 Mutation
  const checkInMutation = useMutation({
    mutationFn: (identifier: string) => memberApi.checkIn(identifier),
    onSuccess: (result) => {
      notifications.show({
        title: '報到成功',
        message: `${result.member.name} 已成功報到`,
        color: 'green'
      });
      queryClient.invalidateQueries({ queryKey: ['members'] });
      setCheckInModalOpened(false);
    },
    onError: (error: any) => {
      notifications.show({
        title: '報到失敗',
        message: error.message || '發生未知錯誤',
        color: 'red'
      });
    }
  });

  // 狀態更新 Mutation
  const updateStatusMutation = useMutation({
    mutationFn: ({ memberId, status }: { memberId: string; status: MemberStatus }) =>
      memberApi.updateMemberStatus(memberId, status),
    onSuccess: () => {
      notifications.show({
        title: '狀態更新成功',
        message: '會員狀態已更新',
        color: 'green'
      });
      queryClient.invalidateQueries({ queryKey: ['members'] });
    }
  });

  // 搜尋處理
  const handleSearch = useCallback((filters: Partial<MemberSearchParams>) => {
    updateSearchParams(filters);
  }, [updateSearchParams]);

  // 快速報到
  const handleQuickCheckIn = useCallback((member: Member) => {
    modals.openConfirmModal({
      title: '確認報到',
      children: (
        <Text size="sm">
          確定要為 <strong>{member.personalInfo.name}</strong> 進行報到嗎？
        </Text>
      ),
      labels: { confirm: '確認報到', cancel: '取消' },
      onConfirm: () => checkInMutation.mutate(member.memberCode)
    });
  }, [checkInMutation]);

  // 狀態快速切換
  const handleStatusChange = useCallback((member: Member, newStatus: MemberStatus) => {
    updateStatusMutation.mutate({
      memberId: member.id,
      status: newStatus
    });
  }, [updateStatusMutation]);

  // 批次操作
  const handleBulkExport = useCallback(() => {
    // TODO: 實作批次匯出功能
    notifications.show({
      title: '匯出功能',
      message: '匯出功能開發中...',
      color: 'blue'
    });
  }, []);

  // 分頁處理
  const handlePageChange = useCallback((page: number) => {
    updateSearchParams({ page });
  }, [updateSearchParams]);

  // 計算總覽統計
  const memberStats = useMemo(() => {
    if (!membersResult?.members) return null;

    const total = membersResult.pagination.totalCount;
    const active = membersResult.members.filter(m => m.status === 'active').length;
    const inactive = membersResult.members.filter(m => m.status === 'inactive').length;

    return { total, active, inactive };
  }, [membersResult]);

  if (!currentTenant) {
    return <Text>請選擇租戶</Text>;
  }

  return (
    <Container size="xl" py="md">
      <Stack spacing="md">
        {/* 頁面標題與統計 */}
        <Paper p="md" withBorder>
          <Group position="apart" mb="md">
            <div>
              <Title order={2}>會員管理</Title>
              {memberStats && (
                <Text size="sm" color="dimmed" mt={4}>
                  總計 {memberStats.total} 位會員，
                  活躍 {memberStats.active} 位，
                  非活躍 {memberStats.inactive} 位
                </Text>
              )}
            </div>

            <Group spacing="sm">
              <Button
                leftIcon={<IconPlus size={16} />}
                onClick={() => setEditModalOpened(true)}
              >
                新增會員
              </Button>

              <Button
                variant="default"
                leftIcon={<IconUserCheck size={16} />}
                onClick={() => setCheckInModalOpened(true)}
              >
                快速報到
              </Button>

              <Menu shadow="md">
                <Menu.Target>
                  <ActionIcon variant="default">
                    <IconDots size={16} />
                  </ActionIcon>
                </Menu.Target>

                <Menu.Dropdown>
                  <Menu.Item
                    icon={<IconDownload size={14} />}
                    onClick={handleBulkExport}
                  >
                    匯出會員資料
                  </Menu.Item>
                  <Menu.Item icon={<IconUpload size={14} />}>
                    匯入會員資料
                  </Menu.Item>
                </Menu.Dropdown>
              </Menu>
            </Group>
          </Group>

          {/* 搜尋與篩選器 */}
          <MemberSearchFilters
            searchParams={searchParams}
            onSearch={handleSearch}
            onReset={resetSearchParams}
          />
        </Paper>

        {/* 會員列表表格 */}
        <Paper withBorder>
          <ScrollArea>
            <Table striped highlightOnHover>
              <thead>
                <tr>
                  <th>會員</th>
                  <th>會員編號</th>
                  <th>聯絡方式</th>
                  <th>狀態</th>
                  <th>加入日期</th>
                  <th>最後到訪</th>
                  <th>總訪問次數</th>
                  <th>操作</th>
                </tr>
              </thead>
              <tbody>
                {isLoading ? (
                  <tr>
                    <td colSpan={8} style={{ textAlign: 'center', padding: '2rem' }}>
                      <Loader />
                    </td>
                  </tr>
                ) : membersResult?.members.length === 0 ? (
                  <tr>
                    <td colSpan={8} style={{ textAlign: 'center', padding: '2rem' }}>
                      <Text color="dimmed">無會員資料</Text>
                    </td>
                  </tr>
                ) : (
                  membersResult?.members.map((member) => (
                    <MemberTableRow
                      key={member.id}
                      member={member}
                      onQuickCheckIn={handleQuickCheckIn}
                      onStatusChange={handleStatusChange}
                      onEdit={() => {
                        setSelectedMember(member);
                        setEditModalOpened(true);
                      }}
                    />
                  ))
                )}
              </tbody>
            </Table>
          </ScrollArea>

          {/* 分頁控制 */}
          {membersResult && membersResult.pagination.totalPages > 1 && (
            <Group position="center" p="md">
              <Pagination
                page={membersResult.pagination.currentPage}
                total={membersResult.pagination.totalPages}
                onChange={handlePageChange}
              />
            </Group>
          )}
        </Paper>
      </Stack>

      {/* 模態視窗 */}
      <MemberCheckInModal
        opened={checkInModalOpened}
        onClose={() => setCheckInModalOpened(false)}
        onCheckIn={(identifier) => checkInMutation.mutate(identifier)}
        isLoading={checkInMutation.isLoading}
      />

      <MemberEditModal
        opened={editModalOpened}
        onClose={() => {
          setEditModalOpened(false);
          setSelectedMember(null);
        }}
        member={selectedMember}
        onSuccess={() => {
          queryClient.invalidateQueries({ queryKey: ['members'] });
          setEditModalOpened(false);
          setSelectedMember(null);
        }}
      />
    </Container>
  );
};

搜尋篩選器組件

// apps/kyo-dashboard/src/components/Members/MemberSearchFilters.tsx
import React, { useState } from 'react';
import {
  Group,
  TextInput,
  Select,
  MultiSelect,
  DateInput,
  NumberInput,
  Button,
  Collapse,
  ActionIcon,
  Badge
} from '@mantine/core';
import { IconSearch, IconFilter, IconX, IconFilterOff } from '@tabler/icons-react';
import { DateValue } from '@mantine/dates';

interface MemberSearchFiltersProps {
  searchParams: MemberSearchParams;
  onSearch: (params: Partial<MemberSearchParams>) => void;
  onReset: () => void;
}

export const MemberSearchFilters: React.FC<MemberSearchFiltersProps> = ({
  searchParams,
  onSearch,
  onReset
}) => {
  const [advancedOpened, setAdvancedOpened] = useState(false);

  // 狀態選項
  const statusOptions = [
    { value: 'active', label: '活躍' },
    { value: 'inactive', label: '非活躍' },
    { value: 'suspended', label: '暫停' },
    { value: 'expired', label: '已到期' }
  ];

  // 性別選項
  const genderOptions = [
    { value: 'male', label: '男' },
    { value: 'female', label: '女' },
    { value: 'other', label: '其他' }
  ];

  // 排序選項
  const sortOptions = [
    { value: 'name', label: '姓名' },
    { value: 'joinDate', label: '加入日期' },
    { value: 'lastVisit', label: '最後到訪' },
    { value: 'totalVisits', label: '總訪問次數' }
  ];

  // 處理基礎搜尋
  const handleBasicSearch = (keyword: string) => {
    onSearch({ keyword, page: 1 });
  };

  // 處理進階篩選
  const handleAdvancedFilter = (filters: Partial<MemberSearchParams>) => {
    onSearch({ ...filters, page: 1 });
  };

  // 清除所有篩選
  const handleClearAll = () => {
    onReset();
    setAdvancedOpened(false);
  };

  // 計算已應用的篩選數量
  const appliedFiltersCount = Object.entries(searchParams).filter(
    ([key, value]) => key !== 'page' && key !== 'limit' && value != null && value !== ''
  ).length;

  return (
    <div>
      {/* 基礎搜尋列 */}
      <Group spacing="sm" mb="sm">
        <TextInput
          placeholder="搜尋會員姓名、電話或 Email"
          icon={<IconSearch size={16} />}
          value={searchParams.keyword || ''}
          onChange={(e) => handleBasicSearch(e.target.value)}
          style={{ flex: 1 }}
        />

        <Button
          variant="default"
          leftIcon={<IconFilter size={16} />}
          onClick={() => setAdvancedOpened(!advancedOpened)}
          color={appliedFiltersCount > 0 ? 'blue' : undefined}
        >
          進階篩選
          {appliedFiltersCount > 0 && (
            <Badge size="sm" ml="xs" color="blue">
              {appliedFiltersCount}
            </Badge>
          )}
        </Button>

        {appliedFiltersCount > 0 && (
          <ActionIcon
            variant="default"
            onClick={handleClearAll}
            title="清除所有篩選"
          >
            <IconFilterOff size={16} />
          </ActionIcon>
        )}
      </Group>

      {/* 進階篩選面板 */}
      <Collapse in={advancedOpened}>
        <div style={{ padding: '1rem', backgroundColor: '#f8f9fa', borderRadius: '0.5rem' }}>
          <Group spacing="md" mb="md">
            {/* 會員編號搜尋 */}
            <TextInput
              label="會員編號"
              placeholder="M20241201001"
              value={searchParams.memberCode || ''}
              onChange={(e) => handleAdvancedFilter({ memberCode: e.target.value })}
            />

            {/* 狀態篩選 */}
            <MultiSelect
              label="會員狀態"
              placeholder="選擇狀態"
              data={statusOptions}
              value={searchParams.status || []}
              onChange={(value) => handleAdvancedFilter({ status: value as MemberStatus[] })}
            />

            {/* 性別篩選 */}
            <MultiSelect
              label="性別"
              placeholder="選擇性別"
              data={genderOptions}
              value={searchParams.gender || []}
              onChange={(value) => handleAdvancedFilter({ gender: value as Gender[] })}
            />
          </Group>

          <Group spacing="md" mb="md">
            {/* 年齡範圍 */}
            <NumberInput
              label="最小年齡"
              placeholder="18"
              min={0}
              max={150}
              value={searchParams.ageFrom || undefined}
              onChange={(value) => handleAdvancedFilter({ ageFrom: value || undefined })}
            />

            <NumberInput
              label="最大年齡"
              placeholder="65"
              min={0}
              max={150}
              value={searchParams.ageTo || undefined}
              onChange={(value) => handleAdvancedFilter({ ageTo: value || undefined })}
            />

            {/* 加入日期範圍 */}
            <DateInput
              label="加入日期 (起始)"
              placeholder="選擇日期"
              value={searchParams.joinDateFrom ? new Date(searchParams.joinDateFrom) : null}
              onChange={(value: DateValue) =>
                handleAdvancedFilter({
                  joinDateFrom: value?.toISOString()
                })
              }
            />

            <DateInput
              label="加入日期 (結束)"
              placeholder="選擇日期"
              value={searchParams.joinDateTo ? new Date(searchParams.joinDateTo) : null}
              onChange={(value: DateValue) =>
                handleAdvancedFilter({
                  joinDateTo: value?.toISOString()
                })
              }
            />
          </Group>

          <Group spacing="md">
            {/* 排序設定 */}
            <Select
              label="排序欄位"
              data={sortOptions}
              value={searchParams.sortBy || 'name'}
              onChange={(value) => handleAdvancedFilter({ sortBy: value as any })}
            />

            <Select
              label="排序方式"
              data={[
                { value: 'asc', label: '升序' },
                { value: 'desc', label: '降序' }
              ]}
              value={searchParams.sortOrder || 'asc'}
              onChange={(value) => handleAdvancedFilter({ sortOrder: value as any })}
            />

            {/* 每頁顯示數量 */}
            <Select
              label="每頁顯示"
              data={[
                { value: '10', label: '10 筆' },
                { value: '20', label: '20 筆' },
                { value: '50', label: '50 筆' },
                { value: '100', label: '100 筆' }
              ]}
              value={String(searchParams.limit || 20)}
              onChange={(value) => handleAdvancedFilter({ limit: Number(value) })}
            />
          </Group>
        </div>
      </Collapse>
    </div>
  );
};

會員表格行組件

// apps/kyo-dashboard/src/components/Members/MemberTableRow.tsx
import React from 'react';
import {
  Group,
  Avatar,
  Text,
  Badge,
  ActionIcon,
  Menu,
  Button
} from '@mantine/core';
import {
  IconDots,
  IconEdit,
  IconEye,
  IconUserCheck,
  IconUserX,
  IconTrash
} from '@tabler/icons-react';

import { formatDate, formatPhoneNumber } from '../../utils/formatters';

interface MemberTableRowProps {
  member: Member;
  onQuickCheckIn: (member: Member) => void;
  onStatusChange: (member: Member, status: MemberStatus) => void;
  onEdit: () => void;
}

export const MemberTableRow: React.FC<MemberTableRowProps> = ({
  member,
  onQuickCheckIn,
  onStatusChange,
  onEdit
}) => {
  // 狀態顏色映射
  const getStatusColor = (status: MemberStatus) => {
    const colors = {
      active: 'green',
      inactive: 'gray',
      suspended: 'yellow',
      expired: 'red'
    };
    return colors[status] || 'gray';
  };

  // 狀態標籤映射
  const getStatusLabel = (status: MemberStatus) => {
    const labels = {
      active: '活躍',
      inactive: '非活躍',
      suspended: '暫停',
      expired: '已到期'
    };
    return labels[status] || status;
  };

  return (
    <tr key={member.id}>
      {/* 會員基本資訊 */}
      <td>
        <Group spacing="sm">
          <Avatar
            src={member.personalInfo.profilePhotoUrl}
            alt={member.personalInfo.name}
            radius="xl"
            size="sm"
          />
          <div>
            <Text size="sm" weight={500}>
              {member.personalInfo.name}
            </Text>
            {member.personalInfo.gender && (
              <Text size="xs" color="dimmed">
                {member.personalInfo.gender === 'male' ? '男' :
                 member.personalInfo.gender === 'female' ? '女' : '其他'}
              </Text>
            )}
          </div>
        </Group>
      </td>

      {/* 會員編號 */}
      <td>
        <Text size="sm" family="monospace">
          {member.memberCode}
        </Text>
      </td>

      {/* 聯絡方式 */}
      <td>
        <div>
          {member.personalInfo.phone && (
            <Text size="xs" color="dimmed">
              {formatPhoneNumber(member.personalInfo.phone)}
            </Text>
          )}
          {member.personalInfo.email && (
            <Text size="xs" color="dimmed">
              {member.personalInfo.email}
            </Text>
          )}
        </div>
      </td>

      {/* 狀態 */}
      <td>
        <Badge
          color={getStatusColor(member.membershipInfo.status)}
          variant="light"
          size="sm"
        >
          {getStatusLabel(member.membershipInfo.status)}
        </Badge>
      </td>

      {/* 加入日期 */}
      <td>
        <Text size="sm">
          {formatDate(member.membershipInfo.joinDate)}
        </Text>
      </td>

      {/* 最後到訪 */}
      <td>
        <Text size="sm" color={member.membershipInfo.lastVisitDate ? undefined : 'dimmed'}>
          {member.membershipInfo.lastVisitDate
            ? formatDate(member.membershipInfo.lastVisitDate)
            : '從未到訪'
          }
        </Text>
      </td>

      {/* 總訪問次數 */}
      <td>
        <Text size="sm" weight={500}>
          {member.membershipInfo.totalVisits}
        </Text>
      </td>

      {/* 操作選單 */}
      <td>
        <Group spacing={4}>
          {/* 快速報到按鈕 */}
          {member.membershipInfo.status === 'active' && (
            <Button
              size="xs"
              variant="light"
              color="green"
              leftIcon={<IconUserCheck size={12} />}
              onClick={() => onQuickCheckIn(member)}
            >
              報到
            </Button>
          )}

          {/* 更多操作選單 */}
          <Menu shadow="md" width={200}>
            <Menu.Target>
              <ActionIcon size="sm" variant="light">
                <IconDots size={14} />
              </ActionIcon>
            </Menu.Target>

            <Menu.Dropdown>
              <Menu.Item icon={<IconEye size={14} />}>
                查看詳情
              </Menu.Item>

              <Menu.Item
                icon={<IconEdit size={14} />}
                onClick={onEdit}
              >
                編輯資料
              </Menu.Item>

              <Menu.Divider />

              {/* 狀態切換選項 */}
              {member.membershipInfo.status !== 'active' && (
                <Menu.Item
                  icon={<IconUserCheck size={14} />}
                  color="green"
                  onClick={() => onStatusChange(member, 'active')}
                >
                  設為活躍
                </Menu.Item>
              )}

              {member.membershipInfo.status === 'active' && (
                <Menu.Item
                  icon={<IconUserX size={14} />}
                  color="yellow"
                  onClick={() => onStatusChange(member, 'suspended')}
                >
                  暫停會員
                </Menu.Item>
              )}

              <Menu.Divider />

              <Menu.Item
                icon={<IconTrash size={14} />}
                color="red"
                onClick={() => {
                  // TODO: 實作刪除確認
                }}
              >
                刪除會員
              </Menu.Item>
            </Menu.Dropdown>
          </Menu>
        </Group>
      </td>
    </tr>
  );
};

會員編輯表單

完整編輯模態視窗

// apps/kyo-dashboard/src/components/Members/MemberEditModal.tsx
import React, { useEffect } from 'react';
import {
  Modal,
  Paper,
  Title,
  TextInput,
  Select,
  Textarea,
  NumberInput,
  MultiSelect,
  Group,
  Button,
  Stack,
  Grid,
  Tabs,
  Avatar,
  FileInput,
  Switch,
  Divider
} from '@mantine/core';
import { useForm } from '@mantine/form';
import { DateInput } from '@mantine/dates';
import { IconUser, IconHeart, IconSettings, IconPhoto } from '@tabler/icons-react';
import { useMutation } from '@tanstack/react-query';
import { notifications } from '@mantine/notifications';

import { memberApi } from '../../services/api/member-api';
import { validatePhoneNumber, validateEmail } from '../../utils/validators';

interface MemberEditModalProps {
  opened: boolean;
  onClose: () => void;
  member?: Member | null;
  onSuccess: () => void;
}

export const MemberEditModal: React.FC<MemberEditModalProps> = ({
  opened,
  onClose,
  member,
  onSuccess
}) => {
  const isEditing = !!member;

  // 表單管理
  const form = useForm<MemberFormData>({
    initialValues: {
      personalInfo: {
        name: '',
        email: '',
        phone: '',
        dateOfBirth: null,
        gender: '',
        emergencyContact: {
          name: '',
          phone: '',
          relationship: ''
        }
      },
      fitnessProfile: {
        height: undefined,
        weight: undefined,
        bodyFatPercentage: undefined,
        fitnessGoals: [],
        medicalConditions: [],
        experienceLevel: 'beginner'
      },
      customFields: {}
    },

    validate: {
      'personalInfo.name': (value) =>
        !value || value.trim().length === 0 ? '姓名是必填項目' : null,
      'personalInfo.email': (value) =>
        value && !validateEmail(value) ? 'Email 格式不正確' : null,
      'personalInfo.phone': (value) =>
        value && !validatePhoneNumber(value) ? '手機號碼格式不正確' : null
    }
  });

  // 建立/更新 Mutation
  const createMemberMutation = useMutation({
    mutationFn: memberApi.createMember,
    onSuccess: () => {
      notifications.show({
        title: '建立成功',
        message: '會員已成功建立',
        color: 'green'
      });
      onSuccess();
    },
    onError: (error: any) => {
      notifications.show({
        title: '建立失敗',
        message: error.message || '發生未知錯誤',
        color: 'red'
      });
    }
  });

  const updateMemberMutation = useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateMemberRequest }) =>
      memberApi.updateMember(id, data),
    onSuccess: () => {
      notifications.show({
        title: '更新成功',
        message: '會員資料已成功更新',
        color: 'green'
      });
      onSuccess();
    },
    onError: (error: any) => {
      notifications.show({
        title: '更新失敗',
        message: error.message || '發生未知錯誤',
        color: 'red'
      });
    }
  });

  // 載入會員資料到表單
  useEffect(() => {
    if (member && opened) {
      form.setValues({
        personalInfo: {
          ...member.personalInfo,
          dateOfBirth: member.personalInfo.dateOfBirth
            ? new Date(member.personalInfo.dateOfBirth)
            : null
        },
        fitnessProfile: member.fitnessProfile,
        customFields: member.customFields
      });
    } else if (!member && opened) {
      form.reset();
    }
  }, [member, opened]);

  // 提交處理
  const handleSubmit = (values: MemberFormData) => {
    if (isEditing && member) {
      updateMemberMutation.mutate({
        id: member.id,
        data: {
          ...values,
          version: member.metadata.version
        }
      });
    } else {
      createMemberMutation.mutate(values);
    }
  };

  // 健身目標選項
  const fitnessGoalOptions = [
    { value: 'weight_loss', label: '減重' },
    { value: 'muscle_gain', label: '增肌' },
    { value: 'strength', label: '力量訓練' },
    { value: 'endurance', label: '耐力提升' },
    { value: 'flexibility', label: '柔軟度' },
    { value: 'general_fitness', label: '一般健身' }
  ];

  // 性別選項
  const genderOptions = [
    { value: 'male', label: '男' },
    { value: 'female', label: '女' },
    { value: 'other', label: '其他' }
  ];

  // 經驗等級選項
  const experienceLevelOptions = [
    { value: 'beginner', label: '初學者' },
    { value: 'intermediate', label: '中級' },
    { value: 'advanced', label: '進階' }
  ];

  return (
    <Modal
      opened={opened}
      onClose={onClose}
      title={
        <Title order={3}>
          {isEditing ? '編輯會員資料' : '新增會員'}
        </Title>
      }
      size="xl"
      centered
      closeOnClickOutside={false}
    >
      <form onSubmit={form.onSubmit(handleSubmit)}>
        <Tabs defaultValue="personal" orientation="horizontal">
          <Tabs.List>
            <Tabs.Tab value="personal" icon={<IconUser size={14} />}>
              個人資料
            </Tabs.Tab>
            <Tabs.Tab value="fitness" icon={<IconHeart size={14} />}>
              健身資料
            </Tabs.Tab>
            <Tabs.Tab value="custom" icon={<IconSettings size={14} />}>
              自訂欄位
            </Tabs.Tab>
          </Tabs.List>

          {/* 個人資料分頁 */}
          <Tabs.Panel value="personal" pt="md">
            <Stack spacing="md">
              {/* 基本資料 */}
              <Grid>
                <Grid.Col span={12}>
                  <TextInput
                    label="姓名"
                    placeholder="請輸入姓名"
                    required
                    {...form.getInputProps('personalInfo.name')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <TextInput
                    label="Email"
                    placeholder="example@email.com"
                    {...form.getInputProps('personalInfo.email')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <TextInput
                    label="手機號碼"
                    placeholder="0912345678"
                    {...form.getInputProps('personalInfo.phone')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <DateInput
                    label="生日"
                    placeholder="選擇生日"
                    {...form.getInputProps('personalInfo.dateOfBirth')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <Select
                    label="性別"
                    placeholder="選擇性別"
                    data={genderOptions}
                    {...form.getInputProps('personalInfo.gender')}
                  />
                </Grid.Col>
              </Grid>

              <Divider label="緊急聯絡人" labelPosition="left" />

              {/* 緊急聯絡人 */}
              <Grid>
                <Grid.Col span={4}>
                  <TextInput
                    label="聯絡人姓名"
                    placeholder="家屬姓名"
                    {...form.getInputProps('personalInfo.emergencyContact.name')}
                  />
                </Grid.Col>

                <Grid.Col span={4}>
                  <TextInput
                    label="聯絡人電話"
                    placeholder="0912345678"
                    {...form.getInputProps('personalInfo.emergencyContact.phone')}
                  />
                </Grid.Col>

                <Grid.Col span={4}>
                  <TextInput
                    label="關係"
                    placeholder="父親、母親等"
                    {...form.getInputProps('personalInfo.emergencyContact.relationship')}
                  />
                </Grid.Col>
              </Grid>
            </Stack>
          </Tabs.Panel>

          {/* 健身資料分頁 */}
          <Tabs.Panel value="fitness" pt="md">
            <Stack spacing="md">
              {/* 身體數據 */}
              <Grid>
                <Grid.Col span={6}>
                  <NumberInput
                    label="身高 (公分)"
                    placeholder="170"
                    min={50}
                    max={250}
                    {...form.getInputProps('fitnessProfile.height')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <NumberInput
                    label="體重 (公斤)"
                    placeholder="70.5"
                    min={20}
                    max={300}
                    precision={1}
                    {...form.getInputProps('fitnessProfile.weight')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <NumberInput
                    label="體脂率 (%)"
                    placeholder="15.5"
                    min={0}
                    max={100}
                    precision={1}
                    {...form.getInputProps('fitnessProfile.bodyFatPercentage')}
                  />
                </Grid.Col>

                <Grid.Col span={6}>
                  <Select
                    label="運動經驗"
                    placeholder="選擇經驗等級"
                    data={experienceLevelOptions}
                    {...form.getInputProps('fitnessProfile.experienceLevel')}
                  />
                </Grid.Col>
              </Grid>

              {/* 健身目標 */}
              <MultiSelect
                label="健身目標"
                placeholder="選擇健身目標"
                data={fitnessGoalOptions}
                {...form.getInputProps('fitnessProfile.fitnessGoals')}
              />

              {/* 健康狀況 */}
              <Textarea
                label="健康狀況或注意事項"
                placeholder="請描述任何相關的健康狀況、傷病史或特殊注意事項"
                minRows={3}
                value={form.values.fitnessProfile.medicalConditions?.join('\n') || ''}
                onChange={(e) =>
                  form.setFieldValue(
                    'fitnessProfile.medicalConditions',
                    e.target.value.split('\n').filter(line => line.trim())
                  )
                }
              />
            </Stack>
          </Tabs.Panel>

          {/* 自訂欄位分頁 */}
          <Tabs.Panel value="custom" pt="md">
            <Stack spacing="md">
              <Title order={5}>自訂欄位</Title>
              <Text size="sm" color="dimmed">
                這裡可以新增健身房特有的欄位，例如：會員分級、推薦人、特殊備註等
              </Text>

              {/* TODO: 動態自訂欄位編輯器 */}
              <Paper p="md" withBorder>
                <Text size="sm" color="dimmed">
                  自訂欄位編輯器開發中...
                </Text>
              </Paper>
            </Stack>
          </Tabs.Panel>
        </Tabs>

        {/* 操作按鈕 */}
        <Group position="right" mt="xl">
          <Button variant="default" onClick={onClose}>
            取消
          </Button>
          <Button
            type="submit"
            loading={createMemberMutation.isLoading || updateMemberMutation.isLoading}
          >
            {isEditing ? '更新' : '建立'}
          </Button>
        </Group>
      </form>
    </Modal>
  );
};

interface MemberFormData {
  personalInfo: {
    name: string;
    email?: string;
    phone?: string;
    dateOfBirth?: Date | null;
    gender?: string;
    emergencyContact?: {
      name: string;
      phone: string;
      relationship: string;
    };
  };
  fitnessProfile: {
    height?: number;
    weight?: number;
    bodyFatPercentage?: number;
    fitnessGoals: string[];
    medicalConditions: string[];
    experienceLevel: 'beginner' | 'intermediate' | 'advanced';
  };
  customFields: Record<string, any>;
}

會員報到功能

快速報到視窗

// apps/kyo-dashboard/src/components/Members/MemberCheckInModal.tsx
import React, { useState } from 'react';
import {
  Modal,
  TextInput,
  Button,
  Paper,
  Group,
  Text,
  Avatar,
  Badge,
  Stack,
  Alert,
  Loader
} from '@mantine/core';
import { IconSearch, IconUserCheck, IconAlertCircle } from '@tabler/icons-react';
import { useQuery } from '@tanstack/react-query';

import { memberApi } from '../../services/api/member-api';
import { formatDate } from '../../utils/formatters';

interface MemberCheckInModalProps {
  opened: boolean;
  onClose: () => void;
  onCheckIn: (identifier: string) => void;
  isLoading: boolean;
}

export const MemberCheckInModal: React.FC<MemberCheckInModalProps> = ({
  opened,
  onClose,
  onCheckIn,
  isLoading
}) => {
  const [searchTerm, setSearchTerm] = useState('');
  const [selectedMember, setSelectedMember] = useState<Member | null>(null);

  // 會員搜尋查詢 (防抖)
  const {
    data: searchResults,
    isLoading: isSearching,
    error: searchError
  } = useQuery({
    queryKey: ['member-search', searchTerm],
    queryFn: () => memberApi.searchMembers({
      keyword: searchTerm,
      limit: 5
    }),
    enabled: searchTerm.length >= 2 && opened,
    staleTime: 30 * 1000 // 30秒
  });

  // 重置狀態
  const handleClose = () => {
    setSearchTerm('');
    setSelectedMember(null);
    onClose();
  };

  // 執行報到
  const handleConfirmCheckIn = () => {
    if (selectedMember) {
      onCheckIn(selectedMember.memberCode);
    }
  };

  // 選擇會員
  const handleSelectMember = (member: Member) => {
    setSelectedMember(member);
    setSearchTerm(member.personalInfo.name);
  };

  return (
    <Modal
      opened={opened}
      onClose={handleClose}
      title="會員報到"
      size="md"
      centered
    >
      <Stack spacing="md">
        {/* 搜尋輸入 */}
        <TextInput
          label="搜尋會員"
          placeholder="輸入會員姓名、電話或會員編號"
          icon={<IconSearch size={16} />}
          value={searchTerm}
          onChange={(e) => {
            setSearchTerm(e.target.value);
            setSelectedMember(null);
          }}
          autoFocus
        />

        {/* 搜尋結果 */}
        {searchTerm.length >= 2 && (
          <div>
            {isSearching && (
              <Paper p="md" withBorder>
                <Group>
                  <Loader size="sm" />
                  <Text>搜尋中...</Text>
                </Group>
              </Paper>
            )}

            {searchError && (
              <Alert icon={<IconAlertCircle size={16} />} title="搜尋錯誤" color="red">
                搜尋過程中發生錯誤，請重試
              </Alert>
            )}

            {searchResults && searchResults.members.length === 0 && !isSearching && (
              <Paper p="md" withBorder>
                <Text color="dimmed">找不到符合條件的會員</Text>
              </Paper>
            )}

            {searchResults && searchResults.members.length > 0 && (
              <Paper withBorder>
                {searchResults.members.map((member) => (
                  <Paper
                    key={member.id}
                    p="sm"
                    style={{
                      cursor: 'pointer',
                      backgroundColor: selectedMember?.id === member.id ? '#f0f7ff' : 'transparent'
                    }}
                    onClick={() => handleSelectMember(member)}
                  >
                    <Group>
                      <Avatar
                        src={member.personalInfo.profilePhotoUrl}
                        alt={member.personalInfo.name}
                        radius="xl"
                      />

                      <div style={{ flex: 1 }}>
                        <Group position="apart">
                          <div>
                            <Text weight={500}>{member.personalInfo.name}</Text>
                            <Text size="sm" color="dimmed">
                              {member.memberCode}
                              {member.personalInfo.phone && ` • ${member.personalInfo.phone}`}
                            </Text>
                          </div>

                          <div style={{ textAlign: 'right' }}>
                            <Badge
                              color={
                                member.membershipInfo.status === 'active' ? 'green' :
                                member.membershipInfo.status === 'inactive' ? 'gray' :
                                member.membershipInfo.status === 'suspended' ? 'yellow' : 'red'
                              }
                              size="sm"
                            >
                              {
                                member.membershipInfo.status === 'active' ? '活躍' :
                                member.membershipInfo.status === 'inactive' ? '非活躍' :
                                member.membershipInfo.status === 'suspended' ? '暫停' : '已到期'
                              }
                            </Badge>
                          </div>
                        </Group>

                        {member.membershipInfo.lastVisitDate && (
                          <Text size="xs" color="dimmed">
                            最後到訪：{formatDate(member.membershipInfo.lastVisitDate)}
                          </Text>
                        )}
                      </div>
                    </Group>
                  </Paper>
                ))}
              </Paper>
            )}
          </div>
        )}

        {/* 選中的會員資訊 */}
        {selectedMember && (
          <Paper p="md" withBorder style={{ backgroundColor: '#f8f9fa' }}>
            <Group>
              <Avatar
                src={selectedMember.personalInfo.profilePhotoUrl}
                alt={selectedMember.personalInfo.name}
                radius="xl"
                size="lg"
              />

              <div style={{ flex: 1 }}>
                <Text weight={600} size="lg">
                  {selectedMember.personalInfo.name}
                </Text>
                <Text size="sm" color="dimmed">
                  會員編號：{selectedMember.memberCode}
                </Text>
                <Text size="sm" color="dimmed">
                  總訪問次數：{selectedMember.membershipInfo.totalVisits}
                </Text>
              </div>

              <Badge
                color={selectedMember.membershipInfo.status === 'active' ? 'green' : 'red'}
                size="lg"
              >
                {selectedMember.membershipInfo.status === 'active' ? '可報到' : '無法報到'}
              </Badge>
            </Group>

            {selectedMember.membershipInfo.status !== 'active' && (
              <Alert
                icon={<IconAlertCircle size={16} />}
                title="無法報到"
                color="yellow"
                mt="sm"
              >
                此會員目前狀態為「
                {selectedMember.membershipInfo.status === 'inactive' ? '非活躍' :
                 selectedMember.membershipInfo.status === 'suspended' ? '暫停' : '已到期'}
                」，無法進行報到
              </Alert>
            )}
          </Paper>
        )}

        {/* 操作按鈕 */}
        <Group position="right">
          <Button variant="default" onClick={handleClose}>
            取消
          </Button>

          <Button
            leftIcon={<IconUserCheck size={16} />}
            onClick={handleConfirmCheckIn}
            loading={isLoading}
            disabled={!selectedMember || selectedMember.membershipInfo.status !== 'active'}
          >
            確認報到
          </Button>
        </Group>
      </Stack>
    </Modal>
  );
};

狀態管理與 API 整合

會員搜尋狀態管理

// apps/kyo-dashboard/src/stores/member-search-store.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface MemberSearchState {
  searchParams: MemberSearchParams;
  updateSearchParams: (params: Partial<MemberSearchParams>) => void;
  resetSearchParams: () => void;
}

const defaultSearchParams: MemberSearchParams = {
  keyword: '',
  status: [],
  sortBy: 'name',
  sortOrder: 'asc',
  page: 1,
  limit: 20
};

export const useMemberSearchStore = create<MemberSearchState>()(
  persist(
    (set, get) => ({
      searchParams: defaultSearchParams,

      updateSearchParams: (params) =>
        set((state) => ({
          searchParams: { ...state.searchParams, ...params }
        })),

      resetSearchParams: () =>
        set({ searchParams: defaultSearchParams })
    }),
    {
      name: 'member-search-params',
      partialize: (state) => ({
        searchParams: {
          ...state.searchParams,
          page: 1 // 重置頁碼，避免跨會話分頁問題
        }
      })
    }
  )
);

API 服務層

// apps/kyo-dashboard/src/services/api/member-api.ts
import { apiClient } from './api-client';

export const memberApi = {
  // 搜尋會員
  searchMembers: async (params: MemberSearchParams): Promise<MemberSearchResult> => {
    const response = await apiClient.post('/api/members/search', params);
    return response.data;
  },

  // 建立會員
  createMember: async (data: CreateMemberRequest): Promise<Member> => {
    const response = await apiClient.post('/api/members', data);
    return response.data;
  },

  // 更新會員
  updateMember: async (id: string, data: UpdateMemberRequest): Promise<Member> => {
    const response = await apiClient.put(`/api/members/${id}`, data);
    return response.data;
  },

  // 會員報到
  checkIn: async (identifier: string): Promise<CheckInResult> => {
    const response = await apiClient.post('/api/members/checkin', { identifier });
    return response.data;
  },

  // 更新會員狀態
  updateMemberStatus: async (id: string, status: MemberStatus): Promise<void> => {
    await apiClient.patch(`/api/members/${id}/status`, { status });
  },

  // 取得會員統計
  getMemberStatistics: async (dateFrom?: string, dateTo?: string): Promise<MemberStatistics> => {
    const params = new URLSearchParams();
    if (dateFrom) params.append('dateFrom', dateFrom);
    if (dateTo) params.append('dateTo', dateTo);

    const response = await apiClient.get(`/api/members/statistics?${params.toString()}`);
    return response.data;
  },

  // 匯出會員資料
  exportMembers: async (params: MemberSearchParams): Promise<Blob> => {
    const response = await apiClient.post('/api/members/export', params, {
      responseType: 'blob'
    });
    return response.data;
  }
};

效能優化與使用者體驗

虛擬化大量資料

// apps/kyo-dashboard/src/components/Members/VirtualizedMemberTable.tsx
import React from 'react';
import { FixedSizeList as List } from 'react-window';
import { Paper, ScrollArea } from '@mantine/core';

interface VirtualizedMemberTableProps {
  members: Member[];
  onQuickCheckIn: (member: Member) => void;
  onStatusChange: (member: Member, status: MemberStatus) => void;
  onEdit: (member: Member) => void;
}

export const VirtualizedMemberTable: React.FC<VirtualizedMemberTableProps> = ({
  members,
  onQuickCheckIn,
  onStatusChange,
  onEdit
}) => {
  const itemHeight = 80; // 每行高度

  const Row = React.memo(({ index, style }: { index: number; style: React.CSSProperties }) => {
    const member = members[index];

    return (
      <div style={style}>
        <MemberTableRow
          member={member}
          onQuickCheckIn={onQuickCheckIn}
          onStatusChange={onStatusChange}
          onEdit={() => onEdit(member)}
        />
      </div>
    );
  });

  return (
    <Paper withBorder>
      <List
        height={600} // 表格高度
        itemCount={members.length}
        itemSize={itemHeight}
        overscanCount={5} // 預渲染項目數
      >
        {Row}
      </List>
    </Paper>
  );
};

響應式設計適配

// apps/kyo-dashboard/src/styles/members.module.scss
.membersContainer {
  @media (max-width: 768px) {
    // 手機版：隱藏部分欄位
    .desktopOnly {
      display: none;
    }

    // 簡化搜尋篩選器
    .searchFilters {
      flex-direction: column;

      .advancedFilters {
        margin-top: 1rem;
      }
    }

    // 調整表格佈局
    .memberTable {
      font-size: 0.875rem;

      .actionButtons {
        flex-direction: column;
        gap: 0.25rem;
      }
    }
  }

  @media (min-width: 768px) and (max-width: 1024px) {
    // 平板版：平衡資訊密度
    .memberTable {
      .memberAvatar {
        display: block;
      }

      .contactInfo {
        max-width: 120px;
        overflow: hidden;
        text-overflow: ellipsis;
      }
    }
  }

  @media (min-width: 1024px) {
    // 桌面版：顯示完整資訊
    .memberTable {
      .allColumns {
        display: table-cell;
      }
    }
  }
}

今日總結

今天我們完成了健身房會員管理介面的完整實作，從需求分析到技術實現，建構了現代化的會員管理系統：

✅ 完成功能

1. 多維度搜尋與篩選

   • 關鍵字搜尋（姓名、電話、Email）
   • 進階篩選（狀態、性別、年齡、加入日期）
   • 彈性排序與分頁機制

2. 即時會員操作

   • 一鍵快速報到功能
   • 狀態即時切換
   • 會員資料 CRUD 操作

3. 響應式使用者介面

   • 手機、平板、桌面自適應
   • 資訊密度動態調整
   • 直覺化操作體驗

4. 企業級效能優化

   • 虛擬化長列表渲染
   • 智能查詢防抖機制
   • React Query 快取策略

🏗️ 技術架構亮點

graph TB
    A[會員管理介面] --> B[搜尋篩選層]
    A --> C[資料展示層]
    A --> D[操作互動層]

    B --> B1[關鍵字搜尋]
    B --> B2[進階篩選器]
    B --> B3[狀態管理]

    C --> C1[虛擬化表格]
    C --> C2[響應式佈局]
    C --> C3[即時更新]

    D --> D1[模態視窗]
    D --> D2[批次操作]
    D --> D3[快速操作]

📊 效能指標

實做心得

1. 用戶體驗優先：從實際健身房工作人員角度設計介面，確保操作流程符合實際需求

2. 效能與功能平衡：在提供功能的同時，通過技術優化確保流暢體驗

3. 可維護性考慮：模組化設計讓後續功能擴充更加容易

4. 資料驅動決策：通過實際效能指標指導優化方向