[Feat/#105] 학생회비 계좌 송금 플로우 화면 구현

[xeoxxn]

#️⃣연관된 이슈

• Closes 학생회비 계좌 송금 플로우 화면 구현 #105

🎯 해결하려는 문제가 무엇인가요?

홈의 "학생회비 납부하기"(3147:146285)를 눌렀을 때 갈 화면이 코드에 하나도 없었다. Figma에는 계좌 송금 플로우가 9개 프레임으로 그려져 있다.

PG 결제가 아니라 토스 딥링크로 송금 → 학생회가 3일 이내 수동 확인하는 방식이고, 남은 학기 수에 따라 납부 금액이 달라져서 학점이수현황 캡처를 함께 제출받는다.

구현 화면

❓ 왜 해결해야 하나요?

학생회비 납부는 홈 진입점이 이미 디자인에 있는 주요 플로우인데, 눌러도 갈 데가 없다.

⭐ 어떻게 해결했나요?

/fee/transfer/semester     남은 학기 수          3562:162833
/fee/transfer/transcript   학점이수현황 업로드    3562:162845 · 3562:162891
/fee/transfer/toss         토스 이동 안내        3562:163025 · 3562:163046
/fee/transfer/confirm      송금하셨나요?         3562:162973
/fee/transfer/complete     확인요청 완료         3562:163013

• FeeTransferStepLayout으로 다섯 화면을 묶었다. 전부 뒤로가기 헤더 → 12px → (일러스트) 제목·설명 → 본문 → 하단 고정 버튼 구조가 같고 간격과 문구만 다르다. 간격은 Figma가 화면마다 8/12/16으로 다르게 잡아둬서 contentGap 유니온 타입으로 받는다.
• 업로드 전/후와 토스 안내/실패는 라우트를 나누지 않았다. 각각 한 화면의 상태 차이지 별개 화면이 아니다.
• 확인요청 완료 화면은 공용 ResultScreen을 쓴다. 체크 모션이 신청 완료 화면들과 같은 Figma 메인 컴포넌트(Circle Check Motion 1712:192849)의 인스턴스라 CompleteCheck를 그대로 재사용했다.
• K-스마트멘토 이동 확인 모달도 공용 ConfirmModal이다. Figma 인스턴스(3562:162972)가 기존 Modal(995:34701)과 같은 311×190이다.
• 이미지 미리보기는 라우트가 아니라 포털 오버레이다. 뒤로가기로 업로드 단계가 사라지면 안 된다.

라우트를 새로 정한 근거

화면설계서(687:20584)에는 경로 컬럼이 아예 없다. 7개 페이지 텍스트 노드 약 19,000개를 /경로 패턴으로 훑어도 라우트 문자열이 0건이다. 그래서 용어 사전(terminology.md)의 회비 납부 → fee와 "프론트 라우트 경로: /{코드 용어}" 규칙으로 정했다.

🧩 이 PR의 한계 & 트레이드오프

• 외부 연동 주소가 전부 비어 있다 — 토스 송금 딥링크, K-스마트멘토 주소. FEE_EXTERNAL_LINKS 상수에 빈 문자열로 두고 값이 있을 때만 열도록 했다(빈 창이 뜨지 않는다). 토스 딥링크는 학생회 계좌와 납부 금액 규칙(남은 학기 수에 따라 달라진다)이 정해져야 만들 수 있다.
• 업로드 API가 없다. 고른 파일을 화면 state로만 들고 있고, 미리보기는 objectURL로 띄운다(언마운트 시 revokeObjectURL). 연동 때 FeeTransferTranscriptScreen에서 업로드 요청을 보내면 된다.
• 단계 간 입력값이 아직 소비되지 않는다. 남은 학기 수는 navigate(..., { state })로 넘기지만 받는 쪽이 없다. API가 붙으면 그 자리에서 쓴다.
• 토스가 열렸는지 확실히 알 수 없다. 딥링크 특성상 브라우저가 결과를 안 알려줘서 window.open 반환값으로만 판정한다. 실패 화면은 그 경우와 링크가 비어 있는 경우에 뜬다.
• 송금 확인 화면 일러스트의 모션이 빠져 있다. 아래 리뷰 포인트 참고.
• 남은 학기 수 검증을 1~99로 뒀다. 실제 학적 기준이 있으면 맞춰야 한다.

⛓️ 기존 기능에 미치는 영향

• ConfirmModal·ResultScreen 설명에 whitespace-pre-line을 붙여 \n을 살렸다. 기존 사용처(행사·사물함 결과 화면, 빌릴게·열린피드백 모달)는 모두 한 줄 문구라 렌더링 변화가 없다(description=에 \n을 쓰는 곳이 0건인 것을 grep으로 확인).
• index.css에 --color-blue-99 토큰이 하나 늘었다. 기존 토큰은 건드리지 않았다.
• 나머지는 전부 신규 파일이고, router.tsx에 라우트 5개가 추가됐다.

🔀 Edge Case & 실패 시나리오

• 남은 학기 수에 문자를 섞어 쳐도 숫자만 걸러 두 자리까지만 받는다. 비었거나 0이면 "다음"이 비활성이다.
• 같은 파일을 연속으로 다시 고를 수 있다(input.value를 비워서 change가 다시 터지게 했다).
• 업로드한 이미지를 지우면 "다음"이 다시 비활성으로 돌아간다.
• 토스 링크가 비어 있거나 팝업이 막히면 실패 화면으로 간다.
• 미리보기는 Esc로도 닫힌다.
• "다음에 할게요"로 빠져나가면 홈으로 보낸다(플로우를 처음부터 다시 탄다).

📋 검토한 대안과 선택 이유

• 단일 라우트 위저드(/fee/transfer 하나에서 step state)도 검토했지만, 뒤로가기를 직접 다뤄야 하고 중간 화면을 열어볼 수 없어서 단계별 라우트로 갔다.
• 업로드 버튼을 WDS Button의 outlined로 대체하는 것도 봤지만 radius·높이가 달라서 Stream 로컬로 만들었다. 파일 행 아이콘도 WDS IconImage는 외곽선 스타일이라 글리프가 달라 Figma 것을 받았다.
• 카드 테두리를 border로 그리면 box-sizing 때문에 Figma의 335×104 / 303px 행이 333×102 / 301px가 된다 — outline-1 -outline-offset-1로 바꿨다.

💬 리뷰 포인트

• [c] 일러스트 모션의 반복 설정을 확인 부탁드립니다. Figma는 둘 다 2초 loop인데 1회 재생(loop={false})으로 맞췄습니다 — 기존 완료 체크 모션과 같은 판단입니다. 계속 반복되는 게 의도면 알려주세요.

• [c] 라우트 경로(/fee/transfer/*)를 새로 정했습니다. 설계서에 근거가 없어 용어 사전 규칙으로 정한 거라, 백엔드 엔드포인트와 맞는지 확인 부탁드립니다.

• [c] 납부 금액 규칙과 토스 계좌가 정해지면 알려주세요. 딥링크를 만들려면 둘 다 필요합니다.

• [a] 납부내역 화면 3종(3147:147841 / 3147:147860 / 3147:147879)과 홈 진입점·상태 뱃지는 이 PR에서 뺐습니다. 별도 이슈로 이어서 하겠습니다.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: fd8bd845-5c39-4123-88ad-5c67e2dc08e8

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}