Keep a single README and remove extra markdown docs
EOF Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Shayan Azadi
584
API_DOCS_FA.md
584
API_DOCS_FA.md
@@ -1,584 +0,0 @@
|
|||||||
<div dir="rtl" lang="fa">
|
|
||||||
|
|
||||||
# مستندات API (Zoneco ORG)
|
|
||||||
|
|
||||||
این سند نحوهٔ کارکرد APIهای بکاند پروژه Zoneco ORG را به زبان فارسی توضیح میدهد.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## وضعیت تستها
|
|
||||||
|
|
||||||
```
|
|
||||||
Ran 31 tests — OK (0 failures)
|
|
||||||
```
|
|
||||||
|
|
||||||
| تعداد تست | گروه |
|
|
||||||
|-----------|------|
|
|
||||||
| ۷ تست | Admin Login |
|
|
||||||
| ۶ تست | Contact Us |
|
|
||||||
| ۱۱ تست | Compositions |
|
|
||||||
| ۷ تست | Campaigns |
|
|
||||||
|
|
||||||
اجرای تستها:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
python manage.py test api -v 2
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## اطلاعات پایه
|
|
||||||
|
|
||||||
| مقدار | مورد |
|
|
||||||
|--------|------|
|
|
||||||
| `{{base_url}}` | آدرس پایه |
|
|
||||||
| `/api/` | پیشوند API |
|
|
||||||
| JSON | فرمت پاسخ |
|
|
||||||
| ۲۰ آیتم در هر صفحه | صفحهبندی |
|
|
||||||
| `/admin/` | پنل ادمین |
|
|
||||||
|
|
||||||
### متغیر Postman
|
|
||||||
|
|
||||||
در فایل Postman از متغیر `{{base_url}}` استفاده شده است.
|
|
||||||
مقدار آن را مطابق محیط اجرا (لوکال، سرور تست یا پروداکشن) تنظیم کنید.
|
|
||||||
|
|
||||||
**نمونهٔ آدرس کامل یک endpoint:**
|
|
||||||
|
|
||||||
```
|
|
||||||
{{base_url}}/api/contact-us/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## سطح دسترسی
|
|
||||||
|
|
||||||
| دسترسی | عملیات |
|
|
||||||
|--------|--------|
|
|
||||||
| عمومی — بدون نیاز به ورود | لیست و جزئیات (متد `GET`) |
|
|
||||||
| عمومی — بدون نیاز به ورود | ایجاد (متد `POST`) |
|
|
||||||
| فقط ادمین — نیاز به توکن | ویرایش و حذف (متدهای `PUT`، `PATCH`، `DELETE`) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ۰. ورود ادمین (Admin Login)
|
|
||||||
|
|
||||||
| مقدار | مورد |
|
|
||||||
|--------|------|
|
|
||||||
| `{{admin_username}}` از env (`ADMIN_USERNAME`) | نام کاربری |
|
|
||||||
| `{{admin_password}}` از env (`ADMIN_PASSWORD`) | رمز عبور |
|
|
||||||
| `{{base_url}}/admin/` | پنل جنگو ادمین |
|
|
||||||
| `POST {{base_url}}/api/admin/login/` | ورود از طریق API |
|
|
||||||
|
|
||||||
> نام کاربری و رمز در کد هاردکد نمیشوند. روی سرور در فایل `.env` تنظیم کنید.
|
|
||||||
|
|
||||||
### ورود و دریافت توکن
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/admin/login/
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"username": "{{admin_username}}",
|
|
||||||
"password": "{{admin_password}}"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**پاسخ نمونه:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"token": "<token>",
|
|
||||||
"user": {
|
|
||||||
"id": 1,
|
|
||||||
"username": "<admin_username>",
|
|
||||||
"is_staff": true,
|
|
||||||
"is_superuser": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
در درخواستهای محافظتشده این هدر را بفرستید:
|
|
||||||
|
|
||||||
```
|
|
||||||
Authorization: Token <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
### اطلاعات ادمین فعلی
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/admin/me/
|
|
||||||
Authorization: Token <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
### خروج (حذف توکن)
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/admin/logout/
|
|
||||||
Authorization: Token <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
برای درخواستهای ادمین در Postman، ابتدا login کنید، سپس توکن را در متغیر `admin_token` بگذارید.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ۱. تماس با ما (Contact Us)
|
|
||||||
|
|
||||||
**مسیر پایه:**
|
|
||||||
|
|
||||||
```
|
|
||||||
/api/contact-us/
|
|
||||||
```
|
|
||||||
|
|
||||||
### فیلدها
|
|
||||||
|
|
||||||
| توضیح | الزامی | نوع | فیلد |
|
|
||||||
|-------|--------|-----|------|
|
|
||||||
| نام و نام خانوادگی | بله | string | `name` |
|
|
||||||
| ایمیل یا شماره تماس | بله | string | `email_or_phone` |
|
|
||||||
| متن پیام | بله | string | `description` |
|
|
||||||
| دستهبندی | بله | string | `category` |
|
|
||||||
|
|
||||||
**مقادیر مجاز برای `category`:**
|
|
||||||
|
|
||||||
- همکاری
|
|
||||||
- فروش
|
|
||||||
- پشتیبانی
|
|
||||||
- درخواست مشاور
|
|
||||||
- سایر
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت لیست تماسها
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/contact-us/
|
|
||||||
```
|
|
||||||
|
|
||||||
**پاسخ نمونه:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"count": 1,
|
|
||||||
"next": null,
|
|
||||||
"previous": null,
|
|
||||||
"results": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"name": "احمد محمدی",
|
|
||||||
"email_or_phone": "ahmad@example.com",
|
|
||||||
"description": "سلام، سوالی دارم.",
|
|
||||||
"category": "پشتیبانی",
|
|
||||||
"created_at": "2025-12-17T12:00:00Z",
|
|
||||||
"updated_at": "2025-12-17T12:00:00Z"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت یک تماس
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/contact-us/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ثبت تماس جدید
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/contact-us/
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
**بدنه درخواست:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "احمد محمدی",
|
|
||||||
"email_or_phone": "09121234567",
|
|
||||||
"description": "میخواهم در مورد محصولات اطلاعات بگیرم.",
|
|
||||||
"category": "فروش"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**کد پاسخ:** `201 Created`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### فیلتر بر اساس دستهبندی
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/contact-us/by_category/?category=پشتیبانی
|
|
||||||
```
|
|
||||||
|
|
||||||
| توضیح | الزامی | پارامتر |
|
|
||||||
|-------|--------|---------|
|
|
||||||
| یکی از دستههای مجاز | بله | `category` |
|
|
||||||
|
|
||||||
اگر پارامتر `category` ارسال نشود، خطای `400` برمیگردد.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ویرایش و حذف (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
PUT {{base_url}}/api/contact-us/{id}/
|
|
||||||
PATCH {{base_url}}/api/contact-us/{id}/
|
|
||||||
DELETE {{base_url}}/api/contact-us/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
نیاز به احراز هویت ادمین دارد.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ۲. ترکیبات (Compositions)
|
|
||||||
|
|
||||||
**مسیر پایه:**
|
|
||||||
|
|
||||||
```
|
|
||||||
/api/compositions/
|
|
||||||
```
|
|
||||||
|
|
||||||
هر ترکیب میتواند **چند تصویر** داشته باشد.
|
|
||||||
یکی از تصاویر با فیلد `is_main: true` بهعنوان **تصویر اصلی** مشخص میشود.
|
|
||||||
|
|
||||||
### فیلدها
|
|
||||||
|
|
||||||
| توضیح | الزامی | نوع | فیلد |
|
|
||||||
|-------|--------|-----|------|
|
|
||||||
| نام ترکیب | بله | string | `name` |
|
|
||||||
| توضیحات | بله | string | `description` |
|
|
||||||
| یک یا چند فایل تصویر (فقط در ایجاد/ویرایش) | خیر | file[] | `uploaded_images` |
|
|
||||||
| ایندکس تصویر اصلی (شمارش از ۰) | خیر | integer | `main_image_index` |
|
|
||||||
|
|
||||||
### محدودیت تصاویر
|
|
||||||
|
|
||||||
- فرمتهای مجاز: JPEG، PNG، WebP، GIF
|
|
||||||
- حداکثر حجم هر فایل: **۵ مگابایت**
|
|
||||||
- مسیر ذخیره: `media/compositions/`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت لیست ترکیبات
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/compositions/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت یک ترکیب
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/compositions/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
**پاسخ نمونه:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"name": "ترکیب A",
|
|
||||||
"description": "توضیحات ترکیب",
|
|
||||||
"image": null,
|
|
||||||
"image_url": null,
|
|
||||||
"images": [
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"image": "/media/compositions/img2.jpg",
|
|
||||||
"image_url": "{{base_url}}/media/compositions/img2.jpg",
|
|
||||||
"is_main": true,
|
|
||||||
"created_at": "2025-12-17T12:00:00Z"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"image": "/media/compositions/img1.jpg",
|
|
||||||
"image_url": "{{base_url}}/media/compositions/img1.jpg",
|
|
||||||
"is_main": false,
|
|
||||||
"created_at": "2025-12-17T11:00:00Z"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"main_image": {
|
|
||||||
"id": 2,
|
|
||||||
"image_url": "{{base_url}}/media/compositions/img2.jpg",
|
|
||||||
"is_main": true,
|
|
||||||
"created_at": "2025-12-17T12:00:00Z"
|
|
||||||
},
|
|
||||||
"created_at": "2025-12-17T10:00:00Z",
|
|
||||||
"updated_at": "2025-12-17T12:00:00Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### فیلتر بر اساس تاریخ ایجاد
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/compositions/by-created-at/?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z
|
|
||||||
```
|
|
||||||
|
|
||||||
| توضیح | الزامی | پارامتر |
|
|
||||||
|-------|--------|---------|
|
|
||||||
| برگشت ترکیبهایی که `created_at >= from` | حداقل یکی | `from` |
|
|
||||||
| برگشت ترکیبهایی که `created_at <= to` | حداقل یکی | `to` |
|
|
||||||
|
|
||||||
فرمت تاریخ: ISO 8601 — مثال: `2026-06-01T00:00:00Z`
|
|
||||||
|
|
||||||
اگر هیچ پارامتری ارسال نشود، خطای `400` برمیگردد.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ایجاد ترکیب (بدون تصویر)
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/compositions/
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "ترکیب تست",
|
|
||||||
"description": "توضیحات ترکیب"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ایجاد ترکیب با چند تصویر
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/compositions/
|
|
||||||
Content-Type: multipart/form-data
|
|
||||||
```
|
|
||||||
|
|
||||||
| مقدار نمونه | نوع | فیلد |
|
|
||||||
|-------------|-----|------|
|
|
||||||
| ترکیب A | text | `name` |
|
|
||||||
| توضیحات | text | `description` |
|
|
||||||
| image1.jpg | file | `uploaded_images` |
|
|
||||||
| image2.jpg | file | `uploaded_images` |
|
|
||||||
| 1 | text | `main_image_index` |
|
|
||||||
|
|
||||||
**نکته:** فیلد `uploaded_images` را برای هر تصویر یکبار تکرار کنید.
|
|
||||||
|
|
||||||
**نکته:** اگر `main_image_index` ارسال نشود، **اولین تصویر** بهعنوان تصویر اصلی انتخاب میشود.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### افزودن تصویر به ترکیب موجود (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/compositions/{id}/add-images/
|
|
||||||
Content-Type: multipart/form-data
|
|
||||||
```
|
|
||||||
|
|
||||||
| نوع | فیلد |
|
|
||||||
|-----|------|
|
|
||||||
| file (یک یا چند فایل) | `uploaded_images` |
|
|
||||||
| text (اختیاری) | `main_image_index` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### تنظیم تصویر اصلی (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/compositions/{id}/set-main-image/
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"image_id": 3
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### حذف یک تصویر (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
DELETE {{base_url}}/api/compositions/{id}/images/{image_id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
**کد پاسخ:** `204 No Content`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ویرایش و حذف ترکیب (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
PUT {{base_url}}/api/compositions/{id}/
|
|
||||||
PATCH {{base_url}}/api/compositions/{id}/
|
|
||||||
DELETE {{base_url}}/api/compositions/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ۳. کمپینها (Campaigns)
|
|
||||||
|
|
||||||
**مسیر پایه:**
|
|
||||||
|
|
||||||
```
|
|
||||||
/api/campaigns/
|
|
||||||
```
|
|
||||||
|
|
||||||
### فیلدها
|
|
||||||
|
|
||||||
| توضیح | الزامی | نوع | فیلد |
|
|
||||||
|-------|--------|-----|------|
|
|
||||||
| نام کمپین | بله | string | `name` |
|
|
||||||
| توضیحات | بله | string | `description` |
|
|
||||||
| زمان شروع (ISO 8601) | بله | datetime | `start_time` |
|
|
||||||
| زمان پایان (باید بعد از `start_time` باشد) | بله | datetime | `end_time` |
|
|
||||||
| تصویر کمپین | خیر | file | `image` |
|
|
||||||
|
|
||||||
### فیلدهای محاسباتی (فقط خواندنی)
|
|
||||||
|
|
||||||
| توضیح | فیلد |
|
|
||||||
|-------|------|
|
|
||||||
| آیا کمپین الان فعال است | `is_active` |
|
|
||||||
| آیا کمپین هنوز شروع نشده | `is_upcoming` |
|
|
||||||
| آیا کمپین تمام شده | `is_ended` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت لیست کمپینها
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/campaigns/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### دریافت یک کمپین
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/campaigns/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ایجاد کمپین
|
|
||||||
|
|
||||||
```
|
|
||||||
POST {{base_url}}/api/campaigns/
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "کمپین نوروز",
|
|
||||||
"description": "تخفیف ویژه نوروز",
|
|
||||||
"start_time": "2026-03-01T00:00:00Z",
|
|
||||||
"end_time": "2026-03-31T23:59:59Z"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### کمپینهای فعال
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/campaigns/active/
|
|
||||||
```
|
|
||||||
|
|
||||||
کمپینهایی که زمان فعلی بین `start_time` و `end_time` قرار دارد.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### کمپینهای آینده
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/campaigns/upcoming/
|
|
||||||
```
|
|
||||||
|
|
||||||
کمپینهایی که هنوز شروع نشدهاند.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### کمپینهای پایانیافته
|
|
||||||
|
|
||||||
```
|
|
||||||
GET {{base_url}}/api/campaigns/ended/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### ویرایش و حذف (ادمین)
|
|
||||||
|
|
||||||
```
|
|
||||||
PUT {{base_url}}/api/campaigns/{id}/
|
|
||||||
PATCH {{base_url}}/api/campaigns/{id}/
|
|
||||||
DELETE {{base_url}}/api/campaigns/{id}/
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## کدهای وضعیت HTTP
|
|
||||||
|
|
||||||
| معنی | کد |
|
|
||||||
|------|-----|
|
|
||||||
| موفق | `200` |
|
|
||||||
| ایجاد شد | `201` |
|
|
||||||
| حذف شد (بدون بدنه) | `204` |
|
|
||||||
| داده نامعتبر | `400` |
|
|
||||||
| دسترسی ندارید | `403` |
|
|
||||||
| یافت نشد | `404` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## فایل Postman
|
|
||||||
|
|
||||||
مجموعه Postman در مسیر زیر قرار دارد:
|
|
||||||
|
|
||||||
```
|
|
||||||
backend/Zoneco_ORG_API.postman_collection.json
|
|
||||||
```
|
|
||||||
|
|
||||||
### نحوه import
|
|
||||||
|
|
||||||
1. Postman را باز کنید
|
|
||||||
2. گزینه **Import** را بزنید
|
|
||||||
3. فایل `Zoneco_ORG_API.postman_collection.json` را انتخاب کنید
|
|
||||||
4. متغیر `{{base_url}}` را مطابق محیط خود تنظیم کنید
|
|
||||||
5. برای درخواستهای ادمین، در تب **Authorization** گزینه **Basic Auth** را فعال کنید
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## خلاصه endpointها
|
|
||||||
|
|
||||||
| دسترسی | Endpoint | Method | # |
|
|
||||||
|--------|----------|--------|---|
|
|
||||||
| عمومی | `/api/admin/login/` | POST | 1 |
|
|
||||||
| ادمین | `/api/admin/logout/` | POST | 2 |
|
|
||||||
| ادمین | `/api/admin/me/` | GET | 3 |
|
|
||||||
| عمومی | `/api/contact-us/` | GET | 4 |
|
|
||||||
| عمومی | `/api/contact-us/` | POST | 5 |
|
|
||||||
| عمومی | `/api/contact-us/{id}/` | GET | 6 |
|
|
||||||
| عمومی | `/api/contact-us/by_category/?category=...` | GET | 7 |
|
|
||||||
| ادمین | `/api/contact-us/{id}/` | PUT/PATCH/DELETE | 8 |
|
|
||||||
| عمومی | `/api/compositions/` | GET | 9 |
|
|
||||||
| عمومی | `/api/compositions/` | POST | 10 |
|
|
||||||
| عمومی | `/api/compositions/{id}/` | GET | 11 |
|
|
||||||
| عمومی | `/api/compositions/by-created-at/?from=...&to=...` | GET | 12 |
|
|
||||||
| ادمین | `/api/compositions/{id}/add-images/` | POST | 13 |
|
|
||||||
| ادمین | `/api/compositions/{id}/set-main-image/` | POST | 14 |
|
|
||||||
| ادمین | `/api/compositions/{id}/images/{image_id}/` | DELETE | 15 |
|
|
||||||
| ادمین | `/api/compositions/{id}/` | PUT/PATCH/DELETE | 16 |
|
|
||||||
| عمومی | `/api/campaigns/` | GET | 17 |
|
|
||||||
| عمومی | `/api/campaigns/` | POST | 18 |
|
|
||||||
| عمومی | `/api/campaigns/{id}/` | GET | 19 |
|
|
||||||
| عمومی | `/api/campaigns/active/` | GET | 20 |
|
|
||||||
| عمومی | `/api/campaigns/upcoming/` | GET | 21 |
|
|
||||||
| عمومی | `/api/campaigns/ended/` | GET | 22 |
|
|
||||||
| ادمین | `/api/campaigns/{id}/` | PUT/PATCH/DELETE | 23 |
|
|
||||||
|
|
||||||
> **توجه:** در Postman قبل از هر مسیر، مقدار `{{base_url}}` را قرار دهید.
|
|
||||||
> مثال: `{{base_url}}/api/campaigns/active/`
|
|
||||||
|
|
||||||
</div>
|
|
||||||
221
DOCKER_README.md
221
DOCKER_README.md
@@ -1,221 +0,0 @@
|
|||||||
# Docker Setup for Zoneco ORG Backend
|
|
||||||
|
|
||||||
This document provides instructions for running the Zoneco ORG backend using Docker and Docker Compose.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
- Docker Engine 20.10 or higher
|
|
||||||
- Docker Compose 2.0 or higher
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
1. **Navigate to the backend directory:**
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Create a `.env` file** (copy from the template below):
|
|
||||||
```bash
|
|
||||||
# Copy and modify as needed
|
|
||||||
SECRET_KEY=your-secret-key-here-change-in-production
|
|
||||||
DEBUG=False
|
|
||||||
ALLOWED_HOSTS=localhost,127.0.0.1,YOUR_SERVER_IP
|
|
||||||
POSTGRES_DB=Zoneco_ORG
|
|
||||||
POSTGRES_USER=postgres
|
|
||||||
POSTGRES_PASSWORD=change-me
|
|
||||||
POSTGRES_HOST=db
|
|
||||||
POSTGRES_PORT=5432
|
|
||||||
DJANGO_PORT=8000
|
|
||||||
ADMIN_USERNAME=your-admin-username
|
|
||||||
ADMIN_PASSWORD=your-admin-password
|
|
||||||
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000,http://YOUR_SERVER_IP:9123
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Build and start the containers:**
|
|
||||||
```bash
|
|
||||||
docker-compose up --build
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **The application will be available at:**
|
|
||||||
- API: `http://localhost:8000/api/`
|
|
||||||
- Admin: `http://localhost:8000/admin/`
|
|
||||||
|
|
||||||
## Docker Commands
|
|
||||||
|
|
||||||
### Start services
|
|
||||||
```bash
|
|
||||||
docker-compose up
|
|
||||||
```
|
|
||||||
|
|
||||||
### Start services in detached mode
|
|
||||||
```bash
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
### Stop services
|
|
||||||
```bash
|
|
||||||
docker-compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
### Stop services and remove volumes (⚠️ deletes database data)
|
|
||||||
```bash
|
|
||||||
docker-compose down -v
|
|
||||||
```
|
|
||||||
|
|
||||||
### View logs
|
|
||||||
```bash
|
|
||||||
docker-compose logs -f
|
|
||||||
```
|
|
||||||
|
|
||||||
### View logs for specific service
|
|
||||||
```bash
|
|
||||||
docker-compose logs -f web
|
|
||||||
docker-compose logs -f db
|
|
||||||
```
|
|
||||||
|
|
||||||
### Rebuild containers
|
|
||||||
```bash
|
|
||||||
docker-compose build --no-cache
|
|
||||||
```
|
|
||||||
|
|
||||||
### Execute commands in running container
|
|
||||||
```bash
|
|
||||||
# Django shell
|
|
||||||
docker-compose exec web python manage.py shell
|
|
||||||
|
|
||||||
# Create superuser
|
|
||||||
docker-compose exec web python manage.py createsuperuser
|
|
||||||
|
|
||||||
# Run migrations manually
|
|
||||||
docker-compose exec web python manage.py migrate
|
|
||||||
|
|
||||||
# Collect static files
|
|
||||||
docker-compose exec web python manage.py collectstatic --noinput
|
|
||||||
```
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
The Docker setup consists of:
|
|
||||||
|
|
||||||
1. **Web Service** (`web`):
|
|
||||||
- Django application running with Gunicorn
|
|
||||||
- Multi-stage Dockerfile for optimized image size
|
|
||||||
- Non-root user for security
|
|
||||||
- Automatic migrations and static file collection on startup
|
|
||||||
- Health checks enabled
|
|
||||||
|
|
||||||
2. **Database Service** (`db`):
|
|
||||||
- PostgreSQL 15 Alpine (lightweight)
|
|
||||||
- Persistent data volume
|
|
||||||
- Health checks to ensure readiness
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
### Security Best Practices
|
|
||||||
- ✅ Multi-stage build for smaller image size
|
|
||||||
- ✅ Non-root user execution
|
|
||||||
- ✅ Environment variable configuration
|
|
||||||
- ✅ No hardcoded secrets
|
|
||||||
- ✅ Health checks for both services
|
|
||||||
|
|
||||||
### Production Ready
|
|
||||||
- ✅ Gunicorn WSGI server
|
|
||||||
- ✅ Automatic database migrations
|
|
||||||
- ✅ Static file collection
|
|
||||||
- ✅ Database connection retry logic
|
|
||||||
- ✅ Proper logging
|
|
||||||
|
|
||||||
### Development Friendly
|
|
||||||
- ✅ Volume mounts for media and static files
|
|
||||||
- ✅ Hot-reload capability (with proper setup)
|
|
||||||
- ✅ Easy access to Django management commands
|
|
||||||
|
|
||||||
## Environment Variables
|
|
||||||
|
|
||||||
| Variable | Description | Default |
|
|
||||||
|----------|-------------|---------|
|
|
||||||
| `SECRET_KEY` | Django secret key | (required in production) |
|
|
||||||
| `DEBUG` | Enable debug mode | `False` |
|
|
||||||
| `ALLOWED_HOSTS` | Comma-separated allowed hosts | `localhost,127.0.0.1` |
|
|
||||||
| `POSTGRES_DB` | Database name | `Zoneco_ORG` |
|
|
||||||
| `POSTGRES_USER` | Database user | `postgres` |
|
|
||||||
| `POSTGRES_PASSWORD` | Database password | `postgres` |
|
|
||||||
| `POSTGRES_HOST` | Database host | `db` |
|
|
||||||
| `POSTGRES_PORT` | Database port | `5432` |
|
|
||||||
| `DJANGO_PORT` | Django application port | `8000` |
|
|
||||||
| `CORS_ALLOWED_ORIGINS` | Comma-separated CORS origins | (see .env.example) |
|
|
||||||
|
|
||||||
## Volumes
|
|
||||||
|
|
||||||
- `postgres_data`: Persistent PostgreSQL data
|
|
||||||
- `./media`: Media files (images, uploads)
|
|
||||||
- `./staticfiles`: Collected static files
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### Database connection errors
|
|
||||||
```bash
|
|
||||||
# Check if database is healthy
|
|
||||||
docker-compose ps
|
|
||||||
|
|
||||||
# Check database logs
|
|
||||||
docker-compose logs db
|
|
||||||
|
|
||||||
# Restart services
|
|
||||||
docker-compose restart
|
|
||||||
```
|
|
||||||
|
|
||||||
### Permission issues
|
|
||||||
```bash
|
|
||||||
# Fix media/staticfiles permissions
|
|
||||||
sudo chown -R $USER:$USER media staticfiles
|
|
||||||
```
|
|
||||||
|
|
||||||
### Port already in use
|
|
||||||
```bash
|
|
||||||
# Change port in .env file
|
|
||||||
DJANGO_PORT=8001
|
|
||||||
# Then update docker-compose.yml or restart
|
|
||||||
```
|
|
||||||
|
|
||||||
### Clear everything and start fresh
|
|
||||||
```bash
|
|
||||||
docker-compose down -v
|
|
||||||
docker-compose build --no-cache
|
|
||||||
docker-compose up
|
|
||||||
```
|
|
||||||
|
|
||||||
## Production Deployment
|
|
||||||
|
|
||||||
For production deployment:
|
|
||||||
|
|
||||||
1. **Set strong SECRET_KEY:**
|
|
||||||
```bash
|
|
||||||
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Set DEBUG=False** in `.env`
|
|
||||||
|
|
||||||
3. **Configure proper ALLOWED_HOSTS**
|
|
||||||
|
|
||||||
4. **Use strong database passwords**
|
|
||||||
|
|
||||||
5. **Consider using:**
|
|
||||||
- Reverse proxy (nginx)
|
|
||||||
- SSL/TLS certificates
|
|
||||||
- Separate database server
|
|
||||||
- Backup strategy
|
|
||||||
- Monitoring and logging
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
backend/
|
|
||||||
├── Dockerfile # Multi-stage production Dockerfile
|
|
||||||
├── docker-compose.yml # Service orchestration
|
|
||||||
├── .dockerignore # Files to exclude from build
|
|
||||||
├── entrypoint.sh # Startup script
|
|
||||||
├── requirements.txt # Python dependencies
|
|
||||||
└── DOCKER_README.md # This file
|
|
||||||
```
|
|
||||||
|
|
||||||
10
README.md
10
README.md
@@ -299,15 +299,9 @@ DB constraint: only one `is_main=True` per composition.
|
|||||||
|
|
||||||
## Postman Collection
|
## Postman Collection
|
||||||
|
|
||||||
Import `backend/Zoneco_ORG_API.postman_collection.json` into Postman.
|
Import `Zoneco_ORG_API.postman_collection.json` into Postman.
|
||||||
|
|
||||||
Set the `base_url` collection variable to your server address.
|
Set collection variables: `base_url`, `admin_username`, `admin_password`.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Persian Documentation
|
|
||||||
|
|
||||||
Full Persian API documentation: `backend/API_DOCS_FA.md`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user