# Master Prompt — MicroLearning Super Admin Panel Redesign می‌خواهم پنل **Super Admin / Platform Admin** پروژه MicroLearning را به‌صورت کامل، مرحله‌ای و کنترل‌شده اصلاح و ارتقا دهی. این پروژه نباید صرفاً یک UI Redesign باشد. هدف این است که پنل Super Admin به یک **Platform Operations & Administration Console** واقعی تبدیل شود. Super Admin باید بتواند کل پلتفرم را از نظر: * Organizations * Subscriptions * Platform Usage * Storage * AI * Jobs & Queues * Health * Audit * Security * Platform Settings مدیریت و مانیتور کند. --- # اجرای پروژه این پروژه باید در **۶ فاز** انجام شود: ```text PHASE 0 Admin Role, Security & Critical Bug Stabilization PHASE 1 Organizations & Subscription Management PHASE 2 Admin Dashboard & Platform Overview PHASE 3 Platform Operations: Storage, AI, Health, Jobs & Backups PHASE 4 Audit, Security, Administrators & Platform Settings PHASE 5 Responsive, Accessibility, QA & Production Hardening ``` هر Phase را جداگانه انجام بده. بعد از پایان هر Phase: 1. تغییرات را کامل کن. 2. Regression را بررسی کن. 3. Backend Tests را اجرا کن. 4. Frontend Tests را اجرا کن. 5. Lint را اجرا کن. 6. Typecheck را اجرا کن. 7. Build را اجرا کن. 8. `git diff` را بررسی کن. 9. فایل‌های تغییرکرده را اعلام کن. 10. Bugs Fixed را گزارش کن. 11. Remaining Issues را گزارش کن. 12. متوقف شو. بدون دستور: > برو فاز بعد وارد Phase بعد نشو. --- # CHANGE SAFETY PROTOCOL ## Working Code Is Sacred اگر بخشی: * سالم است، * Test آن سبز است، * Security issue ندارد، * و مانع Phase فعلی نیست، فقط برای Clean Code یا Preference معماری آن را تغییر نده. --- # Minimum Necessary Change برای هر Issue کمترین تغییر لازم را انجام بده. از Refactor گسترده unrelated جلوگیری کن. --- # Scope Lock در ابتدای هر Phase اعلام کن: ```text Expected files to change Affected modules Affected APIs Affected permissions Expected behavior changes Behavior that must remain unchanged ``` اگر Issue دیگری پیدا شد که ضروری نیست: ```text Deferred Technical Debt ``` ثبتش کن و فعلاً تغییر نده. --- # Never Hide Security in Frontend Hide کردن Menu یا Route امنیت نیست. تمام محدودیت‌های Super Admin / Tenant باید در Backend نیز enforce شوند. --- # Super Admin Architecture قاعده اصلی: ```text Super Admin ↓ Platform Scope ↓ All Organizations Metadata ``` Super Admin نباید به‌عنوان User یک Tenant عمل کند مگر Feature مشخص و امنی مانند Impersonation بعداً طراحی شود. Super Admin: ```text organization_id = null ``` را به‌عنوان حالت معتبر Platform Level در نظر بگیر. --- # PHASE 0 — Admin Role, Security & Critical Bug Stabilization ## هدف قبل از Redesign، رفتار Role و باگ‌های فعلی پنل Admin تثبیت شوند. --- # 1. Admin Role Audit تمام موارد مربوط به `super_admin` را پیدا کن: ```text Role Permissions Middleware Policies Route Guards Platform Routes Tenant Routes Frontend navigation Auth Context ``` بررسی کن Super Admin نباید اشتباهاً Tenant API را صدا بزند. --- # 2. Fix Admin Notification Bug در حال حاضر بررسی کن آیا: ```text WorkspaceShell ↓ NotificationPopover ↓ GET /notifications ``` برای Super Admin اجرا می‌شود. اگر `/notifications` نیازمند Tenant Scope است و Super Admin: ```text organization_id = null ``` دارد، این رفتار را اصلاح کن. راه‌حل مطلوب: اگر Platform Notifications هنوز وجود ندارد: * Notification Bell برای Super Admin نمایش داده نشود. اگر Platform Notifications نیاز است: API مستقل ایجاد کن: ```text /api/v1/platform/notifications ``` Tenant Notifications و Platform Notifications را قاطی نکن. --- # 3. Unknown Admin Route تمام `/admin/*` routeها را بررسی کن. URL نامعتبر مثل: ```text /admin/abc ``` نباید Runtime Error ایجاد کند. ایجاد کن: ```text AdminNotFound ``` یا redirect امن. --- # 4. Capability-aware Routing Hidden Navigation کافی نیست. اگر Deployment یا Feature Flag اجازه صفحه‌ای را نمی‌دهد، direct URL نیز باید صحیح مدیریت شود. به‌خصوص بررسی کن: ```text Organizations Subscriptions Platform settings ``` --- # 5. Settings Stale State Bug Platform Settings را بررسی کن. اگر Save هر Field بلافاصله object قدیمی را دوباره ارسال می‌کند و ممکن است Update قبلی overwrite شود، اصلاح کن. پیشنهاد مطلوب: ```text Edit locally ↓ Dirty state ↓ Save Changes ``` نمایش: ```text Unsaved changes ``` تا Save موفق. --- # 6. Permission Tests Test بنویس که: ### Super Admin بتواند: ```text Platform APIs Organization metadata Platform settings Audit Platform usage ``` ### Userهای Tenant نتوانند: ```text Platform APIs Platform settings Organization-wide platform data ``` و Super Admin هم Tenant-scoped endpoint نامناسب را بدون context صحیح استفاده نکند. --- ## Acceptance Criteria Phase 0 * Notification 403 loop حذف شده. * Unknown admin URL crash ندارد. * Platform/Tenant scope مشخص است. * capability-aware routing وجود دارد. * Settings overwrite bug رفع شده. * Authorization tests وجود دارد. * unrelated feature تغییر نکرده. متوقف شو. --- # PHASE 1 — Organizations & Subscription Management ## هدف Organization Management و Subscription Management از حالت نمایشی به ابزار مدیریتی واقعی تبدیل شوند. --- # Organizations Page صفحه Organizations باید این امکانات را داشته باشد: ```text Search Status Filter Plan Filter Sorting Pagination ``` Backend pagination metadata را حفظ کن. Frontend نباید فقط `data` را بردارد و `meta` را دور بیندازد. --- # Organization Table Columns پیشنهادی: ```text Organization Status Plan Users Storage AI Usage Subscription Expiry Last Activity ``` Actionها: ```text View Edit Subscription Usage Suspend / Activate ``` فقط در صورت support backend. --- # Organization 360° Page برای هر Organization یک صفحه جزئیات ایجاد کن: ```text Organization → Overview Subscription Users Usage Storage AI Activity Audit Settings ``` این صفحه باید Platform View باشد. Super Admin نباید برای دیدن اطلاعات سازمان وارد Tenant Workspace شود. --- # Organization Overview نمایش: ```text Organization Name Status Created Plan Users Storage AI consumption Subscription Recent activity ``` --- # Organization Lifecycle در صورت support backend: ```text Create Edit Activate Suspend ``` Delete hard را فقط در صورت Business Requirement واقعی اضافه کن. Prefer: ```text Suspend Archive ``` برای سیستم عملیاتی. --- # Subscription Management صفحه Subscriptions فعلی را از summary ساده خارج کن. Table: ```text Organization Plan User limit Storage limit AI limit Start date Expiry Status ``` --- # Subscription Actions در صورت support business model: ```text Create subscription Change plan Extend Change limits Suspend Reactivate ``` تمام تغییرات باید Audit شوند. --- # Limits Subscription باید در صورت وجود model مناسب این محدودیت‌ها را مدیریت کند: ```text Users / Seats Storage AI credits / usage Features Expiry ``` اگر backend مدل آنها را ندارد، بدون طراحی داده درست fake UI نساز. --- # Expiry Awareness Statusهایی مثل: ```text Active Expiring Soon Expired Suspended ``` نمایش داده شوند. --- # Confirmation برای عملیات مهم مثل Suspend: Confirmation Dialog واضح: ```text Suspend organization? Users will lose access to the platform. [Cancel] [Suspend] ``` --- ## Acceptance Criteria Phase 1 * Pagination Organizations صحیح است. * Search و Filters وجود دارند. * Organization 360° وجود دارد. * Edit Organization قابل دسترسی است. * Subscription واقعی قابل مدیریت است. * Subscription summary خام حذف شده. * limits شفاف هستند. * عملیات حساس Audit می‌شوند. متوقف شو. --- # PHASE 2 — Admin Dashboard & Platform Overview ## هدف Dashboard از JSON Surface به **Platform Control Center** تبدیل شود. --- # حذف Generic JSON UI Dashboard نباید raw key/value یا JSON objectهای nested را مستقیماً نمایش دهد. `JsonSurface` را برای Dashboard اصلی استفاده نکن مگر برای Debug Tool داخلی. --- # Dashboard Structure Layout پیشنهادی: ```text Platform Overview ↓ Critical KPIs ↓ Needs Attention ↓ Organizations Health ↓ Subscription Health ↓ Storage ↓ AI ↓ System Health ↓ Recent Activity ``` --- # KPI Cards KPIهای اصلی: ```text Organizations Active Organizations Users Storage Used AI Jobs Failed Jobs Active Subscriptions ``` KPIها compact باشند. --- # Trend فقط وقتی داده واقعی historical وجود دارد: ```text +8% this month -3% failed jobs ``` نمایش بده. Trend جعلی نساز. --- # Needs Attention یکی از مهم‌ترین قسمت‌ها. مثال: ```text 3 AI jobs failed 2 organizations are above 90% storage 2 subscriptions expire within 7 days Queue worker unavailable Backup overdue ``` هر Item Action مستقیم داشته باشد: ```text Investigate View organization View jobs View subscription ``` --- # Platform Activity نمایش eventهای مهم: ```text Organization created Subscription changed Platform setting changed AI provider failed Admin action ``` --- # Dashboard Refresh نمایش: ```text Last updated Refresh ``` از polling بی‌دلیل سریع استفاده نکن. اگر polling وجود دارد adaptive باشد. --- # Loading/Error هر Widget: ```text Loading Error Empty Success ``` را مستقل مدیریت کند. Failure یک Widget کل Dashboard را از کار نیندازد. --- # Responsive Dashboard در Mobile اولویت: ```text Needs Attention ↓ KPIs ↓ Critical Operations ↓ Activity ``` باشد. --- ## Acceptance Criteria Phase 2 * Dashboard خام نیست. * JSON مستقیم نمایش داده نمی‌شود. * Needs Attention وجود دارد. * Platform Health واضح است. * KPIها واقعی‌اند. * dashboard actionable است. * responsive صحیح است. * unnecessary polling ندارد. متوقف شو. --- # PHASE 3 — Platform Operations ## هدف Storage، AI، System Health، Jobs و Backup واقعاً Operational شوند. --- # 1. Storage صفحه Storage باید حداقل نمایش دهد: ```text Total Used Configured Capacity Usage % Growth ``` Breakdown در صورت داده واقعی: ```text Images Videos Documents Exports Certificates Other ``` --- # Storage by Organization Table: ```text Organization Used Quota Percentage Trend Status ``` Status: ```text Healthy Warning Critical ``` --- # Storage Alerts Thresholdهای configurable یا منطقی: ```text 80% 90% 95% ``` در صورت نیاز. --- # 2. AI Usage AI صفحه عملیاتی واقعی باشد. KPIها: ```text Requests Successful Failed Queued Avg latency ``` در صورت داده: ```text Tokens Credits Estimated cost ``` --- # Provider Breakdown مثلاً: ```text Ollama OpenAI LM Studio vLLM ``` فقط providerهای واقعی. --- # Model Usage در صورت داده واقعی: ```text Model Requests Failures Latency ``` --- # Organization AI Usage Table: ```text Organization Requests Success Failure Usage ``` --- # AI Failures لیست خطاهای اخیر: ```text Organization Provider Model Error Time Retry status ``` Secretها را log/display نکن. --- # 3. System Health این صفحه نباید صرفاً System Info باشد. Health Check واقعی برای: ```text Application Database Cache Queue Scheduler Storage Email AI Provider ``` در صورت وجود: ```text Redis Search Object Storage ``` --- # Health State نمایش: ```text Healthy Warning Critical Unknown ``` با: ```text Last checked Latency Details ``` --- # 4. Jobs & Queues صفحه اختصاصی: ```text Jobs & Queues ``` نمایش: ```text Queued Processing Failed Completed ``` اگر Laravel failed_jobs وجود دارد، لیست امن آن را نمایش بده. Actions فقط در صورت امن بودن: ```text Retry Retry all selected ``` Delete failed jobs فقط با permission و confirmation. --- # 5. Backups اگر Backup system واقعاً وجود دارد: صفحه: ```text Backups ``` نمایش: ```text Last successful backup Last failed backup Backup size Storage destination Schedule ``` اگر Backup هنوز پیاده‌سازی نشده، fake feature نساز. فقط readiness یا setup requirement گزارش کن. --- # 6. Platform Usage یک Usage Overview ایجاد کن: ```text Organizations Users Courses Assets Storage AI Jobs ``` Historical chart فقط در صورت وجود data. --- ## Acceptance Criteria Phase 3 * Storage operational است. * AI Usage کاربردی است. * Health واقعی است. * Jobs قابل مانیتور هستند. * Backup وضعیت واقعی دارد. * raw JSON نمایش داده نمی‌شود. * secrets در UI/log نمایش داده نمی‌شوند. * performance مناسب است. متوقف شو. --- # PHASE 4 — Audit, Security, Administrators & Platform Settings ## هدف پنل Admin برای Governance و Security قابل اتکا باشد. --- # 1. Audit Log Audit را از آخرین 20 event ساده خارج کن. امکانات: ```text Pagination Search Actor Action Organization Entity Date Range IP ``` --- # Audit Details روی Event کلیک: ```text Actor Action Organization Entity Type Entity ID Time IP Metadata ``` Sensitive data را mask کن. --- # Audit Coverage بررسی کن عملیات مهم Audit می‌شوند یا نه: ```text Organization Create / Update / Suspend Subscription changes Platform Settings Admin actions Role changes Security changes AI configuration changes ``` اگر نیستند، centralized audit approach اضافه کن بدون اینکه کل پروژه را rewrite کنی. --- # 2. Administrators اگر Business Requirement اجازه می‌دهد، صفحه: ```text Platform Administrators ``` ایجاد کن. نمایش: ```text Name Email Status Last login Created ``` اگر Super Admin Management فعلاً product requirement نیست، fake feature ایجاد نکن. --- # 3. Platform Settings Settings را گروه‌بندی کن. پیشنهاد: ```text General Deployment Organizations Subscriptions Storage AI Email Notifications Security Maintenance ``` فقط settingهای واقعی را نمایش بده. --- # Settings Save Pattern از Auto Save خطرناک جلوگیری کن. Pattern: ```text Edit ↓ Unsaved changes ↓ Save Changes ``` در صورت ترک صفحه: ```text You have unsaved changes. ``` در صورت نیاز. --- # Destructive Settings Settingهایی که impact مهم دارند Confirmation بخواهند. مثلاً: ```text Disable external AI Enable maintenance mode ``` --- # 4. Maintenance Mode در صورت پشتیبانی واقعی: ```text Maintenance mode Maintenance message Expected end time ``` ولی کاربر Admin را accidentally lock out نکن. --- # 5. Security Settings در صورت موجود بودن زیرساخت: ```text Session policy Authentication Rate limits Allowed domains Security events ``` ولی architecture جدید سنگین بدون requirement ایجاد نکن. --- ## Acceptance Criteria Phase 4 * Audit pagination دارد. * Filters دارد. * operations مهم Audit می‌شوند. * Sensitive data mask می‌شود. * Settings grouped است. * stale overwrite وجود ندارد. * Save state واضح است. * Admin governance بهتر شده. متوقف شو. --- # PHASE 5 — Responsive, Accessibility, QA & Production Hardening ## هدف Super Admin Panel برای Release آماده شود. --- # Responsive QA Viewportها: ```text 375 430 768 1024 1280 1440 1920 ``` را بررسی کن. --- # Mobile Admin Super Admin Desktop-first است، اما Mobile نباید شکسته باشد. روی Mobile حداقل این کارها ممکن باشند: ```text View dashboard View alerts View organizations View organization status View health View failed jobs ``` عملیات بسیار پیچیده می‌توانند desktop-preferred باشند. --- # Navigation Desktop: ```text Collapsible Sidebar ``` Mobile: ```text Drawer ``` --- # Proposed Navigation ساختار پیشنهادی: ```text OVERVIEW Dashboard CUSTOMERS Organizations Subscriptions PLATFORM Usage Storage AI & Models OPERATIONS System Health Jobs & Queues Backups SECURITY Audit Logs Administrators CONFIGURATION Platform Settings ``` اگر Feature واقعاً موجود نیست نمایش نده. --- # Accessibility بررسی: ```text Keyboard Focus ARIA Contrast Tables Dialog Drawer Form labels Error messages Status indicators ``` رنگ تنها Indicator نباشد. --- # RTL/LTR فارسی: ```text RTL ``` انگلیسی: ```text LTR ``` بررسی کن: ```text Tables Pagination Breadcrumb Icons Charts Drawers ``` --- # Dark Mode تمام صفحات Admin را بررسی کن: ```text Dashboard Organizations Subscriptions Storage AI Health Jobs Audit Settings ``` --- # Security Testing دوباره بررسی کن: ```text Platform/Tenant boundary IDOR Privilege escalation Admin route access Settings authorization Export leakage Sensitive logs Secrets ``` --- # Performance بررسی: ```text Dashboard request count N+1 queries Organization pagination Over-fetching Polling Large audit payload AI metrics queries ``` --- # Smoke Test Scenarios ## Scenario 1 ```text Super Admin Login → Dashboard → Needs Attention → Organization ``` ## Scenario 2 ```text Organizations → Search → Pagination → Organization 360 → Edit ``` ## Scenario 3 ```text Subscriptions → Organization → Modify subscription → Save → Audit ``` ## Scenario 4 ```text AI → View failures → Inspect provider ``` ## Scenario 5 ```text Health → Detect unhealthy service → View details ``` ## Scenario 6 ```text Jobs → Failed job → Retry ``` اگر retry support دارد. ## Scenario 7 ```text Settings → Change value → Unsaved state → Save → Reload ``` ## Scenario 8 ```text Audit → Filter → Open event ``` --- # Unauthorized Tests Tenant user نباید بتواند: ```text Access /admin Access platform APIs Read other organizations Modify subscriptions Read platform audit Change platform settings ``` --- # Quality Gate Backend: ```bash php artisan test ``` در صورت وجود: ```bash ./vendor/bin/pint --test ``` Frontend: ```bash npm run lint npm run typecheck npm test npm run build ``` همه باید سبز باشند. --- # Final Report در پایان Phase 5 گزارش کامل بده: ## Bugs Fixed | Issue | Severity | Status | ## Security Improvements ## Organization Management Improvements ## Subscription Improvements ## Dashboard Improvements ## Storage Improvements ## AI Operations Improvements ## Health Improvements ## Jobs Improvements ## Audit Improvements ## Settings Improvements ## Responsive Improvements ## Accessibility Improvements --- # Final Test Results Backend: ```text Tests: Assertions: Failures: ``` Frontend: ```text Test Files: Tests: Lint: Typecheck: Build: ``` --- # Remaining Technical Debt فقط موارد واقعی باقی‌مانده. Severity: ```text High Medium Low ``` --- # Admin Panel Score از 10 امتیاز بده: ```text Platform Navigation Dashboard Organization Management Subscriptions Storage Operations AI Operations System Health Jobs & Queues Audit Settings Security Responsive Accessibility Performance ``` در نهایت: ```text Super Admin Experience Score: XX/100 ``` و یکی از این وضعیت‌ها: ```text NOT READY STAGING READY PRODUCTION READY WITH CONDITIONS PRODUCTION READY ``` --- # قوانین نهایی ## 1 Super Admin را با Tenant Admin قاطی نکن. ## 2 Platform API و Tenant API تفکیک شوند. ## 3 Hide کردن UI Security Control نیست. ## 4 Raw JSON نباید UI نهایی باشد. ## 5 هر صفحه باید Actionable باشد. ## 6 Metric جعلی نساز. ## 7 Chart بدون historical data نساز. ## 8 Feature بدون Backend واقعی نساز. ## 9 Secret و Credential در Admin UI نمایش نده. ## 10 Feature سالم unrelated را Refactor نکن. ## 11 هر Bug Fix مهم Regression Test داشته باشد. ## 12 هر Phase یک Checkpoint مستقل و قابل rollback باشد. --- # Final Phase Order ```text PHASE 0 Security & Critical Bugs ↓ PHASE 1 Organizations & Subscriptions ↓ PHASE 2 Admin Dashboard ↓ PHASE 3 Platform Operations ↓ PHASE 4 Audit & Settings ↓ PHASE 5 QA & Production Hardening ``` **هر Phase را کامل کن، تست کن، گزارش بده و سپس متوقف شو. بدون دستور صریح من وارد Phase بعد نشو.**