[krestar]

왜 필요한가요?

2026-10-27 Render 운영 로그에서 이야기 시작 시 Gemini 503 반복 및 약 40초 후 RestClientException으로 감싸진 SocketTimeoutException을 확인했습니다.

• Closes fix(ai): Gemini 503 및 읽기 타임아웃 복구 #153

무엇이 바뀌나요?

• 게임 규칙·상태: 변경 없음
• Backend / API / DB: 읽기 타임아웃의 근본 원인이 SocketTimeoutException인 경우 PROVIDER_NETWORK로 분류해 기존 bounded recovery에 포함; 그 외 RestClientException은 비재시도 provider 오류
• AI narrative / prompt: Gemini 3.8 Flash 기본 모델, 3.5 Flash-Lite fallback; stable Flash-Lite 모델 ID 지원
• Image generation: 변경 없음
• Frontend / UX: 변경 없음
• Build / deploy / docs: application.properties, README, architecture 기본값 및 장애 대응 설명 동기화

책임 경계

• 서버가 결정하는 사실: canonical state, turn, 모든 판정과 저장
• LLM이 서술하는 내용: story/choices/visual hints
• LLM이 변경하면 안 되는 사실: 서버가 확정한 결과 및 상태

어떻게 검증했나요?

• PR 전체 diff 비판적 검토 및 누락됐던 테스트·설정·문서 반영
• ./gradlew clean test
• ./gradlew postgresIntegrationTest
• ./gradlew build
• cd frontend && npm ci && npm test && npm run lint && npm run build
• 운영 opening 직접 smoke test (인증 및 실제 provider 응답 필요)
• 실패 흐름의 자동화 테스트 최종 CI 확인
• 중복 canonical commit 경계가 기존 executor/persistence 규칙 그대로임을 diff로 확인 (새 DB mutation 없음)

추가된 GeminiNarrativeAdapterTest: wrapped read timeout이 RecoverableNarrativeResponseException(PROVIDER_NETWORK)가 되는지, 일반 RestClientException은 NarrativeProviderException인지 확인. GeminiProviderSettingsTest는 primary/fallback URL 및 기존 thinking contract를 확인.

CI 증거: https://github.com/krestar/uctale/actions/runs/40379491482 (최종 head 0a9ff361, Backend / PostgreSQL integration / Frontend 모두 success).

비판적 검토에서 반영한 내용: 초기 PR에 누락된 HTTP client 예외 회귀 테스트, default property, README/architecture 동기화를 수정. Run-time 환경변수 override가 기본값과 다를 수 있다는 배포 주의사항도 기재. 외부 provider가 정상화됐다는 주장은 하지 않음.

게임 상태·AI 안전성

• 결정적 상태 판정/저장은 서버 소유 (해당 도메인 코드 변경 없음)
• AI 출력만으로 결정적 상태 변경하는 코드 추가 없음
• 요청의 prompt/문맥 전달 경계 변경 없음
• provider 오류에서 canonical 상태 commit하지 않는 기존 규칙 유지
• GameState/snapshot/schema 변경 없음

보안·비용

• 키 및 개인 데이터 출력/로깅 추가 없음
• 기존 최대 provider 시도 횟수 유지; 읽기 타임아웃 분류 변경에 따라 retry가 발생할 수 있는 비용 영향 확인
• 입력 제한 변경 없음
• CORS 및 공개 endpoint 변경 없음

API·DB·운영 영향

• API 응답 schema 변경 없음
• DB migration 필요 없음
• 환경변수 이름만 문서화; secret 제외
• 배포 후 확인 항목 문서에 기재
• Render 배포 후 실제 이야기 시작 success 확인

화면 / 응답 예시

새 API schema 없음. 한시적 네트워크 오류 재시도 소진 시 기존 NARRATIVE_PROVIDER_UNAVAILABLE 응답 경계가 적용될 수 있음.