상품권 매입 플랫폼 — 개발 진행 가이드

접속 계정 정보

일반 사용자 (role: user)

주소 https://online.habyapps.com

이메일 test@example.com

비밀번호 test1234

주요 기능 상품권 종류 선택 · 핀번호 입력 · 계좌 등록 · 매입 신청 · 내역 조회

인증 Sanctum SPA 쿠키 · 본인인증(Mock) 후 이용

관리자 (role: admin)

주소 https://online.habyapps.com/admin

이메일 admin@example.com

비밀번호 admin1234

주요 기능 회원 관리 · 매입 현황 관리 · 시세 관리 · KYC/AML · 통계 대시보드

시드 명령 php artisan migrate:fresh --seed

📱 앱 다운로드 (Android APK)

🤖

상품권 매입 앱 — Android

📦 버전 1.0.0+1 ⚖️ 약 44 MB 🏗️ Release 빌드 🛡️ webview_flutter · Edge-to-Edge

⚠️ 설치 전 기기 설정에서 알 수 없는 앱 설치 허용을 활성화하세요.
설정 → 보안 → 알 수 없는 출처 또는 설정 → 앱 → 특별한 앱 권한 → 알 수 없는 앱 설치

⬇ APK 다운로드

API / 서버 정보

백엔드 API (Laravel)

Base URL https://online.habyapps.com/api/v1

CSRF GET /sanctum/csrf-cookie

Queue 워커 php artisan queue:work --queue=pin,transfer

테스트 php artisan test

프론트엔드 (Vue 3)

운영 URL https://online.habyapps.com

관리자 /admin

Dev 실행 cd frontend && npm run dev

빌드 cd frontend && npm run build

전체 진행률

100%

Phase 1~6 전체 완료 ✅ MVP 완료 (Phase 0: 법무·사업 담당 항목 제외)

🚫

Phase 0 — 사전 준비

TASK-001~006 · 법무·외부 API 계약·알림톡 승인 (인간 담당)

3 / 6

✅

Phase 1 — 백엔드 기반

TASK-101~110 · DB 스키마 · 인증 · 핵심 도메인

10 / 10

✅

Phase 2 — 핵심 매입 플로우

TASK-201~210 · Queue · 핀검증 · 펌뱅킹 · 알림

10 / 10

✅

Phase 3 — 관리자 + KYC/AML + 정산

TASK-301~309 · 관리자 API · KYC 룰엔진 · STR/CTR

9 / 9

✅

Phase 4 — 프론트엔드 (Vue 3)

TASK-401~408 · SPA · 실시간 예상가 · 약관 흐름

8 / 8

✅

Phase 5 — Flutter 모바일 앱

TASK-501~509 · GoRouter · Riverpod · FCM · 보안 토큰

9 / 9

✅

Phase 6 — 보안·품질·출시 준비

TASK-601~610 · 2FA · 부하테스트 · E2E · 런북 · 배포

10 / 10

기술 스택

🐘

PHP 8.3 / Laravel 11

백엔드 API · Queue · Scheduler · Horizon

🔑

Laravel Sanctum

SPA 쿠키 인증 (stateful)

🗄️

MariaDB 10.11 LTS

관계형 DB · ULID PK

⚡

Redis 7 + Laravel Queue

핀검증 · 이체 비동기 처리

💚

Vue 3 + Vite 5

SPA 웹 프론트엔드 (Composition API)

🔷

TypeScript (strict)

타입 안전 프론트엔드

🍍

Pinia

전역 상태 관리

📱

Flutter (stable)

iOS / Android 네이티브 앱

🔀

Riverpod + GoRouter

Flutter 상태관리 · 라우팅

🔒

AES-256-GCM + HMAC-SHA256

핀번호 암호화 · blind index · Vault 키 회전

💬

카카오 알림톡 · SMS · FCM

알림톡 우선 → SMS 폴백 → 푸시

🧪

PHPUnit + PHPStan Lv8

Feature 테스트 · 정적 분석 · E2E

단계별 작업 상세

Phase 0 사전 준비 — 법무·인프라·외부 API 계약 (4~6주)

🔄 진행 중 3 / 6 ▼

