결제 수단 등록 화면 핸드오프 명세

대상 화면은 카드 등록 바텀시트다.
현재 제공된 정보에는 화면 이미지, 요소 목록, 카드사/결제 SDK, API, 상태 목록의 구체값이 없다. 따라서 아래 문서에서 확정할 수 없는 내용은 모두 미정으로 표시한다. 구현자가 임의로 보완하지 않는다.

1. 화면 범위

확정된 내용

• 화면 목적: 결제 수단으로 사용할 카드를 등록한다.
• 표현 형태: 바텀시트
• 대상 사용자: 이번 스프린트에 처음 합류한 외주 프론트엔드 개발자

미정

• 바텀시트가 어떤 화면 위에서 열리는지
• 바텀시트의 높이와 최대 높이
• 제목과 설명 문구
• 카드 번호, 유효기간, CVC, 카드 소유자명 등 입력 필드 구성
• 등록 버튼의 문구
• 닫기 버튼 또는 바깥 영역 탭 닫기 지원 여부
• 카드 등록 방식과 API/SDK
• 등록 성공 후 이동 또는 화면 갱신 방식

---

2. 요소별 동작 명세

현재 요소 목록이 제공되지 않았으므로, 아래는 구현 전 반드시 확정해야 하는 요소별 명세 표다. 표에 없는 요소는 새로 추가하지 않는다.

요소	탭	호버	포커스	비활성화	데이터/상태	길이 제한	반응형	검증
바텀시트 컨테이너	미정	해당 없음	미정	미정	미정	미정	미정	해당 없음
닫기/취소 컨트롤	미정	미정	미정	미정	미정	해당 없음	미정	해당 없음
카드 번호 입력	미정	미정	미정	미정	미정	미정	미정	검증 규칙 미정
유효기간 입력	미정	미정	미정	미정	미정	미정	미정	검증 규칙 미정
CVC 입력	미정	미정	미정	미정	미정	미정	미정	검증 규칙 미정
카드 소유자명 입력	미정	미정	미정	미정	미정	미정	미정	검증 규칙 미정
카드 등록 버튼	미정	미정	미정	미정	미정	해당 없음	미정	미정
안내/오류 메시지	해당 없음	해당 없음	미정	해당 없음	미정	미정	미정	미정

입력 필드 공통 규칙

현재 다음 항목은 결정되지 않았다.

• 입력 중 자동 포맷팅 여부
• 숫자 키패드 사용 여부
• 카드 번호 마스킹 여부
• 붙여넣기 허용 여부
• 공백과 하이픈 처리 방식
• 자동 완성 사용 여부
• 다음 필드로 자동 이동 여부
• 오류 발생 시 입력값 유지 여부
• 서버에 전송하는 값과 화면에 표시하는 값의 차이

구현자는 위 항목을 임의로 정하지 않는다.

버튼 공통 규칙

• 등록 처리 중 중복 탭 방지 여부: 미정
• 처리 중 버튼 문구 변경 여부: 미정
• 처리 중 바텀시트 닫기 허용 여부: 미정
• 등록 성공 시 버튼 동작: 미정
• 등록 실패 시 버튼 동작: 미정

---

3. 데이터와 상태

데이터 출처

카드 등록에 사용되는 데이터의 출처는 제공되지 않았다.

• 입력값의 로컬 상태 관리 방식: 미정
• 카드 등록 API 또는 SDK: 미정
• 카드사 목록 또는 카드 브랜드 판별 데이터: 미정
• 기존 등록 카드 조회 여부: 미정
• 서버 응답 형식: 미정
• 민감정보 저장 여부: 미정

로딩 상태

필수 로딩 상태는 존재해야 하지만, 표현 방식은 미정이다.

미정 항목:

• 전체 바텀시트 로딩인지 등록 버튼만 로딩인지
• 스피너, 버튼 로딩 문구, 스켈레톤 중 무엇을 사용하는지
• 입력 필드를 잠그는지
• 닫기/취소를 허용하는지
• 로딩 중 오류가 발생할 수 있는지
• 로딩이 일정 시간 이상 지속될 때 별도 문구를 표시하는지

실패 상태

실패 메시지와 복구 방식은 미정이다.

