diff --git a/README.md b/README.md index ff624158..d816bbed 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,133 @@ -# Canina Iran | کانینا ایران 🐾 +# پلتفرم کانی‌نا ایران (Canina Iran Platform) 🐾 +### لندینگ، فروشگاه تخصصی و پرونده سلامت الکترونیک پت (نمایندگی رسمی دارویی Canina Pharma) -پلتفرم تخصصی مکمل‌های فوق‌دارویی حیوانات خانگی (نمایندگی انحصاری Canina pharma GmbH آلمان). - -## 🌟 قابلیت‌های کلیدی (Key Features) - -- **Smart Advisor (مشاور هوشمند)**: سیستم تحلیل بالینی مبتنی بر وضعیت سلامت، نژاد و سن پت برای پیشنهاد دقیق مکمل. -- **Digital Health ID (شناسنامه سلامت)**: مدیریت کامل سوابق درمانی، یادآورها و موجودی انبار شخصی برای هر حیوان. -- **Kindness Footprint (ردپای مهربانی)**: سیستم خیریه یکپارچه برای حمایت از حیوانات بی‌سرپرست پناهگاهی با هر خرید. -- **PWA Support**: قابلیت نصب بر روی موبایل و پشتیبانی از حالت آفلاین برای مشاهده شناسنامه‌ها. -- **B2B Portal**: پورتال اختصاصی برای داروخانه‌ها و کلینیک‌های دامپزشکی. - -## 🛠 تکنولوژی‌ها (Tech Stack) - -- **Frontend**: React 18, Vite, TypeScript -- **Styling**: Tailwind CSS (Medical Design System) -- **State Management**: Zustand -- **Animations**: Framer Motion -- **Icons**: Lucide React -- **Notifications**: Sonner - -## 🚀 نصب و اجرا (Installation) - -۱. شبیه‌سازی مخزن: - ```bash - git clone - ``` - -۲. نصب وابستگی‌ها: - ```bash - npm install - ``` - -۳. اجرای پروژه در محیط توسعه: - ```bash - npm run dev - ``` - -## 📐 معماری پروژه (Architecture) - -پروژه از معماری **Component-Based** با جداسازی لایه‌های داده (Services) و مدیریت وضعیت (Stores) استفاده می‌کند: -- `src/services/productService.ts`: مدیریت دریافت و فیلترینگ هوشمند محصولات. -- `src/store/usePetStore.ts`: مدیریت متمرکز پروفایل‌ها و محاسبات سلامت پت. -- `src/components/SmartAdvisor.tsx`: موتور تحلیل بالینی کاربرمحور. +پلتفرم **کانی‌نا ایران** یک برنامه جامع تحت وب (SPA/PWA) مجهز به بردهای تعاملی و ابزارهای بهداشتی-دامپزشکی است که با هدف ارتقای سلامت حیوانات خانگی و دسترسی آسان‌تر به مکمل‌های دارویی گرید فوق‌ارگانیک و دارویی کمپانی والای **Canina pharma GmbH آلمان** توسعه یافته است. --- -**توسعه یافته با عشق برای حیوانات ایران** ❤️ -**Canina Pharma Laboratory - Proudly German Quality** +## 🌟 ساختار نماها و صفحات پلتفرم (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: } + ``` +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. + +**تهیه شده با رویکرد پزشکی و رعایت اصل تناسب و پاکیزگی دیزاین.** ❤️ +**کیفیت ممتاز آلمانی، دسترسی آسان ایرانی.**