api/AGENTS.md

# AGENTS.md — SuperAdmin آبشده + همکار + خانگی

این فایل برای ادامه کار در Cursor است (از جمله Workspace سه‌پروژه‌ای).  
قبل از تغییر معماری یا اتصال API، این سند را بخوان.

## پروژه‌ها

| نام | مسیر تقریبی | نقش |
|-----|-------------|-----|
| SuperAdminAbshode | `E:\projeha\SuperAdminAbshode` | کنترل‌پنل مرکزی شرکت |
| Hamkar | `E:\projeha\Hamkar` | محصول همکار (نسخه‌های فروشی) |
| Khanegi | `E:\projeha\Khanegi` (عمدتاً KhanegiModular) | محصول خانگی |

Workspace پیشنهادی: `E:\projeha\Abshode-suite.code-workspace`

## هدف کسب‌وکار

مدیر شرکت نرم‌افزاری است؛ محصولات به‌صورت نسخه فروشی (white-label) فروخته می‌شوند.  
نیاز اصلی: مدیریت متمرکز نسخه‌ها، برند، ظاهر، پیامک، سرور/تمدید/پشتیبانی (جایگزین گوگل‌شیت).

## تصمیم‌های قطعی تا الان

1. **استک سوپرادمین:** NestJS + Prisma + Vue 3 + Ant Design Vue + فونت Dana — نه Laravel.
2. **UI:** داشبورد نرم روشن، RTL، بدون سایدبار منو؛ کارت‌های ماژول در صفحه اول.
3. **منبع حقیقت برند/ظاهر:** سوپرادمین و `GET /get_user` (نه SSH/DB برای روزمره).
4. **`/get_user` عمومی است** → رمز/گلوگاه SMS داخلش نرود.
5. **SMS:** پنل کامل داخل سوپرادمین ساخته می‌شود؛ **فعلاً پنل SMS داخل همکار/خانگی دست نخورده می‌ماند** تا تست جواب بدهد؛ بعد حذف/غیرفعال.
6. **منبع حقیقت SMS (پیشنهاد قطعی):** کیف پول / تعرفه / مسدودسازی در سوپرادمین؛ ارسال همچنان با `SmsGatewayService` همان نسخه.
7. **مسئول فنی:** برای برند به DB لوکال نیاز نیست؛ اطلاعات رجیستری از `/get_user`؛ SMS سوپرادمین از صفر.
8. **برای اتصال دوطرفه واقعی** اپ‌ها به سوپرادمین، این پروژه باید روی سرور با دامنه HTTPS باشد. لوکال برای توسعه و push به نسخه‌های آنلاین کافی است.
9. **دیتابیس پروداکشن:** PostgreSQL (نه SQLite). دامنه هدف: `https://adm.montzar.ir` روی سرور مشترک montime؛ API روی پورت `3010`. جزئیات: `deploy/DEPLOY.md`.

## وضعیت فعلی کد سوپرادمین

### ساختار
- `apps/api` — NestJS + Prisma (**PostgreSQL**؛ تاریخچه SQLite در `prisma/migrations_sqlite_archive/`)
- `apps/web` — Vue 3 + Vite + Ant Design Vue
- ورود پیش‌فرض: موبایل `SEED_ADMIN_MOBILE` / `SEED_ADMIN_PASSWORD` (مثلاً `09128081392` / `Admin@12345`)
- دیپلوی: `deploy/` داخل همین ریپوی API (nginx + pm2 + راهنما)

### قابلیت‌های پیاده‌شده
- Auth JWT، CRUD نسخه‌ها (Tenant)، Audit
- مدیران سوپرادمین: نام / نام‌خانوادگی / موبایل / رمز؛ ورود با موبایل؛ صفحه `/admins`
- پیامک هشدار مدیران از API مرکزی اس‌ام‌اس رایگان (`CENTRAL_SMS_*` → `createsms`)؛ رویدادهای نسخه و کیف پول SMS
- پنل سرور: اختصاصی یا مدیریت‌شده؛ نام/مشخصات/قیمت/مدت (۱،۳،۶،۱۲ ماه)؛ هشدار SMS نزدیک انقضا (پیش‌فرض ۳ روز، روزانه تا تمدید)
- پنل افزونه: هر نسخه ۰..N افزونه (`PluginSubscription` + `PluginCharge`)؛ نام اجباری + مشخصات/قیمت/مدت ۱،۳،۶،۱۲ ماه؛ هشدار SMS مثل سرور؛ صفحات `/plugins` و `/plugins/:tenantId`
- `GET /get_user` با تطبیق دامنه اصلی + آرایه `domains` + `app_ui_config` برای خانگی
- `GET /get_version?domain=` — ورژن همان نسخه فروشی (`Tenant.appVersion`)؛ تنظیم از صفحه مدیریت نسخه؛ جایگزین `nerkh.gold/get_version`
- ایمپورت نسخه‌ها از `apps/api/prisma/data/users.json` (`npm run prisma:import-users`)
- تشخیص محصول: `app.` / `khanegi.` → خانگی؛ `hamkar.` → همکار؛ overrides دستی در اسکریپت ایمپورت
- پنل SMS مستقل سوپرادمین: `SmsAccount` + `SmsLedger` (موجودی، شارژ، تعرفه، بلاک، آستانه‌های رنگی، گلوگاه)
- رنگ موجودی: سبز >100000، زرد 10000–100000، قرمز <10000 (ریال)
- داشبورد: ۵ نسخه کم‌موجودی؛ صفحه SMS: کارت‌ها → جزئیات در `/sms/:tenantId`
- ظاهر اپ خانگی: صفحه `UiConfigPage` برای `appUiConfig`؛ بک‌فیل از رجیستری/`users.json` با `npm run prisma:backfill-appearance`؛ در فرانت: `showNotifications` / `header.visible` / `startRoute`
- ظاهر اپ همکار: `/versions/:id/ui-hamkar`؛ رنگ‌ها + حالت رجیستری (`registryMode`)؛ `settingsManaged` باید true باشد تا `ui_settings` بیاید (وگرنه لاراول می‌ماند)

