================================================================================
  MOODLE AUTO-ENROLLMENT - QUICK START
================================================================================

WHAT IT DOES:
-------------
Automatically enrolls students in Moodle courses when:
1. Admin assigns subjects to students
2. Parents pay for subjects  
3. Students register with subject selection

KEY FEATURE: Maps your internal subjects to Moodle courses - NO CODE CONFLICTS!

================================================================================
HOW IT SOLVES YOUR PROBLEM:
================================================================================

YOUR REQUIREMENT:
"Admin configures student subjects → students auto-enroll in Moodle without 
course code conflicts"

OUR SOLUTION:
┌────────────────────────────────────────────────────────┐
│ Subject Mapping Table (per school)                     │
│ ────────────────────────────────────────────────────   │
│ Internal: Grade 7 Mathematics (ID: 1)                  │
│ →  Maps to → Moodle: G7-MATH (Course ID: 101)          │
│ ────────────────────────────────────────────────────   │
│ Different schools can map same subject to different    │
│ Moodle courses - NO CONFLICTS!                         │
└────────────────────────────────────────────────────────┘

================================================================================
SETUP STEPS (15 MINUTES):
================================================================================

STEP 1: RUN SQL MIGRATION
--------------------------
In phpMyAdmin or terminal:

  mysql -u root -p your_database < database/migrations/create_moodle_mapping_table.sql

This creates:
  ✓ subject_moodle_mapping (maps subjects to courses)
  ✓ moodle_enrollment_log (tracks all enrollments)
  ✓ moodle_sync_queue (queue for bulk operations)


STEP 2: CONFIGURE MOODLE SETTINGS
----------------------------------
In Admin Panel → School Settings:

  Moodle URL: https://yourschool.moodle.com
  Moodle Token: your_webservice_token_here
  Enable Moodle: ✓


STEP 3: MAP SUBJECTS TO COURSES
--------------------------------
Go to: admin/moodle/configure_mapping.php

For each subject:
  1. Select subject (e.g., Grade 7 Mathematics)
  2. Select Moodle course (from dropdown)
     OR enter manually:
       - Course Shortname: G7-MATH
       - Course ID Number: G7-MAT-003
  3. Enable Auto-enroll: ✓
  4. Enable Sync: ✓
  5. Click Save

Repeat for all subjects you want to auto-enroll.


STEP 4: TEST WITH ONE STUDENT
------------------------------
  1. Go to admin panel
  2. Assign a subject to a student
  3. Check Moodle - student should be enrolled!
  4. Check enrollment log: admin/moodle/enrollment_log.php

================================================================================
HOW IT WORKS:
================================================================================

FLOW:
-----
Admin assigns "Grade 7 Math" to student John
         ↓
System checks mapping table:
  - School: KINE
  - Subject: Grade 7 Math (ID: 1)
  - Maps to: Moodle Course "G7-MATH" (ID: 101)
         ↓
System checks if John exists in Moodle
  - If NO: Create user in Moodle
  - If YES: Use existing Moodle user ID
         ↓
System enrolls John in course ID 101
         ↓
Logs result in moodle_enrollment_log
         ↓
Done! John can now access course in Moodle


MULTI-SCHOOL EXAMPLE:
----------------------
School A: 
  Subject "Math" → Moodle "SCHOOL-A-MATH" ✓

School B:
  Subject "Math" → Moodle "SCHOOL-B-MATH" ✓

Same internal subject, different Moodle courses - NO CONFLICTS!

================================================================================
WHERE AUTO-ENROLLMENT HAPPENS:
================================================================================

1. ADMIN ASSIGNS SUBJECTS
   File: admin/students/assign_subjects.php
   Trigger: When admin clicks "Assign Subjects"
   
   Code to add:
   ```php
   require_once '../../includes/moodle_enrollment_handler.php';
   $handler = new MoodleEnrollmentHandler($academy_reference, $pdo);
   $handler->enrollStudentInSubject($student_id, $subject_id);
   ```

2. PARENT PAYMENT
   File: parent/process_payment.php  
   Trigger: When payment completes
   Status: Already partially implemented, needs enhancement
   
3. STUDENT REGISTRATION
   File: register.php
   Trigger: After student registers and selects subjects

================================================================================
EXAMPLE MAPPING CONFIGURATION:
================================================================================

