math_cms/app/Services/LearningAnalyticsService.php

<?php

namespace App\Services;

use Exception;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\DB;
use App\Services\ExamTypeStrategy;
use App\Services\QuestionExpansionService;

/**
 * 学习分析服务（本地化重构版）
 *
 * 原先调用外部 LearningAnalytics API (localhost:5016)
 * 现已重构为使用本地服务：MasteryCalculator、KnowledgeMasteryService 等
 */
class LearningAnalyticsService
{
    protected string $baseUrl;
    protected int $timeout = 10;
    protected ?QuestionExpansionService $questionExpansionService;
    protected ?MasteryCalculator $masteryCalculator;
    protected ?LocalAIAnalysisService $aiAnalysisService;

    public function __construct(
        ?QuestionExpansionService $questionExpansionService = null,
        ?MasteryCalculator $masteryCalculator = null,
        ?LocalAIAnalysisService $aiAnalysisService = null
    ) {
        // 保留baseUrl用于兼容，但不再实际调用
        $this->baseUrl = config('services.learning_analytics.url', env('LEARNING_ANALYTICS_API_BASE', 'http://localhost:5016'));
        $this->questionExpansionService = $questionExpansionService;
        $this->masteryCalculator = $masteryCalculator ?? app(MasteryCalculator::class);
        $this->aiAnalysisService = $aiAnalysisService ?? app(LocalAIAnalysisService::class);
    }

    /**
     * 获取学生掌握度（本地化）
     */
    public function getStudentMastery(string $studentId, string $kpCode = null): array
    {
        try {
            Log::info('LearningAnalyticsService: 获取学生掌握度 (本地)', [
                'student_id' => $studentId,
                'kp_code' => $kpCode
            ]);

            if ($kpCode) {
                // 获取特定知识点掌握度
                $result = $this->masteryCalculator->calculateMasteryLevel($studentId, $kpCode);
                return [
                    'student_id' => $studentId,
                    'kp_code' => $kpCode,
                    'mastery_level' => $result['mastery'],
                    'confidence' => $result['confidence'],
                    'trend' => $result['trend'],
                    'total_attempts' => $result['total_attempts'],
                    'correct_attempts' => $result['correct_attempts'],
                ];
            }

            // 获取全部知识点掌握度概览
            $overview = $this->masteryCalculator->getStudentMasteryOverview($studentId);
            return [
                'student_id' => $studentId,
                'total_knowledge_points' => $overview['total_knowledge_points'],
                'average_mastery' => $overview['average_mastery_level'],
                'mastered_count' => $overview['mastered_knowledge_points'],
                'good_count' => $overview['good_knowledge_points'],
                'weak_count' => $overview['weak_knowledge_points'],
                'weak_list' => $overview['weak_knowledge_points_list'],
                'details' => $overview['details'],
            ];
        } catch (\Exception $e) {
            Log::error('LearningAnalyticsService: 获取掌握度失败', [
                'student_id' => $studentId,
                'error' => $e->getMessage(),
            ]);

            return [
                'error' => true,
                'message' => $e->getMessage()
            ];
        }
    }

    /**
     * 更新学生掌握度（本地化）
     */
    public function updateMastery(array $data): array
    {
        try {
            $studentId = $data['student_id'];
            $kpCode = $data['kp_code'];
            $isCorrect = $data['is_correct'] ?? false;
            $difficulty = $data['difficulty_level'] ?? 0.5;

            Log::info('LearningAnalyticsService: 更新掌握度 (本地)', [
                'student_id' => $studentId,
                'kp_code' => $kpCode,
            ]);

            // 获取当前掌握度
            $currentMastery = DB::table('student_knowledge_mastery')
                ->where('student_id', $studentId)
                ->where('kp_code', $kpCode)
                ->value('mastery_level') ?? 0.5;

            // 使用LocalAIAnalysisService更新掌握度
            $result = $this->aiAnalysisService->updateMastery(
                $studentId,
                $kpCode,
                $currentMastery,
                $isCorrect,
                $difficulty
            );

            return [
                'success' => true,
                'data' => $result
            ];
        } catch (\Exception $e) {
            Log::error('LearningAnalyticsService: 更新掌握度失败', [
                'data' => $data,
                'error' => $e->getMessage(),
            ]);

            return [
                'error' => true,
                'message' => $e->getMessage()
            ];
        }
    }

    /**
     * 获取老师名下的所有学生
     */
    public function getTeacherStudents(string $teacherId): array
    {
        try {
            // 从本地MySQL获取学生
            $students = DB::table('students as s')
                ->leftJoin('users as u', 's.student_id', '=', 'u.user_id')
                ->where('s.teacher_id', $teacherId)
                ->select(
                    's.student_id',
                    's.name',
                    's.grade',
                    's.class_name',
                    'u.username',
                    'u.email'
                )
                ->get()
                ->toArray();

            return $students;
        } catch (\Exception $e) {
            Log::error('Get Teacher Students Error', [
                'teacher_id' => $teacherId,
                'error' => $e->getMessage()
            ]);

            return [];
        }
    }

    /**
     * 获取学生学习分析
     */
    public function getStudentAnalysis(string $studentId): array
    {
        // 从LearningAnalytics获取掌握度
        $masteryData = $this->getStudentMastery($studentId);

        // 从MySQL获取练习历史
        $exercises = DB::table('student_exercises')
            ->where('student_id', $studentId)
            ->orderBy('created_at', 'desc')
            ->limit(50)
            ->get()
            ->toArray();

        // 从MySQL获取掌握度记录
        $masteryRecords = DB::table('student_mastery')
            ->where('student_id', $studentId)
            ->get()
            ->toArray();

        return [
            'student_id' => $studentId,
            'mastery_from_la' => $masteryData,
            'exercises' => $exercises,
            'mastery_records' => $masteryRecords,
            'total_exercises' => count($exercises),
            'total_mastery_records' => count($masteryRecords),
        ];
    }

    /**
     * 生成学习测试数据
     */
    public function generateLearningData(string $studentId, array $params): array
    {
        $results = [];

        foreach ($params as $param) {
            $data = [
                'student_id' => $studentId,
                'kp_code' => $param['kp_code'],
                'is_correct' => $param['is_correct'],
                'time_spent_seconds' => $param['time_spent_seconds'] ?? 120,
                'difficulty_level' => $param['difficulty_level'] ?? 3,
            ];

            $result = $this->updateMastery($data);
            $results[] = $result;
        }

        return $results;
    }