### مهم
- موجودی SMS اولیه **دمو** بود تا رنگ‌ها دیده شوند؛ منبع واقعی همکار/خانگی نیست مگر بعداً وصل شود.
- چند دامنه دستی اصلاح شده (مثل 24gold.ir، limangold.ir، vahid.gold).
- چند نسخه با تأیید کاربر از همکار به خانگی منتقل شده‌اند (لیست در `FORCE_KHANEGI` داخل `import-users.ts`).

## معماری هدف اتصال به همکار/خانگی

دو جهت API:

### A) اپ‌ها → سوپرادمین
- `GET /get_user` — برند و ظاهر (موجود)
- بعدی: `GET/POST` وضعیت SMS (`status` / `consume`) با `remoteApiToken`

### B) سوپرادمین → اپ‌ها
- `GET/POST /super/settings` روی Laravel هر نسخه — تنظیمات مدیریتی
- اختیاری: reload برند / health

احراز هویت: `Tenant.remoteApiToken` در سوپرادمین + همان توکن روی نسخه.

### منبع حقیقت پیشنهادی

| موضوع | منبع |
|------|------|
| برند / دامنه / لوگو / رنگ | سوپرادمین `/get_user` |
| `app_ui_config` خانگی | سوپرادمین → مصرف در فرانت خانگی |
| ورژن اپ / رفرش اجباری کش | سوپرادمین `/get_version` (per tenant: `Tenant.appVersion`) |
| کیف پول / تعرفه / بلاک SMS | سوپرادمین |
| ارسال SMS | `SmsGatewayService` همان نسخه |
| پنل SMS داخل محصولات | فعلاً دست‌نخورده |

## فازهای بعدی (به ترتیب)

1. **دیپلوی سوپرادمین** روی `adm.montzar.ir` (migrate + pm2 + nginx) — DB `superadmin` آماده است.
2. **پایلوت برند:** یک نسخه تست فقط از `/get_user` سوپرادمین بوت شود.
3. **ظاهر خانگی:** مصرف کامل `app_ui_config` در خانگی.
4. **API `/super/*` روی Laravel همکار و خانگی** با middleware توکن.
5. **SMS دوطرفه:** status/consume در سوپرادمین + هوک قبل/بعد ارسال در محصولات.
6. بعد از پایداری: کاهش/حذف پنل SMS داخلی محصولات.

## قواعد کار ایجنت

- بدون درخواست صریح کاربر: commit نکن، force push نکن، پنل SMS همکار/خانگی را حذف نکن.
- تغییرات همکار و خانگی را فقط وقتی کاربر صریحاً خواست؛ فعلاً اولویت سوپرادمین + طراحی قرارداد API است.
- در Workspace چندریشه: قبل از ادیت بگو در کدام ریشه کار می‌کنی (`SuperAdminAbshode` / `Hamkar` / `Khanegi`).
- **امنیت (همیشه):** secret / توکن / رمز را در UI، لاگ، `.env.example`، commit، یا پاسخ چت قرار نده؛ fallback هاردکد برای secret نگذار؛ رمز را فقط hash ذخیره کن و در API برنگردان؛ ورودی‌ها را validate/normalize کن (مثل موبایل).
- **تاریخ/ساعت:** همیشه شمسی (جلالی) و به وقت ایران (`Asia/Tehran`) — انتخابگر تاریخ شمسی و فرمت نمایش از `utils/datetime` / `iran-time.util`.
- رمزها و secretهای `users.json` و `CENTRAL_SMS_SECRET` را وارد UI/لاگ عمومی نکن.
- Prisma روی ویندوز: اگر `EPERM` روی `query_engine`، اول API را متوقف کن بعد `prisma generate`.

## اجرای لوکال

`DATABASE_URL` باید PostgreSQL باشد (Docker لوکال یا DB سرور). نمونه: `.env.example`.

```bash
cd E:\projeha\SuperAdminAbshode\apps\api
npx prisma migrate deploy
npm run start:dev

cd E:\projeha\SuperAdminAbshode\apps\web
npm run dev
```

- Web: http://localhost:5173/
- API: http://localhost:3001/

## چت اول در Workspace جدید — پیشنهاد متن

> ادامه کار سوپرادمین آبشده با همکار و خانگی.  
> حتماً `SuperAdminAbshode/AGENTS.md` (یا `AGENTS.md` داخل ریپوی API) را بخوان.  
> تصمیم‌ها و وضعیت فعلی همانجاست؛ از صفر مشورت نکن مگر برای مرحله بعد (پایلوت API / دیپلوی).

## تاریخ به‌روزرسانی

2026-07-30 — Prisma → PostgreSQL؛ DB `superadmin` روی سرور montime؛ deploy برای `adm.montzar.ir`.
2026-07-25 — جمع‌بندی گفتگوهای ساخت پنل، ایمپورت نسخه‌ها، SMS مستقل، و نقشه اتصال API.