136 lines
13 KiB
Markdown
136 lines
13 KiB
Markdown
# پلتفرم کنینا ایران (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
|