<?php
/**
 * ==============================================================================
 * SAQEL ENTERPRISE - CURRICULUM VERTICAL & HORIZONTAL INTEGRATION SERVICE
 * ==============================================================================
 * 
 * ملف: CurriculumIntegrationService.php
 * الهدف المعماري:
 * إدارة التكامل المعرفي بين المناهج والمراحل:
 * 1. التكامل الرأسي (Vertical Integration): تسلسل المفاهيم وامتدادها عبر الصفوف المتعاقبة
 *    (من الصفوف الأساسية وصولاً إلى التوجيهي الوزاري 2008، وتتبع المتطلبات السابقة).
 * 2. التكامل الأفقي (Horizontal Integration): الترابط البيني بين المباحث المختلفة في نفس الصف
 *    (مثل التقاطع بين حساب المثلثات في الرياضيات والمتجهات وقوانين الحركة في الفيزياء).
 * 3. التصفية التلقائية للشجرة الهرمية بناءً على الصف المترفع له الطالب.
 */

namespace App\Services;

class CurriculumIntegrationService
{
    /**
     * استرجاع شجرة المناهج المخصصة لصف معين حصراً
     */
    public static function getCurriculumTreeForGrade(string $gradeLevel): array
    {
        $normalized = StudentAccessControlService::normalizeGrade($gradeLevel);
        $fullTree = CurriculumService::getCurriculumTree();

        if (isset($fullTree[$normalized])) {
            return [
                'grade_key'  => $normalized,
                'grade_name' => $fullTree[$normalized]['name'] ?? $normalized,
                'data'       => $fullTree[$normalized]
            ];
        }

        // إذا كان الصف غير مدرج بعد في المانيفست
        return [
            'grade_key'  => $normalized,
            'grade_name' => StudentAccessControlService::getGradeDisplayName($normalized),
            'data'       => [
                'name'     => StudentAccessControlService::getGradeDisplayName($normalized),
                'subjects' => []
            ]
        ];
    }

    /**
     * استخراج خارطة التكامل الرأسي والأفقي الشاملة لصف دراسي
     */
    public static function getIntegratedCurriculumMap(string $gradeLevel): array
    {
        $normalized = StudentAccessControlService::normalizeGrade($gradeLevel);
        $fullTree = CurriculumService::getCurriculumTree();
        $gradeData = $fullTree[$normalized] ?? [];

        $framework = $gradeData['curriculum_framework'] ?? [];
        $vertical = $framework['vertical_progression'] ?? [
            'previous_grade' => null,
            'next_grade'     => null,
            'core_bridges'   => []
        ];
        $horizontal = $framework['horizontal_integration'] ?? [];

        return [
            'status'                 => 'success',
            'grade_key'              => $normalized,
            'grade_display_name'     => StudentAccessControlService::getGradeDisplayName($normalized),
            'vertical_progression'   => [
                'previous_grade_name' => $vertical['previous_grade'] ? StudentAccessControlService::getGradeDisplayName($vertical['previous_grade']) : null,
                'next_grade_name'     => $vertical['next_grade'] ? StudentAccessControlService::getGradeDisplayName($vertical['next_grade']) : null,
                'bridges'             => $vertical['core_bridges'] ?? []
            ],
            'horizontal_connections' => $horizontal,
            'total_subjects_count'   => count($gradeData['subjects'] ?? [])
        ];
    }

    /**
     * البحث عن الروابط المفاهيمية بين مادتين داخل نفس الصف
     */
    public static function findCrossSubjectSynergy(string $gradeLevel, string $subjectA, string $subjectB): array
    {
        $map = self::getIntegratedCurriculumMap($gradeLevel);
        $connections = $map['horizontal_connections'] ?? [];

        $matches = [];
        foreach ($connections as $conn) {
            $subs = $conn['participating_subjects'] ?? [];
            if (in_array($subjectA, $subs) && in_array($subjectB, $subs)) {
                $matches[] = $conn;
            }
        }

        return $matches;
    }
}