diff --git a/docs/audit/FRONTEND_INTEGRATION_REQUIREMENTS.md b/docs/audit/FRONTEND_INTEGRATION_REQUIREMENTS.md new file mode 100644 index 00000000..6dfe1a40 --- /dev/null +++ b/docs/audit/FRONTEND_INTEGRATION_REQUIREMENTS.md @@ -0,0 +1,486 @@ +# 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 `. +- **Admin Endpoints**: Require `Authorization: Bearer ` 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` +- **`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; +} +```