New_Micro_Learning/Prompt/Admin Prompt.md

# 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 بعد نشو.**