19 KiB

Raw Blame History

راهنمای جامع پروژه اندیشکده فولاد آینده (Andishkade Foolad)

این سند راهنمای فنی و معماری پروژه اندیشکده فولاد آینده است که شامل جزئیات ساختار فرانت‌اند، پنل مدیریت بک‌اند، پایگاه داده، پشته فناوری‌ها و نحوه راه‌اندازی و توسعه پروژه می‌باشد.

فهرست مطالب

۱. ساختار کلی پروژه
۲. فرانت‌اند (Frontend)
۳. پنل مدیریت (Backend / Admin Panel)
۴. نحوه اتصال فرانت‌اند به پنل مدیریت (Wiring)
۵. استقرار و دگرگونی‌ها (Deployment)

۱. ساختار کلی پروژه

پروژه به صورت یک ساختار تک‌مخزنی (Monorepo) طراحی شده است که شامل دو اپلیکیشن مستقل و بدون وابستگی اشتراکی در زمان ساخت (Build) است:

فرانت‌اند (Frontend - ریشه پروژه): یک وب‌سایت بازاریابی و محتوایی تعاملی، مدرن و با اولویت زبان فارسی (Persian-first) و دو زبانه (فارسی / انگلیسی) که با React 19 و Vite توسعه یافته است.
پنل مدیریت (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 جهت مدیریت وضعیت‌های سراسری وب‌سایت.

ویژگی‌ها و قابلیت‌های بصری فرانت‌اند

بومی‌سازی و پشتیبانی دو زبانه (Localization):
- پیاده‌سازی شده با استفاده از useLang() در src/context/LangContext.
- تغییر خودکار چیدمان صفحه به RTL برای زبان فارسی و LTR برای زبان انگلیسی با هدایت ویژگی dir.
- ترجمه درون‌برنامه‌ای کامپوننت‌ها با ساختار دیکشنری‌های محلی درون هر ماژول.
تقویم رویدادهای جلالی بومی (EventCalendar.tsx):
- طراحی شده به صورت کاملاً اختصاصی و بدون استفاده از کتابخانه‌های سنگین خارجی.
- استفاده از موتور بومی مرورگر با متد Intl.DateTimeFormat('en-US-u-ca-persian') برای ساخت گرید روزها و ماه‌های هجری شمسی.
مدیریت عملکرد و اسکرول:
- غیرفعال‌سازی Lenis در مرورگرهای موبایل و تبلت جهت جلوگیری از لگ یا تاخیر لمسی و سپردن اسکرول به سیستم‌عامل بومی دستگاه.
- بهینه‌سازی تصاویر با فرمت مدرن WebP.

دستورات بخش فرانت‌اند

این دستورات را در پوشه ریشه (Root) پروژه اجرا کنید:

# نصب پکیج‌ها
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) برای ایجاد خلاصه‌ها، استخراج داده‌های کلیدی از اسناد آپلود شده و کمک به آماده‌سازی مطالب برای ادمین.

ساختار و معماری پایگاه داده

پایگاه داده در زمان استارت آپ اپلیکیشن به صورت خودکار با جداول زیر مقداردهی اولیه (ایجاد ایندکس‌ها و جداول در صورت عدم وجود) می‌شود:

users: ذخیره ادمین‌ها با نقش‌های admin یا owner (صاحب پنل که دسترسی ویرایش سایر ادمین‌ها را دارد).
articles: مقالات و گزارش‌های تحلیلی. شامل فیلدهای عنوان، دسته‌بندی، نویسنده، مشخصات صفحات، قیمت، تگ‌ها و متن اصلی.
risk_signals: سیگنال‌های ریسک ژئوپلیتیک و صنعتی با سطوح بحرانی متفاوت (critical, high, medium, low, opportunity).
events: رویدادهای تقویم اندیشکده (سمینارها، همایش‌ها، نمایشگاه‌ها).
team_members: اعضای تیم پژوهشی، تخصص‌ها، راه‌های ارتباطی و شمارش گزارش‌های منتشر شده.
radar_items: گزارش‌های رادار بازار در ۵ دسته‌بندی اصلی: بازار (Market)، فناوری (Tech)، کالا (Commodity)، ژئوپلیتیک (Geo) و انرژی (Energy).
prices: قیمت‌های ثبت شده و شاخص‌های مرتبط.
members & purchases: مدیریت خرید اعضا و دسترسی به فایل‌های گزارشات غیر رایگان.

سرویس‌های ویژه پنل مدیریت

واردکننده خودکار داده (Import API): امکان وارد کردن فایل‌های JSON تولید شده توسط هوش مصنوعی Gemini که شامل خلاصه‌سازی‌ها، تگ‌ها و آیتم‌های رادار است با قابلیت پاک‌سازی خودکار کاراکترهای اضافی ارجاع دهی هوش مصنوعی ([cite: ...]).
مبدل خودکار تصاویر به WebP: تبدیل و بهینه‌سازی حجم تصاویر آپلود شده به صورت بی‌درنگ جهت بهبود سرعت لود کلاینت.

دستورات بخش پنل مدیریت

ابتدا به پوشه پنل بروید: cd panel

# نصب وابستگی‌های بک‌اند
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/ لود می‌شود تا فرانت‌بخش بدون وابستگی به سرور قابل نمایش باشد.

برای داینامیک کردن داده‌ها و اتصال فرانت‌اند به پنل مدیریت مراحل زیر پیشنهاد می‌شود:

در ریشه پروژه، متغیر محیطی آدرس بک‌اند را در فایل .env.local تعریف کنید:
```
VITE_PANEL_API=http://localhost:3001
```

یک سرویس کلاینت (مثلا src/lib/api.ts) برای واکشی داده‌ها بسازید:

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();
}

در کامپوننت‌های فرانت‌اند (مانند بخش نمایش گزارش‌های صفحه اصلی)، از React Query (که پکیج آن در پروژه نصب است) یا هوک useEffect برای دریافت پویای داده‌ها به شکل زیر استفاده کنید:

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).

19 KiB Raw Blame History Unescape Escape