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.

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.