[제안] FastAPI 사용자 인증을 위한 내부 Access Token 검증 API 추가

[ghkim1632]

배경

대화 캡처 이미지 기반 장소·맥락 제안 기능을 추가할 예정입니다.

이미지는 Spring을 거치지 않고 Front에서 FastAPI로 직접 전송하며, FastAPI가 이미지 분석과 카카오 장소 검색을 담당합니다. 사용자가 결과를 확정한 이후에는 기존 Spring의 POST /api/core/v1/records로 저장합니다.

Front → FastAPI → 이미지 분석 및 카카오 장소 검색
Front → Spring → 최종 장소 기록 저장

필요한 이유

FastAPI의 이미지 분석 API는 로그인한 사용자만 호출할 수 있어야 합니다.

Access Token은 HttpOnly 쿠키이므로 브라우저가 FastAPI 요청에 자동으로 첨부할 수 있지만, FastAPI가 JWT만 직접 검증하면 토큰 발급 후 탈퇴한 회원을 즉시 확인할 수 없습니다.

FastAPI가 탈퇴 여부를 확인하기 위해 Spring을 호출해야 하므로, Spring에서 다음 내용을 한 번에 확인하는 내부 API를 제안합니다.

• JWT 서명 및 만료 여부
• Access Token 용도
• 회원 ID
• 탈퇴하지 않은 활성 회원인지

이미지나 대화 내용은 Spring에 전달하지 않고 Access Token만 전달합니다.

제안 흐름

1. Front가 이미지와 Access Token 쿠키를 FastAPI에 전달
2. FastAPI가 Access Token만 Spring 내부 API에 전달
3. Spring이 JWT를 검증
4. Spring이 MemberRepository.isActive()로 활성 회원 여부 확인
5. Spring이 active와 memberId를 FastAPI에 반환
6. active=true인 경우에만 FastAPI가 이미지 분석 진행

제안 API

POST /api/core/v1/internal/auth/introspect
Cookie: access_token={JWT}
X-Internal-Secret: {AI_TO_CORE_SECRET}

