aramesh-backend/backend/README.md

# بک‌اند گروه ساختمانی آرامش (Aramesh Building Group API)

بک‌اند سایت گروه ساختمانی آرامش — ساخته‌شده با **FastAPI** + **PostgreSQL** + **SQLAlchemy 2** + **JWT** + **MinIO** (ذخیره تصاویر) + **Traefik** (مسیریابی).

## امکانات

- **API عمومی محتوا**: برند، منو، هیرو، داستان، تیتر بخش‌ها، هیرو صفحات، خدمات، پروژه‌ها، مقالات، نظرات مشتریان، سوالات متداول، تیم، تایم‌لاین، آمار، چرا آرامش، قبل/بعد، مدل‌های سرمایه‌گذاری، مراحل کار، دفاتر، گالری، فرم تماس، خبرنامه و فوتر — **تمام متن‌های سایت در دیتابیس است**
- **فرم تماس**: ثبت پیام مشتریان از سایت (`POST /api/contact`)
- **خبرنامه**: عضویت و مدیریت مشترکین (`POST /api/newsletter`)
- **پنل مدیریت**: ورود با نام کاربری/رمز عبور و دریافت توکن JWT، سپس CRUD کامل همه محتواها، مدیریت پیام‌های تماس و مشترکین
- **آپلود تصویر**: `POST /api/admin/upload` — فایل در MinIO ذخیره و URL نسبی `/media/...` برمی‌گردد
- **Seed خودکار**: همه محتوای فعلی سایت با یک دستور در دیتابیس قرار می‌گیرد (فقط جدول‌های خالی پر می‌شوند — ارتقا بدون از دست رفتن داده)
- مستندات تعاملی Swagger در مسیر `/docs`

## راه‌اندازی

### ۱. پیش‌نیازها

- Python 3.11 یا جدیدتر
- PostgreSQL در حال اجرا (پورت پیش‌فرض 5432)

### ۲. نصب وابستگی‌ها

```bash
cd arameshplaza-backend
python -m venv .venv

# ویندوز
.venv\Scripts\activate
# لینوکس / مک
source .venv/bin/activate

pip install -r requirements.txt
```

### ۳. تنظیمات

فایل `.env.example` را به نام `.env` کپی کنید و مقادیر را تنظیم کنید:

```bash
cp .env.example .env        # لینوکس / مک
copy .env.example .env      # ویندوز
```

مهم‌ترین تنظیم `DATABASE_URL` است:

```
DATABASE_URL=postgresql+psycopg://postgres:YOUR_PASSWORD@localhost:5432/arameshplaza_api
```

### ۴. ساخت دیتابیس و Seed

```bash
# ساخت دیتابیس (یک‌بار):
psql -U postgres -c "CREATE DATABASE arameshplaza_api;"

# ساخت جداول + وارد کردن محتوای سایت + ساخت ادمین پیش‌فرض:
python -m app.seed

# بازنشانی کامل داده‌ها در صورت نیاز:
python -m app.seed --force
```

### ۵. اجرا

```bash
uvicorn app.main:app --reload
```

سپس:
- مستندات API: http://localhost:8000/docs
- بررسی سلامت: http://localhost:8000/api/health

## ورود به پنل مدیریت

```
POST /api/auth/login
{ "username": "admin", "password": "aramesh123" }
```

پاسخ شامل `access_token` است. توکن را در هدر همه درخواست‌های مدیریتی قرار دهید:

```
Authorization: Bearer <access_token>
```

> نام کاربری و رمز عبور پیش‌فرض از تنظیمات `.env` خوانده می‌شود — حتماً در محیط تولید تغییرشان دهید.

## فهرست انتهاپوینت‌ها

### عمومی (بدون نیاز به توکن)