GRADE 7 SUBJECTS:
┌──────────────────────────┬──────────────────────┬─────────────┐
│ Internal Subject         │ Moodle Course        │ Auto-Enroll │
├──────────────────────────┼──────────────────────┼─────────────┤
│ Grade 7 Mathematics      │ G7-MATH              │     ✓       │
│ Grade 7 English          │ G7-ENG               │     ✓       │
│ Grade 7 SiSwati          │ G7-SIS               │     ✓       │
│ Grade 7 Science          │ G7-SCI               │     ✓       │
│ Grade 7 Social Studies   │ G7-SOC               │     ✓       │
│ Grade 7 Physical Ed      │ G7-PE                │     ✓       │
└──────────────────────────┴──────────────────────┴─────────────┘

FORM 1 SUBJECTS:
┌──────────────────────────┬──────────────────────┬─────────────┐
│ Form 1 Mathematics       │ F1-MATH              │     ✓       │
│ Form 1 English           │ F1-ENG               │     ✓       │
│ Form 1 Integrated Science│ F1-ISCI              │     ✓       │
│ Form 1 Business Studies  │ F1-BUS               │     ✓       │
└──────────────────────────┴──────────────────────┴─────────────┘

================================================================================
ADMIN INTERFACE:
================================================================================

URL: admin/moodle/configure_mapping.php

FEATURES:
  ✓ Visual mapping interface
  ✓ Dropdown of available Moodle courses
  ✓ Enable/disable per subject
  ✓ View all current mappings
  ✓ Edit existing mappings
  ✓ Delete mappings
  ✓ Test Moodle connection
  ✓ Sync all students
  ✓ View enrollment log

================================================================================
MONITORING:
================================================================================

VIEW ENROLLMENT LOG:
  URL: admin/moodle/enrollment_log.php
  Shows: All enrollment attempts, successes, failures

CHECK SYNC STATUS:
  SQL Query:
  ```sql
  SELECT 
    status, 
    COUNT(*) as count
  FROM moodle_enrollment_log
  WHERE academy_reference = 'YOUR_SCHOOL'
  GROUP BY status;
  ```

FIND FAILED ENROLLMENTS:
  ```sql
  SELECT 
    s.full_name,
    sub.name as subject,
    el.error_message
  FROM moodle_enrollment_log el
  JOIN students s ON el.student_id = s.id
  JOIN subjects sub ON el.subject_id = sub.id
  WHERE el.status = 'failed'
  ORDER BY el.attempted_at DESC;
  ```

================================================================================
BENEFITS:
================================================================================

✓ AUTOMATIC - No manual Moodle work
✓ CONFLICT-FREE - Per-school course mapping
✓ SCALABLE - Handles thousands of students
✓ AUDITABLE - Complete enrollment log
✓ RECOVERABLE - Failed enrollments can retry
✓ MULTI-TENANT - Each school independent
✓ FLEXIBLE - Can disable per subject
✓ SECURE - Token-based authentication

================================================================================
FILES CREATED:
================================================================================

1. database/migrations/create_moodle_mapping_table.sql
   - Database schema (3 tables)

2. admin/moodle/configure_mapping.php
   - Admin interface for mappings

3. includes/moodle_enrollment_handler.php
   - Enrollment logic and API calls

4. MOODLE_AUTO_ENROLLMENT_GUIDE.md
   - Complete technical documentation

5. MOODLE_QUICK_START.txt
   - This file (quick reference)

================================================================================
TESTING CHECKLIST:
================================================================================

[ ] SQL migration run successfully
[ ] Moodle settings configured (URL, token)
[ ] At least one subject mapped to course
[ ] Test connection button works
[ ] Assign subject to student → Check Moodle
[ ] Student appears in Moodle course
[ ] Enrollment log shows success
[ ] Try unmapped subject → Graceful error
[ ] Test with different school → Correct course

================================================================================
TROUBLESHOOTING:
================================================================================

ISSUE: "No Moodle mapping configured"
FIX: Go to configure_mapping.php and create mapping

ISSUE: "Student not enrolled"
CHECK:
  - Mapping exists?
  - Auto-enroll enabled?
  - Moodle token valid?
  - Check enrollment log for errors

ISSUE: "Course not found"
FIX: Update mapping with correct course shortname

================================================================================
SUPPORT:
================================================================================

Full Documentation: MOODLE_AUTO_ENROLLMENT_GUIDE.md
Enrollment Log: admin/moodle/enrollment_log.php
Test Connection: admin/moodle/test_connection.php
Configure Mappings: admin/moodle/configure_mapping.php

================================================================================

READY TO IMPLEMENT!

1. Upload files to server
2. Run SQL migration  
3. Configure settings
4. Map subjects
5. Test!

Your students will auto-enroll in Moodle when subjects are assigned! 🎉

================================================================================

