docs: update README with project scope and architecture
This commit is contained in:
1 parent
c95c9e5ce0
commit
29ba592366
1 file changed
+129
-45
@@ -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 <repository-url>
|
||||
```
|
||||
|
||||
۲. نصب وابستگیها:
|
||||
```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: <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.
|
||||
|
||||
**تهیه شده با رویکرد پزشکی و رعایت اصل تناسب و پاکیزگی دیزاین.** ❤️
|
||||
**کیفیت ممتاز آلمانی، دسترسی آسان ایرانی.**
|
||||
Reference in new issue
Block a user