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:
- تغییرات همان Phase را کامل کن.
- Regression Test اجرا کن.
- Backend Tests مرتبط را اجرا کن.
- Frontend Tests مرتبط را اجرا کن.
npm run lintرا اجرا کن.npm run typecheckرا اجرا کن.npm testرا اجرا کن.npm run buildرا اجرا کن.git diffرا بررسی کن.- فایلهای تغییرکرده را اعلام کن.
- Bugs Fixed را گزارش کن.
- Remaining Issues را گزارش کن.
- متوقف شو.
بدون دستور صریح من:
برو فاز بعد
وارد 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 نشود.
10. External Links
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 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 تست کن، گزارش بده و متوقف شو.