QnA¶

1. 한 줄 정의¶

학생 질문 ↔ 선생님(또는 AI) 답변 스레드. 컨텍스트별 메시지 누적 + teams/engineering/concepts/사고력-답변구조 통합으로 AI 힌트가 메시지 단위에 actor=AI로 결합된다.

2. 핵심 개념¶

QnaContext — 질문 스레드 + aiStatus, selectedAnswer (v0.2)
QnaMessage — 스레드 내 메시지 (actor: STUDENT/TEACHER/AI, hintLevel deprecated, turnIndex v0.2 신규)
StudentContext — 학생당 1행. strengths·weaknesses deprecated, difficulties v0.2 신규
AiTokenUsage — 호출당 token/cost 기록
TeacherFeedback — 메시지 단위 선생님 댓글
AiPromptTemplate — hint.level1~5 deprecated, conversation.system·conversation.turn v0.2 신규 시드
AiSatisfactionRating (v0.2 신규) — 대화 종료 시 5점 + 자유 의견 수집

3. 관련 코드¶

기존
mvp-back/src/main/java/com/example/demo/domain/qna/ — QnaContext, QnaMessage, QnaStatus, QnaVisibility, QnaSortType, QnaContextView, QnaEvents, QnaRepository
mvp-back/.../application/service/qna/QnaService
mvp-back/.../presentation/controller/qna/QnaController + DTOs 10개
mvp-back/.../infrastructure/persistence/repository/qna/
mvp-front/src/app/(private)/qna
추가 예정 — 구현 명세는 mvp-back:docs/frd/사고력-답변구조/spec (Backend) + mvp-front:docs/frd/사고력-답변구조/spec (Frontend) 에서 관리

4. API 표면¶

구현 명세는 mvp-back:docs/frd/사고력-답변구조/spec §3 + Frontend는 mvp-front:docs/frd/사고력-답변구조/spec §3 참조. 주요 path 6개: - POST /api/student/qna/{contextId}/ai-hint — 다음 hintLevel AI 답변 - GET·PUT /api/student/me/context — StudentContext CRUD - GET /api/teacher/studyrooms/{id}/ai-inbox — 정렬 미해결 → 미완료 → 해결 완료 - GET /api/teacher/qna/{contextId}/ai-log — 전체 로그 (actor 포함) - POST /api/teacher/qna/messages/{messageId}/feedback — 단계별 댓글

(기존 QnA CRUD는 컨트롤러 그대로 유지, path만 추가)

5. 상태/생명주기¶

QnaContext.status:    open → answered → closed (soft delete 가능)
QnaContext.aiStatus:  NONE → IN_PROGRESS → RESOLVED
QnaMessage.actor:     STUDENT | TEACHER | AI

aiStatus는 선생님 AI Inbox 정렬 키. RESOLVED는 학생이 명시적 닫기 또는 선생님 피드백 완료로 전환.

6. 외부 의존¶

S3 (첨부)
LLM provider (Anthropic Claude 잠정) — teams/engineering/concepts/사고력-답변구조 의존
member.studyroom 관계 (선생님 AI Inbox 권한 경계)

7. UI 노출¶

기존: QnA 리스트 / 상세 — mvp-front/src/app/(private)/qna
추가:
QnA 상세에 "디에듀 AI 힌트" 버튼 + 단계 카드
학생 컨텍스트 입력 페이지 (/student/me/context)
선생님 AI Inbox (/teacher/studyrooms/{id}/ai-inbox)
메시지 단위 인라인 피드백 댓글

8. 결정 이력¶

teams/engineering/concepts/사고력-답변구조 §4 채택 (2026-05-20) — v0.1 단계형 힌트
ADR-0009 (2026-05-21) — v0.2 채택, 단계형 → 대화형 사고 유도 + 학생 직접 답 선택 + 만족도 수집
teams/engineering/concepts/사고력-답변구조-v0.2 (현행) — v0.2 추상
(예정) ADR-0006 LLM provider, ADR-0007 프롬프트 저장 위치

9. 열린 질문 / TODO¶

AI 답변 첫 토큰 < 3초 목표 — 스트리밍을 1차에서 도입할지 2차로 미룰지 (현재 2차)
QnaContext.aiStatus 자동 전환 규칙 (시간 경과? 학생 명시?)
분당 10건 레이트 리밋 적용 위치 (API gateway vs 컨트롤러 어노테이션)