New_Micro_Learning/Prompt/Learner.md

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

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

است.


قانون اصلی

این پروژه باید دقیقاً در ۶ فاز انجام شود:

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

این قابلیت‌های فعلی باید حفظ شوند:

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 اعلام کن:

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

Deferred Technical Debt

ثبت کن و فعلاً دست نزن.


Regression Test Rule

برای هر Bug مهم:

Reproduce
↓
Regression Test
↓
Confirm Failure
↓
Minimum Fix
↓
Confirm Pass

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


PRODUCT PRINCIPLE

Learner Experience باید:

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 را شناسایی کن:

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 را مشخص کن.

حداقل تفکیک منطقی:

Not Started
In Progress
Completed
Overdue
Due Today
Due Soon
Upcoming
No Deadline

اگر Backend مدل دیگری دارد، همان مدل واقعی را اصلاح کن.


3. Fix Due Soon Logic

بررسی کن dueSoon واقعاً بر اساس نزدیک‌ترین Deadline مرتب شود.

شرط باید چیزی شبیه:

deadline >= now
AND
deadline <= now + 7 days

باشد.

Assignmentهای گذشته نباید Due Soon باشند.

آنها باید:

Overdue

باشند.

Test بنویس برای:

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 چندبار ثبت نشوند:

course.opened
lesson.started
block.viewed
lesson.completed
course.completed

Eventها باید Session-aware یا Idempotent باشند.

Architecture مناسب ایجاد کن، مثلاً:

learningSessionId
+
courseVersionId
+
lessonId
+
blockId
+
eventType

ولی architecture را بیش از نیاز پیچیده نکن.


5. Complete Lesson Idempotency

دکمه Completion نباید چند Event Completion تولید کند.

بعد از Complete شدن:

✓ Lesson Completed

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

Mutation دوباره نباید Completion duplicate ایجاد کند.

Backend نیز باید idempotency داشته باشد.


6. Loading & Error Audit

تمام Learner API Flowها باید:

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 نوع:

learning_path

چگونه Progress محاسبه می‌کند.

Learning Path نباید با تکمیل Course اول Completed شود.

ساختار منطقی مقصد:

Learning Path
      ↓
Course
      ↓
Lesson
      ↓
Block

Progress Path باید بر اساس تمام Courseهای Path محاسبه شود.


Learning Path Completion

Completion rule را از مدل واقعی سیستم بخوان.

اگر Path نیازمند تمام Courseهاست:

Completed Courses
/
Total Required Courses

محاسبه شود.

اگر Rule دیگری وجود دارد از همان استفاده کن.

Rule جعلی نساز.


Learning Path Tests

حداقل:

3 courses
course 1 = 100%
course 2 = 0%
course 3 = 0%

Expected:

Path != Completed

و:

course 1 = 100
course 2 = 100
course 3 = 100

Expected:

Path = Completed

2. True Resume Learning

Continue Learning فعلی را بررسی کن.

نباید صرفاً:

Highest progress course
→ first lesson

باشد.

باید آخرین فعالیت واقعی Learner را ذخیره/استفاده کند.

حداقل:

lastActivityAt
lastCourseVersionId
lastLessonId

در صورت امکان:

lastBlockId

Resume Flow

هدف:

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 واقعی قابل فیلتر کن:

All
In Progress
Not Started
Completed
Overdue

Downloaded بعداً در Phase Offline اضافه می‌شود.


4. Mandatory Learning

اگر Assignment یا Course قابلیت Mandatory دارد، آن را واضح نمایش بده.

Badge:

Mandatory

و Deadline آن prominent باشد.


5. Needs Attention

در Home بخش:

Needs Attention

اضافه کن.

Priority:

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 همزمان جلوگیری کن.

پیشنهاد:

←
Lesson Title
⋯

Actions ثانویه داخل More:

Notes
Discussion
Favorite
Offline Download

Course Outline باید همچنان به‌سادگی قابل دسترسی باشد.


Lesson Progress

Progress واضح‌تر شود.

مثلاً:

Lesson 2 of 6

