GA Pro
51f340e36e
- 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>
75 lines
4.0 KiB
Markdown
75 lines
4.0 KiB
Markdown
# 외부연동 활성화 가이드 (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`:
|
|
1. Firebase 콘솔 → 웹 앱 등록 → 설정값을 `.env` 의 `VITE_FCM_*` 로 주입
|
|
(`VITE_FCM_API_KEY`, `VITE_FCM_PROJECT_ID`, `VITE_FCM_APP_ID`, `VITE_FCM_SENDER_ID`, `VITE_FCM_VAPID_KEY`)
|
|
2. `npm i firebase` 후 `src/push/initPush.ts` 의 TODO 블록(firebase/messaging `getToken`) 활성화
|
|
3. `public/firebase-messaging-sw.js` 서비스워커 배치
|
|
4. 로그인 시 `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 키 |
|