docs: update backend integration documentation
Expand documentation with comprehensive API protocols, authentication standards, and structured error responses.
This commit is contained in:
parent
03d100905f
commit
b4bf57f000
@ -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 <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;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
*این سند فاکتور تحویل نهایی بخش توسعه فرانتاند به تیم بکبند جهت هماهنگی معماری میکروسرویس تلقی میگردد.*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user