[krestar]

왜 필요한가요?

운영 Gemini Flash-Lite의 정상 JSON 응답에서 선택적 intent/subject_key 검증 실패가 3회 반복되어 503 PROVIDER_RESPONSE_INVALID가 발생했습니다.

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

무엇이 바뀌나요?

• 게임 규칙·상태: 변경 없음
• Backend / API / DB: 선택적 gameplay hint가 불완전/무효하면 양 필드를 함께 제거하고 일반 SKILL_CHECK 선택지 발급
• AI narrative / prompt: 올바른 slug와 필드 쌍을 생성하도록 지시
• Image generation: 변경 없음
• Frontend / UX: 변경 없음
• Build / deploy / docs: provider 문서, 이유 코드 및 telemetry 확인

책임 경계

• 서버가 결정하는 사실: gameplay 제안 검증과 server-issued action·canonical 결과
• LLM이 서술하는 내용: 이야기, 선택지 텍스트 및 선택적 gameplay 제안
• LLM이 변경하면 안 되는 사실: HP·상태·성공/실패·action token·게임 규칙

어떻게 검증했나요?

• 변경 diff 자체 검토: 잘못된 hint만 폐기, 정상 hint는 보존하며 필수 narrative 검증은 이전과 동일
• ./gradlew clean test
• ./gradlew postgresIntegrationTest
• ./gradlew build
• cd frontend && npm ci && npm test && npm run lint && npm run build
• 운영 수동 smoke
• 오류 처리 회귀 테스트 CI 확인
• 새 저장 상태 mutation 없고 중복 요청 로직 변경 없음

게임 상태·AI 안전성

• 서버만 canonical game state 결정
• LLM 출력만으로 canonical state 변경하지 않음
• provider 문맥 새 전송 없음
• 무효 선택적 힌트만 버리며 필수 응답 검증 유지
• schema/legacy 데이터 변경 없음

보안·비용

• raw provider 내용과 secret 로깅하지 않음
• 무효 hint에 대한 불필요한 최대 3회 provider 재시도 비용 축소
• 사용자 입력 길이 정책 변경 없음
• CORS 변경 없음

API·DB·운영 영향

• 공개 API schema 변경 없음
• migration 불필요
• 새 환경변수 없음
• Render 배포 후 opening smoke 검증

화면 / 응답 예시

게임 행동 힌트가 유효하지 않은 선택지는 같은 텍스트와 ID를 가진 SKILL_CHECK 선택지로 발급됩니다.

CI: https://github.com/krestar/uctale/actions/runs/40394324796 — Backend test, PostgreSQL integration, build 및 Frontend test/lint/build 모두 성공.

비판적 검토: 선택지의 id/text 검증을 완화하지 않으며, 타이핑 오류 hint를 그대로 서버-issued gameplay으로 승격하지 않습니다. 실제 운영 검증 전 정상화 주장 금지.