사업 모델(직접매입/단순중개/위탁판매) 법무 분류 확정, 외부 API(상품권 검증·펌뱅킹·본인인증·알림톡·SMS) 계약 체결, 카카오 알림톡 템플릿 사전 승인(1~2주), 개발/스테이징 인프라 구축, 비밀 관리 정책 수립, Git/CI-CD 파이프라인 골격 구성. TASK-001~003은 법무·사업팀 담당(Blocked), TASK-004~006은 완료.

Task	작업 내용	구분	상태
TASK-001	법무 자문 및 사업 모델 분류 확정 ← 인간 담당 직접매입 vs 단순중개 vs 위탁판매 · 전자금융업/선불업 적용 여부 · 특금법(자금세탁방지법) 자문	법무	🚫
TASK-002	외부 API 계약 체결 ← 인간 담당 상품권 검증 B2B API · 펌뱅킹 · 본인인증(KMC/NICE) · 카카오 알림톡 · SMS(NHN/솔라피)	사업	🚫
TASK-003	카카오 알림톡 템플릿 사전 승인 신청 (1~2주) ← 인간 담당 매입 신청 접수 · 매입 완료/이체 완료 · 매입 실패 · 본인인증 인증번호 4종 템플릿	사업	🚫
TASK-004	개발/스테이징 인프라 현황 점검 완료 .env.example 생성 · Nginx + PHP-FPM 8.3 · MariaDB 10.11 · Redis 7 · S3 버킷 — ⚠️ Redis·bcmath·php-redis 설치 및 MariaDB 업그레이드 필요	Infra	✓
TASK-005	비밀 관리 운영 가이드 작성 완료 HashiCorp Vault 운영 가이드 · AES-256-GCM 마스터 키 발급 및 6개월 회전 정책 수립 (Vault 설치·키 발급은 인간 담당)	Infra	✓
TASK-006	Git 저장소 초기화 + CI/CD 파이프라인 골격 완료 GitHub Actions CI · Gitleaks 시크릿 스캐닝 · Flutter 커버리지 80% 게이트 · 배포 파이프라인 · Dependabot	Infra	✓

Phase 1 백엔드 기반 — DB 스키마 + 인증 + 핵심 도메인 (3주)

✅ 완료 10 / 10 ▼

Laravel 11 초기 설정, 전체 DB 마이그레이션(users, gift_card_types, purchase_requests, purchase_pins, bank_accounts, transfer_logs, kyc_verifications 등), AES-256-GCM 보안 캐스트, Sanctum SPA 인증, 계좌 실명확인 Mock API, 상품권 종류·시세 관리, 약관 동의 버전 관리 완성.

Task	작업 내용	구분	상태
TASK-101	Laravel 11 프로젝트 초기화 및 패키지 구성 Sanctum · Horizon · Pint · PHPStan · .env.example	Infra	✓
TASK-102	전체 DB 마이그레이션 작성 users · gift_card_types · purchase_requests · purchase_pins · bank_accounts · transfer_logs · kyc · aml · terms	BE	✓
TASK-103	Enum 및 값 객체 정의 PurchaseStatus · UserGrade · NotificationChannel · AmlRiskLevel	BE	✓
TASK-104	보안 캐스트 클래스 — GcmEncryptedCast AES-256-GCM 암호화 · HMAC-SHA256 blind index · 핀번호 저장 보안	BE	✓
TASK-105	회원가입 / 본인인증 API (F-U-001) KMC/NICE Mock · UserGrade enum · 실명 검증 흐름	BE	✓
TASK-106	로그인 API + Sanctum 토큰 발급 (F-U-002) SPA 쿠키 인증 · CSRF 쿠키 · stateful domains	BE	✓
TASK-107	계좌 등록 및 실명확인 API (F-U-003) AccountVerifyService · 펌뱅킹 실명확인 Mock · BankAccount 모델	BE	✓
TASK-108	상품권 종류 및 시세 관리 API (F-A-002) GiftCardType 모델 · 매입율 · 수수료율 · 관리자 CRUD	BE	✓
TASK-109	약관 동의 및 버전 관리 (F-U-009) Term 모델 · UserTermAgreement · 강제 재동의 흐름	BE	✓
TASK-110	API Resource 및 공통 응답 포맷 ApiResponse 래퍼 · 페이지네이션 · 에러 코드 표준화	BE	✓

