487 lines
15 KiB
Markdown
487 lines
15 KiB
Markdown
# 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;
|
||
}
|
||
```
|