# Comprehensive Frontend Integration Requirements & API Contract

- **Author**: Lead Full-Stack System Architect
- **Version**: 1.0.0
- **Status**: Production Specification
- **Target Applications**: Next.js Storefront App & React Admin SPA
- **Base Backend Path**: `/api`

---

## Executive Summary & Authentication Protocols

This document defines the strict integration contract between the NestJS backend and the two frontend applications (Next.js SSR/SEO Storefront and React SPA Admin Panel).

### Authentication Headers
- **Public Endpoints**: Require no authentication header.
- **User Authenticated Endpoints**: Require `Authorization: Bearer <accessToken>`.
- **Admin Endpoints**: Require `Authorization: Bearer <accessToken>` where user role is `Admin`.

---

## Domain Specifications

### 1. Banners & Hero Sliders

#### Backend Endpoint Specifications
- **`GET /api/banners`**
  - **Auth**: Public
  - **Response (200 OK)**:
    ```json
    [
      {
        "id": "uuid-string",
        "title": "تخصص دارویی از آلمان",
        "subtitle": "بیش از ۴۰ سال تجربه",
        "imageUrl": "https://example.com/banner.jpg",
        "linkUrl": "/products/joints",
        "position": "home_hero",
        "isActive": true,
        "order": 0,
        "createdAt": "2026-08-06T20:00:00.000Z",
        "updatedAt": "2026-08-06T20:00:00.000Z"
      }
    ]
    ```
- **`POST /api/banners`**
  - **Auth**: Admin
  - **Request Body**:
    ```json
    {
      "title": "عنوان بنر",
      "subtitle": "زیرعنوان اختیاری",
      "imageUrl": "https://example.com/banner.jpg",
      "linkUrl": "/products/joints",
      "position": "home_hero",
      "isActive": true,
      "order": 1
    }
    ```
- **`PUT /api/banners/reorder`**
  - **Auth**: Admin
  - **Request Body**:
    ```json
    [
      { "id": "uuid-1", "order": 0 },
      { "id": "uuid-2", "order": 1 }
    ]
    ```
- **`PATCH /api/banners/:id`**
  - **Auth**: Admin
  - **Request Body**: `Partial<BannerInput>`
- **`DELETE /api/banners/:id`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **Banners Management Table** (`/admin/banners`).
- Form Modal fields: `title` (text, required), `subtitle` (text), `imageUrl` (file uploader / URL string, required), `linkUrl` (text), `position` (select: `home_hero`, `category_top`, `sidebar`), `isActive` (toggle switch), `order` (number).
- Implement Drag-and-Drop table rows triggering `PUT /api/banners/reorder`.

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/Hero.tsx` and `HomeClient.tsx` to fetch `GET /api/banners`.
- Filter response by `position === 'home_hero'` and `isActive === true`.

---

### 2. Smart Advisor Rules Engine

#### Backend Endpoint Specifications
- **`GET /api/smart-advisor/rules`**
  - **Auth**: Public
  - **Response (200 OK)**:
    ```json
    [
      {
        "id": "rule-uuid",
        "condition": "مشکلات مفصلی و لنگش",
        "targetPetType": "سگ",
        "recommendedProduct": "product-uuid",
        "reason": "حاوی ۱۰٪ پودر صدف لب‌سبز برای بازسازی غضروف",
        "createdAt": "2026-08-06T20:00:00.000Z",
        "product": {
          "id": "product-uuid",
          "nameFa": "کنهیدروکس GAG",
          "slug": "canhydrox-gag"
        }
      }
    ]
    ```
- **`POST /api/smart-advisor/rules`**
  - **Auth**: Admin
  - **Request Body**:
    ```json
    {
      "condition": "مشکلات گوارشی",
      "targetPetType": "گربه",
      "recommendedProduct": "product-uuid",
      "reason": "پروبیوتیک حاوی باکتری انتروکوکوس فسیوم"
    }
    ```
- **`PATCH /api/smart-advisor/rules/:id`** & **`DELETE /api/smart-advisor/rules/:id`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **Smart Advisor Rules Manager** (`/admin/smart-advisor`).
- Form fields: `condition` (text), `targetPetType` (select: `سگ`, `گربه`, `هر دو`), `recommendedProduct` (searchable product dropdown), `reason` (textarea).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/SmartAdvisor.tsx` to query `GET /api/smart-advisor/rules`.
- Dynamically render recommendation cards based on user's pet selection.

