# پلتفرم کنینا ایران (Canina Iran Platform) 🐾
### لندینگ، فروشگاه تخصصی و پرونده سلامت الکترونیک پت (نمایندگی رسمی دارویی Canina Pharma)

پلتفرم **کنینا ایران** یک برنامه جامع تحت وب (SPA/PWA) مجهز به بردهای تعاملی و ابزارهای بهداشتی-دامپزشکی است که با هدف ارتقای سلامت حیوانات خانگی و دسترسی آسان‌تر به مکمل‌های دارویی گرید فوق‌ارگانیک و دارویی کمپانی والای **Canina pharma GmbH آلمان** توسعه یافته است.

---

## 🌟 ساختار نماها و صفحات پلتفرم (App Views & Architecture)
رویکرد ناوبری در این پلتفرم از معماری پیشپویا بر پایه‌ی بارگذاری تنبل (Lazy Loading) با استفاده از `Suspense` بهره می‌برد که سرعت بارگذاری اولیه، کارایی انیمیشن‌ها و صرفه‌جویی شدید در ترافیک کلاینت را تضمین می‌کند.

### ۱. صفحه اصلی (Home View)
*   **هدف**: لندینگ پیج اصلی برای معرفی هویت برند، مزیت‌های رقابتی محصولات آلمانی و دسترسی سریع به بخش‌های اصلی.
*   **کامپوننت‌های به کار رفته**:
    *   `Header`: منوی ناوبری بالایی با پشتیبانی از مگا منوی پیشرفته راه‌کارهای بالینی (Clinical Solutions MegaMenu) و نمایه جستجوی آنی.
    *   `Hero`: بخش معرفی اول پلتفرم همراه با تصویر باکیفیت آزمایشگاه و دکمه‌های فراخوان به اقدام (CTA) تداعی‌گر حس درمان استاندارد.
    *   `SmartAdvisor`: موتور مشاور بالینی آنلاین که فرم مرحله‌ای با الگوریتم غربالگری نژاد و علائم را پیاده‌سازی می‌کند.
    *   `FeaturedProducts`: بخش نمایش پرفروش‌ترین‌ها با هماهنگی و همگام‌سازی استیشن خرید کلاینت.
    *   `VetGallery`: گالری دامپزشکان متخصص همکار جهت ارزیابی بالینی و افزایش اعتبار اجتماعی برند.
    *   `Footer`: بخش انتهایی هماهنگ شامل خبرنامه، اطلاعات نمایندگی انحصاری، و میانبرهای پورتال همکاران (B2B).

### ۲. فروشگاه تخصصی و آرشیو محصولات (Shop / Archive View)
*   **هدف**: جستجو، فیلترینگ چندبعدی، و انتخاب مکمل‌ها بر اساس انواع علائم، نژادها و دسته‌بندی‌های پزشکی.
*   **کامپوننت‌های به کار رفته**:
    *   `ArchivePage`: هدایت‌کننده اصلی فیلترهای استاتیک و آدرس‌دهی هوشمند بر اساس URL (Synchronized URL Query Params).
    *   `ArchiveProductCard`: کارت تخصصی کالا مجهز به سیستم نمایش میزان ارزیابی و تطبیق (Compatibility Engine) با شرایط بهداشتی حیوان شما (Dynamic Species Badge).
    *   `NetworkBanner`: پنل نمایش پهنای باند و وضعیت ارتباط آفلاین محصول.

### ۳. صفحه جزئیات محصول (Product Details View)
*   **هدف**: صفحه معرفی فوق‌تخصصی هر کالا شامل جزئیات ساختار شیمیایی، جدول دوز مصرفی محاسباتی برای پت، و نقل‌قول از متخصصان آلمانی.
*   **کامپوننت‌های به کار رفته**:
    *   `ProductPage`: صفحه اصلی اطلاعات به همراه سیستم هوشمند محاسبه دوز تجویز (Dosage Calculator) که وزن پت را گرفته و دوز متناسب بر حسب میلی‌لیتر یا قرص در روز را فورا محاسبه می‌کند.
    *   `IngredientWiki`: ارجاع علمی ترکیبات موجود در محصول به دانشنامه مراجع برای شفافیت صددرصد فرآیند دارویی.

