학생·기수·활동 지정

요청은 아발론 원문의 필드명과 평면 구조를 사용합니다. 학생·기수·활동을 별도 객체로 묶지 않으며, 플랭 활동 ID는 보내지 않습니다.

아발론 원문	요청 필드	의미
memIdx	memIdx	학생 고유 ID. 앞자리 0을 보존하는 문자열
regYear	regYear	기수 연도
season	season	1: 봄, 2: 여름, 3: 가을, 4: 겨울
studyType	studyType	학습 유형
level	level	교재 레벨이자 해당 기수의 OrgGroupSet 식별 코드
layer	layer	교재 레이어이자 해당 OrgGroupSet의 OrgGroup 식별 코드
unitCd	unitCd	아발론 단원 코드. 순서·숫자 의미가 없는 1~50자 문자열
regYm	regYm	학습이 귀속되는 월, YYYYMM

regYm은 실제 학습을 수행한 날짜와 구분합니다. 예를 들어 9월 귀속 학습을 10월에 수행했다면 교재 귀속 월은 9월이고 실제 학습일은 10월입니다. 기수는 전달받은 연도·season을 사용하며 서버가 달력 분기에서 추정하지 않습니다.

6개 값으로 활동을 찾습니다

studyType + level + layer + unitCd + regYear + season 조합 하나가 아발론 활동 하나입니다. 플랭은 이 조합을 대응표에서 찾아 학습할 플랭 활동을 정합니다. 등록된 조합은 활동 목록 CSV에서 확인합니다.

• 6개 값 중 하나라도 다르면 다른 활동입니다. 같은 단원이라도 regYear·season이 다르면 새 활동처럼 처음부터 시작합니다.
• unitCd는 원문 문자열 그대로 비교합니다. "3"과 "03"은 다른 단원 코드입니다. 앞뒤 공백도 그대로 비교하므로 넣지 않습니다.
• 대응표에 없는 조합은 404 CONTAINER_NOT_FOUND로 거절하며 학생·그룹을 만들지 않습니다.
• 조합 하나는 플랭 활동 하나에 연결되며, 한 플랭 활동을 여러 조합이 함께 쓰지 않습니다.

기수별 그룹 생성 규칙

그룹은 아발론 조직 → regYear·season 기수(OrgGroupSetBundle) → level(OrgGroupSet) → layer(OrgGroup) 순서로 구분합니다.

요청 예시	처리
2026 / season 3 / MA / RED 첫 요청	해당 기수에 MA 그룹 세트와 그 아래 RED 그룹 생성
2026 / season 3 / MA / RED 재요청	기존 MA 그룹 세트·RED 그룹 재사용
2026 / season 4 / MA / RED	새 기수에 별도의 MA 그룹 세트·RED 그룹 생성
2027 / season 4 / MA / RED	연도가 다르므로 새 기수에 별도 생성

같은 기수라도 level이 다르면 서로 다른 그룹 세트이며, 같은 이름의 layer도 각 그룹 세트 안에서 별도로 관리합니다. 귀속 월·단원 코드·학습 유형만 바뀌면 그룹을 새로 만들지 않습니다. 새 기수 생성 시 이전 기수의 그룹이나 학습 결과를 덮어쓰지 않습니다. 같은 학생은 한 기수 안에서 level·layer가 고정이며, 같은 기수에 다른 level·layer로 요청하면 409 LEARNING_CONTEXT_CONFLICT입니다.

학습 유형 코드

요청 studyType	결과 유형
RA / IBTRA	RA 읽기 평가
WR / IBTW	WR 쓰기 평가
SP / IBTS	SP 말하기 평가

결과 응답의 studyInfo.studyType은 요청 코드를 그대로 유지합니다. 예를 들어 IBTS 요청은 IBTS로 응답하며, 결과 필드 구조는 SP와 같습니다. IBT도 활동 하나에 한 유형만 들어갑니다. 1차 지원 코드는 위 6개로 확정하며 TT는 지원하지 않습니다. 학습 모드는 사전 연동 설정으로 명시합니다.

현재 테스트 환경의 지원 범위

• RA·WR·SP만 진입할 수 있습니다. IBTRA·IBTW·IBTS는 대응하는 플랭 활동 유형을 준비 중이며, 지금은 422 UNSUPPORTED_TASK로 거절합니다.
• RA는 읽기 V3 활동만 받습니다. 이전 형식(V2) 활동은 UNSUPPORTED_TASK로 거절하며 플랭이 V3로 전환한 뒤 대응표에 넣습니다.
• 지원하지 않는 studyType(TT 등)은 422 UNSUPPORTED_TASK로 거절합니다.

학습 기록은 학생 × 활동마다 하나입니다

학습 기록은 학생(memIdx) × 활동(6개 값 조합) 마다 하나입니다. 아발론이 순서나 회차 번호를 보낼 필요는 없습니다.

요청	처리
학생 A·활동 X 첫 요청	학습 기록을 만들고 시작
같은 활동을 다시 요청, 아직 제출 전	이어하기
같은 활동을 다시 요청, 이미 제출 완료	완료 화면과 다시 해보기 버튼
완료 화면에서 다시 해보기	같은 활동의 새 회차를 빈 답안으로 시작. 이전 회차 결과는 보존
학생 A·활동 Y 첫 요청	X와 독립적으로 시작. X가 미완료여도 막지 않음
학생 B·활동 X 첫 요청	A와 독립적으로 시작

다시 해보기로 생긴 회차는 결과 조회의 attemptNumber로 구분합니다(학습 상태와 결과 조회). 정산은 학생 × 활동당 1건이며 회차에는 과금하지 않습니다(학습이력 조회). 같은 문장의 재녹음 횟수(attemptIndex)와는 별개입니다.

이어하기는 그 회차를 시작할 때의 귀속 월(regYm)을 유지합니다. 제출 전인 학습을 다른 regYm으로 다시 요청하면 409 LEARNING_CONTEXT_CONFLICT로 거절하며 기존 기록을 덮어쓰지 않습니다. 다시 해보기로 시작한 새 회차는 완료 화면을 연 진입 코드의 regYm을 사용합니다.

동일 학생의 새 실행이 성공하면 이전 창은 중복 실행 정책에 따라 만료됩니다.