---

### 3. Customer & Vet Testimonials

#### Backend Endpoint Specifications
- **`GET /api/testimonials`**
  - **Auth**: Public
  - **Response (200 OK)**:
    ```json
    [
      {
        "id": "testimonial-uuid",
        "authorName": "دکتر علیرضا محمدی",
        "roleTitle": "دامپزشک و متخصص جراحی",
        "avatarUrl": "https://example.com/avatar.jpg",
        "content": "فرمولاسیون کنهیدروکس کانینا در بهبودی پاهای O شکل سگ‌های نژاد بزرگ معجزه می‌کند.",
        "rating": 5,
        "isFeatured": true,
        "isActive": true,
        "order": 0
      }
    ]
    ```
- **`POST /api/testimonials`**, **`PATCH /api/testimonials/:id`**, **`DELETE /api/testimonials/:id`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **Testimonials Manager** (`/admin/testimonials`).
- Form fields: `authorName` (text, required), `roleTitle` (text), `avatarUrl` (image uploader), `content` (textarea, required), `rating` (rating selector 1-5), `isFeatured` (toggle), `isActive` (toggle).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/VetGallery.tsx` and homepage testimonial widgets to fetch `GET /api/testimonials`.

---

### 4. Ingredients & Scientific Wiki

#### Backend Endpoint Specifications
- **`GET /api/ingredients`**
  - **Auth**: Public
  - **Response (200 OK)**:
    ```json
    [
      {
        "id": "ingredient-uuid",
        "nameFa": "صدف لب‌سبز",
        "nameEn": "Green-Lipped Mussel",
        "slug": "green-lipped-mussel",
        "scientificName": "Perna canaliculus",
        "description": "صدف بومی نیوزیلند غنی از گلیکوزآمیپوگلیکان‌ها",
        "imageUrl": "https://example.com/mussel.png",
        "benefits": ["ترمیم غضروف", "کاهش التهاب مفاصل"]
      }
    ]
    ```
- **`GET /api/ingredients/:idOrSlug`**
  - **Auth**: Public
- **`POST /api/ingredients`**, **`PATCH /api/ingredients/:id`**, **`DELETE /api/ingredients/:id`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **Ingredients Encyclopedia Manager** (`/admin/ingredients`).
- Form fields: `nameFa` (text, required), `nameEn` (text, required), `slug` (text, unique), `scientificName` (text), `description` (rich text editor), `imageUrl` (uploader), `benefits` (tag input string array).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/IngredientWiki.tsx` to fetch `GET /api/ingredients` and `GET /api/ingredients/:idOrSlug`.

---

### 5. Product Dosage Configuration

#### Backend Endpoint Specifications
- **`GET /api/products/:id/dosage-config`**
  - **Auth**: Public
  - **Response (200 OK)**:
    ```json
    {
      "unit": "قرص",
      "baseWeightKg": 10,
      "baseDose": 1,
      "maxDailyDose": 4,
      "instructions": "همراه با غذا یا بلافاصله بعد از غذا مصرف شود"
    }
    ```
- **`PATCH /api/products/:id/dosage-config`**
  - **Auth**: Admin
  - **Request Body**: Json object with dosage formula parameters.

