docs: update README with project scope and architecture

This commit is contained in:
parsa committed 2026-05-26 11:40:39 +03:30
1 parent c95c9e5ce0
commit 29ba592366
1 file changed
+129 -45
+129 -45
View File
@@ -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.
**تهیه شده با رویکرد پزشکی و رعایت اصل تناسب و پاکیزگی دیزاین.** ❤️
**کیفیت ممتاز آلمانی، دسترسی آسان ایرانی.**