[TROUBLE SHOOTING]지도 API 마이그레이션 및 백엔드 좀비 프로세스/모듈 오류 해결

[yura103]

[Troubleshooting]지도 API 마이그레이션 및 백엔드 연동 간 모듈/환경 오류 해결

📅 일시: 2025.11.20

📂 관련 파일:

• src/components/KakaoMapComponent.tsx (API 전환 대상)
• backend/app.py (서버 엔트리 포인트)
• src/utils/location.ts (위치 로직 핸들러)
• src/types/index.ts (타입 정의)

🏷 태그: #Migration #KakaoMap #ZombieProcess #ModuleResolution #FastAPI

---

📌 상황 (Context)

챗봇에서 사용자 위치 기반으로 가장 가까운 가맹점(예: 스타벅스)을 지도에 표시하고, 맞지 않을 경우 범위를 넓혀 리스트를 제공하는 기능을 구현함. 기존 네이버 지도 API의 거리 계산 정확도 문제로 카카오 지도 API로 전면 교체를 진행하는 과정에서 발생함. (React + FastAPI 모노레포 환경)

⚠️ 문제 (Problem)

1. 데이터 불일치 (Mock Data 지속 노출):
   카카오 API로 변경했으나, 사용자의 실제 위치(상암)가 아닌 **Mock 데이터(고양, 강남)**가 지속적으로 노출됨. 프론트엔드와 백엔드 간 통신이 이루어지지 않는 현상 발생.

2. 유령 서버(Zombie Process) 및 포트 충돌:
   백엔드 코드를 수정하고 재실행하려 했으나 [WinError 10048] 각 소켓 주소는 하나만 사용할 수 있습니다 에러 발생. 터미널을 닫았음에도 불구하고 백그라운드에서 서버가 계속 돌아가고 있어 수정 사항이 반영되지 않거나 포트를 점유하고 있었음.

3. 모듈 로딩 및 타입 에러 (Module Resolution Error):
   Chat.tsx에서 location.ts를 import 할 때 빨간 줄 에러 발생. 처음에는 경로(../ vs @/) 문제로 오인하여 시간을 소요했으나, 실제로는 app.py 실행 시 ModuleNotFoundError가 발생하는 등 환경 문제였음.

🛠 해결 (Solution)

1. 원인 파악

• 좀비 프로세스 원인: VS Code 내장 터미널에서 **'휴지통 아이콘(패널 닫기)'**을 눌러 닫았을 때, 화면(UI)만 닫히고 실제 실행 중인 uvicorn 프로세스는 종료 신호(SIGINT)를 받지 못해 백그라운드에 살아있었음. 이 '유령 서버'가 8000번 포트를 계속 잡고 있어서 새 서버가 뜨지 않거나, 프론트엔드가 구버전 서버와 통신함.
• 모듈 에러의 진짜 원인: 경로 문제가 아니라, 참조 대상 파일(location.ts) 내부에 타입 정의(Location, Poi)가 누락되어 컴파일 오류가 발생해 VS Code가 모듈을 인식하지 못한 것임. 또한 백엔드 가상환경에 라이브러리가 설치되지 않았음.

2. 조치

• 좀비 프로세스 사살 및 서버 정상화: netstat으로 8000번 포트를 점유 중인 PID(프로세스 ID) 확인 후 taskkill로 강제 종료하고 python app.py 재실행.
• 코드 및 타입 정상화: src/types/index.ts에 필요한 인터페이스를 추가하여 location.ts의 내부 에러 제거 → 모듈 인식 정상화.
• 환경 구성: 백엔드 의존성 설치 (pip install -r requirements.txt) 및 프론트/백엔드 .env 키 분리 적용.

💻 백엔드 포트 정리 명령어

# [AS-IS] 단순히 터미널 닫기 버튼 클릭 (X)
# 결과: 백그라운드에서 uvicorn 프로세스 생존 (좀비화)

# [TO-BE] 포트 점유 프로세스 확인 및 강제 종료
netstat -ano | findstr :8000
# TCP    0.0.0.0:8000 ... LISTENING    12345 (PID)

taskkill /PID 12345 /F
# 성공: 프로세스(PID 12345)가 종료되었습니다.

💡회고 (Retrospective)

• 프로세스 생명주기: "터미널 창 닫기 ≠ 프로세스 종료"임을 명확히 배움. 특히 uvicorn 처럼 Auto-reload 기능이 있는 서버는 터미널을 닫는다고 죽지 않을 수 있으므로, 반드시 Ctrl + C로 명시적으로 종료하는 습관을 들여야 함.
• 모듈 에러의 본질: "Module not found"는 경로 문제뿐만 아니라, 해당 파일 내부의 문법/타입 오류 때문에도 발생한다는 것을 알게 됨. 경로를 의심하기 전에 파일 내부 상태와 패키지 설치 여부를 먼저 확인해야 함.
• Action Item:
  • 서버 재실행이 안 되거나 동작이 이상할 땐 무조건 netstat으로 포트 상태부터 확인하기.
  • Mock 데이터가 뜰 때는 서버 연결 상태를 알리는 UI(토스트 메시지 등)를 추가하여 디버깅 효율 높이기.