# Master Prompt — MicroLearning Learner PWA Stabilization, UX Enhancement & APK Readiness می‌خواهم بخش **Learner / یادگیرنده** پروژه MicroLearning را به‌صورت مرحله‌ای، کنترل‌شده و Production-Ready اصلاح و ارتقا دهی. این بخش در حال حاضر یک **React PWA** است و در آینده باید بتواند با کمترین تغییر به **Android APK از طریق Capacitor** تبدیل شود. هدف این پروژه: * رفع باگ‌های واقعی Learner * اصلاح Progress Logic * اصلاح Learning Path * ایجاد Resume Learning واقعی * بهبود Course Player * تکمیل Offline/PWA * تکمیل Notifications * تکمیل Certificates * بهبود Progress & Daily Learning * تکمیل i18n و Accessibility * آماده‌سازی معماری برای Android APK * آماده‌سازی برای Firebase Cloud Messaging * حفظ یک Source Code مشترک بین PWA و APK است. --- # قانون اصلی این پروژه باید دقیقاً در **۶ فاز** انجام شود: ```text PHASE 0 Learner Stabilization & Critical Logic Fixes PHASE 1 Learning Paths, Resume Learning & Assignment Logic PHASE 2 Course Player & Assessment UX PHASE 3 Offline Learning & PWA Reliability PHASE 4 Progress, Certificates, Notifications & Learner Product UX PHASE 5 APK Readiness, Responsive, Accessibility & Final QA ``` هر Phase را جداگانه انجام بده. بعد از پایان هر Phase: 1. تغییرات همان Phase را کامل کن. 2. Regression Test اجرا کن. 3. Backend Tests مرتبط را اجرا کن. 4. Frontend Tests مرتبط را اجرا کن. 5. `npm run lint` را اجرا کن. 6. `npm run typecheck` را اجرا کن. 7. `npm test` را اجرا کن. 8. `npm run build` را اجرا کن. 9. `git diff` را بررسی کن. 10. فایل‌های تغییرکرده را اعلام کن. 11. Bugs Fixed را گزارش کن. 12. Remaining Issues را گزارش کن. 13. متوقف شو. بدون دستور صریح من: > برو فاز بعد وارد Phase بعد نشو. --- # CHANGE SAFETY PROTOCOL ## Working Code Is Sacred اگر بخشی: * درست کار می‌کند، * Test دارد، * Security Issue ندارد، * و مانع Phase فعلی نیست، فقط برای تمیزتر شدن Architecture آن را تغییر نده. --- ## Minimum Necessary Change هر Issue را با کمترین تغییر لازم اصلاح کن. از: * Refactor گسترده * Rename گسترده * تغییر Folder Structure unrelated * تغییر API Contract unrelated * Dependency Upgrade غیرضروری * Rebuild کردن Player از صفر خودداری کن. --- ## Preserve Existing Learner Features این قابلیت‌های فعلی باید حفظ شوند: ```text Learner Home My Learning Daily Learning Progress More Bottom Navigation Course Player Notes Highlights Bookmarks Favorites Discussions Assessments Offline Progress Tracking Light/Dark Mode RTL/LTR PWA ``` Feature موجود را بدون دلیل حذف نکن. --- ## Scope Lock قبل از شروع هر Phase اعلام کن: ```text Expected files to change Affected frontend modules Affected backend modules Affected APIs Affected database tables Behavior expected to change Behavior that must remain unchanged ``` اگر Issue دیگری پیدا شد که برای Phase جاری ضروری نیست: ```text Deferred Technical Debt ``` ثبت کن و فعلاً دست نزن. --- ## Regression Test Rule برای هر Bug مهم: ```text Reproduce ↓ Regression Test ↓ Confirm Failure ↓ Minimum Fix ↓ Confirm Pass ``` اگر Test ممکن نبود، دلیلش را گزارش کن. --- # PRODUCT PRINCIPLE Learner Experience باید: ```text Mobile First Simple Fast Low Cognitive Load Progress Oriented Motivating Offline Friendly Touch Friendly Accessible ``` باشد. Learner نباید UI پیچیده Admin یا Course Designer را ببیند. --- # PHASE 0 — Learner Stabilization & Critical Logic Fixes ## هدف قبل از UX Enhancement، باگ‌های واقعی Learner و Data Quality اصلاح شوند. --- # 1. Learner Architecture Audit تمام فایل‌ها و APIهای مرتبط با Learner را شناسایی کن: ```text LearnerShell LearnerHome MyLearning Daily Progress More CoursePlayer Assessment components Learner Controllers Assignments Progress Learning Events Certificates Notifications Offline Store Service Worker ``` --- # 2. Assignment Status Audit تمام Statusهای Assignment را مشخص کن. حداقل تفکیک منطقی: ```text Not Started In Progress Completed Overdue Due Today Due Soon Upcoming No Deadline ``` اگر Backend مدل دیگری دارد، همان مدل واقعی را اصلاح کن. --- # 3. Fix Due Soon Logic بررسی کن `dueSoon` واقعاً بر اساس نزدیک‌ترین Deadline مرتب شود. شرط باید چیزی شبیه: ```text deadline >= now AND deadline <= now + 7 days ``` باشد. Assignmentهای گذشته نباید Due Soon باشند. آنها باید: ```text Overdue ``` باشند. Test بنویس برای: ```text Deadline yesterday Deadline today Deadline tomorrow Deadline in 7 days Deadline in 8 days No deadline ``` --- # 4. Analytics Event Deduplication بررسی کن این Eventها به دلیل React Query Refetch یا Component Render چندبار ثبت نشوند: ```text course.opened lesson.started block.viewed lesson.completed course.completed ``` Eventها باید Session-aware یا Idempotent باشند. Architecture مناسب ایجاد کن، مثلاً: ```text learningSessionId + courseVersionId + lessonId + blockId + eventType ``` ولی architecture را بیش از نیاز پیچیده نکن. --- # 5. Complete Lesson Idempotency دکمه Completion نباید چند Event Completion تولید کند. بعد از Complete شدن: ```text ✓ Lesson Completed ``` نمایش داده شود. Mutation دوباره نباید Completion duplicate ایجاد کند. Backend نیز باید idempotency داشته باشد. --- # 6. Loading & Error Audit تمام Learner API Flowها باید: ```text Loading Empty Error Offline Retry ``` را صحیح مدیریت کنند. --- ## Acceptance Criteria Phase 0 * Due Soon صحیح است. * Overdue جدا شده. * event duplication رفع شده. * completion duplicate وجود ندارد. * Learner regression ایجاد نشده. * tests سبز هستند. سپس متوقف شو. --- # PHASE 1 — Learning Paths, Resume Learning & Assignment Logic ## هدف منطق اصلی Learning Experience درست شود. این Phase بسیار مهم است. --- # 1. Learning Path Progress بررسی کن Assignment نوع: ```text learning_path ``` چگونه Progress محاسبه می‌کند. Learning Path نباید با تکمیل Course اول Completed شود. ساختار منطقی مقصد: ```text Learning Path ↓ Course ↓ Lesson ↓ Block ``` Progress Path باید بر اساس تمام Courseهای Path محاسبه شود. --- # Learning Path Completion Completion rule را از مدل واقعی سیستم بخوان. اگر Path نیازمند تمام Courseهاست: ```text Completed Courses / Total Required Courses ``` محاسبه شود. اگر Rule دیگری وجود دارد از همان استفاده کن. Rule جعلی نساز. --- # Learning Path Tests حداقل: ```text 3 courses course 1 = 100% course 2 = 0% course 3 = 0% ``` Expected: ```text Path != Completed ``` و: ```text course 1 = 100 course 2 = 100 course 3 = 100 ``` Expected: ```text Path = Completed ``` --- # 2. True Resume Learning Continue Learning فعلی را بررسی کن. نباید صرفاً: ```text Highest progress course → first lesson ``` باشد. باید آخرین فعالیت واقعی Learner را ذخیره/استفاده کند. حداقل: ```text lastActivityAt lastCourseVersionId lastLessonId ``` در صورت امکان: ```text lastBlockId ``` --- # Resume Flow هدف: ```text User leaves app ↓ Returns later ↓ Continue Learning ↓ Same Course ↓ Same Lesson ↓ Closest possible Block ``` --- # Resume Data اگر داده لازم در Learning Events موجود است از همان استفاده کن. Schema جدید فقط اگر ضروری است ایجاد کن. Migration موجود را rewrite نکن. --- # 3. My Learning Status Architecture My Learning را براساس status واقعی قابل فیلتر کن: ```text All In Progress Not Started Completed Overdue ``` Downloaded بعداً در Phase Offline اضافه می‌شود. --- # 4. Mandatory Learning اگر Assignment یا Course قابلیت Mandatory دارد، آن را واضح نمایش بده. Badge: ```text Mandatory ``` و Deadline آن prominent باشد. --- # 5. Needs Attention در Home بخش: ```text Needs Attention ``` اضافه کن. Priority: ```text Overdue Due Today Due Soon Mandatory Not Started ``` هر Item CTA مستقیم داشته باشد. --- ## Acceptance Criteria Phase 1 * Learning Path Progress صحیح است. * Learning Path Completion صحیح است. * Resume Learning واقعی است. * User به آخرین Lesson برمی‌گردد. * My Learning status-based است. * Mandatory/Overdue واضح است. * tests کامل هستند. متوقف شو. --- # PHASE 2 — Course Player & Assessment UX ## هدف Course Player ساده‌تر، سریع‌تر و مناسب Microlearning شود. Player را از صفر بازنویسی نکن. --- # Player Header Header موبایل فعلی را audit کن. از نمایش تعداد زیادی Icon همزمان جلوگیری کن. پیشنهاد: ```text ← Lesson Title ⋯ ``` Actions ثانویه داخل More: ```text Notes Discussion Favorite Offline Download ``` Course Outline باید همچنان به‌سادگی قابل دسترسی باشد. --- # Lesson Progress Progress واضح‌تر شود. مثلاً: ```text Lesson 2 of 6 ████████░░ 34% ``` Progress Course نیز در Context مناسب نمایش داده شود. --- # Player Footer Primary flow ساده شود. مثلاً: ```text Previous Complete & Continue → ``` بعد از Completion: ```text ✓ Completed Next Lesson → ``` --- # Inline Progress Feedback وقتی Learner Activity ثبت شد feedback مزاحم ایجاد نکن. Toast فقط برای Actionهایی مثل: ```text Note saved Bookmark added Download ready ``` استفاده شود. --- # Notes / Discussions / Outline روی موبایل ترجیحاً Drawer/Sheet استاندارد باشند. Accessibility: ```text focus trap Escape focus return aria labels ``` رعایت شود. --- # Assessment UX Backend scoring را Source of Truth نگه دار. Client نباید نتیجه رسمی را خودش تعیین کند. بعد از Submit: در صورت support مدل: ```text Correct / Incorrect Feedback Explanation Score Retry Continue ``` نمایش بده. --- # Assessment Retry Retry فقط اگر Rule assessment اجازه می‌دهد. UI نباید خودش retry policy اختراع کند. --- # Hotspot Accessibility Hotspot Image باید در صورت وجود متن مناسب: ```text alt ``` داشته باشد. برای interactionهای تصویری keyboard alternative بررسی شود. --- # Rich Content بررسی کن: ```text Text Image Video Audio Quiz Flashcard Hotspot Other interactive blocks ``` در Mobile overflow ایجاد نکنند. --- # Video / Audio بررسی: ```text responsive sizing playback controls captions if available resume position if supported ``` --- # Fullscreen & Orientation از UX خراب در Landscape جلوگیری کن. Feature جدید native اضافه نکن؛ فقط Web/PWA behavior را اصلاح کن. --- ## Acceptance Criteria Phase 2 * Header ساده‌تر است. * Footer واضح‌تر است. * progress قابل فهم است. * assessment feedback بهتر است. * accessibility Drawers بهتر شده. * Player Feature حذف نشده. * mobile UX بهتر شده. * tests سبزند. متوقف شو. --- # PHASE 3 — Offline Learning & PWA Reliability ## هدف Offline از حالت partial cache خارج شود و واقعاً قابل اعتماد شود. این Phase باید با احتیاط انجام شود. --- # 1. Offline Architecture Audit بررسی کن: ```text IndexedDB Cache Storage Service Worker Offline queue Course download Progress synchronization ``` چگونه کار می‌کنند. قبل از تغییر architecture یک diagram کوتاه ارائه کن. --- # 2. Fix Lesson Cache Collision اگر Offline Data با: ```text assignmentId ``` Key می‌شود ولی فقط Lesson فعلی ذخیره می‌شود، اصلاح کن. Key یا schema باید Lesson-aware باشد. مثلاً: ```text organizationId userId assignmentId courseVersionId lessonId ``` یا کل Course Payload structured ذخیره شود. بهترین گزینه را با کمترین migration risk انتخاب کن. --- # 3. Full Course Download وقتی user: ```text Download Course ``` می‌زند، تمام محتوای لازم Course باید برای Offline آماده شود. حداقل: ```text Course metadata Lessons Blocks Images Documents required for lesson Other essential assets ``` Videoهای بسیار بزرگ را براساس policy پروژه مدیریت کن. Download fake نساز. --- # 4. Service Worker Cache Fix Service Worker نباید Cacheهای Course Download را هنگام Activate اشتباهاً پاک کند. Cache namespaces را جدا کن: ```text microlearn-shell-* microlearn-course-* microlearn-assets-* ``` Cleanup فقط cacheهای obsolete مربوط به همان namespace را حذف کند. --- # 5. Offline Download Manager در Learner `More` یا محل مناسب اضافه کن: ```text Offline Downloads ``` هر Download: ```text Course name Downloaded Size Last updated Update available Remove ``` --- # 6. Download Status Stateها: ```text Not downloaded Downloading Downloaded Update available Failed ``` Progress واقعی فقط اگر قابل اندازه‌گیری است. --- # 7. Offline Progress Queue اگر Learner Offline Course را تکمیل کرد: ```text Store progress locally ↓ Network available ↓ Sync ``` Queue باید: ```text idempotent ordered where needed retry-safe ``` باشد. --- # 8. Conflict Handling اگر Server و Device Progress اختلاف دارند، Rule مشخص داشته باش. برای Progress معمولاً از monotonic behavior استفاده کن: ```text Progress should not accidentally decrease ``` ولی business rules واقعی را بررسی کن. --- # 9. User Isolation Offline Data باید بین Userها leak نشود. اگر User A logout کند و User B وارد شود: User B نباید Cache خصوصی User A را ببیند. Cache/IndexedDB scope را بررسی کن. --- # 10. PWA Update Experience اگر Service Worker Version جدید آمد: Update نباید Downloadهای Offline را نابود کند. UX مناسب: ```text نسخه جدید آماده است. [به‌روزرسانی] ``` در صورت امکان. --- ## Acceptance Criteria Phase 3 * Lesson offline collision رفع شده. * Course Download واقعی است. * Service Worker cache bug رفع شده. * Offline Manager وجود دارد. * Offline progress sync کار می‌کند. * User isolation رعایت می‌شود. * PWA update امن است. * Offline tests وجود دارند. متوقف شو. --- # PHASE 4 — Progress, Certificates, Notifications & Learner Product UX ## هدف Learner Experience از یک Player ساده به تجربه کامل یادگیری تبدیل شود. --- # 1. Home Redesign Home باید اولویت داشته باشد: ```text Continue Learning ↓ Needs Attention ↓ Today's Microlearning ↓ Due Soon ↓ Recent / Assigned Learning ``` --- # Continue Learning Card نمایش: ```text Course Lesson Progress Last activity ``` CTA: ```text Continue ``` و باید به Resume واقعی Phase 1 متصل شود. --- # 2. Daily Learning Daily باید انتخاب منطقی داشته باشد. اگر algorithm فعلی Deadline-based است: واقعاً نزدیک‌ترین Learning مناسب را انتخاب کن. نمایش: ```text Today 5 minutes Lesson title Part of: Course title Why selected: Due in 3 days ``` Reason فقط اگر واقعی است. --- # 3. Progress Page Progress را از summary بسیار ساده ارتقا بده. فقط Metricهای واقعی. پیشنهاد: ```text Overall completion Completed courses Active learning Assessment average Learning activity Skills Certificates ``` Learning Time فقط اگر داده معتبر داریم. --- # 4. Certificates Learner API مستقل ایجاد یا تکمیل کن: ```text GET /learner/certificates GET /learner/certificates/:id ``` برای Download از معماری امن موجود استفاده کن. Learner فقط Certificate خودش را ببیند. --- # Certificates UI در More: ```text My Certificates ``` صفحه: ```text Course Issue date Certificate ID Status View Download Share if supported ``` --- # 5. Notification Center Notificationهای داخل App را برای Learner کامل کن. Categoryها: ```text Course assigned Deadline Reminder Completion Certificate System ``` --- # 6. Notification Preferences Preferences را از Keyهای فنی به UI واقعی تبدیل کن. مثلاً: ```text Notifications New learning assignments Deadline reminders Daily learning reminders Certificates ``` --- # 7. Push Notification Readiness در این Phase **FCM را اجباری پیاده‌سازی نکن** مگر زیرساخت APK/Capacitor آماده باشد. اما Backend Notification architecture را آماده کن: ```text Notification Event ↓ Notification Service ↓ Channel ``` Channelهای آینده: ```text In App Web Push FCM Email ``` --- # Notification Device Model برای آینده طراحی کن که User بتواند چند Device داشته باشد. مثلاً: ```text user_devices ``` با: ```text user_id platform push_token last_seen_at enabled ``` اما Migration فقط اگر در همین Phase واقعاً لازم است ایجاد شود. --- # 8. Preferences Cleanup Preferenceهایی که UI دارد ولی رفتار واقعی ندارند: یا: * پیاده‌سازی شوند، یا: * تا آماده‌شدن از UI حذف شوند. Fake settings ممنوع. --- # 9. More Page ساختار پیشنهادی: ```text Profile Certificates Offline Downloads Notifications Preferences Language Theme Help Logout ``` --- ## Acceptance Criteria Phase 4 * Home actionable است. * Daily Learning منطقی است. * Progress کامل‌تر است. * Certificates قابل دسترسی‌اند. * Notification Preferences واقعی‌اند. * Fake preferences حذف شده‌اند. * Push architecture آماده است. * Learner privacy رعایت شده. متوقف شو. --- # PHASE 5 — APK Readiness, Responsive, Accessibility & Final QA ## هدف Learner PWA را به نقطه‌ای برسان که بدون بازنویسی بتوان آن را با Capacitor به APK تبدیل کرد. در این Phase لزوماً APK نساز مگر من صریحاً درخواست کنم. هدف اصلی: ```text APK Ready ``` است. --- # 1. Source Sharing Rule نباید Android Learner Frontend جداگانه ساخته شود. Architecture باید: ```text React Learner App ↓ Web / PWA ↓ Capacitor Android ``` باشد. یک Source Code اصلی. --- # 2. Platform Abstraction موارد platform-specific را abstraction بده: ```text Notifications Network Storage Deep Links Status Bar Back Button Sharing Downloads ``` Web fallback داشته باشند. ولی dependency native را تا زمان نیاز بی‌دلیل اضافه نکن. --- # 3. Capacitor Readiness Audit بررسی کن: ```text SPA routing API base URL CORS Authentication Cookies / Sanctum strategy Deep links File downloads External links Back button behavior Safe areas Keyboard Status bar ``` --- # 4. Authentication for APK بررسی کن مدل Authentication فعلی برای native shell امن و سازگار است. Secret یا session token در storage ناامن قرار نگیرد. اگر تغییر auth لازم است impact را گزارش کن و Minimum Change انجام بده. --- # 5. API Environment Hard-coded localhost نباید در production APK وجود داشته باشد. Config باید environment-based باشد. مثلاً: ```text Development Staging Production On-Premise ``` --- # 6. Push Notification Integration Readiness برای Android architecture مقصد: ```text Laravel ↓ Queue ↓ FCM ↓ Capacitor Android ↓ Native Notification ``` باشد. در این Phase اگر implementation انجام می‌دهی: * permission Android 13+ * token registration * token refresh * logout token cleanup * multiple devices * deep link * notification channels را صحیح انجام بده. اگر من هنوز درخواست implementation نداده‌ام، فقط readiness ایجاد کن و integration را شروع نکن. --- # Notification Channels پیشنهاد: ```text Learning Deadlines Assignments Certificates System ``` --- # 7. Deep Linking آماده باش برای: ```text microlearning://course/{assignmentId}/lesson/{lessonId} ``` یا Universal/App Links. Notification باید بتواند user را مستقیم وارد context مربوط کند. --- # 8. Responsive QA حداقل: ```text 320 360 375 390 430 768 1024 ``` را برای Learner بررسی کن. تمرکز اصلی Mobile است. --- # 9. Safe Areas برای گوشی‌های دارای: ```text notch status bar gesture navigation ``` Safe Area را رعایت کن. --- # 10. Touch Targets حداقل حدود: ```text 44 × 44 ``` برای actionهای مهم. --- # 11. Accessibility Audit کن: ```text Keyboard Focus Screen reader ARIA Headings Labels Contrast Alt text Dialog Drawer Reduced motion Assessment accessibility ``` حداقل WCAG AA را هدف قرار بده. --- # 12. Full i18n تمام Learner Player hard-coded textها را وارد i18n کن. فارسی: ```text RTL ``` انگلیسی: ```text LTR ``` Mixed UI نباید وجود داشته باشد مگر نام فنی/برند. --- # 13. Dark Mode تمام Learner Experience: ```text Home My Learning Daily Progress More Player Assessment Notes Discussion Downloads Certificates ``` در Dark Mode بررسی شود. --- # 14. Performance Audit: ```text initial bundle course payload image loading video loading React Query cache unnecessary refetch event network calls offline storage ``` Optimization فقط بعد از اندازه‌گیری. --- # FINAL SMOKE TESTS ## Scenario 1 — Resume ```text Login → Start Course → Lesson 3 → Exit → Reopen → Continue Learning → Lesson 3 ``` --- ## Scenario 2 — Learning Path ```text Learning Path → Complete Course 1 → Path remains incomplete → Complete all required Courses → Path completed ``` --- ## Scenario 3 — Deadline ```text Overdue assignment → Needs Attention Tomorrow deadline → Due Soon ``` --- ## Scenario 4 — Assessment ```text Open quiz → Answer → Submit → Server score → Feedback ``` --- ## Scenario 5 — Offline ```text Download Course → Airplane Mode → Open Lesson 1 → Lesson 2 → Lesson 3 → Complete Learning → Reconnect → Progress Sync ``` --- ## Scenario 6 — User Isolation ```text User A → Download Course → Logout → User B Login → Cannot access User A private offline data ``` --- ## Scenario 7 — Certificate ```text Complete eligible Course → Certificate issued → My Certificates → Open / Download ``` --- ## Scenario 8 — Language ```text FA → Full RTL EN → Full LTR ``` --- ## Scenario 9 — PWA Update ```text Download Course → New Service Worker → Update App → Offline Course remains available ``` --- # SECURITY TESTS بررسی کن: ```text Learner cannot view other learner progress Learner cannot access other certificates Learner cannot access manager/admin APIs Learner cannot modify another assignment Offline cache does not leak user data Downloaded assets obey authorization model Progress APIs validate assignment ownership ``` --- # FINAL 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 | ## Learning Path Improvements ## Resume Learning Improvements ## Assignment & Deadline Improvements ## Player Improvements ## Assessment Improvements ## Offline Improvements ## PWA Improvements ## Progress Improvements ## Certificate Improvements ## Notification Improvements ## i18n Improvements ## Accessibility Improvements ## APK Readiness --- # TEST RESULTS Backend: ```text Tests: Assertions: Failures: ``` Frontend: ```text Test Files: Tests: Lint: Typecheck: Build: ``` --- # REMAINING TECHNICAL DEBT فقط موارد واقعی را گزارش کن. Severity: ```text High Medium Low ``` --- # LEARNER EXPERIENCE SCORE از 10 امتیاز بده: ```text Learner Home My Learning Daily Learning Course Player Assessments Progress Learning Paths Offline PWA Certificates Notifications Mobile UX Accessibility i18n Performance APK Readiness ``` در نهایت: ```text Learner Experience Score: XX/100 ``` --- # RELEASE STATUS یکی را انتخاب کن: ```text NOT READY PWA STAGING READY PWA PRODUCTION READY APK READY APK READY WITH CONDITIONS ``` --- # قوانین نهایی ## 1 Learner را از صفر بازنویسی نکن. ## 2 Bottom Navigation فعلی را مگر با دلیل UX جدی تغییر نده. ## 3 Offline را Fake نکن. ## 4 Learning Path را بر اساس Course اول Completed نکن. ## 5 Continue Learning باید واقعاً Resume باشد. ## 6 Server Source of Truth برای Assessment باشد. ## 7 Analytics Eventها duplicate نشوند. ## 8 Cache بین Userها leak نکند. ## 9 PWA و APK باید یک Source Code اصلی داشته باشند. ## 10 Firebase/Capacitor را زودتر از نیاز وارد پروژه نکن. ## 11 UI setting بدون رفتار واقعی نمایش نده. ## 12 هر Bug Fix مهم Test داشته باشد. ## 13 هر Phase یک Checkpoint مستقل و قابل rollback باشد. --- # FINAL PHASE ORDER ```text PHASE 0 Critical Stabilization ↓ PHASE 1 Learning Paths + Resume ↓ PHASE 2 Course Player + Assessments ↓ PHASE 3 Offline + PWA ↓ PHASE 4 Progress + Certificates + Notifications ↓ PHASE 5 APK Readiness + QA ``` **هر Phase را کامل کن، تست کن، `git diff` را بررسی کن، گزارش بده و سپس متوقف شو. بدون دستور صریح من وارد Phase بعد نشو.** # SUPPLEMENTARY PROMPT ## MicroLearning — Learner Android APK + Native Push Notifications + Manager PWA Notifications این Prompt مکمل Promptهای قبلی **Learner** و **Manager** است. قوانین Safety، Scope Lock، Minimum Necessary Change، Regression Testing و Working Code Is Sacred که در Promptهای اصلی تعریف شده‌اند، همچنان لازم‌الاجرا هستند. هیچ بخش سالمی صرفاً برای اجرای این قابلیت‌ها بازنویسی نشود. --- # PART A — LEARNER PROMPT EXTENSION Prompt فعلی Learner دارای Phase 0 تا Phase 5 است. دو Phase جدید زیر را بعد از Phase 5 اضافه کن: ```text PHASE 6 Android APK with Capacitor PHASE 7 Native Push Notifications with Firebase Cloud Messaging ``` ترتیب نهایی Learner: ```text PHASE 0 Critical Stabilization ↓ PHASE 1 Learning Paths + Resume ↓ PHASE 2 Course Player + Assessments ↓ PHASE 3 Offline + PWA ↓ PHASE 4 Progress + Certificates + Notifications ↓ PHASE 5 APK Readiness + QA ↓ PHASE 6 Android APK with Capacitor ↓ PHASE 7 FCM Native Push Notifications ``` --- # PHASE 6 — Android Learner APK with Capacitor ## هدف Learner PWA فعلی را بدون ایجاد Frontend جدید به Android Application واقعی تبدیل کن. قانون معماری: ```text ONE LEARNER SOURCE CODE React Learner │ ├── Web ├── PWA └── Capacitor Android ``` به هیچ عنوان یک React App، Flutter App یا Android UI مستقل برای Learner نساز. --- ## 1. Capacitor Integration نسخه‌های dependencyهای فعلی را بررسی کن و نسخه سازگار Capacitor را انتخاب کن. Dependency upgrade unrelated انجام نده. Android Platform را به پروژه اضافه کن. ساختار باید به‌صورت استاندارد باشد: ```text frontend/ src/ dist/ capacitor.config.* android/ ``` از build output فعلی Vite استفاده کن. --- ## 2. Learner-Only Android Experience APK باید تجربه Learner را ارائه کند. نباید به‌صورت پیش‌فرض navigation مربوط به: ```text Super Admin Course Designer Course Builder AI Studio Platform Administration ``` نمایش دهد. اگر همان User چند Role دارد، رفتار را از architecture واقعی Role Switching پروژه استخراج کن. امنیت را فقط با مخفی کردن menu پیاده‌سازی نکن. Backend authorization همچنان Source of Truth است. --- ## 3. API Configuration هیچ URL مانند: ```text localhost 127.0.0.1 ``` در Production APK hard-code نشود. Environmentهای واقعی را پشتیبانی کن: ```text Development Staging Production On-Premise ``` Configuration باید از روش استاندارد پروژه گرفته شود. --- ## 4. On-Premise Support MicroLearning ممکن است روی Server داخلی سازمان نصب شود. Android App باید بتواند به Endpoint سازمان متصل شود. Architecture را طوری طراحی کن که Server/Base URL قابل configuration امن باشد اگر Business Model پروژه نیاز دارد. Validation انجام بده: ```text HTTPS preferred Valid hostname No malformed URL Connection test ``` در Production اتصال insecure را بدون تصمیم صریح Business/Security مجاز نکن. --- ## 5. Authentication Authentication فعلی را برای Capacitor بررسی کن. Token/Session نباید در storage ناامن نگهداری شود. بررسی کن: ```text Login Logout Session expiry Token refresh if applicable 401 handling Multiple accounts Organization context ``` بعد از Logout داده Authentication و داده خصوصی local پاک یا isolate شود. --- ## 6. Native Back Button Android Back Button باید رفتار طبیعی داشته باشد. مثلاً: ```text Course Player → Previous App Screen Drawer Open → Close Drawer Modal Open → Close Modal ``` نباید با اولین Back کل App بسته شود. در Root Screen در صورت لزوم رفتار native مناسب داشته باش. --- ## 7. Deep Linking Foundation زیرساخت Deep Link ایجاد کن. هدف: ```text microlearning://learning/{assignmentId} ``` و ترجیحاً: ```text microlearning://learning/{assignmentId}/lesson/{lessonId} ``` در صورت استفاده از App Links: ```text https://learn.example.com/app/... ``` نیز architecture آماده باشد. Deep Link باید بعد از Authentication به destination صحیح منتقل شود. --- ## 8. Native Safe Areas بررسی کن: ```text Status Bar Navigation Bar Display Cutout Notch Gesture Area Keyboard ``` UI نباید زیر عناصر system قرار بگیرد. CSS safe-area را برای: ```text env(safe-area-inset-top) env(safe-area-inset-bottom) ``` در صورت نیاز صحیح استفاده کن. --- ## 9. Android Keyboard روی: ```text Login Notes Discussion Assessment Search Forms ``` بررسی کن Keyboard باعث مخفی شدن input یا CTA نشود. --- ## 10. External Links External URLها را audit کن. تصمیم واضح داشته باش: ```text Internal route → App External trusted URL → System browser ``` رفتار ناخواسته WebView ایجاد نکن. --- ## 11. Downloads این موارد را بررسی کن: ```text Certificates Documents Course resources ``` اگر download در Web کار می‌کند، رفتار Android را نیز تست کن. برای Certificate باید حداقل امکان: ```text Open Download Share ``` در صورت پشتیبانی platform وجود داشته باشد. --- ## 12. Sharing برای موارد مناسب abstraction ایجاد کن: ```text Certificate Course link Achievement ``` در Android از Native Share در صورت نیاز استفاده کن و Web fallback حفظ شود. --- ## 13. Network Awareness App باید وضعیت شبکه را تشخیص دهد. Stateهای حداقل: ```text Online Offline Reconnecting ``` Offline Learning Phase 3 باید همچنان کار کند. Capacitor integration نباید Offline/PWA architecture را خراب کند. --- ## 14. Splash Screen Splash Screen حرفه‌ای ولی کوتاه باشد. از نمایش Splash طولانی و مصنوعی جلوگیری کن. Branding موجود پروژه را reuse کن. --- ## 15. App Icon Android launcher icon و adaptive icon استاندارد ایجاد کن. از asset برند فعلی MicroLearning استفاده کن. Icon جدید unrelated طراحی نکن مگر asset مناسب موجود نباشد. --- ## 16. Status Bar Status Bar با: ```text Light Theme Dark Theme ``` هماهنگ شود. --- ## 17. PWA Must Continue Working بعد از اضافه شدن Capacitor این موارد نباید خراب شوند: ```text Web PWA Install Service Worker Offline Downloads Responsive UI Desktop Learner ``` APK نباید باعث fork شدن codebase شود. --- ## 18. Android Build Debug APK بساز. در صورت آماده بودن signing configuration، release build architecture را نیز آماده کن. Secret signing key را commit نکن. --- ## 19. GitHub Actions Readiness در صورت وجود GitHub Actions، pipeline جدا برای Android ایجاد کن یا readiness آن را اضافه کن. هدف آینده: ```text Frontend Test ↓ Frontend Build ↓ Capacitor Sync ↓ Android Build ↓ APK Artifact ``` اما CI موجود را بدون ضرورت بازنویسی نکن. --- ## PHASE 6 ACCEPTANCE CRITERIA Phase 6 فقط وقتی Complete است که: ```text React Web works PWA works Android project builds APK installs Login works Learner Home works Course Player works Assessments work Resume works Offline works Certificates work Android Back works Dark Mode works RTL works LTR works ``` و هیچ Frontend دوم ایجاد نشده باشد. --- # PHASE 7 — Native Push Notifications with FCM ## هدف Learner Android App باید Notification واقعی Android دریافت کند. حتی وقتی App در foreground نیست. Architecture مقصد: ```text MicroLearning Backend ↓ Notification Domain Event ↓ Notification Service ↓ Laravel Queue ↓ Firebase Cloud Messaging ↓ Android App ↓ Native Android Notification ``` --- # 1. Notification Architecture Notification logic را داخل Controllerها پراکنده نکن. Architecture ترجیحی: ```text Domain Event ↓ Notification Orchestrator ↓ Channel ``` Channelها: ```text InAppChannel PushChannel EmailChannel ``` Web Push در آینده قابل اضافه شدن باشد. --- # 2. Device Registration Backend باید Deviceهای User را مدیریت کند. مدل مناسب طراحی کن. مثلاً: ```text user_devices ``` فیلدهای منطقی: ```text id user_id organization_id platform device_identifier push_token enabled last_seen_at created_at updated_at ``` نام نهایی را با conventions پروژه هماهنگ کن. --- # 3. Multiple Devices یک User ممکن است: ```text Phone Tablet Second Phone ``` داشته باشد. Notification architecture باید Multiple Device را پشتیبانی کند. --- # 4. Token Registration بعد از دریافت FCM Token: ```text Android App ↓ Authenticated API ↓ Register Device Token ``` Backend ownership را verify کند. --- # 5. Token Refresh FCM Token ممکن است تغییر کند. Token refresh باید به Backend sync شود. Duplicate token ایجاد نکن. --- # 6. Logout هنگام Logout: Device registration مربوطه disable یا unregister شود. User قبلی نباید Notification User جدید را دریافت کند. --- # 7. Android 13+ Permission برای Androidهایی که Permission لازم دارند: ```text POST_NOTIFICATIONS ``` را صحیح مدیریت کن. Permission را بلافاصله و بدون context درخواست نکن. UX پیشنهادی: ```text اعلان‌های یادگیری را فعال کنید مهلت دوره‌ها، آموزش‌های جدید و گواهی‌های صادرشده را از دست ندهید. [فعال کردن اعلان‌ها] [بعداً] ``` از Dialog/Component استاندارد پروژه استفاده کن. --- # 8. Notification Channels Android Notification Channels ایجاد کن. حداقل: ```text Learning Deadlines Certificates System ``` در صورت نیاز: ```text Assignments Reminders ``` اما Channelهای بسیار زیاد نساز. --- # 9. Learner Notification Types حداقل Eventهای زیر را بررسی و در صورت support Backend پیاده‌سازی کن: ```text Course Assigned Learning Path Assigned Mandatory Learning Assigned Deadline Approaching Due Today Overdue Continue Learning Reminder Assessment Available Course Completed Certificate Issued Important Organization Announcement ``` --- # 10. Notification Preferences به Preference واقعی User احترام بگذار. مثلاً: ```text New assignments Deadline reminders Daily reminders Certificates Organization announcements ``` Notificationهای security/critical system در صورت Business Rule می‌توانند سیاست متفاوت داشته باشند. --- # 11. Scheduled Reminders Reminderها از queue/scheduler ارسال شوند. برای مثال: ```text 3 days before deadline 1 day before deadline Due today Overdue ``` از Request synchronous برای ارسال bulk notification استفاده نکن. --- # 12. Duplicate Protection یک Notification نباید به دلیل Retry Queue چندبار برای یک Event ارسال شود. Idempotency مناسب ایجاد کن. مثلاً بر اساس: ```text user event assignment notification type scheduled window ``` --- # 13. Deep Link on Notification Tap هر Push باید در صورت نیاز مقصد داشته باشد. مثلاً: ### Course Assigned ```text Notification ↓ My Learning ↓ Course ``` ### Deadline ```text Notification ↓ Assignment ↓ Resume Lesson ``` ### Certificate ```text Notification ↓ My Certificates ↓ Certificate ``` --- # 14. Foreground Behavior اگر App باز است، Notification نباید UX آزاردهنده ایجاد کند. در صورت مناسب بودن: ```text In-app banner / toast ``` و در background: ```text Native notification ``` --- # 15. Notification History Push Notification باید در صورت منطقی بودن با Notification Center داخل App هماهنگ باشد. یعنی Notification دریافت‌شده فقط ephemeral نباشد. User بتواند بعداً در: ```text Notifications ``` آن را مشاهده کند. --- # 16. Read / Unread Notification Center: ```text Unread Read Mark as read Mark all as read ``` داشته باشد در صورت support فعلی. --- # 17. Security هر Notification Payload را حداقل‌گرا نگه دار. Sensitive data را مستقیماً داخل Push Payload قرار نده. مثلاً اطلاعات خصوصی ارزیابی یا اطلاعات حساس Employee ارسال نشود. Push فقط context identifier امن ارسال کند و App داده اصلی را از API مجاز دریافت کند. --- # 18. FCM Credentials Firebase credential: ```text .env Secret Manager Server Configuration ``` باشد. هیچ: ```text Private Key Server Key Service Account Secret ``` در repository commit نشود. --- # 19. Failure Handling FCM responseها را مدیریت کن. برای Tokenهای: ```text Invalid Expired Unregistered ``` Device token را disable/remove کن. --- # 20. Observability حداقل بتوانیم بفهمیم: ```text Queued Sent to FCM Failed Invalid token ``` ولی Delivery قطعی را اگر FCM چنین اطلاعاتی نداده، جعلی نمایش نده. --- # 21. Push Tests حداقل تست: ```text User A notification → User A devices only ``` ```text User B → Must not receive User A notification ``` ```text Disabled preference → Optional notification not sent ``` ```text Invalid token → Safely disabled ``` ```text Logout → Device no longer receives private push ``` ```text Notification tap → Correct deep link ``` --- # PHASE 7 ACCEPTANCE CRITERIA Phase 7 زمانی Complete است که: ```text FCM connected Device registration works Token refresh works Logout cleanup works Android permission works Native notification works Background notification works Notification channels work Preferences work Deep linking works Duplicate push protection works Notification center stays consistent Security tests pass ``` --- # LEARNER FINAL QUALITY GATE — UPDATED پس از Phase 7 حتماً این Flow را تست کن: ```text Learner Login ↓ Device Registered ↓ Course Assigned ↓ App Closed ↓ Native Notification Received ↓ Tap Notification ↓ App Opens ↓ Correct Course ↓ Correct Resume Location ``` و: ```text Deadline Reminder ↓ Native Notification ↓ Tap ↓ Assignment ↓ Continue Learning ``` و: ```text Course Complete ↓ Certificate Issued ↓ Native Notification ↓ My Certificates ``` --- # UPDATED LEARNER RELEASE STATUS در گزارش نهایی یکی از این وضعیت‌ها را بده: ```text NOT READY PWA PRODUCTION READY ANDROID DEBUG READY ANDROID RELEASE READY WITH CONDITIONS ANDROID PRODUCTION READY ``` --- # PART B — MANAGER PROMPT EXTENSION Prompt Manager فعلی Phase 0 تا Phase 5 دارد. یک Phase جدید اضافه کن: ```text PHASE 6 Manager PWA & Push/Web Notification Experience ``` ترتیب نهایی: ```text PHASE 0 Role & Permission Audit ↓ PHASE 1 Manager Shell & Dashboard ↓ PHASE 2 My Team & Learning Profiles ↓ PHASE 3 Assignments, Deadlines & Notifications ↓ PHASE 4 Skills, Insights, Reports & Approvals ↓ PHASE 5 Responsive, Security & Final QA ↓ PHASE 6 Manager PWA & Notifications ``` --- # PHASE 6 — Manager PWA & Notification Experience ## هدف Manager Panel علاوه بر Desktop/Web، روی موبایل نیز به‌صورت PWA قابل استفاده باشد. برای Manager فعلاً Android APK مستقل نساز. Architecture: ```text Manager React Experience ↓ Web + Installable PWA ``` --- # 1. PWA Availability Manager بتواند در browserهای پشتیبانی‌شده PWA را Install کند. PWA Shell باید Role-aware باشد. وقتی Manager وارد می‌شود: ```text Manager Dashboard ``` نمایش داده شود، نه Learner Home. --- # 2. Role Combination اگر Manager خودش Learner هم هست، Role Switching یا Experience Switching فعلی پروژه را بررسی کن. راه‌حل جدید duplicate نساز. در صورت وجود switching استاندارد: ```text Manager Mode Learner Mode ``` را حفظ کن. --- # 3. Manager Mobile Priorities PWA Manager روی موبایل باید حداقل این Actions را عالی پشتیبانی کند: ```text View Needs Attention View My Team View Employee Learning Send Reminder Assign Learning Review Deadline Approve Request View Team Progress ``` Course Builder و Admin Toolهای unrelated را وارد PWA Manager نکن. --- # 4. Manager In-App Notifications Notification Center برای Manager category-aware باشد. نمونه: ```text Team Learning Deadlines Approvals Skill Alerts Reports System ``` --- # 5. Manager Notification Events در صورت وجود داده واقعی، Manager بتواند Notification دریافت کند برای: ```text Team member overdue Mandatory course not started Team deadline approaching Approval requested Learning request received Assignment completed Critical skill gap alert Weekly learning summary ready ``` Insight ساده را بی‌دلیل Push نکن. Notification fatigue ایجاد نکن. --- # 6. Immediate vs Digest همه Eventها Push فوری نباشند. تقسیم‌بندی منطقی: ```text Immediate: Critical overdue Approval needing action Important assignment issue ``` ```text Digest: Team learning summary Weekly progress General insights ``` --- # 7. Manager Notification Preferences Manager بتواند تنظیم کند: ```text Team deadline alerts Overdue alerts Approval requests Learning activity Weekly summary ``` --- # 8. Web Push اگر infrastructure Web Push پروژه آماده و قابل اتکا است، Manager PWA بتواند Web Push واقعی دریافت کند. اگر هنوز زیرساخت Web Push وجود ندارد: Fake implementation ایجاد نکن. Architecture Notification Channel را طوری نگه دار که Web Push بعداً اضافه شود. --- # 9. Shared Notification Backend Notification Business Rules را بین: ```text Learner APK Manager PWA In-App Notification Center ``` duplicate نکن. Architecture: ```text Domain Event ↓ Notification Service ↓ Recipient Resolution ↓ Preferences ↓ Channels ``` Channels: ```text In-App FCM Web Push Email ``` باید قابل توسعه باشند. --- # 10. Manager Assignment Notification Integration وقتی Manager در Phase 3 دوره‌ای تخصیص می‌دهد: ```text Manager ↓ Assign Course ↓ Learners ↓ Notification Event ↓ In-App + FCM according to preference ``` در صورت APK Learner. Manager نباید خودش مستقیم FCM API را فراخوانی کند. --- # 11. Manager Reminder Action Action: ```text Send Reminder ``` باید از همان Notification Service استفاده کند. نه implementation جداگانه. قبل از ارسال bulk reminder خلاصه نشان بده: ```text 12 learners Course: Workplace Safety Channel: In-App + Push [Send Reminder] ``` --- # 12. Rate / Spam Protection Manager نباید بتواند ناخواسته پشت سر هم Pushهای مشابه برای یک Team ارسال کند. برای Reminder: ```text cooldown duplicate detection authorization ``` در نظر بگیر. --- # 13. Team Scope Notification recipientها حتماً Backend-scoped باشند. Manager با دستکاری Request نباید بتواند برای افراد خارج از Team مجاز خودش Push ارسال کند. --- # 14. Notification Audit عملیات مهم Manager مثل: ```text Bulk reminder sent Assignment notification triggered Deadline changed ``` در صورت وجود Audit architecture ثبت شود. --- # 15. PWA Responsive QA بررسی: ```text 360 375 390 430 768 ``` Manager PWA روی mobile نباید desktop table shrink شده باشد. --- # MANAGER PHASE 6 ACCEPTANCE CRITERIA ```text Manager PWA installable Manager route correct Mobile dashboard works Team actions work Notifications permission-aware Reminder action uses shared service Team scope enforced Duplicate reminder protection works Learner FCM integration compatible No separate Manager APK created ``` --- # PART C — SHARED NOTIFICATION ARCHITECTURE این بخش برای هر دو Prompt الزامی است. نباید برای Manager و Learner دو سیستم Notification جدا ساخته شود. Architecture مقصد: ```text MicroLearning │ Domain/Application Events │ Notification Service │ ┌───────────┼───────────┐ │ │ │ In-App Push Email │ ┌────────┴────────┐ │ │ FCM Web Push │ │ Learner APK Manager PWA ``` --- # Recipient Resolution Notification Service باید خودش مشخص کند Recipient چه کسی است. مثلاً: ```text Course Assigned → Learner ``` ```text Deadline approaching → Learner ``` ```text Employee overdue → Authorized Manager ``` ```text Approval requested → Manager ``` --- # Preferences Flow: ```text Event ↓ Recipient ↓ Permission / Scope ↓ Notification Preference ↓ Channel ↓ Queue ↓ Delivery ``` --- # Queue First ارسال Notificationهای خارجی را synchronous داخل user request انجام نده. از Queue استفاده کن. Failure FCM/Web Push نباید عملیات اصلی مثل: ```text Assign Course Complete Course Issue Certificate ``` را rollback کند مگر business rule صریحی وجود داشته باشد. --- # Notification Taxonomy یک taxonomy استاندارد داشته باش. مثلاً: ```text learning.assigned learning.reminder learning.deadline_soon learning.overdue learning.completed assessment.available certificate.issued manager.approval_requested manager.team_overdue manager.weekly_summary system.announcement ``` Naming را با conventions فعلی پروژه تطبیق بده. --- # Notification Payload Payload استاندارد داشته باش: ```text type title body recipient entityType entityId deepLink createdAt ``` Sensitive information اضافه نکن. --- # Shared Deep Links Learner: ```text /course /lesson /certificate /notification ``` Manager: ```text /team/member /assignment /approval /report ``` هم Web و هم Native باید از destination منطقی مشترک استفاده کنند. --- # FINAL SAFETY RULE برای اضافه کردن Capacitor، FCM یا PWA Notification: **هیچ‌یک از فازهای قبلی را دوباره Refactor نکن مگر integration واقعاً به تغییر آن نیاز داشته باشد.** اگر integration نیازمند تغییر گسترده شد: ```text STOP ``` و قبل از ادامه گزارش بده: ```text Integration blocker: Why: Affected modules: Risk: Minimum viable fix: Alternative: ``` --- # UPDATED EXECUTION ORDER ترتیب پیشنهادی نهایی برای این دو بخش: ```text LEARNER PHASE 0–5 ↓ LEARNER PHASE 6 Android APK ↓ LEARNER PHASE 7 FCM Push ↓ MANAGER PHASE 0–5 ↓ MANAGER PHASE 6 PWA + Manager Notifications ``` اگر Manager Phaseهای 0–5 قبلاً انجام شده‌اند، مستقیماً Phase 6 را اجرا کن. **هیچ Phase را بدون دستور صریح من شروع نکن. پس از هر Phase تست کن، گزارش بده و متوقف شو.**