ON SURVEY — 토스 미니앱 설문 조사 플랫폼

설문을 만들고 싶은 사람과 응답하고 참여 보상을 받고 싶은 사람을 연결하는 서비스. 토스 앱 안에서 동작하는 미니앱(Apps in Toss)으로, 결제·인증·포인트 지급이 모두 토스 플랫폼과 연동됩니다.

⚙️ 기술 스택

Language / Runtime	Java 21, Spring Boot 3.5.6
Persistence	MySQL 8(AWS RDS), Spring Data JPA, QueryDSL 7
Cache / Lock	Redis 7, Redisson(분산락)
Security	Spring Security
Infra	Docker, Nginx, NCP Server, NCP Object Storage, AWS Lambda
CI/CD	GitHub Actions
Observability	Sentry, Discord Webhook, Spring Actuator

---

1. 어떤 서비스인가

flowchart LR
  A["설문 의뢰자"] -->|"코인 충전 (토스 IAP)"| B["설문 생성<br/>문항·타게팅·목표 응답 수 설정"]
  B --> C["검수 후 게시"]
  C --> D["참여자에게 노출"]
  D --> E["스크리닝 통과 → 응답"]
  E --> F["목표 응답 수 도달 시 자동 마감"]
  E --> G["참여자에게 프로모션 지급"]
  F --> H["의뢰자: 결과 집계·CSV 다운로드"]

Loading

---

2. 시스템 아키텍처

flowchart TB
  subgraph CLIENT["클라이언트"]
    TOSS["토스 미니앱 WebView"]
    BO["백오피스 브라우저"]
  end
 
  subgraph SERVER
    NGX["Nginx 1.25<br/>TLS 종료 · 리버스 프록시"]
    BLUE["onsurvey-blue :8080"]
    GREEN["onsurvey-green :8081"]
    REDIS[("Redis 7<br/>분산락 · 카운터")]
  end
 
  subgraph DATA["데이터"]
    RDS[("AWS RDS<br/>MySQL 8")]
    OBS[("NCP Object Storage<br/>이미지 · 변환 JSON")]
  end
 
  subgraph EXT["외부 연동"]
    TAPI["Toss Partner API (mTLS)<br/>OAuth2 · IAP · 프로모션 · 푸시"]
    LAMBDA["AWS Lambda<br/>구글폼 파싱"]
    SENTRY["Sentry"]
    DISCORD["Discord Webhook"]
  end
 
  TOSS --> NGX
  BO --> NGX
  NGX -->|"active"| BLUE
  NGX -.->|"standby"| GREEN
  BLUE --> REDIS
  BLUE --> RDS
  BLUE --> OBS
  BLUE --> TAPI
  BLUE --> LAMBDA
  BLUE --> SENTRY
  BLUE --> DISCORD
  LAMBDA -->|"파싱 결과 적재"| OBS

Loading

---

3. 애플리케이션 구조

패키지를 domain(비즈니스) 과 global(공통·외부연동) 로 나누고, 외부 시스템에 의존하는 영역은 포트-어댑터 방식으로 인터페이스와 구현을 분리했습니다.

OneQ/OnSurvey/
├── domain/                        # 바운디드 컨텍스트
│   ├── survey/                    # 설문 생성·게시·관리·집계·환불
│   ├── question/                  # 문항 11종 및 보기·섹션
│   ├── participation/             # 스크리닝·응답 저장·응답 완료
│   ├── member/                    # 회원·코인·포인트
│   ├── discount/                  # 할인 코드
│   └── admin/                     # 백오피스 (port/adapter 구조)
└── global/
    ├── auth/                      # 인증 전략 · 필터 · 토큰
    ├── payment/  promotion/  push/   # 토스 연동 유스케이스 (port/out)
    ├── infra/                     # toss · redis · ncp · discord · transaction
    └── common/                    # config · exception · response · util

flowchart TB
  subgraph L1["Presentation"]
    C1["REST Controller"]
    C2["Backoffice (Thymeleaf SSR)"]
  end
  subgraph L2["Security Filter Chain"]
    F1["#1 /connect-out — 고정 헤더 검증"]
    F2["#2 백오피스 — 세션 + RateLimiter"]
    F3["#3 그 외 — STATELESS + AuthStrategy"]
  end
  subgraph L3["Application"]
    A1["Facade/UseCase"]
    A2["Command/Query 서비스 분리"]
  end
  subgraph L4["Domain"]
    D1["Entity"]
    D2["Port(out) 인터페이스"]
  end
  subgraph L5["Infrastructure"]
    I1["JPA + QueryDSL"]
    I2["TossApiClient (WebClient / mTLS)"]
    I3["RedisAgent (Redisson)"]
    I4["NcpS3Client / Discord Notifier"]
  end

  C1 --> F3 --> A1
  C2 --> F2 --> A1
  A1 --> A2 --> D1
  A1 --> D2
  D2 -. 구현 .-> I2
  D2 -. 구현 .-> I1
  A2 --> I3
  A1 --> I4

