imen_pishghaman/README.md

# ایمن پیشگامان — مونوریپو (سایت + API + پنل مدیریت)

سایت ایمن پیشگامان به‌همراه بکند و پنل مدیریت محتوا. همه‌ی متن‌ها، تصاویر، دسته‌ها و محصولات سایت از پنل مدیریت قابل ویرایش‌اند.

| بخش | مسیر | فناوری |
|---|---|---|
| سایت | `apps/web` | Nuxt 4 (SSR + کش SWR)، Vue 3، Tailwind v4، Ant Design Vue، Pinia |
| API | `apps/api` | NestJS 12، Prisma 7، PostgreSQL، ذخیره‌ساز S3 (MinIO) |
| پنل مدیریت | `apps/admin` | Vue 3 + Vite، Ant Design Vue، Tailwind v4، Pinia، Vue Router |
| کد مشترک | `packages/shared` | اسکیماهای Zod و تایپ‌ها (مشترک بین هر سه اپ) |

ابزار مونوریپو: **pnpm workspaces + Turborepo**.

```
مرورگر ──► gateway (nginx)
            ├─ imenpishgaman.ir        → web  (Nuxt SSR، صفحات کش‌شده)
            ├─ admin.imenpishgaman.ir  → admin (فایل‌های استاتیک)
            ├─ /api/*                   → api  (NestJS) ──► PostgreSQL
            └─ /media/*                 → MinIO (تصاویر آپلودشده)

ذخیره در پنل ──► API ──► POST web:/_internal/revalidate ──► کش صفحات سایت پاک می‌شود
```

## ساختار پوشه‌ها

```
apps/
  web/                 سایت (همان طراحی قبلی؛ داده‌ها از API)
    app/stores/site.ts   محتوای سایت از GET /api/public/site (یک بار در هر رندر)
    app/plugins/api.ts   $api — در SSR آدرس داخلی API، در مرورگر /api
    server/routes/       sitemap.xml (از دیتابیس)، robots.txt، manifest، _internal/revalidate
  api/
    prisma/schema.prisma مدل داده؛ migrations/ کنار آن
    src/                 ماژول‌ها: auth, users, catalog, media, sections, contact, public, dashboard
    src/seed/            مقداردهی اولیه (محتوای فعلی سایت + ۸ دسته / ۸۹ محصول)
    seed-assets/         تصاویر اولیه که seed در MinIO آپلود می‌کند
    test/                تست‌های e2e
  admin/
    src/pages/           داشبورد، محصولات، دسته‌ها، بخش‌های سایت، پیام‌ها، رسانه، کاربران
    src/sections/        فرم اختصاصی هر بخش سایت
packages/shared/src/     sections.ts (اسکیمای بخش‌ها)، catalog.ts، admin.ts، icons.ts
docker/                  Dockerfile هر اپ و پیکربندی nginx
docker-compose.yml       استقرار production
docker-compose.dev.yml   PostgreSQL + MinIO برای توسعه
```

## راه‌اندازی محیط توسعه

پیش‌نیاز: Node.js 22.19 یا جدیدتر (۲۴ توصیه می‌شود)، Docker.

```bash
corepack enable pnpm          # در ویندوز بدون دسترسی ادمین:
                              # corepack enable pnpm --install-directory "%APPDATA%\npm"
pnpm install

pnpm infra:up                 # PostgreSQL روی 5433 و MinIO روی 9000 (کنسول: 9001)

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

pnpm db:migrate               # ساخت جدول‌ها
pnpm db:seed                  # محتوای اولیه + کاربر مدیر (ADMIN_PHONE / ADMIN_PASSWORD در apps/api/.env)

pnpm dev                      # هر سه اپ با هم
```

| آدرس | چیست |
|---|---|
| http://localhost:3000 | سایت |
| http://localhost:5173 | پنل مدیریت |
| http://localhost:4000/api | API |
| http://localhost:9001 | کنسول MinIO |

در توسعه، سرور Nuxt و Vite مسیرهای `/api` و `/media` را به API و MinIO پراکسی می‌کنند؛ در production همین کار را nginx انجام می‌دهد. به همین دلیل آدرس تصاویر همه‌جا به‌صورت `/media/...` ذخیره می‌شود.

### اسکریپت‌ها (از ریشه‌ی پروژه)

| دستور | کار |
|---|---|
| `pnpm dev` | اجرای همه‌ی اپ‌ها در حالت توسعه |
| `pnpm build` | build همه‌ی پکیج‌ها |
| `pnpm typecheck` | بررسی TypeScript همه‌ی پکیج‌ها |
| `pnpm test` | تست‌های e2e بکند (روی دیتابیس توسعه؛ داده‌های تست پاک می‌شوند) |
| `pnpm db:migrate` | ساخت/اعمال migration (`prisma migrate dev`) |
| `pnpm db:seed` | مقداردهی اولیه؛ اجرای دوباره چیزی را بازنویسی نمی‌کند |
| `pnpm db:studio` | Prisma Studio برای دیدن داده‌ها |
| `pnpm infra:up` / `infra:down` | روشن/خاموش کردن PostgreSQL و MinIO |

