# CHANGE SAFETY PROTOCOL — MANDATORY

این پروژه در حال حاضر دارای قابلیت‌های فعال و کد عملیاتی است.

هدف این برنامه **Stabilization و Controlled Improvement** است، نه بازنویسی پروژه.

## اصل اول — Working Code Is Sacred

اگر یک بخش:

* درست کار می‌کند،
* Test آن سبز است،
* Security issue ندارد،
* مانع مستقیم Phase فعلی نیست،

فقط برای Clean Code، زیبایی Architecture یا Preference شخصی آن را تغییر نده.

---

## Minimum Necessary Change

برای حل هر Issue کمترین تغییر ممکن را انجام بده.

مثلاً اگر یک Bug با تغییر:

* یک Route،
* یک Service،
* یا یک Component

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

---

## Scope Lock

در ابتدای هر Phase دقیقاً مشخص کن:

```text
Files expected to change
Modules affected
Behavior expected to change
Behavior that must remain unchanged
```

در طول Phase از این Scope خارج نشو مگر اینکه یک Blocker واقعی پیدا شود.

اگر مشکل دیگری پیدا کردی که برای Phase جاری ضروری نیست، آن را در:

```text
Deferred Technical Debt
```

ثبت کن و تغییرش نده.

---

## No Opportunistic Refactoring

این موارد ممنوع هستند مگر اینکه مستقیماً برای حل مشکل Phase ضروری باشند:

* Renameهای گسترده
* تغییر Folder Structure
* تغییر Architecture unrelated
* تغییر API Contract unrelated
* تغییر State Management unrelated
* تغییر Database Schema unrelated
* Replace کردن Libraryها
* Rewrite کردن Componentهای سالم
* تغییر Design System در Phase فنی
* Dependency Upgrade گسترده

---

## Preserve Existing Behavior

قبل از تغییر مشخص کن رفتار فعلی چیست.

پس از تغییر همان رفتارهای سالم باید حفظ شده باشند.

Feature موجود نباید به‌صورت تصادفی:

* حذف شود،
* غیرفعال شود،
* تغییر UX پیدا کند،
* یا رفتار متفاوت پیدا کند.

---

## Regression Test Rule

برای هر Bug واقعی ترجیحاً:

```text
Reproduce
↓
Write regression test
↓
Confirm test fails
↓
Implement minimum fix
↓
Confirm test passes
```

اگر نوشتن Test ممکن نبود، دلیل آن را گزارش کن.

---

## Never Fix Tests by Weakening Them

برای سبز کردن Pipeline حق نداری:

* Test را حذف کنی.
* Test را skip کنی.
* Assertion را حذف کنی.
* شرط Test را ضعیف کنی.
* Error را suppress کنی.

مگر اینکه Test واقعاً اشتباه باشد و دلیل فنی آن را مستند کنی.

---

## Checkpoint Rule

قبل از هر Phase:

```bash
git status
```

را بررسی کن.

Phase باید روی وضعیت مشخص شروع شود.

بعد از Phase:

```bash
git diff
git status
```

را بررسی کن.

هر Phase باید یک تغییر مستقل و قابل rollback باشد.

---

## One Phase = One Stable Checkpoint

تا زمانی که موارد زیر سبز نشده‌اند Phase را Completed اعلام نکن:

```text
Relevant Backend Tests
Relevant Frontend Tests
Lint
Typecheck
Build
Smoke Tests
```

در صورت Failure ابتدا همان Phase را Stabilize کن.

به Phase بعد نرو.

---

## Stop-Loss Rule

اگر Fix یک Issue باعث شد:

* بیش از حد انتظار فایل تغییر کند،
* Architecture جدید نیاز شود،
* APIهای زیادی تحت تأثیر قرار گیرند،
* migration گسترده لازم شود،
* Regression متعدد ایجاد شود،

کار را متوقف کن.

به‌جای ادامه دادن، گزارش بده:

```text
Issue:
Why the fix became high-risk:
Files/modules affected:
Safer alternatives:
Recommended next step:
```

بدون اجازه User تغییر پرریسک را ادامه نده.

---

## Refactor Budget

برای Phaseهای Bug Fix:

حداکثر Refactor باید فقط به اندازه‌ای باشد که Bug امن و قابل نگهداری حل شود.

از Refactor پروژه‌محور خودداری کن.

---

## Dependency Freeze

در Phaseهای Stabilization هیچ Dependency عمده‌ای را Upgrade یا Replace نکن مگر اینکه:

