# راهنمای جامع پروژه اندیشکده فولاد آینده (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`).