نسخه ۲ بک‌اند آرامش پلازا — بازنویسی کامل
- API عمومی محتوای سایت (پروژه‌ها، مقالات، خدمات و...) - فرم تماس و خبرنامه با اعتبارسنجی سرور - پنل مدیریت با JWT و CRUD کامل + مدیریت پیام‌ها و مشترکین - اسکریپت seed با داده‌های واقعی سایت - تست‌شده: ۳۶/۳۶ انتهاپوینت
This commit is contained in:
Behrad
@@ -1,177 +1,154 @@
|
||||
# بک‌اند آرامش پلازا (FastAPI + PostgreSQL)
|
||||
# بک‌اند آرامش پلازا (ArameshPlaza API)
|
||||
|
||||
این بک‌اند برای سایت **آرامش پلازا** ساخته شده و شامل:
|
||||
- API کامل برای مدیریت محتوا: پروژه‌ها، مقالات، خدمات، تیم، نظرات مشتریان، تایم‌لاین، آمار، سوالات متداول، اطلاعات برند
|
||||
- فرم تماس (ذخیره در دیتابیس)
|
||||
- فرم خبرنامه (ذخیره در دیتابیس)
|
||||
- ورود ادمین با JWT برای مدیریت محتوا (ایجاد/ویرایش/حذف)
|
||||
- مستندات خودکار API (Swagger) روی آدرس `/docs`
|
||||
بک‌اند سایت آرامش پلازا — ساخته‌شده با **FastAPI** + **PostgreSQL** + **SQLAlchemy 2** + **JWT**.
|
||||
|
||||
قبلاً همه‌ی این محتوا داخل فایل `src/data/site.ts` توی فرانت‌اند به‌صورت ثابت نوشته شده بود. با این بک‌اند، همون محتوا از دیتابیس میاد و می‌تونی بدون نیاز به دیپلوی دوباره‌ی فرانت، محتوا رو تغییر بدی.
|
||||
## امکانات
|
||||
|
||||
---
|
||||
- **API عمومی محتوا**: برند، خدمات، پروژه‌ها، مقالات، نظرات مشتریان، سوالات متداول، تیم، تایم‌لاین، آمار، چرا آرامش، و بخش قبل/بعد
|
||||
- **فرم تماس**: ثبت پیام مشتریان از سایت (`POST /api/contact`)
|
||||
- **خبرنامه**: عضویت و مدیریت مشترکین (`POST /api/newsletter`)
|
||||
- **پنل مدیریت**: ورود با نام کاربری/رمز عبور و دریافت توکن JWT، سپس CRUD کامل همه محتواها، مدیریت پیام‌های تماس و مشترکین
|
||||
- **Seed خودکار**: همه محتوای فعلی سایت با یک دستور در دیتابیس قرار می‌گیرد
|
||||
- مستندات تعاملی Swagger در مسیر `/docs`
|
||||
|
||||
## پیش‌نیازها
|
||||
## راه‌اندازی
|
||||
|
||||
روی سیستم خودت باید این دو تا نصب باشن:
|
||||
1. **Python 3.11 یا بالاتر** — از [python.org](https://www.python.org/downloads/) دانلود کن
|
||||
2. **PostgreSQL** — از [postgresql.org](https://www.postgresql.org/download/) دانلود کن (موقع نصب، یک رمز عبور برای کاربر `postgres` ازت می‌پرسه؛ یادت بمونه)
|
||||
### ۱. پیش‌نیازها
|
||||
|
||||
برای چک کردن نصب بودنشون:
|
||||
```bash
|
||||
python --version
|
||||
psql --version
|
||||
```
|
||||
- Python 3.11 یا جدیدتر
|
||||
- PostgreSQL در حال اجرا (پورت پیش‌فرض 5432)
|
||||
|
||||
---
|
||||
|
||||
## قدم ۱: ساخت دیتابیس
|
||||
|
||||
بعد از نصب PostgreSQL، یک ترمینال باز کن و وارد psql شو:
|
||||
### ۲. نصب وابستگی‌ها
|
||||
|
||||
```bash
|
||||
psql -U postgres
|
||||
```
|
||||
cd arameshplaza-backend
|
||||
python -m venv .venv
|
||||
|
||||
(رمزی که موقع نصب گذاشتی رو وارد کن). حالا داخل psql این دستورها رو بزن:
|
||||
# ویندوز
|
||||
.venv\Scripts\activate
|
||||
# لینوکس / مک
|
||||
source .venv/bin/activate
|
||||
|
||||
```sql
|
||||
CREATE USER aramesh_user WITH PASSWORD 'یک-رمز-قوی-انتخاب-کن';
|
||||
CREATE DATABASE aramesh_db OWNER aramesh_user;
|
||||
\q
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## قدم ۲: نصب پروژه
|
||||
|
||||
توی پوشه‌ی این پروژه (همونجایی که این فایل `README.md` هست) یک ترمینال باز کن:
|
||||
|
||||
```bash
|
||||
# ساخت محیط مجازی پایتون (اختیاری ولی توصیه‌شده)
|
||||
python -m venv venv
|
||||
|
||||
# فعال‌سازی محیط مجازی
|
||||
# ویندوز:
|
||||
venv\Scripts\activate
|
||||
# مک/لینوکس:
|
||||
source venv/bin/activate
|
||||
|
||||
# نصب کتابخانه‌ها
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
### ۳. تنظیمات
|
||||
|
||||
## قدم ۳: تنظیم فایل `.env`
|
||||
|
||||
فایل `.env.example` رو کپی کن و اسمش رو بذار `.env`:
|
||||
فایل `.env.example` را به نام `.env` کپی کنید و مقادیر را تنظیم کنید:
|
||||
|
||||
```bash
|
||||
# ویندوز (Command Prompt):
|
||||
copy .env.example .env
|
||||
# مک/لینوکس:
|
||||
cp .env.example .env
|
||||
cp .env.example .env # لینوکس / مک
|
||||
copy .env.example .env # ویندوز
|
||||
```
|
||||
|
||||
حالا فایل `.env` رو با یک ادیتور متنی (مثل Notepad یا VS Code) باز کن و این خط رو با اطلاعات واقعی خودت پر کن:
|
||||
مهم‌ترین تنظیم `DATABASE_URL` است:
|
||||
|
||||
```
|
||||
DATABASE_URL=postgresql://aramesh_user:همون-رمزی-که-انتخاب-کردی@localhost:5432/aramesh_db
|
||||
DATABASE_URL=postgresql+psycopg://postgres:YOUR_PASSWORD@localhost:5432/arameshplaza_api
|
||||
```
|
||||
|
||||
خط `SECRET_KEY` رو هم به یک رشته‌ی رندوم و طولانی تغییر بده (هر متن دلخواه طولانی کافیه، برای پروداکشن بهتره واقعاً رندوم باشه).
|
||||
|
||||
---
|
||||
|
||||
## قدم ۴: ساخت جدول‌های دیتابیس (Migration)
|
||||
### ۴. ساخت دیتابیس و Seed
|
||||
|
||||
```bash
|
||||
alembic upgrade head
|
||||
# ساخت دیتابیس (یک‌بار):
|
||||
psql -U postgres -c "CREATE DATABASE arameshplaza_api;"
|
||||
|
||||
# ساخت جداول + وارد کردن محتوای سایت + ساخت ادمین پیش‌فرض:
|
||||
python -m app.seed
|
||||
|
||||
# بازنشانی کامل داده‌ها در صورت نیاز:
|
||||
python -m app.seed --force
|
||||
```
|
||||
|
||||
این دستور همه‌ی جدول‌های لازم (پروژه‌ها، مقالات، تماس‌ها و...) رو توی دیتابیست می‌سازه.
|
||||
|
||||
---
|
||||
|
||||
## قدم ۵: پر کردن دیتابیس با محتوای فعلی سایت
|
||||
|
||||
```bash
|
||||
python scripts/seed_data.py
|
||||
```
|
||||
|
||||
این اسکریپت همون محتوایی که الان توی `site.ts` هست (پروژه‌ها، مقالات، تیم و...) رو توی دیتابیس می‌ریزه تا سایت خالی نمونه.
|
||||
|
||||
---
|
||||
|
||||
## قدم ۶: ساخت اکانت ادمین
|
||||
|
||||
```bash
|
||||
python scripts/create_admin.py
|
||||
```
|
||||
|
||||
یک نام کاربری و رمز عبور وارد کن. با همین اکانت وارد پنل مدیریت می‌شی (بعداً وقتی پنل ادمین رو هم بسازیم).
|
||||
|
||||
---
|
||||
|
||||
## قدم ۷: اجرای سرور
|
||||
### ۵. اجرا
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
اگه همه چیز درست باشه، پیام `Application startup complete` رو می‌بینی. حالا:
|
||||
- API روی آدرس **http://localhost:8000** در دسترسه
|
||||
- مستندات تعاملی (می‌تونی همونجا API رو تست کنی) روی **http://localhost:8000/docs**
|
||||
سپس:
|
||||
- مستندات 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/projects` | لیست همه پروژه‌ها |
|
||||
| پروژه‌ها | `GET /api/projects/{slug}` | جزئیات یک پروژه |
|
||||
| مقالات | `GET /api/articles` | لیست همه مقالات |
|
||||
| مقالات | `GET /api/articles/{slug}` | جزئیات یک مقاله |
|
||||
| خدمات | `GET /api/services` | لیست خدمات |
|
||||
| تیم | `GET /api/team` | اعضای تیم |
|
||||
| نظرات مشتریان | `GET /api/testimonials` | نظرات |
|
||||
| تایم‌لاین | `GET /api/timeline` | تاریخچه شرکت |
|
||||
| چرا ما | `GET /api/why-us` | نکات "چرا آرامش پلازا" |
|
||||
| آمار | `GET /api/stats` | آمار صفحه اصلی |
|
||||
| سوالات متداول | `GET /api/faqs` | لیست FAQ |
|
||||
| برند | `GET /api/brand` | اطلاعات تماس/لوگو/آدرس |
|
||||
| تماس | `POST /api/contact` | ثبت فرم تماس (عمومی) |
|
||||
| خبرنامه | `POST /api/newsletter` | عضویت در خبرنامه (عمومی) |
|
||||
| ورود ادمین | `POST /api/auth/login` | گرفتن توکن JWT |
|
||||
| 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` | ورود ادمین و دریافت توکن |
|
||||
|
||||
تمام درخواست‌های `GET` روی این منابع **عمومی** هستن (فرانت‌اند بدون نیاز به ورود می‌تونه بخونتشون).
|
||||
تمام درخواست‌های `POST` / `PUT` / `DELETE` (به‌جز فرم تماس و خبرنامه) نیاز به توکن ادمین دارن — یعنی باید هدر زیر رو بفرستی:
|
||||
### مدیریت (نیاز به توکن Bearer)
|
||||
|
||||
```
|
||||
Authorization: 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` بک‌اند قرار دارد.
|
||||
|
||||
## اتصال فرانت‌اند به این بک‌اند
|
||||
## ساختار پروژه
|
||||
|
||||
فرانت‌اند فعلی (`src/data/site.ts`) داده‌ها رو به‌صورت ثابت داره. برای اتصال به این بک‌اند باید:
|
||||
1. به‌جای import کردن از `site.ts`، هر کامپوننت داده‌هاش رو با `fetch` یا `axios` از این آدرس‌ها بگیره (مثلاً `fetch('http://localhost:8000/api/projects')`)
|
||||
2. فرم `ContactSection.tsx` و `Newsletter.tsx` به‌جای فقط تغییر state داخلی، باید یک درخواست `POST` به `/api/contact` و `/api/newsletter` بفرستن
|
||||
|
||||
اگه بخوای، توی یک مرحله‌ی بعدی می‌تونم دقیقاً همین تغییرات رو توی کدهای فرانت‌اندت اعمال کنم تا کامل به این بک‌اند وصل بشه.
|
||||
|
||||
---
|
||||
|
||||
## دیپلوی (وقتی آماده‌ی انتشار شدی)
|
||||
|
||||
گزینه‌های ساده برای هاست این بک‌اند:
|
||||
- **Railway** یا **Render**: خیلی راحت از روی گیت‌هاب دیپلوی می‌کنن و PostgreSQL هم بهت می‌دن
|
||||
- سرور شخصی با Docker یا مستقیم با `uvicorn`/`gunicorn`
|
||||
|
||||
نکته مهم امنیتی: قبل از دیپلوی روی سرور واقعی، حتماً:
|
||||
1. یک `SECRET_KEY` رندوم و قوی بذار (نه همون مقدار پیش‌فرض)
|
||||
2. آدرس دقیق دامنه‌ی فرانت‌اندت (مثلاً `https://aramesh-six.vercel.app`) رو توی `CORS_ORIGINS` بذار
|
||||
3. رمز عبور دیتابیس رو قوی انتخاب کن
|
||||
```
|
||||
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 # ورود و پنل مدیریت
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user