████████░░ 34%

Progress Course نیز در Context مناسب نمایش داده شود.


Player Footer

Primary flow ساده شود.

مثلاً:

Previous

Complete & Continue →

بعد از Completion:

✓ Completed

Next Lesson →

Inline Progress Feedback

وقتی Learner Activity ثبت شد feedback مزاحم ایجاد نکن.

Toast فقط برای Actionهایی مثل:

Note saved
Bookmark added
Download ready

استفاده شود.


Notes / Discussions / Outline

روی موبایل ترجیحاً Drawer/Sheet استاندارد باشند.

Accessibility:

focus trap
Escape
focus return
aria labels

رعایت شود.


Assessment UX

Backend scoring را Source of Truth نگه دار.

Client نباید نتیجه رسمی را خودش تعیین کند.

بعد از Submit:

در صورت support مدل:

Correct / Incorrect
Feedback
Explanation
Score
Retry
Continue

نمایش بده.


Assessment Retry

Retry فقط اگر Rule assessment اجازه می‌دهد.

UI نباید خودش retry policy اختراع کند.


Hotspot Accessibility

Hotspot Image باید در صورت وجود متن مناسب:

alt

داشته باشد.

برای interactionهای تصویری keyboard alternative بررسی شود.


Rich Content

بررسی کن:

Text
Image
Video
Audio
Quiz
Flashcard
Hotspot
Other interactive blocks

در Mobile overflow ایجاد نکنند.


Video / Audio

بررسی:

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

بررسی کن:

IndexedDB
Cache Storage
Service Worker
Offline queue
Course download
Progress synchronization

چگونه کار می‌کنند.

قبل از تغییر architecture یک diagram کوتاه ارائه کن.


2. Fix Lesson Cache Collision

اگر Offline Data با:

assignmentId

Key می‌شود ولی فقط Lesson فعلی ذخیره می‌شود، اصلاح کن.

Key یا schema باید Lesson-aware باشد.

مثلاً:

organizationId
userId
assignmentId
courseVersionId
lessonId

یا کل Course Payload structured ذخیره شود.

بهترین گزینه را با کمترین migration risk انتخاب کن.


3. Full Course Download

وقتی user:

Download Course

می‌زند، تمام محتوای لازم Course باید برای Offline آماده شود.

حداقل:

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 را جدا کن:

microlearn-shell-*
microlearn-course-*
microlearn-assets-*

Cleanup فقط cacheهای obsolete مربوط به همان namespace را حذف کند.


5. Offline Download Manager

در Learner More یا محل مناسب اضافه کن:

Offline Downloads

هر Download:

Course name
Downloaded
Size
Last updated
Update available
Remove

6. Download Status

Stateها:

Not downloaded
Downloading
Downloaded
Update available
Failed

Progress واقعی فقط اگر قابل اندازه‌گیری است.


7. Offline Progress Queue

اگر Learner Offline Course را تکمیل کرد:

Store progress locally
      ↓
Network available
      ↓
Sync

Queue باید:

idempotent
ordered where needed
retry-safe

باشد.


8. Conflict Handling

اگر Server و Device Progress اختلاف دارند، Rule مشخص داشته باش.

برای Progress معمولاً از monotonic behavior استفاده کن:

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

نسخه جدید آماده است.

[به‌روزرسانی]

در صورت امکان.


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 باید اولویت داشته باشد:

Continue Learning
↓
Needs Attention
↓
Today's Microlearning
↓
Due Soon
↓
Recent / Assigned Learning

Continue Learning Card

نمایش:

Course
Lesson
Progress
Last activity

CTA:

Continue

و باید به Resume واقعی Phase 1 متصل شود.


2. Daily Learning

Daily باید انتخاب منطقی داشته باشد.

اگر algorithm فعلی Deadline-based است:

واقعاً نزدیک‌ترین Learning مناسب را انتخاب کن.

نمایش:

Today

5 minutes

Lesson title

Part of:
Course title

Why selected:
Due in 3 days

Reason فقط اگر واقعی است.


3. Progress Page