• 필드별 검증 오류인지
• 서버 등록 실패인지
• 네트워크 실패인지
• 인증 또는 권한 실패인지
• 오류 메시지를 필드 아래, 바텀시트 상단, 토스트 중 어디에 표시하는지
• 사용자가 재시도할 수 있는지
• 입력값을 보존하는지

---

4. 필수 상태별 명세

아래 상태는 모두 화면에 대해 정의되어야 한다. 현재 구체적인 UI와 문구는 제공되지 않았다.

Empty

의미와 진입 조건은 미정이다.

확정이 필요한 항목:

• 입력값이 하나도 없는 초기 상태인지
• 카드 등록 정보 자체가 없는 상태인지
• 안내 문구가 있는지
• 등록 버튼을 비활성화하는지
• 빈 상태에서 닫기 동작을 허용하는지

Loading

확정이 필요한 항목:

• 최초 바텀시트 로딩인지
• 카드 등록 요청 중인지
• 표시할 로딩 UI
• 입력 및 버튼 비활성화 여부
• 닫기 가능 여부
• 로딩 중 재요청 방지 방식

Partial

의미가 미정이다.

가능한 의미 중 어느 것인지 결정되지 않았다.

• 일부 입력만 완료된 상태
• 카드 정보 일부만 서버에서 로드된 상태
• 카드 브랜드만 판별된 상태
• 일부 필드만 오류인 상태

부분 입력 상태라면 다음을 정해야 한다.

• 입력한 값 유지 여부
• 등록 버튼 활성화 조건
• 이동 또는 닫기 시 경고 여부
• 누락 필드 표시 시점

Error

오류 유형별 표시 방식이 미정이다.

• 유효하지 않은 카드 정보
• 등록 불가 카드
• 네트워크 오류
• 서버 오류
• 중복 등록
• 인증 실패
• 권한 부족

각 오류에 대해 문구, 위치, 재시도 여부, 입력값 보존 여부가 필요하다.

Permission

권한 상태가 무엇을 뜻하는지 제공되지 않았다.

확정이 필요한 항목:

• 결제 수단 등록 권한이 없는 경우인지
• 앱 또는 브라우저 권한이 필요한 경우인지
• 권한 요청을 수행하는지
• 권한이 없을 때 입력 UI를 숨기는지
• 안내 문구와 이동 버튼이 필요한지
• 사용자가 권한을 얻은 뒤 화면이 자동 갱신되는지

---

5. 반응형 동작

좁은 너비에서 변경할 것

현재 결정되지 않았다.

• 바텀시트 너비
• 좌우 여백
• 바텀시트 높이
• 필드의 1열/다열 배치
• 버튼의 너비
• 키보드가 열렸을 때 바텀시트 이동 또는 스크롤
• 긴 오류 메시지 처리
• 안전 영역 및 하단 여백

좁은 너비에서도 변경하지 않을 것

현재 제공된 정보만으로는 확정할 수 없다.
다음 항목은 별도 결정이 필요하다.

• 입력 순서
• 필수 입력 항목
• 등록 처리 의미
• 검증 기준
• 성공 및 실패 결과

오버플로

각 텍스트와 입력값에 대해 다음이 미정이다.

• 한 줄 말줄임
• 여러 줄 줄바꿈
• 가로 스크롤
• 전체 표시
• 오류 문구의 줄바꿈 여부

구현자는 임의로 truncate, wrap, scroll 중 하나를 선택하지 않는다.

---

6. 검증 명세

현재 검증 규칙은 전혀 제공되지 않았다.

확정해야 하는 항목:

• 검증 실행 시점

  • 입력 중
  • 포커스 해제 시
  • 등록 버튼 탭 시
  • 서버 응답 후

• 검증 대상

  • 필수값 누락
  • 형식 오류
  • 길이 오류
  • 만료 카드
  • CVC 오류
  • 등록 불가 카드
  • 중복 카드

• 메시지 문구

• 메시지 위치

• 오류 필드의 시각적 상태

• 오류가 사라지는 시점

• 서버 오류와 클라이언트 오류의 구분

• 첫 오류 필드로 포커스를 이동할지 여부

• 오류가 여러 개일 때 표시 순서

현재 상태에서는 검증 문구나 필드별 길이를 확정할 수 없다.