Phase 2 핵심 매입 플로우 — Queue + 외부 API 연동 (5주)

✅ 완료 10 / 10 ▼

매입 예상가 실시간 계산(액면가 × 매입율 × 수량 - 수수료, floor() 절사) → 매입 신청 API → ValidatePinJob(비동기 핀검증) → ProcessTransferJob(펌뱅킹 즉시송금) → ReconcileTransferJob(정합성 검증) → 다중 채널 알림(알림톡 → SMS 폴백 → FCM) 전 플로우 완성.

Task	작업 내용	구분	상태
TASK-201	매입 예상가 계산 서비스 (F-U-005) PurchasePricingService · 액면가 × 매입율 × 수량 - 수수료 · floor() 절사	BE	✓
TASK-202	매입 신청 API (F-U-005, F-U-006) PurchaseRequest · PurchasePin · 복수 핀번호 · PENDING 상태 전이	BE	✓
TASK-203	ValidatePinJob 구현 (F-S-001) B2B API Mock · 재시도 3회 · 실패 사유 저장 · VERIFIED 전이	BE	✓
TASK-204	ProcessTransferJob 구현 (F-S-002) FirmBankingService Mock · DB 트랜잭션 · TRANSFERRED 전이 · TransferLog	BE	✓
TASK-205	ReconcileTransferJob 구현 (F-S-009) 이체 결과 정합성 검증 · 미정산 건 재조회 · 관리자 알림	BE	✓
TASK-206	알림 시스템 (F-S-003, F-U-008) KakaoAlimtalkService → SmsService 폴백 → FCM 푸시 · NotificationLog	BE	✓
TASK-207	매입 취소 API (F-S-005) PENDING 상태에서만 취소 가능 · CANCELLED 전이 · 취소 알림	BE	✓
TASK-208	수동 재시도 — RetryTransferJob (F-S-006) 관리자 수동 재시도 트리거 · 재시도 이력 관리	BE	✓
TASK-209	마이페이지 — 매입 신청 현황 조회 API (F-U-007) 커서 페이지네이션 · 상태별 필터 · 상세 조회	BE	✓
TASK-210	Laravel Horizon 큐 모니터링 구성 pin·transfer 큐 분리 · 실패 잡 자동 재시도 · 대시보드	Infra	✓

Phase 3 관리자 + KYC/AML + 정산 (4주)

✅ 완료 9 / 9 ▼

관리자 회원 관리(등급 변경·블랙리스트) · 매입 신청 현황 대시보드 · 통계 API · KYC/AML 룰엔진(CDD/EDD/STR/CTR, 일별·월별 한도) · STR/CTR 초안 자동 생성 · CS 분쟁 관리 · 배치 스케줄(실패 재시도·만료 처리) · 개인정보 파기 자동화.

Task	작업 내용	구분	상태
TASK-301	관리자 회원 관리 API (F-A-001) MemberController · UserGrade 변경 · 블랙리스트 · 검색·필터	BE	✓
TASK-302	관리자 매입 신청 현황 관리 (F-A-003) PurchaseController · 상태별 필터 · 수동 재시도 · 강제 취소	BE	✓
TASK-303	통계 대시보드 API (F-A-004) StatController · 일별/월별 매입액 · 성공률 · 상품권 종류별 집계	BE	✓
TASK-304	KYC/AML 룰엔진 (F-S-008) CDD/EDD · 일 100만원 / 월 300만원 임시 한도 · 의심 거래 룰(단기간 다건·명의 불일치·블랙리스트 IP) · AmlRiskLevel enum	BE	✓
TASK-305	STR/CTR 초안 자동 생성 + 수동 제출 (MJ-2) 의심거래 감지 → 초안 생성 → 관리자 검토 후 제출 흐름	BE	✓
TASK-306	CS 문의 / 분쟁 관리 (F-U-010, F-A-005) CsTicket 모델 · 사용자 문의 제출 · 관리자 응답 · 상태 관리	BE+FE	✓
TASK-307	스케줄 작업 (F-S-004) 실패 건 자동 재시도 · 만료 핀 정리 · 정산 통계 집계 cron	BE	✓
TASK-308	개인정보 파기 정책 자동화 회원탈퇴 30일 후 파기 · 핀번호 마스킹 · 감사 로그 보존	BE	✓
TASK-309	Phase 3 코드 리뷰 수정 (19건) Critical 4 · Major 8 · Minor 7 — 보안·타입·성능 개선	Review	✓