* vulnerability جدی وجود داشته باشد،
* dependency خراب باشد،
* یا Issue بدون آن قابل حل نباشد.

هر Dependency Change را جداگانه گزارش کن.

---

## Database Safety

Migrationهای موجود را rewrite نکن.

برای schema change از Migration جدید استفاده کن.

عملیات destructive روی داده موجود ممنوع است مگر با دستور صریح User.

---

## API Safety

API Contractهای فعال را بدون ضرورت تغییر نده.

اگر تغییر API ضروری است:

1. مصرف‌کنندگان آن را پیدا کن.
2. backward compatibility را بررسی کن.
3. frontend و tests را همزمان اصلاح کن.
4. تغییر Contract را صریح گزارش کن.

---

## UI Safety During Technical Phases

در Phaseهای Technical:

* layout را redesign نکن.
* spacing را redesign نکن.
* navigation را redesign نکن.
* typography را تغییر نده.
* visual styling unrelated را تغییر نده.

فقط UI لازم برای رفع Bug مجاز است.

---

## Technical Safety During UI Phases

در Phaseهای UI:

Business Logic، Database و Backend Architecture را فقط زمانی تغییر بده که UI بدون آن قابل اجرا نباشد.

در غیر این صورت Technical Debt ثبت کن.

---

## Final Principle

هدف هر Phase:

```text
Project after Phase
=
Project before Phase
+
specific improvement
-
specific bug
```

نه:

```text
Project after Phase
=
partially rewritten project
+
new unknown regressions
```

# Master Prompt — MicroLearning Debug, Refactor & UI/UX Enhancement

می‌خواهم پروژه **MicroLearning** را به‌صورت مرحله‌ای، کنترل‌شده و Production-Ready بررسی، Debug، Refactor و از نظر UI/UX ارتقا دهی.

## قانون اصلی اجرای پروژه

این کار باید دقیقاً در **۹ فاز از Phase 0 تا Phase 8** انجام شود.

**هرگز چند فاز را همزمان انجام نده.**

پس از پایان هر فاز:

1. تمام تغییرات همان فاز را کامل کن.
2. تست‌های مرتبط را اجرا کن.
3. Regression احتمالی را بررسی کن.
4. فایل‌های تغییرکرده را اعلام کن.
5. باگ‌های پیدا شده را اعلام کن.
6. باگ‌های رفع‌شده را اعلام کن.
7. نتیجه Test / Lint / Build را اعلام کن.
8. وضعیت Git را بررسی کن.
9. یک گزارش کوتاه ارائه کن.
10. متوقف شو.

تا زمانی که من صراحتاً نگفته‌ام:

> برو فاز بعد

نباید Phase بعدی را شروع کنی.

---

# اصول غیرقابل مذاکره

در تمام فازها این قوانین رعایت شوند.

* Feature موجود بدون دلیل حذف نشود.
* رفتار فعلی سیستم بدون ضرورت تغییر نکند.
* داده کاربران یا migrationهای موجود خراب نشوند.
* API Contract بدون بررسی frontend تغییر نکند.
* هیچ Mock دائمی وارد production code نشود.
* هیچ hard-coded URL جدید ایجاد نشود.
* هیچ API Key یا Secret داخل source code قرار نگیرد.
* `.env` commit نشود.
* Architecture جدید باید component-based و maintainable باشد.
* TypeScript تا جای ممکن strict باقی بماند.
* `any` فقط با دلیل موجه استفاده شود.
* Errorها silent swallow نشوند.
* همه Async Operationها loading/error state داشته باشند.
* RTL و LTR هر دو حفظ شوند.
* Dark/Light Mode خراب نشود.
* Responsive Design حفظ شود.
* Accessibility در componentهای جدید رعایت شود.
* از ایجاد فایل‌های بسیار بزرگ جلوگیری شود.
* قبل از ساخت component جدید بررسی کن component مشابه وجود دارد یا خیر.
* Design Tokenهای فعلی را تا حد ممکن reuse کن.
* duplicate logic ایجاد نکن.
* Business Logic را از UI جدا نگه دار.

اگر برای رفع یک مشکل مجبور به تغییر Architecture شدی، ابتدا impact آن را بررسی کن.

---

# تکنولوژی پروژه

Frontend:

* React
* TypeScript
* Vite
* React Query
* CSS / Design System موجود

Backend:

* Laravel
* PHP
* REST API
* Laravel Sanctum
* Queue / Jobs
* Database-backed configuration

AI Providers شامل مواردی مانند:

* Ollama
* OpenAI-compatible providers
* LM Studio
* vLLM
* Custom providers

---

# PHASE 0 — Full Baseline & Project Health Audit

## هدف

قبل از تغییر سورس باید وضعیت واقعی فعلی پروژه ثبت شود.

هیچ Refactor یا Feature Development در این فاز انجام نده.

## کارها

ابتدا ساختار پروژه را بررسی کن.

موارد زیر را شناسایی کن:

* Frontend entry points
* Backend entry points
* Routes
* Middleware
* Authentication flow
* Permissions
* API Client
* React Query configuration
* Builder architecture
* AI architecture
* Queue architecture
* Database migrations
* Tests
* GitHub Actions
* Environment/config files

---

## Backend baseline

اجرا کن:

```bash
php artisan about
php artisan route:list
php artisan route:list --path=ai
php artisan test
```

در صورت وجود ابزارها:

```bash
./vendor/bin/pint --test
```

و هر static analysis موجود در پروژه.

ثبت کن:

* تعداد Tests
* تعداد Assertions
* Failed Tests
* Skipped Tests
* Warnings

---

## Frontend baseline

اجرا کن:

```bash
npm ci
npm run lint
npm run typecheck
npm test
npm run build
```

اگر script متفاوت است ابتدا `package.json` را بررسی کن.

ثبت کن:

* تعداد Test files
* تعداد Tests
* TypeScript errors
* ESLint errors
* Build errors
* Build warnings

---

## GitHub Actions

Workflowهای موجود را بررسی کن.

Quality Gate مطلوب:

```text
install
↓
lint
↓
typecheck
↓
test
↓
build
```

Backend نیز باید test شود.

---

## خروجی Phase 0

جدولی بساز:

| Area | Status | Problem | Severity |
| ---- | ------ | ------- | -------- |

Severity:

```text
P0 Critical
P1 High
P2 Medium
P3 Low
```

همچنین Baseline رسمی پروژه را ثبت کن.

در این فاز هیچ تغییر معماری انجام نده.

پس از گزارش متوقف شو.

---

# PHASE 1 — Critical Bugs & Security Stabilization

این فاز فقط مربوط به مشکلات **P0 / Security / Critical API bugs** است.

---

## 1. Fix duplicated API prefix

فایل زیر را بررسی کن:

```text
backend/routes/api.php
```

مشکل شناخته‌شده:

Route group دوباره `v1` prefix گرفته و مسیرهایی مانند این ساخته شده‌اند:

```text
/api/v1/v1/ai/chat
/api/v1/v1/health
/api/v1/v1/certificates/verify/{code}
```

معماری route را اصلاح کن.

مسیر نهایی AI باید منطقی و یکتا باشد، مثلاً:

```text
/api/v1/ai/chat
```

بعد از اصلاح:

```bash
php artisan route:list
```

را اجرا و routeهای نهایی را بررسی کن.

---

## 2. Secure AI endpoints

تمام endpointهای AI را شناسایی کن.

بررسی کن:

* Authentication
* Authorization
* Throttling
* Organization scope
* Permission
* Input validation

AI endpoint نباید برای anonymous user قابل استفاده باشد مگر endpoint مشخصاً public طراحی شده باشد.

AI generation باید حداقل تحت:

```text
auth:sanctum
```

و permission مناسب باشد.

برای عملیات expensive rate limit تعریف کن.

---

## 3. SSRF Protection

تمام AI Connection URLها را بررسی کن.

سیستم نباید اجازه دهد user به هر URL دلخواه backend request ارسال کند.

Policy مناسب طراحی کن.

برای providerهای شناخته‌شده:

```text
Ollama
LM Studio
vLLM
OpenAI
```

قوانین مشخص داشته باش.

Local providerها باید بتوانند localhost را استفاده کنند.

Custom Providerها باید تحت policy / allowlist باشند.

بررسی کن:

* hostname
* protocol
* resolved IP
* redirects
* ports
* localhost rules
* private network rules

DNS rebinding و redirect bypass را نیز در نظر بگیر.

---

## 4. Secrets

بررسی کن:

```text
.env
API Keys
tokens
credentials
```

هیچ secret داخل repository قرار نگیرد.

`.gitignore` را بررسی کن.

---

## Acceptance Criteria — Phase 1

* duplicated `v1` وجود ندارد.
* anonymous AI generation امکان‌پذیر نیست.
* AI endpoint rate limited است.
* organization isolation رعایت شده.
* SSRF mitigation وجود دارد.
* تست security route نوشته شده.
* تست authentication نوشته شده.
* تست authorization نوشته شده.
* backend tests سبز هستند.
* frontend regression ایجاد نشده.