برای برگرداندن متن‌های سایت به محتوای اولیه: `SEED_OVERWRITE_SECTIONS=1 pnpm db:seed`.

## پنل مدیریت

- **محصولات**: افزودن/ویرایش، تصویر اصلی و گالری، توضیحات کامل، جدول مشخصات فنی، ویژگی‌های کلیدی، کاربردها، استانداردها، سایزها و مدل‌ها، برند و کشور سازنده، بسته‌بندی و حداقل سفارش، سئو، انتشار یا پیش‌نویس، کپی، مرتب‌سازی (با فیلتر یک دسته). هر محصول صفحه‌ی اختصاصی `/products/<اسلاگ>` دارد (گالری با بزرگ‌نمایی، مشخصات، محصولات مرتبط، دکمه‌ی درخواست قیمت که فرم تماس را با نام محصول پر می‌کند، JSON-LD نوع Product). بخش‌هایی که پر نشده‌اند در صفحه نمایش داده نمی‌شوند.
- **دسته‌بندی‌ها**: کاور، زیرگروه‌ها (فیلترهای صفحه‌ی دسته)، سئو، ترتیب نمایش.
- **بخش‌های سایت**: Hero، نوار متحرک، آمار، معرفی محصولات، درباره ما، خدمات، استانداردها، صنایع، نظرات، تماس، فوتر و تنظیمات سایت (تلفن، ایمیل، نشانی، ساعات کاری، شبکه‌های اجتماعی، سئوی پیش‌فرض).
- **پیام‌های تماس**: درخواست‌های فرم مشاوره‌ی سایت، با وضعیت جدید / خوانده‌شده / بایگانی.
- **کتابخانه رسانه**: همه‌ی تصاویر به‌صورت خودکار بهینه و به WebP تبدیل می‌شوند. تصویری که جایی استفاده شده قابل حذف نیست.
- **کاربران و نقش‌ها**: «مدیر کل» به همه‌چیز دسترسی دارد. «ویرایشگر» به‌جز کاربران و تنظیمات سایت، همه‌ی بخش‌ها را می‌بیند.

تغییرات پس از ذخیره، حداکثر ظرف چند ثانیه روی سایت دیده می‌شوند. اگر فراخوانی پاک‌کردن کش به هر دلیلی نرسد، صفحه‌ها در هر صورت هر ۶۰ ثانیه تازه می‌شوند.

**امنیت ورود**: access token کوتاه‌عمر (۱۵ دقیقه) فقط در حافظه‌ی مرورگر نگه داشته می‌شود و refresh token در کوکی httpOnly است. refresh token در هر استفاده عوض می‌شود. اگر یک توکن باطل‌شده دوباره استفاده شود، همه‌ی نشست‌های آن کاربر بسته می‌شوند. رمزها با argon2 ذخیره می‌شوند و تعداد تلاش برای ورود و ارسال فرم تماس محدود است.

## راهنمای توسعه

**افزودن فیلد به یک بخش سایت** (مثلاً یک متن جدید در Hero):
1. اسکیمای آن بخش را در `packages/shared/src/sections.ts` تغییر دهید. اگر فیلد اجباری است، مقدار پیش‌فرض بدهید (`text()`)، وگرنه داده‌های فعلی دیتابیس دیگر معتبر نیستند.
2. فیلد را به فرم همان بخش در `apps/admin/src/sections/` اضافه کنید.
3. در کامپوننت سایت (`apps/web/app/components/sections/`) از آن استفاده کنید.
4. مقدار اولیه را در `apps/api/src/seed/data/sections.ts` اضافه کنید.

یک اسکیمای Zod هم ورودی API را اعتبارسنجی می‌کند و هم فرم پنل را. برای همین پیام‌های خطا در هر دو یکسان و فارسی‌اند.

**تغییر مدل دیتابیس**: `apps/api/prisma/schema.prisma` را ویرایش کنید و `pnpm db:migrate` را اجرا کنید. اسم migration را می‌پرسد. فایل migration را هم commit کنید.

**آیکون‌ها**: آیکون‌های قابل‌انتخاب در پنل در `packages/shared/src/icons.ts` تعریف شده‌اند. برای افزودن آیکون جدید، آن را به همین لیست، به `apps/web/app/components/ui/DynamicIcon.vue` و به `apps/admin/src/components/icons.ts` اضافه کنید. این تکرار عمدی است تا فقط همین آیکون‌ها وارد باندل شوند.

