parsa/canina
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8d1b786a24
canina/docs/audit/FRONTEND_INTEGRATION_REQUIREMENTS.md
parsa aghaei 8d1b786a24
All checks were successful
Deploy Canina / deploy (push) Successful in 1m50s
Details
chore(brand): rename all Persian occurrences of کانینا to کنینا across the project
2026-08-16 16:40:08 +03:30

15 KiB
Raw Blame History

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): 
      [
  {
    "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: 
      {
  "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: 
      [
  { "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): 
      [
  {
    "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: 
      {
  "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): 
      [
  {
    "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): 
      [
  {
    "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): 
      {
  "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): 
      {
  "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): 
      {
  "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): 
      {
  "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: 
      {
  "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: 
      {
  "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: 
      {
  "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: 
      {
  "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:

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;
}