| متد | مسیر | توضیح |
|---|---|---|
| GET | `/api/health` | وضعیت سرور |
| GET | `/api/brand` | اطلاعات برند و تماس |
| GET | `/api/services` | خدمات |
| GET | `/api/projects` | همه پروژه‌ها |
| GET | `/api/projects/{slug}` | جزئیات یک پروژه |
| GET | `/api/articles` | همه مقالات |
| GET | `/api/articles/{slug}` | جزئیات یک مقاله |
| GET | `/api/testimonials` | نظرات مشتریان |
| GET | `/api/faqs` | سوالات متداول |
| GET | `/api/team` | اعضای تیم |
| GET | `/api/timeline` | تایم‌لاین شرکت |
| GET | `/api/stats` | آمار |
| GET | `/api/why-us` | چرا گروه ساختمانی آرامش |
| GET | `/api/before-after` | بخش قبل/بعد |
| GET | `/api/site` | **همه محتوا در یک درخواست** |
| POST | `/api/contact` | ثبت پیام تماس |
| POST | `/api/newsletter` | عضویت در خبرنامه |
| POST | `/api/auth/login` | ورود ادمین و دریافت توکن |

### مدیریت (نیاز به توکن Bearer)

برای هر یک از این مسیرها، CRUD کامل در دسترس است:
`brand`، `services`، `projects`، `articles`، `testimonials`، `faqs`، `team`، `timeline`، `stats`، `why-us`، `before-after`

| متد | مسیر | توضیح |
|---|---|---|
| GET/POST | `/api/admin/{resource}` | لیست / ساخت |
| GET/PUT/DELETE | `/api/admin/{resource}/{id}` | دریافت / ویرایش / حذف |
| GET | `/api/admin/messages` | پیام‌های تماس (با `?unread_only=true` فقط خوانده‌نشده‌ها) |
| PATCH | `/api/admin/messages/{id}` | تغییر وضعیت خوانده‌شدن |
| DELETE | `/api/admin/messages/{id}` | حذف پیام |
| GET | `/api/admin/subscribers` | مشترکین خبرنامه |
| DELETE | `/api/admin/subscribers/{id}` | حذف مشترک |
| POST | `/api/admin/upload` | آپلود تصویر (multipart، حداکثر ۱۰MB — jpg/png/webp/gif/avif) → `{"url": "/media/..."}` |

### تصاویر و MinIO

فایل‌های آپلودشده در باکت `aramesh-media` روی MinIO ذخیره می‌شوند و با مسیر نسبی `/media/<سال>/<ماه>/<فایل>` برگردانده می‌شوند. Traefik مسیر `/media` را به MinIO می‌برد، پس URLها مستقل از بک‌اند ذخیره‌سازی هستند — بعداً برای مهاجرت به R2/S3 فقط تنظیمات را عوض کنید، نه محتوای دیتابیس را.

- کنسول MinIO: `http://localhost:9001` (کاربر/رمز از `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` در compose)
- تصاویر عمومی و قابل نمایش‌اند؛ آپلود فقط با توکن ادمین انجام می‌شود.

## اتصال به فرانت‌اند

در پروژه React (پوشه `ArameshPlaza`)، فایل `src/config.ts` آدرس بک‌اند را نگه می‌دارد:

```ts
export const API_URL = import.meta.env.VITE_API_URL ?? 'http://localhost:8000'
```

در محیط تولید مقدار `VITE_API_URL` را روی آدرس عمومی API تنظیم کنید و مطمئن شوید آدرس سایت در `CORS_ORIGINS` فایل `.env` بک‌اند قرار دارد.

## ساختار پروژه

```
app/
├── main.py        # نقطه ورود FastAPI، CORS، ثبت روترها
├── config.py      # تنظیمات از .env
├── database.py    # اتصال PostgreSQL و نشست‌ها
├── models.py      # مدل‌های SQLAlchemy
├── schemas.py     # اسکیماهای Pydantic (ورودی/خروجی)
├── auth.py        # هش رمز عبور و JWT
├── seed.py        # اسکریپت seed
├── seed_data.py   # داده‌های اولیه سایت
└── api/
    ├── public.py  # انتهای عمومی محتوا
    ├── forms.py   # فرم تماس و خبرنامه
    └── admin.py   # ورود و پنل مدیریت
```