Progress را از summary بسیار ساده ارتقا بده.

فقط Metricهای واقعی.

پیشنهاد:

Overall completion
Completed courses
Active learning
Assessment average
Learning activity
Skills
Certificates

Learning Time فقط اگر داده معتبر داریم.


4. Certificates

Learner API مستقل ایجاد یا تکمیل کن:

GET /learner/certificates
GET /learner/certificates/:id

برای Download از معماری امن موجود استفاده کن.

Learner فقط Certificate خودش را ببیند.


Certificates UI

در More:

My Certificates

صفحه:

Course
Issue date
Certificate ID
Status

View
Download
Share if supported

5. Notification Center

Notificationهای داخل App را برای Learner کامل کن.

Categoryها:

Course assigned
Deadline
Reminder
Completion
Certificate
System

6. Notification Preferences

Preferences را از Keyهای فنی به UI واقعی تبدیل کن.

مثلاً:

Notifications

New learning assignments
Deadline reminders
Daily learning reminders
Certificates

7. Push Notification Readiness

در این Phase FCM را اجباری پیاده‌سازی نکن مگر زیرساخت APK/Capacitor آماده باشد.

اما Backend Notification architecture را آماده کن:

Notification Event
      ↓
Notification Service
      ↓
Channel

Channelهای آینده:

In App
Web Push
FCM
Email

Notification Device Model

برای آینده طراحی کن که User بتواند چند Device داشته باشد.

مثلاً:

user_devices

با:

user_id
platform
push_token
last_seen_at
enabled

اما Migration فقط اگر در همین Phase واقعاً لازم است ایجاد شود.


8. Preferences Cleanup

Preferenceهایی که UI دارد ولی رفتار واقعی ندارند:

یا:

  • پیاده‌سازی شوند،

یا:

  • تا آماده‌شدن از UI حذف شوند.

Fake settings ممنوع.


9. More Page

ساختار پیشنهادی:

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 نساز مگر من صریحاً درخواست کنم.

هدف اصلی:

APK Ready

است.


1. Source Sharing Rule

نباید Android Learner Frontend جداگانه ساخته شود.

Architecture باید:

React Learner App
      ↓
Web / PWA
      ↓
Capacitor Android

باشد.

یک Source Code اصلی.


2. Platform Abstraction

موارد platform-specific را abstraction بده:

Notifications
Network
Storage
Deep Links
Status Bar
Back Button
Sharing
Downloads

Web fallback داشته باشند.

ولی dependency native را تا زمان نیاز بی‌دلیل اضافه نکن.


3. Capacitor Readiness Audit

بررسی کن:

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

مثلاً:

Development
Staging
Production
On-Premise

6. Push Notification Integration Readiness

برای Android architecture مقصد:

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

پیشنهاد:

Learning
Deadlines
Assignments
Certificates
System

7. Deep Linking

آماده باش برای:

microlearning://course/{assignmentId}/lesson/{lessonId}

یا Universal/App Links.

Notification باید بتواند user را مستقیم وارد context مربوط کند.


8. Responsive QA

حداقل:

320
360
375
390
430
768
1024

را برای Learner بررسی کن.

تمرکز اصلی Mobile است.


9. Safe Areas

برای گوشی‌های دارای:

notch
status bar
gesture navigation

Safe Area را رعایت کن.


10. Touch Targets

حداقل حدود:

44 × 44

برای actionهای مهم.


11. Accessibility

Audit کن:

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

فارسی:

RTL

انگلیسی:

LTR

Mixed UI نباید وجود داشته باشد مگر نام فنی/برند.


13. Dark Mode

تمام Learner Experience:

Home
My Learning
Daily
Progress
More
Player
Assessment
Notes
Discussion
Downloads
Certificates

در Dark Mode بررسی شود.


14. Performance

Audit:

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

Login
→
Start Course
→
Lesson 3
→
Exit
→
Reopen
→
Continue Learning
→
Lesson 3

Scenario 2 — Learning Path

Learning Path
→
Complete Course 1
→
Path remains incomplete
→
Complete all required Courses
→
Path completed

