From b4bf57f000199a1c33806adac0ec5889a7a3c43d Mon Sep 17 00:00:00 2001 From: parsa aghayi Date: Tue, 26 May 2026 11:48:36 +0330 Subject: [PATCH] docs: update backend integration documentation Expand documentation with comprehensive API protocols, authentication standards, and structured error responses. --- BACKEND_INTEGRATION.md | 434 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 402 insertions(+), 32 deletions(-) diff --git a/BACKEND_INTEGRATION.md b/BACKEND_INTEGRATION.md index ff8ec32..cab5ed0 100644 --- a/BACKEND_INTEGRATION.md +++ b/BACKEND_INTEGRATION.md @@ -1,36 +1,406 @@ -# Backend Integration Map | نقشه اتصال به بک‌بند 🏗️ +# نقشه جامع اتصال به بک‌بند (Comprehensive Backend Integration Map) 🏗️ -این سند شامل تمامی نقاط اتصال (End-points) مورد نیاز برای عملیاتی کردن پلتفرم کانی‌نا ایران است. - -## لیست TODOهای تزریق شده در کد: - -### ۱. سرویس محصولات (Product Service) -- **GET /api/products**: دریافت لیست محصولات با فیلتر نژاد، دسته‌بندی و جستجو. - -### ۲. مدیریت کاربران (User Store) -- **POST /api/auth/login**: ورود با موبایل یا تفکیک نقش (صاحب پت/همکار). -- **POST /api/auth/logout**: خروج از حساب کاربری. -- **PATCH /api/user/profile**: بروزرسانی اطلاعات پروفایل. -- **POST /api/user/addresses**: ثبت آدرس جدید. -- **PATCH /api/user/addresses/{id}**: ویرایش آدرس موجود. -- **DELETE /api/user/addresses/{id}**: حذف آدرس. -- **POST /api/user/addresses/{id}/set-default**: انتخاب آدرس پیش‌فرض. -- **POST /api/user/wallet/top-up**: شارژ کیف پول. - -### ۳. پرونده سلامت پت (Pet Store) -- **POST /api/pets**: ثبت پت جدید (صدور شناسنامه). -- **PATCH /api/pets/{id}**: ویرایش اطلاعات پت. -- **DELETE /api/pets/{id}**: حذف پروفایل پت. -- **POST /api/pets/{petId}/reminders**: افزودن یادآور جدید. -- **POST /api/pets/{petId}/reminders/{reminderId}/toggle**: ثبت انجام یادآور (کاهش موجودی انبار شخصی). -- **POST /api/pets/{petId}/health-logs**: ثبت گزارش سلامت روزانه. - -### ۴. سبد خرید و پرداخت (Cart & Payment) -- **POST /api/cart/apply-coupon**: استعلام و اعمال کد تخفیف. -- **POST /api/orders**: ثبت نهایی سفارش و تولید کد رهگیری. -- **POST /api/payment/init**: اتصال به درگاه پرداخت بانکی. +این سند حاوی معماری دقیق، فهرست کامل نقاط اتصال (API Endpoints)، کامنت‌های مکان‌نما در کد (TODO Markers)، و تعاریف رسمی تمامی تایپ‌های ورودی (Inputs) و خروجی (Outputs) پلتفرم درمانی و فروشگاهی کانی‌نا ایران است. --- -## راهنمای پیاده‌سازی: -تمامی این نقاط در کد با کامنت `// TODO: [BACKEND_API]` مشخص شده‌اند. کافیست در هر بخش، منطق `set` یا `fetch` فعلی را با یک فراخوانی `axios` یا `fetch` جایگزین کنید. +## ۱. اصول عمومی و ساختار تبادل داده (General Protocols) + +- **Base URL:** تمام درخواست‌ها به روت اصلی آدرس ریلیتیو `/api` یا آدرس دامین اصلی متصل می‌شوند. +- **Content-Type:** کلیه ورودی‌ها و خروجی‌ها در قالب `application/json` با استاندارد انکودینگ UTF-8 تبادل می‌شوند. +- **Authentication:** احراز هویت با استفاده از استاندارد JWT انجام می‌شود. پس از دریافت توکن در زمان ورود، باید هدر زیر در سایر درخواست‌ها الصاق شود: + ```http + Authorization: Bearer + ``` +- **Error Structure:** ساختار برگشت‌گر خطاها در شرایط کدهای وضعیت (HTTP Status Codes) غیر ۲۰۰ باید به فرم زیر باشد: + ```json + { + "success": false, + "message": "کد تخفیف وارد شده منقضی شده است", + "code": "COUPON_EXPIRED", + "details": {} // اختیاری + } + ``` + +--- + +## ۲. مستندات جزء به جزء تایپ‌ها و نقاط اتصال (API Directory & Types) + +در زیر، تمام ۱۸ نقطه اتصال مشخص شده همراه با کارهایی که در فروشگاه‌های حالت (Zustand Stores) و کامپوننت‌های فرانت‌اند باید جایگزین منطق موالاتی کلاینت شوند آورده شده است: + +### ۲.۱. مدیریت احراز هویت و اطلاعات کاربر (Authentication & Profiling) + +موقعیت فایل‌ها: +- درون کامپوننت `src/components/AuthModal.tsx` دکمه ورود. +- درون استور حالت پرتابل `src/store/userStore.ts`. + +#### ۱. ورود کاربر به سیستم (User Login) +- **مسیر:** `POST /api/auth/login` +- **موقعیت در کد:** `src/components/AuthModal.tsx` +- **تایپ ورودی (Payload):** + ```typescript + interface LoginRequest { + role: "User_Guest" | "User_PetOwner" | "User_Partner"; + mobile?: string; + } + ``` +- **تایپ خروجی (Success Response):** + ```typescript + interface LoginResponse { + token: string; + user: { + firstName: string; + lastName: string; + email: string; + walletBalance: number; + charityDonationTotal: number; + addresses: Address[]; + transactions: Transaction[]; + }; + } + ``` +- **کدهای خطا:** `400 Bad Request` (فرمت موبایل نامعتبر)، `401 Unauthorized` (رد ورود). + +#### ۲. خروج از سیستم (User Logout) +- **مسیر:** `POST /api/auth/logout` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `logout`) +- **تایپ ورودی:** فاقد بدنه (استفاده از Bearer Token در هدر) +- **تایپ خروجی:** + ```typescript + interface LogoutResponse { + success: boolean; + } + ``` + +#### ۳. ویرایش و بروزرسانی اطلاعات پروفایل (Update Profile) +- **مسیر:** `PATCH /api/user/profile` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `updateProfile`) +- **تایپ ورودی:** + ```typescript + type UpdateProfileRequest = Partial<{ + firstName: string; + lastName: string; + email: string; + }>; + ``` +- **تایپ خروجی:** `UserProfile` (پروفایل با داده‌های جدید) + +#### ۴. ثبت آدرس جدید برای کاربر (Add New Address) +- **مسیر:** `POST /api/user/addresses` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `addAddress`) +- **تایپ ورودی:** + ```typescript + interface AddAddressRequest { + title: string; + receptorName: string; + phone: string; + province: string; + city: string; + detail: string; + zipCode: string; + isDefault: boolean; + } + ``` +- **تایپ خروجی:** + ```typescript + interface AddressResponse extends AddAddressRequest { + id: string; // شناسه یکتا تولید شده توسط دیتابیس + } + ``` + +#### ۵. ویرایش آدرس موجود (Update Address) +- **مسیر:** `PATCH /api/user/addresses/{id}` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `updateAddress`) +- **تایپ ورودی:** `Address` (شامل فیلد `id`) +- **تایپ خروجی:** `Address` (آدرس با آخرین تغییرات) + +#### ۶. حذف آدرس (Delete Address) +- **مسیر:** `DELETE /api/user/addresses/{id}` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `deleteAddress`) +- **تایپ ورودی:** پارامتر متغیر در آدرس URL +- **تایپ خروجی:** + ```typescript + interface DeleteAddressResponse { + success: boolean; + } + ``` + +#### ۷. انتخاب آدرس به عنوان پیش‌فرض (Set Address as Default) +- **مسیر:** `POST /api/user/addresses/{id}/set-default` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `setDefaultAddress`) +- **تایپ ورودی:** پارامتر متغیر در آدرس URL +- **تایپ خروجی:** + ```typescript + interface SetDefaultAddressResponse { + success: boolean; + } + ``` + +#### ۸. افزایش اعتبار و شارژ کیف پول (Wallet Top-Up) +- **مسیر:** `POST /api/user/wallet/top-up` +- **موقعیت در کد:** `src/store/userStore.ts` (متد `topUpWallet`) +- **تایپ ورودی:** + ```typescript + interface TopUpRequest { + amount: number; + } + ``` +- **تایپ خروجی:** + ```typescript + interface TopUpResponse { + transactionId: string; + newBalance: number; + } + ``` + +--- + +### ۲.۲. جستجو و پایگاه داده محصولات (Product Catalog) + +موقعیت فایل: `src/services/productService.ts`. + +#### ۹. دریافت کاتالوگ محصولات با فیلترینگ چندجانبه (Get Products) +- **مسیر:** `GET /api/products` +- **موقعیت در کد:** `src/services/productService.ts` (متد `fetchProducts`) +- **پارامترهای کوئری ورودی (Query params):** + ```typescript + interface ProductsQueryFilters { + category?: string; // مانند joints, immune, energy, special-care + petType?: string; // مقادیر: سگ, گربه, or all + query?: string; // کلمه کلیدی برای جستجو در متن درمان یا نام + } + ``` +- **تایپ خروجی (Success Response):** + ```typescript + interface Product { + id: string; + artNo: string; + name: string; + scientificTagline?: string; + description: string; + shortDescription: string; + keyBenefits: Array<{ icon: string; title: string; description: string }>; + category: string; + categorySlug?: string; + price: string; + priceValue: number; + unit: string; + packageSize: number; + main_ingredients: string[]; + dosage_logic?: string; + benefits: string | string[]; + symptoms: string[]; + suitableFor: "سگ" | "گربه" | "هر دو"; + calculateDosage?: (weight: number) => string; + image: string; + } + + type GetProductsResponse = Product[]; + ``` + +--- + +### ۲.۳. پرونده سلامت و شناسنامه سلامت پت (Pet Profile & Medical Records) + +موقعیت فایل: `src/store/usePetStore.ts`. + +#### ۱۰. ثبت و ایجاد شناسنامه دیجیتال برای پت جدید (Add Pet) +- **مسیر:** `POST /api/pets` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addPet`) +- **تایپ ورودی:** + ```typescript + interface AddPetRequest { + name: string; + type: "سگ" | "گربه"; + breed: string; + age: number; + weight: number; + activityLevel: "کم" | "متوسط" | "زیاد"; + medicalConditions: string[]; + image?: string; + } + ``` +- **تایپ خروجی:** + ```typescript + interface PetResponse extends AddPetRequest { + id: string; // شناسه تولید شده سمت سرور + reminders: Reminder[]; + logs: HealthLog[]; + consumptions: PetConsumption[]; + } + ``` + +#### ۱۱. حذف پرونده سلامت حیوان خانگی (Delete Pet) +- **مسیر:** `DELETE /api/pets/{id}` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `removePet`) +- **تایپ ورودی:** پارامتر متغیر در آدرس URL +- **تایپ خروجی:** + ```typescript + interface DeletePetResponse { + success: boolean; + } + ``` + +#### ۱۲. ویرایش اطلاعات بیومتریک پت (Update Pet Details) +- **مسیر:** `PATCH /api/pets/{id}` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `updatePet`) +- **تایپ ورودی:** `Partial` +- **تایپ خروجی:** `PetProfile` (مشخصات بروزرسانی شده) + +#### ۱۳. ثبت برنامه دارویی و یادآور جدید (Add Medicine Reminder) +- **مسیر:** `POST /api/pets/{petId}/reminders` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addReminder`) +- **تایپ ورودی:** + ```typescript + interface AddReminderRequest { + title: string; + time: string; + frequency: "روزانه" | "هفتگی"; + productId?: string; // آیدی مکمل بخصوص برای اتصال به انبار مصرفی + } + ``` +- **تایپ خروجی:** + ```typescript + interface ReminderResponse extends AddReminderRequest { + id: string; + completedDates: string[]; + } + ``` + +#### ۱۴. ثبت مصرف دوز یادآوری شده (تغییر وضعیت و همگام‌سازی انبار) (Toggle & Consume Reminder) +- **مسیر:** `POST /api/pets/{petId}/reminders/{reminderId}/toggle` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `toggleReminder`) +- **تایپ ورودی:** + ```typescript + interface ToggleReminderRequest { + date: string; // تاریخ روز به فرمت ISO (YYYY-MM-DD) + } + ``` +- **تایپ خروجی:** + ```typescript + interface ToggleReminderResponse { + success: boolean; + newRemaining?: number; // مقدار باقیمانده بسته پس از مصرف دوز (کم شده از پک پت) + } + ``` + +#### ۱۵. ثبت لاگ‌های ارزیابی وضعیت گوارش و انرژی پت (Add Daily Health Log) +- **مسیر:** `POST /api/pets/{petId}/health-logs` +- **موقعیت در کد:** `src/store/usePetStore.ts` (متد `addHealthLog`) +- **تایپ ورودی:** + ```typescript + interface AddHealthLogRequest { + appetite: "عالی" | "متوسط" | "کم"; + energy: "زیاد" | "نرمال" | "بی‌حال"; + digestion: "نرمال" | "حساس" | "مشکل‌دار"; + note?: string; + } + ``` +- **تایپ خروجی:** + ```typescript + interface HealthLogResponse extends AddHealthLogRequest { + id: string; + date: string; // تاریخ ثبت شده سمت سرور + } + ``` + +--- + +### ۲.۴. سبد خرید، کدهای آفر و خروجی فاکتور نهایی (Cart & Order Transactions) + +موقعیت فایل‌ها: +- درون استور حالت کاربری سبد `src/store/cartStore.ts`. +- درون کامپوننت پرداخت فیزیکی `src/components/CheckoutPage.tsx`. + +#### ۱۶. ارزیابی و بررسی اعتبار کوپن‌های آفر (Apply Discount Coupon) +- **مسیر:** `POST /api/cart/apply-coupon` +- **موقعیت در کد:** `src/store/cartStore.ts` (متد `applyCoupon`) +- **تایپ ورودی:** + ```typescript + interface ApplyCouponRequest { + code: string; + } + ``` +- **تایپ خروجی:** + ```typescript + interface ApplyCouponResponse { + discount: number; // قیمت آفر کاهش دهنده یا پله درصد (نسب کسر) + } + ``` +- **کدهای خطا:** `404 Not Found` (چنین کدی تعریف نشده)، `400 Bad Request` (منقضی یا نامعتبر). + +#### ۱۷. ثبت قطعی سفارش و ایجاد پیش‌فاکتور (Place Final Order) +- **مسیر:** `POST /api/orders` +- **موقعیت در کد:** `src/store/cartStore.ts` (متد `addOrder`) +- **تایپ ورودی:** + ```typescript + interface PlaceOrderRequest { + items: Array<{ + product: { id: string; name: string }; + quantity: number; + calculatedDose?: { quantity: number; unit: string }; + }>; + total: number; + charityDonation?: number; + petId?: string; + } + ``` +- **تایپ خروجی:** + ```typescript + interface OrderResponse extends PlaceOrderRequest { + id: string; + date: string; + status: "processing" | "shipped" | "delivered"; + trackingNumber: string; // کد رهگیری پستی ملی فیزیکی تولید شده + } + ``` + +#### ۱۸. آماده‌سازی توکن پرداخت شبکه بانکی زیتون/شتاب (Initialize Gateway) +- **مسیر:** `POST /api/payment/init` +- **موقعیت در کد:** `src/components/CheckoutPage.tsx` +- **تایپ ورودی:** + ```typescript + interface PaymentInitRequest { + method: string; // روش مانند "wallet" یا "online" + amount: number; // کل مبلغ قابل پرداخت به ریال یا تومان + } + ``` +- **تایپ خروجی:** + ```typescript + interface PaymentInitResponse { + gatewayUrl: string; // آدرس ریدایرکت کلاینت به درگاه شاپرک/شتاب بانکی + } + ``` + +--- + +## ۳. الگوی نمونه پیاده‌سازی متد اتصال (Zustand Axios Integration Blueprint) + +برای اتصال فرانت‌اند Zustand با دیتابیس زنده، توسعه‌دهندگان می‌توانند از الگوی زیر برای متدهای استور استفاده کنند. قبل از الصاق، حتما کتابخانه `axios` را نصب نمایید: + +```typescript +import axios from "axios"; + +// نمونه فراخوانی جهت ثبت پت جدید در فایل src/store/usePetStore.ts +const addPet = async (petData: Omit) => { + try { + const token = localStorage.getItem("auth_token"); + const response = await axios.post("/api/pets", petData, { + headers: { + Authorization: `Bearer ${token}` + } + }); + + // بروزرسانی استور محلی پس از موفقیت پاسخ بک‌بند + set((state) => ({ + pets: [...state.pets, response.data], + activePetId: response.data.id + })); + } catch (error) { + console.error("خطا در ایجاد شناسنامه پت روی سرور:", error); + throw error; + } +}; +``` + +*این سند فاکتور تحویل نهایی بخش توسعه فرانت‌اند به تیم بک‌بند جهت هماهنگی معماری میکروسرویس تلقی می‌گردد.*