Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions docs/api-specs/class-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,10 +117,11 @@
- 이용 기간은 등록 시점부터 6개월이다.
- 정원은 리워드 티어(5 / 15 / 30석)를 따른다.
- 계정당 사용 중인(ACTIVE) 이용권은 1개다.
- 코드의 공백·하이픈·대소문자는 무시한다.
- 코드 형식은 `PKE` + 16진수 대문자 6자리다 (예: `PKE05D2E1`). 코드의 공백·하이픈·대소문자는 무시한다.
- **입력 5회 제한:** 코드 확인(1.1)과 등록(1.2)에서 없는 코드를 넣은 횟수를 계정별로 센다. 1시간 안에 5번 틀리면 그 응답부터 1시간 동안 429 `TICKET_429_LOCKED`다. 잠긴 동안에는 맞는 코드도 막힌다. 맞는 코드를 넣어도 틀린 횟수는 초기화되지 않는다.

### 1.1 이용권 코드 확인 (미리보기)
- `GET /api/v1/class-tickets/preview?code=PICKE-AB12-CD34`
- `GET /api/v1/class-tickets/preview?code=PKE05D2E1`
- 코드를 소비하지 않고 정원과 등록 기한을 보여준다.

```json
Expand All @@ -137,6 +138,7 @@
|---|---|
| 빈 코드 | 400 `COMMON_400` |
| 없는 코드 | 404 `TICKET_404_CODE` |
| 없는 코드를 1시간 안에 5번 넣음 (5번째부터 1시간) | 429 `TICKET_429_LOCKED` |
| 재발급·환불로 무효화된 코드 | 409 `TICKET_409_REVOKED` |
| 등록 기한 경과 | 409 `TICKET_409_REG_EXP` |
| 다른 계정이 이미 등록 | 409 `TICKET_409_CLAIMED` |
Expand All @@ -146,7 +148,7 @@
- `POST /api/v1/class-tickets/register`

```json
{ "code": "PICKE-AB12-CD34" }
{ "code": "PKE05D2E1" }
```

- 등록하면 즉시 ACTIVE가 되고 6개월 뒤 만료된다.
Expand Down Expand Up @@ -1276,7 +1278,7 @@ AI가 주제 후보를 제안하면 운영자가 하나를 고르거나 직접
"ticketId": 3, "fundingOrderId": 1, "orderId": "T-0001",
"supporterName": "홍길동", "supporterEmail": "...", "supporterPhone": "...",
"capacity": 30, "registerBy": "2027-09-01T00:00:00",
"code": "XXXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
"code": "PKE05D2E1"
}
],
"skipped": [ { "fundingOrderId": 2, "orderId": "T-0002", "reason": "ALREADY_ISSUED" } ]
Expand Down Expand Up @@ -1471,6 +1473,7 @@ PRD "등록기한 30일·7일 전 알림은 허용된 연락 수단에서만 발
| 코드 | HTTP | 메시지 |
|---|---|---|
| `TICKET_404_CODE` | 404 | 유효하지 않은 이용권 코드입니다. |
| `TICKET_429_LOCKED` | 429 | 이용권 코드를 5번 잘못 입력해 1시간 동안 입력할 수 없어요. 잠시 후 다시 시도해 주세요. |
| `TICKET_404` | 404 | 등록된 이용권이 없습니다. |
| `TICKET_409_CLAIMED` | 409 | 이미 등록된 이용권 코드입니다. |
| `TICKET_409_REVOKED` | 409 | 재발급되어 더 이상 사용할 수 없는 이용권 코드입니다. |
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
package com.swyp.picke.domain.ticket.entity;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.time.LocalDateTime;
import lombok.AccessLevel;
import lombok.Getter;
import lombok.NoArgsConstructor;

/**
* 이용권 코드 입력 실패 횟수 (계정별 1행). 짧은 코드(PKE+6자리)를 추측해 가로채지 못하게,
* 1시간 안에 없는 코드를 5번 넣으면 1시간 동안 코드 확인·등록을 막는다 (기획 결정 2026-11-19).
*/
@Getter
@Entity
@Table(name = "ticket_code_attempts")
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class TicketCodeAttempt {

@Id
@Column(name = "user_id")
private Long userId;

@Column(name = "fail_count", nullable = false)
private int failCount;

/** 실패 횟수를 세기 시작한 시각. 여기서 1시간이 지나면 횟수를 0부터 다시 센다 */
@Column(name = "window_started_at")
private LocalDateTime windowStartedAt;

@Column(name = "locked_until")
private LocalDateTime lockedUntil;

@Column(name = "updated_at", nullable = false)
private LocalDateTime updatedAt;

public TicketCodeAttempt(Long userId, LocalDateTime now) {
this.userId = userId;
this.updatedAt = now;
}

public boolean isLocked(LocalDateTime now) {
return lockedUntil != null && now.isBefore(lockedUntil);
}

/** 실패 1회를 기록하고, 이번 실패로 잠겼으면 true */
public boolean recordFailure(LocalDateTime now, int maxFailures, long windowMinutes, long lockMinutes) {
if (windowStartedAt == null || !now.isBefore(windowStartedAt.plusMinutes(windowMinutes))) {
windowStartedAt = now;
failCount = 0;
}
failCount++;
updatedAt = now;
if (failCount >= maxFailures) {
lockedUntil = now.plusMinutes(lockMinutes);
failCount = 0;
windowStartedAt = null;
return true;
}
return false;
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
package com.swyp.picke.domain.ticket.repository;

import com.swyp.picke.domain.ticket.entity.TicketCodeAttempt;
import jakarta.persistence.LockModeType;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Lock;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

public interface TicketCodeAttemptRepository extends JpaRepository<TicketCodeAttempt, Long> {

/** 동시에 여러 번 틀려도 횟수가 빠지지 않도록 행을 잠그고 읽는다 */
@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("select a from TicketCodeAttempt a where a.userId = :userId")
Optional<TicketCodeAttempt> findByUserIdForUpdate(@Param("userId") Long userId);
}
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import java.util.List;
import java.util.Optional;
import lombok.RequiredArgsConstructor;
import org.springframework.dao.DataIntegrityViolationException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
Expand All @@ -37,15 +38,17 @@ public class ClassTicketServiceImpl implements ClassTicketService {

private final ClassTicketRepository classTicketRepository;
private final UserRepository userRepository;
private final TicketCodeAttemptGuard attemptGuard;

@Override
public ClassTicketPreviewResponse preview(Long userId, String code) {
if (TicketCodeHasher.normalize(code).isEmpty()) {
throw new CustomException(ErrorCode.COMMON_INVALID_PARAMETER);
}
LocalDateTime now = LocalDateTime.now(KST);
attemptGuard.checkNotLocked(userId, now);
ClassTicket ticket = classTicketRepository.findByCodeHash(TicketCodeHasher.hash(code))
.orElseThrow(() -> new CustomException(ErrorCode.TICKET_CODE_INVALID));
.orElseThrow(() -> invalidCode(userId, now));

boolean registeredByMe = ticket.isRegisteredBy(userId);
if (!registeredByMe) {
Expand All @@ -71,8 +74,9 @@ public ClassTicketResponse register(Long userId, ClassTicketRegisterRequest requ
User user = userRepository.findById(userId)
.orElseThrow(() -> new CustomException(ErrorCode.USER_NOT_FOUND));

attemptGuard.checkNotLocked(userId, now);
ClassTicket ticket = classTicketRepository.findByCodeHashForUpdate(TicketCodeHasher.hash(request.code()))
.orElseThrow(() -> new CustomException(ErrorCode.TICKET_CODE_INVALID));
.orElseThrow(() -> invalidCode(userId, now));

if (ticket.isRevoked()) {
throw new CustomException(ErrorCode.TICKET_CODE_REVOKED);
Expand Down Expand Up @@ -106,6 +110,20 @@ public ClassTicketResponse getMyTicket(Long userId) {
return ClassTicketConverter.toResponse(ticket, now);
}

/**
* 없는 코드 입력. 실패를 기록하고 404 를 돌려준다. 이번 실패로 5회가 차면 바로 429(1시간 잠금)를 돌려준다.
* 같은 계정의 첫 실패가 동시에 들어와 기록 행 생성이 충돌하면 한 번 더 기록한다.
*/
private CustomException invalidCode(Long userId, LocalDateTime now) {
boolean locked;
try {
locked = attemptGuard.recordFailure(userId, now);
} catch (DataIntegrityViolationException e) {
locked = attemptGuard.recordFailure(userId, now);
}
return new CustomException(locked ? ErrorCode.TICKET_CODE_LOCKED : ErrorCode.TICKET_CODE_INVALID);
}

/** 상태를 바꾸지 않는 순수 검사. preview 와 register 가 같이 쓴다 */
private void validateCodeRegistrable(ClassTicket ticket, LocalDateTime now) {
if (ticket.isRevoked()) {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
package com.swyp.picke.domain.ticket.service;

import com.swyp.picke.domain.ticket.entity.TicketCodeAttempt;
import com.swyp.picke.domain.ticket.repository.TicketCodeAttemptRepository;
import com.swyp.picke.global.common.exception.CustomException;
import com.swyp.picke.global.common.exception.ErrorCode;
import java.time.LocalDateTime;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

/**
* 이용권 코드 입력 5회 제한 (기획 결정 2026-11-19). 계정별로 1시간 안에 없는 코드를 5번 넣으면 1시간 동안 막는다.
* <p>실패 기록은 호출한 쪽이 예외로 롤백돼도 남아야 하므로 별도 트랜잭션(REQUIRES_NEW)으로 저장한다.
* 맞는 코드를 넣어도 횟수를 초기화하지 않는다. 초기화하면 본인 코드로 횟수를 지우며 계속 추측할 수 있기 때문이다.</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class TicketCodeAttemptGuard {

public static final int MAX_FAILURES = 5;
public static final long WINDOW_MINUTES = 60;
public static final long LOCK_MINUTES = 60;

private final TicketCodeAttemptRepository attemptRepository;

/** 잠겨 있으면 429 */
@Transactional(propagation = Propagation.REQUIRES_NEW, readOnly = true)
public void checkNotLocked(Long userId, LocalDateTime now) {
attemptRepository.findById(userId)
.filter(a -> a.isLocked(now))
.ifPresent(a -> {
throw new CustomException(ErrorCode.TICKET_CODE_LOCKED);
});
}

/** 없는 코드 입력 1회 기록. 이번 실패로 잠기면 true */
@Transactional(propagation = Propagation.REQUIRES_NEW)
public boolean recordFailure(Long userId, LocalDateTime now) {
TicketCodeAttempt attempt = attemptRepository.findByUserIdForUpdate(userId)
.orElseGet(() -> createRow(userId, now));
boolean locked = attempt.recordFailure(now, MAX_FAILURES, WINDOW_MINUTES, LOCK_MINUTES);
if (locked) {
log.warn("이용권 코드 입력 잠금 - userId: {}, lockedUntil: {}", userId, attempt.getLockedUntil());
}
return locked;
}

/**
* 같은 계정의 첫 실패가 동시에 들어오면 한쪽은 PK 충돌(DataIntegrityViolationException)로 끝난다.
* 이 트랜잭션은 그대로 롤백되고, 호출한 쪽이 한 번 더 부르면 이미 만들어진 행을 잠그고 센다.
*/
private TicketCodeAttempt createRow(Long userId, LocalDateTime now) {
return attemptRepository.saveAndFlush(new TicketCodeAttempt(userId, now));
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,34 @@
import java.security.SecureRandom;

/**
* 이용권 코드 생성. SecureRandom 130bit → Crockford Base32 26자 (0/O, 1/I/L 혼동 문자 제외).
* 표시 형식은 {@code XXXXXX-XXXXX-XXXXX-XXXXX-XXXXX} (6-5-5-5-5). 하이픈·소문자는 {@link TicketCodeHasher#normalize} 가 흡수한다.
* 원문은 관리자 발급/조회 응답으로만 노출하고 서버 로그에는 남기지 않는다. DB에는 별도 키로 암호화해 보관한다.
* 이용권 코드 생성. 형식은 {@code PKE} + 16진수 대문자 6자리 (예: {@code PKE05D2E1}, 기획 결정 2026-11-19).
* <p>무작위 부분이 24비트(약 1,678만 가지)라 추측 공격에 약하므로, 코드 확인·등록은
* {@link com.swyp.picke.domain.ticket.service.TicketCodeAttemptGuard} 로 계정별 실패 횟수를 제한한다.</p>
* <p>공백·하이픈·소문자는 {@link TicketCodeHasher#normalize} 가 흡수한다. 원문은 관리자 발급/조회 응답으로만 노출하고
* 서버 로그에는 남기지 않는다. DB에는 별도 키로 암호화해 보관한다.</p>
*/
public final class TicketCodeGenerator {

public static final int CODE_LENGTH = 26;
private static final String ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
private static final int[] GROUPS = {6, 5, 5, 5, 5};
public static final String PREFIX = "PKE";
public static final int RANDOM_LENGTH = 6;
public static final int CODE_LENGTH = PREFIX.length() + RANDOM_LENGTH;
private static final String HEX = "0123456789ABCDEF";
private static final SecureRandom RANDOM = new SecureRandom();

private TicketCodeGenerator() {
}

/** 하이픈 없는 26자 원문 (해시 입력·정규화 기준과 동일) */
/** 정규화 기준과 같은 원문 (해시 입력) */
public static String generate() {
StringBuilder sb = new StringBuilder(CODE_LENGTH);
for (int i = 0; i < CODE_LENGTH; i++) {
sb.append(ALPHABET.charAt(RANDOM.nextInt(ALPHABET.length())));
StringBuilder sb = new StringBuilder(CODE_LENGTH).append(PREFIX);
for (int i = 0; i < RANDOM_LENGTH; i++) {
sb.append(HEX.charAt(RANDOM.nextInt(HEX.length())));
}
return sb.toString();
}

/** 사람이 받아 적기 쉬운 표시 형식 */
/** 사람에게 보여주는 형식. 새 형식은 원문 그대로다 */
public static String format(String rawCode) {
StringBuilder sb = new StringBuilder(CODE_LENGTH + GROUPS.length - 1);
int pos = 0;
for (int i = 0; i < GROUPS.length; i++) {
if (i > 0) {
sb.append('-');
}
sb.append(rawCode, pos, pos + GROUPS[i]);
pos += GROUPS[i];
}
return sb.toString();
return rawCode;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ public enum ErrorCode {

// ClassTicket (클래스 이용권)
TICKET_CODE_INVALID(HttpStatus.NOT_FOUND, "TICKET_404_CODE", "유효하지 않은 이용권 코드입니다."),
TICKET_CODE_LOCKED(HttpStatus.TOO_MANY_REQUESTS, "TICKET_429_LOCKED", "이용권 코드를 5번 잘못 입력해 1시간 동안 입력할 수 없어요. 잠시 후 다시 시도해 주세요."),
TICKET_CODE_ALREADY_CLAIMED(HttpStatus.CONFLICT, "TICKET_409_CLAIMED", "이미 등록된 이용권 코드입니다."),
TICKET_CODE_REVOKED(HttpStatus.CONFLICT, "TICKET_409_REVOKED", "재발급되어 더 이상 사용할 수 없는 이용권 코드입니다."),
TICKET_REGISTER_EXPIRED(HttpStatus.CONFLICT, "TICKET_409_REG_EXP", "등록 기한이 지난 이용권 코드입니다."),
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
-- #653 이용권 코드 입력 실패 횟수 (계정별 1행).
-- 코드가 PKE+16진수 6자리로 짧아져, 1시간 안에 없는 코드를 5번 넣으면 1시간 동안 코드 확인·등록을 막는다.
-- 서버 배포 전에 먼저 실행해야 한다 (없으면 코드 확인·등록이 500).
-- 멱등하게 작성되어 재실행해도 안전하다.

CREATE TABLE IF NOT EXISTS ticket_code_attempts (
user_id BIGINT PRIMARY KEY,
fail_count INT NOT NULL DEFAULT 0,
window_started_at TIMESTAMP,
locked_until TIMESTAMP,
updated_at TIMESTAMP NOT NULL
);

DO $$
BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_ticket_code_attempts_user') THEN
ALTER TABLE ticket_code_attempts ADD CONSTRAINT fk_ticket_code_attempts_user
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE;
END IF;
END $$;
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
-- Rollback for V20261119_03__create_ticket_code_attempts.sql
-- 애플리케이션 코드를 #653 이전으로 되돌린 뒤 실행할 것.
DROP TABLE IF EXISTS ticket_code_attempts;
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ class AdminFundingApiIntegrationTest {

private static final String HEADER =
"platform,campaign_id,order_id,reward_tier,quantity,supporter_name,supporter_email,supporter_phone,payment_status,paid_at\n";
private static final String CODE_PATTERN = "[0-9A-Z]{6}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}";
private static final String CODE_PATTERN = "PKE[0-9A-F]{6}";

@Autowired
private MockMvc mockMvc;
Expand Down
Loading
Loading