프론트/백 경계 정리와 Docker 배포 — 대량 메일 자동화 (3)

FastAPI와 React 사이 경계를 다잡는다. TypeScript 인터페이스와 Pydantic 스키마를 snake_case로 글자까지 일치시켜 직렬화 버그를 없애고, axios /api 상대 경로와 Vite 프록시로 주소를 통일한다. 블로킹 SMTP를 asyncio.to_thread로 격리, 한글 폰트·OpenCV를 멀티스테이지 Docker 이미지에 봉인하고 Nginx 웹소켓 프록시까지 정리한다.

 

3편: 경계와 배포

1편 템플릿 치환, 2편 PDF 첨부에 이어, 시리즈 마지막은 코드 위생, 프론트/백 경계, 그리고 Docker 배포다. 기능을 다 만든 뒤 "어떻게 안정적으로 굴릴 것인가"의 영역이다.

프론트/백 경계 — 가장 흔한 버그의 원천

2편에서도 짚었지만, 이 프로젝트에서 반복된 버그의 큰 줄기는 프론트엔드와 백엔드 사이 경계의 불일치였다.

• 필드명 규칙: 프론트(camelCase) vs 백엔드(snake_case). PDF 첨부에서 필드명이 어긋나 첨부가 조용히 실패했다. → snake_case로 통일.
• API 타입: 프론트의 타입 정의와 백엔드 응답 모양이 어긋나면 런타임에서야 터진다. → 타입과 URL을 점검해 맞췄다.

경계를 지나는 데이터의 "모양"을 양쪽이 똑같이 알고 있어야 한다는, 단순하지만 자주 어기는 원칙이다.

코드 위생

기능을 붙이는 중간중간 코드도 정리했다.

• 불필요한 @ts-ignore 제거 — 타입 오류를 가리지 않고 제대로 해결.
• 디버그용 console.log 제거.
• 변수명의 군더더기(불필요한 언더스코어 등) 정리.

기능 개발 중에 쌓이는 이런 부스러기를 그때그때 걷어내야, 나중에 "이건 왜 있지" 하는 코드가 안 남는다.

테스트

PDF 첨부 같은 핵심 기능은 통합 테스트로 발송 흐름 전체를 검증했다. 메일 발송은 외부(SMTP)에 의존해 단위 테스트만으론 부족하다. 업로드 → 매칭 → 발송으로 이어지는 경로 전체가 한 번에 도는지 확인하는 통합 테스트가, 경계 버그를 잡는 데 효과적이었다.

배포 — Docker

메일 발송 서버는 환경(OS·런타임·의존성·로케일)에 특히 민감하다. "내 PC에서는 되는데" 문제를 없애기 위해 Docker로 컨테이너화했다.

FROM python:3.x-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# 업로드 디렉토리(PDF 하위 포함)는 시작 시 생성 — 2편의 그 디테일
CMD ["python", "-m", "app"]

배포 스크립트로 빌드·실행을 한 번에 처리하게 해서, 같은 이미지가 어디서든 동일하게 돌도록 했다. 의존성과 실행 환경을 이미지에 고정하니, 환경 차이로 인한 변수가 사라졌다.

정리하며

기능 너머의 "운영 가능성"을 만든 마지막 단계였다.

• 프론트/백 경계의 데이터 모양 통일 — 가장 흔한 버그를 구조적으로 차단.
• 코드 위생 — 개발 중 부스러기를 그때그때 정리.
• 통합 테스트 — 외부 의존이 있는 흐름은 경로 전체를 검증.
• Docker — 환경 차이를 이미지로 봉인.

시리즈를 마치며

세 편에 걸쳐 대량 메일 도구를 정리했다. 핵심 교훈은 이 도구의 난이도가 "메일 보내기"가 아니라 개인화 데이터와 첨부의 정확한 매칭, 그리고 경계의 일관성에 있다는 점이었다. 발송 채널이나 첨부 종류가 늘어도 같은 패턴(스키마 → API → store → 발송 연동)으로 확장할 수 있게 정리한 점이 만족스러웠다.