docs(audit): generate frontend integration requirements based on new API contracts
Deploy Canina / deploy (push) Failing after 28s

This commit is contained in:
parsa committed 2026-08-06 23:49:27 +03:30
1 parent 1ae4c99ffc
commit 8dc2b1e586
1 file changed
+486
@@ -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 <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;
}
```