#### Admin Panel Action Items
- Inside **Product Edit Page** (`/admin/products/:id`), add a **Dosage Formula Builder Tab**.
- Fields: `unit` (text), `baseWeightKg` (number), `baseDose` (number), `maxDailyDose` (number), `instructions` (textarea).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/ProductPage.tsx` and dosage calculator widget to fetch `GET /api/products/:id/dosage-config` for interactive dosage calculation based on pet's exact weight.

---

### 6. SEO Settings

#### Backend Endpoint Specifications
- **`GET /api/settings/seo`**
  - **Auth**: Admin
  - **Response (200 OK)**:
    ```json
    {
      "defaultMetaTitle": "کانینا ایران | مکمل‌های دارویی آلمانی حیوانات خانگی",
      "defaultMetaDescription": "نمایندگی رسمی محصولات کانینا فارما آلمان",
      "keywords": "مکمل سگ, مکمل گربه, کنهیدروکس, کانینا",
      "canonicalBaseUrl": "https://caninairan.com",
      "ogImageUrl": "https://caninairan.com/og-default.jpg"
    }
    ```
- **`PATCH /api/settings/seo`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **SEO Global Settings Form** (`/admin/settings/seo`).
- Fields: `defaultMetaTitle`, `defaultMetaDescription`, `keywords`, `canonicalBaseUrl`, `ogImageUrl`.

#### Storefront (Next.js) Action Items
- Connect `app/layout.tsx` dynamic metadata generator to fetch default SEO settings.

---

### 7. Financial Settings

#### Backend Endpoint Specifications
- **`GET /api/settings/financial`**
  - **Auth**: Admin
  - **Response (200 OK)**:
    ```json
    {
      "taxPercentage": 10,
      "freeShippingThreshold": 2000000,
      "standardShippingFee": 85000,
      "charityDonationOptions": [10000, 20000, 50000]
    }
    ```
- **`PATCH /api/settings/financial`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **Financial & Shipping Settings Form** (`/admin/settings/financial`).
- Fields: `taxPercentage` (number), `freeShippingThreshold` (number), `standardShippingFee` (number), `charityDonationOptions` (number array).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/CheckoutPage.tsx` and `cartStore.ts` to compute shipping fees, free shipping progress bars, and charity options dynamically.

---

### 8. System Settings

#### Backend Endpoint Specifications
- **`GET /api/settings/system`**
  - **Auth**: Admin
  - **Response (200 OK)**:
    ```json
    {
      "maintenanceMode": false,
      "allowGuestCheckout": true,
      "b2bRegistrationOpen": true,
      "supportPhone": "021-12345678"
    }
    ```
- **`PATCH /api/settings/system`**
  - **Auth**: Admin

#### Admin Panel Action Items
- Create **System Control Panel** (`/admin/settings/system`).
- Fields: `maintenanceMode` (toggle), `allowGuestCheckout` (toggle), `b2bRegistrationOpen` (toggle), `supportPhone` (text).

#### Storefront (Next.js) Action Items
- Read `maintenanceMode` flag in Next.js middleware to render `MaintenancePage.tsx` when system maintenance is enabled.

---

### 9. Prescriptions Workflow

#### Backend Endpoint Specifications
- **`POST /api/prescriptions`**
  - **Auth**: User Authenticated
  - **Request Body**:
    ```json
    {
      "petId": "pet-uuid-optional",
      "fileUrl": "https://cdn.caninairan.com/prescriptions/rx-123.pdf",
      "notes": "نسخه مربوط به کلینیک دکتر رضایی"
    }
    ```
- **`GET /api/prescriptions`**
  - **Auth**: User / Admin
  - **Response**: List of prescriptions (scoped to user or all for Admin).
- **`GET /api/prescriptions/:id`**
  - **Auth**: User / Admin
- **`PATCH /api/prescriptions/:id/review`**
  - **Auth**: Admin
  - **Request Body**:
    ```json
    {
      "status": "APPROVED",
      "adminNotes": "نسخه تایید شد. دوز مصرفی مطابق دستور پزشک است."
    }
    ```

