407 lines
15 KiB
Markdown
407 lines
15 KiB
Markdown
# نقشه جامع اتصال به بکبند (Comprehensive Backend Integration Map) 🏗️
|
|
|
|
این سند حاوی معماری دقیق، فهرست کامل نقاط اتصال (API Endpoints)، کامنتهای مکاننما در کد (TODO Markers)، و تعاریف رسمی تمامی تایپهای ورودی (Inputs) و خروجی (Outputs) پلتفرم درمانی و فروشگاهی کنینا ایران است.
|
|
|
|
---
|
|
|
|
## ۱. اصول عمومی و ساختار تبادل داده (General Protocols)
|
|
|
|
- **Base URL:** تمام درخواستها به روت اصلی آدرس ریلیتیو `/api` یا آدرس دامین اصلی متصل میشوند.
|
|
- **Content-Type:** کلیه ورودیها و خروجیها در قالب `application/json` با استاندارد انکودینگ UTF-8 تبادل میشوند.
|
|
- **Authentication:** احراز هویت با استفاده از استاندارد JWT انجام میشود. پس از دریافت توکن در زمان ورود، باید هدر زیر در سایر درخواستها الصاق شود:
|
|
```http
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
- **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<AddPetRequest>`
|
|
- **تایپ خروجی:** `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<PetProfile, "id">) => {
|
|
try {
|
|
const token = localStorage.getItem("auth_token");
|
|
const response = await axios.post<PetProfile>("/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;
|
|
}
|
|
};
|
|
```
|
|
|
|
*این سند فاکتور تحویل نهایی بخش توسعه فرانتاند به تیم بکبند جهت هماهنگی معماری میکروسرویس تلقی میگردد.*
|