پلتفرم کنینا ایران (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)

├── 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 (به انگلیسی معتبر و تک کلمه‌ای) تنظیم گشته است:

   category: "مراقبت‌های قلبی و تنفسی",
   categorySlug: "cardio"
   

2. به آرایه CATEGORIES در src/components/ArchivePage.tsx رفته و آيتم متناظر را ثبات بخشید:

   { id: "cardio", label: "مراقبت قلب و ریه", icon: <Heart className="w-4 h-4" /> }
   

3. همچنین نقشه همخوانی CATEGORY_MAP را برای تفکیک راهکارهای فرزند متصل به مگا منو گسترش دهید.

۲. اتصال پروژه به بک‌بند فیزیکی (API Connectivity Strategy)

بستر برای اتصال این پلتفرم به هر سرور بک‌بند به صورت کاممت‌های فنی با ساختار زیر استانداردسازی شده است:

// 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