Files

T

GA Pro 51f340e36e chore: incar 14도메인 데모 샘플데이터(V108) + 외부연동 활성화 가이드

- V108__incar도메인_샘플데이터.sql: P7/P8 14개 도메인 대표 샘플 시드(멱등 NOT EXISTS,
  기준월 202605). 신규 화면이 빈 화면으로 보이지 않도록 — 기존 V65/V69/V80 패턴.
  ROLLBACK 트랜잭션 사전검증(오류 0) 후 Flyway V108 success.
  라이브 확인: 12개 신규 엔드포인트 전부 200 + 샘플 rows 반환.
- docs/외부연동_활성화_가이드.md: KFTC/Toast/FCM 어댑터 운영 활성화 절차
  (전환 스위치 app.adapter.*, 환경변수 매트릭스, 사전조건, 검증법).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-31 21:09:12 +09:00

4.0 KiB

Raw Permalink Blame History

외부연동 활성화 가이드 (KFTC 펌뱅킹 / NHN Toast / FCM 푸시)

세 외부연동 어댑터는 코드 구현 완료 상태이며, 기본은 모두 Mock 으로 동작한다. 운영 활성화는 아래 환경변수(또는 application.yml)만 주입하면 된다. 키가 비어 있으면 어댑터는 fail-fast(IllegalStateException) 하여 잘못된 적용을 즉시 알린다.

공통 전환 스위치: app.adapter.{bank|message|push} = mock(기본) / kftc / toast / fcm 어댑터별 구현체는 ga-external-adapter 모듈, 모든 외부호출은 external_call_log 에 AOP 로 자동 감사된다.

1. KFTC 오픈뱅킹 입금이체 (펌뱅킹)

구현체: KftcBankTransferAdapter (입금이체 POST /v2.0/transfer/deposit/acnt_num + 이체결과조회)
활성화: ADAPTER_BANK=kftc

환경변수	설명	예시
`KFTC_BASE_URL`	API 베이스 (운영/테스트베드)	`https://openapi.openbanking.or.kr`
`KFTC_ACCESS_TOKEN`	이용기관 2-legged Access Token (주기 재발급)	(발급 토큰)
`KFTC_CNTR_ACCOUNT_NUM`	이용기관 약정 출금계좌 번호	(약정계좌)
`KFTC_CNTR_ACCOUNT_TYPE`	약정계좌 구분	`N`
`KFTC_WD_PRINT`	출금계좌 인자내역	`수수료정산`
`KFTC_NAME_CHECK`	수취인 실명확인 옵션	`off`

사전 조건(비개발): 금융결제원 이용기관 계약, 약정 출금계좌 등록, Access Token 발급 체계. 검증: 테스트베드에서 출금 1건 → withdraw_request.transfer_status 전이 + external_call_log 확인.

2. NHN Cloud(Toast) SMS / 카카오 알림톡

구현체: ToastMessageAdapter (SMS v3.0 + 알림톡 v2.3, MessageChannel 분기)
활성화: ADAPTER_MESSAGE=toast

환경변수	설명
`TOAST_SMS_APP_KEY` / `TOAST_SMS_SECRET_KEY`	SMS 프로젝트 AppKey / Secret Key
`TOAST_SENDER_NO`	사전 등록 발신번호
`TOAST_ALIMTALK_APP_KEY` / `TOAST_ALIMTALK_SECRET_KEY`	알림톡 AppKey / Secret Key
`TOAST_SENDER_KEY`	카카오 비즈메시지 발신프로필 SenderKey

사전 조건(비개발): NHN Cloud 프로젝트 + SMS/알림톡 상품 활성화, 발신번호 등록, 알림톡 템플릿 등록(발송 시 templateCode 필수). 검증: 본인 번호로 SMS 1건 발송 → header.isSuccessful=true + external_call_log 확인.

3. FCM 푸시 (모바일 PWA)

서버 구현체: FcmPushAdapter (HTTP v1 POST /v1/projects/{projectId}/messages:send)
활성화(서버): ADAPTER_PUSH=fcm

환경변수(서버)	설명
`FCM_PROJECT_ID`	Firebase 프로젝트 ID
`FCM_ACCESS_TOKEN`	서비스계정 OAuth2 토큰(scope `firebase.messaging`, 주기 재발급)

PWA(클라이언트) 활성화 — ga-mobile-pwa:

Firebase 콘솔 → 웹 앱 등록 → 설정값을 .env 의 VITE_FCM_* 로 주입 (VITE_FCM_API_KEY, VITE_FCM_PROJECT_ID, VITE_FCM_APP_ID, VITE_FCM_SENDER_ID, VITE_FCM_VAPID_KEY)
npm i firebase 후 src/push/initPush.ts 의 TODO 블록(firebase/messaging getToken) 활성화
public/firebase-messaging-sw.js 서비스워커 배치
로그인 시 initPush() 가 토큰 발급 → POST /api/mobile/me/device-tokens 자동 등록

동작 흐름(구현 완료): 알림 발생(예: 출금 SETTLED) → PushDispatchService 가 user_device_token 의 활성 토큰 조회 → PushAdapter.send. 토큰 미등록/Mock 이면 no-op. 검증: PWA 로그인 → device-token 등록 확인(user_device_token) → 출금 SETTLED 트리거 → 푸시 수신 + external_call_log(call_type=PUSH) 확인.

요약 — 남은 것은 "키 주입"뿐

연동	코드	활성화에 필요한 것(비개발)
KFTC 입금이체	✅ 완료	계약 + 약정계좌 + Access Token
Toast SMS/알림톡	✅ 완료	AppKey/SecretKey + 발신번호 + 알림톡 템플릿
FCM 푸시	✅ 완료(서버) / 스캐폴드(PWA)	Firebase 프로젝트 + `firebase` SDK + VAPID 키

4.0 KiB Raw Permalink Blame History