[DDD] Thiết kế Chi tiết Trang Cài đặt

Tóm tắt tài liệu

Tài liệu này mô tả thiết kế kỹ thuật chi tiết cho Trang Cài đặt (Settings Page). Đây là một giao diện điều hướng dạng tab phức tạp, cho phép người dùng quản lý cài đặt nội dung, quyền riêng tư và thông báo thông qua ba màn hình con được tổ chức một cách logic và có giao diện dark theme với accent màu xanh.

1. Tổng quan (Overview)

1.1. Bối cảnh và Vấn đề

Để tránh làm người dùng choáng ngợp với quá nhiều tùy chọn cài đặt, các cài đặt cần được phân loại và sắp xếp một cách hợp lý. Trang Cài đặt giải quyết vấn đề này bằng cách sử dụng giao diện tab, giúp nhóm các cài đặt liên quan lại với nhau và cung cấp một lối vào duy nhất để quản lý tất cả các tùy chọn của Prima Brok platform.

1.2. Mục tiêu & Phi mục tiêu (Goals and Non-Goals)

Mục tiêu (Goals)

• Cung cấp một giao diện điều hướng dựa trên tab với 3 danh mục chính.
• Tab Nội dung (Content): Quản lý cài đặt thông báo desktop, tương tác và thông báo in-app.
• Tab Quyền riêng tư (Privacy): Quản lý bảo mật tài khoản, lịch sử đăng nhập, phiên hoạt động và danh sách chặn.
• Tab Thông báo (Notifications): Quản lý các loại thông báo browser, push và email.
• Cung cấp nút bật/tắt cho các tùy chọn đơn giản và ô nhập liệu cho các cài đặt chi tiết hơn.
• Nhớ vị trí: Hệ thống nhớ tab nào bạn đang xem, khi quay lại sẽ mở đúng chỗ đó.
• Tự động lưu: Cài đặt được lưu tự động và hiển thị thông báo khi hoàn tất.

Phi mục tiêu (Non-Goals)

• Bản thân trang này không chứa logic xử lý cài đặt phức tạp; nó chỉ điều phối và hiển thị các component con.
• Không quản lý cài đặt hệ thống hoặc admin (chỉ cài đặt người dùng).
• Không hỗ trợ import/export cài đặt hàng loạt.

2. Kiến trúc Tổng thể (Overall Architecture)

Đây là một component điều phối (coordinator component) phức tạp, quản lý trạng thái tab, giao tiếp với API và điều phối các component con chuyên biệt.

🔍 Giải thích sơ đồ:

Tầng 1 - Giao diện chính (Client):

• Trang Cài đặt là "trung tâm điều khiển"
• Quản lý việc chuyển đổi giữa các tab

Tầng 2 - Các tab con:

• Mỗi tab có chức năng riêng biệt
• Như các "phòng" khác nhau trong một ngôi nhà

Tầng 3 - Kết nối dữ liệu:

• Hooks = "cầu nối" giữa giao diện và dữ liệu
• API = "đường dây" liên lạc với server

Tầng 4 - Lưu trữ:

• Browser Storage = "bộ nhớ tạm" ghi nhớ lựa chọn
• Backend = "kho dữ liệu chính" lưu cài đặt thật

Sequence Diagram - Luồng hoạt động Trang Cài đặt

Giải thích các bước chính:

1. Khởi tạo: Tải cài đặt và nhớ tab trước đó
2. Auto-save: Debounce 2 giây trước khi lưu
3. Optimistic Updates: UI cập nhật ngay, rollback nếu lỗi
4. Tab switching: Lưu vị trí tab vào localStorage
5. Security features: Modal riêng cho 2FA và session management

3. Thiết kế Chi tiết (Detailed Design)

3.1. Thiết kế Giao diện & Luồng người dùng (UI & User Flow)

• Components: SettingsPage, ContentSettings, PrivacySettings, NotificationSettings, ToggleSwitch, PasswordChangeForm, TwoFactorSetup.
• State Management:
  • activeTab: State (content, privacy, hoặc notifications) để theo dõi tab nào đang được chọn.
  • settingsData: Đối tượng chứa tất cả cài đặt người dùng từ API.
  • pendingChanges: Đối tượng theo dõi các thay đổi chưa được lưu.
  • isSaving: Cờ boolean để hiển thị trạng thái đang lưu.

🚀 Hành trình của người dùng:

Bước 1 - Mở trang cài đặt: Giống như khi bạn mở cài đặt trên điện thoại, người dùng click vào menu "Cài đặt"

Bước 2 - Hệ thống chuẩn bị:

• 💾 Nhớ lại phần nào người dùng đã xem lần trước (như bookmark)
• 📥 Tải thông tin cài đặt hiện tại từ tài khoản

Bước 3 - Hiển thị loading: Biểu tượng xoay tròn xuất hiện trong khi hệ thống đang chuẩn bị dữ liệu

Bước 4: Sau khi tải xong, người dùng thấy:

• Thanh điều hướng với 3 tab: Nội dung, Quyền riêng tư, Thông báo.
• Nội dung của tab đang được chọn.

Bước 5: Khi người dùng thay đổi bất kỳ cài đặt nào (bật/tắt, nhập liệu):

• Hệ thống ghi nhận thay đổi.
• Sau 2 giây không có thay đổi nào khác, hệ thống tự động lưu.

Bước 6: Trong quá trình lưu cài đặt:

• Hiển thị trạng thái "Đang lưu...".
• Gửi thông tin mới lên server.
• Hiển thị thông báo kết quả (thành công hoặc lỗi).

Bước 7: Các tính năng bảo mật đặc biệt như:

• Thiết lập xác thực 2 yếu tố
• Đổi mật khẩu
• Quản lý phiên đăng nhập

Sẽ mở ra cửa sổ popup riêng để người dùng thực hiện các bước cần thiết.

3.2. Thiết kế API (API Design)

i. Lấy Cài đặt Người dùng

Mục đích: Tải tất cả cài đặt hiện tại của người dùng khi vào trang

Endpoint: GET /brok/api/v1/user/settings

Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Response:

{
  "success": true,
  "data": {
    "content": {
      "desktop_notifications": true,
      "browser_notifications": true,
      "interactions": {
      "likes": true,
      "comments": true,
      "new_followers": true,
      "mentions": true,
      "tags": true
    },
    "in_app_notifications": {
      "likes": true,
      "comments": true,
      "new_followers": true,
      "mentions": true,
      "tags": true
    }
  },
  "privacy": {
    "two_factor_enabled": false,
    "login_notifications": true,
    "session_timeout": 3600
  },
  "notifications": {
  "browser_notifications": true,
    "push_notifications": true,
    "email_notifications": {
      "marketing": false,
      "updates": true,
      "security": true
    }
  }
  }
}

ii. Cập nhật Cài đặt

Cập nhật một hoặc nhiều cài đặt của người dùng.

Endpoint: PUT /brok/api/v1/user/settings

Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Request Body:

{
"content": {
  "desktop_notifications": false,
  "interactions": {
    "likes": false
  }
  }
}

Response:

{
  "success": true,
  "message": "Settings updated successfully",
  "data": {
    "updated_fields": ["content.desktop_notifications", "content.interactions.likes"],
    "timestamp": "2023-11-03T10:30:00Z"
  }
}

iii. Bật/Tắt Two-Factor Authentication

Quản lý tính năng xác thực hai yếu tố.

Endpoint: POST /brok/api/v1/auth/2fa/toggle

Request Body (Bật 2FA):

{
"action": "enable",
"phone_number": "+84901234567"
}

Request Body (Tắt 2FA):

{
"action": "disable",
"verification_code": "123456"
}

Response:

{
  "success": true,
  "message": "Two-factor authentication enabled successfully",
  "data": {
    "backup_codes": ["code1", "code2", "code3"],
    "qr_code": "data:image/png;base64,..."
  }
}

iv. Quản lý Phiên hoạt động

Lấy danh sách và xóa các phiên hoạt động.

Lấy danh sách phiên: GET /brok/api/v1/user/sessions

Xóa phiên cụ thể: DELETE /brok/api/v1/user/sessions/{session_id}

Xóa tất cả phiên khác: DELETE /brok/api/v1/user/sessions/others

3.4. Logic Xác thực & Bảo mật (Validation & Security Logic)

• Client-side Validation:

  • Email format validation cho notification settings
  • Phone number validation cho 2FA setup
  • Password strength validation cho change password
  • Required field validation cho security settings

• Debounced Auto-save:

const debouncedSave = useCallback(
debounce((changes) => {
updateSettingsMutation.mutate(changes);
}, 2000),
[]
);

• Security Measures:
  • Current password verification trước khi thay đổi cài đặt bảo mật
  • Rate limiting cho 2FA attempts
  • Session validation cho sensitive operations

4. Các yếu tố phi chức năng (Non-Functional Requirements)

4.1. Bảo mật (Security)

• Xác thực Session: Tất cả API calls đều require valid JWT token.
• Sensitive Operations: Thay đổi password, bật/tắt 2FA yêu cầu xác nhận password hiện tại.
• Rate Limiting: API có rate limiting để ngăn chặn brute force attacks.
• Data Encryption: Sensitive data như phone numbers được encrypt trong database.

4.2. Trải nghiệm người dùng (UX)

• Auto-save: Cài đặt được tự động lưu sau 2 giây không có thay đổi, giảm friction cho người dùng.
• Visual Feedback: Toggle switches có animation smooth, loading states rõ ràng.
• Responsive Design: Giao diện hoạt động tốt trên cả desktop và mobile.
• Dark Theme Consistency: Màu sắc và styling nhất quán với theme tổng thể của Prima Brok.
• Accessibility: Proper ARIA labels, keyboard navigation support.

4.3. Hiệu năng (Performance)