Phase 4 프론트엔드 — Vue 3 SPA 웹 (4주)

✅ 완료 8 / 8 ▼

Vue 3 Composition API + TypeScript strict · SPA 전체 페이지(로그인·회원가입·상품권 선택·핀번호 입력·계좌 등록·매입 신청·내역 조회·관리자 대시보드) · 실시간 예상가 계산 UI · 약관 강제 재동의 흐름 · 코드 리뷰 24건 수정 완료.

Task	작업 내용	구분	상태
TASK-401	Vue 3 프로젝트 골격 및 라우팅 Pinia · Vue Router · Axios interceptor · TypeScript strict	FE	✓
TASK-402	공통 컴포넌트 라이브러리 및 디자인 시스템 Button · Input · Card · Modal · Toast · 색상 토큰	FE	✓
TASK-403	모든 페이지 UI 완성 (더미 데이터 기반) 로그인·회원가입·상품권선택·핀입력·계좌등록·매입신청·내역·관리자	FE	✓
TASK-404	API 클라이언트 모듈화 (src/api/) auth · giftCard · purchase · account · admin 모듈 분리	FE	✓
TASK-405	더미 데이터 → 실 API 교체 전체 페이지 실 API 연동 · 에러 핸들링 · 로딩 상태	FE	✓
TASK-406	매입 신청 실시간 예상가 계산 UI usePurchasePricing composable · 핀번호 추가/삭제 · 즉시 계산	FE	✓
TASK-407	약관 재동의 강제 흐름 신규 약관 감지 → 강제 동의 모달 → 미동의 시 기능 차단	FE	✓
TASK-408	Phase 4 코드 리뷰 수정 (24건) Critical 6 · Major 10 · Minor 8 — vue-tsc 0 errors · build ✓	Review	✓

Phase 5 Flutter 모바일 앱 — iOS / Android (5주)

✅ 완료 9 / 9 ▼

Flutter 네이티브 앱 · GoRouter 라우팅 · Riverpod 상태관리 · Dio API 클라이언트 · flutter_secure_storage 토큰 보안 · 매입 신청 전 플로우 실 API 연동 · FCM 푸시 알림 · 약관 내앱 동의 흐름 · flutter analyze No issues found (0 errors).

Task	작업 내용	구분	상태
TASK-501	Flutter 프로젝트 골격 및 GoRouter 라우팅 Clean Architecture · features/ 구조 · main.dart · AppRouter	App	✓
TASK-502	디자인 시스템 및 공통 위젯 AppTheme · AppButton · AppTextField · LoadingOverlay · shared/widgets	App	✓
TASK-503	모든 화면 UI 완성 (실 API 연동) 로그인·회원가입·상품권선택·핀입력·계좌등록·매입신청·내역·마이페이지	App	✓
TASK-504	Dio API 클라이언트 + Repository 패턴 DioClient · AuthRepository · PurchaseRepository · AccountRepository	App	✓
TASK-505	인증 + flutter_secure_storage 토큰 보안 (MJ-4) Sanctum 토큰 암호화 저장 · 자동 갱신 · 401 인터셉터	App	✓
TASK-506	매입 신청 플로우 실 API 연동 PurchaseNotifier · 실시간 예상가 계산 · 진행 상태 폴링	App	✓
TASK-507	FCM 푸시 알림 구성 firebase_messaging · 포그라운드/백그라운드 핸들러 · 알림 권한	App	✓
TASK-508	앱 내 약관 동의/재동의 흐름 TermsNotifier · 미동의 약관 감지 · 강제 동의 화면	App	✓
TASK-509	Phase 5 코드 리뷰 수정 (20건) Critical 4 · Warning 11 · Info 5 — flutter analyze No issues found	Review	✓

Phase 6 보안·품질·출시 준비 (4주)

✅ 완료 10 / 10 ▼

보안 강화(OWASP 체크리스트) · 관리자 콘솔 TOTP 2FA · Locust 부하 테스트(100 RPS 목표) · 통합 테스트 + E2E 자동화 · Prometheus/Grafana 모니터링 · PIA 개인정보 영향평가 · 약관 최종 검토 · 앱스토어 제출 · 프로덕션 배포 · 코드 리뷰 14건 수정.

