35 KiB

خام سرزنش تاریخچه

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 دقیقاً مشخص کن:

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

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

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

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 واقعی ترجیحاً:

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:

git status

را بررسی کن.

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

بعد از Phase:

git diff
git status

را بررسی کن.

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

One Phase = One Stable Checkpoint

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

Relevant Backend Tests
Relevant Frontend Tests
Lint
Typecheck
Build
Smoke Tests

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

به Phase بعد نرو.

Stop-Loss Rule

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

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

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

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

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 ضروری است:

مصرف‌کنندگان آن را پیدا کن.
backward compatibility را بررسی کن.
frontend و tests را همزمان اصلاح کن.
تغییر 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:

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

نه:

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 انجام شود.

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

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

تمام تغییرات همان فاز را کامل کن.
تست‌های مرتبط را اجرا کن.
Regression احتمالی را بررسی کن.
فایل‌های تغییرکرده را اعلام کن.
باگ‌های پیدا شده را اعلام کن.
باگ‌های رفع‌شده را اعلام کن.
نتیجه Test / Lint / Build را اعلام کن.
وضعیت Git را بررسی کن.
یک گزارش کوتاه ارائه کن.
متوقف شو.

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

برو فاز بعد

نباید 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

اجرا کن:

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

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

./vendor/bin/pint --test

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

ثبت کن:

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

Frontend baseline

اجرا کن:

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 مطلوب:

install
↓
lint
↓
typecheck
↓
test
↓
build

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

خروجی Phase 0

جدولی بساز:

Area	Status	Problem	Severity

Severity:

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

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

backend/routes/api.php

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

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

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

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

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

/api/v1/ai/chat

بعد از اصلاح:

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 باید حداقل تحت:

auth:sanctum

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

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

3. SSRF Protection

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

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

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

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

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

بررسی کن:

.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 را پیدا کن.

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

AIController
App\Services\AI\OllamaService
AiProviderResolver
AiProviderConnection
OpenAiCompatibleProvider

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

معماری مقصد

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

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

Providerها:

OllamaProvider
OpenAIProvider
OpenAICompatibleProvider
LMStudioProvider
VllmProvider

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

Legacy Architecture

بررسی کن آیا:

AIController
App\Services\AI\OllamaService

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

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

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

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

AI Config

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

.env.example
config/ai.php

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

به‌خصوص:

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:

enabled=false

با hard-coded:

enabled=true

overwrite نشود.

Default Connection invariant

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

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

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

shared/api/client.ts
AuthProvider
AuthContext

را بررسی کن.

مشکل:

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

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

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

مثلاً:

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 ایجاد کن.

مقصد:

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

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

404 Not Found
403 Permission Denied
Session Expired

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

4. Error Handling

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

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

فایل بزرگ:

CourseBuilderPage.tsx

را بررسی کن.

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

Architecture پیشنهادی:

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

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

State Separation

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

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

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 مناسب:

GET /assets/:id

یا hydration مناسب.

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

Collaboration Polling

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

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 سبزند.

سپس متوقف شو.

این اولین فاز 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های واقعی پروژه تعیین کن.

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

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

Dashboard Redesign

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

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

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:

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

[ایجاد دوره]

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 فضای اصلی باشد.

پیشنهاد:

Block Library
+
Canvas
+
Right Panel

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

Properties
Structure
Review

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

Slash Command

در Canvas امکان:

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

مثلاً:

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

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

Autosave Feedback

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

Saved
Saving...
Unsaved
Offline
Conflict
Save failed

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

Publish Readiness

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

مثلاً:

3 issues before publishing

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

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

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

Builder Keyboard Shortcuts

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

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

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

AI Studio Redesign

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

پیشنهاد:

1 Source
2 Learning Design
3 Generate
4 Review

Upload UI

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

Component حرفه‌ای:

Drag & Drop
Browse

Supported:
PDF
DOCX
PPTX

Selected file:
filename
size
progress
remove

AI Configuration

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

Provider
Model
Language
Audience
Difficulty
Duration
Learning objective
Tone
Output type

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

AI Generation Progress

به جای spinner ساده:

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

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

AI Review

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

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

AI Suggestion

Accept
Edit
Reject

و در نهایت:

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های زیر بررسی کن:

375px
430px
768px
1024px
1440px

Mobile Builder

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

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

Workflow پیشنهادی:

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 بیایند.

مثلاً:

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

FA:

dir=rtl

EN:

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

اجرا کن:

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

در صورت وجود:

./vendor/bin/pint --test

بررسی کن:

route duplicates
migration status
queue jobs
scheduler
permissions
policies
organization isolation

Full Frontend QA

از clean install:

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 نهایی باید حداقل چنین منطق داشته باشد:

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 نباید شامل موارد غیرضروری باشد:

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

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

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

"*"

را بررسی و در صورت منطقی بودن 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:

Tests:
Assertions:
Failures:

Frontend:

Test Files:
Tests:
Lint:
Typecheck:
Build:

10. Remaining Technical Debt

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

Severity بده:

P0
P1
P2
P3

11. Production Readiness Score

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

Architecture
Security
Reliability
Performance
Testing
UI/UX
Accessibility
Maintainability

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

NOT READY
STAGING READY
PRODUCTION READY WITH CONDITIONS
PRODUCTION READY

قوانین Git

در هر Phase:

قبل از تغییر:

git status

بعد از تغییر:

git diff

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

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

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

قانون تست

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

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

اولویت:

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 کن.

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

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

ترتیب دقیق:

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 بعد بمان.

35 KiB خام سرزنش تاریخچه مخزن unescape control characters مخزن escape control characters

CHANGE SAFETY PROTOCOL — MANDATORY

اصل اول — Working Code Is Sacred

Minimum Necessary Change

Scope Lock

No Opportunistic Refactoring

Preserve Existing Behavior

Regression Test Rule

Never Fix Tests by Weakening Them

Checkpoint Rule

One Phase = One Stable Checkpoint

Stop-Loss Rule

Refactor Budget

Dependency Freeze

Database Safety

API Safety

UI Safety During Technical Phases

Technical Safety During UI Phases

Final Principle

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

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

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

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

PHASE 0 — Full Baseline & Project Health Audit

هدف

کارها

Backend baseline

Frontend baseline

GitHub Actions

خروجی Phase 0

PHASE 1 — Critical Bugs & Security Stabilization

1. Fix duplicated API prefix

2. Secure AI endpoints

3. SSRF Protection

4. Secrets

Acceptance Criteria — Phase 1

PHASE 2 — AI Architecture Consolidation

هدف

معماری مقصد

Legacy Architecture

AI Config

AI Connection Bug Fixes

enabled bug

Default Connection invariant

Scenario A

Scenario B

Scenario C

Scenario D

AI Provider Tests

Acceptance Criteria — Phase 2

PHASE 3 — Frontend Reliability & Application State

هدف

1. Authentication State

2. React Query Cache

3. Routing

4. Error Handling

5. Network Resilience

Acceptance Criteria Phase 3

PHASE 4 — Builder Architecture & Performance Refactor

هدف

CourseBuilderPage

State Separation

Rich Text

Asset Resolution

Collaboration Polling

Memory & Rendering

Acceptance Criteria Phase 4

PHASE 5 — Navigation, Dashboard & Information Architecture UX

Sidebar

Create

People

Insights

Manage

Role-aware Navigation

Dashboard Redesign

Global Header

Empty States

UX Consistency

Acceptance Criteria Phase 5

PHASE 6 — Builder & AI Studio UX Enhancement

35 KiB

خام سرزنش تاریخچه