پس از پایان Phase 1 متوقف شو.

---

# PHASE 2 — AI Architecture Consolidation

## هدف

در حال حاضر AI نباید چند معماری موازی و ناسازگار داشته باشد.

تمام مسیرهای AI را پیدا کن.

به‌طور خاص بررسی کن:

```text
AIController
App\Services\AI\OllamaService
AiProviderResolver
AiProviderConnection
OpenAiCompatibleProvider
```

و فایل‌های مشابه.

---

## معماری مقصد

تمام درخواست‌های AI باید تا جای ممکن از یک abstraction واحد عبور کنند:

```text
Frontend
↓
AI API
↓
AI Application Service
↓
AiProviderResolver
↓
Provider Adapter
↓
Provider
```

Providerها:

```text
OllamaProvider
OpenAIProvider
OpenAICompatibleProvider
LMStudioProvider
VllmProvider
```

در صورت امکان adapterها را reuse کن.

---

## Legacy Architecture

بررسی کن آیا:

```text
AIController
App\Services\AI\OllamaService
```

هنوز نیاز هستند یا خیر.

اگر functionality آنها توسط معماری جدید پوشش داده شده:

* dependencyها را migrate کن.
* tests را migrate کن.
* routeها را migrate کن.
* سپس legacy code را حذف کن.

هیچ dead code باقی نگذار.

---

## AI Config

این فایل‌ها را بررسی کن:

```text
.env.example
config/ai.php
```

هر config که application استفاده می‌کند باید واقعاً در config تعریف شده باشد.

به‌خصوص:

```text
AI_OPENAI_BASE_URL
AI_OPENAI_API_KEY
AI_OPENAI_MODEL_FAST
AI_OPENAI_MODEL_BALANCED
AI_OPENAI_MODEL_ADVANCED
AI_OPENAI_TIMEOUT
```

اگر دیگر لازم نیستند حذف شوند.

اگر لازم هستند config صحیح ایجاد شود.

---

# AI Connection Bug Fixes

## enabled bug

هنگام Create Connection بررسی کن که مقدار user:

```text
enabled=false
```

با hard-coded:

```text
enabled=true
```

overwrite نشود.

---

## Default Connection invariant

Backend باید invariant مشخص داشته باشد:

```text
Per Organization:
Maximum one default enabled AI connection
```

Create / Update / Delete / Make Default باید transaction-safe باشند.

حالت‌های زیر را تست کن:

### Scenario A

Default connection حذف می‌شود.

Expected:

یک **enabled** connection دیگر default شود.

### Scenario B

Default connection disable می‌شود.

Expected:

default به enabled connection دیگری منتقل شود یا default خالی شود.

### Scenario C

connection جدید default می‌شود.

Expected:

default قبلی atomically برداشته شود.

### Scenario D

همه connectionها disabled هستند.

Expected:

هیچ default active connection وجود نداشته باشد.

---

# AI Provider Tests

برای موارد زیر Test بنویس:

* Ollama reachable
* Ollama unavailable
* invalid model
* invalid URL
* timeout
* OpenAI compatible provider
* disabled provider
* default provider
* fallback provider
* invalid credential
* provider deletion

---

## Acceptance Criteria — Phase 2

* یک architecture اصلی AI وجود دارد.
* duplicate AI logic حذف شده.
* dead service حذف شده.
* configها consistent هستند.
* AI connections درست کار می‌کنند.
* enabled/default logic تست دارد.
* provider resolver deterministic است.
* تمام tests سبز هستند.

سپس متوقف شو.

---

# PHASE 3 — Frontend Reliability & Application State

## هدف

رفع باگ‌های state، routing و API handling.

---

# 1. Authentication State

فایل‌هایی مثل:

```text
shared/api/client.ts
AuthProvider
AuthContext
```

را بررسی کن.

مشکل:

روی HTTP 401 فقط token پاک نشود.

Authentication state نیز باید synchronize شود.

Architecture مناسب طراحی کن.

مثلاً:

```text
API receives 401
↓
central unauthorized handler
↓
clear token
↓
clear user
↓
clear protected cache
↓
set guest state
↓
navigate to login
```

از circular dependency جلوگیری کن.

---

# 2. React Query Cache

بعد از Logout یا Organization change:

cache حساس باید invalidate یا clear شود.

مطمئن شو اطلاعات organization قبلی برای organization جدید نمایش داده نمی‌شود.

