로브 (Lovv) 트러블슈팅 문서

문서 성격: 보조 Markdown

대표 문서: ../11_deployment_ops.md

문서 버전: v0.14

문서 상태: 초안 (Draft)

작성일: 2026-06-12

작성자: llm팀

기준 문서: ../../04_database_design/04_database_design.md, ../../04_database_design/supplemental/neptune_alternative.md, ../../07_api_spec/07_api_spec.md, ../../08_data_preprocessing/supplemental/korea_data_preprocessing_result_report.md, ../../08_data_preprocessing/supplemental/s3_vector_index_plan.md, ../../99_pptx/01_midterm_presentation/01_midterm_presentation.md

문서 목적: 프로젝트 진행 중 발생한 주요 이슈를 원인, 판단, 조치, 재발 방지 기준으로 정리해 발표와 운영 문서에서 함께 사용할 수 있게 한다.

---

1. 문서 개요

이 문서는 로브(Lovv) 프로젝트에서 발생했거나 현재 운영 기준상 주의해야 하는 이슈를 트러블슈팅 관점으로 정리한다.

정리 기준은 다음과 같다.

2. 요약

4. 발표용 트러블슈팅 요약 문구

중간발표에서 한 장으로 설명할 때는 다음 구조로 축약한다.

이슈: 그래프DB가 필요해 보였지만 PoC 관계는 대부분 1~2-hop이었다.
        판단: Neptune은 지금 넣으면 비용과 운영 복잡도가 먼저 커진다.
        대응: 그래프DB 직접 도입 대신 Lambda로 유사 관계 탐색 기능을 구현한다.
        구현: DynamoDB 인접 리스트, 사전계산 후보 테이블, Lambda 인메모리 그래프를 조합한다.
        기준: 3-hop 이상 관계 탐색이나 실시간 그래프 쓰기가 병목이 되면 Neptune으로 승격한다.

5. 변경 이력

---

6. 상세 트러블슈팅

TS-01 Neptune 도입 범위 판단

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.2

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: TS-01 이슈의 문제, 원인, 판단, 조치, 재발 방지 기준을 본 문서에서 분리해 상세 관리한다.

---

1. 요약

2. 증상

추천 시스템에서 도시, 테마, 축제, 인접 도시 관계를 다루기 때문에 그래프DB인 Neptune을 도입할 수 있다는 의견이 있었다.

그러나 중간발표 PoC 범위에서는 대부분의 관계 탐색이 1~2-hop 수준이었다. 이 단계에서 Neptune을 바로 넣으면 기능 검증보다 운영 비용과 복잡도가 먼저 증가할 위험이 있었다.

3. 조사 범위

이번 조사는 다음 질문에 답하는 방식으로 진행했다.

4. 원인

5. AWS 서비스 조사 결과

6. 현재 Lovv 질의 패턴 분석

현재 범위에서는 임의 길이 경로 탐색보다, 이미 정의된 관계 타입을 기준으로 후보를 좁히고 재랭킹하는 일이 중심이다.

7. 대체 아키텍처

PoC와 Production 1차에서는 Neptune을 직접 도입하지 않는다. 현재 방향은 그래프DB와 유사한 관계 탐색 기능을 Lambda로 구현하는 것이다.

현재는 다음 대체 방식으로 충분하다.

7.1 관계 데이터 예시

7.2 요청 처리 흐름

사용자 조건
        ↓
        S3 vector similarity search + metadata filter
        ↓
        DynamoDB 정규화 문서 재조회
        ↓
        Lambda 관계 탐색 보조로 도시·축제·테마·장소 관계 확장
        ↓
        사전계산 후보 또는 인메모리 그래프 재랭킹
        ↓
        최종 후보 반환

8. 판단

현재 단계에서는 Neptune을 도입하지 않는 판단이 타당하다.

9. 조치

• Neptune은 원본 저장소가 아니라 향후 승격 가능한 파생 관계 인덱스로만 정의한다.
• 현재 설계는 DynamoDB, S3 vector index, Lambda 관계 탐색 보조 기능을 기준으로 작성한다.
• Lambda는 DynamoDB 인접 리스트와 사전계산 후보를 읽어 그래프DB와 유사한 후보 확장·재랭킹 기능을 수행한다.
• 발표에서는 "도입 실패"가 아니라 "비용·범위 검토 후 보류한 기술 판단"으로 설명한다.

