2026-06-26 · DEVELOPMENT RECORD
추천 로직을 브라우저 밖으로 옮긴 이유
추천 규칙이 화면 코드 안에 있으면 버튼을 바꾸는 일과 후보를 고르는 일이 한 덩어리가 된다. 메뉴가 늘어난 뒤에는 ‘화면이 무엇을 보여 줄지’와 ‘서비스가 무엇을 계산할지’를 분리하는 편이 더 안전했다.
서버 이전의 실제 범위
브라우저 안에 있던 추천 계산을 서버로 옮기고, 화면은 메뉴와 추천 응답을 받아 표시하도록 바꿨다. 외부 개발자에게 제공하는 공개 API는 만들지 않았다. 개발 중 사용할 로컬 계산과 운영 서버의 실패 처리도 이때 구분했다.
추천 규칙과 화면이 함께 바뀌고 있었다
초기에는 프런트가 메뉴를 읽고 점수를 계산했다. 빠르게 실험하기에는 편했지만, 추천 후보 구성이나 메뉴 계약을 바꾸면 화면 컴포넌트까지 같이 건드려야 했다. 운영 환경에서 어느 규칙이 실제로 사용되는지도 분명하지 않았다.
데이터가 317개까지 늘자 이 결합은 더 부담이 됐다. 사용자가 보는 이미지 경로와 서버가 보장해야 하는 메뉴 속성은 같은 책임이 아니므로 분리할 필요가 있었다.
계산은 서버, 표시는 프런트
공통 API 계약 타입을 만들고 메뉴 저장소와 추천 서비스를 프런트에 분리했다. Node 기본 HTTP 서버가 카탈로그와 추천을 제공하고, 프런트는 상대 API 경로와 응답 검증을 맡는 구조다.
중요한 선택은 API가 실패했을 때 운영 화면이 조용히 옛 프런트 계산으로 돌아가지 않게 한 점이다. 개발 환경에서는 전환을 돕는 fallback을 허용하되, 운영에서는 서비스 경계가 실제로 실패했음을 드러내도록 제한했다.
- 메뉴 수
- 317개까지 확장 후 정리 준비
- 새 경계
- Node API · 프런트 서비스
- fallback 원칙
- 개발 환경에서만 로컬 대체
프록시부터 후보 수까지 API 경계를 따라 검증했다
추천 계산을 서버 모듈로 옮기며 기존 프런트 유틸리티를 제거했고, Vite proxy와 API 서버를 연결했다. 메뉴 이미지 해석은 프런트 책임으로 남겨 백엔드 계약이 이미지 파일명에 묶이지 않게 했다.
인코딩 검사와 문서 생성 스크립트도 도입했다. 서버로 옮긴 뒤 빌드와 API 요청이 성공하는지, 추천 후보 수와 메뉴 데이터 규칙이 유지되는지 확인했다.
API 경계 뒤에 남은 일
추천 규칙을 바꾸면 응답 타입과 화면의 오류 처리까지 함께 확인해야 했다. 특히 개발용 로컬 계산이 운영에서도 실행되면 서버 오류를 놓칠 수 있어, 환경별 허용 범위를 명시했다.
이전 작업으로 계산과 표시를 분리했지만 요청을 오래 기다리는 문제는 남았다. 캐시와 응답 제한 시간, 배포 환경별 오류 처리는 이후 작업에서 보완했다.
서버 분리가 추천 품질까지 해결하지는 않았다
서버를 추가한다고 추천 품질이 자동으로 좋아지는 것은 아니다. 이 작업은 규칙의 소유자를 분명히 한 것이며, 캐시·장애 대응·서버리스 배포는 아직 남아 있었다.
또한 API 경로를 만들었다고 외부 공개 API가 된 것은 아니다. 이후 공개 응답에서 무엇을 숨기고 어떤 오류를 공통 처리할지는 별도 운영 단계에서 다시 다뤘다.