#### Admin Panel Action Items
- Create **Prescription Review Dashboard** (`/admin/prescriptions`).
- Features: Filter by `status` (`PENDING`, `APPROVED`, `REJECTED`), image/PDF viewer, status change toggle buttons with `adminNotes` comment input.

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/PrescriptionUploadModal.tsx` and `UserDashboard.tsx` to handle upload via `POST /api/prescriptions` and display prescription review badges.

---

### 10. B2B Wholesale Portal & Partner Credit

#### Backend Endpoint Specifications
- **`POST /api/b2b/inquiries`**
  - **Auth**: Public
  - **Request Body**:
    ```json
    {
      "companyName": "کلینیک دامپزشکی پارت",
      "contactName": "دکتر کامران سمیعی",
      "email": "info@partvet.com",
      "phone": "09121112233",
      "businessType": "clinic",
      "estimatedVolume": "۵۰ تا ۱۰۰ بسته در ماه",
      "message": "تقاضای دریافت لیست قیمت عمده و نمایندگی استان اصفهان"
    }
    ```
- **`GET /api/b2b/inquiries`** & **`PATCH /api/b2b/inquiries/:id`**
  - **Auth**: Admin
- **`GET /api/b2b/partner`**
  - **Auth**: User Authenticated (Partner)
  - **Response**: Partner account details, credit limits, discount tiers.
- **`POST /api/b2b/orders`**
  - **Auth**: User Authenticated (Partner)
  - **Request Body**:
    ```json
    {
      "items": [
        { "productId": "prod-1", "quantity": 50 }
      ],
      "totalAmount": 75000000
    }
    ```

#### Admin Panel Action Items
- Create **B2B Partner & Inquiry Management** (`/admin/b2b`).
- Inquiry review table with status toggles (`PENDING`, `CONTACTED`, `APPROVED`, `REJECTED`).
- Partner Account setup modal (assigning credit limits and discount tiers to user accounts).

#### Storefront (Next.js) Action Items
- Update `frontend/application/components/B2BPortal.tsx` to post inquiries to `POST /api/b2b/inquiries`.
- If logged in user has `User_Partner` role, render partner credit dashboard and wholesale order form using `GET /api/b2b/partner` and `POST /api/b2b/orders`.

---

## Shared TypeScript Interfaces for Frontend Codebases

Developers should paste the following definitions into `lib/types.ts` / `src/types/api.ts`:

```typescript
export interface Banner {
  id: string;
  title: string;
  subtitle?: string;
  imageUrl: string;
  linkUrl?: string;
  position: string;
  isActive: boolean;
  order: number;
  createdAt: string;
  updatedAt: string;
}

export interface SmartAdvisorRule {
  id: string;
  condition: string;
  targetPetType?: string;
  recommendedProduct: string;
  reason: string;
  createdAt: string;
  product?: {
    id: string;
    nameFa: string;
    slug: string;
  };
}

export interface Testimonial {
  id: string;
  authorName: string;
  roleTitle?: string;
  avatarUrl?: string;
  content: string;
  rating: number;
  isFeatured: boolean;
  isActive: boolean;
  order: number;
  createdAt: string;
  updatedAt: string;
}

export interface Ingredient {
  id: string;
  nameFa: string;
  nameEn: string;
  slug: string;
  description?: string;
  scientificName?: string;
  imageUrl?: string;
  benefits: string[];
  createdAt: string;
  updatedAt: string;
}

export interface Prescription {
  id: string;
  userId: string;
  petId?: string;
  fileUrl: string;
  status: 'PENDING' | 'APPROVED' | 'REJECTED';
  notes?: string;
  adminNotes?: string;
  createdAt: string;
  updatedAt: string;
}

export interface B2BInquiry {
  id: string;
  companyName: string;
  contactName: string;
  email: string;
  phone: string;
  businessType: string;
  estimatedVolume?: string;
  message: string;
  status: 'PENDING' | 'CONTACTED' | 'APPROVED' | 'REJECTED';
  adminNotes?: string;
  createdAt: string;
  updatedAt: string;
}

export interface PartnerAccount {
  id: string;
  userId: string;
  companyName: string;
  taxId?: string;
  creditLimit: string | number;
  discountTier: string;
  status: string;
  createdAt: string;
  updatedAt: string;
}
```