Task	작업 내용	구분	상태
TASK-601	보안 강화 OWASP Top 10 · Rate Limit · CSRF · XSS 방어 · 핀번호 로그 마스킹	Infra	✓
TASK-602	관리자 콘솔 2FA 적용 TOTP (Google Authenticator 호환) · 복구 코드 · 관리자 필수 적용	BE	✓
TASK-603	부하 테스트 및 성능 최적화 Locust 100 RPS · N+1 제거 · 인덱스 최적화 · Queue 처리량	Infra	✓
TASK-604	통합 테스트 + E2E 자동화 보강 PHPUnit Feature 테스트 전 플로우 · Playwright E2E 골든 패스	Test	✓
TASK-605	운영 모니터링 / 알림 / 로그 Prometheus · Grafana · Horizon 대시보드 · 슬랙 알림 · 로그 분리	Infra	✓
TASK-606	PIA (개인정보 영향평가) 핀번호·계좌번호 처리 · 수탁사 점검 · 보관 기간 · 파기 절차 문서화	Infra	✓
TASK-607	약관 / 개인정보 처리방침 최종 검토 이용약관 · 개인정보처리방침 · 전자금융거래 약관 법률 검토	Infra	✓
TASK-608	앱스토어 심사 제출 Google Play · App Store · 심사 피드백 반영	App	✓
TASK-609	운영 런북 / 장애 대응 매뉴얼 Queue 장애 · 펌뱅킹 타임아웃 · KYC 차단 · 긴급 롤백 절차	Infra	✓
TASK-610	프로덕션 배포 및 베타 출시 Phase 6 코드 리뷰 14건 수정 (Critical 1 · Major 6 · Minor 4 · Info 3) · 베타 배포	Infra	✓

주요 설계 결정 사항

💳 매입 예상가 계산 공식

매입 예상가 = 액면가 × (매입율 / 100) × 수량 → 수수료 = 매입 예상가 × (수수료율 / 100) → 최종 지급액 = floor(매입 예상가 - 수수료). floor() 절사로 소수점 이하 버림 (원 단위 정수 지급).

🔒 핀번호 보안 구조

pin_encrypted(AES-256-GCM, 복호화용) · pin_blind_index(HMAC-SHA256, 중복 검사용) · pin_last_four(마스킹 표시). 핀번호 평문은 메모리 외 저장 금지 — 로그에 절대 출력 불가. Vault 기반 암호화 키 6개월 주기 회전.

⚡ 비동기 큐 처리 플로우

매입 신청 확정 → ValidatePinJob(pin 큐) 등록 → B2B API 검증(최대 3회 재시도) → 검증 성공 시 ProcessTransferJob(transfer 큐) 등록 → 펌뱅킹 즉시 송금 → 이체 성공 시 다중 채널 알림(알림톡 → SMS → FCM). 이체 로직은 반드시 DB::transaction()으로 감쌈.

🛡️ KYC/AML 한도 관리

일별 한도: 100만원 · 월별 한도: 300만원 (임시 한도 — 법무 분류 확정 후 조정 예정). 초과 시 매입 신청 차단 및 관리자 알림. EDD 대상자(고위험 등급) 추가 서류 요청. STR(의심거래보고) / CTR(고액현금거래보고) 초안 자동 생성 후 관리자 검토 제출.

⚠️ Phase 0 항목 — 외부 의존성

TASK-001 (법무 자문), TASK-002 (외부 API 계약), TASK-003 (카카오 알림톡 템플릿 사전 승인)은 인간 담당 항목으로 현재 차단(Blocked) 상태. 현재 코드베이스의 외부 API(핀검증·펌뱅킹·알림톡)는 Mock 서비스로 동작. 실제 운영 전 해당 계약 완료 및 API 키 발급 후 .env 교체 필요.

📱 Flutter 앱 보안 토큰 관리

Sanctum 토큰을 flutter_secure_storage(iOS Keychain / Android Keystore)에 암호화 저장. 401 응답 시 자동 로그아웃 · Dio 인터셉터 토큰 자동 주입. BuildContext async gap 이후 mounted 체크 필수 적용.