---

# 3. Routing

AppRouter را بررسی و در صورت نیاز nested route architecture ایجاد کن.

مقصد:

```text
/app
  /dashboard
  /courses
  /courses/:id
  /library
  /monitoring/*
  /ai-studio
  /settings
  /*
```

صفحات مستقل داشته باش:

```text
404 Not Found
403 Permission Denied
Session Expired
```

Unknown route نباید صفحه unrelated نشان دهد.

---

# 4. Error Handling

برای API stateها componentهای استاندارد تعریف کن:

```text
Loading
Empty
Error
Permission denied
Offline
Retry
```

هر صفحه نباید implementation متفاوت داشته باشد.

---

# 5. Network Resilience

بررسی کن:

* timeout
* cancellation
* retry
* duplicated request
* stale data
* race condition

روی mutationهای حساس retry کورکورانه انجام نشود.

---

## Acceptance Criteria Phase 3

* Session expiry صحیح است.
* logout کامل است.
* cache leakage وجود ندارد.
* 404 صحیح است.
* 403 صحیح است.
* routes deterministic هستند.
* error handling استاندارد شده.
* lint/typecheck/test/build موفق‌اند.

سپس متوقف شو.

---

# PHASE 4 — Builder Architecture & Performance Refactor

## هدف

Builder بدون تغییر UX فعلی از نظر architecture پایدار شود.

---

# CourseBuilderPage

فایل بزرگ:

```text
CourseBuilderPage.tsx
```

را بررسی کن.

اگر همچنان بسیار بزرگ است آن را component-based کن.

Architecture پیشنهادی:

```text
builder/
  components/
  shell/
  canvas/
  toolbar/
  block-library/
  inspector/
  structure/
  review/
  collaboration/

  hooks/
  state/
  commands/
  services/
  utils/
  types/
```

---

# State Separation

Business logic از JSX جدا شود.

مواردی مانند:

```text
selection
drag/drop
block mutations
autosave
publish
collaboration
keyboard shortcuts
```

نباید همگی داخل یک page component باشند.

---

# Rich Text

Text block فعلی را بررسی کن.

اگر HTML ذخیره می‌شود ولی render آن با regex strip می‌شود، این behavior را اصلاح کن.

Rich Text واقعی باید حداقل پشتیبانی کند:

* Paragraph
* Heading
* Bold
* Italic
* Lists
* Link

از ذخیره unsafe HTML جلوگیری کن.

Sanitization مناسب داشته باش.

در صورت نیاز از editor استاندارد مانند TipTap/ProseMirror استفاده کن، ولی dependency جدید فقط در صورت توجیه اضافه شود.

---

# Asset Resolution

بررسی کن برای دریافت یک Asset کل library دریافت نشود.

API مناسب:

```text
GET /assets/:id
```

یا hydration مناسب.

React Query cache keyهای asset را اصلاح کن.

---

# Collaboration Polling

این موارد را بررسی کن:

```text
Presence
Collaboration
Notifications
Locks
AI Jobs
```

Polling frequency را audit کن.

در صورت مناسب بودن:

* Page Visibility API
* adaptive polling
* pause in background
* exponential backoff

استفاده کن.

برای realtime architecture آینده abstraction ایجاد کن تا بعداً WebSocket/SSE قابل اضافه شدن باشد.

اما در این فاز بدون ضرورت infrastructure بزرگ جدید اضافه نکن.

---

# Memory & Rendering

بررسی کن:

* unnecessary renders
* unstable callbacks
* large context providers
* large list rendering
* expensive calculations

برای listهای بزرگ virtualization را فقط در صورت نیاز واقعی اضافه کن.

---

## Acceptance Criteria Phase 4

* Builder functionality تغییر نکرده.
* فایل‌های monolithic شکسته شده‌اند.
* business logic جدا شده.
* duplicate logic کاهش یافته.
* rich text صحیح است.
* asset loading بهینه شده.
* polling کنترل شده.
* tests برای core builder behavior وجود دارد.
* lint/typecheck/test/build سبزند.

سپس متوقف شو.

---

# PHASE 5 — Navigation, Dashboard & Information Architecture UX

این اولین فاز major UI/UX enhancement است.

در این مرحله functionality جدید سنگین اضافه نکن.

تمرکز روی usability باشد.

---

# Sidebar

Navigation فعلی را audit کن.

پیشنهاد grouping:

## Create

* Dashboard
* Courses
* Learning Paths
* Library
* Templates
* Question Bank
* AI Studio

## People

* Users
* Teams
* Assignments

