문제

클라이언트가 로그인 시점과 만료까지 남은 시간으로 만료 시각을 자체 계산해, 기기 시간 오차나 절전 모드 복귀 시 서버 기준과 어긋나 만료 응답을 받는 일이 반복됐습니다. 더 근본적인 결함은 프론트엔드 서버에서 인증 상태가 갱신되어도 클라이언트 쿼리 캐시가 이를 알 수 없다는 점이었습니다. 국소 대응 코드가 계속 늘고 있었고, ISMS 인증 준비로 세션 만료 정책을 명시적으로 정의하고 증빙해야 하는 요건이 더해졌습니다.

검토와 판단

• A

  클라이언트 계산에 여유 버퍼 추가 — 오차는 줄지만 판단 기준이 이원화된 근본 원인이 그대로 남음

• B

  짧은 주기로 세션 유효성 폴링 — 기준은 일원화되나 아무 일이 없어도 인증 API 호출이 계속 발생. 4.5만 사업자 규모에서 상시 비용이 정당화되지 않음

• C (채택)

  서버 응답 기반으로 만료 판단 일원화 — 클라이언트는 판단하지 않고 서버의 거절에만 반응. 추가 호출 없이 기준이 하나로 모임

C의 핵심은 클라이언트에서 판단 로직을 없애는 것입니다. 판단을 서버가 독점하고 클라이언트는 결과만 반영하면, 어떤 보정보다 확실하게 어긋날 여지가 사라집니다.

실행

• 만료 응답에만 반응해 single-flight로 재발급 후 원요청을 재시도하도록 일원화 — 동시 만료에도 재발급은 1회

• 비로그인과 만료를 throw가 아니라 세션 상태 값으로 표현해 인증 상태를 한 곳에서만 읽게 하고, 흩어진 만료 계산과 임시 대응 코드를 한 번의 PR로 전량 제거

• 기존 응답까지 모두 수용하는 구조로 만들어 백엔드가 교체 배포되는 중에도 문제가 없게 함

결과

• 누적된 임시 대응 코드 전량 제거, 새 구조는 문서화해 팀의 기준으로 정착

• 만료되지 않았다고 오판해 보내던 불필요한 인증 API 호출 소멸

• 세션 만료 정책이 코드 한 곳에 명시되어 업계 최초 ISMS 인증 획득에 기여

회고 당연하게 여겼던 기존 구조의 결함을 의심하고 탐구해 재검증하는 경험을 했습니다. 구조가 바뀌어도 운영은 중단 없이 이어져야 했기에 기존과 새 구조를 모두 아우르는 전환까지 함께 설계했고, 그 기준은 혼자 채울 수 없어 기획팀, 백엔드 팀원들과 엣지 케이스를 함께 검토하며 다듬었습니다.

문제

Server Action 기반 API 계층은 백엔드로 REST 요청을 보내기 전 일종의 프록시 서버 역할을 하고 있었습니다. 여기에 세 문제가 겹쳐 있었습니다. 요청이 순차 처리되어 클라이언트에서 병렬로 묶어도 네트워크 워터폴을 피할 수 없었고, 빌드 시 생성된 액션 ID로 참조되어 배포 직후 구버전 클라이언트의 요청이 실패하는 Version Skew가 배포마다 발생했으며, 일반 HTTP 요청이 아니라 MSW 같은 서드파티 라이브러리와 호환이 떨어져 E2E와 스토리북이 각자 다른 방식으로 응답을 흉내내고 있었습니다.

검토와 판단

• A

  Server Action 유지 + 호출 패턴으로 우회 (기존 방식 유지) — 변경량은 가장 적으나 워터폴은 실행 모델의 제약이라 사용법으로 해소되지 않고, Version Skew와 모킹 문제도 그대로 남음

• B

  Route Handler 방식으로 변경 — 앞의 문제는 모두 해결되지만, 기존에 쓰던 zod와 TanStack Query를 위한 래퍼 함수가 추가되어야 하고 타입 안정성이 보장되지 않아 별도 처리가 더 필요함

