연동 준비 및 확인 사항

확정된 연동 정책을 기준으로 개발을 준비합니다. 기술 명세와 운영 설정은 플랭이 정해 안내하며, 아발론과 함께 확인할 사항은 담당자·키 전달·연동 테스트입니다.

테스트 환경

항목	내용
학습 진입	`POST https://avalon-stg.plang.ai/integrations/v1/entry`
조회 API 주소	`https://avalon-stg.plang.ai/integrations/v1/` (`class-tasks.csv`, `learning-history`)
암호화	`alg=dir`, `enc=A256GCM`, `kid=stg-2026a`, `iss=avalon`, `aud=plang-stg`
전달하는 값	진입 암호화 키, 조회 API 키(`plk_…`), 진입 데모 계정. 문서에 싣지 않고 보안 경로로 따로 전달합니다.
진입 데모	`https://avalon-stg.plang.ai/integrations/v1/demo/entry` — 아발론 서버 없이 학생·활동(대응표 항목)·귀속 월을 골라 진입 코드를 만들고 학습 창을 열어 볼 수 있습니다. 테스트 환경에만 있습니다.
테스트 활동	활동 CSV로 확인합니다. 테스트 학생 ID는 자유롭게 정하되 실제 학생 정보를 쓰지 않습니다.
열린 기능	학습 진입·실행 권한 만료·중복 실행 교체, 활동 CSV, 학습이력 조회(정산)
준비 중	결과 조회 API, IBT 코드(IBTRA·IBTW·IBTS)

항목	안내할 내용
암호화 명세	확정: 암호화 규약. 언어 간 테스트 벡터는 요청 시 제공
접속 환경	테스트 확정(위 표), 운영 주소는 개통 시 안내. 실행 권한 수명은 4시간
API 운영 기준	경로·요청/응답 스키마·오류 코드, 호출량 제한, 재조회 간격·상한
결과 처리 기준	학습 상태와 분석 상태 구분, 미준비·실패·공개 제한 및 null 처리 규칙

문서에 정의된 정책을 바탕으로 구현·검증한 명세를 제공합니다. 진입 암호화 규약과 운영 수치는 확정했으며, 결과 조회 API의 재조회 간격·상한은 개통 시 함께 안내합니다.

항목	함께 확인할 내용
키 전달	키를 전달받을 개발 담당자와 보안 전달 경로
테스트 일정	테스트 담당자·일정과 양쪽 환경 준비 여부
구현 호환성	동일한 테스트 벡터로 암호화·복호화 확인, 실제 학습 진입·제출·결과 조회 및 오류 응답 처리 확인

항목	확인할 내용
대상 활동	지원 코드와 실제 단일 활동 연결, 학습 모드 설정, 활동 CSV 검증
RA 표시·음원	originalText와 UTF-16 인덱스 일치, 원어민 음원 기본 속도 설정
루브릭	아발론 제공 항목과 외부 평가축 연결, 개별 점수 정의와 평가 제외 항목 검증
결과 일관성	점수 수정·재평가 시 개별 평가 결과 반영, 결과 공개 제한과 준비 상태 검증

암호화 코드 form POST로 6개 값이 가리키는 활동에 진입합니다. 완료한 활동은 완료 화면에서 다시 해보기로 새 회차를 시작하며, 동일 학생의 최신 실행만 유지합니다.
지원 코드는 RA/WR/SP/IBTRA/IBTS/IBTW입니다. TT와 SP 응답의 round는 제외합니다.
RA는 문장별 전체 attempts와 totalAttempt를 반환합니다. 정수 인덱스·다섯 소수 필드의 문자열 표현 및 기존 RAV3 최고점 집계 기준을 적용합니다.
WR·SP의 totalScore는 응답에서 제외하며 신규 계산·저장을 하지 않습니다. 개별 루브릭 점수와 종합 코멘트는 계속 제공합니다. RA의 기존 종합 점수는 유지합니다.
SP 발음·유창성은 1차 평가에서 제외합니다. FLUENCY/PRONUNCIATION의 score/strengths/improvements는 null로 제공하며, 음성 평가 도입은 추후 검토합니다.
미션은 title/basis/isPassed만 제공하고 achievementRate는 제외합니다. grammarCorrections에는 틀린 문장만 포함합니다.

이 문서는 개발 명세입니다. 개통 상태는 위 테스트 환경 표를 기준으로 합니다.