**Ant Design و Tailwind**: استایل‌های Tailwind v4 داخل cascade layer هستند و CSS-in-JS آنت‌دیزاین بیرون از layer. بنابراین روی کامپوننت‌های antd کلاس ظاهری Tailwind نگذارید. در سایت، پالت رنگ در دو جا تعریف شده است: `@theme` در `main.css` و `palette` در `app/design/theme.ts`. هنگام تغییر، هر دو را هم‌گام کنید.

## استقرار (production)

```bash
cp .env.example .env            # همه‌ی رمزها و دامنه‌ها را تنظیم کنید
docker compose up -d --build
docker compose exec api node dist/seed/seed.js   # فقط بار اول
```

- کانتینر `gateway` روی پورت `HTTP_PORT` (پیش‌فرض 8080) گوش می‌دهد و هر دو دامنه (`SITE_DOMAIN` و `ADMIN_DOMAIN`) را سرو می‌کند. TLS را nginx یا Traefik روی سرور یا CDN جلوی آن تأمین می‌کند. هر دو دامنه باید به سرور اشاره کنند.
- سرویس یک‌باره‌ی `migrate` پیش از `api` اجرا می‌شود، migrationهای جدید را اعمال می‌کند و خارج می‌شود. این کار را `dist/migrate.js` انجام می‌دهد که هم‌ارز `prisma migrate deploy` است و از همان جدول `_prisma_migrations` استفاده می‌کند، پس Prisma CLI روی سرور لازم نیست.
- نام پروژه‌ی Compose ثابت و برابر `imen` است، تا با `docker-compose.dev.yml` (PostgreSQL و MinIO توسعه) هیچ کانتینر یا volume مشترکی نداشته باشد.
- سرویس `backup` هر روز یک dump از دیتابیس در `./backups` می‌سازد و dumpهای قدیمی‌تر از ۱۴ روز را پاک می‌کند. بازگردانی:
  `docker compose exec -T postgres pg_restore -U imen -d imen --clean < backups/imen-YYYY-MM-DD.dump`
- از فایل‌های MinIO (volume `miniodata`) هم جداگانه بکاپ بگیرید.

**روی سرور چیزی نصب یا build نمی‌شود.** imageها فقط خروجی آماده‌ای را که در ریپو commit شده کپی می‌کنند، پس سرور به رجیستری npm نیازی ندارد. قبل از هر push روی سیستم توسعه `pnpm build` بگیرید و خروجی‌ها را هم commit کنید:
- `apps/web/.output` (همراه `server/node_modules`)، `apps/admin/dist` و `apps/api/.output`.
- `apps/api/.output` را `apps/api/scripts/bundle.mjs` می‌سازد. کد API و همه‌ی وابستگی‌های JS در آن bundle می‌شوند و فقط پکیج‌های native (`sharp` و `@node-rs/argon2`) با باینری Linux (Alpine، x64) کنارش کپی می‌شوند. این باینری‌ها را `supportedArchitectures` در `pnpm-workspace.yaml` موقع `pnpm install` دانلود می‌کند.
- آدرس سایت در لینک‌های پنل ادمین موقع build از `apps/admin/.env.production` خوانده می‌شود.

**Object Storage ابرآروان (یا هر S3 دیگر) به‌جای MinIO**: در سرویس `api`، مقادیر `S3_ENDPOINT`، `S3_BUCKET` و کلیدها را تنظیم کنید و `S3_ENSURE_BUCKET` را `false` بگذارید. `MEDIA_PUBLIC_URL` را روی آدرس عمومی باکت یا CDN بگذارید. بعد از آن به سرویس `minio` و مسیر `/media` در gateway نیازی نیست.

## کارهای باقی‌مانده و پیشنهادها

- **پر کردن جزئیات محصولات** (توضیحات کامل، مشخصات فنی، استانداردها و ...) از پنل؛ این فیلدها برای محصولات فعلی خالی‌اند و فعلاً صفحه‌ی محصول توضیح دسته را نشان می‌دهد.
- عکس برای ۱۷ محصول پوشاک کار و تجهیزات ترافیک (فعلاً کاور دسته نمایش داده می‌شود).
- **ایمپورت/اکسپورت اکسل** محصولات برای ورود دسته‌جمعی.
- **اعلان پیام تماس جدید** با ایمیل، پیامک یا ربات بله/تلگرام.
- پوشه‌ی `محصولات/` (عکس‌ها و فایل‌های Word خام) و فایل‌های `_dev.log` و `landing-nextjs-seo.skill` بهتر است از ریپو خارج شوند.
- لوگوی رسمی (`apps/web/public/images/logo.png`)، تصویر اختصاصی Open Graph با ابعاد ۱۲۰۰×۶۳۰ و آیکون‌های PNG برای PWA.
- CI روی سرور git (`pnpm typecheck && pnpm build && pnpm test`).