---

7. 재사용과 신규 개발

기존 컴포넌트 재사용 여부

기존 컴포넌트 목록이나 디자인 시스템 정보가 제공되지 않았다.

따라서 다음의 재사용 여부는 미정이다.

• 바텀시트
• 텍스트 입력 필드
• 에러 메시지
• 버튼
• 로딩 인디케이터
• 포커스 및 키보드 처리
• 모달 닫기 처리
• 카드 브랜드 아이콘
• 폼 검증 로직

새로 만드는 범위

새 컴포넌트가 필요한지 여부도 미정이다.

다만 새로 구현하게 된다면, 다음을 기존 시스템과 먼저 대조해야 한다.

• 바텀시트 동작
• 입력 필드 상태
• 버튼 상태
• 오류 표시 규칙
• 여백과 타이포그래피
• 접근성 속성
• 반응형 규칙

기존 컴포넌트가 있는데도 동일한 동작을 별도로 만들지 않는다.

---

8. 의도적으로 처리하지 않는 범위

현재 제공된 정보만으로 다음은 처리하지 않는다.

• 카드사별 정책
• 카드 등록 API 또는 SDK 연동
• 카드 번호 유효성 알고리즘
• 카드 브랜드 판별
• 결제 인증 또는 3D Secure
• 카드 저장 보안 정책
• 개인정보 및 민감정보 보관 정책
• 중복 카드 정책
• 등록된 카드 목록 화면
• 등록 성공 후 결제 흐름
• 권한 획득 흐름
• 다국어
• 분석 이벤트
• 접근성 기준
• 브라우저별 키보드 동작
• 네트워크 재시도 정책
• 서버 오류 코드별 처리

이 항목들은 화면에 없다는 뜻이 아니라, 현재 요구사항에 정의되어 있지 않아 구현 범위에 포함하지 않는다는 뜻이다.

---

9. 구현자가 물어볼 세 가지 질문과 답

1. 어떤 입력 필드와 버튼을 만들어야 하나요?

아직 결정되지 않았다.
현재 확정된 것은 “카드를 등록하는 바텀시트”라는 목적뿐이다. 화면 이미지나 요소 목록 없이 입력 필드를 추정하지 않는다.

2. 등록 버튼을 눌렀을 때 어디로 연결해야 하나요?

아직 결정되지 않았다.
API/SDK, 성공·실패 응답, 성공 후 화면 전환 또는 갱신 방식이 제공되지 않았다.

3. 오류와 로딩 상태는 어떻게 보여주나요?

아직 결정되지 않았다.
필드별 오류, 서버 오류, 네트워크 오류, 권한 오류의 문구와 위치가 정의되지 않았다.

---

10. 미결정 사항

다음은 빈칸이 아니라 명시적인 미정 항목이다.

• 화면의 실제 요소 목록
• 모든 텍스트 문구
• 바텀시트 열림·닫힘 조건
• 바깥 영역 탭 및 뒤로가기 동작
• 입력 필드 종류와 순서
• 필드별 최대 길이와 포맷
• 마스킹 및 붙여넣기 정책
• 등록 버튼 활성화 조건
• API/SDK와 데이터 매핑
• 로딩 UI
• 오류 UI와 오류 문구
• 권한 상태의 의미
• 반응형 규칙
• 키보드 및 포커스 동작
• 접근성 요구사항
• 기존 컴포넌트 목록
• 분석 이벤트
• 성공 이후 동작
• 취소 또는 중단 시 입력값 처리
• 다국어 지원 여부

---

11. 추측하지 말고 확인받아야 할 것

구현자가 우선 질문해야 하는 것은 다음이다.

1. 화면 이미지 또는 정확한 요소 목록은 무엇인가?
2. 카드 등록에 사용할 API/SDK와 성공·실패 응답은 무엇인가?
3. 필드별 검증 규칙, 오류 문구, 최대 길이는 무엇인가?
4. 바텀시트의 닫기·뒤로가기·키보드 동작은 무엇인가?
5. 재사용해야 하는 기존 컴포넌트와 디자인 시스템 규칙은 무엇인가?

이 다섯 가지가 정해지기 전에는 화면을 완성된 동작으로 구현할 수 없다.