10. 승격 기준

다음 조건 중 하나가 실제 요구사항으로 확인되면 Neptune 도입을 재검토한다.

추가로 다음 지표를 관찰한다.

11. 조사 결론

TS-01의 결론은 기존과 동일하게 유지한다.

Neptune은 그래프 질의 자체에는 적합한 서비스지만, 현재 Lovv의 PoC/Production 1차 범위에서는 관계 규모와 질의 깊이가 작고, 관계 데이터도 재생성 가능한 파생 인덱스다.

비용 측면에서도 Neptune을 바로 도입하면 최소 NCU 기반 고정비, storage, I/O, backup, data transfer 비용 축이 기존 DynamoDB, S3 vector, Lambda 스택 위에 추가된다. 초기 트래픽과 예산 규모에서는 이 고정비가 기능 검증보다 먼저 부담으로 작용할 가능성이 높다.

따라서 현재는 DynamoDB 인접 리스트, 사전계산 후보 테이블, Lambda 인메모리 그래프, S3 vector metadata filter를 조합해 구현하고, Neptune은 고도화 단계의 승격 옵션으로 둔다.

12. 출처 및 근거

13. 변경 이력

---

TS-02 S3 vector index 계약 정합성

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.2

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: TS-02 이슈의 문제, 원인, 판단, 조치, 재발 방지 기준을 본 문서에서 분리해 상세 관리한다.

---

1. 증상

S3 vector index 생성 기준을 정리하는 과정에서 city_id, vector ID, embedding dimension, metadata filter 기준이 초기 설계와 실제 적재 데이터 사이에서 어긋날 수 있었다.

2. 원인

3. 조치

• city_id는 실데이터 기준 KR-{CityNameEn} 형식으로 확정한다.
• Vector ID는 {source_type}#{source_id}#{chunk_no} 3분절로 통일한다.
• Amazon Titan Text Embeddings V2, 1024 dimension, cosine 기준으로 고정한다.
• visitor_statistics는 개별 vector가 아니라 city chunk의 보조 문맥으로만 반영한다.
• CEA 검색 요구에 맞춰 restaurant chunk에는 주소를 포함한다.

4. 재발 방지

• index 생성 전에 dimension, metric, non-filterable key를 문서와 IaC에서 대조한다.
• GSI3 entity type별 export 결과로 원천 수량을 manifest에 남긴다.
• S3 vector 결과는 DynamoDB ddb_pk/ddb_sk로 재검증하는 것을 기본 계약으로 둔다.

5. 출처 및 근거

6. 변경 이력

---

TS-03 PDF 산출물 생성·검증

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.2

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: TS-03 이슈의 문제, 원인, 판단, 조치, 재발 방지 기준을 본 문서에서 분리해 상세 관리한다.

---

1. 증상

새 결과보고서 Markdown을 추가했지만 PDF/TeX 산출물 또는 pdf/AGENT.md 목록이 함께 갱신되지 않으면 배포용 문서와 원본 문서가 어긋난다.

2. 조치

새 PDF 문서를 추가할 때는 다음을 함께 갱신한다.

PDF는 다음처럼 2회 빌드한다.

cd pdf
        xelatex -interaction=nonstopmode -halt-on-error korea_data_preprocessing_result_report.tex
        xelatex -interaction=nonstopmode -halt-on-error korea_data_preprocessing_result_report.tex

3. 재발 방지