• Lazy Loading: Mỗi tab component được lazy load để giảm initial bundle size.
• Optimistic Updates: UI cập nhật ngay lập tức, revert nếu API call thất bại.
• Caching: Settings data được cache và chỉ refetch khi cần thiết.
• Debouncing: Auto-save được debounce để tránh quá nhiều API calls.

5. Rủi ro và Phương án giảm thiểu (Risks and Mitigation)

Rủi ro	Mức độ ảnh hưởng	Khả năng xảy ra	Phương án giảm thiểu
Auto-save thất bại, người dùng mất thay đổi	Cao	Thấp	Implement optimistic updates với rollback mechanism. Hiển thị toast error và retry button khi save thất bại.
Conflict khi nhiều device thay đổi cài đặt cùng lúc	Trung bình	Trung bình	Implement last-write-wins với timestamp, hoặc conflict resolution UI cho sensitive settings.
2FA setup thất bại giữa chừng	Cao	Thấp	Implement proper cleanup mechanism, clear partial 2FA state. Provide clear recovery steps.
Performance issues với large settings object	Thấp	Thấp	Use React.memo và useMemo để optimize rendering. Consider splitting settings into smaller chunks.
localStorage corruption hoặc unavailable	Thấp	Thấp	Graceful fallback to default tab, không affect core functionality.

6. Implementation Details

6.1. Component API & Props Interface

interface SettingsPageProps {
  defaultTab?: 'content' | 'privacy' | 'notifications';
  onSettingsChange?: (settings: SettingsData) => void;
  className?: string;
}

interface SettingsData {
  content: ContentSettings;
  privacy: PrivacySettings;
  notifications: NotificationSettings;
}

interface ContentSettings {
  desktop_notifications: boolean;
  browser_notifications: boolean;
  interactions: InteractionSettings;
  in_app_notifications: InteractionSettings;
}

interface InteractionSettings {
  likes: boolean;
  comments: boolean;
  new_followers: boolean;
  mentions: boolean;
  tags: boolean;
}

6.2. Constants & Configuration

export const SETTINGS_CONFIG = {
  STORAGE_KEY: 'prima-brok-settings-active-tab',
  DEFAULT_TAB: 'content',
  AUTO_SAVE_DELAY: 2000,
  TABS: [
    { id: 'content', label: 'Nội dung', icon: FaListAlt },
    { id: 'privacy', label: 'Quyền riêng tư', icon: FaUserSecret },
    { id: 'notifications', label: 'Thông báo', icon: FaBell }
  ]
};

6.3. Custom Hooks

// Hook quản lý auto-save logic
const useAutoSave = (settingsData, updateMutation) => {
  const [pendingChanges, setPendingChanges] = useState({});

  const debouncedSave = useCallback(
    debounce((changes) => {
      updateMutation.mutate(changes);
      setPendingChanges({});
    }, SETTINGS_CONFIG.AUTO_SAVE_DELAY),
    [updateMutation]
  );

  return { pendingChanges, setPendingChanges, debouncedSave };
};

7. Testing Strategy

7.1. Unit Tests

• ✅ Tab switching functionality và localStorage persistence
• ✅ Auto-save debouncing behavior
• ✅ Toggle switch state management
• ✅ Form validation cho sensitive operations
• ✅ Error handling cho API failures

7.2. Integration Tests

• ✅ Settings synchronization với backend
• ✅ 2FA setup và disable flow
• ✅ Password change functionality
• ✅ Session management operations
• ✅ Cross-tab settings sync

7.3. E2E Tests

describe('Settings Page', () => {
  it('should auto-save desktop notification toggle', () => {
    cy.visit('/dashboard/settings');
    cy.get('[data-testid="desktop-notifications-toggle"]').click();
    cy.wait(2500); // Wait for debounce
    cy.get('[data-testid="save-success-toast"]').should('be.visible');
  });

  it('should remember selected tab after reload', () => {
    cy.visit('/dashboard/settings');
    cy.get('[data-testid="privacy-tab"]').click();
    cy.reload();
    cy.get('[data-testid="privacy-tab"]').should('have.class', 'active');
  });
});

8. Performance Considerations

8.1. Optimization Strategies

• Code Splitting:

const ContentSettings = lazy(() => import('./ContentSettings'));
const PrivacySettings = lazy(() => import('./PrivacySettings'));
const NotificationSettings = lazy(() => import('./NotificationSettings'));

• Memoization: React.memo cho components, useMemo cho expensive calculations
• Optimistic Updates: UI updates immediately, rollback on API failure

8.2. Bundle Size Impact

Component	Estimated Size	Loading Strategy
ContentSettings	~12KB	Lazy loaded
PrivacySettings	~18KB	Lazy loaded
NotificationSettings	~10KB	Lazy loaded
2FA Modal	~8KB	On-demand

Tài liệu tham khảo:

• Prima Brok API Documentation
• React Query Documentation
• Web Accessibility Guidelines
• Jira Epic: DASH-SETTINGS