회원 / 인증¶

휴대폰 번호를 단일 신원(identity)으로 사용하는 SMS 인증 기반 회원가입·로그인. 별도 비밀번호 없이 폰 인증코드만으로 가입/로그인이 완결되며, JWT(access token + refresh token)로 세션을 관리합니다.

사용자 여정¶

신규 가입 / 재가입 흐름¶

sequenceDiagram
    autonumber
    participant U as 사용자
    participant FE as 프론트엔드
    participant API as Backend (AuthController)
    participant SVC as AuthService
    participant DB as MySQL
    participant SMS as 외부 SMS

    U->>FE: 폰번호 입력 + "인증코드 받기"
    FE->>API: POST /auth/phone-authentications/issue
    API->>SVC: issuePhoneAuthentication(phone, isChange=false)
    SVC->>DB: PhoneAuthentication 조회 (있으면 issue() 갱신, 없으면 create)
    SVC->>SMS: 인증 메시지 발송
    SVC-->>FE: { id, issueCount }

    U->>FE: 인증코드 6자리 입력
    FE->>API: POST /accounts (가입) 또는 로그인 흐름
※ 검증/계정 생성은 AccountController가 담당
    Note over API,DB: PhoneAuthentication.verifyAndCreateAccount(code)
코드 일치 확인 → Account.normalUser(phone) 생성
    API-->>FE: { accountId, accessToken, refreshToken }

폰 번호 변경 흐름 (로그인 상태)¶

sequenceDiagram
    autonumber
    participant U as 사용자
    participant FE as 프론트엔드
    participant API as Backend (AuthController)
    participant SVC as AuthService
    participant DB as MySQL

    U->>FE: 새 폰번호 입력 + "인증코드 받기"
    FE->>API: POST /auth/phone-authentications/issue
{ phone, isChange: true }
    API->>SVC: issuePhoneAuthentication(phone, isChange=true)
    Note over SVC: 새 폰번호가 이미 다른 계정에서 사용 중이면
AlreadyUsedPhoneException

    U->>FE: 인증코드 입력
    FE->>API: POST /auth/phone-authentications/change
(Authorization: Bearer )
    API->>SVC: changePhoneAuthentication(accountId, id, code)
    SVC->>DB: 새 PhoneAuthentication.verifyAndChangeAccount(code, account)
기존 PhoneAuthentication 삭제
    API-->>FE: 200 OK

토큰 재발급 흐름¶

Access token 만료 시 refresh token으로 재발급. 한 번 사용된 refresh token은 blacklist 등록되어 재사용 불가.

sequenceDiagram
    participant FE as 프론트엔드
    participant API as Backend (AuthController)
    participant SVC as AuthService
    participant DB as MySQL

    FE->>API: POST /auth/reissue
(refresh-token: )
    API->>SVC: reissueToken(RT)
    SVC->>DB: RefreshTokenBlacklist 조회
    alt RT가 blacklist에 있음
        SVC-->>FE: 401 AlreadyUsedRefreshTokenException
    else 정상
        SVC->>DB: 새 token 생성 + Account.addToken
        SVC-->>FE: { accountId, accessToken, refreshToken }
    end

백엔드 구현¶

도메인 규칙¶

API 엔드포인트¶

스펙 상세(request/response schema)는 API 레퍼런스 / OpenAPI 페이지에서 endpoint별 검색.

신규 회원가입 시 호출되는 verifyAndCreateAccount는 AccountController(/accounts/**)가 담당. 멤버십·구독 페이지의 "최초 가입 시 FREE 멤버십 자동 부여" 절 참조.

데이터 모델¶

erDiagram
    PHONE_AUTHENTICATION {
        string phone_authentication_id PK "UUID"
        string phone "11자리 (예: 01099999999)"
        string code "6자리"
        int issue_count "일별 누적 발급 횟수"
        datetime last_issue_time
        boolean join_status
        string account_id FK "nullable"
    }
    ACCOUNT {
        string account_id PK
        string phone
        string name
        string role "GUEST / USER / ADMIN"
        string account_status "ACTIVE / WITHDRAWAL"
    }
    REFRESH_TOKEN_BLACKLIST {
        string refresh_token PK
        datetime expired_time
    }
    PHONE_AUTHENTICATION ||--o| ACCOUNT : "account_id (1:0..1)"

보안 설정¶

알려진 이슈 / 개선 예정¶

• 카드사 심사 백도어 (01099999999 → 999999): PG사 심사 통과 후 코드에서 제거 예정 (AuthService.kt의 //TODO - 카드사 심사 통과시 제거 주석)
• 재시도 제한 미구현: 잘못된 코드를 무제한 시도 가능 (rate limit 부재) — 보안 개선 여지
• OAuth2 도메인 코드 존재 (OAuth2Account, OAuth2Provider 등) — 현재 미사용. 추후 카카오/네이버 로그인 도입 시 활용
• /auth/test는 운영 환경 노출 위험: dev tooling이지만 profile gate 미적용 — 운영 노출 시 임의 번호로 SMS 발송 가능. (별도 PR로 profile-gate 적용 필요. #170은 /accounts/test/**에만 적용됨)

관련 문서¶

• 멤버십·구독 — 가입 직후 FREE 멤버십 부여 흐름
• 관리자 콘솔 — 어드민이 계정 상태/권한 변경
• API 레퍼런스 / OpenAPI — 모든 endpoint의 request/response schema