Scenario 3 — Deadline

Overdue assignment
→
Needs Attention

Tomorrow deadline
→
Due Soon

Scenario 4 — Assessment

Open quiz
→
Answer
→
Submit
→
Server score
→
Feedback

Scenario 5 — Offline

Download Course
→
Airplane Mode
→
Open Lesson 1
→
Lesson 2
→
Lesson 3
→
Complete Learning
→
Reconnect
→
Progress Sync

Scenario 6 — User Isolation

User A
→
Download Course
→
Logout
→
User B Login
→
Cannot access User A private offline data

Scenario 7 — Certificate

Complete eligible Course
→
Certificate issued
→
My Certificates
→
Open / Download

Scenario 8 — Language

FA
→
Full RTL

EN
→
Full LTR

Scenario 9 — PWA Update

Download Course
→
New Service Worker
→
Update App
→
Offline Course remains available

SECURITY TESTS

بررسی کن:

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:

php artisan test

در صورت وجود:

./vendor/bin/pint --test

Frontend:

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:

Tests:
Assertions:
Failures:

Frontend:

Test Files:
Tests:
Lint:
Typecheck:
Build:

REMAINING TECHNICAL DEBT

فقط موارد واقعی را گزارش کن.

Severity:

High
Medium
Low

LEARNER EXPERIENCE SCORE

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

Learner Home
My Learning
Daily Learning
Course Player
Assessments
Progress
Learning Paths
Offline
PWA
Certificates
Notifications
Mobile UX
Accessibility
i18n
Performance
APK Readiness

در نهایت:

Learner Experience Score: XX/100

RELEASE STATUS

یکی را انتخاب کن:

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

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 اضافه کن:

PHASE 6
Android APK with Capacitor

PHASE 7
Native Push Notifications with Firebase Cloud Messaging

ترتیب نهایی Learner:

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 واقعی تبدیل کن.

قانون معماری:

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 را به پروژه اضافه کن.

ساختار باید به‌صورت استاندارد باشد:

frontend/
  src/
  dist/
  capacitor.config.*
  android/

از build output فعلی Vite استفاده کن.


2. Learner-Only Android Experience

APK باید تجربه Learner را ارائه کند.

نباید به‌صورت پیش‌فرض navigation مربوط به:

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

localhost
127.0.0.1

در Production APK hard-code نشود.

Environmentهای واقعی را پشتیبانی کن:

Development
Staging
Production
On-Premise

Configuration باید از روش استاندارد پروژه گرفته شود.


4. On-Premise Support

MicroLearning ممکن است روی Server داخلی سازمان نصب شود.

Android App باید بتواند به Endpoint سازمان متصل شود.

Architecture را طوری طراحی کن که Server/Base URL قابل configuration امن باشد اگر Business Model پروژه نیاز دارد.

Validation انجام بده:

HTTPS preferred
Valid hostname
No malformed URL
Connection test

در Production اتصال insecure را بدون تصمیم صریح Business/Security مجاز نکن.


5. Authentication

Authentication فعلی را برای Capacitor بررسی کن.

Token/Session نباید در storage ناامن نگهداری شود.

بررسی کن:

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 باید رفتار طبیعی داشته باشد.

مثلاً:

Course Player
→ Previous App Screen

Drawer Open
→ Close Drawer

Modal Open
→ Close Modal

نباید با اولین Back کل App بسته شود.

در Root Screen در صورت لزوم رفتار native مناسب داشته باش.


7. Deep Linking Foundation

زیرساخت Deep Link ایجاد کن.

هدف:

microlearning://learning/{assignmentId}

و ترجیحاً:

microlearning://learning/{assignmentId}/lesson/{lessonId}

در صورت استفاده از App Links:

https://learn.example.com/app/...

نیز architecture آماده باشد.

Deep Link باید بعد از Authentication به destination صحیح منتقل شود.


8. Native Safe Areas

بررسی کن:

Status Bar
Navigation Bar
Display Cutout
Notch
Gesture Area
Keyboard

UI نباید زیر عناصر system قرار بگیرد.

