feat: add TourProgressController and related entities for user tour progress tracking

- Implemented TourProgressController to handle API endpoints for tracking guided tours seen by users.
- Created UserTourProgress entity to store the highest version of tours seen by each user.
- Developed UserTourProgressRepository for database interactions related to user tour progress.
- Introduced TourProgressService to manage business logic for marking tours as seen and retrieving seen maps.
- Added comprehensive tests for API endpoints and entity behavior to ensure functionality and data integrity.

assets/admin/components/ui/PageHeader.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { Link } from 'react-router';
 import { ChevronLeftIcon } from '@heroicons/react/24/outline';
 import BackButton from './BackButton';
+import TourButton from './TourButton';
 
 interface Crumb {
   label: string;
@@ -18,9 +19,11 @@ interface Props {
    * مقدار، مقصدِ fallback است وقتی تاریخچه‌ای برای برگشتن نیست.
    */
   backTo?: string;
+  /** شناسهٔ تور راهنمای این صفحه؛ اگر در registry ثبت نشده باشد دکمه‌ای نمی‌آید. */
+  tourId?: string;
 }
 
-export default function PageHeader({ title, breadcrumbs, action, description, backTo }: Props) {
+export default function PageHeader({ title, breadcrumbs, action, description, backTo, tourId }: Props) {
   return (
     <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16, marginBottom: 24 }}>
       <div style={{ minWidth: 0 }}>
@@ -48,7 +51,10 @@ export default function PageHeader({ title, breadcrumbs, action, description, ba
             ))}
           </nav>
         )}
-        <h1 className="section-title">{title}</h1>
+        <div style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+          <h1 className="section-title">{title}</h1>
+          <TourButton tourId={tourId} />
+        </div>
         {description && (
           <p style={{ fontSize: 13, color: 'var(--text-3)', marginTop: 4 }}>{description}</p>
         )}

assets/admin/components/ui/TourButton.test.tsx

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { renderWithProviders } from '@/test/utils';
+
+vi.mock('@/lib/api', () => ({
+    api: { get: vi.fn(), post: vi.fn(), patch: vi.fn(), put: vi.fn(), delete: vi.fn() },
+    ApiError: class extends Error {},
+}));
+
+const drive = vi.fn();
+vi.mock('driver.js', () => ({ driver: vi.fn(() => ({ drive })) }));
+vi.mock('driver.js/dist/driver.css', () => ({}));
+
+import { api } from '@/lib/api';
+import TourButton from './TourButton';
+import PageHeader from './PageHeader';
+import { appointmentsTour } from '@/lib/tour/tours/appointments';
+
+const get = api.get as ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+    get.mockReset();
+    get.mockResolvedValue({ data: { seen: {} } });
+    drive.mockReset();
+    document.body.innerHTML = '';
+});
+
+describe('TourButton', () => {
+    it('برای تور ثبت‌شده دکمهٔ راهنما می‌آورد', () => {
+        renderWithProviders(<TourButton tourId="appointments" />);
+
+        expect(screen.getByRole('button', { name: 'راهنمای این صفحه' })).toBeInTheDocument();
+    });
+
+    it('برای شناسهٔ ناشناس یا بدون شناسه چیزی رندر نمی‌کند', () => {
+        const { container } = renderWithProviders(<TourButton tourId="does-not-exist" />);
+        expect(container).toBeEmptyDOMElement();
+
+        const { container: bare } = renderWithProviders(<TourButton />);
+        expect(bare).toBeEmptyDOMElement();
+    });
+
+    it('کلیک، تور را روی المان‌های موجود اجرا می‌کند', async () => {
+        const user = userEvent.setup();
+        renderWithProviders(
+            <>
+                <TourButton tourId="appointments" />
+                {appointmentsTour.steps.map((s) => (
+                    <div key={s.anchor} data-tour={s.anchor} />
+                ))}
+            </>,
+        );
+
+        await user.click(screen.getByRole('button', { name: 'راهنمای این صفحه' }));
+
+        expect(drive).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('PageHeader', () => {
+    it('با tourId دکمهٔ راهنما را کنار عنوان می‌گذارد', () => {
+        renderWithProviders(<PageHeader title="نوبت‌ها" tourId="appointments" />);
+
+        expect(screen.getByRole('heading', { name: 'نوبت‌ها' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'راهنمای این صفحه' })).toBeInTheDocument();
+    });
+
+    it('بدون tourId هیچ دکمهٔ راهنمایی ندارد', () => {
+        renderWithProviders(<PageHeader title="نوبت‌ها" />);
+
+        expect(screen.queryByRole('button', { name: 'راهنمای این صفحه' })).toBeNull();
+    });
+
+    it('صفحهٔ بدون تور هیچ درخواستی برای وضعیت تورها نمی‌فرستد', () => {
+        renderWithProviders(<PageHeader title="نوبت‌ها" />);
+
+        expect(get).not.toHaveBeenCalled();
+    });
+});

assets/admin/components/ui/TourButton.tsx

@@ -0,0 +1,41 @@
+import { QuestionMarkCircleIcon } from '@heroicons/react/24/outline';
+import { useTour } from '../../hooks/useTour';
+import { getTour } from '../../lib/tour/registry';
+
+/**
+ * دکمهٔ «راهنمای این صفحه».
+ *
+ * وجود تور قبل از هر هوکی بررسی می‌شود تا صفحه‌ای که راهنما ندارد — یعنی بیشتر
+ * صفحات پنل — هیچ درخواستی برای وضعیت تورها نفرستد.
+ */
+export default function TourButton({ tourId }: { tourId?: string }) {
+  const tour = getTour(tourId);
+
+  if (!tour) return null;
+
+  return <TourLauncher tourId={tour.id} />;
+}
+
+/** اجرای خودکار وظیفهٔ خود صفحه است؛ این دکمه فقط دستی اجرا می‌کند. */
+function TourLauncher({ tourId }: { tourId: string }) {
+  const { start } = useTour(tourId);
+
+  return (
+    <button
+      type="button"
+      aria-label="راهنمای این صفحه"
+      title="راهنمای این صفحه"
+      onClick={start}
+      style={{
+        display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
+        width: 30, height: 30, borderRadius: 'var(--r-pill)',
+        background: 'transparent', border: 'none', cursor: 'pointer',
+        color: 'var(--text-3)', flexShrink: 0,
+      }}
+      onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--primary)')}
+      onMouseLeave={(e) => (e.currentTarget.style.color = 'var(--text-3)')}
+    >
+      <QuestionMarkCircleIcon style={{ width: 20, height: 20 }} />
+    </button>
+  );
+}