• C (채택)

  tRPC로 API 계층 교체 — 기존에 쓰던 zod, TanStack Query와 호환되고, HTTP 위라 병렬 요청, 캐싱, MSW가 그대로 동작하며 배포와 무관한 경로로 호출되어 Version Skew가 사라짐. 타입 추론도 유지

판단 기준은 세 문제가 같은 원인에서 오는가였습니다. 셋 모두 Server Action이 일반 HTTP 요청이 아니라는 실행 모델에서 나왔고, 원인이 하나면 우회를 세 번 하는 것보다 원인을 바꾸는 편이 쌉니다.

실행

• 트레이드오프를 정리해 제안하고 팀 방향으로 채택 — 도메인 단위 점진 이관으로 운영 중단 없이 전환하고, 완료 후 기존 인프라를 전량 제거

• 전환 후에야 가능해진 tRPC-MSW 모킹 환경을 구축해 E2E와 스토리북을 단일 핸들러 세트로 통합하고, 개발 서버에서도 모킹이 동작하게 구성

결과

• 프론트엔드 서버로 향하는 요청이 배치로 묶이고 각 요청이 병렬로 흘러, 메인 페이지 네트워크 요청 시간 49% 감소

• 배포 시 요청 실패 해소

• 신규 API에 핸들러 하나만 작성하면 E2E와 스토리북이 함께 동작

• 팀 전체 도메인 전환을 운영 중단 없이 완료

회고 기존 아키텍처를 당연하게 보지 않고 결함을 정의해, 실험으로 검증하고, 그 근거로 팀을 설득해 함께 적용하는 전체 플로우를 경험했습니다. 제안까지 가는 동안 얻을 효과와 전환에 드는 노력을 계속 저울질했고, 앞으로의 구조 제안도 이 순서로 진행하려 합니다.

문제

서비스가 성장하며 선정산 신청 로직이 점점 복잡해졌는데, 응답 모델은 상당수 프로퍼티가 Optional이라 상태별로 어떤 값이 유효한지 코드만으로 알 수 없었습니다. 화면은 값이 있는지 그때그때 확인하며 그렸고, 확인이 빠진 자리에서 표기가 깨졌습니다.

검토와 판단

• A

  Optional 값마다 기본값과 존재 확인을 추가 — 당장의 오류는 막히지만 어떤 조합이 유효한지는 여전히 코드에 없어, 새 상태가 추가되면 같은 자리에서 다시 깨짐

• B (채택)

  Discriminated Union 구조로 재설계 — 상태가 정해지면 유효한 필드가 타입에서 확정되어, 잘못된 조합이 컴파일 단계에서 차단됨

런타임에 확인하던 것을 선언으로 옮기는 것이 핵심이었습니다. 확인 코드는 빠뜨린 자리에서만 문제를 드러내지만, 타입 선언은 빠뜨리는 것 자체가 불가능합니다.

실행

• 신청 응답을 Discriminated Union으로 재설계해 상태별 유효 필드를 타입에 선언하고, 화면의 상태 분기를 명시적으로 재작성

결과

• 잘못된 상태 조합이 타입에서 차단되어 개발 안정성 개선

• 존재할 수 없는 상태가 사라져 가독성 향상

• 새 신청 유형이 들어와도 타입 하나만 추가하면 되는 구조가 됨

회고 복잡해진 메인 로직을 타입 안정성으로 풀어낸 경험이었습니다. TypeScript를 JavaScript의 부가 기능 정도로 여겨왔는데, 타입에는 타입만의 프로그래밍이 필요하다는 것을 배웠습니다. 파싱된 JavaScript 산출물이 그대로여도 타입만으로 개발의 안정성이 달라진다는 것을 체감했습니다.

문제

사용자 액션 없이 조건에 따라 자동 노출되는 오버레이가 늘면서, 조건이 동시에 충족되면 겹쳐 떴고 반드시 처리해야 하는 안내가 다른 오버레이에 묻혔습니다. 쌓임 맥락과 z-index를 오버레이마다 개별 대응했고, 무엇이 우선인지가 어디에도 정의되어 있지 않았습니다. 기획 방향상 이런 오버레이는 계속 늘어날 것이 분명해, 요소가 늘 때마다 재발할 문제였습니다.