### ۴. پرونده و شناسنامه سلامت دیجیتال پت (Pet Profile / Digital Health ID)
*   **هدف**: تعریف پروفایل دیجیتال برای حیوان خانگی، ردیابی یادآورهای دارویی با همگام‌سازی انبار شخصی مکمل (Personal Stock Tracking).
*   **کامپوننت‌های به کار رفته**:
    *   `PetProfile`: مرکز نمایش اطلاعات هویتی و سلامت حیوان.
    *   `ReminderSection`: ابزار زمان‌بندی مصرف داروها. با تایید به مصرف رسیدن دارو، به صورت خودکار از حجم موجودی مکمل شما در خانه کم شده و هشدار اتمام شارژ مجدد به کاربر صادر می‌گردد.
    *   `HealthLogSection`: ثبت یادداشت‌های وضعیت بالینی روزانه برای اشتراک آسان سوابق با دامپزشک.

### ۵. داشبورد و پروفایل کاربر (User Dashboard View)
*   **هدف**: مدیریت سفارشات، فاکتورها، تراکنش‌های مالی و شارژ کیف پول مجازی.
*   **کامپوننت‌های به کار رفته**:
    *   `UserDashboard`: بورد اصلی شامل سایدبار اطلاعات هویتی و مدیریت آدرس‌ها.
    *   `TopUpModal`: مودال پیشرفته جهت افزایش اعتبار حساب کلاینت به صورت شبیه‌سازی شده.
    *   `AddressModal`: فرم اعتبارسنجی شده آدرس‌ها به سبک مپ‌آدرس‌های مدرن.

### ۶. پورتال پزشکان و همکاران B2B (B2B Partner Portal)
*   **هدف**: بخش ورود اختصاصی داروخانه‌ها، پت‌شاپ‌ها و کلینیک‌های همکار سراسر کشور جهت دریافت تخفیف‌های تیراژ بالا و پیگیری پروفرمای خرید.
*   **کامپوننت‌های به کار رفته**:
    *   `B2BPortal`: رابط کاربری پیشرفته مجهز به فرم‌های سفت‌وسخت مالی جهت ثبت فاکتورهای رسمی همکاران.

---

## 🏗️ ساختار دایرکتوری‌ها و درخت پروژۀ (Project Directory Tree)

```text
├── public/                 # دارایی‌های استاتیک و فایل‌های بومی‌سازی i18n
│   └── locales/
│       └── fa/
│           └── common.json # بانک متن خطاهای سرور و پیام‌های سیستم
│
├── src/
│   ├── assets/             # تصاویر، گرافیک‌های پرفرمنس و فایل بگراند
│   ├── components/         # تمامی کامپوننت‌های ماژولار و مستقل سیستم
│   │   ├── Header.tsx      # منوی اصلی و مگا منو هماهنگ با Slugها
│   │   ├── ArchivePage.tsx # فیلترها و سیستم ریست پارامترها
│   │   ├── SmartAdvisor.tsx# فرم مرحله‌ای و منطق توصیه‌گر هوشمند
│   │   └── ...
│   │
│   ├── data/
│   │   └── products.ts     # دیتابیس کالاها با تخصیص تگ‌های علمی (categorySlug)
│   │
│   ├── store/              # مدیریت متمرکز حالت مستقل (Global Stores via Zustand)
│   │   ├── cartStore.ts    # ذخیره سفارش‌ها، کدهای تخفیف و اهدای خیریه به پناهگاه‌ها
│   │   ├── userStore.ts    # ذخیره اطلاعات کاربر، کیف پول و تراکنش‌ها
│   │   └── usePetStore.ts  # ذخیره یادآورها، گزارشات بالینی و مشخصات پت‌ها
│   │
│   ├── services/
│   │   └── productService.ts # کپسول‌سازی فیلترینگ و شبیه‌سازی تاخیرهای اینترنت
│   │
│   ├── App.tsx             # ناوبری روتر کلاینت و تدارک Lazy Load با Suspense
│   ├── main.tsx            # نقطه اتصال اصلی React به DOM
│   └── index.css           # پیکربندی استایل‌ها با Tailwind CSS
│
├── swagger.yml             # مستندات OpenAPI 3.0 برای توسعه فرانت و بک‌بند
├── BACKEND_INTEGRATION.md  # نقشه راه و آدرس‌های خط اتصال بک‌بند (TODO integration)
├── package.json            # اسکریپت‌ها و وابستگی‌های پروژه
└── README.md               # فراداده و راهنمای در دسترس کلاینت
```