CSS safe-area را برای:

env(safe-area-inset-top)
env(safe-area-inset-bottom)

در صورت نیاز صحیح استفاده کن.


9. Android Keyboard

روی:

Login
Notes
Discussion
Assessment
Search
Forms

بررسی کن Keyboard باعث مخفی شدن input یا CTA نشود.


External URLها را audit کن.

تصمیم واضح داشته باش:

Internal route
→ App

External trusted URL
→ System browser

رفتار ناخواسته WebView ایجاد نکن.


11. Downloads

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

Certificates
Documents
Course resources

اگر download در Web کار می‌کند، رفتار Android را نیز تست کن.

برای Certificate باید حداقل امکان:

Open
Download
Share

در صورت پشتیبانی platform وجود داشته باشد.


12. Sharing

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

Certificate
Course link
Achievement

در Android از Native Share در صورت نیاز استفاده کن و Web fallback حفظ شود.


13. Network Awareness

App باید وضعیت شبکه را تشخیص دهد.

Stateهای حداقل:

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 با:

Light Theme
Dark Theme

هماهنگ شود.


17. PWA Must Continue Working

بعد از اضافه شدن Capacitor این موارد نباید خراب شوند:

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 آن را اضافه کن.

هدف آینده:

Frontend Test
↓
Frontend Build
↓
Capacitor Sync
↓
Android Build
↓
APK Artifact

اما CI موجود را بدون ضرورت بازنویسی نکن.


PHASE 6 ACCEPTANCE CRITERIA

Phase 6 فقط وقتی Complete است که:

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 مقصد:

MicroLearning Backend
        ↓
Notification Domain Event
        ↓
Notification Service
        ↓
Laravel Queue
        ↓
Firebase Cloud Messaging
        ↓
Android App
        ↓
Native Android Notification

1. Notification Architecture

Notification logic را داخل Controllerها پراکنده نکن.

Architecture ترجیحی:

Domain Event
↓
Notification Orchestrator
↓
Channel

Channelها:

InAppChannel
PushChannel
EmailChannel

Web Push در آینده قابل اضافه شدن باشد.


2. Device Registration

Backend باید Deviceهای User را مدیریت کند.

مدل مناسب طراحی کن.

مثلاً:

user_devices

فیلدهای منطقی:

id
user_id
organization_id
platform
device_identifier
push_token
enabled
last_seen_at
created_at
updated_at

نام نهایی را با conventions پروژه هماهنگ کن.


3. Multiple Devices

یک User ممکن است:

Phone
Tablet
Second Phone

داشته باشد.

Notification architecture باید Multiple Device را پشتیبانی کند.


4. Token Registration

بعد از دریافت FCM Token:

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 لازم دارند:

POST_NOTIFICATIONS

را صحیح مدیریت کن.

Permission را بلافاصله و بدون context درخواست نکن.

UX پیشنهادی:

اعلان‌های یادگیری را فعال کنید

مهلت دوره‌ها، آموزش‌های جدید و
گواهی‌های صادرشده را از دست ندهید.

[فعال کردن اعلان‌ها]
[بعداً]

از Dialog/Component استاندارد پروژه استفاده کن.


8. Notification Channels

Android Notification Channels ایجاد کن.

حداقل:

Learning
Deadlines
Certificates
System

در صورت نیاز:

Assignments
Reminders

اما Channelهای بسیار زیاد نساز.


9. Learner Notification Types

حداقل Eventهای زیر را بررسی و در صورت support Backend پیاده‌سازی کن:

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 احترام بگذار.

مثلاً:

New assignments
Deadline reminders
Daily reminders
Certificates
Organization announcements

Notificationهای security/critical system در صورت Business Rule می‌توانند سیاست متفاوت داشته باشند.


11. Scheduled Reminders

Reminderها از queue/scheduler ارسال شوند.

برای مثال:

3 days before deadline
1 day before deadline
Due today
Overdue

از Request synchronous برای ارسال bulk notification استفاده نکن.


12. Duplicate Protection

یک Notification نباید به دلیل Retry Queue چندبار برای یک Event ارسال شود.

