미국 화물 포워더 한 곳의 운영 대시보드를 손봤다. 컨테이너가 지금 어디에 앉아 있고, 오늘·내일 배송이 몇 건이고, 어떤 건이 밀렸는지를 한 화면에서 보는 물건이다. 담당자가 아침마다 이걸 보고 그날 순서를 정한다.
그래서 이 화면의 버그는 “보기 싫음”이 아니라 틀린 판단이 된다. 이번에 잡은 것도 예쁘게 고치는 작업이 아니라, 화면이 데이터를 거짓말하고 있던 세 군데를 막는 작업이었다.
구조는 단순하다. n8n 워크플로가 원천 시트를 읽어 dashboard.json 하나를 만들어 오브젝트 스토리지에 올리고, 자체포함 index.html 한 장이 그걸 fetch 해서 그린다. 빌드 스텝도 프레임워크도 없다. 이 단순함이 장점인데, 이번 버그의 원인이기도 했다.
1. 표에 undefined가 떠 있었다
“내일 배송” 표가 이랬다.
DATA.tomorrow.map(r =>
`<tr><td>${r.cont}</td><td>${r.dest}</td>
<td>${r.req}</td><td>${r.trans||'—'}</td></tr>`
)
Req Del 칸엔 전 행이 undefined, Carrier 칸엔 전 행이 —였다. 빌더가 tomorrow 배열에는 req·trans를 더 이상 보내지 않고 있었다. today에만 있다.
프론트가 죽지 않은 게 문제였다. 템플릿 리터럴은 없는 키를 만나면 문자열 "undefined"를 성실하게 찍는다. ||'—' 같은 방어는 한술 더 떠서, 필드가 사라진 것과 값이 빈 것을 구분 불가능하게 만든다. 담당자 눈에는 “차량 배정이 아직 안 됐구나”로 보였을 것이다.
실제로 오는 필드를 확인하고 열 구성을 다시 짰다. 없는 req 대신 도착 후 경과일을 넣었다 — 컨테이너가 오래 앉아 있을수록 보관료 노출이 커지니, 담당자가 실제로 궁금해하는 숫자다.
// 미국 도착(ATA) 이후 경과일
function daysSince(dateStr, todayStr){
if(!dateStr||!todayStr) return null;
const a=new Date(dateStr.replace(/\./g,'-')), t=new Date(todayStr.replace(/\./g,'-'));
if(isNaN(a)||isNaN(t)) return null;
return Math.round((t-a)/86400000);
}
const ageCls = age>=30 ? 'bad' : age>=14 ? 'warn' : '';
2. 도넛 차트가 36%를 통째로 빼먹었다
이게 제일 고약했다. 업무 유형별 분포를 보여주는 도넛인데, 유형이 두 종에서 세 종으로 늘어난 뒤로 세 번째 유형이 아예 그려지지 않고 있었다. 원이 다 안 채워진 채 한 조각이 비어 있었는데, 그냥 여백처럼 보였다.
원인은 SVG 원을 미리 마크업에 박아두고 id로 찾아 쓰던 구조였다.
const segIds = {A:'donutA', B:'donutB', ETC:'donutETC'};
// ...
const el = document.getElementById(segIds[b.k]);
if(!el) return; // ← 여기서 조용히 사라진다
세 번째 유형은 segIds에 없으니 undefined, getElementById(undefined)는 null, 그리고 if(!el) return이 아무 일도 없었던 것처럼 넘어간다. 콘솔에 경고 한 줄 안 뜬다. 전체 건수의 36%가 그렇게 없는 취급을 받고 있었다.
if(!el) return은 내가 쓴 방어 코드였다. 의도는 “혹시 엘리먼트가 없으면 죽지 말자”였는데, 실제로 한 일은 데이터 누락을 정확히 은폐하는 것이었다. 렌더 루프의 조용한 return은 대부분 이 성질을 갖는다.
고친 방향은 마크업을 지우는 쪽이다. 세그먼트를 데이터에서 동적으로 만든다.
segs.innerHTML = dist.biz.map(b =>
`<circle cx="64" cy="64" r="52" fill="none"
stroke="${BIZ_COLORS[b.k]||BIZ_COLORS.ETC}" stroke-width="16"
stroke-dasharray="0 ${C}" stroke-dashoffset="0" data-k="${b.k}"/>`
).join('');
이제 유형이 네 종이 되어도 조각은 알아서 는다. 색만 모르면 ETC 회색으로 떨어지고, 조각 자체는 절대 사라지지 않는다. 모르는 값은 눈에 띄게 그려야지, 건너뛰면 안 된다.
이 과정에서 색도 갈아엎었다. 기존 두 유형이 보라 두 톤이라 배지만 보고는 구분이 안 됐다. 보라/파랑/청록으로 hue 자체를 분리했다. 채도 차이는 나란히 놓였을 때만 구분되고, 표 안에서 행마다 흩어지면 같은 색으로 읽힌다.
3. 같은 데이터인데 두 표가 다르게 보여줬다
“오늘” 표엔 유형 배지가 아예 없고 “내일” 표엔 있었다. 순서도 달랐다. 같은 컨테이너가 화면 위아래에서 다른 물건처럼 보인다.
두 표의 열 순서를 맞추고, 배지 클래스 매핑을 렌더 함수 안에서 빼내 한 곳으로 올렸다.
// 두 표가 같은 색을 쓰도록 한 곳에서 관리한다
const BIZ_BADGE = { A:'b-a', B:'b-b', C:'b-c' };
원래는 {A:'b-a',B:'b-b',C:'b-c'}[biz] 같은 리터럴이 렌더 함수 안에 인라인으로 박혀 있었다. 한 군데면 편한데, 두 번째 표가 생기는 순간 복붙이 된다. 이번 버그 셋 중 둘이 “같은 목록이 여러 곳에 하드코딩되어 있고, 값이 하나 늘 때 한 곳만 고쳐진” 형태였다.
CSS 공용 규칙이 놓은 함정
곁가지 하나. “내일” 표의 컨테이너 번호 열이 30px로 짓눌려 있었다. 범인은 공용 규칙이었다.
tbody tr.main td:first-child{ width:30px } /* 펼침 화살표 칸용 */
화살표가 있는 표를 기준으로 쓴 규칙인데, 화살표가 없는 표에선 첫 칸이 데이터 칸이다. 해제하고 table-layout:fixed로 열폭을 명시했다. 주석도 같이 남겼다 — 왜 해제했는지 적어두지 않으면 다음에 또 붙는다.
그래서 문서를 한 장 썼다
세 버그의 원인은 결국 하나다. 빌더가 무엇을 보내는지가 어디에도 적혀 있지 않았다. 프론트는 예전 모양을 기억하고 있었고, 빌더는 조용히 바뀌었다.
DATA-CONTRACT.md 한 장을 만들어 실측으로 채웠다.
today[] cont biz dest pu req act delivered lfd route ata empty storage bl resched reason
tomorrow[] cont biz dest from ata pu stat ← req·resched 없음
여기에 제일 중요한 걸 같이 적었다. 원천 시트의 두 날짜 컬럼이 이름과 의미가 서로 반대다. (실제 필드명은 바꿔 적는다.)
| 시트 컬럼 | 실제 의미 | 쓰나 |
|---|---|---|
est_finish |
배송 요청·약속일 | ✅ 대시보드와 EDI 전송이 전부 이걸 쓴다 |
req_finish |
예상 도착일(담당자 감으로 기입) | ❌ 실적보다 평균 9.5일 이르다 |
이름만 보면 정확히 거꾸로 고르게 되어 있다. 교차검증도 같이 적어뒀다 — 같은 날 건들의 est_finish는 전부 그날 하루로 모이는데, req_finish는 3주에 걸쳐 흩어져 있었다.
이런 건 코드 주석에 적어봐야 소용이 없다. 다음에 이 데이터를 건드릴 사람(대개 나 아니면 에이전트)이 먼저 읽는 자리에 둬야 한다.
배포본이 최신인지는 바이트로 확인한다
정적 호스팅 특성상 경로를 아무거나 쳐도 200이 떨어진다. 미매칭 폴백이라 전부 루트와 같은 파일인데, 이걸 모르면 “다른 대시보드를 덮어쓰는 거 아닌가”로 30분을 쓴다. 확인은 단순하게 했다.
curl -s https://<배포주소>/ | wc -c
git show <커밋>:dashboard/index.html | wc -c
단일 파일 배포라 크기 비교만으로 배포본 버전이 나온다.
한계 · 다음 계획
- 계약이 문서일 뿐 강제가 아니다. 빌더가 필드를 또 빼면 여전히 화면에서 조용히 사라진다. 프론트 진입점에 필수 키 검증을 넣고, 없으면 패널에 눈에 띄게 표시하는 게 다음 순서다.
- 도넛 합계 검증이 없다. 조각 합이 total과 다르면 경고를 띄우는 한 줄이면 이번 버그는 첫날 잡혔다.
- 리스케줄 건이 “내일” 목록에서 구분되지 않는다. 원래 다른 날짜였다가 옮겨온 건인데 표에선 평범한 내일 건으로 보인다. 빌더에 두 필드를 추가하면 끝나는 일이라 다음 작업으로 남겼다.
- 배지 색은 눈으로만 확인했다. 대비비 실측은 아직이다.
정리
하루 작업이었지만 남는 건 한 줄이다. 렌더 코드에서 조용히 넘어가는 분기는 버그가 아니라 버그 은폐 장치다. 모르는 값은 회색으로라도 그리고, 없는 필드는 빈칸 대신 티나게 표시한다. 그리고 데이터 계약은 만든 사람이 기억하는 대신 파일로 남긴다 — 기억은 빌더가 바뀌었다는 걸 모른다.
FAQ
Q. if(!el) return 같은 방어 코드가 왜 문제인가?
엘리먼트가 없는 상황이 “정상”일 때만 맞는 코드다. 렌더 루프에서는 대개 정상이 아니라 데이터가 늘었거나 마크업이 어긋난 상황이다. 조용히 넘기면 화면에서만 사라지고 로그엔 아무것도 안 남는다. 최소한 console.warn을 남기거나, 이번처럼 마크업 의존 자체를 없애는 게 낫다.
Q. 차트 조각을 마크업에 미리 박아두는 게 왜 나쁜가?
카테고리 목록이 코드의 두 군데(마크업·id 매핑)에 복제되기 때문이다. 데이터에 새 값이 들어오면 두 곳 다 고쳐야 하는데, 안 고쳐도 아무도 안 알려준다. 데이터에서 동적으로 생성하면 목록의 소유자는 데이터 한 곳뿐이다.
Q. 데이터 계약 문서는 스키마 검증(JSON Schema 등)으로 대체 가능한가?
검증은 “형식이 맞는가”만 본다. 이번 건의 핵심은 est_finish가 이름과 달리 약속일이라는 의미였고, 그건 스키마로 표현되지 않는다. 검증은 검증대로 넣고, 의미·함정·실측 근거는 문서로 남기는 게 맞다.
Q. 빌드 스텝 없는 단일 HTML 대시보드, 계속 쓸 만한가?
이 규모에선 그렇다. 배포가 파일 하나 올리기고, 롤백이 이전 커밋 올리기고, 버전 확인이 wc -c다. 다만 타입 체크가 없어서 이번 같은 필드 불일치는 런타임까지 간다. 그 비용을 계약 문서와 진입점 검증으로 메우는 거래로 보고 있다.