3 min read · 668 words
#541
이 글은 프론트엔드 페이로드 누락으로 인해 백엔드 독트린이 제대로 적용되지 않아 어려움을 겪는 분들을 위한 기록입니다. 내가 겪었던 문제를 해결한 과정을 통해 유사한 상황에 처한 분들이 즉시 해결책을 찾을 수 있도록 돕고자 합니다.
문제 상황
내가 개발 중이던 시스템에서는 사용자가 카테고리 선택기(selector)를 통해 글의 카테고리를 지정하면, 백엔드 프롬프트에 해당 카테고리가 반영되어 글의 구조나 내용에 대한 독트린(doctrine)이 동적으로 적용되도록 설계했습니다. 예를 들어, '뉴스' 카테고리를 선택하면 날짜 기반 요약과 출처 명시가 필수로 요구되는 독트린이 적용되고, '활용 팁' 카테고리에는 8개 섹션으로 구성된 특정 구조가 적용되는 식입니다. 하지만 실제 운영 환경에서 사용자가 '뉴스'를 선택해도 시스템은 여전히 '활용 팁'의 8-섹션 구조를 따르는 현상이 발생했습니다. 내가 확인해 보니, 프론트엔드에서 백엔드로 전송하는 페이로드에 'category' 필드가 누락되어 있었고, 백엔드는 기본값인 '활용 팁' 독트린만을 모든 글에 일괄 적용하고 있었습니다. 이는 정보 시스템의 결정론적 동작(deterministic behavior)을 저해하는 심각한 문제였습니다.
에러 증상
가장 명확한 증상은 'Writing' 탭에서 사용자가 '뉴스' 카테고리를 선택했음에도 불구하고, 생성된 글이 '활용 팁' 카테고리에 할당된 8-섹션 구조를 그대로 사용한다는 점이었습니다. '뉴스' 글에 필수적인 '날짜 기반 요약'이나 '외부 출처 명시'와 같은 독트린이 전혀 적용되지 않았습니다. 백엔드 로그를 확인했을 때, 카테고리 정보가 제대로 전달되지 않아 항상 기본 카테고리 독트린이 활성화되는 것을 확인할 수 있었습니다.
환경
내가 이 문제를 겪은 환경은 다음과 같습니다. 프론트엔드는 JavaScript 기반의 웹 애플리케이션(writer.js)으로 구성되어 있었고, 백엔드는 여러 엔드포인트(generate-title, outline, publish)를 통해 프론트엔드와 통신하는 구조였습니다. 특히, 글의 제목 생성, 개요 생성, 그리고 최종 발행을 담당하는 세 가지 주요 엔드포인트에서 이 문제가 발생했습니다. 이들 엔드포인트는 모두 프론트엔드에서 전송하는 JSON 페이로드를 기반으로 동작했습니다.
시도했지만 실패한 방법
처음에는 백엔드의 기본 카테고리 설정을 변경해 보았습니다. 기본값을 '뉴스'로 변경하자, '뉴스' 글에는 정상적으로 날짜 기반 요약과 출처 명시 독트린이 적용되었습니다. 그러나 이 경우 '활용 팁' 글이 '뉴스' 독트린을 따르는 불일치(mismatch) 문제가 발생했습니다. 이는 문제의 근본 원인이 백엔드의 기본값 설정이 아니라, 프론트엔드에서 카테고리 정보 자체가 백엔드로 전달되지 않는다는 것을 명확히 보여주었습니다. 결국, 백엔드의 기본값 변경은 임시방편일 뿐, 시스템 전체의 일관성을 해치는 해결책이었습니다.
최종 해결
문제의 근본 원인은 프론트엔드(writer.js)에서 백엔드로 전송하는 페이로드에 'category' 필드가 누락되어 있었다는 점이었습니다. 이를 해결하기 위해 나는 writer.js 파일의 generate-title, outline, publish 세 가지 엔드포인트로 데이터를 전송하는 부분에 category: window.TSP_WRITER_CATEGORY 필드를 추가했습니다. window.TSP_WRITER_CATEGORY는 프론트엔드에서 현재 선택된 카테고리 값을 저장하는 전역 변수였습니다. 또한, 백엔드에서는 OutlineBody와 GenerateTitleBody 스키마에 category 필드를 추가하고, 이 필드 값을 활용하여 _category_doctrine() 헬퍼 함수를 호출하도록 로직을 수정했습니다. 이로써 백엔드는 프론트엔드로부터 정확한 카테고리 정보를 받아 해당 카테고리에 맞는 독트린을 동적으로 적용할 수 있게 되었습니다. 이는 정보의 무결성(data integrity)을 확보하고 시스템의 예측 가능성(predictability)을 높이는 중요한 조치였습니다.
사용한 코드 또는 프롬프트
다음은 writer.js에서 백엔드 페이로드에 카테고리 필드를 추가하기 위해 내가 수정한 코드입니다. 이 변경을 통해 프론트엔드에서 선택된 카테고리 정보가 백엔드로 정확히 전달될 수 있었습니다.
# writer.js
# 이전 (말썽난 코드)
const body = JSON.stringify({ topic, keywords, ... });
# 수정 (바로잡은 후)
const category = window.TSP_WRITER_CATEGORY || "활용 팁";
const body = JSON.stringify({ topic, keywords, ..., category });검증 결과 및 현재 상태
수정 후, 나는 /api/writer/outline 엔드포인트를 호출하여 백엔드가 카테고리별 프롬프트 접두사를 정확하게 주입하는지 확인했습니다. '뉴스' 카테고리를 선택했을 때, 백엔드에서 외부 출처 필수 독트린이 올바르게 적용되는 것을 확인했습니다. 현재 이 문제는 완전히 해결(fixed)되었으며, 시스템은 사용자가 선택한 카테고리에 따라 정확한 독트린을 적용하고 있습니다.
같은 문제 겪는 분들에게
만약 여러분의 시스템에서도 프론트엔드에서 전달하는 데이터가 백엔드 로직에 제대로 반영되지 않는다면, 가장 먼저 프론트엔드 페이로드에 필요한 필드가 모두 포함되어 있는지, 그리고 백엔드에서 해당 필드를 올바르게 파싱하고 활용하는지를 확인해 보십시오. 특히, 동적으로 변경되어야 할 중요한 정보(예: 카테고리, 사용자 설정 등)가 기본값으로만 처리되고 있다면, 데이터 흐름의 시작점인 프론트엔드 페이로드 구성을 면밀히 검토하는 것이 중요합니다. 나의 경험상, 이러한 문제는 종종 작은 필드 누락에서 시작되는 경우가 많습니다. 데이터 무결성(Data Integrity)은 시스템의 신뢰성을 결정하는 핵심 요소임을 잊지 마십시오.