모바일 QR 통합 설계로 트랙 분기 흐름 단순화

설계 문서 하나 작성하는 데 반나절 넘게 쏟았다.

트랙 2와 트랙 3를 별도 UI 흐름으로 두느냐, 단일 흐름으로 합치느냐 — 이게 생각보다 결정이 쉽지 않았다. 처음엔 "그냥 분리하면 되지 않나" 싶었는데 막상 모바일 QR 시나리오를 전부 그려보니 사용자 입장에서 두 트랙의 진입 맥락이 생각보다 많이 겹쳤다.

왜 단일 UI 흐름으로 합치기로 했나

트랙 2와 트랙 3가 각각 어떤 맥락에서 실행되는지 먼저 짚고 넘어갔다. 팀원들이랑 화이트보드 앞에서 유저 시나리오를 쭉 나열했을 때, 두 트랙의 분기 조건이 결국 QR 스캔 이후 단계에서 갈리는 거지 UI 진입 자체는 동일하다는 걸 발견했다.

두 트랙을 분리 설계했을 때 생기는 문제들:

• 진입점이 두 개라 사용자가 "내가 어떤 트랙인지" 알아야 하는 맥락 전환 비용 발생
• 각 트랙별로 QR 스캔 컴포넌트를 따로 유지하면 공통 버그 픽스 시 두 군데를 손대야 함
• 모바일 특성상 화면 공간이 좁기 때문에 분기 안내 UI를 추가로 쑤셔 넣으면 오히려 복잡해짐
• QA 시나리오가 두 배로 늘어나 테스트 커버리지 관리 부담

반대로 단일 흐름으로 합쳤을 때 얻는 것:

• 사용자는 QR 찍는 행위 하나만 하면 되고, 트랙 분기는 시스템이 내부적으로 처리
• 공통 QR 스캔 레이어 하나로 관리 → 유지보수 포인트 축소
• 화면 흐름 단순화 → 신규 팀원이 온보딩할 때 이해하기 쉬움

이 판단을 설계서에 명시적으로 적어두는 게 중요하다고 봤다. 나중에 "왜 합쳤어요?"라는 질문이 반드시 나오기 때문에.

설계서에 담은 것들

zlgoon_mobile_qr_integration_plan.md 한 파일이지만 내부 구성은 꽤 세분화했다.

특히 미결 사항 섹션을 따로 빼는 게 습관인데, 설계서에서 "다 해결된 척"하면 나중에 구현 단계에서 터진다. 모르는 건 모른다고 적어두는 편이 팀 전체 인식 맞추기에 훨씬 낫다.

분기 조건 부분은 코드는 아직 없지만 의사코드 수준으로라도 남겨뒀다.

scan_result = qr_scan()

if scan_result.type == TRACK_2_IDENTIFIER:
    route_to_track2_flow(scan_result.payload)
elif scan_result.type == TRACK_3_IDENTIFIER:
    route_to_track3_flow(scan_result.payload)
else:
    show_unsupported_qr_error()

이 정도만 적어둬도 구현자 입장에서 "아, 분기를 여기서 치는구나"가 명확해진다. 설계서에 의사코드 한 블록 있고 없고 차이가 생각보다 크다.

설계 문서 작업에 대한 짧은 회고

솔직히 docs 커밋은 체감 성취감이 낮다. 코드를 짠 것도 아니고, 화면에 뭔가 나오는 것도 아니니까. 근데 팀 입장에서는 이게 없으면 구현 단계에서 각자 해석이 달라져서 나중에 정합성 맞추는 데 훨씬 큰 비용이 든다.

특히 모바일 QR처럼 하드웨어 스캔 → 서버 분기 → UI 반응이 연결되는 흐름은, 구현 직전에 팀 전체가 같은 그림을 보고 있어야 한다. 이걸 말로만 공유하면 회의 끝나고 각자 기억이 다르다.

문서 작업이 지루하게 느껴지는 순간에도, 이걸 안 쓰면 미래의 내가 다시 설명하는 데 더 많은 시간을 쓴다는 걸 경험으로 알기 때문에 계속 쓰게 된다.

다음은 이 설계서 기반으로 구현 태스크를 쪼개는 작업이다.