• 목차와 outline 경고가 있으면 2회 빌드한다.
• pdf/*.aux, pdf/*.log, pdf/*.out, pdf/*.toc는 중간 산출물이므로 커밋하지 않는다.
• PDF 본문 의미가 바뀌면 먼저 대응 Markdown을 수정한다.

4. 출처 및 근거

5. 변경 이력

---

TS-04 Cognito / Social Login 책임 경계 충돌

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.2

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: TS-04 이슈의 문제, 원인, 판단, 조치, 재발 방지 기준을 본 문서에서 분리해 상세 관리한다.

---

1. 배경

초기 Lovv Auth 구조는 프론트가 Google/Kakao에서 받은 provider token을 백엔드로 전달하고, 백엔드가 직접 검증하는 방식이었다.

POST /api/v1/auth/google
        POST /api/v1/auth/kakao
        ↓
        Lovv backend가 Google/Kakao provider token 검증
        ↓
        Lovv user 조회/생성
        ↓
        Lovv access token 발급
        ↓
        refresh session 저장

하지만 Cognito를 도입하면 Google/Kakao 인증은 Cognito Hosted UI 또는 OIDC IdP가 담당한다. 백엔드는 provider token을 직접 검증하는 대신 Cognito가 검증한 JWT claims 또는 API Gateway Authorizer claims를 기준으로 Lovv 사용자와 세션 응답을 구성해야 한다.

2. 문제 1: 기존 Social Login API와 Cognito 흐름 충돌

기존 /api/v1/auth/google, /api/v1/auth/kakao를 그대로 신규 흐름의 중심으로 두면 인증 책임이 Lovv backend와 Cognito 두 군데로 나뉜다.

해결 방향

3. 문제 2: Cognito 로그인 후 Lovv 세션 shape 필요

Cognito가 인증을 처리해도 프론트는 Lovv 서비스 상태가 필요하다.

프론트가 필요한 값은 다음과 같다.

해결 방향

POST /api/v1/auth/cognito/session은 API Gateway JWT Authorizer가 검증한 Cognito claims를 받아 Lovv user/session shape로 변환한다.

처리 순서:

Cognito JWT Authorizer 검증
        ↓
        sub, email, cognito:groups claims 확인
        ↓
        Lovv user 조회 또는 생성
        ↓
        Lovv 내부 role 정규화
        ↓
        preferences 조회
        ↓
        onboardingCompleted 계산
        ↓
        session response 반환

4. 문제 3: Provider Verifier 재사용 금지

Cognito bridge endpoint에서 기존 Google/Kakao provider verifier를 재사용하면 안 된다. Cognito 흐름에서는 이미 Cognito가 provider 인증을 완료했기 때문이다.

5. 문제 4: Cognito claims 누락 시 500 발생 가능

개발 중 missing claims 테스트에서 401이 아니라 500이 발생할 수 있었다.

원인

Cognito claims 검증보다 repository 초기화가 먼저 실행되면, 인증 정보가 없는 요청인데 DB/repository 초기화 실패가 먼저 드러나 내부 서버 오류처럼 보인다.

해결 방향

• Cognito claims를 먼저 검증한다.
• repository와 DB client는 claims 검증 이후 lazy init한다.
• 인증 실패와 내부 장애를 분리한다.

6. 문제 5: Handler route와 SAM template route 불일치

src/auth/app.py에 /api/v1/auth/cognito/session 처리를 추가해도 template.yaml에 API Gateway route가 없으면 실제 배포 API에서는 접근할 수 없다.

해결 방향

코드 테스트뿐 아니라 template route 테스트를 추가한다.

확인 기준:

7. 문제 6: Logout 의미 분리

Cognito 도입 후 logout을 단순히 백엔드 session 삭제로만 설명하면 부족하다. Cognito access token은 JWT이므로 이미 발급된 token은 만료 전까지 유효할 수 있다.

백엔드가 Cognito token 자체를 즉시 무효화한다고 표현하지 않는다. 프론트는 필요하면 Cognito logout URL로 redirect한다.

8. 문제 7: Role을 Cognito Group만으로 처리하면 복잡해짐

Lovv Admin에는 일반 사용자 외에도 여러 운영 role이 필요하다.

해결 방향

Cognito Group은 큰 권한 구분만 담당하고, 담당 지역과 provider 소유권 같은 세부 권한은 Lovv DB/backend에서 검증한다.

주의 기준:

• 프론트 route guard만으로 관리자 보안을 처리하지 않는다.
• Lambda/API에서도 role을 검증한다.
• 지역 운영자의 담당 지역 scope는 DB에서 확인한다.

9. 문제 8: API 명세 재정리 필요

기존 OpenAPI/API 명세는 custom social login 기준이라 Cognito bridge 흐름을 설명하지 못했다.

반영 기준:

10. 최종 정리

Cognito 도입의 핵심은 Google/Kakao 로그인을 백엔드가 직접 처리하는 구조에서 벗어나, Cognito가 인증을 담당하고 Lovv 백엔드는 Cognito claims를 서비스 사용자/session shape로 변환하는 것이다.

현재 방향:

• Google/Kakao 직접 로그인 API는 legacy로 유지한다.
• Cognito Hosted UI/OIDC가 Social Login을 담당한다.
• Lovv 백엔드는 /api/v1/auth/cognito/session으로 bridge 처리한다.
• API Gateway JWT Authorizer 연결은 후속 Task로 분리한다.
• Role은 Cognito Group과 Lovv DB scope 조합으로 처리한다.
• 프론트는 Cognito token 기반으로 session/me를 호출해 서비스 상태를 복구한다.

11. 출처 및 근거

12. 변경 이력

---

TS-05 식당 데이터 취득 범위 조정

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.2

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: 경북·강원 관광지와 축제 데이터 취득 과정에서 식당 데이터를 직접 취득하지 않고 Kakao Map API로 대체한 판단 근거를 정리한다.

---

1. 요약

2. 문제

경북·강원 관광지와 축제 데이터를 취득하는 과정에서 식당 데이터도 함께 취득 대상으로 검토했고, 당시에는 식당 데이터를 실제로 취득해 사용하였다.

그러나 취득한 식당 데이터를 적용했을 때 추천·검색 품질 측면에서 의미 있는 결과가 나오지 않았다. 또한 식당 데이터는 관광지·축제 데이터보다 수량이 많아 S3 vector로 변환하는 작업 시간이 증가하는 문제가 발생했다.

이 상태로 식당 데이터를 계속 직접 보유하면 수집, 정제, S3 vector 변환, 갱신, 품질 검증 부담이 프로젝트 범위를 넘어설 수 있었다.

3. 원인

4. 해결 과정

• 관광지·축제 데이터와 식당 데이터의 성격을 분리해 검토했다.
• 관광지·축제는 프로젝트 도메인 데이터로 직접 취득·정제하는 쪽이 적합하다고 판단했다.
• 식당 데이터는 정적 데이터로 직접 취득하면 DynamoDB 비용과 DB 운영 부담이 커질 수 있다고 판단했다.
• 식당 데이터는 사용자의 위치, 일정, 시간대, 선호도에 따라 실시간으로 달라지는 성격이 강하다고 정리했다.
• 식당 데이터는 직접 취득 대상에서 제외하고, Kakao Map API를 통해 사용자 맥락에 맞게 조회하는 방향으로 전환했다.

5. 결과

식당 데이터는 프로젝트 내부 데이터셋으로 대량 취득하지 않는다.

대신 관광지·축제 데이터는 직접 취득·정제 대상으로 유지하고, 식당 데이터는 Kakao Map API를 통해 필요 시점에 조회하는 외부 API 연동 대상으로 정리한다. 이를 통해 데이터 보유 범위, DynamoDB 운영 비용, S3 vector 변환 부담을 줄이고, 식당 데이터의 최신성과 사용자 취향 반영 가능성을 확보한다.

6. 출처 및 근거

7. 변경 이력

---

TS-06 일본 데이터 취득 포기

문서 성격: 트러블슈팅 하위 Markdown

상위 문서: ../troubleshooting.md

문서 버전: v0.6

문서 상태: 초안 (Draft)

작성일: 2026-07-09

작성자: llm팀

문서 목적: 일본 데이터 취득 검토 과정에서 CC BY 4.0 기준으로 처리하려던 후보가 JATO 및 일본 정부·공공 운영 출처의 세부 규약 확인 과정에서 제한되는 문제를 확인하고, 취득을 포기한 판단 근거를 정리한다.

---

1. 요약

2. 문제

일본 데이터는 최초 검토 시 CC BY 4.0 또는 CC BY 4.0과 호환되는 공개 조건으로 처리 가능한 것으로 보고 취득 후보에 포함되었다.

그러나 본격적인 데이터 취득을 진행하기 전에 제한 사항을 확인하는 과정에서 별도 데이터 규약을 검토했고, CC BY 4.0 기준으로만 보면 가능해 보이던 이용 범위가 실제 규약에서는 제한될 수 있음을 확인했다.

이 상태에서 데이터를 취득하면 CC BY 4.0 라이센스 기준만 보고 사용 가능하다고 판단한 내용과, 제공처의 실제 데이터 규약 사이에 충돌이 발생할 수 있었다.

특히 JATO(Japan Adventure Tourism Organization, 일반사단법인 일본 어드벤처 투어리즘 협의회) 자료는 관광 관련 정보로 활용 가능해 보일 수 있으나, 공식 페이지 확인 결과 오픈데이터 제공처라기보다 회원 기반 협의회와 활동 안내 성격이 강했다. 따라서 공개 웹 페이지에 접근 가능하다는 이유만으로 수집, 저장, 벡터화, 서비스 제공에 활용할 수 있다고 판단하기 어렵다.

추가로 일본 정부가 직접 운영하거나 정부 산하·공공기관이 운영하는 관광 관련 출처도 함께 확인했다. 정부 운영 출처는 PDL 1.0 또는 정부 표준 이용규약을 통해 CC BY 4.0 호환 조건으로 볼 수 있는 경우가 있었지만, 모든 정부·공공 사이트가 동일하게 자유 취득 가능한 것은 아니었다. 예를 들어 일본 관광청(JTA) 사이트는 별도 명시가 없는 콘텐츠에 Public Data License 1.0을 적용하지만, JNTO의 Japan Tourism Statistics는 다운로드 과정에서 사용 신청 또는 이용 허가 확인 절차를 요구한다. 따라서 CC BY 4.0 기준으로 내부 처리했더라도, 최종 취득 가능 여부는 출처별 세부 규약을 기준으로 판단해야 한다.

3. 원인

4. JATO 조사 결과

5. 일본 정부·공공 운영 출처 조사 결과

6. 해결 과정

• 일본 데이터를 취득 후보로 두고 CC BY 4.0 또는 CC BY 4.0 호환 조건으로 처리 가능한지 1차로 확인했다.
• JATO 공식 사이트에서 JATO가 Japan Adventure Tourism Organization이며, 일본 어드벤처 투어리즘 협의회라는 점을 확인했다.
• JATO 입회 안내와 회원규약을 확인해 회원 혜택, 상호·상표 이용 조건, 자료·데이터 재사용 제한을 검토했다.
• 일본 정부·공공 운영 출처를 추가로 확인해 디지털청 PDL 1.0, 일본 관광청(JTA), JNTO Japan Tourism Statistics, e-Stat의 이용조건 차이를 검토했다.
• 데이터 규약이 라이센스 문구와 다르게 해석될 수 있고, JATO 자료는 오픈 라이센스 대상이 아니라 무단 재게시·양도·판매·공표 제한에 걸릴 수 있음을 확인했다.
• 정부·공공 출처도 CC BY 4.0 호환 여부와 별도로 출처 표기, 편집 표시, 제3자 권리, API/외부 DB 조건, 신청·허가 절차를 확인해야 한다고 판단했다.
• CC BY 4.0 기준과 세부 규약이 충돌할 수 있는 상태에서 데이터를 취득·가공·적재하지 않기로 결정했다.
• 일본 데이터는 취득 대상에서 제외하고, KR 데이터 중심의 전처리·검색·추천 범위를 우선 유지했다.

7. 결과

일본 데이터는 본격적인 취득을 진행하지 않는다.

CC BY 4.0 또는 CC BY 4.0 호환 조건만으로 취득 여부를 확정하지 않고, 데이터 규약까지 확인한 뒤 취득 포기를 결정했다. 이 판단을 통해 규약 위반 가능성, 사후 데이터 제거 비용, 운영 문서와 실제 데이터 사용 조건의 불일치 위험을 줄였다.

JATO 관련 자료는 명시적 허가 전까지 수집 대상, Raw 적재 대상, DynamoDB 적재 대상, S3 vector 생성 대상에서 제외한다. 향후 일본 관광 데이터를 다시 검토할 경우 JATO 자료를 직접 취득 대상으로 두지 않고, 공공 오픈데이터 포털이나 API 제공 조건이 명확한 출처를 우선 검토한다.

일본 정부·공공 운영 출처는 취득 포기 대상과 재검토 가능 대상을 분리한다. PDL 1.0 또는 CC BY 4.0 호환 조건이 명시되고, 출처 표기·편집 표시·제3자 권리·API 조건을 충족할 수 있는 데이터는 후보로 남긴다. 반대로 신청·허가 절차가 있거나, API/외부 DB의 별도 약관이 있거나, 사진·로고·지도처럼 제3자 권리 확인이 필요한 자료는 CC BY 4.0으로 내부 처리했더라도 자동 수집·벡터화 대상에서 제외한다.

8. 재발 방지

• 외부 데이터를 취득하기 전 라이센스와 데이터 규약을 반드시 함께 확인한다.
• CC BY 4.0 또는 CC BY 4.0 호환 조건으로 보이더라도 별도 규약, 신청 절차, API 약관이 더 엄격하면 취득을 보류한다.
• 취득 전 확인 항목에 저장, 가공, 재배포, API 제공, 벡터화, 상용 서비스 활용 가능 여부를 포함한다.
• 규약 해석이 애매한 경우 Raw 적재, DynamoDB 적재, S3 vector 생성 전 단계에서 중단한다.
• 협회, 단체, 회원 기반 사이트의 자료는 공공 오픈데이터 포털과 구분해서 검토한다.
• 회원규약, 상호·상표 사용 조건, 자료·데이터 재사용 조항을 별도 확인한다.
• 정부·공공 운영 출처라도 CC BY 4.0 호환 여부, API 약관, 신청·허가 절차를 출처별로 확인한다.
• 정부 자료를 편집·가공해 사용할 경우 출처 표기와 편집 사실 표시를 함께 남긴다.

9. 조사 결론

TS-06의 핵심은 일본 데이터 후보를 CC BY 4.0 기준으로 처리하려 했지만, 실제 데이터 규약을 함께 확인했을 때 동일한 범위의 사용 허용으로 보기 어려웠다는 점이다.

JATO 조사 결과, JATO는 Japan Adventure Tourism Organization으로 확인되며 공식 사이트와 입회 안내는 협의회 활동 및 회원 혜택 중심으로 구성되어 있었다. 또한 회원규약상 협의회가 발행하는 자료·데이터는 무단으로 다른 매체에 게재하거나 제3자에게 양도·판매·공표할 수 없으므로, 명시적 허가 없이 프로젝트 데이터셋으로 취득하는 것은 적절하지 않다.

일본 정부·공공 운영 출처까지 포함해 확인한 결과, CC BY 4.0 또는 CC BY 4.0 호환 조건 자체가 취득 가능성을 보장하지는 않는다. 일본 관광청(JTA)처럼 PDL 1.0을 적용하는 출처는 CC BY 4.0 호환 기준으로 재검토 가능성이 있지만, JNTO Japan Tourism Statistics처럼 사용 신청 또는 허가 절차가 붙는 출처도 있다. 또한 e-Stat처럼 정부 표준 이용규약과 CC BY 4.0 호환을 안내하는 경우에도 API·GIS 등 별도 조건이 존재한다.

따라서 일본 데이터는 수집을 강행하지 않고 취득 대상에서 제외하는 것이 맞다. 이후 재검토 시에는 JATO와 같은 협의회 자료는 제외하고, 일본 정부·공공 출처 중 CC BY 4.0 호환 조건이 명확하며 프로젝트의 Raw 저장, DynamoDB 적재, S3 vector 생성, 서비스 제공 범위를 세부 규약상 충족하는 데이터만 별도 후보로 분리한다.

10. 라이센스 원문 첨부

11. 출처 및 근거

12. 변경 이력