Behrad
ed14435485
- API عمومی محتوای سایت (پروژه‌ها، مقالات، خدمات و...) - فرم تماس و خبرنامه با اعتبارسنجی سرور - پنل مدیریت با JWT و CRUD کامل + مدیریت پیام‌ها و مشترکین - اسکریپت seed با داده‌های واقعی سایت - تست‌شده: ۳۶/۳۶ انتهاپوینت
155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# بک‌اند آرامش پلازا (ArameshPlaza API)
|
||
|
||
بک‌اند سایت آرامش پلازا — ساخته‌شده با **FastAPI** + **PostgreSQL** + **SQLAlchemy 2** + **JWT**.
|
||
|
||
## امکانات
|
||
|
||
- **API عمومی محتوا**: برند، خدمات، پروژه‌ها، مقالات، نظرات مشتریان، سوالات متداول، تیم، تایم‌لاین، آمار، چرا آرامش، و بخش قبل/بعد
|
||
- **فرم تماس**: ثبت پیام مشتریان از سایت (`POST /api/contact`)
|
||
- **خبرنامه**: عضویت و مدیریت مشترکین (`POST /api/newsletter`)
|
||
- **پنل مدیریت**: ورود با نام کاربری/رمز عبور و دریافت توکن JWT، سپس CRUD کامل همه محتواها، مدیریت پیام‌های تماس و مشترکین
|
||
- **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}` | حذف مشترک |
|
||
|
||
## اتصال به فرانت‌اند
|
||
|
||
در پروژه 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 # ورود و پنل مدیریت
|
||
```
|