Loading

의도

• Command / Query 분리 — 조회는 @Transactional(readOnly = true)로 잡고 QueryDSL Projection으로 필요한 컬럼만 가져옵니다. 쓰기 경로는 정합성, 읽기 경로는 응답속도를 중점으로 모델을 분리했습니다.
• RedisAgent를 인터페이스(RedisLockAction, RedisCacheAction)로 노출시킵니다.
• 필터 체인 3분리 — 사용자와 운영자의 인증 방식이 다릅니다. 각 인증 방식에 따라@Order가 다른 SecurityFilterChain 세 개로 분리했습니다.

---

4. 도메인 모델

erDiagram
    MEMBER ||--o{ SURVEY : "생성"
    MEMBER ||--o{ RESPONSE : "참여"
    MEMBER ||--o{ PAYMENT : "결제"
    MEMBER ||--o{ PROMOTION_GRANT : "프로모션 수령"

    SURVEY ||--|| SURVEY_INFO : "타게팅/목표응답수"
    SURVEY ||--o{ SECTION : "구성"
    SURVEY ||--o{ QUESTION : "포함"
    SURVEY ||--o| SCREENING : "사전질문"
    SURVEY ||--o{ RESPONSE : "응답 이력"

    QUESTION ||--o{ CHOICE_OPTION : "객관식 보기"
    QUESTION ||--o{ GRID_OPTION : "그리드 행/열"
    QUESTION ||--o{ QUESTION_ANSWER : "답변"
    SCREENING ||--o{ SCREENING_ANSWER : "답변"

    SURVEY_INFO }o--o| DISCOUNT_CODE : "할인 적용"

    MEMBER {
        bigint member_id PK
        bigint user_key UK "토스 사용자 식별자"
        string name
        enum   gender
        enum   status "ACTIVE / WITHDRAWN 등"
        bigint coin "충전 코인"
        bigint promotion_point "지급 프로모션"
        bool   onboarding_completed
    }
    SURVEY {
        bigint id PK
        bigint member_id FK
        text   title
        datetime deadline
        enum   status "WRITING/ONGOING/CLOSED/REFUNDED/REVIEW"
        bool   is_temporary
        bool   is_free
        int    total_coin
    }
    SURVEY_INFO {
        bigint info_id PK
        bigint survey_id FK
        int    due_count "목표 응답 수"
        int    completed_count
        enum   gender "타게팅 조건"
        int    promotion_amount
        bool   refundable
    }
    QUESTION {
        bigint question_id PK
        bigint survey_id FK
        string type "단일 테이블 상속 판별자"
        int    question_order
        int    section
        bool   is_required
    }
    RESPONSE {
        bigint survey_id PK "복합 PK"
        bigint member_id PK
        bool   is_responded
        bool   is_screened
    }
    PROMOTION_GRANT {
        bigint id PK
        bigint user_key "UK(user_key, survey_id, promotion_code)"
        bigint survey_id
        string promotion_code
        enum   status "PENDING/SUCCESS/FAILED"
        string exec_key "토스 실행 키"
        bool   point_granted "포인트 반영 여부"
    }
    PAYMENT {
        bigint payment_id PK
        string order_id "토스 주문 번호"
        bigint user_key
        int    total_amount
        enum   status "PENDING/PAID/REFUNDED"
        enum   purpose "COIN_CHARGE/HOME_REGISTRATION"
    }

Loading

• 문항 11종을 단일 테이블 상속(SINGLE_TABLE)으로 — 객관식, 평점, NPS, 그리드, 날짜, 시간 등 타입마다 필요한 속성이 다릅니다. 조인 전략을 쓰면 문항 조회마다 조인이 붙는데, 설문 참여 시 다건의 문항 조회가 발생하므로 조인 비용을 최소화하고자 했습니다. 이에 대한 트레이드 오프로 하위 타입의 컬럼이 nullable이 되는 것을 감수했습니다.
• RESPONSE의 복합 PK (survey_id, member_id) — 한 사람은 한 설문에 한 번만 응답하도록 데이터베이스 레벨에서 보장합니다.
• PROMOTION_GRANT의 복합 유니크 제약 — 포인트 중복 지급을 막도록 유니크 제약을 추가했습니다.
• SURVEY와 SURVEY_INFO 분리 — 설문 본문(제목, 문항)은 작성 중 자주 변경되고 타게팅, 가격 정보 등은 결제 및 게시 시점에 확정됩니다. 변경 주기가 다른 데이터를 분리해 잠금 경합을 줄였습니다.