---

## 🛠️ راهنمای جامع توسعه و نگهداری (Development & Maintenance Guide)

### ۱. افزودن یک راهکار درمانی یا دسته‌بندی جدید (How to Add a Category Study)
اگر نیاز به افزودن دسته‌بندی محصولی جدید یا راه‌کارهای درمانی متناظر دارید:
1. ابتدا به `src/data/products.ts` رفته و محصولات مورد نظر را تعریف کنید. اطمینان حاصل کنید که خصوصیت `category` (به لٹریچر فارسی دقیق) و `categorySlug` (به انگلیسی معتبر و تک کلمه‌ای) تنظیم گشته است:
   ```typescript
   category: "مراقبت‌های قلبی و تنفسی",
   categorySlug: "cardio"
   ```
2. به آرایه `CATEGORIES` در `src/components/ArchivePage.tsx` رفته و آيتم متناظر را ثبات بخشید:
   ```typescript
   { id: "cardio", label: "مراقبت قلب و ریه", icon: <Heart className="w-4 h-4" /> }
   ```
3. همچنین نقشه همخوانی `CATEGORY_MAP` را برای تفکیک راهکارهای فرزند متصل به مگا منو گسترش دهید.

### ۲. اتصال پروژه به بک‌بند فیزیکی (API Connectivity Strategy)
بستر برای اتصال این پلتفرم به هر سرور بک‌بند به صورت کاممت‌های فنی با ساختار زیر استانداردسازی شده است:
```typescript
// TODO: [BACKEND_API] {METHOD} {ENDPOINT_PATH} | Payload: {...} | Expected: {...} | Errors: [400, 401, ...]
```
شما می‌توانید با جستجو در کل گام‌های پروژه (`grep` کلمه `TODO`) سریعاً نقاط فلت و سرویس‌ها را یافته و با پیاده‌سازی متدهای `fetch` یا `axios` کدهای موقت فروشگاه و استورهای Zustand را به پایگاه داده زنده (نظیر Node.js، Django یا Laravel) متصل کنید. مستند مفصل Swagger نیز در فایل `swagger.yml` برای همگام‌سازی سریع ساختارهای تیم بک‌بند آماده است.

### ۳. توسعه پرونده سلامت (Enhancing Digital ID Features)
پرونده‌های سلامت و سوابق در زمان واقعی توسط فروشگاه Zustand در `src/store/usePetStore.ts` به کمک لایه‌گذاری محلی (LocalStorage) تا ابد ذخیره و ماندگار می‌شوند. برای گسترش یادآورها و اتصال سیستم‌های هشدار پیامکی (SMS Gateways):
*   متد `toggleReminder` را مشاهده کرده و وب‌سرویس فرستنده پیامک حاوی یادآوری دوره‌ای دارو را در بدنه شرط `success` الحاق کنید.

### ۴. زبان‌های چندگانه و خطاها (i18n & Error Localization)
تمام پیام‌های مربوط به ارورهای پرداختی، عدم موجودی، ناسازگاری نژاد پت و خطا در کدهای تخفیف با کلیدهای استاندارد در فولدری مجزا مقیم هستند:
*   مسیر فایل: `/public/locales/fa/common.json`
*   در هنگام ایجاد هر کلس فیلتر یا خطای سفارشی خط اتصال وب، پیام مورد نظر را به شکل متقابل در فایل فوق ثبات دهید تا هشدارهای کلاینت تماماً فارسی و تعاملی نمایش یابند.

---

### اسکرپت‌های حیاتی (Vital Scripts)
*   `npm run dev` : بورد توسعه لوکال را روی پورت تعریف شده راه‌اندازی می‌کند.
*   `npm run build` : تولید خروجی توزیع بهینه (SPA Static files) در فولدر `dist/`.
*   `npm run lint` : اجرای الگوهای کیفی و بررسی صحت تایپ‌های TypeScript.

**تهیه شده با رویکرد پزشکی و رعایت اصل تناسب و پاکیزگی دیزاین.** ❤️
**کیفیت ممتاز آلمانی، دسترسی آسان ایرانی.**
# CI/CD test
# CI/CD test