## Insights

* Monitoring
* Skills
* Reports

## Manage

* Reviews
* Certificates
* Subscription
* Settings

اما grouping نهایی را بر اساس نقش‌ها و featureهای واقعی پروژه تعیین کن.

---

# Role-aware Navigation

Navigation باید بر اساس Role / Permission نمایش داده شود.

مثلاً Learner نباید ابزار Course Designer را ببیند.

---

# Dashboard Redesign

Dashboard باید action-oriented باشد.

بخش‌های پیشنهادی:

```text
Needs Attention
Continue Working
Recent Courses
Pending Reviews
Publishing Issues
Learner Risk
AI Jobs
Recent Activity
Quick Actions
```

KPIها را compactتر کن.

از empty whitespace غیرضروری جلوگیری کن.

---

# Global Header

Header باید شامل موارد مورد نیاز باشد:

* context
* search
* notifications
* user menu

اما clutter ایجاد نکند.

---

# Empty States

برای صفحات بدون داده Empty State حرفه‌ای ایجاد کن.

مثلاً Courses:

```text
هنوز دوره‌ای ایجاد نشده
اولین دوره خود را بسازید.

[ایجاد دوره]
```

---

# UX Consistency

بررسی کن:

* button hierarchy
* destructive actions
* primary CTA
* page titles
* breadcrumbs
* tables
* filters
* dialogs
* drawers
* toasts

Componentهای مشترک باید visual behavior یکسان داشته باشند.

---

## Acceptance Criteria Phase 5

* Navigation ساده‌تر شده.
* Sidebar role-aware است.
* Dashboard action-oriented است.
* visual hierarchy بهبود یافته.
* UX consistency افزایش یافته.
* Feature حذف نشده.
* responsive regression وجود ندارد.

سپس متوقف شو.

---

# PHASE 6 — Builder & AI Studio UX Enhancement

این مهم‌ترین UX Phase پروژه است.

---

# Builder Layout

Layout چهارپنله فعلی را audit کن.

هدف این است که Canvas فضای اصلی باشد.

پیشنهاد:

```text
Block Library
+
Canvas
+
Right Panel
```

Right Panel می‌تواند tab داشته باشد:

```text
Properties
Structure
Review
```

Block Library قابل collapse باشد.

---

# Slash Command

در Canvas امکان:

```text
/
```

برای افزودن سریع block بررسی و در صورت مناسب بودن اضافه شود.

مثلاً:

```text
/text
/heading
/image
/video
/quiz
/flashcard
/divider
/ai
```

Keyboard-first UX ایجاد کن.

---

# Autosave Feedback

کاربر همیشه باید وضعیت سند را بداند:

```text
Saved
Saving...
Unsaved
Offline
Conflict
Save failed
```

این indicator در toolbar قرار گیرد.

---

# Publish Readiness

قبل از Publish Validation انجام شود.

مثلاً:

```text
3 issues before publishing
```

مواردی مانند:

* Empty lesson
* Missing title
* Broken asset
* Invalid quiz
* Missing answer
* Missing required settings

نمایش داده شوند.

---

# Builder Keyboard Shortcuts

در صورت سازگاری:

```text
Ctrl/Cmd + S
Ctrl/Cmd + Z
Ctrl/Cmd + Shift + Z
Delete
Escape
Ctrl/Cmd + D
```

Shortcuts باید در input/editor مزاحم تایپ نباشند.

---

# AI Studio Redesign

AI Studio را به workflow واضح تبدیل کن.

پیشنهاد:

```text
1 Source
2 Learning Design
3 Generate
4 Review
```

---

# Upload UI

از native file input خام استفاده نکن.

Component حرفه‌ای:

```text
Drag & Drop
Browse

Supported:
PDF
DOCX
PPTX

Selected file:
filename
size
progress
remove
```

---

# AI Configuration

کاربر باید قبل از Generate موارد مهم را واضح ببیند:

```text
Provider
Model
Language
Audience
Difficulty
Duration
Learning objective
Tone
Output type
```

تنظیمات advanced را collapse کن.

---

# AI Generation Progress

به جای spinner ساده:

```text
Uploading source
Extracting content
Analyzing
Designing learning structure
Generating blocks
Validating
Preparing draft
```

نشان داده شود.

---

# AI Review

AI output نباید blind accept شود.

در صورت سازگاری architecture، review block-level ایجاد کن:

```text
AI Suggestion

Accept
Edit
Reject
```

و در نهایت:

```text
Accept all reviewed changes
```

---