Idempotency مناسب ایجاد کن.

مثلاً بر اساس:

user
event
assignment
notification type
scheduled window

13. Deep Link on Notification Tap

هر Push باید در صورت نیاز مقصد داشته باشد.

مثلاً:

Course Assigned

Notification
↓
My Learning
↓
Course

Deadline

Notification
↓
Assignment
↓
Resume Lesson

Certificate

Notification
↓
My Certificates
↓
Certificate

14. Foreground Behavior

اگر App باز است، Notification نباید UX آزاردهنده ایجاد کند.

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

In-app banner / toast

و در background:

Native notification

15. Notification History

Push Notification باید در صورت منطقی بودن با Notification Center داخل App هماهنگ باشد.

یعنی Notification دریافت‌شده فقط ephemeral نباشد.

User بتواند بعداً در:

Notifications

آن را مشاهده کند.


16. Read / Unread

Notification Center:

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:

.env
Secret Manager
Server Configuration

باشد.

هیچ:

Private Key
Server Key
Service Account Secret

در repository commit نشود.


19. Failure Handling

FCM responseها را مدیریت کن.

برای Tokenهای:

Invalid
Expired
Unregistered

Device token را disable/remove کن.


20. Observability

حداقل بتوانیم بفهمیم:

Queued
Sent to FCM
Failed
Invalid token

ولی Delivery قطعی را اگر FCM چنین اطلاعاتی نداده، جعلی نمایش نده.


21. Push Tests

حداقل تست:

User A notification
→ User A devices only
User B
→ Must not receive User A notification
Disabled preference
→ Optional notification not sent
Invalid token
→ Safely disabled
Logout
→ Device no longer receives private push
Notification tap
→ Correct deep link

PHASE 7 ACCEPTANCE CRITERIA

Phase 7 زمانی Complete است که:

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 را تست کن:

Learner Login
↓
Device Registered
↓
Course Assigned
↓
App Closed
↓
Native Notification Received
↓
Tap Notification
↓
App Opens
↓
Correct Course
↓
Correct Resume Location

و:

Deadline Reminder
↓
Native Notification
↓
Tap
↓
Assignment
↓
Continue Learning

و:

Course Complete
↓
Certificate Issued
↓
Native Notification
↓
My Certificates

UPDATED LEARNER RELEASE STATUS

در گزارش نهایی یکی از این وضعیت‌ها را بده:

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 جدید اضافه کن:

PHASE 6
Manager PWA & Push/Web Notification Experience

ترتیب نهایی:

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:

Manager React Experience
        ↓
Web
+
Installable PWA

1. PWA Availability

Manager بتواند در browserهای پشتیبانی‌شده PWA را Install کند.

PWA Shell باید Role-aware باشد.

وقتی Manager وارد می‌شود:

Manager Dashboard

نمایش داده شود، نه Learner Home.


2. Role Combination

اگر Manager خودش Learner هم هست، Role Switching یا Experience Switching فعلی پروژه را بررسی کن.

راه‌حل جدید duplicate نساز.

در صورت وجود switching استاندارد:

Manager Mode
Learner Mode

را حفظ کن.


3. Manager Mobile Priorities

PWA Manager روی موبایل باید حداقل این Actions را عالی پشتیبانی کند:

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

نمونه:

Team Learning
Deadlines
Approvals
Skill Alerts
Reports
System

5. Manager Notification Events

در صورت وجود داده واقعی، Manager بتواند Notification دریافت کند برای:

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 فوری نباشند.

تقسیم‌بندی منطقی:

Immediate:
Critical overdue
Approval needing action
Important assignment issue
Digest:
Team learning summary
Weekly progress
General insights

7. Manager Notification Preferences

Manager بتواند تنظیم کند:

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

Learner APK
Manager PWA
In-App Notification Center

duplicate نکن.

Architecture:

Domain Event
        ↓
Notification Service
        ↓
Recipient Resolution
        ↓
Preferences
        ↓
Channels

Channels:

In-App
FCM
Web Push
Email

