docs: 피드백 실패 영속 마커 스펙 반영

database.md interview_sessions V29 컬럼, api-conventions §5 FEEDBACK_*
카탈로그(기존 3종 누락 정정 + GENERATION_FAILED), event-stream §4 폴링
fallback 의 실패 구분, messaging §5.11 Core 마커 영속화 서술.

Author: Jaeho-Site

docs/api-conventions.md

@@ -245,6 +245,12 @@ SESSION_MAX_REACHED         422  최대 질문/시간 도달
 SESSION_NOT_FOUND           404
 SESSION_FORBIDDEN           403  타인 세션 접근
 
+# 피드백 (FEEDBACK_*)
+FEEDBACK_NOT_READY          404  아직 생성 중 (폴링/SSE 대기 지속)
+FEEDBACK_GENERATION_FAILED  404  생성 실패 마커 존재 — 대기 중단, 재생성 유도. details.retriable(boolean) 동봉
+FEEDBACK_NOT_FOUND          404  공유 토큰 무효
+FEEDBACK_ALREADY_EXISTS     409  재생성 요청 시 이미 존재 (재조회 신호)
+
 # 시스템 (SYS_*)
 SYS_RATE_LIMITED            429
 SYS_DEPENDENCY_DOWN         503  RabbitMQ/AI/LLM 다운

docs/database.md

@@ -171,6 +171,10 @@ CREATE TABLE interview_sessions (
     target_job_description TEXT,
     resumed_at             TIMESTAMPTZ,               -- 이어하기로 재개한 시각. 시간 한도를 이 값 기준으로 다시 잰다(V27)
     focus_areas            JSONB,                     -- 약점 집중 재도전의 겨냥 축 배열(TECHNICAL|LOGIC|COMMUNICATION). 일반 면접은 NULL
+    -- 피드백 생성 실패 마커(V29). callback.feedback FAILED 수신 시 기록, 성공 콜백·재생성 요청 시 클리어.
+    -- 새로고침한 클라이언트가 GET 피드백에서 "생성 중"(FEEDBACK_NOT_READY)과 "실패"(FEEDBACK_GENERATION_FAILED)를 구분하는 근거.
+    feedback_failed_at     TIMESTAMPTZ,
+    feedback_fail_retriable BOOLEAN,
     status                VARCHAR(20)  NOT NULL DEFAULT 'READY'
                           CHECK (status IN ('READY','IN_PROGRESS','INTERRUPTED','COMPLETED','CANCELLED')),
     total_question_count  INT          DEFAULT 0,

docs/event-stream.md

@@ -222,6 +222,8 @@ SSE 미지원 환경 또는 영구 단절 시:
 ```
 GET /api/documents/{id}     # 5초 간격 폴링
 GET /api/sessions/{id}      # 메시지 변경 감지
+GET /api/sessions/{id}/feedback  # 피드백 대기 폴링. 실패는 SSE ERROR(§3.6) 미수신이어도
+                                 # 404 FEEDBACK_GENERATION_FAILED(영속 마커)로 구분된다
 ```
 
 프론트엔드 구현은 `frontend/src/shared/hooks/useEventStream.ts` 단일 책임 훅으로 추상화. SSE 우선 → 실패 시 폴링.

docs/messaging.md

@@ -526,7 +526,9 @@
 - 생성이 성공했는데 **성공 콜백 발행만** 실패한 경우는 FAILED 로 오인 발행하지 않는다 — 원 예외로
   DLQ 에 보내 재처리 가능하게 남긴다(멱등 마킹도 되돌림).
 - Core 는 FAILED 수신 시 피드백을 저장하지 않고 SSE `ERROR`(scope=FEEDBACK) 로 세션·유저 채널에
-  알린다. `errorMessage` 원문은 서버 로그에만 남긴다(클라이언트 미노출).
+  알리며, **실패 마커를 영속화**한다(`interview_sessions.feedback_failed_at`/`feedback_fail_retriable`,
+  V29) — SSE 를 놓친 클라이언트도 GET 피드백의 404 `FEEDBACK_GENERATION_FAILED` 로 실패를 구분한다.
+  마커는 성공 콜백 도착·재생성 요청 시 클리어. `errorMessage` 원문은 서버 로그에만 남긴다(클라이언트 미노출).
 
 ### 5.12 `realtime.session.notify`
 ```json