검토와 판단

• A

  기존 방식대로 전역 스토어의 플래그로 관리 — 자동 노출 오버레이가 생길 때마다 스토어를 만들거나 고쳐야 하고, 노출 조건이 코드 곳곳에 흩어져 누락되기 쉬움

• B

  큐 방식 순차 노출 — 네트워크 응답 같은 자동 노출 조건이 계속 달라지면서 노출 순서가 매번 바뀌어, 일관된 사용자 경험을 줄 수 없음

• C (채택)

  우선순위 기반 단일 노출 — 조건을 충족한 것 중 최상위 하나만 노출, 나머지는 다음 진입에서 조건을 재평가

설계에 앞서 이 노력이 정당한지부터 확인했습니다. 모달 라이브러리는 많지만 쿼리 응답이나 페이지 진입 같은 조건 노출을 한 번에 관리하는 라이브러리는 없었기에 시간이 많이 소요되는 작업이었으나, 기획팀과 디자인팀에 서비스 방향을 확인해 이런 오버레이가 계속 늘어난다는 결론을 얻은 뒤 직접 설계를 시작했습니다.

실행

• 오버레이 렌더링을 OverlayCoordinator로 중앙화하고, 우선순위를 배열 선언 하나로 정의

• 코디네이터가 렌더하는 위임형과 호출처가 활성 여부만 받아 직접 렌더하는 비위임형(사이드바, 온보딩)으로 나눠 설계

결과

• 오버레이 겹침과 필수 안내 묻힘이 구조적으로 불가능해짐

• 흩어져 있던 쌓임 맥락과 z-index 개별 대응이 사라지고, 선언된 순서만으로 동작이 결정됨

회고 단순히 눈앞의 결함을 고치는 데서 멈추지 않고, 기획팀, 디자인팀과 협업하며 서비스가 커졌을 때 생길 문제까지 미리 파악해 구조 수준에서 개선한 경험이었습니다. 본질을 먼저 정의하면 요소가 늘어도 설계가 흔들리지 않는다는 것을 배웠습니다.

문제

전역적인 UI 변경은 영향 범위를 사람이 눈으로 확인하고 있었고, E2E가 다양한 환경으로 늘어나며 CI 실행 시간이 테스트 수에 비례해 증가해 GitHub Actions 리소스와 실행 시간 사이의 균형을 잡기 어려웠습니다.

검토와 판단

• A

  기존 방식 유지 — 테스트 수와 환경이 늘어나는 만큼 실행 시간이 그대로 늘어남

• B

  고정 샤드 증설 — 테스트가 커질 때마다 알맞은 크기로 샤드를 다시 조정하는 작업이 계속 필요함

• C (채택)

  샤드 수 동적 산출 — 테스트 수에 비례해 샤드가 자동 배정되어, 러너 리소스와 실행 시간의 트레이드오프를 값 하나로 조절

시각적 회귀 테스트는 CI에 넣으면 스냅샷 관리의 복잡성이 늘고, CI에 올리기 전에 로컬에서 검사하려면 러너 환경을 도커 같은 도구로 맞춰야 하는 부담이 생깁니다. 그래서 로컬 검증 도구로 구성해 전역 UI 변경이 있을 때 일괄 비교하는 쪽을 택했습니다.

실행

• 샤드 수를 테스트 개수로 동적 산출하고, 중복 실행 제거, 워커 병렬화, 픽스처 중복 파싱 제거로 CI 청구 시간 감축

• 시각적 회귀 테스트를 로컬 도구로 구성해 커맨드를 문서화하고, 과정을 회사 기술 블로그에 정리

결과

• 다양한 환경이 추가되어 테스트 수가 3배 이상 늘어도 CI 실행 시간은 오히려 30% 단축

• 전역적인 UI 변경의 회귀를 사람의 눈이 아니라 배포 전 일괄 비교로 확인하게 됨

회고 검증 도구는 관성적으로 CI에 넣기 쉽습니다. 도구를 통상적인 자리에 두는 대신, 팀의 개발 환경을 따져 문제에 맞는 자리를 찾는 판단을 연습한 작업이었습니다.