باید قابل توسعه باشند.


10. Manager Assignment Notification Integration

وقتی Manager در Phase 3 دوره‌ای تخصیص می‌دهد:

Manager
↓
Assign Course
↓
Learners
↓
Notification Event
↓
In-App + FCM according to preference

در صورت APK Learner.

Manager نباید خودش مستقیم FCM API را فراخوانی کند.


11. Manager Reminder Action

Action:

Send Reminder

باید از همان Notification Service استفاده کند.

نه implementation جداگانه.

قبل از ارسال bulk reminder خلاصه نشان بده:

12 learners
Course: Workplace Safety
Channel:
In-App + Push

[Send Reminder]

12. Rate / Spam Protection

Manager نباید بتواند ناخواسته پشت سر هم Pushهای مشابه برای یک Team ارسال کند.

برای Reminder:

cooldown
duplicate detection
authorization

در نظر بگیر.


13. Team Scope

Notification recipientها حتماً Backend-scoped باشند.

Manager با دستکاری Request نباید بتواند برای افراد خارج از Team مجاز خودش Push ارسال کند.


14. Notification Audit

عملیات مهم Manager مثل:

Bulk reminder sent
Assignment notification triggered
Deadline changed

در صورت وجود Audit architecture ثبت شود.


15. PWA Responsive QA

بررسی:

360
375
390
430
768

Manager PWA روی mobile نباید desktop table shrink شده باشد.


MANAGER PHASE 6 ACCEPTANCE CRITERIA

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 مقصد:

                 MicroLearning
                      │
              Domain/Application Events
                      │
              Notification Service
                      │
          ┌───────────┼───────────┐
          │           │           │
       In-App        Push        Email
                      │
             ┌────────┴────────┐
             │                 │
            FCM             Web Push
             │                 │
       Learner APK        Manager PWA

Recipient Resolution

Notification Service باید خودش مشخص کند Recipient چه کسی است.

مثلاً:

Course Assigned
→ Learner
Deadline approaching
→ Learner
Employee overdue
→ Authorized Manager
Approval requested
→ Manager

Preferences

Flow:

Event
↓
Recipient
↓
Permission / Scope
↓
Notification Preference
↓
Channel
↓
Queue
↓
Delivery

Queue First

ارسال Notificationهای خارجی را synchronous داخل user request انجام نده.

از Queue استفاده کن.

Failure FCM/Web Push نباید عملیات اصلی مثل:

Assign Course
Complete Course
Issue Certificate

را rollback کند مگر business rule صریحی وجود داشته باشد.


Notification Taxonomy

یک taxonomy استاندارد داشته باش.

مثلاً:

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 استاندارد داشته باش:

type
title
body
recipient
entityType
entityId
deepLink
createdAt

Sensitive information اضافه نکن.


Shared Deep Links

Learner:

/course
/lesson
/certificate
/notification

Manager:

/team/member
/assignment
/approval
/report

هم Web و هم Native باید از destination منطقی مشترک استفاده کنند.


FINAL SAFETY RULE

برای اضافه کردن Capacitor، FCM یا PWA Notification:

هیچ‌یک از فازهای قبلی را دوباره Refactor نکن مگر integration واقعاً به تغییر آن نیاز داشته باشد.

اگر integration نیازمند تغییر گسترده شد:

STOP

و قبل از ادامه گزارش بده:

Integration blocker:
Why:
Affected modules:
Risk:
Minimum viable fix:
Alternative:

UPDATED EXECUTION ORDER

ترتیب پیشنهادی نهایی برای این دو بخش:

LEARNER PHASE 05
        ↓
LEARNER PHASE 6
Android APK
        ↓
LEARNER PHASE 7
FCM Push
        ↓
MANAGER PHASE 05
        ↓
MANAGER PHASE 6
PWA + Manager Notifications

اگر Manager Phaseهای 05 قبلاً انجام شده‌اند، مستقیماً Phase 6 را اجرا کن.

هیچ Phase را بدون دستور صریح من شروع نکن. پس از هر Phase تست کن، گزارش بده و متوقف شو.