오늘의 목표와 맥락

행사 참여자 관리 서비스의 작성자(관리자) 화면을 손봤다. 처음에는 개별 요청을 하나씩 처리하는 흐름이었다 — 등록 화면 상단 이미지 배치, 이벤트 상세의 진행/종료 버튼 위치, 참여자 목록 표시 방식. 그러다 마지막에 "작성자 화면들의 넓이나 디자인 통합" 이라는 큰 주제로 넘어갔다.

앞의 작은 요청들이 사실 같은 문제의 증상이었다. 화면마다 폭도 제목도 표도 각자 정하고 있었고, 새 화면을 만들 때마다 그중 하나씩을 빠뜨렸다.

---

구현한 내용

등록 화면 상단 정리

사진 위에 행사명을 얹고 그 위에 검은 그라데이션을 깔던 구조를 버렸다. 이미지는 이미지대로 두고, 행사 정보는 그 아래 별도 영역으로 내렸다.

• 이미지 비율을 2:1로 고정해 업로드한 사진마다 높이가 들쭉날쭉하지 않게 했다.
• 좌우를 띄우고 모서리를 12px 둥글렸다.
• 이미지가 없는 행사는 영역 자체를 렌더하지 않는다. 자리표시자 그라데이션이 정보를 주지 않으면서 행사 정보만 아래로 밀어냈고, 화면에 따라 검게 나와 사진이 깨진 것처럼 보였다.

관리자 프로필 사진

작성자 정보에 그룹웨어 프로필 사진을 붙였다. 사진은 관리자 테이블이 아니라 그룹웨어 사용자 동기화 테이블에 있다.

gw_user: Mapped["GwUser | None"] = relationship(
    primaryjoin="foreign(Admin.user_key) == remote(GwUser.user_key)",
    viewonly=True, lazy="selectin",
)

이 관계를 모델에 두자 관리자 정보를 직렬화하는 모든 지점(로그인 사용자, 이벤트 작성자, 관리 콘솔)이 한 번에 사진을 갖게 됐다. 마이그레이션이 필요 없다.

참여자 목록을 화면으로

모달로 열던 명단을 상세 화면에 그대로 펼치고 페이징을 붙였다. 처음엔 20명씩으로 만들었다가 "너무 많다"는 피드백을 받아 10명으로 줄이고 글자도 한 단계 낮췄다.

---

설계와 판단

폭 결정을 레이아웃으로 올린 이유

디자인 문서는 관리자 화면 최대 폭을 1200px로 못박고 있었다. 실제 코드는 이랬다.

화면	실제 폭
대시보드, 이벤트, 상세, 검색, 디자이너	1280px
설정	1024px
설문 목록, 참여자 계정, 로그인 기록	컨테이너 없음

폭이 없는 세 화면은 모두 최근에 추가한 것이다. 페이지가 자기 폭을 정하는 구조에서는 새 화면이 그 규칙을 빠뜨린다. 그래서 폭 결정을 레이아웃 한 곳으로 올리고 페이지의 폭 지정을 전부 제거했다. 앞으로 만드는 화면은 아무것도 하지 않아도 폭이 맞는다.

같은 판단으로 제목 블록과 표 조각도 공통 컴포넌트로 뽑았다. 표 머리글 정의가 여섯 개 파일에 흩어져 있었고, 셀 글자 크기가 화면마다 달랐다.

관리자 표의 일시 표기

한국어 로케일 표기(2026년 8월 12일 오후 2:35)와 고정폭 표기(2026-08-12 14:35)가 섞여 있었다. 관리자 표는 고정폭으로 통일했다. 로케일 표기는 값마다 폭이 달라 열이 흔들리고, 여러 줄을 세로로 훑을 때 자릿수가 맞지 않는다.

반대로 응답자 화면은 친근한 표기를 유지했다. 한 번에 한 건만 보는 화면이라 기준이 다르다.

정렬 타이브레이커

