학습 상태와 결과 조회

활동 하나는 RA·WR·SP 중 한 유형입니다. 하나의 학습 차시를 조회하면 그 유형의 결과 객체 하나를 반환합니다. 별도의 하위 활동 목록이나 하위 활동 ID를 거쳐 결과를 다시 조회하는 단계는 없습니다.

GET /integrations/v1/learning-runs/:learningRunId

아발론 서버가 서버 전용 키로 호출합니다. URL 발급 응답의 data.learningRunId를 저장해 결과 조회에 사용합니다. 완료 후 재수행하면 새 ID가 발급되며 이전 ID로는 이전 차시 결과를 조회합니다. 요청의 studyType은 선택한 활동의 실제 유형과 일치해야 합니다.

원문 응답 구조

위치	필드	의미
최상위	success, regDate, data	원문의 응답 틀 유지. regDate는 응답 생성 시각
data	studyInfo	원문의 studyType, memIdx, level, layer, unitCd, regYear, season, regYm 유지
data	studyStatus	문자열 "0": 학습 전, "500": 학습 중, "1100": 학습 완료
data	유형별 결과 필드	totalScore, accuracy, fluency, sentences, originalEssay, rubrics 등 해당 유형의 원문 필드를 같은 깊이에 배치
data	studyDate	마지막 학생 학습 시각. 분석·교사 수정 시각과 구분

data.results[], data.activities[], data.result처럼 결과를 다시 감싸는 계층은 추가하지 않습니다. regDate·studyDate는 원문과 같은 YYYY-MM-DD HH:mm:ss 형식의 한국시간이며, 학습 전 studyDate는 null입니다.

원문에 추가하는 필드 제안

필드	위치	필요한 이유
learningRunId	URL 발급·결과 응답의 data	동일 교재 학습의 재수행 결과 구분
runNumber	URL 발급·결과 응답의 data	해당 학습의 수행 순번. 교재 회차 unitCd와 구분
launchUrl, expiresAt	URL 발급 응답의 data	일회용 실행 URL과 사용기한. expiresAt은 시간대가 있는 ISO 8601
resultStatus	결과 응답의 data	학습 완료와 분석 준비 상태 구분
resultRevision	결과 응답의 data	재분석·교사 수정에 따른 결과 변경 구분
unavailableReason	결과 응답의 data	결과 미준비·실패·공개 제한 사유. 정상 준비 시 null

이 확장 필드는 신규 연동에 필요한 제안이며 아발론 원문에 있던 필드와 구분합니다. URL 발급 요청의 class_task_id도 추가 필드입니다.

resultStatus	의미
not_started	결과 생성 전
processing	분석 진행 중
ready	결과 준비 완료
failed	분석 실패
withheld	시험 등 결과 공개 제한

제출은 완료됐지만 분석 중인 WR 응답 예시입니다. 실제 점수 예시가 아니라 응답 구조 예시입니다.

{
  "success": true,
  "regDate": "2026-09-14 10:20:05",
  "data": {
    "studyInfo": {
      "studyType": "WR",
      "memIdx": "001234567",
      "level": "MA",
      "layer": "RED",
      "unitCd": "1",
      "regYear": "2026",
      "season": "3",
      "regYm": "202609"
    },
    "studyStatus": "1100",
    "learningRunId": "example-run-id",
    "runNumber": 1,
    "resultStatus": "processing",
    "resultRevision": 1,
    "unavailableReason": "analysis_in_progress",
    "totalScore": null,
    "topic": null,
    "originalEssay": null,
    "correctedEssay": null,
    "mission": null,
    "grammarCorrections": null,
    "rubrics": null,
    "comment": null,
    "studyDate": "2026-09-14 10:20:00"
  }
}

분석 전·진행 중·실패·공개 제한 상태에서도 studyInfo와 studyStatus는 반환하고, 답안·음원·점수 등 유형별 결과 필드는 null로 반환하는 안입니다. ready일 때는 해당 유형의 결과를 채웁니다. 확인된 빈 목록은 []이며, 미준비를 빈 목록이나 0점으로 표현하지 않습니다. 미지원 평가축은 ready 상태에서도 계약에 따라 null일 수 있습니다. 아발론의 전체 종합 코멘트는 필수 제공 항목이므로 ready 상태에서는 comment가 비어 있지 않은 문자열로 반환됩니다.

분석 중에는 일정 간격으로 재조회하고 실패·공개 제한을 무한 대기와 구분합니다. 재조회 간격·상한과 오류 코드는 최종 명세에서 확정합니다. HTTP 호출 성공 여부인 success와 학습/분석 성공 여부는 별개입니다.

유형별 원문 필드

아래 결과 필드는 모두 data 바로 아래에 있습니다. 필드 이름과 배열·객체 구조는 전달받은 Word 문서를 기준으로 합니다.

유형	결과 필드
RA	totalScore, accuracy, fluency, sentences[], comment, studyDate
WR	totalScore, topic, originalEssay, correctedEssay, mission[], grammarCorrections[], rubrics, comment, studyDate
SP	totalScore, topic, round, recordings[], mission[], grammarCorrections[], rubrics, comment, studyDate

하위 객체	원문 필드
accuracy	score, stars, goodCount, normalCount, badCount, totalWords, goodRatio, normalRatio, badRatio
fluency	score, stars, wpm, wpmStars, wpmComment, hesitationAvgSec, hesitationStars, hesitationComment
sentences[]	sentenceIndex, currentAttempt, maxAttempt, accuracyScore, accuracyStars, fluencyScore, fluencyStars, studentAudioUrl, nativeAudioUrl, tokens[]
sentences[].tokens[]	startIdx, endIdx, word, status
recordings[]	audioIndex, audioUrl, sttTranscript
mission[]	title, basis, achievementRate, isPassed
grammarCorrections[]	correctYn, originalSentence, wrongToken, correctedToken, correctedSentence, feedback
rubrics	평가축 코드를 키로 갖는 객체. 각 값은 score, strengths[], improvements[]

WR의 루브릭 키는 원문의 TOPIC_RELEVANCE, ORGANIZATION, SUPPORT, VOCABULARY, GRAMMAR에 실제 아발론 평가 기준을 매핑합니다. SP는 FLUENCY, PRONUNCIATION, VOCABULARY, TOPIC_RELEVANCE, GRAMMAR이며 음성 평가가 필요한 두 축의 제공 가능성은 학습 결과 제공 범위에 명시합니다. 임의로 기존 점수 이름을 바꾸어 채우지 않습니다.