opic/docs/PLAN.md

OPIc Flow 구현 계획

1. 제품 목표

사용자가 난이도와 설문 주제를 선택하면 실제 OPIc 흐름에 가까운 15문항을 음성으로 듣고 영어로 답한다. 각 답변은 즉시 전사·평가되며, 시험 종료 후 전체 평가를 첫 장으로 하고 문항별 점수·키워드·개선점을 포함하는 보고서를 제공한다.

점수와 추정 등급은 공식 OPIc 성적이 아닌 학습용 지표로 명확히 표시한다.

2. 시험 구성

1. 자기소개 1문항
2. 선택 주제 묘사·일상·과거 경험 6문항
3. 롤플레이 3문항
4. 돌발 주제 2문항
5. 비교·의견·미래 예측 3문항

총 15문항이며 난이도에 따라 질문의 추상성, 요구 근거 수, 후속 조건을 조정한다.

3. 상태 흐름

Setup → Device check → Question → Listening → Recording → Transcribing → Evaluating → Next question → Final report

세션 상태는 Go 백엔드가 권위 있게 관리한다. 프런트엔드는 현재 문항보다 앞선 문항을 임의 제출할 수 없다.

4. AI 파이프라인

현재 MVP

• 질문 음성: Web Speech Synthesis
• 사용자 음성: MediaRecorder(WebM/Opus)
• 전사: POST /v1/audio/transcriptions
• 평가: POST /v1/responses, strict JSON Schema
• 다음 질문: 사전 구성된 OPIc 블루프린트

사전 구성 질문을 사용하면 AI가 시험 범위를 벗어나거나 문항 수를 잘못 생성하는 문제를 막을 수 있다. 답변 내용은 다음 문항을 고를 때 분기 조건으로 사용하도록 확장한다.

Realtime 2단계

• Wails Go 백엔드가 표준 API 키로 /v1/realtime/calls에 SDP를 전달한다.
• Vue WebView는 RTCPeerConnection으로 마이크 트랙과 oai-events 데이터 채널을 구성한다.
• server_vad 또는 semantic_vad로 발화 종료를 감지한다.
• input_audio_transcription 이벤트로 실시간 자막을 표시한다.
• 모델 음성 출력은 원격 audio track으로 재생한다.
• 문항 종료마다 별도의 Responses API 평가를 수행해 점수 JSON을 확정한다.

Realtime 모델이 대화를 자연스럽게 진행하더라도 시험 문항 인덱스와 최대 15문항 제한은 앱 상태 머신이 통제해야 한다.

5. 평가 기준

각 문항 100점:

• 과업 수행 25
• 구체성·내용 전개 20
• 구성·연결 15
• 어휘 다양성 15
• 문법 정확성 15
• 유창성·답변 길이 10

오디오 기반 고도화 시 말하기 속도, 긴 침묵, filler, 반복, 자기 수정도 별도 feature로 저장한다. transcript만으로 발음 점수를 단정하지 않는다.

6. 보고서

첫 장:

• 전체 평균 점수
• 연습용 추정 등급
• 핵심 강점 3개
• 우선 개선 과제 3개
• 다음 세션 권장 난이도·주제

문항별:

• 질문과 답변 transcript
• 0–100 점수
• 핵심 키워드
• 잘한 점
• 개선점
• 개선된 예시 답변(후속 단계)

내보내기:

• 1차: 브라우저 인쇄/PDF
• 2차: Go PDF 생성 및 세션 JSON/오디오 내보내기

7. 인증과 보안

• ChatGPT 웹 로그인/구독은 API 인증으로 재사용하지 않는다.
• 개인용 MVP: 사용자가 Platform API 키를 입력하며 메모리에만 유지한다.
• 배포용: 앱에 공용 API 키를 포함하지 않는다. 자체 백엔드에서 사용자 로그인, 사용량 제한, ephemeral Realtime 인증을 처리한다.
• 장기 로컬 저장이 필요하면 Windows Credential Manager/macOS Keychain/libsecret을 사용한다.
• 오디오는 기본적으로 평가 후 폐기하고, 사용자가 명시적으로 저장을 선택한 경우에만 로컬 암호화 저장한다.

8. 단계별 로드맵

Phase 1 — 현재

• Wails/Vue 앱 골격
• 설정·시험·보고서 UI
• 15문항 상태 머신
• 녹음, 전사, 구조화 평가
• 데모 모드

Phase 2

• Realtime API WebRTC
• VAD, 실시간 자막, 모델 음성, 끼어들기
• 답변 특징에 따른 제한된 후속 질문 분기
• 마이크/스피커 사전 점검

Phase 3

• SQLite 세션 기록
• 오디오 파형과 침묵/filler 분석
• 개선 답변 생성과 쉐도잉
• PDF/JSON 내보내기

Phase 4

• 사용자 계정과 서버 측 API 프록시
• 기기 간 동기화
• 평가 prompt/eval 데이터셋 및 회귀 테스트
• 비용·속도·품질 관측 대시보드

9. 검증 계획

• 질문 수와 순서 상태 머신 단위 테스트
• 점수 스키마 0–100 경계 테스트
• 빈 오디오, 마이크 거부, API 401/429/5xx 오류 테스트
• 25MB 오디오 업로드 제한 전 사전 차단
• 세션 완료 전 보고서 접근 차단
• 난이도별 대표 transcript를 사용한 평가 회귀 테스트