## Acceptance Criteria Phase 6

* Builder سریع‌تر و ساده‌تر شده.
* Canvas فضای بیشتری دارد.
* Properties/Structure واضح‌ترند.
* Save state مشخص است.
* Publish validation وجود دارد.
* AI Studio workflow واضح دارد.
* File Upload UI حرفه‌ای است.
* AI review قابل کنترل است.
* mobile/desktop regression وجود ندارد.

سپس متوقف شو.

---

# PHASE 7 — Responsive, PWA, i18n & Accessibility

## Mobile

تمام صفحات اصلی را در حداقل viewportهای زیر بررسی کن:

```text
375px
430px
768px
1024px
1440px
```

---

# Mobile Builder

Builder نباید صرفاً در mobile مخفی شود.

نسخه **Quick Edit** ایجاد کن.

Workflow پیشنهادی:

```text
Course
↓
Lesson
↓
Blocks
↓
Tap block
↓
Full screen editor
```

Mobile باید حداقل اجازه دهد:

* edit text
* reorder block
* add common block
* delete block
* image selection
* quiz edit
* preview
* save

Advanced desktop features می‌توانند desktop-only بمانند.

---

# Learner Experience

Learner UI را جداگانه audit کن.

Focus:

* bottom navigation
* course progress
* touch targets
* reading comfort
* assessments
* resume learning
* offline/PWA state

---

# i18n

Hard-coded Persian/English stringها را audit کن.

تمام UI stringها باید از translation catalog بیایند.

مثلاً:

```text
t('builder.publish')
t('builder.saved')
t('ai.generate')
```

FA:

```text
dir=rtl
```

EN:

```text
dir=ltr
```

Mixed UI حذف شود مگر نام فنی باشد.

---

# Accessibility

Audit:

* semantic HTML
* heading hierarchy
* labels
* ARIA
* focus state
* focus trap
* modal/dialog semantics
* drawer semantics
* keyboard navigation
* contrast
* images alt
* tabs
* skip link
* reduced motion

Tabها باید keyboard accessible باشند.

Dialog باید focus trap داشته باشد.

Escape باید modal را ببندد.

Focus بعد از close به trigger برگردد.

---

# PWA

بررسی کن:

* manifest
* icons
* install
* offline fallback
* update handling
* cache policy

API response حساس را بی‌دلیل cache نکن.

---

## Acceptance Criteria Phase 7

* responsive QA کامل است.
* Builder mobile quick-edit دارد.
* FA/EN کامل‌تر شده.
* RTL/LTR صحیح است.
* accessibility issues اصلی رفع شده.
* PWA behavior پایدار است.
* Lighthouse regression جدی وجود ندارد.

سپس متوقف شو.

---

# PHASE 8 — Final QA, Production Hardening & Release Gate

این فاز هیچ major feature جدیدی ندارد.

فقط stabilization.

---

# Full Backend QA

اجرا کن:

```bash
php artisan optimize:clear
php artisan route:list
php artisan test
```

در صورت وجود:

```bash
./vendor/bin/pint --test
```

بررسی کن:

* route duplicates
* migration status
* queue jobs
* scheduler
* permissions
* policies
* organization isolation

---

# Full Frontend QA

از clean install:

```bash
rm -rf node_modules
npm ci
npm run lint
npm run typecheck
npm test
npm run build
```

---

# Manual Smoke Tests

حداقل موارد زیر را دستی بررسی کن.

## Authentication

* Login
* Logout
* Expired Session
* Unauthorized URL
* Permission Denied

## Users

* Create
* Edit
* Search
* Team assignment

## Courses

* Create
* Edit
* Builder
* Add Blocks
* Reorder
* Save
* Preview
* Publish

## AI

* Ollama connection
* Connection test
* Generate
* Failure handling
* Timeout
* Invalid model
* AI Studio workflow

## Learner

* Open course
* Continue
* Complete lesson
* Quiz
* Progress

## Monitoring

* Dashboard
* Filters
* learner progress

## Theme

* Light
* Dark

## Languages

* Persian
* English

## Responsive

* Mobile
* Tablet
* Desktop

---

# Security Audit

حداقل بررسی کن:

* XSS
* CSRF
* SSRF
* IDOR
* authorization
* organization isolation
* unsafe uploads
* mass assignment
* exposed secrets
* rate limit
* file access
* AI endpoint abuse

---

# Database

بررسی کن:

* indexes
* foreign keys
* unique constraints
* N+1 queries
* transaction boundaries

خصوصاً جداول پرترافیک.