참여자 목록을 나눠 보여주기로 하면서 정렬이 문제가 됐다. 기존 정렬은 등록 시각 하나뿐이었다.

같은 시각에 등록한 사람들의 순서가 조회마다 달라질 수 있다.

한 화면에 전부 뿌릴 때는 드러나지 않던 것이, 페이지를 끊는 순간 행이 겹치거나 새는 버그가 된다. 실패하는 테스트를 먼저 쓰고 id 역순 타이브레이커를 넣었다.

---

문제와 해결

토큰 이름이 직관과 반대였다

가장 뼈아팠던 실수다. 이 프로젝트에서 primary는 잉크 블랙이고 secondary가 인디고다. 이걸 모르고 병렬 작업자에게 "잉크 블랙 알약 버튼으로 바꿔라"며 인디고 토큰을 지시했다. 목록 화면의 주 행동 색이 뒤집힐 뻔했고, 감사 결과와 대조하다 잡아 되돌렸다.

공통 어휘를 다루는 지시는 이름이 아니라 값을 확인하고 내려야 한다.

보이지 않던 호버

이벤트 목록의 표 행 호버가 surface-bright였는데, 이 토큰의 값이 #ffffff다. 카드 배경도 흰색이라 호버 시 아무 변화도 일어나지 않았다. 정상 동작처럼 보였을 뿐 기능이 죽어 있던 셈이다.

존재하지 않는 토큰

text-label-lg를 쓰는 곳이 다섯 군데 있었는데, 이 토큰은 정의된 적이 없다. 클래스가 생성되지 않으니 글자 크기 지정이 조용히 사라진다. 오류도 경고도 없어서 발견되지 않고 있었다.

감사 보고를 그대로 믿지 않기

병렬 감사에서 "카드에 바깥 그림자를 쓴 위반"으로 여러 건이 올라왔다. 확인해 보니 해당 그림자 토큰은 안쪽 헤어라인으로 재정의돼 있어 위반이 아니었다. 보고를 받은 쪽에서 근거를 다시 확인하지 않았다면 멀쩡한 코드를 고칠 뻔했다.

---

검증한 내용

• 백엔드 테스트 139개 전부 통과. 오늘 추가한 것은 프로필 사진 조인 3건과 정렬 타이브레이커 1건이며, 모두 실패하는 테스트를 먼저 작성했다.
• 프론트엔드 타입 검사·린트·프로덕션 빌드 통과.
• 표의 빈 상태 colSpan을 실제 열 개수와 대조했다. 조건부로 열이 하나 빠지는 화면까지 포함해 전부 일치.
• 클릭 가능한 컨트롤에 옛 반경이 남았는지 파서로 훑어 0건 확인.
• 무한스크롤, CSV 내보내기, 페이징, 필터, 행 클릭 등 리팩터링 대상 화면의 주요 핸들러 잔존 확인.

한계도 남겨 둔다. 화면을 눈으로 확인하지는 못했다. 관리자 화면이 사내 인증 뒤에 있고, 대신 로그인하지 않기로 했기 때문이다. 코드 검증까지가 오늘 할 수 있는 전부였다.

독립적인 코드 리뷰를 맡긴 작업자는 두 번 요청했으나 결과를 내놓지 못한 채 종료했다. 회귀 검증은 결국 직접 했고, 제3자의 시선은 받지 못했다.

---

다음 단계

• 관리자 화면 전반의 시각 확인 — 특히 설정 화면의 추가 버튼이 섹션마다 색이 갈리는 것이 의도한 위계인지
• 이벤트 태그 칩이 사용자가 고른 배경색 위에 흰 글씨를 강제하는 문제. 밝은 색을 고르면 글자가 읽히지 않는다
• 설문 디자이너의 드래그 핸들 반경 — 규칙 범위 밖이라 남겨 뒀으나 재검토 여지가 있음
• 표가 없는 화면의 빈 상태와 표 안의 빈 상태가 두 가지 형태로 공존 중. 통합할지 그대로 둘지 판단 필요