/v1/auth/**는 공개 경로이므로, 내부 API는 /v1/internal/** 아래에 둡니다.

유효한 활성 회원

{
  "success": true,
  "data": {
    "active": true,
    "memberId": 123
  }
}

토큰이 잘못됐거나 만료됐거나 탈퇴한 회원

{
  "success": true,
  "data": {
    "active": false
  }
}

memberId는 active=true인 경우에만 반환합니다.

구현 조건

• 기존 JwtTokenProvider.parseAccessToken()을 재사용합니다.
• JWT 검증 후 MemberRepository.isActive(memberId)를 반드시 확인합니다.
• 기존 Spring 공통 응답 envelope을 유지합니다.
• Spring→FastAPI 시크릿과 분리된 AI_TO_CORE_SECRET을 사용합니다.
• 해당 내부 API는 X-Internal-Secret 검증을 통과한 요청만 처리합니다.
• 서비스 간 POST 요청이므로 해당 경로를 Spring CSRF 검사에서 제외합니다.
• CSRF 예외 처리 이유를 인증 문서와 테스트에 명시합니다.
• 내부 API는 외부 Ingress에서 접근할 수 없도록 차단합니다.
• Access Token과 내부 시크릿은 요청·오류 로그에 기록하지 않습니다.
• Spring에 이미지나 대화 내용은 전달하지 않습니다.

완료 조건

• 유효한 활성 회원의 토큰은 active=true와 memberId를 반환합니다.
• 위조·만료·용도가 다른 토큰은 active=false를 반환합니다.
• 탈퇴 회원의 유효한 JWT도 active=false를 반환합니다.
• 내부 시크릿이 없거나 일치하지 않으면 요청을 거부합니다.
• CSRF 토큰 없이도 내부 시크릿이 유효한 서비스 간 요청은 처리됩니다.
• 외부에서 내부 인증 API에 직접 접근할 수 없습니다.
• 정상·만료·위조·탈퇴·시크릿 누락에 대한 테스트가 포함됩니다.

관련 협의

공용 계약 문서에 다음 내용을 먼저 반영할 예정입니다.

• 신규 이미지 분석 흐름
• FastAPI→Spring 토큰 검증 요청
• 역방향 내부 시크릿
• 내부 API의 CSRF 예외
• 외부 FastAPI 경로와 Infra 라우팅

[colosair]

흐름 자체는 타당합니다 — FastAPI 가 JWT 를 직접 검증하지 않는 것이 맞습니다

introspect 로 탈퇴 여부까지 한 번에 확인하는 설계에 동의합니다. FastAPI 가 서명 검증만 하면 탈퇴한 회원의 유효 토큰을 통과시키게 되고, 그렇다고 FastAPI 가 core.* 를 읽는 것은 계약 위반입니다(static/05 — "FastAPI 는 core.* 에 접근하지 않는다").

AI 파트 구현 부담도 크지 않습니다. 나가는 HTTP 클라이언트가 이미 있고(GMS), 내부 인증 헤더 패턴도 PINLOG_AI_INTERNAL_SECRET 으로 이미 씁니다.

다만 이 제안이 건드리는 것이 인증 하나가 아니어서 세 가지를 나눠 짚습니다.

1. 통신 방향 결정이 지금 세 곳에 흩어져 있습니다

docs#32    현재 계약을 확인한 곳 — "AI → Backend 방향은 MVP 계약에 없다" 로 저희가 답했다
back#129   안 B — 완료 이벤트를 FastAPI 가 발행 (ai → back 비동기)
back#138   토큰 검증 — FastAPI 가 Spring 을 호출 (ai → back 동기)

#129 와 #138 은 수단이 다를 뿐 같은 결정을 요구합니다. 어느 쪽이든 채택되면 docs#32 에서 확인한 5항목 중 4·5번(callback 없음 · ai → back NetworkPolicy 불필요)이 바뀝니다.

저희가 인프라에 "지금 막힌 게 맞고 열지 말라" 고 답한 지 얼마 안 됐습니다. 결정이 나면 저희가 인프라에 정정해서 전하겠습니다 — 다만 그 결정이 한 곳에서 나야 합니다.

2. 인증은 MQ 로 대체할 수 없습니다

#129 논의와 함께 보실 때를 위해 적습니다.

#129 안 B   완료 통보 — 비동기 · 응답을 기다리지 않는다   → MQ 가 맞다
#138        토큰 검증 — 동기 · 즉시 답이 필요하다        → MQ 로는 못 한다

브로커로 요청을 보내고 응답을 기다리는 것은 MQ 의 용도가 아닙니다. 「MQ 를 도입하니 인증도 그걸로」는 성립하지 않습니다. 두 건은 방향 결정만 공유하고 수단은 각자 정하는 것이 맞습니다.

3. 가장 무거운 것 — FastAPI 외부 노출입니다

1. Front 가 이미지와 Access Token 쿠키를 FastAPI 에 전달

이 한 줄이 네트워크 경계를 통째로 바꿉니다. 현재 계약과 정면으로 부딪힙니다.

현재	근거
ingress.enabled: false · 내부 전용 ClusterIP	infra apps/dev/ai/values.yaml
"클러스터 외부에서 AI 서버로의 진입점이 존재하지 않는다"	S15P11A705-61 완료 조건
"Spring(back)에서만 호출, 외부 진입점 없음"	같은 티켓 서비스 개요
Backend Pod → AI 8000 만 허용	인프라가 docs#32 에서 확인한 NetworkPolicy

즉 지금 구성에서는 Front 가 FastAPI 를 부를 수 없습니다. 열려면 Ingress·인증·CORS·rate limit·WAF 가 전부 새로 필요하고, 이것은 인증 API 하나를 추가하는 것과 비용이 다릅니다.

이미지를 Spring 경유로 보내면 이 축이 사라집니다

현재 제안   Front → FastAPI (이미지)          외부 노출 필요
대안        Front → Spring → FastAPI (이미지)  기존 경계 유지 · introspect 도 불필요

대안에서는 #138 자체가 필요 없어집니다 — Spring 이 이미 인증을 마친 뒤 부르므로 FastAPI 가 토큰을 볼 이유가 없습니다.

"이미지는 Spring 을 거치지 않고" 로 정하신 이유가 대용량 바이너리를 Spring 이 중계하는 부담이라면 그것은 실재하는 근거입니다. 다만 그 비용과 외부 노출 비용을 비교해 보시면 좋겠습니다 — 후자는 인프라·보안 표면 전체에 걸립니다.

저희 쪽 정리

API 구현        introspect 호출은 부담스럽지 않다 — 클라이언트도 헤더 패턴도 이미 있다
방향 결정       한 곳에서 나야 한다. docs#32 가 현재 계약을 확인한 곳이다
외부 노출       AI 파트 단독으로 판단할 수 없다 — 인프라·보안 결정이다
                S15P11A705-61 완료 조건과 정면으로 부딪히므로 그 티켓도 함께 고쳐야 한다

저희가 막는 것은 없습니다. 다만 3 이 정해지기 전에 1·2 만으로 착수하시면, 나중에 경로가 바뀔 때 인증 설계를 다시 하게 됩니다.

[ghkim1632]

논의 내용을 종합하면, 이번 기능은 Spring이 인증된 이미지 요청을 받아 FastAPI로 전달하는 방식을 우선 검토하는 것이 적절해 보입니다.

제안 흐름

1. Front → Spring: 대화 캡처 이미지 업로드
2. Spring: 기존 쿠키 인증 및 CSRF 검증
3. Spring → FastAPI: 이미지와 내부 인증 헤더 전달
4. FastAPI: 장소·맥락 추출 및 카카오 장소 검색
5. FastAPI → Spring → Front: 장소 제안 결과 반환
6. Front: 사용자가 최종 장소와 맥락 확인
7. Front → Spring: 기존 POST /api/core/v1/records로 저장

단계가 길어 보이지만 각 서비스의 책임은 비교적 단순합니다.

• Spring: 사용자 인증, 요청 중계, 응답 전달
• FastAPI: 이미지 분석, 장소·맥락 추출, 카카오 검색
• Front: 이미지 업로드, 후보 표시, 사용자 확인, 최종 저장

Spring은 이미지 내용을 분석하거나 카카오 검색을 수행하지 않고, 인증된 요청을 내부 FastAPI로 전달하는 얇은 중계 역할만 담당합니다.

이 방식을 긍정적으로 검토하는 이유

기존 네트워크 경계를 유지할 수 있습니다

현재 FastAPI는 외부 Ingress 없이 Spring에서만 호출하는 내부 서비스로 설계돼 있습니다.

Spring 중계 방식을 사용하면 다음 기존 조건을 그대로 유지할 수 있습니다.

• FastAPI ingress.enabled: false
• 외부에서 FastAPI 직접 접근 불가
• 기존 Back → AI NetworkPolicy 유지
• 기존 X-Internal-Secret 통신 방식 재사용
• AI 서버의 외부 공격 표면 증가 없음

별도의 인증 API가 필요하지 않습니다

Spring이 Front 요청을 받을 때 이미 다음 항목을 확인할 수 있습니다.

• Access Token 서명과 만료
• Access Token 용도
• 활성 회원 여부
• CSRF 토큰

따라서 FastAPI가 Spring에 Access Token 검증을 요청하는 introspect API를 별도로 만들 필요가 없습니다.

또한 FastAPI에 다음 기능을 중복 구현하지 않아도 됩니다.

• JWT 검증
• 탈퇴 회원 확인
• 사용자 쿠키 처리
• CSRF 처리
• 외부 사용자 인증 오류 처리

변경 범위와 운영 부담이 작습니다

Front가 FastAPI를 직접 호출하면 Ingress, CORS, WAF, Rate Limit, AI→Spring NetworkPolicy와 별도 내부 시크릿이 필요합니다.

Spring 중계 방식에서는 신규 외부 진입점이 Spring 하나로 유지되므로 기존 인증·보안·모니터링 체계를 재사용할 수 있습니다.

이번 기능은 이미지 1장, 최대 10 MiB 수준의 제한된 요청이므로 MVP 단계에서는 Spring의 중계 부담보다 FastAPI 외부 노출에 따른 인프라·보안 변경 비용이 더 크다고 판단합니다.

구현 시 필요한 조건

• Spring에 사용자용 장소 제안 API를 추가합니다.
• Spring은 기존 인증과 CSRF 검증을 적용합니다.
• Spring은 이미지 내용을 저장하거나 분석하지 않습니다.
• Spring은 내부 FastAPI API에 이미지와 X-Internal-Secret을 전달합니다.
• FastAPI가 반환한 결과를 Spring 공통 응답 형식으로 Front에 전달합니다.
• 이미지 최대 용량과 전체 제한 시간을 Spring과 FastAPI 양쪽에 동일하게 설정합니다.
• 원본 이미지는 요청 처리 후 Spring과 FastAPI 어디에도 영구 저장하지 않습니다.
• FastAPI 장애와 제한 시간 초과를 Spring의 공통 오류 형식으로 변환합니다.
• 최종 장소 기록은 기존 POST /api/core/v1/records를 그대로 사용합니다.

기대 효과

이 방식을 선택하면 기존 AI 내부 전용 계약을 유지하면서 기능을 추가할 수 있습니다.

또한 인증 판단은 Spring, 이미지 분석은 FastAPI라는 기존 책임 경계를 유지하므로, 구현 이후 운영과 장애 원인 파악도 단순해집니다.

따라서 이번 추가 개발에서는 Spring 중계 방식을 우선안으로 긍정 검토하고, 실제 이미지 크기와 처리 시간을 측정한 뒤 Spring 중계가 병목이 되는 경우에만 FastAPI 외부 노출 구조를 재검토하는 방향을 제안합니다.

[colosair]

Spring 중계 방식에 동의합니다 — 저희가 짚은 것이 그대로 반영됐습니다

FastAPI ingress.enabled: false        유지
외부 → FastAPI 직접 접근 불가          유지
Back → AI NetworkPolicy               유지
X-Internal-Secret 재사용               유지

S15P11A705-61 의 완료 조건("클러스터 외부에서 AI 서버로의 진입점이 존재하지 않는다")과 docs#32 에서 인프라에 확인해 드린 통신 방향이 둘 다 그대로 삽니다. introspect 도 필요 없어졌습니다.

다만 이 방식에서 새로 생기는 것이 셋 있습니다. 저희 쪽에서만 보이는 것이라 미리 적습니다.

1. AI → 카카오 egress 가 새로 생깁니다 (가장 확실한 변경)

현재 FastAPI 가 나가는 외부 호출은 GMS 게이트웨이 하나뿐입니다. 카카오 장소 검색을 FastAPI 가 맡으면 두 번째 외부 대상이 됩니다.

NetworkPolicy   AI Pod → 카카오 API egress 허용이 필요하다 (인프라)
Secret          VITE_KAKAO_REST_KEY 는 지금 프론트 빌드 변수다
                FastAPI 가 쓰려면 runtime Secret 으로 따로 주입돼야 한다

S15P11A705-118 의 runtime key 집합에 키가 하나 늘어납니다. 지금 8키이고 infra/tools/validate_ai_dev_prerequisites.py 가 unexpected 도 오류로 잡으므로, 검증기와 문서를 함께 고쳐야 합니다.

2. 비전 모델 지원 여부를 확인하지 못했습니다 — 이게 선행 조건입니다

현재 FastAPI 의 GMS 호출은 텍스트 전용입니다. 코드에 이미지·멀티모달 경로가 없습니다.

임베딩   text-embedding-3-small
판정     gpt-4o-mini → gemini-2.5-flash → claude-haiku-4-5  (벤더 폴백)

GMS 게이트웨이가 비전 요청을 프록시하는지 저희도 모릅니다. 프록시 형태({root}/api.openai.com/v1/chat/completions)를 보면 이미지 파트를 담은 요청도 그대로 통과할 가능성이 높지만 확인한 적이 없습니다.

이것이 안 되면 기능 자체가 성립하지 않습니다. 저희가 프로브로 먼저 재 보겠습니다 — tools/keyword_eval/probe_vendors.py 가 벤더별 요청·응답 어댑터를 이미 갖고 있어 이미지 파트만 얹으면 됩니다. 결과를 여기 남기겠습니다.

3. Spring 이 이미지 바이너리를 통과시킵니다

원래 이 방식을 피하신 이유("이미지는 Spring 을 거치지 않고")가 여기 있었을 것입니다. 그 부담은 실재하고 사라지지 않았습니다 — 다만 외부 노출 비용과 견주면 저희도 이쪽이 낫다고 봅니다.

정하실 때 참고하실 값 둘입니다.

요청 크기 상한   Spring · FastAPI 양쪽에 필요하다
타임아웃         이미지 분석은 텍스트 판정보다 오래 걸린다
                현재 AiProcessClient 는 202 접수 후 fire-and-forget 인데,
                이 기능은 동기 응답이라 계약이 다르다

마지막 줄이 중요합니다. 기존 POST /internal/v1/context/process 는 접수만 하고 결과를 DB 로 보내지만, 이미지 제안은 응답을 기다려야 합니다. 새 엔드포인트의 동기/비동기 성격을 계약에 명시해야 하고, 동기라면 Spring 쪽 타임아웃과 맞춰야 합니다.

저희 쪽 정리

방식 자체        동의. 기존 경계가 전부 유지된다
선행 확인        GMS 비전 지원 — 저희가 프로브로 재고 결과를 여기 남긴다
따라오는 변경     카카오 키 runtime Secret 추가 · AI egress NetworkPolicy · 8키 검증기 갱신
계약에 넣을 것    새 엔드포인트의 동기 성격 · 요청 크기 상한 · 타임아웃

비전 지원 확인 전에는 티켓을 세우지 않겠습니다. 그것이 안 되면 설계 전체가 바뀝니다.

[colosair]

GMS 비전 지원 재고 — 약속했는데 못 했습니다

앞서 이 이슈에 "GMS 게이트웨이가 비전(이미지 입력)을 지원하는지 재고해 결과를 남기겠다" 고 적었습니다. 오늘 안에 못 돌렸습니다. 사실만 남깁니다.

확인한 것    GMS 게이트웨이는 gms.ssafy.io/gmsapi/{provider-host}/... 형태이고
            텍스트 경로(OpenAI·Gemini·Anthropic)는 실호출로 확인했습니다
            2026-07-31 오류 응답 실측에서 네 경로에 19건을 호출했습니다
확인 못 한 것  이미지 입력이 그 경로로 통과하는지

이 확인이 이미지 분석 기능의 성립 여부를 가릅니다. GMS 가 비전 요청을 거부하면 이 이슈가 제안하는 흐름(Front → FastAPI → 이미지 분석) 자체가 다른 설계를 필요로 합니다.

확인 방법

멀티모달 요청 한 건을 GMS 경로로 보내면 즉시 갈립니다. 벤더 API 스펙 그대로 image_url 을 실은 요청입니다.

POST gms.ssafy.io/gmsapi/api.openai.com/v1/chat/completions
{ "model": "...", "messages": [{ "role": "user", "content": [
    { "type": "text", "text": "..." },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } } ] }] }

200 이면    지원한다 — 이 이슈의 흐름이 성립합니다
4xx 이면    본문을 보고 게이트웨이가 막는지 벤더가 막는지 갈라야 합니다
            [GMS 에러] 는 게이트웨이 고정 문구, [<Vendor> 에러] 는 벤더 원문 중첩입니다

공용 게이트웨이라 최소 횟수로만 재야 합니다 — 같은 키를 쓰는 다른 세션·시연에 영향이 갑니다.

티켓으로 남깁니다

작업 환경이 바뀌어 오늘은 못 돌립니다. S15P11A705-227 로 발행해 추적합니다 — 잊고 넘어가지 않도록 여기에도 적어 둡니다.

이 이슈가 제안한 내부 인증 API 자체에 대한 의견은 앞선 코멘트에서 바뀐 것이 없습니다.

[minyongP]

Claude Code 자동 코멘트입니다. 최종 결정·승인은 @minyongP가 직접 남깁니다.

백엔드 관점을 정리합니다.

Spring 중계 방식이 백엔드의 계약·보안 방향과 맞습니다. FastAPI가 외부에 직접 노출되지 않고(ingress.enabled: false 유지), introspect 같은 새 내부 인증 API가 필요 없어지며, 기존 쿠키 인증·CSRF 경로를 그대로 탑니다.

확정 전에 갈리는 지점 셋을 짚어 둡니다.

• S15P11A705-227(GMS 비전 지원 확인)이 선행입니다 — 결과에 따라 이 흐름 자체가 성립하지 않을 수 있습니다.
• 중계 엔드포인트의 크기·시간 예산 — 이미지 multipart 최대 크기, FastAPI 분석 지연을 감안한 타임아웃, 실패 시 오류 계약(code)이 백엔드 구현 조건입니다.
• 공용 계약 선반영 — 새 엔드포인트와 오류 계약은 docs 공용 계약에 먼저 반영한 뒤 구현합니다(feat(S15P11A705-152): 소셜 로그인에서 이메일을 필수로 강제하고 미제공 시 가입 거절 #97 때와 같은 순서).

[colosair]

GMS 비전 지원 재고 — 결과: 지원한다

앞서 약속한 재고를 실행했다. 사실만 남긴다.

방법

1×1 투명 PNG(68바이트)를 벤더 API 스펙 그대로 실어 세 경로에 각 1회씩, 총 3호출을 보냈다.

OpenAI      {root}/api.openai.com/v1/chat/completions        content[].type=image_url
Gemini      {root}/generativelanguage.googleapis.com/...     parts[].inlineData
Anthropic   {root}/api.anthropic.com/v1/messages              content[].type=image

이미지를 가장 작게 잡은 이유는 S15P11A705-205에서 큰 요청 본문이 게이트웨이 자체 오류("모델을 못 찾겠다")를 먼저 내는 것을 관측했기 때문이다 — 크기 요인과 비전 지원 여부가 섞이지 않게 했다.

결과

세 경로 모두 200. 세 벤더 모두 빈 응답이나 거부가 아니라 이미지 내용에 대한 실제 답(색상 등 한 단어)을 반환했다 — 게이트웨이가 이미지 파트를 통과시켰다는 뜻이다.

결론

GMS 게이트웨이는 멀티모달(이미지 입력) 요청을 통과시킨다. 이 이슈가 제안한 Front → Spring → FastAPI → 이미지 분석 흐름은 GMS 비전 거부로는 막히지 않는다.

안 잰 것

• 오류 응답 형태(429·5xx)는 실측하지 않았다 — 공용 게이트웨이를 의도적으로 밀지 않는 원칙.
• 실사용 크기(최대 10 MiB) 이미지·다중 이미지는 재지 않았다. 1×1 PNG 한 장만 확인했다.

리포트

docs/implements/2026-08-03-gms-vision-probe.md (PR Team-PinLog/ai#81)

[ghkim1632]

AI·Spring 담당자 검토와 GMS 비전 프로브 결과를 종합해, 이번 기능은 Spring 중계 방식으로 긍정 검토합니다.

결정안

Front → Spring → FastAPI → GMS 비전 모델·카카오 로컬 API
Front ← Spring ← FastAPI
사용자 확인 후 → 기존 POST /api/core/v1/records

Spring은 기존 쿠키 인증과 CSRF 검증을 수행한 뒤 이미지를 FastAPI 내부 API로 전달합니다. 이미지 분석과 카카오 검색은 FastAPI가 담당하며, Spring은 분석 결과를 Front에 전달하는 중계 역할만 수행합니다.

선택 이유

• FastAPI의 ingress.enabled: false를 유지할 수 있습니다.
• 외부에서 FastAPI로 직접 접근하는 경로를 만들지 않습니다.
• 기존 Back → AI NetworkPolicy를 유지합니다.
• 기존 X-Internal-Secret 통신 방식을 재사용합니다.
• 별도의 Access Token introspect API가 필요하지 않습니다.
• JWT·탈퇴 회원·CSRF 검증을 FastAPI에 중복 구현하지 않습니다.
• 기존 AI 내부 전용 계약과 보안 경계를 유지할 수 있습니다.

선행 조건 확인

GMS 게이트웨이의 비전 요청 지원 여부는 AI 담당자가 확인했습니다.

• OpenAI, Gemini, Anthropic 세 경로 모두 이미지 요청에 HTTP 200 응답
• 이미지 내용을 실제로 인식한 응답 확인
• 따라서 GMS의 이미지 입력 미지원으로 기능이 차단되지는 않음

단, 해당 프로브는 1×1 PNG로 통신 가능 여부만 확인했습니다. 실제 대화 캡처의 인식 품질, 요청 크기 및 처리 시간은 별도 측정이 필요합니다.

추가로 필요한 변경

• 동기식 FastAPI 내부 장소 제안 API 추가
• Spring 사용자용 이미지 제안 API 추가
• Spring과 FastAPI의 multipart 크기 제한 통일
• Spring→FastAPI 및 전체 요청 제한 시간 확정
• FastAPI 장애·제한 시간 초과 오류 계약 정의
• AI Pod→카카오 로컬 API egress 허용
• FastAPI용 카카오 REST API 키 Runtime Secret 추가
• AI Runtime Secret 검증기와 관련 인프라 문서 수정
• 이미지와 대화 원문 비저장 및 로그 제외

다음 순서

1. 실제 대화 캡처로 크기·품질·응답 시간 측정
2. 용량·제한 시간·오류 코드를 공용 계약에 확정
3. 공용 기능·API·AI 설계 문서 수정
4. Spring, AI, Front, Infra 담당 티켓 생성
5. 담당별 구현 진행

공용 계약이 먼저 확정돼야 각 담당자가 동일한 경로, 동기 응답, 용량 및 제한 시간 기준으로 구현할 수 있습니다.

[ghkim1632]

최종 결정

담당자 검토와 GMS 비전 지원 확인 결과, 대화 이미지 기반 장소 제안 기능은 FastAPI 직접 노출이 아닌 Spring 중계 방식으로 진행합니다.

Front → Spring → FastAPI → GMS 비전 모델·카카오 로컬 API
Front ← Spring ← FastAPI
사용자 확인 후 → 기존 POST /api/core/v1/records

인증 및 네트워크 경계

• Front 요청의 Access Token, 활성 회원 여부, CSRF는 Spring의 기존 인증 경로에서 검증합니다.
• 인증이 완료된 요청만 Spring이 FastAPI 내부 API로 전달합니다.
• FastAPI에는 Access Token과 회원 ID를 전달하지 않습니다.
• FastAPI의 ingress.enabled: false와 내부 전용 ClusterIP를 유지합니다.
• 기존 Back → AI NetworkPolicy와 X-Internal-Secret을 재사용합니다.
• AI → Back 인증 요청과 별도 AI_TO_CORE_SECRET은 추가하지 않습니다.

따라서 이 이슈에서 제안한 다음 API는 구현하지 않습니다.

POST /api/core/v1/internal/auth/introspect

Spring이 요청 진입점에서 인증과 활성 회원 확인을 모두 끝내므로, FastAPI가 다시 Spring에 토큰 검증을 요청할 필요가 없기 때문입니다.

확정된 중계 계약

• 외부 API: POST /api/core/v1/places/suggestions
• 내부 API: POST /internal/v1/place-suggestions
• 요청: PNG 또는 JPEG 이미지 정확히 1장
• 초기 이미지 상한: 5 MiB
• Spring → FastAPI read timeout: 35초
• 초기 동시 이미지 분석 상한: 인스턴스당 1건
• 동시 실행 한도 초과는 PLACE_SUGGESTION_BUSY로 구분
• 원본 이미지와 제안 결과는 Spring DB에 저장하지 않음
• 최종 저장은 기존 POST /api/core/v1/records 사용
• FastAPI 장애와 제한 시간 초과는 Spring 공통 오류 envelope으로 변환

GMS 게이트웨이의 이미지 입력 지원은 OpenAI, Gemini, Anthropic 경로에서 확인됐습니다. 실제 이미지 품질과 처리 성능은 구현 후 별도 테스트와 최적화로 진행합니다.

Spring 중계 구현은 S15P11A705-261에서 진행하며, 카카오 API egress·Runtime Secret·로그 마스킹 등 인프라 변경은 담당 작업으로 분리합니다.

이상으로 내부 Access Token 검증 API 제안은 Spring 중계 구조로 대체됐으므로 본 이슈를 not planned로 종료합니다.