    /**
     * 获取学习推荐
     */
    public function getLearningRecommendations(string $studentId): array
    {
        try {
            Log::info('LearningAnalytics Request: Get Learning Recommendations', [
                'url' => $this->baseUrl . "/api/v1/learning-path/student/{$studentId}/recommend"
            ]);

            $response = Http::timeout($this->timeout)
                ->post($this->baseUrl . "/api/v1/learning-path/student/{$studentId}/recommend");

            Log::info('LearningAnalytics Response: Get Learning Recommendations', [
                'status' => $response->status(),
                'body' => $response->json()
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            return ['error' => true, 'message' => 'Failed to fetch recommendations'];
        } catch (\Exception $e) {
            return ['error' => true, 'message' => $e->getMessage()];
        }
    }

    /**
     * 获取知识点列表（从知识图谱API）
     */
    public function getKnowledgePoints(array $filters = []): array
    {
        try {
            $kgBaseUrl = config('services.knowledge_api.base_url', 'http://localhost:5011');
            Log::info('LearningAnalytics Request: Get Knowledge Points', [
                'url' => $kgBaseUrl . '/knowledge-points/',
                'filters' => $filters
            ]);

            $response = Http::timeout($this->timeout)
                ->get($kgBaseUrl . '/knowledge-points/', $filters);

            Log::info('LearningAnalytics Response: Get Knowledge Points', [
                'status' => $response->status(),
                'count' => count($response->json()['data'] ?? [])
            ]);

            if ($response->successful()) {
                return $response->json()['data'] ?? [];
            }

            return [];
        } catch (\Exception $e) {
            Log::error('LearningAnalytics Knowledge Points Error', [
                'error' => $e->getMessage()
            ]);

            return [];
        }
    }

    /**
     * 获取学生技能熟练度
     */
    public function getStudentSkillProficiency(string $studentId): array
    {
        try {
            Log::info('LearningAnalytics Request: Get Student Skill Proficiency', [
                'url' => $this->baseUrl . "/api/v1/skill/proficiency/student/{$studentId}"
            ]);

            $response = Http::timeout($this->timeout)
                ->get($this->baseUrl . "/api/v1/skill/proficiency/student/{$studentId}");

            Log::info('LearningAnalytics Response: Get Student Skill Proficiency', [
                'status' => $response->status(),
                'body' => $response->json()
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::warning('LearningAnalytics Skill Proficiency API Error', [
                'student_id' => $studentId,
                'status' => $response->status(),
                'response' => $response->body()
            ]);

            // API失败时返回空数据，不报错
            return [
                'student_id' => $studentId,
                'total_count' => 0,
                'data' => []
            ];
        } catch (\Exception $e) {
            Log::warning('LearningAnalytics Skill Proficiency API Exception', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);

            // 发生异常时返回空数据，不报错
            return [
                'student_id' => $studentId,
                'total_count' => 0,
                'data' => []
            ];
        }
    }

    /**
     * 获取学生掌握度列表（别名方法）
     */
    public function getStudentMasteryList(string $studentId): array
    {
        return $this->getStudentMastery($studentId);
    }

    /**
     * 获取知识点依赖关系
     */
    public function getKnowledgeDependencies(): array
    {
        try {
            Log::info('LearningAnalytics Request: Get Knowledge Dependencies', [
                'url' => $this->baseUrl . '/knowledge-dependencies/'
            ]);

            $response = Http::timeout($this->timeout)
                ->get($this->baseUrl . '/knowledge-dependencies/');

            Log::info('LearningAnalytics Response: Get Knowledge Dependencies', [
                'status' => $response->status(),
                'count' => count($response->json()['data'] ?? [])
            ]);

            if ($response->successful()) {
                return $response->json()['data'] ?? [];
            }

            return [];
        } catch (\Exception $e) {
            Log::error('LearningAnalytics Knowledge Dependencies Error', [
                'error' => $e->getMessage()
            ]);

            return [];
        }
    }

    /**
     * 提交学生答题记录
     */
    public function submitAttempt(string $studentId, array $attemptData): array
    {
        try {
            Log::info('LearningAnalytics Request: Submit Attempt', [
                'url' => $this->baseUrl . "/api/v1/attempts/student/{$studentId}",
                'data' => $attemptData
            ]);

            $response = Http::timeout($this->timeout)
                ->post($this->baseUrl . "/api/v1/attempts/student/{$studentId}", $attemptData);

            Log::info('LearningAnalytics Response: Submit Attempt', [
                'status' => $response->status(),
                'body' => $response->json()
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Submit Attempt Error', [
                'student_id' => $studentId,
                'data' => $attemptData,
                'status' => $response->status(),
                'response' => $response->body()
            ]);

            return [
                'error' => true,
                'message' => 'Failed to submit attempt'
            ];
        } catch (\Exception $e) {
            Log::error('Submit Attempt Exception', [
                'student_id' => $studentId,
                'error' => $e->getMessage(),
                'data' => $attemptData
            ]);

            return [
                'error' => true,
                'message' => $e->getMessage()
            ];
        }
    }

    /**
     * 批量提交学生答题记录
     */
    public function submitBatchAttempts(string $studentId, array $data): array
    {
        try {
            Log::info('LearningAnalytics Request: Submit Batch Attempts', [
                'url' => $this->baseUrl . "/api/v1/attempts/batch/student/{$studentId}",
                'data_count' => count($data['answers'] ?? []),
                'paper_id' => $data['paper_id'] ?? null
            ]);

            $response = Http::timeout($this->timeout)
                ->post($this->baseUrl . "/api/v1/attempts/batch/student/{$studentId}", $data);

            Log::info('LearningAnalytics Response: Submit Batch Attempts', [
                'status' => $response->status(),
                'body' => $response->json()
            ]);

            if ($response->successful()) {
                return $response->json();
            }

            Log::error('Submit Batch Attempts Error', [
                'student_id' => $studentId,
                'data_count' => count($data['answers'] ?? []),
                'status' => $response->status(),
                'response' => $response->body()
            ]);

            return [
                'error' => true,
                'message' => 'Failed to submit batch attempts: ' . $response->body()
            ];
        } catch (\Exception $e) {
            Log::error('Submit Batch Attempts Exception', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);

            return [
                'error' => true,
                'message' => $e->getMessage()
            ];
        }
    }

    /**
     * 提交OCR分析请求
     */
    public function submitOCRAnalysis(array $data): array
    {
        Log::warning('submitOCRAnalysis 已停用：分析项目已下线', [
            'student_id' => $data['student_id'] ?? 'unknown',
            'exam_id' => $data['exam_id'] ?? 'unknown',
        ]);

        return [
            'success' => false,
            'message' => 'analysis_api_disabled',
        ];
    }

    /**
     * 获取分析结果详情
     */
    public function getAnalysisResult(string $analysisId): array
    {
        Log::warning('getAnalysisResult 已停用：分析项目已下线', [
            'analysis_id' => $analysisId,
        ]);

        return [
            'success' => false,
            'message' => 'analysis_api_disabled',
        ];
    }

    /**
     * 检查服务健康状态（本地化）
     */
    public function checkHealth(): bool
    {
        // 检查本地服务是否可用
        try {
            $this->masteryCalculator->getStudentMasteryOverview('test');
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }

    /**
     * 获取学生掌握度概览（本地化）
     */
    public function getStudentMasteryOverview(string $studentId): array
    {
        try {
            // 直接使用MasteryCalculator
            $overview = $this->masteryCalculator->getStudentMasteryOverview($studentId);

            return [
                'total_knowledge_points' => $overview['total_knowledge_points'],
                'average_mastery_level' => $overview['average_mastery_level'],
                'mastered_knowledge_points' => $overview['mastered_knowledge_points'],
                'good_knowledge_points' => $overview['good_knowledge_points'],
                'weak_knowledge_points' => $overview['weak_knowledge_points'],
                'weak_knowledge_points_list' => $overview['weak_knowledge_points_list'],
                'details' => $overview['details']
            ];
        } catch (\Exception $e) {
            Log::error('Get Student Mastery Overview Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return [
                'total_knowledge_points' => 0,
                'average_mastery_level' => 0,
                'mastered_knowledge_points' => 0,
                'good_knowledge_points' => 0,
                'weak_knowledge_points' => 0,
                'weak_knowledge_points_list' => [],
                'details' => []
            ];
        }
    }

    /**
     * 获取学生技能摘要
     */
    public function getStudentSkillSummary(string $studentId): array
    {
        try {
            $proficiency = $this->getStudentSkillProficiency($studentId);

            // 无论是否有error，都继续处理，返回空数据
            $data = $proficiency['data'] ?? [];
            $totalSkills = count($data);
            $averageLevel = $totalSkills > 0 ? array_sum(array_column($data, 'proficiency_level')) / $totalSkills : 0;

            // 计算总答题数
            $totalQuestions = 0;
            foreach ($data as $skill) {
                $totalQuestions += $skill['total_questions_attempted'] ?? 0;
            }

            return [
                'total_skills' => $totalSkills,
                'average_proficiency_level' => $averageLevel,
                'total_questions_attempted' => $totalQuestions,
                'skill_list' => $data
            ];
        } catch (\Exception $e) {
            Log::warning('Get Student Skill Summary Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            // 发生异常时返回空数据
            return [
                'total_skills' => 0,
                'average_proficiency_level' => 0,
                'total_questions_attempted' => 0,
                'skill_list' => []
            ];
        }
    }

    /**
     * 获取学生预测数据（本地化 - 已停用外部API）
     */
    public function getStudentPredictions(string $studentId, int $count = 5): array
    {
        // 外部API已停用，基于本地数据生成预测
        try {
            Log::info('LearningAnalyticsService: 获取学生预测 (本地)', [
                'student_id' => $studentId,
            ]);

            $overview = $this->masteryCalculator->getStudentMasteryOverview($studentId);
            $avgMastery = $overview['average_mastery_level'] ?? 0;

            // 基于掌握度生成简单预测
            $predictions = [];
            if ($avgMastery > 0) {
                $predictions[] = [
                    'type' => 'score_improvement',
                    'current_level' => round($avgMastery * 100),
                    'predicted_improvement' => rand(5, 15),
                    'confidence' => 0.75,
                ];
            }

            return [
                'predictions' => $predictions
            ];
        } catch (\Exception $e) {
            Log::error('Get Student Predictions Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return [
                'predictions' => []
            ];
        }
    }

    /**
     * 获取学生学习路径（本地化 - 已停用外部API）
     */
    public function getStudentLearningPaths(string $studentId, int $count = 3): array
    {
        // 外部API已停用，基于薄弱点生成学习路径
        try {
            Log::info('LearningAnalyticsService: 获取学习路径 (本地)', [
                'student_id' => $studentId,
            ]);

            $overview = $this->masteryCalculator->getStudentMasteryOverview($studentId);
            $weakPoints = $overview['weak_knowledge_points_list'] ?? [];

            $paths = [];
            foreach (array_slice($weakPoints, 0, $count) as $weak) {
                $paths[] = [
                    'kp_code' => $weak->kp_code ?? $weak['kp_code'] ?? '',
                    'current_mastery' => $weak->mastery_level ?? $weak['mastery_level'] ?? 0,
                    'target_mastery' => 0.85,
                    'recommended_practice' => 5,
                ];
            }

            return [
                'paths' => $paths
            ];
        } catch (\Exception $e) {
            Log::error('Get Student Learning Paths Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return [
                'paths' => []
            ];
        }
    }

    /**
     * 获取预测分析数据
     */
    public function getPredictionAnalytics(string $studentId): array
    {
        try {
            $predictions = $this->getStudentPredictions($studentId, 10);

            if (empty($predictions)) {
                return ['accuracy' => 0, 'trend' => 'stable', 'confidence' => 0];
            }

            $accuracy = 0;
            $confidence = 0;
            if (!empty($predictions)) {
                $accuracy = rand(75, 95); // 模拟准确率
                $confidence = rand(70, 90); // 模拟置信度
            }

            $trend = 'improving'; // improving, stable, declining

            return [
                'accuracy' => $accuracy,
                'trend' => $trend,
                'confidence' => $confidence,
                'sample_size' => count($predictions)
            ];
        } catch (\Exception $e) {
            Log::error('Get Prediction Analytics Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return ['accuracy' => 0, 'trend' => 'stable', 'confidence' => 0];
        }
    }

    /**
     * 获取学习路径分析数据
     */
    public function getLearningPathAnalytics(string $studentId): array
    {
        try {
            $paths = $this->getStudentLearningPaths($studentId, 5);

            if (empty($paths)) {
                return [
                    'active_paths' => 0,
                    'completed_paths' => 0,
                    'average_efficiency_score' => 0,
                    'completion_rate' => 0,
                    'average_time' => 0,
                    'total_paths' => 0
                ];
            }

            $activePaths = 0;
            $completedPaths = 0;
            $efficiencyScores = [];

            foreach ($paths as $path) {
                if (($path['status'] ?? '') === 'active') {
                    $activePaths++;
                }
                if (($path['status'] ?? '') === 'completed') {
                    $completedPaths++;
                }
                if (isset($path['efficiency_score'])) {
                    $efficiencyScores[] = $path['efficiency_score'];
                }
            }

            $averageEfficiency = !empty($efficiencyScores)
                ? array_sum($efficiencyScores) / count($efficiencyScores)
                : rand(60, 85) / 100;

            $completionRate = count($paths) > 0
                ? ($completedPaths / count($paths)) * 100
                : 0;

            $averageTime = rand(30, 60); // 模拟平均时间（分钟）

            return [
                'active_paths' => $activePaths,
                'completed_paths' => $completedPaths,
                'average_efficiency_score' => $averageEfficiency,
                'completion_rate' => $completionRate,
                'average_time' => $averageTime,
                'total_paths' => count($paths)
            ];
        } catch (\Exception $e) {
            Log::error('Get Learning Path Analytics Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return [
                'active_paths' => 0,
                'completed_paths' => 0,
                'average_efficiency_score' => 0,
                'completion_rate' => 0,
                'average_time' => 0,
                'total_paths' => 0
            ];
        }
    }

    /**
     * 快速分数预测
     */
    public function quickScorePrediction(string $studentId): array
    {
        Log::info('开始调用快速预测API', ['student_id' => $studentId]);

        $response = Http::timeout($this->timeout)
            ->post($this->baseUrl . "/api/v1/prediction/student/{$studentId}/quick-prediction");

        Log::info('快速预测API响应', [
            'student_id' => $studentId,
            'status' => $response->status(),
            'body' => $response->body()
        ]);

        if (!$response->successful()) {
            throw new \Exception(sprintf(
                '快速预测接口失败: %s %s',
                $response->status(),
                $response->body()
            ));
        }

        $data = $response->json();
        Log::info('快速预测API返回数据', ['student_id' => $studentId, 'data' => $data]);

        // API 返回结构：{ student_id, current_assumption, target_assumption, quick_prediction, prediction_id, message }
        $quickPredictionData = $data['quick_prediction'] ?? [];

        return [
            'quick_prediction' => [
                'current_score' => $quickPredictionData['current_score'] ?? $data['current_assumption'] ?? 0,
                'predicted_score' => $quickPredictionData['predicted_score'] ?? $data['target_assumption'] ?? 0,
                'improvement_potential' => $quickPredictionData['improvement_potential'] ?? (($data['target_assumption'] ?? 0) - ($data['current_assumption'] ?? 0)),
                'estimated_study_hours' => $quickPredictionData['estimated_study_hours'] ?? 0,
                'confidence_level' => $quickPredictionData['confidence_level'] ?? 0,
                'priority_topics' => $quickPredictionData['priority_topics'] ?? [],
                'recommended_actions' => $quickPredictionData['recommended_actions'] ?? [],
                'weak_knowledge_points_count' => $quickPredictionData['weak_knowledge_points_count'] ?? 0,
                'total_knowledge_points' => $quickPredictionData['total_knowledge_points'] ?? 0
            ],
            'predicted_score' => $quickPredictionData['predicted_score'] ?? $data['target_assumption'] ?? 0,
            'confidence' => isset($quickPredictionData['confidence_level']) ? $quickPredictionData['confidence_level'] * 100 : 0,
            'time_estimate' => $quickPredictionData['estimated_study_hours'] ?? 0,
            'prediction_id' => $data['prediction_id'] ?? null,
            'message' => $data['message'] ?? null,
        ];
    }

    /**
     * 推荐学习路径（本地化）
     */
    public function recommendLearningPaths(string $studentId, int $count = 3): array
    {
        try {
            Log::info('LearningAnalyticsService: 推荐学习路径 (本地)', [
                'student_id' => $studentId,
            ]);

            $overview = $this->masteryCalculator->getStudentMasteryOverview($studentId);
            $weakPoints = $overview['weak_knowledge_points_list'] ?? [];

            $recommendations = [];
            foreach (array_slice($weakPoints, 0, $count) as $weak) {
                $kpCode = is_object($weak) ? $weak->kp_code : ($weak['kp_code'] ?? '');
                $masteryLevel = is_object($weak) ? $weak->mastery_level : ($weak['mastery_level'] ?? 0);

                $recommendations[] = [
                    'kp_code' => $kpCode,
                    'kp_name' => $this->getKnowledgePointName($kpCode),
                    'current_mastery' => $masteryLevel,
                    'target_mastery' => 0.85,
                    'priority' => 1 - $masteryLevel,
                    'recommended_practice_count' => max(3, intval((0.85 - $masteryLevel) * 10)),
                    'estimated_time_minutes' => max(15, intval((0.85 - $masteryLevel) * 60)),
                ];
            }

            return [
                'recommendations' => $recommendations
            ];
        } catch (\Exception $e) {
            Log::error('Recommend Learning Paths Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return [
                'recommendations' => []
            ];
        }
    }

    /**
     * 获取知识点名称
     */
    private function getKnowledgePointName(string $kpCode): string
    {
        try {
            $kp = DB::table('knowledge_points')
                ->where('kp_code', $kpCode)
                ->value('name');
            return $kp ?? $kpCode;
        } catch (\Exception $e) {
            return $kpCode;
        }
    }

    /**
     * 重新计算掌握度（本地化）
     */
    public function recalculateMastery(string $studentId, string $kpCode): bool
    {
        try {
            Log::info('LearningAnalyticsService: 重新计算掌握度 (本地)', [
                'student_id' => $studentId,
                'kp_code' => $kpCode,
            ]);

            // 使用MasteryCalculator重新计算
            $result = $this->masteryCalculator->calculateMasteryLevel($studentId, $kpCode);

            // 更新到数据库
            DB::table('student_knowledge_mastery')
                ->updateOrInsert(
                    ['student_id' => $studentId, 'kp_code' => $kpCode],
                    [
                        'mastery_level' => $result['mastery'],
                        'confidence_level' => $result['confidence'],
                        'total_attempts' => $result['total_attempts'],
                        'correct_attempts' => $result['correct_attempts'],
                        'mastery_trend' => $result['trend'],
                        'last_mastery_update' => now(),
                        'updated_at' => now(),
                    ]
                );

            return true;
        } catch (\Exception $e) {
            Log::error('Recalculate Mastery Error', [
                'student_id' => $studentId,
                'kp_code' => $kpCode,
                'error' => $e->getMessage()
            ]);
            return false;
        }
    }

    /**
     * 批量更新技能熟练度（本地化）
     */
    public function batchUpdateSkillProficiency(string $studentId): bool
    {
        try {
            Log::info('LearningAnalyticsService: 批量更新技能熟练度 (本地)', [
                'student_id' => $studentId,
            ]);

            // 获取学生所有知识点
            $kpCodes = DB::table('student_knowledge_mastery')
                ->where('student_id', $studentId)
                ->pluck('kp_code')
                ->toArray();

            // 批量更新
            $this->masteryCalculator->batchUpdateMastery($studentId, $kpCodes);

            return true;
        } catch (\Exception $e) {
            Log::error('Batch Update Skill Proficiency Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return false;
        }
    }

    /**
     * 清空学生所有答题数据（本地化）
     */
    public function clearStudentData(string $studentId): bool
    {
        try {
            Log::info('LearningAnalyticsService: 清空学生数据 (本地)', [
                'student_id' => $studentId,
            ]);

            // 清空MySQL中的数据
            $this->clearStudentMySQLData($studentId);

            Log::info('Student Data Cleared Successfully', [
                'student_id' => $studentId,
            ]);

            return true;
        } catch (\Exception $e) {
            Log::error('Clear Student Data Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            return false;
        }
    }

    /**
     * 清空学生MySQL中的答题数据
     */
    private function clearStudentMySQLData(string $studentId): void
    {
        try {
            // 清空student_exercises表
            DB::table('student_exercises')
                ->where('student_id', $studentId)
                ->delete();

            // 清空student_mastery表
            DB::table('student_mastery')
                ->where('student_id', $studentId)
                ->delete();

            Log::info('Student MySQL Data Cleared', [
                'student_id' => $studentId
            ]);
        } catch (\Exception $e) {
            Log::error('Clear Student MySQL Data Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);
            throw $e; // 重新抛出异常，让上层处理
        }
    }

    /**
     * 获取学生列表（供智能出卷使用）
     */
    public function getStudentsList(): array
    {
        try {
            $response = Http::timeout($this->timeout)
                ->get($this->baseUrl . '/api/v1/students/list');

            if ($response->successful()) {
                return $response->json('data', []);
            }

            // 如果API失败，尝试从MySQL直接读取
            return $this->getStudentsFromMySQL();
        } catch (\Exception $e) {
            Log::error('Get Students List Error', [
                'error' => $e->getMessage()
            ]);

            // 返回模拟数据
            return [
                ['student_id' => 'stu_001', 'name' => '张三'],
                ['student_id' => 'stu_002', 'name' => '李四'],
                ['student_id' => 'stu_003', 'name' => '王五'],
            ];
        }
    }

    /**
     * 从MySQL获取学生列表
     */
    private function getStudentsFromMySQL(): array
    {
        try {
            return DB::table('students')
                ->select('student_id', 'name')
                ->limit(100)
                ->get()
                ->toArray();
        } catch (\Exception $e) {
            Log::error('Get Students From MySQL Error', [
                'error' => $e->getMessage()
            ]);
            return [];
        }
    }

    /**
     * 获取学生薄弱点列表
     * 策略：MySQL作为权威数据源，LearningAnalytics API仅作为辅助/缓存
     */
    public function getStudentWeaknesses(string $studentId, int $limit = 10): array
    {
        try {
            // 从本地MySQL数据库获取学生薄弱点
            Log::info('从本地MySQL数据库获取学生薄弱点', [
                'student_id' => $studentId,
                'limit' => $limit
            ]);

            $weaknesses = $this->getStudentWeaknessesFromMySQL($studentId, $limit);

            if (!empty($weaknesses)) {
                Log::info('从本地数据库获取到薄弱点数据', [
                    'student_id' => $studentId,
                    'count' => count($weaknesses)
                ]);
                return $weaknesses;
            }

            Log::warning('本地数据库中无该学生薄弱点数据', [
                'student_id' => $studentId
            ]);

            return [];
        } catch (\Exception $e) {
            Log::error('Get Student Weaknesses Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage()
            ]);

            // 发生异常时，返回空数组
            return [];
        }
    }

    /**
     * 从MySQL获取学生薄弱点
     */
    private function getStudentWeaknessesFromMySQL(string $studentId, int $limit = 10): array
    {
        try {
            // 优先从 student_knowledge_mastery 表读取（更完整的掌握度数据）
            $weaknesses = DB::table('student_knowledge_mastery as skm')
                ->join('knowledge_points as kp', 'kp.kp_code', '=', 'skm.kp_code')
                ->where('skm.student_id', $studentId)
                ->where('skm.mastery_level', '<', 0.9) // 掌握度低于70%视为薄弱点
                ->whereNotNull('kp.parent_kp_code') // 排除根节点（如 M00/S000_000）
                ->orderBy('skm.mastery_level', 'asc')
                ->limit($limit)
                ->select([
                    'skm.kp_code',
                    'skm.mastery_level',
                    'skm.total_attempts',
                    'skm.correct_attempts',
                    'skm.incorrect_attempts',
                    'skm.confidence_level',
                    'skm.mastery_trend'
                ])
                ->get()
                ->toArray();

            // 如果student_knowledge_mastery表没有数据，尝试从student_mastery表读取
            if (empty($weaknesses)) {
                Log::info('student_knowledge_mastery表无数据，尝试从student_mastery表读取', [
                    'student_id' => $studentId
                ]);

                $weaknesses = DB::table('student_mastery as sm')
                    ->leftJoin('knowledge_points as kp', 'sm.kp', '=', 'kp.kp_code')
                    ->where('sm.student_id', $studentId)
                    ->where('sm.mastery', '<', 0.7) // 掌握度低于70%视为薄弱点
                    ->whereNotNull('kp.parent_kp_code') // 排除根节点（如 M00/S000_000）
                    ->orderBy('sm.mastery', 'asc')
                    ->limit($limit)
                    ->select([
                        'sm.kp as kp_code',
                        'kp.name as kp_name',
                        'sm.mastery',
                        'sm.attempts',
                        'sm.correct'
                    ])
                    ->get()
                    ->toArray();

                // 转换为统一格式
                return array_map(function ($item) {
                    $mastery = (float) ($item->mastery ?? 0);
                    $attempts = (int) ($item->attempts ?? 0);
                    $correct = (int) ($item->correct ?? 0);

                    return [
                        'kp_code' => $item->kp_code,
                        'kp_name' => $item->kp_name ?? $item->kp_code,
                        'mastery' => $mastery,
                        'stability' => 0.5, // 默认稳定性
                        'weakness_level' => 1.0 - $mastery, // 薄弱程度
                        'practice_count' => $attempts,
                        'success_rate' => $attempts > 0 ? ($correct / $attempts) : 0,
                        'priority' => $mastery < 0.3 ? '高' : ($mastery < 0.5 ? '中' : '低'),
                        'suggested_questions' => max(5, (int)((0.7 - $mastery) * 20)) // 掌握度越低，建议题目越多
                    ];
                }, $weaknesses);
            }

            // 转换student_knowledge_mastery表的数据格式
            return array_map(function ($item) {
                $mastery = (float) ($item->mastery_level ?? 0);
                $totalAttempts = (int) ($item->total_attempts ?? 0);
                $correctAttempts = (int) ($item->correct_attempts ?? 0);
                $incorrectAttempts = (int) ($item->incorrect_attempts ?? 0);
                $confidence = (float) ($item->confidence_level ?? 0.5);
                $trend = $item->mastery_trend ?? 'stable';

                // 计算成功率
                $successRate = $totalAttempts > 0 ? ($correctAttempts / $totalAttempts) : 0;

                // 确定优先级
                $priority = '中';
                if ($mastery < 0.3) {
                    $priority = '高';
                } elseif ($mastery < 0.5) {
                    $priority = '中';
                } else {
                    $priority = '低';
                }

                return [
                    'kp_code' => $item->kp_code,
                    'kp_name' => $item->kp_code, // 如果没有中文名，使用代码作为名称
                    'mastery' => $mastery,
                    'stability' => $confidence,
                    'weakness_level' => 1.0 - $mastery, // 薄弱程度
                    'practice_count' => $totalAttempts,
                    'success_rate' => $successRate,
                    'priority' => $priority,
                    'suggested_questions' => max(5, (int)((0.7 - $mastery) * 20)), // 掌握度越低，建议题目越多
                    'trend' => $trend,
                    'correct_attempts' => $correctAttempts,
                    'incorrect_attempts' => $incorrectAttempts
                ];
            }, $weaknesses);
        } catch (\Exception $e) {
            Log::error('Get Student Weaknesses From MySQL Error', [
                'student_id' => $studentId,
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);
            return [];
        }
    }

    /**
     * 智能出卷：根据学生掌握度智能选择题目
     */
    public function generateIntelligentExam(array $params): array
    {
        $startTime = microtime(true);

        try {
            // 应用组卷类型策略
            $assembleType = (int) ($params['assemble_type'] ?? 4); // 默认为通用类型(4)
            $examTypeLegacy = $params['exam_type'] ?? 'general'; // 兼容旧版参数

            // 如果有 assemble_type 参数，优先使用新的参数系统
            if (isset($params['assemble_type'])) {
                try {
                    // 确保QuestionExpansionService和QuestionLocalService可用
                    $questionExpansionService = $this->questionExpansionService ?? app(QuestionExpansionService::class);
                    $questionLocalService = app(QuestionLocalService::class);

                    $strategy = new ExamTypeStrategy($questionExpansionService, $questionLocalService);
                    $params = $strategy->buildParams($params, $assembleType);
                } catch (Exception $e) {
                    Log::warning('LearningAnalyticsService: 组卷策略应用失败，使用默认策略', [
                        'assemble_type' => $assembleType,
                        'error' => $e->getMessage(),
                        'trace' => $e->getTraceAsString()
                    ]);
                }
            } elseif ($examTypeLegacy !== 'general') {
                // 兼容旧版 exam_type 参数
                try {
                    $questionExpansionService = $this->questionExpansionService ?? app(QuestionExpansionService::class);
                    $questionLocalService = app(QuestionLocalService::class);

                    $strategy = new ExamTypeStrategy($questionExpansionService, $questionLocalService);
                    $params = $strategy->buildParamsLegacy($params, $examTypeLegacy);
                } catch (Exception $e) {
                    Log::warning('LearningAnalyticsService: 组卷策略应用失败，使用默认策略', [
                        'exam_type' => $examTypeLegacy,
                        'error' => $e->getMessage(),
                        'trace' => $e->getTraceAsString()
                    ]);
                }
            }

            $studentId = $params['student_id'] ?? null;
            $grade = $params['grade'] ?? null; // 用户选择的年级
            $totalQuestions = $params['total_questions'] ?? (int) config('question_bank.default_total_questions');

            // 【修复】参数映射：支持 kp_codes 和 kp_code_list 两种参数名
            $kpCodes = $params['kp_codes'] ?? $params['kp_code_list'] ?? [];
            if (!is_array($kpCodes)) {
                $kpCodes = [];
            }

            $skills = $params['skills'] ?? [];
            $questionTypeRatio = $params['question_type_ratio'] ?? [
                '选择题' => 40,
                '填空题' => 40,
                '解答题' => 20,
            ];
            // 新增：题目分类筛选
            $questionCategory = $params['question_category'] ?? null;
            // 注意: difficulty_ratio 参数已废弃，使用 difficulty_category 控制难度分布
            $difficultyLevels = $params['difficulty_levels'] ?? [];
            // 如果用户没有选择任何难度，difficultyLevels 为空数组，表示随机难度

            // 1. 如果指定了学生，获取学生的薄弱点
            $weaknessFilter = [];
            if ($studentId) {
                $weaknesses = $this->getStudentWeaknesses($studentId, 20);

                $weaknessFilter = array_column($weaknesses, 'kp_code');

                // 【修复】教材出卷（assemble_type=3）不使用薄弱点，严格按章节获取知识点
                if ($assembleType == 3) {
                    // 教材组卷不使用薄弱点
                } else {
                    // 如果用户没有指定知识点，使用学生的薄弱点（非教材组卷）
                    if (empty($kpCodes)) {
                        $kpCodes = $weaknessFilter;
                    }
                }
            }

            // 2. 优先使用学生错题（如果存在）
            $mistakeQuestionIds = $params['mistake_question_ids'] ?? [];
            $priorityQuestions = [];
            $maxQuestions = 50; // 错题最大题目数限制
            $poolLimit = 0; // 题库池不设上限，0 表示不限制

            if (!empty($mistakeQuestionIds)) {
                // 如果错题超过最大值，截取到最大值
                $truncatedMistakeIds = $mistakeQuestionIds;
                if (count($mistakeQuestionIds) > $maxQuestions) {
                    $truncatedMistakeIds = array_slice($mistakeQuestionIds, 0, $maxQuestions);
                }

                // 获取学生错题的详细信息（错题获取不需要智能补充，不传入 grade/textbook_id）
                $priorityQuestions = $this->getQuestionsFromBank([], [], $studentId, $questionTypeRatio, $maxQuestions, $truncatedMistakeIds, [], null, null, null, null, 1);
            }

            // 3. 处理错题本逻辑
            $allQuestions = $priorityQuestions;
            $isMistakeBook = ($assembleType === 5); // 错题本类型
            $hasMistakePriority = !empty($priorityQuestions);
            $strictMistakeBook = $isMistakeBook && $hasMistakePriority;

            // 【修改】错题本类型严格按错题组卷，不补充题目
            if ($isMistakeBook) {
                $mistakeKpSource = (bool) ($params['mistake_kp_source'] ?? false);
                // 如果完全没有错题，回退到知识点/题库组卷
                if (!$hasMistakePriority && !$mistakeKpSource) {
                } elseif (!$hasMistakePriority && $mistakeKpSource) {
                }
            }

            if (!$strictMistakeBook && count($priorityQuestions) < $totalQuestions) {
                try {
                    // 【优化】获取textbook_catalog_node_ids参数（教材组卷时使用）
                    $textbookCatalogNodeIds = $params['textbook_catalog_node_ids'] ?? null;
                    // 【修复超纲问题】获取 textbook_id 和 difficulty_category，用于智能补充时限制范围
                    $textbookId = isset($params['textbook_id']) ? (int) $params['textbook_id'] : null;
                    $difficultyCategory = (int) ($params['difficulty_category'] ?? 1);

                    // 【修复超纲问题】传入 grade 和 textbook_id，用于智能补充时限制范围
                    // 【修复】传入实际需要数量，否则 totalNeeded=0 会导致智能补充不触发
                    $excludeQuestionIds = $params['exclude_question_ids'] ?? [];
                    $needCount = $totalQuestions - count($priorityQuestions);
                    $baseNeedCount = in_array($assembleType, [2, 3], true) ? 0 : $needCount;
                    $additionalQuestions = $this->getQuestionsFromBank(
                        $kpCodes,
                        $skills,
                        $studentId,
                        $questionTypeRatio,
                        $baseNeedCount,
                        [],
                        $excludeQuestionIds,
                        $questionCategory,
                        $textbookCatalogNodeIds,
                        $grade ? (int) $grade : null,  // 年级
                        $textbookId,                    // 教材ID（避免超纲）
                        $difficultyCategory             // 难度类别
                    );
                    $allQuestions = $this->dedupeQuestionsByBankId(array_merge($priorityQuestions, $additionalQuestions));

                    // assemble_type=2/3：本源池不足，先用父树补题 KP 拉题（兄弟节点优先）
                    if (
                        in_array($assembleType, [2, 3], true)
                        && count($allQuestions) < $totalQuestions
                        && ! empty($params['kp_supplement_subtree_codes'] ?? [])
                        && $grade !== null
                    ) {
                        $before = count($allQuestions);
                        $excludeForSupp = array_values(array_unique(array_filter(array_merge(
                            $excludeQuestionIds,
                            array_column($allQuestions, 'id')
                        ))));
                        Log::info('assemble.supplement', [
                            'stage' => 'kp_subtree',
                            'status' => 'start',
                            'before_count' => $before,
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                        ]);
                        $supp = $this->fetchQuestionsForKpAssembleSupplement(
                            $params['kp_supplement_subtree_codes'],
                            $excludeForSupp,
                            (int) $grade,
                            $skills,
                            $questionCategory,
                            $assembleType === 3 ? null : $textbookCatalogNodeIds
                        );
                        $supplementStats = $this->buildSupplementQuestionStats($supp);
                        $allQuestions = $this->dedupeQuestionsByBankId(array_merge($allQuestions, $supp));
                        Log::info('assemble.supplement', [
                            'stage' => 'kp_subtree',
                            'status' => empty($supp) ? 'empty' : 'done',
                            'before_count' => $before,
                            'supplement_count' => count($supp),
                            'after_count' => count($allQuestions),
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                            'supplement_kp_distribution_topn' => $supplementStats['supplement_kp_distribution_topn'],
                            'supplement_kp_sample' => $supplementStats['supplement_kp_sample'],
                        ]);
                    }

                    // assemble_type=3：兄弟补题后仍不足，再走教材前章节补题兜底
                    if (
                        $assembleType === 3
                        && count($allQuestions) < $totalQuestions
                        && $grade !== null
                    ) {
                        $before = count($allQuestions);
                        $deficit = $totalQuestions - count($allQuestions);
                        $excludeForChapterSupplement = array_values(array_unique(array_filter(array_merge(
                            $excludeQuestionIds,
                            array_column($allQuestions, 'id')
                        ))));
                        Log::info('assemble.supplement', [
                            'stage' => 'chapter_fallback',
                            'status' => 'start',
                            'before_count' => $before,
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                        ]);
                        $chapterSupplement = $this->getSupplementaryQuestionsForGrade(
                            (int) $grade,
                            array_column($allQuestions, 'kp_code'),
                            $deficit,
                            $difficultyCategory,
                            $textbookId,
                            $excludeForChapterSupplement,
                            $textbookCatalogNodeIds ?? null,
                            $studentId
                        );

                        $chapterSupplementStats = $this->buildSupplementQuestionStats($chapterSupplement);
                        $allQuestions = $this->dedupeQuestionsByBankId(array_merge($allQuestions, $chapterSupplement));
                        Log::info('assemble.supplement', [
                            'stage' => 'chapter_fallback',
                            'status' => empty($chapterSupplement) ? 'empty' : 'done',
                            'before_count' => $before,
                            'supplement_count' => count($chapterSupplement),
                            'after_count' => count($allQuestions),
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                            'supplement_kp_distribution_topn' => $chapterSupplementStats['supplement_kp_distribution_topn'],
                            'supplement_kp_sample' => $chapterSupplementStats['supplement_kp_sample'],
                        ]);
                    }

                    // 通用兜底：无论何种组卷类型，前序补题后仍不足时，最终都走常规补题策略
                    if (count($allQuestions) < $totalQuestions && $grade !== null) {
                        $before = count($allQuestions);
                        $deficit = $totalQuestions - count($allQuestions);
                        $excludeForCommonFallback = array_values(array_unique(array_filter(array_merge(
                            $excludeQuestionIds,
                            array_column($allQuestions, 'id')
                        ))));
                        Log::info('assemble.supplement', [
                            'stage' => 'common_fallback',
                            'status' => 'start',
                            'before_count' => $before,
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                        ]);
                        $commonFallback = $this->getSupplementaryQuestionsForGrade(
                            (int) $grade,
                            array_column($allQuestions, 'kp_code'),
                            $deficit,
                            $difficultyCategory,
                            $textbookId,
                            $excludeForCommonFallback,
                            $assembleType === 3 ? null : ($textbookCatalogNodeIds ?? null),
                            $studentId
                        );

                        $commonFallbackStats = $this->buildSupplementQuestionStats($commonFallback);
                        $allQuestions = $this->dedupeQuestionsByBankId(array_merge($allQuestions, $commonFallback));
                        Log::info('assemble.supplement', [
                            'stage' => 'common_fallback',
                            'status' => empty($commonFallback) ? 'empty' : 'done',
                            'before_count' => $before,
                            'supplement_count' => count($commonFallback),
                            'after_count' => count($allQuestions),
                            'target_count' => $totalQuestions,
                            'assemble_type' => $assembleType,
                            'supplement_kp_distribution_topn' => $commonFallbackStats['supplement_kp_distribution_topn'],
                            'supplement_kp_sample' => $commonFallbackStats['supplement_kp_sample'],
                        ]);
                    }

                } catch (\Exception $e) {
                    Log::error('getQuestionsFromBank 调用失败', [
                        'error' => $e->getMessage(),
                        'trace' => $e->getTraceAsString()
                    ]);

                    throw $e;
                }
            }

            if (empty($allQuestions)) {
                // 如果指定了知识点但题库为空，给出明确提示
                if (!empty($kpCodes)) {
                    $message = '所选知识点 [' . implode(', ', $kpCodes) . '] 在题库中暂无可用题目。您可以：1) 选择其他知识点，2) 点击"生成练习题"按钮先补充题库，或 3) 取消知识点选择让系统随机选题。';
                } else {
                    // 没有选择知识点时，从所有题目中选择
                    // 如果仍然没有题目，说明题库为空，提示补充题库
                    $message = '题库为空，请先添加题目到题库。您可以点击"生成练习题"按钮或手动上传题目。';
                }

                return [
                    'success' => false,
                    'message' => $message,
                    'questions' => []
                ];
            }

            // 3. 根据掌握度对题目进行筛选和排序（含追练：题量与 total_questions / default_total_questions 一致，不再按 50 拉满）
            $targetQuestionCount = min(count($allQuestions), $totalQuestions);

            if (! empty($params['kp_target_counts']) || ! empty($params['max_difficulty_by_kp']) || ! empty($params['type_targets_by_kp'])) {
                $allQuestions = app(QuestionDifficultyResolver::class)->applyCalibratedDifficulty($allQuestions);
            }

            $startTime = microtime(true);
            $selectedQuestions = $this->selectQuestionsByMastery(
                $allQuestions,
                $studentId,
                $targetQuestionCount,
                $questionTypeRatio,
                $difficultyLevels,
                $weaknessFilter,
                $assembleType,  // 新增assembleType参数
                $params['kp_code_list_original'] ?? $params['kp_codes'] ?? [],
                $params['kp_target_counts'] ?? [],
                $params['max_difficulty_by_kp'] ?? [],
                $params['type_targets_by_kp'] ?? []
            );
            if (empty($selectedQuestions)) {
                return [
                    'success' => false,
                    'message' => '题目筛选失败',
                    'questions' => []
                ];
            }

            // 【恢复】简化难度分布检查
            $difficultyCategory = $params['difficulty_category'] ?? 1;
            $enableDistribution = $params['enable_difficulty_distribution'] ?? false;
            // assemble_type=2（知识点组卷）优先保证请求知识点覆盖，避免二次难度重排把次要 KP 挤没
            $isExcludedType = ($assembleType === 2);

            if ($enableDistribution && !$isExcludedType) {
                try {
                    $selectedQuestions = $this->applyTypeAwareDifficultyDistribution(
                        $allQuestions,
                        $selectedQuestions,
                        $totalQuestions,
                        (int) $difficultyCategory,
                        $questionTypeRatio
                    );

                } catch (\Exception $e) {
                    // 保持组卷主流程稳定，难度分布失败时继续返回原结果
                }
            }

            $requestedKpSelectionStats = $this->buildRequestedKpSelectionStats(
                $selectedQuestions,
                $params['kp_code_list_original'] ?? $params['kp_codes'] ?? []
            );

            Log::info('LearningAnalyticsService: 最终选题分布', [
                'assemble_type' => $assembleType,
                'question_count' => count($selectedQuestions),
                'type_distribution' => $this->countByType($selectedQuestions),
                'kp_distribution' => array_count_values(array_column($selectedQuestions, 'kp_code')),
                'requested_kp_selection' => $assembleType === 2 ? $requestedKpSelectionStats : null,
            ]);

            return [
                'success' => true,
                'message' => '智能出卷成功',
                'questions' => $selectedQuestions,
                // 【新增】传递章节摸底和智能组卷的关键字段
                'diagnostic_chapter_id' => $params['diagnostic_chapter_id'] ?? null,
                'explanation_kp_codes' => $params['explanation_kp_codes'] ?? null,
                'assemble_type' => $params['assembleType'] ?? null, // 策略可能修改assembleType（如章节智能→章节摸底）
                'stats' => [
                    'total_selected' => count($selectedQuestions),
                    'source_questions' => count($allQuestions),
                    'weakness_targeted' => $studentId && !empty($weaknessFilter) ? count(array_filter($selectedQuestions, function($q) use ($weaknessFilter) {
                        return in_array($q['kp_code'] ?? '', $weaknessFilter);
                    })) : 0,
                    'difficulty_distribution_applied' => $enableDistribution && !$isExcludedType,
                    'difficulty_category' => $difficultyCategory,
                    'final_distribution' => $this->buildDifficultyDistributionStats($selectedQuestions, (int) $difficultyCategory),
                    'final_distribution_shortage' => $this->buildDifficultyDistributionShortage(
                        $selectedQuestions,
                        (int) $difficultyCategory,
                        (int) $totalQuestions
                    ),
                    'requested_kp_selection' => $assembleType === 2 ? $requestedKpSelectionStats : null,
                    // 【新增】章节知识点数量统计（教材组卷时）
                    'chapter_knowledge_point_stats' => $params['chapter_knowledge_point_stats'] ?? null,
                    'textbook_catalog_node_ids' => $params['textbook_catalog_node_ids'] ?? null
                ]
            ];
        } catch (\Exception $e) {
            Log::error('Generate Intelligent Exam Error', [
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);

            return [
                'success' => false,
                'message' => '智能出卷异常: ' . $e->getMessage(),
                'questions' => []
            ];
        }
    }

    /**
     * @param  array<int, array<string, mixed>>  $questions
     * @return array<int, array<string, mixed>>
     */
    private function dedupeQuestionsByBankId(array $questions): array
    {
        $seen = [];
        $out = [];
        foreach ($questions as $q) {
            $id = $q['id'] ?? null;
            if ($id === null || $id === '') {
                continue;
            }
            $k = (string) $id;
            if (isset($seen[$k])) {
                continue;
            }
            $seen[$k] = true;
            $out[] = $q;
        }

        return $out;
    }

    /**
     * 知识点组卷补题：仅按补充 KP 列表查询，筛选条件与 getQuestionsFromBank 主查询一致（不调用教材/已学那条智能补题）。
     *
     * @param  array<string>  $kpCodes
     * @param  array<int|string>  $excludeQuestionIds
     * @return array<int, array<string, mixed>>
     */
    private function fetchQuestionsForKpAssembleSupplement(
        array $kpCodes,
        array $excludeQuestionIds,
        int $grade,
        array $skills = [],
        ?int $questionCategory = null,
        ?array $textbookCatalogNodeIds = null
    ): array {
        $kpCodes = array_values(array_unique(array_filter($kpCodes)));
        if ($kpCodes === []) {
            return [];
        }

        $query = \App\Models\Question::query()
            ->where('audit_status', 0)
            ->whereIn('kp_code', $kpCodes);

        $stageGrade = $this->normalizeQuestionStageGrade($grade);
        if ($stageGrade !== null) {
            $query->where('grade', $stageGrade);
        }

        if (! empty($skills)) {
            $query->where(function ($q) use ($skills) {
                foreach ($skills as $skill) {
                    $q->orWhere('tags', 'like', '%'.$skill.'%');
                }
            });
        }

        if (! empty($excludeQuestionIds)) {
            $query->whereNotIn('id', $excludeQuestionIds);
        }

        if ($questionCategory !== null) {
            $query->where('question_category', $questionCategory);
        }

        $query->whereNotNull('solution')
            ->where('solution', '!=', '')
            ->where('solution', '!=', '[]');

        if (! empty($textbookCatalogNodeIds)) {
            $query->whereIn('textbook_catalog_nodes_id', $textbookCatalogNodeIds);
        }

        return $query->inRandomOrder()->get()->map(function ($q) {
            return [
                'id' => $q->id,
                'question_code' => $q->question_code,
                'kp_code' => $q->kp_code,
                'question_type' => $q->question_type,
                'difficulty' => $q->difficulty !== null ? (float) $q->difficulty : 0.5,
                'stem' => $q->stem,
                'solution' => $q->solution,
                'metadata' => [
                    'has_solution' => true,
                    'is_choice' => $q->question_type === 'choice',
                    'is_fill' => $q->question_type === 'fill',
                    'is_answer' => $q->question_type === 'answer',
                    'difficulty_label' => $this->getDifficultyLabel($q->difficulty ?? 0.5),
                    'question_type_label' => $this->getQuestionTypeLabel($q->question_type),
                ],
            ];
        })->toArray();
    }

    /**
     * 从题库获取题目
     *
     * @param array $kpCodes 知识点代码列表
     * @param array $skills 技能标签列表
     * @param string|null $studentId 学生ID
     * @param array $questionTypeRatio 题型比例
     * @param int $totalNeeded 需要的题目数量
     * @param array $priorityQuestionIds 优先获取的题目ID（错题）
     * @param array $excludeQuestionIds 排除的题目ID
     * @param int|null $questionCategory 题目分类
     * @param array|null $textbookCatalogNodeIds 教材章节节点ID
     * @param int|null $grade 年级（用于智能补充时限制范围）
     * @param int|null $textbookId 教材ID（用于智能补充时限制范围，避免超纲）
     * @param int $difficultyCategory 难度类别（用于智能补充）
     * @return array 题目列表
     */
    private function getQuestionsFromBank(array $kpCodes, array $skills, ?string $studentId, array $questionTypeRatio = [], int $totalNeeded = 100, array $priorityQuestionIds = [], array $excludeQuestionIds = [], ?int $questionCategory = null, ?array $textbookCatalogNodeIds = null, ?int $grade = null, ?int $textbookId = null, int $difficultyCategory = 1): array
    {
        $startTime = microtime(true);

        try {
            // 错题回顾：优先获取指定的学生错题
            if (!empty($priorityQuestionIds)) {

                $priorityQuestions = $this->getLocalQuestionsByIds($priorityQuestionIds);

                if (!empty($priorityQuestions)) {
                    return $priorityQuestions;
                } else {
                    // 错题本类型获取不到错题时，返回空数组，不回退到题库随机选题
                    return [];
                }
            }

            $query = \App\Models\Question::query();

            // 【新增】只获取审核通过的题目（audit_status = 0 表示合格）
            $query->where('audit_status', 0);

            // 按知识点筛选
            if (!empty($kpCodes)) {
                $query->whereIn('kp_code', $kpCodes);
            }

            // 按学段筛选（题库 grade: 2=初中, 3=高中）
            if ($grade !== null) {
                $stageGrade = $this->normalizeQuestionStageGrade((int) $grade);
                if ($stageGrade !== null) {
                    $query->where('grade', $stageGrade);
                }
            }

            // 按技能筛选（这里使用 tags 字段模拟技能筛选）
            if (!empty($skills)) {
                $query->where(function ($q) use ($skills) {
                    foreach ($skills as $skill) {
                        $q->orWhere('tags', 'like', "%{$skill}%");
                    }
                });
            }

            // 排除学生已做过的题目
            if (!empty($excludeQuestionIds)) {
                $query->whereNotIn('id', $excludeQuestionIds);
            }

            // 按题目分类筛选（如果指定了 question_category）
            if ($questionCategory !== null) {
                $query->where('question_category', $questionCategory);
            }

            // 筛选有解题思路的题目
            $query->whereNotNull('solution')
                  ->where('solution', '!=', '')
                  ->where('solution', '!=', '[]');

            // 注意: 难度筛选由 QuestionLocalService 的难度分布系统处理
            // 不在这里进行难度筛选，让 QuestionLocalService 做精确的难度分布

            // 【重要】移除数量限制，获取所有符合条件的题目
            // 不使用limit()限制查询结果，让后续处理逻辑决定最终数量
            $query->inRandomOrder();

            $questions = $query->get();

            // 转换为标准格式
            $formattedQuestions = $questions->map(function ($q) {
                return [
                    'id' => $q->id,
                    'question_code' => $q->question_code,
                    'kp_code' => $q->kp_code,
                    'question_type' => $q->question_type,
                    'difficulty' => $q->difficulty !== null ? (float) $q->difficulty : 0.5,
                    'stem' => $q->stem,
                    'solution' => $q->solution,
                    'metadata' => [
                        'has_solution' => true,
                        'is_choice' => $q->question_type === 'choice',
                        'is_fill' => $q->question_type === 'fill',
                        'is_answer' => $q->question_type === 'answer',
                        'difficulty_label' => $this->getDifficultyLabel($q->difficulty ?? 0.5),
                        'question_type_label' => $this->getQuestionTypeLabel($q->question_type)
                    ]
                ];
            })->toArray();

            // 【重要】返回所有符合条件的题目，不限制数量
            // 让上层调用者根据需要选择题目数量
            $selectedQuestions = $formattedQuestions;

            // 【修复】重新启用智能补充功能，增加 textbook_id 限制避免超纲
            if ($totalNeeded > 0 && count($selectedQuestions) < $totalNeeded && $grade !== null) {
                $deficit = $totalNeeded - count($selectedQuestions);
                Log::info('assemble.supplement', [
                    'stage' => 'start',
                    'deficit' => $deficit,
                    'current_count' => count($selectedQuestions),
                    'target_count' => $totalNeeded,
                    'grade' => $grade,
                    'textbook_id' => $textbookId,
                    'has_student_id' => ! empty($studentId),
                    'has_chapter_scope' => ! empty($textbookCatalogNodeIds),
                ]);

                // 【修复超纲问题】补充策略：只从「学过的」内容补充
                // - 有 textbook_id：从同教材的前章节补充
                // - 无 textbook_id：从学生做过的题目对应的知识点补充，避免未学内容
                $supplementaryQuestions = $this->getSupplementaryQuestionsForGrade(
                    $grade,
                    array_column($selectedQuestions, 'kp_code'),
                    $deficit,
                    $difficultyCategory,
                    $textbookId,
                    $excludeQuestionIds,
                    $textbookCatalogNodeIds ?? null,
                    $studentId
                );

                if (!empty($supplementaryQuestions)) {
                    $selectedQuestions = array_merge($selectedQuestions, $supplementaryQuestions);
                    Log::info('assemble.supplement', [
                        'stage' => 'done',
                        'supplement_count' => count($supplementaryQuestions),
                        'after_count' => count($selectedQuestions),
                        'target_count' => $totalNeeded,
                        'grade' => $grade,
                        'textbook_id' => $textbookId,
                    ]);
                } else {
                    Log::info('assemble.supplement', [
                        'stage' => 'empty',
                        'supplement_count' => 0,
                        'after_count' => count($selectedQuestions),
                        'target_count' => $totalNeeded,
                        'grade' => $grade,
                        'textbook_id' => $textbookId,
                    ]);
                }
            }

            return $selectedQuestions;

        } catch (\Exception $e) {
            Log::error('getQuestionsFromBank 查询失败', [
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);

            throw $e;
        }
    }

    /**
     * 获取指定ID的题目详情
     */
    private function getLocalQuestionsByIds(array $questionIds): array
    {
        try {
            // 通过QuestionBankService获取题目详情
            $questionBankService = $this->questionBankService ?? app(\App\Services\QuestionBankService::class);

            // 批量获取题目详情
            $response = $questionBankService->getQuestionsByIds($questionIds);

            if (empty($response['data'])) {
                Log::warning('getLocalQuestionsByIds: 未获取到任何题目', [
                    'requested_ids' => $questionIds
                ]);
                return [];
            }

            $questions = $response['data'];

            // 转换为标准格式
            $result = array_map(function ($q) {
                $difficulty = $q['difficulty'] ?? 0.5;
                return [
                    'id' => $q['id'],
                    'question_code' => $q['question_code'] ?? '',
                    'kp_code' => $q['kp_code'] ?? '',
                    'question_type' => $q['question_type'] ?? 'choice',
                    'difficulty' => (float) $difficulty,
                    'stem' => $q['stem'] ?? '',
                    'solution' => $q['solution'] ?? '',
                    'answer' => $q['answer'] ?? '',
                    'metadata' => [
                        'has_solution' => !empty($q['solution']),
                        'is_choice' => ($q['question_type'] ?? 'choice') === 'choice',
                        'is_fill' => ($q['question_type'] ?? 'choice') === 'fill',
                        'is_answer' => ($q['question_type'] ?? 'choice') === 'answer',
                        'difficulty_label' => $this->getDifficultyLabel((float) $difficulty),
                        'question_type_label' => $this->getQuestionTypeLabel($q['question_type'] ?? 'choice')
                    ]
                ];
            }, $questions);

            Log::info('getLocalQuestionsByIds 获取成功', [
                'requested_count' => count($questionIds),
                'found_count' => count($result),
                'missing_ids' => array_diff($questionIds, array_column($result, 'id')),
                'question_ids' => array_slice($questionIds, 0, 20),
                'found_question_ids' => array_slice(array_column($result, 'id'), 0, 20)
            ]);

            return $result;

        } catch (\Exception $e) {
            Log::error('getLocalQuestionsByIds 获取失败', [
                'question_ids' => $questionIds,
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);

            return [];
        }
    }

    /**
     * 获取卷子的所有题目ID（不区分对错）
     */
    private function getPaperAllQuestions(array $paperIds): array
    {
        try {
            // 查询 paper_questions 表获取所有题目ID
            $questionIds = DB::table('paper_questions')
                ->whereIn('paper_id', $paperIds)
                ->pluck('question_bank_id')
                ->unique()
                ->filter()
                ->values()
                ->toArray();

            Log::debug('LearningAnalyticsService: 获取卷子所有题目', [
                'paper_ids' => $paperIds,
                'question_count' => count($questionIds)
            ]);

            return $questionIds;
        } catch (\Exception $e) {
            Log::error('LearningAnalyticsService: 获取卷子题目失败', [
                'paper_ids' => $paperIds,
                'error' => $e->getMessage()
            ]);
            return [];
        }
    }

    /**
     * 获取难度标签
     */
    private function getDifficultyLabel(?float $difficulty): string
    {
        if ($difficulty === null) {
            return '未知';
        }
        return match (true) {
            $difficulty < 0.4 => '基础',
            $difficulty < 0.7 => '中等',
            default => '拔高'
        };
    }

    /**
     * 获取题型标签
     */
    private function getQuestionTypeLabel(string $questionType): string
    {
        return match ($questionType) {
            'choice' => '选择题',
            'fill' => '填空题',
            'answer' => '解答题',
            default => '未知题型'
        };
    }

    /**
     * 根据题型配比选择题目
     * 注意: 难度配比调整由 QuestionLocalService 处理
     */
    private function selectQuestionsByRatio(
        array $questions,
        int $totalNeeded,
        array $questionTypeRatio = []
    ): array {
        if (empty($questions)) {
            return [];
        }

        // 如果没有配比要求，直接返回
        if (empty($questionTypeRatio)) {
            return array_slice($questions, 0, $totalNeeded);
        }

        $selected = [];
        $usedIndices = [];

        // 按题型配比选择
        if (!empty($questionTypeRatio)) {
            foreach ($questionTypeRatio as $type => $ratio) {
                $count = (int) round(($ratio / 100) * $totalNeeded);
                if ($count <= 0) continue;

                $typeQuestions = [];
                foreach ($questions as $idx => $q) {
                    if (in_array($idx, $usedIndices)) continue;

                    $qType = $q['question_type'] ?? '';
                    $label = $this->getQuestionTypeLabel($qType);

                    if ($label === $type) {
                        $typeQuestions[] = ['idx' => $idx, 'question' => $q];
                    }
                }

                // 随机选择
                shuffle($typeQuestions);
                $selectedCount = min($count, count($typeQuestions));

                for ($i = 0; $i < $selectedCount; $i++) {
                    $selected[] = $typeQuestions[$i]['question'];
                    $usedIndices[] = $typeQuestions[$i]['idx'];
                }
            }
        }

        // 如果还有空缺，补充剩余题目
        // 注意: 难度配比调整由 QuestionLocalService 处理
        if (count($selected) < $totalNeeded) {
            foreach ($questions as $idx => $q) {
                if (count($selected) >= $totalNeeded) break;
                if (!in_array($idx, $usedIndices)) {
                    $selected[] = $q;
                    $usedIndices[] = $idx;
                }
            }
        }

        return array_slice($selected, 0, $totalNeeded);
    }

    /**
     * 根据学生掌握度筛选题目
     */
    private function selectQuestionsByMastery(
        array $questions,
        ?string $studentId,
        int $totalQuestions,
        array $questionTypeRatio,
        array $difficultyLevels,
        array $weaknessFilter,
        int $assembleType,  // 新增assembleType参数
        array $requestedKpCodes = [],
        array $kpTargetCounts = [],
        array $maxDifficultyByKp = [],
        array $typeTargetsByKp = []
    ): array {
        // 【修复】题目数量处理逻辑：无论题目数量多少，都要进行权重分配和筛选
        // 如果题目数量超过目标，则截取到目标数量
        // 如果题目数量不足，则使用所有题目，并记录警告
        if (count($questions) > $totalQuestions) {
            Log::debug('selectQuestionsByMastery: 题目数量超过目标，进行截取', [
                'question_count' => count($questions),
                'total_questions' => $totalQuestions
            ]);
        } else {
            Log::warning('题目数量不足，将使用所有可用题目', [
                'available_count' => count($questions),
                'requested_count' => $totalQuestions,
                'note' => '可能需要补充题库或放宽筛选条件'
            ]);
        }

        // 【移除】删除多余的难度筛选逻辑
        // 题目本身就有难度系数，QuestionLocalService的难度分布系统会处理题目分布
        // 不需要额外的难度筛选，让题目保持原始的难度分布

        $requestedKpCodes = array_values(array_unique(array_filter($requestedKpCodes)));
        $requestedKpSet = array_fill_keys($requestedKpCodes, true);
        $shouldRestrictToRequestedKps = ($assembleType === 2 && ! empty($requestedKpSet));

        if ($assembleType === 2 && ! empty($kpTargetCounts)) {
            return $this->selectQuestionsByKpTargets(
                $questions,
                $totalQuestions,
                $requestedKpCodes,
                $kpTargetCounts,
                $maxDifficultyByKp,
                $typeTargetsByKp
            );
        }

        if ($shouldRestrictToRequestedKps) {
            $requestedQuestions = array_values(array_filter($questions, function ($question) use ($requestedKpSet) {
                $kpCode = $question['kp_code'] ?? '';
                return isset($requestedKpSet[$kpCode]);
            }));
            $fallbackQuestions = array_values(array_filter($questions, function ($question) use ($requestedKpSet) {
                $kpCode = $question['kp_code'] ?? '';
                return ! isset($requestedKpSet[$kpCode]);
            }));

            Log::info('selectQuestionsByMastery: assemble_type=2 请求知识点约束', [
                'requested_kp_codes' => $requestedKpCodes,
                'requested_question_count' => count($requestedQuestions),
                'fallback_question_count' => count($fallbackQuestions),
                'target_question_count' => $totalQuestions,
            ]);

            // 原始请求知识点足够时，最终选题不应被补题池中的兄弟/父树知识点带偏。
            if (count($requestedQuestions) >= $totalQuestions) {
                $questions = $requestedQuestions;
            } else {
                $questions = array_merge($requestedQuestions, $fallbackQuestions);
            }
        }

        // 1. 按知识点分组
        $groupStartTime = microtime(true);
        $questionsByKp = [];
        foreach ($questions as $question) {
            $kpCode = $question['kp_code'] ?? '';
            if (!isset($questionsByKp[$kpCode])) {
                $questionsByKp[$kpCode] = [];
            }
            $questionsByKp[$kpCode][] = $question;
        }
        $groupTime = (microtime(true) - $groupStartTime) * 1000;

        // 2. 为每个知识点计算权重（用于题型内的题目排序）
        $kpWeights = [];
        $kpCodes = array_keys($questionsByKp);
        $startTime = microtime(true);
        $allMastery = [];

        if ($studentId) {
            // 批量获取所有知识点的掌握度（一次查询）
            $masteryStart = microtime(true);
            try {
                $masteryRecords = DB::table('student_mastery')
                    ->where('student_id', $studentId)
                    ->whereIn('kp', $kpCodes)
                    ->pluck('mastery', 'kp')
                    ->all();

                Log::debug('批量获取掌握度', [
                    'student_id' => $studentId,
                    'kp_count' => count($kpCodes),
                    'found_count' => count($masteryRecords),
                    'time_ms' => round((microtime(true) - $masteryStart) * 1000, 2)
                ]);

                $allMastery = $masteryRecords;
            } catch (\Exception $e) {
                Log::warning('批量获取掌握度失败，将使用默认值', [
                    'student_id' => $studentId,
                    'error' => $e->getMessage()
                ]);
            }
        }

        foreach ($kpCodes as $kpCode) {
            if ($studentId) {
                $mastery = $allMastery[$kpCode] ?? 0.5; // 默认0.5（中等掌握度）

                // 薄弱点权重更高
                if (in_array($kpCode, $weaknessFilter)) {
                    $kpWeights[$kpCode] = 2.0; // 薄弱点权重翻倍
                } else {
                    // 掌握度越低，权重越高
                    $kpWeights[$kpCode] = 1.0 + (1.0 - $mastery) * 1.5;
                }

                Log::debug('计算知识点权重', [
                    'kp_code' => $kpCode,
                    'mastery' => $mastery,
                    'weight' => $kpWeights[$kpCode]
                ]);
            } else {
                $kpWeights[$kpCode] = 1.0; // 未指定学生时平均分配
            }
        }

        // 3. 按题型分配题目数量（权重用于题型内排序）
        $selectedQuestions = [];

        // 将所有题目合并
        $weightedQuestions = [];
        foreach ($questionsByKp as $kpCode => $kpQuestions) {
            foreach ($kpQuestions as $q) {
                $q['kp_code'] = $kpCode;
                $weightedQuestions[] = $q;
            }
        }

        // ========== 知识点优先选择机制 ==========
        // 摸底测试的核心目标是最大化知识点覆盖
        // 题型只是约束条件（每种至少1题）

        // 首先按题型分组
        $questionsByType = [
            'choice' => [],
            'fill' => [],
            'answer' => [],
        ];

        foreach ($weightedQuestions as $q) {
            $qid = $q['id'] ?? $q['question_id'] ?? null;
            if ($qid && isset($questionTypeCache[$qid])) {
                $type = $questionTypeCache[$qid];
            } else {
                $type = $this->determineQuestionType($q);
                if ($qid) {
                    $questionTypeCache[$qid] = $type;
                }
            }

            if (!isset($questionsByType[$type])) {
                $type = 'answer';  // 默认归类为answer
            }
            $questionsByType[$type][] = $q;
        }

        // ========== 步骤1：按题型分配题目 ==========
        $selectedQuestions = [];

        // 【区分】根据 assembleType 决定是否使用知识点覆盖优先机制
        // - 0：摸底测试，优先扩大知识点覆盖
        // - 2：知识点组卷，也应尽量覆盖请求中的多个知识点，避免被单一 KP 吞掉
        $useKnowledgePointPriority = in_array($assembleType, [0, 2], true);
        $kpSelected = []; // 已选知识点记录

        // 【新增】非摸底类型：按比例计算每种题型的目标数量
        $typeTargets = ['choice' => 0, 'fill' => 0, 'answer' => 0];
        if (!$useKnowledgePointPriority) {
            $ratioMap = ['choice' => '选择题', 'fill' => '填空题', 'answer' => '解答题'];
            $totalRatio = array_sum($questionTypeRatio) ?: 100;
            $allocated = 0;
            $fractions = [];
            foreach ($ratioMap as $type => $ratioKey) {
                $ratio = $questionTypeRatio[$ratioKey] ?? 0;
                $exact = $totalQuestions * $ratio / $totalRatio;
                $typeTargets[$type] = (int) floor($exact);
                $fractions[$type] = $exact - floor($exact);
                $allocated += $typeTargets[$type];
            }
            // 余数分配给小数部分最大的题型
            $remainder = $totalQuestions - $allocated;
            arsort($fractions);
            foreach ($fractions as $type => $frac) {
                if ($remainder <= 0) break;
                $typeTargets[$type]++;
                $remainder--;
            }

            Log::debug('selectQuestionsByMastery: 题型目标分配', [
                'total_questions' => $totalQuestions,
                'targets' => $typeTargets,
            ]);
        }

        // 确保每种题型至少选1题
        foreach (['choice', 'fill', 'answer'] as $type) {
            if (empty($questionsByType[$type])) {
                Log::warning('题型分配：题型无题目', ['type' => $type]);
                continue;
            }

            // 按权重排序该题型的题目
            usort($questionsByType[$type], function ($a, $b) use ($kpWeights) {
                $kpA = $a['kp_code'] ?? '';
                $kpB = $b['kp_code'] ?? '';
                $weightA = $kpWeights[$kpA] ?? 1.0;
                $weightB = $kpWeights[$kpB] ?? 1.0;
                return $weightB <=> $weightA;
            });

            // 【修复】摸底测试题型基础分配：记录每个题型的知识点分布
            $typeKpDistribution = [];
            foreach ($questionsByType[$type] as $q) {
                $kpCode = $q['kp_code'] ?? '';
                if (!isset($typeKpDistribution[$kpCode])) {
                    $typeKpDistribution[$kpCode] = 0;
                }
                $typeKpDistribution[$kpCode]++;
            }

            Log::debug('摸底测试题型基础分配', [
                'type' => $type,
                'total_in_type' => count($questionsByType[$type]),
                'kp_count' => count($typeKpDistribution)
            ]);

            // 根据策略选择题目
            if ($useKnowledgePointPriority) {
                // 知识点优先：assemble_type=2 先从原始请求知识点里选；摸底则扩大覆盖
                $selectedInThisType = 0;
                $candidate = null;

                foreach ($questionsByType[$type] as $q) {
                    $kpCode = $q['kp_code'] ?? '';
                    if ($shouldRestrictToRequestedKps && ! isset($requestedKpSet[$kpCode])) {
                        continue;
                    }
                    if (!isset($kpSelected[$kpCode])) {
                        $candidate = $q;
                        break; // 只选1题
                    }
                }

                if ($candidate === null && $shouldRestrictToRequestedKps) {
                    foreach ($questionsByType[$type] as $q) {
                        $kpCode = $q['kp_code'] ?? '';
                        if (isset($requestedKpSet[$kpCode])) {
                            $candidate = $q;
                            break;
                        }
                    }
                }

                if ($candidate !== null) {
                    $kpCode = $candidate['kp_code'] ?? '';
                    $selectedQuestions[] = $candidate;
                    $kpSelected[$kpCode] = true;
                    $selectedInThisType++;
                    Log::debug('题型基础分配（知识点优先）', [
                        'type' => $type,
                        'kp' => $kpCode,
                        'question_id' => $candidate['id'] ?? 'unknown',
                        'selected_in_type' => $selectedInThisType
                    ]);
                }

                Log::debug('知识点优先题型基础分配完成', [
                    'type' => $type,
                    'selected_count' => $selectedInThisType
                ]);
            } else {
                // 非摸底：按目标数量从该题型池中选题
                $target = $typeTargets[$type] ?? 0;
                $selectedIds = array_column($selectedQuestions, 'id');
                $taken = 0;
                foreach ($questionsByType[$type] as $q) {
                    if ($taken >= $target) break;
                    $qid = $q['id'] ?? null;
                    if ($qid && !in_array($qid, $selectedIds)) {
                        $selectedQuestions[] = $q;
                        $selectedIds[] = $qid;
                        $taken++;
                    }
                }
                $typeTargets[$type . '_actual'] = $taken;

                Log::debug('题型按比例分配', [
                    'type' => $type,
                    'target' => $target,
                    'actual' => $taken
                ]);
            }
        }

        // ========== 步骤2：继续选题目，直到达到目标数量 ==========
        $allQuestions = array_merge($questionsByType['choice'], $questionsByType['fill'], $questionsByType['answer']);

        // 【重要】添加排序前的知识点分布日志
        $preSortKpDistribution = [];
        foreach ($allQuestions as $q) {
            $kpCode = $q['kp_code'] ?? '';
            if (!isset($preSortKpDistribution[$kpCode])) {
                $preSortKpDistribution[$kpCode] = 0;
            }
            $preSortKpDistribution[$kpCode]++;
        }

        Log::debug('selectQuestionsByMastery: 排序前知识点分布', [
            'total_questions' => count($allQuestions),
            'kp_distribution' => $preSortKpDistribution
        ]);

        // 【修复】添加随机因子到排序中，避免因ID排序导致知识点分布不均
        usort($allQuestions, function ($a, $b) use ($kpWeights) {
            $kpA = $a['kp_code'] ?? '';
            $kpB = $b['kp_code'] ?? '';
            $weightA = $kpWeights[$kpA] ?? 1.0;
            $weightB = $kpWeights[$kpB] ?? 1.0;

            // 主要按权重排序
            if ($weightA != $weightB) {
                return $weightB <=> $weightA;
            }

            // 权重相同时，添加随机排序而不是按ID排序
            // 使用随机因子确保相同权重的知识点有公平的选中机会
            return mt_rand(-1, 1);
        });

        // 【重要】添加排序后的知识点分布日志
        $postSortKpDistribution = [];
        $postSortFirst50 = []; // 记录前50题的知识点分布
        foreach ($allQuestions as $idx => $q) {
            $kpCode = $q['kp_code'] ?? '';
            if (!isset($postSortKpDistribution[$kpCode])) {
                $postSortKpDistribution[$kpCode] = 0;
            }
            $postSortKpDistribution[$kpCode]++;

            // 记录前50题的知识点
            if ($idx < 50) {
                $postSortFirst50[] = $kpCode;
            }
        }

        Log::debug('selectQuestionsByMastery: 排序后知识点分布', [
            'total_questions' => count($allQuestions),
            'kp_distribution' => $postSortKpDistribution
        ]);

        // 【修复】摸底测试继续选择题目：记录详细的选题过程
        Log::debug('摸底测试继续选择题目开始', [
            'selected_count_after_basic' => count($selectedQuestions),
            'total_questions' => $totalQuestions,
            'selected_kp_codes' => array_keys($kpSelected),
            'available_kp_count' => count($preSortKpDistribution),
            'strategy' => $useKnowledgePointPriority ? '知识点覆盖优先' : '无知识点限制'
        ]);

        if ($useKnowledgePointPriority) {
            // 知识点优先：assemble_type=2 先补齐原始请求知识点，再允许请求知识点重复，最后才使用 fallback KP
            $initialSelectedCount = count($selectedQuestions);
            $prioritySelectedCount = 0;
            $selectedIds = array_values(array_filter(array_column($selectedQuestions, 'id')));

            if ($shouldRestrictToRequestedKps) {
                foreach ($allQuestions as $q) {
                    if (count($selectedQuestions) >= $totalQuestions) {
                        break;
                    }

                    $kpCode = $q['kp_code'] ?? '';
                    $qid = $q['id'] ?? null;
                    if (!isset($requestedKpSet[$kpCode]) || $qid === null || in_array($qid, $selectedIds)) {
                        continue;
                    }

                    if (!isset($kpSelected[$kpCode])) {
                        $selectedQuestions[] = $q;
                        $selectedIds[] = $qid;
                        $kpSelected[$kpCode] = true;
                        $prioritySelectedCount++;
                        Log::debug('继续选择题目（请求知识点优先）', [
                            'kp' => $kpCode,
                            'id' => $qid,
                            'priority_selected_count' => $prioritySelectedCount,
                            'total_selected' => count($selectedQuestions)
                        ]);
                    }
                }
            } else {
                foreach ($allQuestions as $q) {
                    if (count($selectedQuestions) >= $totalQuestions) break;

                    $kpCode = $q['kp_code'] ?? '';
                    if (!isset($kpSelected[$kpCode])) {
                        $selectedQuestions[] = $q;
                        $kpSelected[$kpCode] = true;
                        $prioritySelectedCount++;
                        Log::debug('继续选择题目（知识点优先）', [
                            'kp' => $kpCode,
                            'id' => $q['id'] ?? 'unknown',
                            'priority_selected_count' => $prioritySelectedCount,
                            'total_selected' => count($selectedQuestions)
                        ]);
                    }
                }
            }

            Log::debug('摸底测试优先阶段完成', [
                'priority_selected_count' => $prioritySelectedCount,
                'total_selected' => count($selectedQuestions),
                'unique_kp_count' => count($kpSelected),
                'note' => '优先选择未选过知识点的题目'
            ]);

            // 【修复】降级策略：如果仍未达到目标数量，允许重复选择知识点
            if (count($selectedQuestions) < $totalQuestions) {
                Log::warning('selectQuestionsByMastery: 知识点优先策略无法满足数量要求，启用降级策略', [
                    'requested_count' => $totalQuestions,
                    'selected_count' => count($selectedQuestions),
                    'priority_selected_count' => $prioritySelectedCount,
                    'unique_kp_count' => count($kpSelected),
                    'available_kp_count' => count($preSortKpDistribution),
                    'note' => '将允许重复选择知识点以达到目标数量'
                ]);

                $fallbackSelectedCount = 0;
                $selectedIds = array_values(array_filter(array_column($selectedQuestions, 'id')));

                if ($shouldRestrictToRequestedKps) {
                    foreach ($allQuestions as $q) {
                        if (count($selectedQuestions) >= $totalQuestions) {
                            break;
                        }

                        $kpCode = $q['kp_code'] ?? '';
                        $qid = $q['id'] ?? null;
                        if ($qid === null || in_array($qid, $selectedIds) || !isset($requestedKpSet[$kpCode])) {
                            continue;
                        }

                        $selectedQuestions[] = $q;
                        $selectedIds[] = $qid;
                        $fallbackSelectedCount++;
                        Log::debug('降级选择题目（请求知识点重复）', [
                            'kp' => $kpCode,
                            'id' => $qid,
                            'fallback_selected_count' => $fallbackSelectedCount,
                            'current_count' => count($selectedQuestions)
                        ]);
                    }
                }

                foreach ($allQuestions as $q) {
                    if (count($selectedQuestions) >= $totalQuestions) break;

                    $qid = $q['id'] ?? null;
                    if ($qid && !in_array($qid, $selectedIds)) {
                        $selectedQuestions[] = $q;
                        $selectedIds[] = $qid;
                        $fallbackSelectedCount++;
                        Log::debug('降级选择题目（允许知识点重复）', [
                            'kp' => $q['kp_code'] ?? 'unknown',
                            'id' => $qid,
                            'fallback_selected_count' => $fallbackSelectedCount,
                            'current_count' => count($selectedQuestions)
                        ]);
                    }
                }

                Log::debug('摸底测试降级阶段完成', [
                    'fallback_selected_count' => $fallbackSelectedCount,
                    'total_selected' => count($selectedQuestions),
                    'note' => '允许重复选择知识点补充数量'
                ]);
            }
        } else {
            // 非摸底：题型不足时，缺口按优先级补到其他题型
            $totalSelected = count($selectedQuestions);
            if ($totalSelected < $totalQuestions) {
                $deficit = $totalQuestions - $totalSelected;
                $selectedIds = array_column($selectedQuestions, 'id');

                // 按补充优先级：填空 > 解答 > 选择（避免解答题独占缺口）
                $supplementOrder = ['fill', 'answer', 'choice'];

                Log::debug('题型缺口补充开始', [
                    'deficit' => $deficit,
                    'current_count' => $totalSelected,
                    'target' => $totalQuestions,
                    'supplement_order' => $supplementOrder,
                ]);

                foreach ($supplementOrder as $type) {
                    if ($deficit <= 0) break;
                    foreach ($questionsByType[$type] as $q) {
                        if ($deficit <= 0) break;
                        $qid = $q['id'] ?? null;
                        if ($qid && !in_array($qid, $selectedIds)) {
                            $selectedQuestions[] = $q;
                            $selectedIds[] = $qid;
                            $deficit--;
                        }
                    }
                }

                Log::debug('题型缺口补充完成', [
                    'final_count' => count($selectedQuestions),
                    'target' => $totalQuestions,
                ]);
            }
        }

        // 【移除】删除步骤3的多余逻辑
        // 前面的逻辑已经能选够题目，不需要额外的补充步骤

        Log::info('selectQuestionsByMastery 完成', [
            'total_questions' => $totalQuestions,
            'selected_count' => count($selectedQuestions),
            'success' => count($selectedQuestions) === $totalQuestions,
            'assemble_type' => $assembleType,
            'strategy' => $useKnowledgePointPriority ? '知识点覆盖优先' : '无知识点限制',
            'requested_kp_selection' => $this->buildRequestedKpSelectionStats($selectedQuestions, $requestedKpCodes),
            'type_distribution' => array_count_values(array_map(function($q) {
                $qid = $q['id'] ?? $q['question_id'] ?? null;
                if ($qid && isset($questionTypeCache[$qid])) {
                    return $questionTypeCache[$qid];
                }
                return $this->determineQuestionType($q);
            }, $selectedQuestions)),
            'kp_distribution' => array_count_values(array_column($selectedQuestions, 'kp_code'))
        ]);

        // 【重要】最终截取到目标数量（如果超过）
        if (count($selectedQuestions) > $totalQuestions) {
            Log::info('题目数量超过目标，进行最终截取', [
                'before' => count($selectedQuestions),
                'after' => $totalQuestions
            ]);
            $selectedQuestions = array_slice($selectedQuestions, 0, $totalQuestions);
        }

        // 【重要】添加最终数量验证日志
        Log::debug('selectQuestionsByMastery: 最终题目数量验证', [
            'before_final_check' => count($selectedQuestions),
            'target_count' => $totalQuestions,
            'is_array' => is_array($selectedQuestions)
        ]);

        // 【新增】最终知识点分布统计
        $finalKpDistribution = array_count_values(array_column($selectedQuestions, 'kp_code'));
        Log::debug('摸底测试最终知识点分布', [
            'final_total_count' => count($selectedQuestions),
            'target_count' => $totalQuestions,
            'final_kp_distribution' => $finalKpDistribution,
            'unique_kp_count' => count($finalKpDistribution),
            'success' => count($selectedQuestions) === $totalQuestions,
            'kp_coverage_rate' => count($finalKpDistribution) / max(count($preSortKpDistribution), 1) * 100
        ]);

        // ========== 最终排查：确保无重复题目且题型分布合理 ==========
        $finalQuestions = [];
        $seenQuestionIds = [];
        $duplicateCount = 0;
        $typeDistribution = ['choice' => 0, 'fill' => 0, 'answer' => 0];

        foreach ($selectedQuestions as $question) {
            $qbId = $question['question_bank_id'] ?? $question['id'];
            if (!in_array($qbId, $seenQuestionIds)) {
                $seenQuestionIds[] = $qbId;
                $finalQuestions[] = $question;

                // 统计题型分布
                $qid = $question['id'] ?? $question['question_id'] ?? null;
                $type = null;
                if ($qid && isset($questionTypeCache[$qid])) {
                    $type = $questionTypeCache[$qid];
                } else {
                    $type = $this->determineQuestionType($question);
                    if ($qid) {
                        $questionTypeCache[$qid] = $type;
                    }
                }
                if (isset($typeDistribution[$type])) {
                    $typeDistribution[$type]++;
                }
            } else {
                $duplicateCount++;
                Log::warning('发现重复题目（已自动移除）', [
                    'question_id' => $qbId,
                    'duplicate_count' => $duplicateCount
                ]);
            }
        }

        // 【重要】如果去重后数量不足，补充到目标数量
        if (count($finalQuestions) < $totalQuestions) {
            Log::warning('selectQuestionsByMastery: 去重后数量不足，尝试补充', [
                'final_count' => count($finalQuestions),
                'target_count' => $totalQuestions,
                'need_more' => $totalQuestions - count($finalQuestions)
            ]);

            // 从原始题目中选择未选过的题目补充
            $usedIds = array_column($finalQuestions, 'id');
            $supplementCount = 0;
            foreach ($selectedQuestions as $question) {
                if ($supplementCount >= ($totalQuestions - count($finalQuestions))) break;

                $qid = $question['id'] ?? null;
                if ($qid && !in_array($qid, $usedIds)) {
                    $finalQuestions[] = $question;
                    $usedIds[] = $qid;
                    $supplementCount++;
                }
            }

            Log::debug('selectQuestionsByMastery: 补充完成', [
                'supplement_added' => $supplementCount,
                'final_count_after_supplement' => count($finalQuestions)
            ]);
        }

        Log::debug('最终排查完成', [
            'original_count' => count($selectedQuestions),
            'final_count' => count($finalQuestions),
            'duplicate_removed' => $duplicateCount,
            'final_type_distribution' => $typeDistribution,
            'target_count' => $totalQuestions
        ]);

        // 【重要】确保返回的题目数量正确
        $finalQuestions = array_slice($finalQuestions, 0, $totalQuestions);

        Log::debug('selectQuestionsByMastery: 返回结果', [
            'return_count' => count($finalQuestions),
            'target_count' => $totalQuestions,
            'success' => count($finalQuestions) === $totalQuestions
        ]);

        // 注意：题型平衡已在上面完成，不需要再调用adjustQuestionsByRatio
        // adjustQuestionsByRatio主要处理题型配比，但我们的题型平衡机制已经确保了题型分布符合要求
        return $finalQuestions;
    }

    /**
     * 错题追练复用知识点组卷时使用：按计划里的 KP 配额、题型配额和难度上限选题。
     *
     * @param  array<int, array<string, mixed>>  $questions
     * @param  array<int, string>  $requestedKpCodes
     * @param  array<string, int>  $kpTargetCounts
     * @param  array<string, float|int|string>  $maxDifficultyByKp
     * @param  array<string, array<string, int>>  $typeTargetsByKp
     * @return array<int, array<string, mixed>>
     */
    private function selectQuestionsByKpTargets(
        array $questions,
        int $totalQuestions,
        array $requestedKpCodes,
        array $kpTargetCounts,
        array $maxDifficultyByKp,
        array $typeTargetsByKp
    ): array {
        $normalizedKpTargetCounts = [];
        foreach ($kpTargetCounts as $kpCode => $count) {
            $count = (int) $count;
            if ($count > 0) {
                $normalizedKpTargetCounts[(string) $kpCode] = $count;
            }
        }
        $kpTargetCounts = $normalizedKpTargetCounts;
        if ($kpTargetCounts === [] || $totalQuestions <= 0) {
            return [];
        }

        $targetKpOrder = array_values(array_filter($requestedKpCodes, static fn ($kp) => isset($kpTargetCounts[$kp])));
        foreach (array_keys($kpTargetCounts) as $kpCode) {
            if (! in_array($kpCode, $targetKpOrder, true)) {
                $targetKpOrder[] = $kpCode;
            }
        }

        $targetKpSet = array_fill_keys(array_keys($kpTargetCounts), true);
        $questionsByKp = [];
        $supplementQuestions = [];
        foreach ($questions as $question) {
            $kpCode = (string) ($question['kp_code'] ?? '');
            if ($kpCode === '') {
                continue;
            }
            $questionsByKp[$kpCode][] = $question;
            if (! isset($targetKpSet[$kpCode])) {
                $supplementQuestions[] = $question;
            }
        }

        $selected = [];
        $usedIds = [];
        $shortageByKp = [];

        foreach ($targetKpOrder as $kpCode) {
            $need = min((int) ($kpTargetCounts[$kpCode] ?? 0), max(0, $totalQuestions - count($selected)));
            if ($need <= 0) {
                continue;
            }

            $maxDifficulty = $this->normalizeAssemblyDifficulty($maxDifficultyByKp[$kpCode] ?? null);
            $typeTargets = $typeTargetsByKp[$kpCode] ?? [];
            $directSelected = $this->takeQuestionsForPracticeTarget(
                $questionsByKp[$kpCode] ?? [],
                $need,
                $maxDifficulty,
                $typeTargets,
                $usedIds
            );
            foreach ($directSelected as $question) {
                $question['practice_target_kp_code'] = $kpCode;
                $question['practice_target_difficulty'] = $maxDifficulty;
                $selected[] = $question;
            }

            $remainingNeed = $need - count($directSelected);
            if ($remainingNeed > 0 && $supplementQuestions !== []) {
                $supplementSelected = $this->takeQuestionsForPracticeTarget(
                    $supplementQuestions,
                    $remainingNeed,
                    $maxDifficulty,
                    [],
                    $usedIds
                );
                foreach ($supplementSelected as $question) {
                    $question['practice_target_kp_code'] = $kpCode;
                    $question['practice_target_difficulty'] = $maxDifficulty;
                    $question['practice_supplement_kp_code'] = $question['kp_code'] ?? null;
                    $selected[] = $question;
                }
                $remainingNeed -= count($supplementSelected);
            }

            if ($remainingNeed > 0) {
                $shortageByKp[$kpCode] = $remainingNeed;
            }
        }

        if (count($selected) < $totalQuestions) {
            $remainingNeed = $totalQuestions - count($selected);
            $targetPool = [];
            foreach ($targetKpOrder as $kpCode) {
                $targetPool = array_merge($targetPool, $questionsByKp[$kpCode] ?? []);
            }

            $backfillSelected = $this->takeQuestionsForPracticeTarget(
                $targetPool,
                $remainingNeed,
                null,
                [],
                $usedIds
            );
            foreach ($backfillSelected as $question) {
                $question['practice_backfill_reason'] = 'target_kp_shortage';
                $selected[] = $question;
            }

            $remainingNeed = $totalQuestions - count($selected);
            if ($remainingNeed > 0 && $supplementQuestions !== []) {
                $supplementBackfill = $this->takeQuestionsForPracticeTarget(
                    $supplementQuestions,
                    $remainingNeed,
                    null,
                    [],
                    $usedIds
                );
                foreach ($supplementBackfill as $question) {
                    $question['practice_backfill_reason'] = 'supplement_kp_shortage';
                    $selected[] = $question;
                }
            }

            Log::info('selectQuestionsByKpTargets: applied global backfill', [
                'target_count' => $totalQuestions,
                'selected_count' => count($selected),
                'shortage_by_kp' => $shortageByKp,
                'backfill_count' => count($selected) - ($totalQuestions - array_sum($shortageByKp)),
            ]);
        }

        if (count($selected) < $totalQuestions) {
            Log::warning('selectQuestionsByKpTargets: planned KP selection produced fewer questions', [
                'target_count' => $totalQuestions,
                'selected_count' => count($selected),
                'shortage_by_kp' => $shortageByKp,
                'kp_target_counts' => $kpTargetCounts,
                'available_kp_distribution' => array_map('count', $questionsByKp),
            ]);
        }

        Log::info('selectQuestionsByKpTargets 完成', [
            'target_count' => $totalQuestions,
            'selected_count' => count($selected),
            'kp_target_counts' => $kpTargetCounts,
            'selected_kp_distribution' => array_count_values(array_column($selected, 'kp_code')),
            'practice_target_distribution' => array_count_values(array_column($selected, 'practice_target_kp_code')),
        ]);

        return array_slice($selected, 0, $totalQuestions);
    }

    /**
     * @param  array<int, array<string, mixed>>  $pool
     * @param  array<string, int>  $typeTargets
     * @param  array<string, bool>  $usedIds
     * @return array<int, array<string, mixed>>
     */
    private function takeQuestionsForPracticeTarget(
        array $pool,
        int $need,
        ?float $maxDifficulty,
        array $typeTargets,
        array &$usedIds
    ): array {
        if ($need <= 0 || $pool === []) {
            return [];
        }

        $candidateBuckets = ['choice' => [], 'fill' => [], 'answer' => []];
        $questionPayloadMapper = app(QuestionPayloadMapper::class);
        foreach ($pool as $question) {
            $id = (string) ($question['id'] ?? $question['question_id'] ?? '');
            if ($id === '' || isset($usedIds[$id])) {
                continue;
            }

            $difficulty = $this->normalizeAssemblyDifficulty($question['difficulty'] ?? null) ?? 0.5;

            $type = $questionPayloadMapper->normalizeQuestionType((string) ($question['question_type'] ?? $question['type'] ?? ''))
                ?? $this->determineQuestionType($question);
            if (! isset($candidateBuckets[$type])) {
                $type = 'answer';
            }
            $question['practice_match_delta'] = $maxDifficulty !== null ? round($maxDifficulty - $difficulty, 4) : 0.0;
            $question['practice_candidate_difficulty'] = $difficulty;
            $candidateBuckets[$type][] = $question;
        }

        foreach ($candidateBuckets as &$bucket) {
            usort($bucket, function (array $a, array $b) use ($maxDifficulty): int {
                return $this->comparePracticeDifficulty($a, $b, $maxDifficulty);
            });
        }
        unset($bucket);

        $selected = [];
        foreach (['choice', 'fill', 'answer'] as $type) {
            $target = min((int) ($typeTargets[$type] ?? 0), $need - count($selected));
            if ($target <= 0) {
                continue;
            }
            while ($target > 0 && ! empty($candidateBuckets[$type])) {
                $question = array_shift($candidateBuckets[$type]);
                $id = (string) ($question['id'] ?? $question['question_id'] ?? '');
                if ($id === '' || isset($usedIds[$id])) {
                    continue;
                }
                $selected[] = $question;
                $usedIds[$id] = true;
                $target--;
            }
        }

        $remaining = array_merge($candidateBuckets['choice'], $candidateBuckets['fill'], $candidateBuckets['answer']);
        usort($remaining, function (array $a, array $b) use ($maxDifficulty): int {
            return $this->comparePracticeDifficulty($a, $b, $maxDifficulty);
        });

        foreach ($remaining as $question) {
            if (count($selected) >= $need) {
                break;
            }
            $id = (string) ($question['id'] ?? $question['question_id'] ?? '');
            if ($id === '' || isset($usedIds[$id])) {
                continue;
            }
            $selected[] = $question;
            $usedIds[$id] = true;
        }

        return $selected;
    }

    private function comparePracticeDifficulty(array $a, array $b, ?float $targetDifficulty): int
    {
        $da = $this->normalizeAssemblyDifficulty($a['difficulty'] ?? null) ?? 0.5;
        $db = $this->normalizeAssemblyDifficulty($b['difficulty'] ?? null) ?? 0.5;

        if ($targetDifficulty === null) {
            $scoreA = abs(0.5 - $da);
            $scoreB = abs(0.5 - $db);
        } else {
            $scoreA = $da <= $targetDifficulty
                ? $targetDifficulty - $da
                : 1 + ($da - $targetDifficulty);
            $scoreB = $db <= $targetDifficulty
                ? $targetDifficulty - $db
                : 1 + ($db - $targetDifficulty);
        }

        if ($scoreA !== $scoreB) {
            return $scoreA <=> $scoreB;
        }

        return ((int) ($a['id'] ?? $a['question_id'] ?? 0)) <=> ((int) ($b['id'] ?? $b['question_id'] ?? 0));
    }

    private function normalizeAssemblyDifficulty(mixed $difficulty): ?float
    {
        if ($difficulty === null || $difficulty === '') {
            return null;
        }
        if (! is_numeric($difficulty)) {
            return null;
        }

        $value = (float) $difficulty;
        if ($value > 1) {
            $value = $value / 5;
        }

        return max(0.0, min(1.0, $value));
    }

    /**
     * @param  array<int, array<string, mixed>>  $questions
     * @param  array<int, string>  $requestedKpCodes
     * @return array<string, mixed>
     */
    private function buildRequestedKpSelectionStats(array $questions, array $requestedKpCodes): array
    {
        $requestedKpCodes = array_values(array_unique(array_filter($requestedKpCodes)));
        if ($requestedKpCodes === []) {
            return [
                'requested_kp_codes' => [],
                'requested_kp_selected_count' => 0,
                'related_kp_selected_count' => 0,
                'requested_kp_distribution' => [],
                'related_kp_distribution' => [],
            ];
        }

        $requestedKpSet = array_fill_keys($requestedKpCodes, true);
        $requestedDistribution = [];
        $relatedDistribution = [];

        foreach ($questions as $question) {
            $kpCode = (string) ($question['kp_code'] ?? '');
            if ($kpCode === '') {
                continue;
            }

            if (isset($requestedKpSet[$kpCode])) {
                $requestedDistribution[$kpCode] = ($requestedDistribution[$kpCode] ?? 0) + 1;
            } else {
                $relatedDistribution[$kpCode] = ($relatedDistribution[$kpCode] ?? 0) + 1;
            }
        }

        return [
            'requested_kp_codes' => $requestedKpCodes,
            'requested_kp_selected_count' => array_sum($requestedDistribution),
            'related_kp_selected_count' => array_sum($relatedDistribution),
            'requested_kp_distribution' => $requestedDistribution,
            'related_kp_distribution' => $relatedDistribution,
        ];
    }

    /**
     * @param  array<int, array<string, mixed>>  $questions
     * @return array<string, mixed>
     */
    private function buildSupplementQuestionStats(array $questions): array
    {
        $kpDistribution = array_count_values(array_filter(array_map(
            static fn ($question) => (string) ($question['kp_code'] ?? ''),
            $questions
        )));
        arsort($kpDistribution);

        return [
            'supplement_kp_distribution_topn' => array_slice($kpDistribution, 0, 10, true),
            'supplement_kp_sample' => array_slice(array_keys($kpDistribution), 0, 10),
        ];
    }

    /**
     * 获取学生对特定知识点的掌握度
     */
    private function getStudentKpMastery(string $studentId, string $kpCode): float
    {
        try {
            $mastery = DB::table('student_mastery')
                ->where('student_id', $studentId)
                ->where('kp', $kpCode)
                ->value('mastery');

            return $mastery ? (float) $mastery : 0.5; // 默认0.5（中等掌握度）
        } catch (\Exception $e) {
            Log::error('Get Student Kp Mastery Error', [
                'student_id' => $studentId,
                'kp_code' => $kpCode,
                'error' => $e->getMessage()
            ]);
            return 0.5;
        }
    }

    /**
     * 根据题型和难度配比调整题目
     */
    private function adjustQuestionsByRatio(array $questions, array $typeRatio, int $targetCount): array
    {
        Log::debug('开始题型配比调整', [
            'input_questions' => count($questions),
            'target_count' => $targetCount,
            'type_ratio' => $typeRatio
        ]);

        // 缓存题目类型，避免重复计算
        $questionTypeCache = [];

        // 按题型分桶
        $buckets = [
            'choice' => [],
            'fill' => [],
            'answer' => [],
        ];
        foreach ($questions as $q) {
            $qid = $q['id'] ?? $q['question_id'] ?? null;

            if ($qid && isset($questionTypeCache[$qid])) {
                $type = $questionTypeCache[$qid];
            } else {
                $type = $this->determineQuestionType($q);
                if ($qid) {
                    $questionTypeCache[$qid] = $type;
                }
            }

            if (!isset($buckets[$type])) {
                $type = 'answer';
            }
            $buckets[$type][] = $q;
        }

        // 计算目标数（四舍五入，比例>0 则至少 1 道）
        // 修复：不自动减少目标数量，确保达到用户要求
        $availableCount = count($questions);
        $targets = $this->computeTypeTargets($targetCount, $typeRatio);

        Log::debug('题型配比调整前桶统计', [
            'target_count' => $targetCount,
            'available_count' => $availableCount,
            'targets' => $targets,
            'bucket_counts' => [
                'choice' => count($buckets['choice']),
                'fill' => count($buckets['fill']),
                'answer' => count($buckets['answer']),
            ],
            'raw_ratio' => $typeRatio,
        ]);

        // 随机打乱桶
        foreach ($buckets as $k => $v) {
            if (!empty($v)) {
                shuffle($v);
                $buckets[$k] = $v;
            }
        }

        $selected = [];
        $selectedIds = [];

        // 按目标数依次取题
        foreach (['choice', 'fill', 'answer'] as $typeKey) {
            $need = $targets[$typeKey] ?? 0;
            if ($need <= 0 || empty($buckets[$typeKey])) {
                continue;
            }
            $take = min($need, count($buckets[$typeKey]));
            $slice = array_slice($buckets[$typeKey], 0, $take);
            foreach ($slice as $q) {
                $id = $q['id'] ?? $q['question_id'] ?? spl_object_id((object)$q);
                if (isset($selectedIds[$id])) {
                    continue;
                }
                $selected[] = $q;
                $selectedIds[$id] = true;
            }
        }

        // 不足则从剩余题中补齐
        if (count($selected) < $targetCount) {
            $remaining = [];
            foreach ($buckets as $v) {
                foreach ($v as $q) {
                    $id = $q['id'] ?? $q['question_id'] ?? spl_object_id((object)$q);
                    if (!isset($selectedIds[$id])) {
                        $remaining[] = $q;
                    }
                }
            }
            shuffle($remaining);
            $needMore = $targetCount - count($selected);
            $selected = array_merge($selected, array_slice($remaining, 0, $needMore));
        }

        // 截断至目标数
        $selected = array_slice($selected, 0, $targetCount);

        // 使用缓存统计题型分布
        $selectedCounts = ['choice' => 0, 'fill' => 0, 'answer' => 0];
        foreach ($selected as $q) {
            $qid = $q['id'] ?? $q['question_id'] ?? null;
            if ($qid && isset($questionTypeCache[$qid])) {
                $type = $questionTypeCache[$qid];
            } else {
                $type = $this->determineQuestionType($q);
            }
            if (isset($selectedCounts[$type])) {
                $selectedCounts[$type]++;
            }
        }

        Log::debug('题型配比调整完成', [
            'target_count' => $targetCount,
            'targets' => $targets,
            'selected_counts' => $selectedCounts,
            'final_selected_count' => count($selected)
        ]);

        return $selected;
    }

    private function determineQuestionType(array $q): string
    {
        // 优先根据题目内容判断（而不是数据库字段）
        $stem = $q['stem'] ?? $q['content'] ?? '';
        // 处理 stem 可能是数组的情况
        if (is_array($stem)) {
            $stem = json_encode($stem, JSON_UNESCAPED_UNICODE);
        }
        $tags = $q['tags'] ?? '';
        // 处理 tags 可能是数组的情况
        if (is_array($tags)) {
            $tags = json_encode($tags, JSON_UNESCAPED_UNICODE);
        }
        $skills = $q['skills'] ?? [];

        // 1. 根据题干内容判断 - 选择题特征：必须包含 A. B. C. D. 选项（至少2个）
        if (is_string($stem)) {
            // 选择题特征：必须包含 A. B. C. D. 四个选项（至少2个）
            $hasOptionA = preg_match('/\bA\s*[\.\、\:]/', $stem) || preg_match('/\(A\)/', $stem) || preg_match('/^A[\.\s]/', $stem);
            $hasOptionB = preg_match('/\bB\s*[\.\、\:]/', $stem) || preg_match('/\(B\)/', $stem) || preg_match('/^B[\.\s]/', $stem);
            $hasOptionC = preg_match('/\bC\s*[\.\、\:]/', $stem) || preg_match('/\(C\)/', $stem) || preg_match('/^C[\.\s]/', $stem);
            $hasOptionD = preg_match('/\bD\s*[\.\、\:]/', $stem) || preg_match('/\(D\)/', $stem) || preg_match('/^D[\.\s]/', $stem);
            $hasOptionE = preg_match('/\bE\s*[\.\、\:]/', $stem) || preg_match('/\(E\)/', $stem) || preg_match('/^E[\.\s]/', $stem);

            // 至少有2个选项就认为是选择题（降低阈值）
            $optionCount = ($hasOptionA ? 1 : 0) + ($hasOptionB ? 1 : 0) + ($hasOptionC ? 1 : 0) + ($hasOptionD ? 1 : 0) + ($hasOptionE ? 1 : 0);
            if ($optionCount >= 2) {
                return 'choice';
            }

            // 检查是否有"（ ）"或"( )"括号，这通常是选择题的标志
            if (preg_match('/（\s*）|\(\s*\)/', $stem) && (strpos($stem, 'A.') !== false || strpos($stem, 'B.') !== false || strpos($stem, 'C.') !== false || strpos($stem, 'D.') !== false)) {
                return 'choice';
            }
        }

        // 2. 根据技能点判断
        if (is_array($skills) && !empty($skills)) {
            // 过滤非字符串元素，避免 implode 报错
            $skillsFiltered = array_filter($skills, 'is_string');
            if (!empty($skillsFiltered)) {
                $skillsStr = implode(',', $skillsFiltered);
                if (strpos($skillsStr, '选择题') !== false) return 'choice';
                if (strpos($skillsStr, '填空题') !== false) return 'fill';
                if (strpos($skillsStr, '解答题') !== false) return 'answer';
            }
        }

        // 3. 根据题目已有类型字段判断（作为后备）
        $typeField = $q['question_type'] ?? $q['type'] ?? '';
        if (is_string($typeField)) {
            $t = strtolower($typeField);
            if (in_array($t, ['choice', 'single_choice', 'multiple_choice', '选择题', 'choice', 'single_choice', 'multiple_choice'])) {
                return 'choice';
            }
            if (in_array($t, ['fill', 'blank', 'fill_blank', 'fill_in_the_blank', '填空题'])) {
                return 'fill';
            }
            if (in_array($t, ['answer', 'calculation', 'word_problem', 'proof', '解答题'])) {
                return 'answer';
            }
        }

        // 4. 根据标签判断
        if (is_string($tags)) {
            if (strpos($tags, '选择') !== false || strpos($tags, '选择题') !== false) {
                return 'choice';
            }
            if (strpos($tags, '填空') !== false || strpos($tags, '填空题') !== false) {
                return 'fill';
            }
            if (strpos($tags, '解答') !== false || strpos($tags, '简答') !== false || strpos($tags, '证明') !== false) {
                return 'answer';
            }
        }

        // 5. 根据options字段判断
        if (!empty($q['options']) && is_array($q['options'])) {
            return 'choice';
        }

        // 6. 填空题特征：连续下划线或明显的填空括号
        if (is_string($stem)) {
            // 检查填空题特征：连续下划线
            if (preg_match('/_{3,}/', $stem) || strpos($stem, '____') !== false) {
                return 'fill';
            }
            // 空括号填空
            if (preg_match('/（\s*）/', $stem) || preg_match('/\(\s*\)/', $stem)) {
                return 'fill';
            }
        }

        // 7. 根据题干内容关键词判断
        if (is_string($stem)) {
            // 有证明、解答、计算、求证等关键词的是解答题
            if (preg_match('/(证明|求证|解方程|计算：|求解|推导|说明理由)/', $stem)) {
                return 'answer';
            }
        }

        // 默认是解答题（更安全的默认值）
        return 'answer';
    }

    // 【移除】删除未使用的mapDifficultyLevel方法
    // 难度分布由QuestionLocalService处理，不需要额外的难度映射

    private function computeTypeTargets(int $targetCount, array $questionTypeRatio): array
    {
        $map = [
            '选择题' => 'choice',
            '填空题' => 'fill',
            '解答题' => 'answer',
        ];
        $targets = ['choice' => 0, 'fill' => 0, 'answer' => 0];
        foreach ($questionTypeRatio as $label => $ratio) {
            $key = $map[$label] ?? null;
            if (!$key) {
                continue;
            }
            $cnt = (int) round($targetCount * ($ratio / 100));
            if ($ratio > 0 && $cnt < 1) {
                $cnt = 1;
            }
            $targets[$key] = $cnt;
        }
        $sum = array_sum($targets);
        if ($sum === 0) {
            $targets['answer'] = $targetCount;
            return $targets;
        }
        while ($sum > $targetCount) {
            arsort($targets);
            foreach ($targets as $k => $v) {
                if ($v > 1) {
                    $targets[$k]--;
                    $sum--;
                    break;
                }
            }
        }
        if ($sum < $targetCount) {
            $ratioByKey = [
                'choice' => $questionTypeRatio['选择题'] ?? 0,
                'fill' => $questionTypeRatio['填空题'] ?? 0,
                'answer' => $questionTypeRatio['解答题'] ?? 0,
            ];
            while ($sum < $targetCount) {
                arsort($ratioByKey);
                $k = array_key_first($ratioByKey);
                $targets[$k]++;
                $sum++;
            }
        }
        return $targets;
    }

    /**
     * 提交手动评分结果到 LearningAnalytics
     *
     * @param array $data 包含 student_id, paper_id, grades 的数组
     * @return array
     */
    public function submitManualGrading(array $data): array
    {
        try {
            $response = Http::timeout($this->timeout)
                ->post($this->baseUrl . '/api/ocr/analyze', [
                    'student_id' => $data['student_id'],
                    'paper_id' => $data['paper_id'],
                    'answers' => $data['grades'],
                ]);

            if ($response->successful()) {
                Log::info('Manual grading submitted successfully', [
                    'student_id' => $data['student_id'],
                    'paper_id' => $data['paper_id'],
                    'question_count' => count($data['grades'])
                ]);

                return $response->json();
            }

            Log::error('Submit Manual Grading Error', [
                'data' => $data,
                'status' => $response->status(),
                'response' => $response->body()
            ]);

            return [
                'error' => true,
                'message' => 'Failed to submit manual grading'
            ];
        } catch (\Exception $e) {
            Log::error('Submit Manual Grading Exception', [
                'error' => $e->getMessage(),
                'data' => $data
            ]);

            return [
                'error' => true,
                'message' => $e->getMessage()
            ];
        }
    }

    /**
     * 分析学生作答结果
     *
     * @param array $data 包含 paper_id, student_id, answers 等
     * @return array
     */
    public function analyzeStudentAnswers(array $data): array
    {
        Log::warning('analyzeStudentAnswers 已停用：分析项目已下线', [
            'student_id' => $data['student_id'] ?? null,
            'paper_id' => $data['paper_id'] ?? null,
        ]);

        return [
            'success' => false,
            'message' => 'analysis_api_disabled',
        ];
    }

    /**
     * 智能补充题目（当指定知识点的题目不足时）
     *
     * @param int $grade 年级
     * @param array $existingKpCodes 已有的知识点代码（用于排除）
     * @param int $needCount 需要补充的题目数量
     * @param int $difficultyCategory 难度类别
     * @param int|null $textbookId 教材ID（用于限制补充范围，避免超纲）
     * @param array $excludeQuestionIds 排除的题目ID（学生已做过，避免重复）
     * @param array|null $textbookCatalogNodeIds 当前选中的章节节点ID；与 textbookId 同时传入时，仅从同教材的前章节补充（未学章节不补充）
     * @param string|null $studentId 学生ID（无教材时用于获取「已学知识点」，仅从已学内容补充，避免未学章节）
     * @return array 补充的题目列表
     */
    private function getSupplementaryQuestionsForGrade(
        int $grade,
        array $existingKpCodes,
        int $needCount,
        int $difficultyCategory,
        ?int $textbookId = null,
        array $excludeQuestionIds = [],
        ?array $textbookCatalogNodeIds = null,
        ?string $studentId = null
    ): array {
        try {
            Log::info('getSupplementaryQuestionsForGrade: 开始智能补充', [
                'grade' => $grade,
                'existing_kp_count' => count($existingKpCodes),
                'need_count' => $needCount,
                'difficulty_category' => $difficultyCategory,
                'textbook_id' => $textbookId,
                'student_id' => $studentId ? '(有)' : '(无)',
                'exclude_count' => count($excludeQuestionIds),
                'has_chapter_scope' => !empty($textbookCatalogNodeIds),
            ]);

            // 【核心】补充范围：只从「学过的」内容补充，不能从未学知识点或年级对应章节中选
            // - 有 textbookId：从 textbook_id -> 章节 -> 章节知识点关联表 取 kp_code（若有 chapter scope 再收缩到前章节）
            // - 无 textbookId 且有 studentId：从学生做过的题目对应知识点（getStudentLearnedKpCodes）补充
            // - 无 textbookId 且无 studentId：无法确定学过的内容，不补充
            $gradeKpCodes = [];
            if ($textbookId) {
                $allCatalogNodeIds = DB::table('textbook_catalog_nodes')
                    ->where('textbook_id', $textbookId)
                    ->pluck('id')
                    ->map(static fn ($id) => (int) $id)
                    ->toArray();

                $gradeKpCodes = $this->getKpCodesForCatalogChapterIds($allCatalogNodeIds);

                Log::info('getSupplementaryQuestionsForGrade: 教材模式，按章节关联知识点补题', [
                    'kp_count' => count($gradeKpCodes),
                    'textbook_id' => $textbookId,
                    'catalog_node_count' => count($allCatalogNodeIds),
                ]);
            } elseif ($studentId) {
                $learnedKps = $this->getStudentLearnedKpCodes($studentId);
                $gradeKpCodes = array_values(array_diff($learnedKps, $existingKpCodes));
                Log::info('getSupplementaryQuestionsForGrade: 无教材模式，使用学生已学知识点', [
                    'learned_count' => count($learnedKps),
                    'after_exclude_existing' => count($gradeKpCodes),
                ]);
            } else {
                Log::warning('getSupplementaryQuestionsForGrade: 无教材且无学生ID，无法确定学过的内容，不补充');
                return [];
            }

            if (empty($gradeKpCodes)) {
                Log::warning('getSupplementaryQuestionsForGrade: 无可用知识点，跳过补充', [
                    'grade' => $grade,
                    'textbook_id' => $textbookId,
                    'note' => $textbookId ? '教材知识点不足' : '学生已学知识点不足或与当前选题重复',
                ]);
                return [];
            }

            // 有教材且带章节：用 textbook_chapter_knowledge_relation 由「前章节」解析知识点，再按 kp_code 选题（不用 questions.textbook_catalog_nodes_id）
            $effectiveKpCodes = $gradeKpCodes;
            if ($textbookId && ! empty($textbookCatalogNodeIds)) {
                $allowedNodeIds = $this->getEarlierChapterNodeIds((int) $textbookId, $textbookCatalogNodeIds);
                if (empty($allowedNodeIds)) {
                    Log::warning('getSupplementaryQuestionsForGrade: 未找到前章节节点，跳过补充');

                    return [];
                }
                $chapterKpCodes = $this->getKpCodesForCatalogChapterIds($allowedNodeIds);
                if (empty($chapterKpCodes)) {
                    Log::warning('getSupplementaryQuestionsForGrade: 前章节在 textbook_chapter_knowledge_relation 中无知识点', [
                        'allowed_node_ids' => $allowedNodeIds,
                    ]);

                    return [];
                }
                $effectiveKpCodes = array_values(array_intersect($gradeKpCodes, $chapterKpCodes));
                if (empty($effectiveKpCodes)) {
                    Log::warning('getSupplementaryQuestionsForGrade: 教材年级知识点与章节关联知识点无交集', [
                        'grade_kp_count' => count($gradeKpCodes),
                        'chapter_kp_count' => count($chapterKpCodes),
                    ]);

                    return [];
                }
                Log::info('getSupplementaryQuestionsForGrade: 按章节关联知识点缩小补充范围', [
                    'allowed_chapter_nodes' => count($allowedNodeIds),
                    'chapter_kp_count' => count($chapterKpCodes),
                    'effective_kp_count' => count($effectiveKpCodes),
                ]);
            }

            // 查询同年级其他知识点的题目
            $query = \App\Models\Question::query();

            // 只获取审核通过的题目
            $query->where('audit_status', 0);

            // 【新增】排除学生已做过的题目
            if (!empty($excludeQuestionIds)) {
                $query->whereNotIn('id', $excludeQuestionIds);
            }

            $stageGrade = $this->normalizeQuestionStageGrade($grade);
            if ($stageGrade !== null) {
                $query->where('grade', $stageGrade);
                Log::info('getSupplementaryQuestionsForGrade: 应用学段筛选', [
                    'input_grade' => $grade,
                    'stage_grade' => $stageGrade
                ]);
            }

            // 排除已选知识点
            if (!empty($existingKpCodes)) {
                $query->whereNotIn('kp_code', $existingKpCodes);
            }

            $query->whereIn('kp_code', $effectiveKpCodes);

            // 筛选有解题思路的题目
            $query->whereNotNull('solution')
                  ->where('solution', '!=', '')
                  ->where('solution', '!=', '[]');

            // 【重要】移除题目分类限制，允许补充其他分类的题目
            // $query->where('question_category', 1); // 移除这行

            // 根据难度类别调整查询
            $difficultyRanges = $this->getDifficultyRangesForCategory($difficultyCategory);
            $query->where(function ($q) use ($difficultyRanges) {
                foreach ($difficultyRanges as $range) {
                    $q->orWhereBetween('difficulty', [$range['min'], $range['max']]);
                }
            });

            // 随机排序，增加多样性
            $query->inRandomOrder()
                  ->limit($needCount * 2); // 多取一些，后续筛选

            $supplementaryQuestions = $query->get();

            Log::info('getSupplementaryQuestionsForGrade: 查询完成', [
                'found_count' => $supplementaryQuestions->count(),
                'need_count' => $needCount
            ]);

            // 格式化题目
            $formatted = [];
            foreach ($supplementaryQuestions as $question) {
                // 优先使用题库原始题型
                $stem = $question->stem ?? '';
                $options = is_array($question->options) ? $question->options : (json_decode($question->options ?? '[]', true) ?: []);
                $correctAnswer = $question->correct_answer ?? '';

                $questionType = $question->question_type ?? 'answer';

                $formatted[] = [
                    'id' => $question->id,
                    'question_bank_id' => $question->id,
                    'question_type' => $questionType,
                    'kp_code' => $question->kp_code,
                    'difficulty' => $question->difficulty !== null ? (float) $question->difficulty : 0.5,
                    'stem' => $stem,
                    'options' => $options,
                    'correct_answer' => $correctAnswer,
                    'solution' => $question->solution,
                    'score' => $question->score ?? 4,
                    'estimated_time' => $question->estimated_time ?? 300,
                    'metadata' => [
                        'question_type_label' => $questionType === 'choice' ? '选择题' : ($questionType === 'fill' ? '填空题' : '解答题'),
                        'difficulty_label' => $this->getDifficultyLabelFromObject($question->difficulty ?? 0.5),
                        'is_supplementary' => true
                    ]
                ];
            }

            // 随机选择需要的数量
            shuffle($formatted);
            $selected = array_slice($formatted, 0, $needCount);

            Log::info('getSupplementaryQuestionsForGrade: 补充完成', [
                'supplementary_count' => count($selected),
                'kp_distribution' => array_count_values(array_column($selected, 'kp_code'))
            ]);

            return $selected;

        } catch (\Exception $e) {
            Log::error('getSupplementaryQuestionsForGrade: 补充失败', [
                'grade' => $grade,
                'need_count' => $needCount,
                'error' => $e->getMessage()
            ]);
            return [];
        }
    }

    /**
     * 获取同教材中「当前选中章节及之前」的节点 ID 列表（用于前章节补充，避免未学章节）
     *
     * @param int $textbookId 教材ID
     * @param array $chapterNodeIds 当前选中的章节节点ID
     * @return array 允许的节点ID列表（sort_order <= 选中章节的最大 sort_order）
     */
    private function getEarlierChapterNodeIds(int $textbookId, array $chapterNodeIds): array
    {
        if (empty($chapterNodeIds)) {
            return [];
        }
        try {
            $maxSortOrder = DB::table('textbook_catalog_nodes')
                ->where('textbook_id', $textbookId)
                ->whereIn('id', $chapterNodeIds)
                ->max('sort_order');

            if ($maxSortOrder === null) {
                Log::warning('getEarlierChapterNodeIds: 未找到选中章节的 sort_order', [
                    'textbook_id' => $textbookId,
                    'chapter_node_ids' => $chapterNodeIds
                ]);
                return [];
            }

            $allowedNodeIds = DB::table('textbook_catalog_nodes')
                ->where('textbook_id', $textbookId)
                ->where('sort_order', '<=', $maxSortOrder)
                ->pluck('id')
                ->toArray();

            Log::info('getEarlierChapterNodeIds: 前章节节点', [
                'textbook_id' => $textbookId,
                'max_sort_order' => $maxSortOrder,
                'allowed_node_count' => count($allowedNodeIds)
            ]);
            return $allowedNodeIds;
        } catch (\Exception $e) {
            Log::error('getEarlierChapterNodeIds: 查询失败', [
                'textbook_id' => $textbookId,
                'error' => $e->getMessage()
            ]);
            return [];
        }
    }

    /**
     * 获取指定年级的知识点列表
     *
     * @param int $grade 年级
     * @param int|null $textbookId 教材ID（可选，用于限制在特定教材范围内，避免超纲）
     * @return array 知识点代码列表
     */
    /**
     * 获取学生「已学知识点」：通过该学生做过的题目（paper_questions）对应的 kp_code 推断
     * 用于无教材信息时，智能补充仅从已学知识点中选，避免出现未学内容
     *
     * @param string|null $studentId 学生ID
     * @return array 知识点代码列表（去重、非空）
     */
    private function getStudentLearnedKpCodes(?string $studentId): array
    {
        if (empty($studentId)) {
            return [];
        }
        try {
            $questionBankIds = \App\Models\PaperQuestion::query()
                ->whereHas('paper', fn($q) => $q->where('student_id', $studentId))
                ->pluck('question_bank_id')
                ->unique()
                ->filter()
                ->values()
                ->toArray();

            if (empty($questionBankIds)) {
                Log::info('getStudentLearnedKpCodes: 学生暂无做题记录', ['student_id' => $studentId]);
                return [];
            }

            $kpCodes = \App\Models\Question::query()
                ->whereIn('id', $questionBankIds)
                ->whereNotNull('kp_code')
                ->where('kp_code', '!=', '')
                ->pluck('kp_code')
                ->unique()
                ->values()
                ->toArray();

            Log::info('getStudentLearnedKpCodes: 已学知识点', [
                'student_id' => $studentId,
                'kp_count' => count($kpCodes),
            ]);
            return $kpCodes;
        } catch (\Exception $e) {
            Log::error('getStudentLearnedKpCodes: 查询失败', [
                'student_id' => $studentId,
                'error' => $e->getMessage(),
            ]);
            return [];
        }
    }

    /**
     * 由 catalog 章节节点 ID 列表，从 textbook_chapter_knowledge_relation 取关联的知识点编码（用于选题，而非题目表上的章节字段）。
     *
     * @param  array<int>  $catalogChapterIds  textbook_catalog_nodes.id
     * @return list<string>
     */
    private function getKpCodesForCatalogChapterIds(array $catalogChapterIds): array
    {
        $ids = array_values(array_unique(array_filter(array_map(
            static fn ($id) => (int) $id,
            $catalogChapterIds
        ), static fn (int $id) => $id > 0)));

        if ($ids === []) {
            return [];
        }

        return array_values(array_filter(array_unique(DB::table('textbook_chapter_knowledge_relation')
            ->whereIn('catalog_chapter_id', $ids)
            ->where(function ($q) {
                $q->where('is_deleted', 0)->orWhereNull('is_deleted');
            })
            ->pluck('kp_code')
            ->toArray())));
    }

    private function getGradeKnowledgePoints(int $grade, ?int $textbookId = null): array
    {
        try {
            $query = DB::table('textbook_chapter_knowledge_relation as tckr')
                ->join('textbook_catalog_nodes as tcn', 'tckr.catalog_chapter_id', '=', 'tcn.id')
                ->join('textbooks as t', 'tcn.textbook_id', '=', 't.id')
                ->where('t.grade', $grade)
                ->where(function ($q) {
                    $q->where('tckr.is_deleted', 0)->orWhereNull('tckr.is_deleted');
                });

            // 【修复超纲问题】如果有 textbook_id，严格限制在该教材范围内
            // 避免七年级上册学生拿到七年级下册的知识点
            if ($textbookId) {
                $query->where('t.id', $textbookId);
                Log::info('getGradeKnowledgePoints: 限制在指定教材范围内', [
                    'grade' => $grade,
                    'textbook_id' => $textbookId
                ]);
            }

            $kpCodes = $query->distinct()
                ->pluck('tckr.kp_code')
                ->toArray();

            Log::info('getGradeKnowledgePoints: 获取知识点完成', [
                'grade' => $grade,
                'textbook_id' => $textbookId,
                'kp_count' => count($kpCodes)
            ]);

            return array_filter($kpCodes);
        } catch (\Exception $e) {
            Log::error('getGradeKnowledgePoints: 查询失败', [
                'grade' => $grade,
                'textbook_id' => $textbookId,
                'error' => $e->getMessage()
            ]);
            return [];
        }
    }

    /**
     * 【新增】根据难度类别获取难度范围
     */
    private function getDifficultyRangesForCategory(int $difficultyCategory): array
    {
        return match($difficultyCategory) {
            1 => [
                ['min' => 0.0, 'max' => 0.5],  // 基础型：偏向低难度
                ['min' => 0.5, 'max' => 1.0],
            ],
            2 => [
                ['min' => 0.0, 'max' => 0.5],  // 进阶型：均衡分布
                ['min' => 0.5, 'max' => 1.0],
            ],
            3 => [
                ['min' => 0.25, 'max' => 0.75], // 中等型：偏向中等难度
                ['min' => 0.0, 'max' => 1.0],
            ],
            4 => [
                ['min' => 0.5, 'max' => 1.0],  // 拔高型：偏向高难度
                ['min' => 0.0, 'max' => 0.5],
            ],
            default => [
                ['min' => 0.0, 'max' => 1.0],
            ]
        };
    }

    private function normalizeQuestionStageGrade(int $grade): ?int
    {
        if ($grade <= 0) {
            return null;
        }

        // 年级转学段 todo：下一步需要视频小学
        return $grade <= 9 ? 2 : 3;
    }

    /**
     * 【新增】获取难度标签（重载版本）
     */
    private function getDifficultyLabelFromObject(?float $difficulty): string
    {
        if ($difficulty === null) return '未知';
        if ($difficulty < 0.3) return '基础';
        if ($difficulty < 0.7) return '中等';
        return '拔高';
    }

    private function buildDifficultyDistributionStats(array $questions, int $difficultyCategory): array
    {
        if (empty($questions)) {
            return [];
        }

        $service = app(DifficultyDistributionService::class);
        $buckets = $service->groupQuestionsByDifficultyRange($questions, $difficultyCategory);
        $total = max(1, count($questions));

        return array_map(static function ($bucket) use ($total) {
            $count = count($bucket);
            return [
                'count' => $count,
                'ratio' => round(($count / $total) * 100, 2),
            ];
        }, $buckets);
    }

    private function buildDifficultyDistributionShortage(array $questions, int $difficultyCategory, int $totalQuestions): array
    {
        $service = app(DifficultyDistributionService::class);
        $distribution = $service->calculateDistribution($difficultyCategory, $totalQuestions);
        $buckets = $service->groupQuestionsByDifficultyRange($questions, $difficultyCategory);

        $expected = [
            'primary_low' => 0,
            'primary_medium' => 0,
            'primary_high' => 0,
            'secondary' => 0,
            'other' => 0,
        ];

        foreach ($distribution as $level => $config) {
            $bucketKey = $service->mapDifficultyLevelToRangeKey($level, $difficultyCategory);
            $expected[$bucketKey] += (int) ($config['count'] ?? 0);
        }

        $actual = array_map(static fn($bucket) => count($bucket), $buckets);
        $shortage = [];

        foreach ($expected as $bucketKey => $count) {
            $actualCount = $actual[$bucketKey] ?? 0;
            $shortage[$bucketKey] = [
                'expected' => $count,
                'actual' => $actualCount,
                'short' => max(0, $count - $actualCount),
            ];
        }

        return $shortage;
    }

    /**
     * 题型感知的难度分布选题
     * 在每种题型内部应用难度分布，确保题型比例和难度分布同时被满足
     */
    private function applyTypeAwareDifficultyDistribution(
        array $allQuestions,
        array $selectedQuestions,
        int $totalQuestions,
        int $difficultyCategory,
        array $questionTypeRatio
    ): array {
        $diffService = app(DifficultyDistributionService::class);
        $distribution = $diffService->calculateDistribution($difficultyCategory, $totalQuestions);

        // 1. 计算每种题型的目标数量
        $ratioMap = ['choice' => '选择题', 'fill' => '填空题', 'answer' => '解答题'];
        $totalRatio = array_sum($questionTypeRatio) ?: 100;
        $typeTargets = [];
        $fractions = [];
        $allocated = 0;

        foreach ($ratioMap as $type => $ratioKey) {
            $ratio = $questionTypeRatio[$ratioKey] ?? 0;
            $exact = $totalQuestions * $ratio / $totalRatio;
            $typeTargets[$type] = (int) floor($exact);
            $fractions[$type] = $exact - floor($exact);
            $allocated += $typeTargets[$type];
        }

        $remainder = $totalQuestions - $allocated;
        arsort($fractions);
        foreach ($fractions as $type => $frac) {
            if ($remainder <= 0) break;
            $typeTargets[$type]++;
            $remainder--;
        }

        // 2. 构建候选题池（合并 allQuestions + selectedQuestions 去重）
        $candidatePool = [];
        $seen = [];
        foreach (array_merge($allQuestions, $selectedQuestions) as $q) {
            $id = $q['id'] ?? null;
            if ($id && !isset($seen[$id])) {
                $seen[$id] = true;
                $candidatePool[] = $q;
            }
        }

        // 3. 按题型分组候选题
        $candidatesByType = ['choice' => [], 'fill' => [], 'answer' => []];
        foreach ($candidatePool as $q) {
            $qType = $q['question_type'] ?? '';
            if (isset($candidatesByType[$qType])) {
                $candidatesByType[$qType][] = $q;
            }
        }

        // 4. 在每种题型内按难度分桶选题
        $result = [];
        $usedIds = [];
        $typeActual = [];

        foreach ($ratioMap as $type => $ratioKey) {
            $target = $typeTargets[$type];
            if ($target <= 0) {
                $typeActual[$type] = 0;
                continue;
            }

            $typeCandidates = $candidatesByType[$type];
            $buckets = $diffService->groupQuestionsByDifficultyRange($typeCandidates, $difficultyCategory);

            // 按 distribution 比例在该题型内选题
            $typeSelected = [];
            foreach ($distribution as $level => $config) {
                $levelRatio = $config['percentage'];
                $levelTarget = max(0, (int) round($target * $levelRatio / 100));
                if ($levelTarget <= 0) continue;

                $rangeKey = $diffService->mapDifficultyLevelToRangeKey($level, $difficultyCategory);
                $bucket = $buckets[$rangeKey] ?? [];
                shuffle($bucket);

                $taken = 0;
                foreach ($bucket as $q) {
                    if ($taken >= $levelTarget) break;
                    $qid = $q['id'] ?? null;
                    if ($qid && !isset($usedIds[$qid])) {
                        $typeSelected[] = $q;
                        $usedIds[$qid] = true;
                        $taken++;
                    }
                }
            }

            // 如果难度分布不满足目标数，从该题型剩余题目补充
            if (count($typeSelected) < $target) {
                $allTypeBuckets = array_merge(
                    $buckets['primary_medium'] ?? [],
                    $buckets['primary_low'] ?? [],
                    $buckets['primary_high'] ?? [],
                    $buckets['secondary'] ?? [],
                    $buckets['other'] ?? []
                );
                shuffle($allTypeBuckets);
                foreach ($allTypeBuckets as $q) {
                    if (count($typeSelected) >= $target) break;
                    $qid = $q['id'] ?? null;
                    if ($qid && !isset($usedIds[$qid])) {
                        $typeSelected[] = $q;
                        $usedIds[$qid] = true;
                    }
                }
            }

            $typeActual[$type] = count($typeSelected);
            $result = array_merge($result, $typeSelected);
        }

        // 5. 如果总数不足（某题型候选不够），跨题型补充
        if (count($result) < $totalQuestions) {
            $deficit = $totalQuestions - count($result);
            // 按 fill > choice > answer 优先级补充
            $supplementOrder = ['fill', 'choice', 'answer'];
            foreach ($supplementOrder as $type) {
                if ($deficit <= 0) break;
                $bucket = $candidatesByType[$type];
                shuffle($bucket);
                foreach ($bucket as $q) {
                    if ($deficit <= 0) break;
                    $qid = $q['id'] ?? null;
                    if ($qid && !isset($usedIds[$qid])) {
                        $result[] = $q;
                        $usedIds[$qid] = true;
                        $deficit--;
                    }
                }
            }
        }

        Log::info('LearningAnalyticsService: 题型感知难度分布详情', [
            'type_targets' => $typeTargets,
            'type_actual' => $typeActual,
            'total_result' => count($result),
            'difficulty_category' => $difficultyCategory,
            'candidates_by_type' => array_map('count', $candidatesByType),
        ]);

        return array_slice($result, 0, $totalQuestions);
    }

    /**
     * 统计题目列表中各题型的数量
     */
    private function countByType(array $questions): array
    {
        $counts = ['choice' => 0, 'fill' => 0, 'answer' => 0];
        foreach ($questions as $q) {
            $type = $q['question_type'] ?? '';
            if (isset($counts[$type])) {
                $counts[$type]++;
            }
        }
        return $counts;
    }

    private function buildDistributionCandidates(array $allQuestions, array $selectedQuestions, int $difficultyCategory): array
    {
        if (empty($allQuestions)) {
            return $selectedQuestions;
        }

        $service = app(DifficultyDistributionService::class);
        $distribution = $service->calculateDistribution($difficultyCategory, max(1, count($selectedQuestions)));
        $buckets = $service->groupQuestionsByDifficultyRange($allQuestions, $difficultyCategory);

        $preferredBuckets = [];
        foreach ($distribution as $level => $config) {
            $bucketKey = $service->mapDifficultyLevelToRangeKey($level, $difficultyCategory);
            $preferredBuckets[$bucketKey] = true;
        }

        $candidates = [];
        foreach (array_keys($preferredBuckets) as $bucketKey) {
            foreach ($buckets[$bucketKey] ?? [] as $q) {
                $candidates[] = $q;
            }
        }

        foreach ($selectedQuestions as $q) {
            $candidates[] = $q;
        }

        $seen = [];
        $unique = [];
        foreach ($candidates as $q) {
            $id = $q['id'] ?? null;
            if (!$id || isset($seen[$id])) {
                continue;
            }
            $seen[$id] = true;
            $unique[] = $q;
        }

        return $unique;
    }
}