1) 엔드포인트 설계 (REST)

1. 로드맵 CRUD

• GET /students/{studentId}/roadmaps

  • 설명: 학생별 로드맵 목록
  • 응답: [{ roadmapId, createdAt, itemCount }]

• POST /students/{studentId}/roadmaps

  • 설명: 빈 로드맵 생성 또는 자동 생성

  • 요청(JSON)

    {
      "mode": "empty | from_recommendations | from_degree_gap | mixed",
      "options": {
        "careerLimit": 3,
        "courseLimit": 6,
        "useLatestSession": true,
        "simulationId": null}
    }
    
    

  • 응답: { roadmapId }

• GET /roadmaps/{roadmapId}

  • 설명: 로드맵 상세(단계 포함)

  • 응답:

    {
      "roadmapId": 12,
      "studentId": 7,
      "createdAt": "2025-08-11T08:10:00Z",
      "items": [
        {"stepOrder":1,"itemType":"career","itemId":10,"name":"데이터 엔지니어"},
        {"stepOrder":2,"itemType":"course","itemId":202,"name":"자료구조(3학점)"}
      ]
    }
    
    

• DELETE /roadmaps/{roadmapId}

  • 설명: 로드맵 삭제

2. 로드맵 단계 관리

• POST /roadmaps/{roadmapId}/items (배치 추가)

  • 요청(JSON):

    {
      "items": [
        {"itemType":"career","itemId":10},
        {"itemType":"course","itemId":202},
        {"itemType":"course","itemId":305}
      ],
      "insertAt": 1   // 선택: 삽입 시작 위치(없으면 맨 뒤)
    }
    
    

• PUT /roadmaps/{roadmapId}/items/{stepOrder}

  • 설명: 단일 단계 교체/수정(예: course → career 교체)
  • 요청(JSON): {"itemType":"course","itemId":205}

• DELETE /roadmaps/{roadmapId}/items/{stepOrder}

• PUT /roadmaps/{roadmapId}/items/reorder

  • 설명: 단계 순서 재배치

  • 요청(JSON):

    { "newOrder": [3,1,2,4] } // stepOrder들의 새로운 순서
    
    

3. 추천·시뮬레이션 보조 API

• GET /students/{studentId}/recommendations?type=career|course&limit=10
  • 설명: 통합 추천(Recommendations) 조회
• POST /students/{studentId}/simulations
  • 설명: 졸업 시뮬레이션 실행(GraduationSimulations 생성 → 백엔드에서 SimulationOutcomes 채움)
  • 요청(JSON): {"major":"컴퓨터공학"} (선택. 없으면 Students.major 사용)
  • 응답: { "simulationId": 33, "status": "pending|completed" }
• GET /students/{studentId}/degree-gap?simulationId=33

  • 설명: SimulationOutcomes 기준 부족 학점/필수 과목 반환

  • 응답:

    {
      "major": "컴퓨터공학",
      "requirements": [
        {"requirementId":1,"category":"core","courseId":101,"fulfilled":false,"neededCredits":3},
        {"requirementId":2,"category":"elective","courseId":null,"neededCredits":6}
      ],
      "summary": {"coreLeft":3,"electiveLeft":6}
    }