어드민 대시보드, 폰트부터 데이터 흐름까지 한 번에 정비한 날

오늘 오후 5시대는 어드민 대시보드를 "쓸 만한 수준"으로 끌어올리는 데 집중한 시간이었다. 시작은 단순한 폰트 404 오류 하나였는데, 뚜껑을 열어보니 hydration 이슈, 디자인 정책 부재, 데이터 적재 문서화까지 줄줄이 엮여 있었다. 결국 한 시간 동안 UI 레이어부터 운영 지식 문서까지 전 범위를 건드리게 됐다.

왜 폰트 하나로 이렇게 깊게 들어갔나

처음 신호는 S-Core Dream 폰트가 브라우저 콘솔에서 404를 뱉는 것이었다. woff 파일명이 실제 파일 풀네임과 달라서 생긴 단순 오타였지만, 고치면서 globals.css를 열어보니 본문과 제목 폰트가 뒤섞인 채로 선언되어 있었다.

/* 수정 전: 폰트 역할 구분 없이 혼재 */
font-family: 'S-Core Dream', 'Pretendard', sans-serif;

/* 수정 후: 역할 명확 분리 */
/* 제목 → S-Core Dream */
/* 본문 → Pretendard */

이걸 정리하면서 아예 디자인 폴리시를 CLAUDE.md에 문서화했다. "어디에 어떤 폰트를 쓰는가"가 코드 안에만 암묵적으로 존재하면 다음 작업 때 또 뒤섞인다.

AutoRefresh와 hydration 문제

폰트 작업과 동시에 대시보드 60초 자동갱신 기능을 붙이려다 Next.js hydration mismatch가 터졌다. AutoRefresh.tsx에서 서버 렌더링 시점과 클라이언트 마운트 시점의 상태가 달라서 생기는 전형적인 패턴이었다.

해결 방식은 간단했다 — 갱신 관련 상태를 클라이언트 마운트 이후에만 초기화하도록 분리. 기능은 제대로 동작하면서 콘솔 경고도 사라졌다.

데이터 흐름 문서화 — admin_db 통합의 맥락

이날 작업에서 가장 중요한 건 사실 bots-infra.md 업데이트였다. 디스코드 cron이 수집한 데이터가 admin_db에 동시 적재된다는 흐름이 코드 안에 이미 구현되어 있었지만, 문서에는 없었다.

대시보드에서 읽어오는 테이블이 6개인데, 이걸 처음 보는 사람은 "이 숫자들이 어디서 오는 거야?"라는 질문부터 시작해야 한다. 그래서 적재 테이블 목록, 읽기 함수 구조, GSC 페이지 연동 방식, S-Core Dream 폰트 사용 정책까지 한 번에 CLAUDE.md에 박아뒀다.

• admin_db 적재 테이블 6개 목록 명시
• 읽기 함수별 역할 정리
• GSC 데이터 페이지 경로 및 연동 방식
• 폰트 정책 (본문 Pretendard / 제목 S-Core Dream)

한 시간을 돌아보며

이날 흐름을 한 줄로 요약하면 "작은 버그 하나가 정책 공백을 드러냈고, 그 공백을 메우는 게 진짜 작업이었다"는 거다. 폰트 404는 10분이면 끝났을 일이지만, 거기서 나온 질문들 — 왜 두 폰트가 섞였지? 대시보드 데이터는 어디서 오지? hydration은 왜 깨지지? — 을 끝까지 따라간 덕에 대시보드가 설명 가능한 구조로 정비됐다. 다음에 누가 이 코드를 건드려도 문서만 보면 맥락을 잡을 수 있다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.