math_cms/app/Http/Controllers/Api/KnowledgeMasteryController.php

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Services\KnowledgeMasteryService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

/**
 * 知识点掌握情况 API 控制器
 *
 * 提供：
 * 1. 获取学生知识点掌握情况统计
 * 2. 获取知识点图谱数据（考试快照）
 * 3. 获取知识点图谱快照列表
 */
class KnowledgeMasteryController extends Controller
{
    protected KnowledgeMasteryService $service;

    public function __construct(KnowledgeMasteryService $service)
    {
        $this->service = $service;
    }

    /**
     * 获取学生知识点掌握情况统计
     *
     * GET /api/knowledge-mastery/stats/{studentId}
     *
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function stats(string $studentId): JsonResponse
    {
        $result = $this->service->getStats($studentId);

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '获取知识点掌握情况失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'data' => $result['data'],
        ]);
    }

    /**
     * 获取学生知识点掌握摘要（简化版）
     *
     * GET /api/knowledge-mastery/summary/{studentId}
     *
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function summary(string $studentId): JsonResponse
    {
        $result = $this->service->getSummary($studentId);

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '获取知识点掌握摘要失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'data' => $result['data'],
        ]);
    }

    /**
     * 获取学生知识点图谱数据
     *
     * GET /api/knowledge-mastery/graph/{studentId}
     *
     * @param Request $request
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function graph(Request $request, string $studentId): JsonResponse
    {
        $examId = $request->query('exam_id');

        $result = $this->service->getGraph($studentId, $examId);

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '获取知识点图谱失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'data' => $result['data'],
        ]);
    }

    /**
     * 获取学生知识点图谱快照列表
     *
     * GET /api/knowledge-mastery/graph/snapshots/{studentId}
     *
     * @param Request $request
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function graphSnapshots(Request $request, string $studentId): JsonResponse
    {
        $limit = (int) $request->query('limit', 10);

        $result = $this->service->getGraphSnapshots($studentId, $limit);

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '获取知识点图谱快照列表失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'data' => $result['data'],
        ]);
    }

    /**
     * 获取学生知识点快照列表（简化路径）
     *
     * GET /api/knowledge-mastery/snapshots/{studentId}
     *
     * @param Request $request
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function snapshots(Request $request, string $studentId): JsonResponse
    {
        $limit = (int) $request->query('limit', 10);

        $result = $this->service->getGraphSnapshots($studentId, $limit);

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '获取知识点快照列表失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'data' => $result['data'],
        ]);
    }

    /**
     * 创建知识点掌握度快照
     *
     * POST /api/knowledge-mastery/snapshot/{studentId}
     *
     * @param Request $request
     * @param string $studentId 学生ID
     * @return JsonResponse
     */
    public function createSnapshot(Request $request, string $studentId): JsonResponse
    {
        $snapshotType = $request->input('snapshot_type', 'report');
        $sourceId = $request->input('source_id');
        $sourceName = $request->input('source_name');
        $notes = $request->input('notes');

        $result = $this->service->createSnapshot(
            $studentId,
            $snapshotType,
            $sourceId,
            $sourceName,
            $notes
        );

        if (!$result['success']) {
            return response()->json([
                'success' => false,
                'message' => $result['error'] ?? '创建知识点掌握度快照失败',
            ], 500);
        }

        return response()->json([
            'success' => true,
            'message' => '快照创建成功',
            'data' => $result['data'],
        ]);
    }
}