250 lines
19 KiB
Markdown
250 lines
19 KiB
Markdown
# راهنمای جامع پروژه اندیشکده فولاد آینده (Andishkade Foolad)
|
||
|
||
این سند راهنمای فنی و معماری پروژه **اندیشکده فولاد آینده** است که شامل جزئیات ساختار فرانتاند، پنل مدیریت بکاند، پایگاه داده، پشته فناوریها و نحوه راهاندازی و توسعه پروژه میباشد.
|
||
|
||
---
|
||
|
||
## فهرست مطالب
|
||
- [۱. ساختار کلی پروژه](#۱-ساختار-کلی-پروژه)
|
||
- [۲. فرانتاند (Frontend)](#۲-فرانتاند-frontend)
|
||
- [پشته فناوری فرانتاند](#پشته-فناوری-فرانتاند)
|
||
- [ویژگیها و قابلیتهای بصری فرانتاند](#ویژگیها-و-قابلیتهای-بصری-فرانتاند)
|
||
- [دستورات بخش فرانتاند](#دستورات-بخش-فرانتاند)
|
||
- [۳. پنل مدیریت (Backend / Admin Panel)](#۳-پنل-مدیریت-backend--admin-panel)
|
||
- [پشته فناوری بکاند](#پشته-فناوری-بکاند)
|
||
- [ساختار و معماری پایگاه داده](#ساختار-و-معماری-پایگاه-داده)
|
||
- [سرویسهای ویژه پنل مدیریت](#سرویسهای-ویژه-پنل-مدیریت)
|
||
- [دستورات بخش پنل مدیریت](#دستورات-بخش-پنل-مدیریت)
|
||
- [لیست APIهای پنل مدیریت](#لیست-apiهای-پنل-مدیریت)
|
||
- [۴. نحوه اتصال فرانتاند به پنل مدیریت (Wiring)](#۴-نحوه-اتصال-فرانتاند-به-پنل-مدیریت-wiring)
|
||
- [۵. استقرار و دگرگونیها (Deployment)](#۵-استقرار-و-دگرگونیها-deployment)
|
||
|
||
---
|
||
|
||
## ۱. ساختار کلی پروژه
|
||
|
||
پروژه به صورت یک ساختار تکمخزنی (Monorepo) طراحی شده است که شامل دو اپلیکیشن مستقل و بدون وابستگی اشتراکی در زمان ساخت (Build) است:
|
||
|
||
1. **فرانتاند (Frontend - ریشه پروژه)**: یک وبسایت بازاریابی و محتوایی تعاملی، مدرن و با اولویت زبان فارسی (Persian-first) و دو زبانه (فارسی / انگلیسی) که با React 19 و Vite توسعه یافته است.
|
||
2. **پنل مدیریت (Admin Panel - پوشه `panel/`)**: یک وباپلیکیشن مستقل SPA با معماری Node.js/Express و پایگاه داده PostgreSQL که محتوای پویا وبسایت را مدیریت میکند.
|
||
|
||
```
|
||
andishkade-foolad/
|
||
├── panel/ # پروژه بکاند و پنل مدیریت
|
||
│ ├── public/ # فایلهای استاتیک و رابط کاربری پنل (Vanilla JS)
|
||
│ ├── uploads/ # فایلهای آپلود شده محلی (در صورت عدم استفاده از S3)
|
||
│ ├── server.js # سرور اصلی Express
|
||
│ ├── db.js # پیکربندی پایگاه داده PostgreSQL و کوئریها
|
||
│ └── package.json # وابستگیهای بکاند
|
||
├── src/ # کدهای منبع فرانتاند (React 19)
|
||
│ ├── app/ # مسیریابی و قالب اصلی (Layout)
|
||
│ ├── components/ # کامپوننتهای اشتراکی و UI
|
||
│ ├── context/ # کانتکستهای ریاکت (مانند زبان سیستم)
|
||
│ ├── data/ # دادههای اولیه و ماک (Mock Data)
|
||
│ └── pages/ # صفحات مختلف وبسایت
|
||
├── package.json # وابستگیهای فرانتاند
|
||
├── Dockerfile # داکرفایل اجرای فرانتاند به عنوان سرور استاتیک Nginx
|
||
└── docker-compose.yml # تنظیمات داکر کامپوز برای اجرای لوکال فرانتاند
|
||
```
|
||
|
||
---
|
||
|
||
## ۲. فرانتاند (Frontend)
|
||
|
||
بخش کاربری وبسایت اندیشکده فولاد آینده یک پورتال محتوایی بسیار پیشرفته و پویا با انیمیشنهای غنی است.
|
||
|
||
### پشته فناوری فرانتاند
|
||
|
||
* **هسته اصلی:** React 19 همراه با TypeScript برای ایمنی کدها و مدلسازی دادهها.
|
||
* **سیستم بیلد:** Vite جهت بارگذاری سریع در زمان توسعه (HMR) و خروجی بهینه در زمان پروداکشن.
|
||
* **استایلدهی:** Tailwind CSS v4 (با پیکربندی جدید مبتنی بر پلاگین Vite) به همراه متغیرهای سفارشی CSS در `src/index.css` برای رنگبندی سازمانی طلایی (`#CD9E53`) و سورمهای (`#032340`).
|
||
* **مسیریابی:** React Router DOM v7 با استفاده از ساختار شیءگرا (`createBrowserRouter`).
|
||
* **انیمیشنها و اسکرول:**
|
||
* **GSAP (GreenSock) & ScrollTrigger:** برای پیادهسازی انیمیشنهای پیچیده مبتنی بر اسکرول (مانند بخش Hero تعاملی).
|
||
* **Lenis Smooth Scroll:** موتور اسکرول بسیار نرم هماهنگ شده با تیکر GSAP (مخصوص دسکتاپ).
|
||
* **Framer Motion:** برای انیمیشنهای خرد (Micro-animations)، پاپآپها و ترنزیشن کامپوننتها.
|
||
* **کامپوننتهای سهبعدی:**
|
||
* **Three.js & React Three Fiber (R3F):** برای رندر کردن اشیاء سهبعدی در وب.
|
||
* **Three Globe & Cobe:** جهت نمایش کره زمین سهبعدی تعاملی و زیبا در بخش ژئوپلیتیک و ارتباطات بینالملل.
|
||
* **نمودارها:** React ApexCharts جهت نمایش نوسانات بازار فولاد و قیمتها.
|
||
* **مدیریت وضعیت:** Zustand جهت مدیریت وضعیتهای سراسری وبسایت.
|
||
|
||
### ویژگیها و قابلیتهای بصری فرانتاند
|
||
|
||
1. **بومیسازی و پشتیبانی دو زبانه (Localization):**
|
||
* پیادهسازی شده با استفاده از `useLang()` در `src/context/LangContext`.
|
||
* تغییر خودکار چیدمان صفحه به RTL برای زبان فارسی و LTR برای زبان انگلیسی با هدایت ویژگی `dir`.
|
||
* ترجمه درونبرنامهای کامپوننتها با ساختار دیکشنریهای محلی درون هر ماژول.
|
||
2. **تقویم رویدادهای جلالی بومی (`EventCalendar.tsx`):**
|
||
* طراحی شده به صورت کاملاً اختصاصی و بدون استفاده از کتابخانههای سنگین خارجی.
|
||
* استفاده از موتور بومی مرورگر با متد `Intl.DateTimeFormat('en-US-u-ca-persian')` برای ساخت گرید روزها و ماههای هجری شمسی.
|
||
3. **مدیریت عملکرد و اسکرول:**
|
||
* غیرفعالسازی Lenis در مرورگرهای موبایل و تبلت جهت جلوگیری از لگ یا تاخیر لمسی و سپردن اسکرول به سیستمعامل بومی دستگاه.
|
||
* بهینهسازی تصاویر با فرمت مدرن WebP.
|
||
|
||
### دستورات بخش فرانتاند
|
||
|
||
این دستورات را در پوشه ریشه (Root) پروژه اجرا کنید:
|
||
|
||
```bash
|
||
# نصب پکیجها
|
||
npm install
|
||
|
||
# اجرای سرور توسعه محلی ریاکت
|
||
npm run dev
|
||
|
||
# بررسی خطاهای تایپاسکریپت (سریعترین ابزار اعتبارسنجی لوپ توسعه)
|
||
npx tsc -b --noEmit
|
||
|
||
# بررسی و رفع کدهای غیراستاندارد با ESLint
|
||
npm run lint
|
||
|
||
# ایجاد پکیج خروجی نهایی (Production Build)
|
||
npm run build
|
||
|
||
# پیشنمایش نسخه نهایی بیلد شده روی سیستم محلی
|
||
npm run preview
|
||
```
|
||
|
||
---
|
||
|
||
## ۳. پنل مدیریت (Backend / Admin Panel)
|
||
|
||
پنل مدیریت در پوشه `panel/` قرار دارد و وظیفه ذخیرهسازی دادههای ساختاریافته وبسایت و مدیریت کاربران ادمین را بر عهده دارد.
|
||
|
||
### پشته فناوری بکاند
|
||
|
||
* **فریمورک سرور:** Express.js 4 مبتنی بر Node.js (نسخه ۲۰ به بالا).
|
||
* **پایگاه داده:** PostgreSQL (سیستم میزبانی ابری لیارا) به همراه ماژول `pg`. برای تسهیل مهاجرت از SQLite قبلی، یک نمای هماهنگ شبیه به متدهای `better-sqlite3` در فایل `db.js` ایجاد شده است.
|
||
* **امنیت و احراز هویت:**
|
||
* `bcryptjs` برای رمزنگاری امن گذرواژهها.
|
||
* `jsonwebtoken` (JWT) برای احراز هویت کاربران ادمین و اعضا. کوکیهای امن با ویژگیهای `HttpOnly` و `Secure/SameSite` به مرورگر فرستاده میشوند تا از حملات XSS جلوگیری شود.
|
||
* `helmet` جهت اضافه کردن هدرهای امنیتی HTTP.
|
||
* `express-rate-limit` برای محدود کردن تعداد درخواستها به اندپوینتهای حساس نظیر فرم ورود و فرم تماس با ما.
|
||
* **پردازش تصاویر و فایلها:**
|
||
* `multer` برای مدیریت آپلود فایلهای چندرسانهای به صورت بافر حافظه.
|
||
* `sharp` جهت پردازش خودکار تصاویر آپلود شده (فشردهسازی داینامیک، چرخش صحیح بر اساس EXIF، ریسایز تا سقف ۲۰۰۰ پیکسل و خروجی با فرمت فوقالعاده بهینه WebP).
|
||
* `pdf-parse` برای خواندن و استخراج متون داخل اسناد PDF گزارشها جهت تحلیل توسط هوش مصنوعی.
|
||
* **ذخیرهسازی فایل (Storage):**
|
||
* پشتیبانی از پروتکل **S3-compatible Object Storage** (مانند فضای ذخیرهسازی ابری لیارا). در صورت تنظیم متغیرهای محیطی S3، فایلها مستقیماً آپلود شده و آدرس مستقیم CDN دریافت میشود. در غیر این صورت، پروژه به صورت خودکار به حالت آپلود روی دیسک محلی (`panel/uploads/`) تغییر مسیر میدهد.
|
||
* **یکپارچهسازی هوش مصنوعی (AI Integration):**
|
||
* استفاده از SDKهای رسمی **OpenAI** و **Anthropic (Claude)** برای ایجاد خلاصهها، استخراج دادههای کلیدی از اسناد آپلود شده و کمک به آمادهسازی مطالب برای ادمین.
|
||
|
||
### ساختار و معماری پایگاه داده
|
||
|
||
پایگاه داده در زمان استارت آپ اپلیکیشن به صورت خودکار با جداول زیر مقداردهی اولیه (ایجاد ایندکسها و جداول در صورت عدم وجود) میشود:
|
||
|
||
1. **`users`**: ذخیره ادمینها با نقشهای `admin` یا `owner` (صاحب پنل که دسترسی ویرایش سایر ادمینها را دارد).
|
||
2. **`articles`**: مقالات و گزارشهای تحلیلی. شامل فیلدهای عنوان، دستهبندی، نویسنده، مشخصات صفحات، قیمت، تگها و متن اصلی.
|
||
3. **`risk_signals`**: سیگنالهای ریسک ژئوپلیتیک و صنعتی با سطوح بحرانی متفاوت (`critical`, `high`, `medium`, `low`, `opportunity`).
|
||
4. **`events`**: رویدادهای تقویم اندیشکده (سمینارها، همایشها، نمایشگاهها).
|
||
5. **`team_members`**: اعضای تیم پژوهشی، تخصصها، راههای ارتباطی و شمارش گزارشهای منتشر شده.
|
||
6. **`radar_items`**: گزارشهای رادار بازار در ۵ دستهبندی اصلی: بازار (Market)، فناوری (Tech)، کالا (Commodity)، ژئوپلیتیک (Geo) و انرژی (Energy).
|
||
7. **`prices`**: قیمتهای ثبت شده و شاخصهای مرتبط.
|
||
8. **`members` & `purchases`**: مدیریت خرید اعضا و دسترسی به فایلهای گزارشات غیر رایگان.
|
||
|
||
### سرویسهای ویژه پنل مدیریت
|
||
|
||
* **واردکننده خودکار داده (Import API):**
|
||
امکان وارد کردن فایلهای JSON تولید شده توسط هوش مصنوعی Gemini که شامل خلاصهسازیها، تگها و آیتمهای رادار است با قابلیت پاکسازی خودکار کاراکترهای اضافی ارجاع دهی هوش مصنوعی (`[cite: ...]`).
|
||
* **مبدل خودکار تصاویر به WebP:**
|
||
تبدیل و بهینهسازی حجم تصاویر آپلود شده به صورت بیدرنگ جهت بهبود سرعت لود کلاینت.
|
||
|
||
### دستورات بخش پنل مدیریت
|
||
|
||
ابتدا به پوشه پنل بروید: `cd panel`
|
||
|
||
```bash
|
||
# نصب وابستگیهای بکاند
|
||
npm install
|
||
|
||
# ساخت حساب کاربری ادمین اولیه با استفاده از مقادیر .env
|
||
npm run seed
|
||
|
||
# اجرای سرور در حالت پروداکشن
|
||
npm start
|
||
|
||
# اجرای سرور در حالت توسعه با قابلیت راهاندازی مجدد خودکار هنگام تغییر کدها (Watch mode)
|
||
npm run dev
|
||
|
||
# بازسازی ماژول پایگاه داده در صورت تغییر نسخه Node.js سیستم
|
||
npm rebuild better-sqlite3
|
||
```
|
||
|
||
### لیست APIهای پنل مدیریت
|
||
|
||
تمامی متدهای ویرایشی (POST/PUT/DELETE) نیازمند ارسال توکن JWT در کوکی مرورگر یا هدر درخواست (`Authorization: Bearer <token>`) هستند.
|
||
|
||
| متد | مسیر | نیاز به احراز هویت | توضیحات |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **POST** | `/api/auth/login` | خیر | ورود ادمین و ثبت کوکی نشست امن |
|
||
| **POST** | `/api/auth/logout` | خیر | خروج از حساب کاربری و پاک کردن کوکی |
|
||
| **GET** | `/api/auth/me` | بله | دریافت مشخصات کاربر جاری |
|
||
| **GET** | `/api/articles` | خیر | لیست مقالات و گزارشها (دارای فیلتر دستهبندی و نوع) |
|
||
| **POST** | `/api/articles` | بله (ادمین) | ایجاد مقاله جدید |
|
||
| **PUT** | `/api/articles/:id` | بله (ادمین) | ویرایش مقاله موجود |
|
||
| **DELETE** | `/api/articles/:id` | بله (ادمین) | حذف مقاله |
|
||
| **POST** | `/api/uploads` | bله (ادمین) | آپلود تصویر و تبدیل خودکار به WebP بهینه |
|
||
| **POST** | `/api/uploads/raw` | بله (ادمین) | آپلود ویدیو و اسناد PDF به فضای ابری S3 |
|
||
| **GET** | `/api/events` | خیر | لیست کل رویدادهای تقویم |
|
||
| **GET** | `/api/radar` | خیر | لیست تحلیلهای رادار بازار |
|
||
| **POST** | `/api/admin/import` | بله (ادمین) | ایمپورت مستقیم دادههای تحلیلی هوش مصنوعی |
|
||
| **GET** | `/api/health` | خیر | بررسی سلامت سرور |
|
||
|
||
---
|
||
|
||
## ۴. نحوه اتصال فرانتاند به پنل مدیریت (Wiring)
|
||
|
||
در حال حاضر بخش زیادی از اطلاعات فرانتاند به صورت ایستا (Static / Mock Data) از پوشه `src/data/` یا `src/content/` لود میشود تا فرانتبخش بدون وابستگی به سرور قابل نمایش باشد.
|
||
|
||
برای داینامیک کردن دادهها و اتصال فرانتاند به پنل مدیریت مراحل زیر پیشنهاد میشود:
|
||
|
||
1. در ریشه پروژه، متغیر محیطی آدرس بکاند را در فایل `.env.local` تعریف کنید:
|
||
```env
|
||
VITE_PANEL_API=http://localhost:3001
|
||
```
|
||
2. یک سرویس کلاینت (مثلا `src/lib/api.ts`) برای واکشی دادهها بسازید:
|
||
```typescript
|
||
const API_URL = import.meta.env.VITE_PANEL_API || 'http://localhost:3001';
|
||
|
||
export async function getArticles(category?: string) {
|
||
const url = category ? `${API_URL}/api/articles?category=${encodeURIComponent(category)}` : `${API_URL}/api/articles`;
|
||
const res = await fetch(url);
|
||
if (!res.ok) throw new Error('خطا در دریافت اطلاعات از سرور');
|
||
return res.json();
|
||
}
|
||
```
|
||
3. در کامپوننتهای فرانتاند (مانند بخش نمایش گزارشهای صفحه اصلی)، از React Query (که پکیج آن در پروژه نصب است) یا هوک `useEffect` برای دریافت پویای دادهها به شکل زیر استفاده کنید:
|
||
```typescript
|
||
import { useQuery } from '@tanstack/react-query';
|
||
import { getArticles } from '@/lib/api';
|
||
|
||
// در داخل کامپوننت ریاکت
|
||
const { data: reports, isLoading } = useQuery({
|
||
queryKey: ['articles', category],
|
||
queryFn: () => getArticles(category),
|
||
placeholderData: fallbackMockData // استفاده از دادههای ماک قبلی در زمان لودینگ یا خطا
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## ۵. استقرار و دگرگونیها (Deployment)
|
||
|
||
### فرانتاند
|
||
فرانتاند پروژه به دلیل ایستا (Static) بودن خروجی نهایی، به راحتی به کمک **Dockerfile** موجود استقرار مییابد.
|
||
* داکرفایل از ساختار دو مرحلهای (Multi-stage build) استفاده میکند:
|
||
1. مرحله اول: استفاده از ایمیج Node جهت نصب پکیجها و ایجاد خروجی نهایی بیلد در پوشه `dist`.
|
||
2. مرحله دوم: استفاده از سرور بسیار سبک Nginx جهت کپی و سرو کردن فایلهای پوشه `dist` روی پورت `7860`.
|
||
* این پورت برای آپلود مستقیم در پلتفرمهایی مانند **Hugging Face Spaces** بهینه شده است (تنظیمات متا دیتا در بالای فایل `README.md` ریشه قید شده است).
|
||
|
||
### پنل مدیریت (بکاند)
|
||
* پنل مدیریت به پایگاه داده و در صورت تمایل سیستم فایل نیاز دارد.
|
||
* برای دیپلوی روی **لیارا (Liara)**، فایلهای کانفیگ نظیر `liara.json` و فایل نادیدهگیری `.liaraignore` تعبیه شدهاند.
|
||
* حتما باید متغیرهای محیطی زیر در کنترل پنل هاست تعریف شوند:
|
||
* `PORT`: پورت سرور (به عنوان مثال ۳۰۰۱).
|
||
* `JWT_SECRET`: یک رشته هگزادسیمل تصادفی طولانی (حداقل ۳۲ کاراکتر).
|
||
* `DATABASE_URL`: آدرس اتصال به پایگاه داده PostgreSQL ابری شما.
|
||
* `ALLOWED_ORIGINS`: آدرس دامنه فرانتاند جهت عبور از گیت CORS.
|
||
* متغیرهای سرویس فایل ابری در صورت نیاز (`LIARA_ENDPOINT`, `LIARA_BUCKET`, `LIARA_ACCESS_KEY`, `LIARA_SECRET_KEY`).
|