01. SNAP-AGENT 소개

SNAP 에이전트 소개서

1. SNAP 에이전트란?

SNAP 에이전트는 별도의 추가 개발 프로세스 없이, 고객사의 서버에 에이전트를 설치하고 데이터베이스(DB) 연동을 통해 손쉽게 메시지를 발송할 수 있도록 지원하는 서버 구축형 서비스입니다.

2. SNAP 에이전트의 구조 및 아키텍처

시스템 아키텍처 다이어그램

SNAP 에이전트는 내부의 5개 컴포넌트(Collector, Sender, Receiver, Updater, Mover)와 두 개의 큐(발송 Queue, 응답 Queue)가 유기적으로 맞물려 고객사 발송 DB와 LG U+ 메시지 G/W 간의 데이터를 처리합니다.

[발송 DB] ──(① 데이터 수집: ready)──> [ Collector ] ──(② ready → pre-send 상태 업데이트)
   │                                         │
   │                                  (③ 데이터 발송 대기)
   │                                         ▼
   │                                   [ 발송 Queue ]
   │                                         │
   │                                         ▼
   │                                     [ Sender ] ──(④ 데이터 전송)──> [ LG U+ 메시지 G/W ]
   │                                         │                                    │
   │                              (⑤ Deliver Ack 수집)                            │
   │                                         │                               (⑥ 데이터 결과 수신)
   │                                         ▼                                    │
   ◄──(⑨ 상태값 업데이트) ◄──────────── [ 응답 Queue ] ◄────(⑦ Report 수집) ◄─── [ Receiver ]
   │                                         ▲
   │                                  (⑧ Update 대기)
   ▼
(⑩ 이관 대상 데이터 수집)
   │
   ▼
[ Mover ] ──(⑪ 데이터 이관)──> [ 이력 DB ]

컴포넌트별 상세 기능

📋 Collector (데이터 수집 및 적재)
- ① 데이터 수집: 메시지 발송을 위해 발송 DB에서 상태 값이 ready인 항목들을 1,000건씩 자동으로 읽어옵니다.
- ② 상태 업데이트: 읽어온 데이터의 상태 값을 즉시 pre-send로 업데이트하여 중복 수집을 방지합니다.
- ③ 데이터 발송 대기: 수집한 데이터를 발송 Queue에 안전하게 적재합니다.
📤 Sender (메시지 전송)
- ④ 데이터 전송: 발송 Queue에 대기 중인 메시지를 읽어 LG U+ 메시지 G/W로 전송합니다.
- ⑤ 데이터 발송 상태 값 수집 (Deliver Ack): 정상적으로 G/W에 전송이 완료되면 Deliver Ack 상태 값을 수집하여 응답 Queue에 저장합니다.
📥 Receiver (결과 수신)
- ⑥ 데이터 결과 수신: LG U+ 메시지 G/W로부터 단말기 도달 여부 등 최종 메시지 처리 결과를 수신합니다.
- ⑦ 데이터 발송 상태 값 수집 (Report): 수신한 Report 결과 값을 응답 Queue에 저장합니다.
🔄 Updater (상태 값 반영)
- ⑧ 데이터 Update 대기: 응답 Queue에 쌓인 전송 및 결과 데이터를 순차적으로 대기시킵니다.
- ⑨ 데이터 발송 상태 값 업데이트: 발송 DB에 최종 상태 값을 실시간으로 업데이트합니다.
  - ⑤번에 의한 변경: pre-send → request
  - ⑦번에 의한 변경: request → complete
📦 Mover (데이터 이관 및 정리)
- ⑩ 이관 대상 데이터 수집: 발송 DB에서 처리가 완전히 끝난 데이터를 수집합니다.
  - 정상 이관: 결과 수신이 완료(complete)된 데이터를 100건씩 가져옵니다.
  - 타임아웃(Timeout) 이관: 지정된 시간 동안 발송 테이블에 남아있는 데이터를 expire 처리하여 수집합니다. (Timeout 기준: SMS 26시간 / MMS·HUB 74시간)
- ⑪ 데이터 이관: 수집한 데이터를 이력 DB로 안전하게 이관하여 발송 DB의 성능을 최적화합니다.

3. SNAP 에이전트 발송 상태 값 흐름

메시지 발송 단계에 따라 데이터는 다음과 같은 상태 표준을 가집니다.

단계	상태 값 코드	의미	관련 컴포넌트
발송 요청	`ready` (또는 0)	고객사 시스템에서 발송할 데이터를 등록한 상태	Collector 수집 대상
발송 대기	`pre-send` (또는 9)	에이전트가 데이터를 가져와 발송 큐에 등록한 상태	Collector 변경 / Sender 처리 대상
발송 요청 완료	`request`	LG U+ G/W로 전송 완료 및 Ack 접수 상태 (`SMS: 1`, `MMS: 2`)	Sender 수집 / Updater 반영
결과 수신 완료	`complete`	최종 이동통신사 결과(Report)까지 수신 완료된 상태 (`SMS: 2`, `MMS: 3`)	Receiver 수집 / Updater 반영

4. 공식 가이드라인 및 레퍼런스

상세 연동 규격, 환경 설정 가이드 및 연동 과정에서 발생하는 오류 코드 확인은 공식 안내 페이지를 참조하시기 바랍니다.

공식 Notion 안내 사이트: LG U+ 메시지허브 에이전트 가이드

⚠️ 초기 설정 시 필수 주의사항 SNAP 에이전트는 기본적으로 DB 데이터를 실시간으로 조회(Polling)하며 메시지를 발송합니다. 따라서 2개 이상의 에이전트가 동일한 발송 DB 테이블을 바라보도록 설정하면 메시지가 중복 발송될 위험이 있습니다. 초기 환경 구성 시 에이전트별 대상 테이블 혹은 식별 조건을 반드시 분리하여 설정하시기 바랍니다.