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

این سند، راهنمای فنی و معماریِ پروژه **اندیشکده فولاد آینده** است — یک پلتفرم تحلیلیِ صنعت فولاد، شاملِ یک وب‌سایتِ محتوایی و یک پنلِ مدیریت/بک‌اند. در این سند ساختار پوشه‌ها، پشته‌ی فناوری، پایگاه داده، احراز هویت، قابلیت‌ها و نحوه‌ی استقرار توضیح داده شده است.

---

## فهرست مطالب
- [۱. ساختار کلی پروژه](#۱-ساختار-کلی-پروژه)
- [۲. فرانت‌اند (`frontend/`)](#۲-فرانت‌اند-frontend)
- [۳. پنل مدیریت و بک‌اند (`panel/`)](#۳-پنل-مدیریت-و-بک‌اند-panel)
- [۴. پایگاه داده](#۴-پایگاه-داده)
- [۵. احراز هویت و اعضا](#۵-احراز-هویت-و-اعضا)
- [۶. اتصال فرانت‌اند به پنل (Wiring)](#۶-اتصال-فرانت‌اند-به-پنل-wiring)
- [۷. فهرست APIها](#۷-فهرست-apiها)
- [۸. استقرار (Deployment)](#۸-استقرار-deployment)

---

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

پروژه یک **مونوریپو** با دو اپلیکیشنِ مستقل و کنارهم (sibling) است که **هیچ build یا وابستگیِ مشترکی** ندارند؛ فرانت‌اند فقط در زمانِ اجرا (runtime) و از طریق متغیر `VITE_PANEL_API` با پنل حرف می‌زند.

```
andishkade-foolad/
├── frontend/               # وب‌سایت عمومی — Vite + React 19 + TypeScript
│   ├── src/
│   │   ├── app/            # مسیریابی (router) و قالب اصلی (RootLayout)
│   │   ├── components/     # کامپوننت‌های اشتراکی و UI
│   │   ├── context/        # کانتکست‌ها: زبان (LangContext) و احراز هویت (AuthContext)
│   │   ├── content/ data/  # داده‌های اولیه/ماک + ماژول‌های bootstrap که از پنل واکشی می‌کنند
│   │   └── pages/          # صفحات سایت
│   ├── public/             # دارایی‌های استاتیک، فونت‌ها، manifest و service worker (PWA)
│   ├── index.html
│   ├── vite.config.ts  tsconfig*.json  eslint.config.js
│   ├── Dockerfile  nginx.conf  liara.json   # استقرار به‌صورت سرور استاتیک Nginx روی پورت ۷۸۶۰
│   └── package.json
├── panel/                  # بک‌اند (Express API) + پنلِ مدیریت (CMS) — یک اپ واحد
│   ├── server.js           # سرور و همه‌ی Routeهای API
│   ├── db.js               # اتصال PostgreSQL + facade شبیه better-sqlite3 + مپ ردیف‌ها
│   ├── public/             # رابط کاربری پنل (SPA با Vanilla JS، بدون build)
│   ├── uploads/            # آپلودِ محلی (در صورت نبودِ S3)
│   ├── liara.json
│   └── package.json
├── docker-compose.yml      # اجرای لوکالِ فرانت (context: ./frontend)
├── CLAUDE.md  README.md  README_FA.md  SECURITY.md  design-system.md
```

> **نکته:** پنل **هم بک‌اندِ API است و هم CMS** (رابطِ مدیریت را از `panel/public/` سرو می‌کند). این دو به‌هم گره خورده‌اند و یک اپلیکیشنِ واحدند.

### نمودار معماری

```
                         ┌──────────────────────────┐
                         │        مرورگرِ کاربر       │
                         └───────────┬──────────────┘
              صفحاتِ سایت │           │ پنلِ مدیریت (ادمین)
                          ▼           ▼
   ┌───────────────────────────┐   ┌───────────────────────────────┐
   │  FRONTEND (اپِ Liara:      │   │  PANEL (اپِ Liara:             │
   │  steelforesight)          │   │  cms-steelforesight)          │
   │  Nginx → فایل‌های استاتیکِ │   │  Express (server.js)          │
   │  dist/  (پورت ۷۸۶۰)        │   │  + رابطِ CMS از panel/public/  │
   │  React 19 / Vite          │   │                               │
   └───────────┬───────────────┘   └──────┬───────────┬────────┬───┘
               │  fetch (runtime)         │           │        │
               │  VITE_PANEL_API ─────────┘           │        │
               ▼                                       ▼        ▼
        ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  ┌──────────────┐
        │  REST  /api  │   │  PostgreSQL  │   │  S3 Storage  │  │ Kavenegar SMS │
        │  (JSON)      │   │  (Liara)     │   │  (Liara)     │  │ OpenAI/Claude │
        └──────────────┘   └──────────────┘   └──────────────┘  └──────────────┘
```

- **دو اپِ کاملاً جدا:** هرکدام Dockerfile/استقرارِ خودش را دارد و جداگانه روی Liara مستقر می‌شود. هیچ کدِ مشترکی بین `frontend/` و `panel/` import نمی‌شود.
- **زمانِ build (فرانت):** مقدارِ `VITE_PANEL_API` در زمانِ `vite build` داخلِ باندل تزریق می‌شود (نه در زمانِ اجرا). یعنی آدرسِ پنل در فایل‌های استاتیکِ خروجی ثابت می‌شود.
- **زمانِ اجرا:** مرورگر فایل‌های استاتیک را از فرانت می‌گیرد، سپس مستقیماً با `fetch` به `https://cms-steelforesight.liara.run/api/...` وصل می‌شود (cross-origin، با `credentials: 'include'` برای کوکیِ نشست). CORS در پنل با `ALLOWED_ORIGINS` کنترل می‌شود.
- **پنل ↔ سرویس‌ها:** پنل تنها مؤلفه‌ای است که به PostgreSQL، object storageِ S3، پیامکِ کاوه‌نگار و APIهای هوش مصنوعی وصل می‌شود؛ فرانت هیچ‌وقت مستقیماً با این‌ها حرف نمی‌زند.

### لایه‌بندیِ فرانت‌اند (jریانِ یک درخواست)

```
main.tsx  →  bootstrap*()  →  fetch(VITE_PANEL_API + /api/...)  →  پر کردنِ ماژول‌های content/data
   │                                   │
   │ (در صورت خطا/آفلاین: fallback به دادهٔ ایستا)
   ▼
RouterProvider → RootLayout (Header / Footer / Lenis / بومی‌سازِ ارقام / ردیابِ فعالیت)
   ▼
صفحه (src/pages/*)  →  useLang() برای fa/en  ·  useAuth() برای نشستِ عضو
```

### لایه‌بندیِ پنل (jریانِ یک درخواست)

```
درخواست → helmet → CORS(ALLOWED_ORIGINS) → cookieParser → rate-limit
   → میدلورِ احراز هویت (authRequired برای ادمین / memberRequired برای عضو)
   → هندلرِ Route → db.prepare(sql).get/all/run()  ↔  PostgreSQL
   → (آپلود: multer → sharp/WebP → S3 یا دیسک)
   → پاسخِ JSON
```

---

## ۲. فرانت‌اند (`frontend/`)

پورتالِ محتواییِ فارسی‌محور (Persian-first)، دوزبانه (fa/en) و RTL با انیمیشن‌های غنی.

### پشته‌ی فناوری
- **هسته:** React 19 + TypeScript.
- **بیلد:** Vite (HMR در توسعه، خروجی بهینه در پروداکشن). اعتبارسنجیِ سریع: `npx tsc -b --noEmit`.
- **استایل:** عمدتاً `style` اینلاین + کلاس‌های Tailwind CSS v4 برای واکنش‌گرایی (`max-md:` …) + متغیرهای CSS در `src/index.css`. رنگِ سازمانی: طلایی `#CD9E53` و سورمه‌ای `#032340` (در بسیاری فایل‌ها به‌صورت `const GOLD`/`const NAVY` هاردکد شده‌اند).
- **مسیریابی:** React Router DOM v7 (`createBrowserRouter`). `RootLayout` همه‌ی صفحات را با Header/Footer و موتورِ اسکرول می‌پیچد.
- **انیمیشن و اسکرول:**
  - **GSAP + ScrollTrigger:** انیمیشن‌های مبتنی بر اسکرول.
  - **Lenis:** اسکرولِ نرم هماهنگ با تیکرِ GSAP — **فقط دسکتاپ** (روی لمسی به مومنتومِ بومیِ سیستم‌عامل واگذار می‌شود تا لگ نشود).
  - **Framer Motion:** میکروانیمیشن‌ها، پاپ‌آپ‌ها و ترنزیشن‌ها.
- **سه‌بعدی و نقشه:** Three.js + React Three Fiber، `three-globe` و `react-globe.gl` برای کره‌ی زمینِ تعاملی.
- **نمودار:** ApexCharts (صفحه‌ی Market).
- **مدیریت وضعیت:** صرفاً **React Context** (زبان و احراز هویت). بدون کتابخانه‌ی state خارجی.

### قابلیت‌های کلیدی
1. **دوزبانه/RTL:** هوک `useLang()` (`src/context/LangContext`) مقدار `{ lang, toggle }` می‌دهد؛ کامپوننت‌ها دیکشنریِ درون‌خطیِ `{ fa, en }` دارند و جهتِ صفحه با `dir` تنظیم می‌شود.
2. **اعدادِ فارسی:** یک «بومی‌سازِ ارقام» در `RootLayout` همه‌ی ارقامِ لاتینِ نمایش‌داده‌شده را در حالتِ فارسی به فارسی تبدیل می‌کند (با MutationObserver برای محتوای دیرلودشده).
3. **تاریخ شمسی:** بدون کتابخانه‌ی تاریخ — مستقیماً با `Intl.DateTimeFormat('fa-IR-u-ca-persian', …)`.
4. **PWA و موبایل:** manifest + service worker (نصب‌پذیری + کشِ آفلاین)؛ صفحه روی موبایل **غیرقابلِ زوم** است (viewport + بلوکِ pinch/double-tap برای iOS).
5. **جستجوی سراسری:** آیکونِ سرچِ هدر → صفحه‌ی `/search` که به‌صورت کلاینت‌ساید روی همه‌ی محتوا (گزارش‌ها، مطالب، «در یک نگاه»، رادار آینده، ویدیوکست/پادکست، رویدادها) می‌گردد و به صفحه‌ی جزئیاتِ هر مورد لینک می‌دهد.

### دستورات (در پوشه‌ی `frontend/`)
```bash
cd frontend
npm install
npm run dev            # سرورِ توسعه‌ی Vite (HMR)
npx tsc -b --noEmit    # فقط type-check (سریع‌ترین حلقه‌ی اعتبارسنجی)
npm run lint           # ESLint
npm run build          # tsc -b && vite build → خروجی در dist/
npm run preview        # پیش‌نمایشِ بیلدِ پروداکشن
```
برای دیدنِ دادهٔ واقعیِ پنل در حالتِ توسعه:
```bash
VITE_PANEL_API=https://cms-steelforesight.liara.run npm run dev
```
> هیچ فریم‌ورکِ تستی پیکربندی نشده؛ «تأیید» یعنی `tsc` تمیز + بازدیدِ سرورِ در حالِ اجرا.

---

## ۳. پنل مدیریت و بک‌اند (`panel/`)

سرورِ Express که هم API می‌دهد و هم رابطِ مدیریت (CMS) را سرو می‌کند.

### پشته‌ی فناوری
- **سرور:** Express 4 روی Node.js.
- **پایگاه داده:** PostgreSQL (لیارا) با ماژول `pg` (Pool روی `DATABASE_URL`). در `db.js` یک facadeِ شبیهِ `better-sqlite3` ساخته شده: `db.prepare(sql).get/all/run(...)` — **همه async و باید await شوند**. جداول و ایندکس‌ها در زمانِ استارت‌آپ به‌صورت idempotent ساخته/مهاجرت می‌شوند.
- **امنیت/احراز هویت:** `bcryptjs` (هشِ گذرواژه)، `jsonwebtoken` (کوکیِ HttpOnly با `Secure`/`SameSite` پشتِ TLS)، `helmet` (هدر/CSP)، `express-rate-limit` (محدودسازیِ ورود و فرمِ تماس). CORS با `ALLOWED_ORIGINS` کنترل می‌شود (و در توسعه هر `localhost`).
- **آپلود و تصویر:** `multer` (بافرِ حافظه) + `sharp` (چرخشِ EXIF، ریسایز تا ۲۰۰۰px و خروجیِ **WebP**). `pdf-parse` برای استخراجِ متنِ PDF.
- **ذخیره‌سازی:** **S3-compatible** (object storage لیارا) در صورتِ تنظیمِ متغیرها؛ وگرنه fallback به دیسکِ محلی `panel/uploads/`.
- **هوش مصنوعی:** SDKهای **OpenAI** و **Anthropic (Claude)** برای خلاصه‌سازی و استخراجِ دادهٔ کلیدی از اسناد.
- **رابطِ مدیریت:** SPA با **Vanilla JS** در `panel/public/` (بدون build). تب‌ها در دو گروه: **محتوا** (در یک نگاه، رادار آینده، ویدیوکست/پادکست، رویدادها، بنرها) و **کاربران** (کاربران سایت، خبرنامه).

### دستورات (در پوشه‌ی `panel/`)
```bash
cd panel
npm install
npm run seed     # ساختِ ادمینِ اولیه از روی .env (ADMIN_USERNAME/PASSWORD)
npm start        # node server.js → http://localhost:3001
npm run dev      # node --watch server.js
```

---

## ۴. پایگاه داده

جداولِ اصلی (PostgreSQL):

| جدول | کاربرد |
| :--- | :--- |
| `users` | ادمین‌های پنل با نقشِ `admin` یا `owner` |
| `articles` | مقالات/گزارش‌ها (مدلِ منعطف؛ با `category`/`type` تفکیک می‌شود) |
| `radar_items` | آیتم‌های «در یک نگاه» در ۵ دسته: market/tech/commodity/geo/energy |
| `radar_pages` | صفحاتِ «رادار آینده» (مقاله‌ی بلوکیِ هر زیرمنو) |
| `risk_signals` | سیگنال‌های ریسک با سطوحِ critical…opportunity |
| `events` | رویدادهای تقویم |
| `team_members` | اعضای تیم/خبرگان |
| `market_prices`, `market_chart_points` | قیمت‌ها و نمودارهای صفحه‌ی Market (**دستی، ادیت‌شونده در پنل**) |
| `banners`, `integrations`, `institute_stats`, `vision_items`, `advisory_board`, `plans`, `factory_reports` | بخش‌های مختلفِ محتواییِ سایت |
| `members` | اعضای ثبت‌نامیِ سایت (موبایل/OTP) + `last_login`, `is_active` |
| `purchases` | خریدِ گزارش‌های غیررایگانِ اعضا |
| `member_activity` | لاگِ فعالیتِ اعضا (بازدیدِ صفحه + کلیک) |
| `subscribers` | ایمیل‌های عضویت در خبرنامه (فرمِ فوتر) |

> جدولِ `prices` (اسکرپرِ قدیمیِ tgju) دیگر استفاده نمی‌شود؛ اسکرپرِ زنده حذف شده و صفحه‌ی Market از `market_prices` می‌خواند.

---

## ۵. احراز هویت و اعضا

دو نشستِ مجزا:
- **ادمینِ پنل:** کوکیِ `session` (جدولِ `users`). نقشِ `owner` می‌تواند ادمین‌ها و اعضا را حذف کند.
- **عضوِ سایت:** کوکیِ `member_session` (جدولِ `members`).

**ورود/ثبت‌نامِ اعضا با موبایل + کدِ یک‌بارمصرف (OTP):** ارسالِ پیامک با **کاوه‌نگار** (`KAVENEGAR_API_KEY`). در نبودِ کلید (محیطِ لوکال) کد در کنسولِ سرور چاپ می‌شود تا تست ممکن باشد. بازنشانیِ رمز هم از طریقِ SMS ممکن است.

**مدیریتِ کاربران در پنل** (تب «کاربران سایت»): فهرستِ اعضا با شماره و **آخرین ورود**، صفحه‌ی جزئیات (خریدها + **تایم‌لاینِ فعالیت: بازدید/کلیک**)، **مسدودسازی/رفعِ مسدودی** (`is_active`) و **حذف**. عضوِ مسدودشده در سمتِ سایت هم اثر می‌گیرد: `AuthContext` نشست را هنگامِ لود و بازگشتِ فوکوسِ تب با `/api/members/me` اعتبارسنجی می‌کند و در صورتِ `403` کاربر را خارج می‌کند.

---

## ۶. اتصال فرانت‌اند به پنل (Wiring)

فرانت‌اند هنگامِ استارت‌آپ، محتوای چند بخش را از پنل واکشی می‌کند (در `frontend/src/main.tsx` توابعِ `bootstrap*` فراخوانی می‌شوند) و در صورتِ در دسترس نبودنِ پنل به دادهٔ ایستای داخلِ `src/content` و `src/data` به‌عنوان fallback برمی‌گردد. نمونه‌ها: `/api/articles` (گزارش‌ها)، `/api/radar` (در یک نگاه)، `/api/events`، `/api/market-prices` و غیره. احراز هویتِ اعضا از طریقِ `AuthContext` و مسیرهای `/api/members/*` انجام می‌شود.

آدرسِ پنل از متغیرِ `VITE_PANEL_API` خوانده می‌شود (در پروداکشن هنگامِ build در Dockerfile مقدارِ `https://cms-steelforesight.liara.run` به باندل تزریق می‌شود).

---

## ۷. فهرست APIها

خواندنی‌ها عمومی‌اند؛ نوشتنی‌ها (POST/PUT/PATCH/DELETE) نیازمندِ کوکیِ نشست یا هدرِ `Authorization: Bearer <token>` هستند.

| متد | مسیر | احراز هویت | توضیح |
| :--- | :--- | :--- | :--- |
| POST | `/api/auth/login` `/logout` | — / — | ورود/خروجِ ادمین |
| GET | `/api/auth/me` | ادمین | مشخصاتِ ادمینِ جاری |
| GET/POST/PUT/DELETE | `/api/articles[...]` | خواندن آزاد / نوشتن ادمین | CRUD مقالات |
| GET/POST/PUT/DELETE | `/api/radar`, `/api/radar-pages`, `/api/events`, `/api/banners`, `/api/risks`, `/api/team`, `/api/market-prices` … | خواندن آزاد / نوشتن ادمین | CRUD بخش‌های محتوایی |
| POST | `/api/uploads`, `/api/uploads/raw` | ادمین | آپلودِ تصویر (→WebP) / ویدیو و PDF (→S3) |
| POST | `/api/admin/import` | ادمین | ایمپورتِ دادهٔ تحلیلیِ هوش مصنوعی |
| POST | `/api/members/otp/send` `/otp/verify` | — | ورود/ثبت‌نام با OTP |
| POST | `/api/members/register-verify` | — | تکمیلِ ثبت‌نام پس از تأییدِ کد |
| GET/PUT | `/api/members/me` | عضو | پروفایلِ عضو |
| GET | `/api/members/me/purchases[...]` | عضو | خریدها و دانلودِ گزارش |
| POST | `/api/members/activity` | عضو | ثبتِ فعالیت (بازدید/کلیک) |
| GET | `/api/members` `/api/members/:id` `/:id/activity` | ادمین | فهرست/جزئیات/فعالیتِ اعضا |
| PATCH/DELETE | `/api/members/:id` | ادمین/owner | مسدودسازی/حذفِ عضو |
| POST/GET/DELETE | `/api/newsletter[...]` | نوشتن آزاد / خواندن ادمین | عضویت در خبرنامه و مدیریتِ آن |
| POST | `/api/contact` | — | فرمِ تماس با ما |
| GET | `/api/health` | — | سلامتِ سرور |

---

## ۸. استقرار (Deployment)

هر دو اپ روی **لیارا (Liara)** مستقر می‌شوند (دو اپِ جدا).

### فرانت‌اند — اپِ `steelforesight`
خروجیِ استاتیک، با Dockerfileِ دو‌مرحله‌ای: مرحله‌ی Node برای `vite build` و سپس Nginxِ سبک برای سروِ `dist/` روی پورتِ **۷۸۶۰** (سازگار با Hugging Face Spaces).
```bash
cd frontend
liara deploy --app steelforesight --platform docker --port 7860 --build-location iran
```
`VITE_PANEL_API` هنگامِ build از طریقِ `ARG` در Dockerfile تزریق می‌شود.

### پنل — اپِ `cms-steelforesight`
```bash
cd panel
liara deploy --app cms-steelforesight --platform node --build-location iran
```
متغیرهای محیطیِ لازم (در کنترل‌پنلِ هاست):
- `DATABASE_URL` — اتصالِ PostgreSQL.
- `JWT_SECRET` — رشته‌ی تصادفیِ بلند (≥۳۲ کاراکتر).
- `ADMIN_USERNAME` / `ADMIN_PASSWORD` — برای `npm run seed`.
- `ALLOWED_ORIGINS` — دامنه‌ی فرانت برای عبور از CORS.
- `KAVENEGAR_API_KEY` — ارسالِ پیامکِ OTP.
- اختیاری: متغیرهای ایمیل و object storage (`LIARA_ENDPOINT`, `LIARA_BUCKET`, `LIARA_ACCESS_KEY`, `LIARA_SECRET_KEY`).