---

# Performance

بررسی کن:

* frontend bundle size
* lazy loading
* unnecessary requests
* duplicate requests
* query count
* image loading
* large lists

قبل و بعد را در صورت امکان مقایسه کن.

---

# GitHub Actions Final Quality Gate

Pipeline نهایی باید حداقل چنین منطق داشته باشد:

```text
Backend install
Backend static checks
Backend tests

Frontend install
Frontend lint
Frontend typecheck
Frontend tests
Frontend build

↓
SUCCESS
```

اگر هر مرحله Fail شد Release نباید موفق تلقی شود.

---

# Release Hygiene

Archive یا deployment package نباید شامل موارد غیرضروری باشد:

```text
.git
.env
node_modules
temporary logs
IDE files
runtime cache
test artifacts
```

Dependencyها باید lock شده باشند.

در PHP dependencyهای wildcard مانند:

```text
"*"
```

را بررسی و در صورت منطقی بودن version constraint مناسب تعریف کن.

`minimum-stability` را نیز بررسی کن.

---

# Final Report

در انتهای Phase 8 یک گزارش نهایی بده.

فرمت:

## 1. Bugs Fixed

جدول:

| Issue | Severity | Status |

## 2. Security Improvements

## 3. Architecture Improvements

## 4. Performance Improvements

## 5. UI/UX Improvements

## 6. Accessibility Improvements

## 7. Responsive Improvements

## 8. AI Improvements

## 9. Test Results

Backend:

```text
Tests:
Assertions:
Failures:
```

Frontend:

```text
Test Files:
Tests:
Lint:
Typecheck:
Build:
```

## 10. Remaining Technical Debt

فقط موارد واقعی باقی‌مانده را بنویس.

Severity بده:

```text
P0
P1
P2
P3
```

## 11. Production Readiness Score

از 100 امتیاز بده:

```text
Architecture
Security
Reliability
Performance
Testing
UI/UX
Accessibility
Maintainability
```

و در نهایت یکی از این وضعیت‌ها را اعلام کن:

```text
NOT READY
STAGING READY
PRODUCTION READY WITH CONDITIONS
PRODUCTION READY
```

---

# قوانین Git

در هر Phase:

قبل از تغییر:

```bash
git status
```

بعد از تغییر:

```bash
git diff
```

فایل‌های unrelated را تغییر نده.

در پایان هر Phase فایل‌های تغییرکرده را اعلام کن.

اگر Git repository دارای تغییرات قبلی user است، آنها را overwrite یا revert نکن.

---

# قانون تست

هیچ Phase را فقط به دلیل اینکه کد compile شد موفق اعلام نکن.

هر Bug Fix مهم باید تا حد امکان Regression Test داشته باشد.

اولویت:

```text
Bug reproduction
↓
Test
↓
Fix
↓
Test passes
```

---

# قانون Refactor

Refactor و Feature Change را مخلوط نکن.

اگر قرار است رفتار تغییر کند، دقیقاً اعلام کن.

اگر فقط Refactor است، رفتار observable باید ثابت بماند.

---

# قانون UI

در UI/UX Enhancement:

* از redesign بی‌هدف خودداری کن.
* Design System موجود را حفظ و تقویت کن.
* visual consistency مهم‌تر از decoration است.
* از gradient، glass، animation و shadow بی‌دلیل استفاده نکن.
* Density برای نرم‌افزار سازمانی متعادل باشد.
* Primary Action در هر صفحه واضح باشد.
* Information hierarchy حفظ شود.
* RTL first-class citizen باشد.

---

# قانون Performance

قبل از optimization حدس نزن.

ابتدا bottleneck را شناسایی کن.

سپس fix کن.

سپس نتیجه را دوباره اندازه بگیر.

---

# قانون نهایی اجرای مراحل

ترتیب دقیق:

```text
PHASE 0
Baseline & Audit
        ↓
PHASE 1
Critical Bugs & Security
        ↓
PHASE 2
AI Architecture
        ↓
PHASE 3
Frontend Reliability
        ↓
PHASE 4
Builder Architecture & Performance
        ↓
PHASE 5
Navigation & Dashboard UX
        ↓
PHASE 6
Builder & AI Studio UX
        ↓
PHASE 7
Responsive + i18n + Accessibility + PWA
        ↓
PHASE 8
Final QA & Production Release Gate
```

**هیچ Phase را بدون اجازه من رد نکن.**

بعد از پایان هر Phase فقط گزارش بده و منتظر دستور من برای Phase بعد بمان.