Files

T

HeuJung e7fa1b5535 feat(message_bizppurio): 알림 템플릿 편집 통합·검수 의견·관리탭 개선 및 언어팩 번역 보존 결함군 수정

비즈뿌리오 알림톡 UX 개편 후속:
- 코어/게시판/이커머스 알림 템플릿 [편집] 모달에 확장 채널 편집 영역
 (extension_point 2종 + hidden_template_editor 채널 메타)을 신설하고,
 알림톡 템플릿·문자(SMS)·수신자 규칙을 한 창에서 통합 저장하도록 개정
 (행 하단은 상태 요약 전용, 승인 여부 2단 배지)
- 검수 신청에 검수자 전달 의견(comment) 동봉 — kapi request 로만 전달,
 행에는 저장하지 않음 (FormRequest 신설 + API 문서 백필)
- 관리 탭 모바일 카드뷰·도구줄 코어 관례 통일, 사이트맵 알림 정의
 다국어 라벨 결측 수정 + 코어 정의 라벨 패리티 테스트 신설

언어팩 번역 소실·보존 결함군 (보완 실측 → 커밋 전 점검에서 연쇄 확정,
전부 실패 테스트 선행 후 수정):
- [기본값 복원]이 활성 언어팩 번역(ja)을 영구 소실 → 복원 기본값에
 시딩과 같은 주입기(SSoT)로 팩 로케일 병합 (notification·identity)
- 코어 알림/본인인증 시더의 언어팩 주입 전면 불능 → 주입기가 연관/리스트
 양형태 수용 + identity 시더의 config 복합 키 보존
- 실패한 언어팩 업데이트가 active 팩을 installed 로 방치 → 상태 복원 확장
- 병합·제거의 사용자 수정 보존 판정 사문(연관 전제 isset) → dot-path 판정
 교정, 팩 주입 저장의 user_overrides 오염 차단(시딩 바인딩), 템플릿
 2모델 translatableTrackableFields 선언(beta.4 설계 누락), 같은 프로세스
 활성화 시 시더 번역 필터 stale(캡처 인스턴스 캐시) 교정
- 7.0.9 업그레이드 스텝 신설 — 활성 팩 seed 재동기화로 기설치본의 소실
 번역 자동 복구 (멱등·운영자 수정 보존·팩별 실패 격리)

2026-08-24 14:51:37 +09:00

15 KiB

Raw Blame History

Bizppurio Messaging Plugin for G7

비즈뿌리오(Bizppurio)를 연동해 문자(SMS/LMS)와 카카오 알림톡을 발송하는 G7 플러그인입니다.

G7 코어 알림 시스템에 문자·알림톡 채널을 추가해, 회원가입·주문 등 코어/모듈이 발화하는 알림을 문자와 알림톡으로도 자동 발송합니다. 발송 결과는 비즈뿌리오가 보내는 webhook 통보로 수신해 성공/실패와 실패 사유를 발송 이력에 기록합니다.

주요 기능 · 요구 사항 · 설치 · 관리자 설정 · webhook 등록 · 발송 흐름 · 알림톡 템플릿 관리 · 발송 결과 코드 · 훅 · API · 테스트

주요 기능

문자(SMS/LMS) 발송 — 본문 길이에 따라 SMS/LMS 자동 선택
카카오 알림톡 발송 — 승인된 템플릿의 본문·버튼·바로연결·강조표기·아이템리스트·대표링크까지 반영
알림톡 미승인·발송 불가 시 문자로 자동 대체발송(옵션)
회원·비회원 대상 알림에 문자 채널 연동 (비회원은 주문 시 입력한 연락처 사용)
비즈뿌리오 webhook 리포트 수신으로 발송 결과(성공/실패/사유) 자동 기록
검수(테스트) 모드 — 실제 발송 없이 화면·흐름 검증
지갑 잔액 부족·후불 한도 초과 시 관리자 알림 (반복 발송 방지 쿨다운 적용)
관리자 "알림 발송 이력" 화면에 문자·알림톡 결과 통합 표시
알림별 카카오 알림톡 템플릿을 관리자 화면에서 직접 작성 → 검수 신청 → 승인 후 자동 발송
검수 결과(승인·반려)를 30분 주기로 자동 확인하고, 반려 사유를 화면에서 확인해 수정 후 재신청

요구 사항

구분	항목	내용
플랫폼	G7	`>= 7.0.6`
플랫폼	PHP	`^8.2`
사전 준비	비즈뿌리오 계정	가입 + API 사용 승인
사전 준비	문자 발송	발신번호 사전 등록 (비즈뿌리오 콘솔)
사전 준비	알림톡 발송	카카오 발신프로필 등록 (템플릿은 이 플러그인 화면에서 작성·검수 신청)

운영 모드로 전환하려면 비즈뿌리오 아이디·비밀번호·API 키·발신번호가 모두 입력되어야 하며, 이 시점부터 실제 발송과 비용이 발생합니다.

설치

플러그인을 G7 프로젝트의 플러그인 디렉토리에 배치합니다.

plugins/sirsoft-message_bizppurio

프론트엔드 에셋을 수정한 경우 플러그인 디렉토리에서 빌드합니다.

npm install
npm run build

그다음 G7 관리자에서 플러그인을 활성화합니다. 설치 시 회원 대상 알림의 문자·알림톡 채널이 알림 설정에 등록됩니다.

관리자 설정

관리자 플러그인 설정 화면에서 비즈뿌리오 계정 정보를 입력합니다.

설정	필수 여부	설명
검수 모드	-	활성화 시 실제 발송 없이 검수용으로만 동작. 발송 이력에 "검수" 라벨로 표시되어 실제 장애와 구분됨
비즈뿌리오 아이디 / 비밀번호	운영 시 필수	비즈뿌리오 계정 로그인 정보
API 키	운영 시 필수	비즈뿌리오 API 인증에 사용
발신번호	운영 시 필수	문자 발송용 발신번호. 비즈뿌리오 콘솔에 사전 등록된 번호만 사용 가능
알림톡 발신프로필 키	알림톡 사용 시 필수	카카오 알림톡 발송에 사용할 발신프로필 키
잔액부족 알림 재발송 간격(초)	선택 (기본 3600)	잔액 부족/한도 초과 실패 시 관리자 알림의 최소 재발송 간격. 대량 실패 시 반복 발송 방지

검수와 운영은 별도의 비즈뿌리오 계정으로 운영하는 것을 권장합니다. 비밀번호·API 키·발신프로필 키는 관리자 설정 화면에서만 입력하며 프론트엔드로 노출되지 않습니다.

webhook(발송 결과 리포트) 등록

비즈뿌리오가 발송 결과를 통보할 URL을 비즈뿌리오 콘솔에 등록해야 발송 결과(성공/실패/사유)가 발송 이력에 자동 기록됩니다.

이 등록을 하지 않으면 발송 자체는 되지만 성공/실패 여부를 확인할 수 없습니다.

https://your-domain.com/api/plugins/sirsoft-message_bizppurio/webhook

정확한 URL은 관리자 플러그인 설정 화면의 환경설정 탭에서도 복사할 수 있습니다.

발송 흐름

코어/모듈이 알림 발화 (예: 회원가입, 주문 완료)
→ 알림 설정에서 켜 둔 문자·알림톡 채널로 발송 작업 큐잉
→ 알림톡: 승인된 템플릿의 저장 내용으로 발송, 발송 불가 시 문자로 대체발송(옵션)
→ 문자: 본문 길이에 따라 SMS/LMS 자동 선택
→ 비즈뿌리오 발송 API 호출
→ 비즈뿌리오가 webhook 으로 결과(성공/실패/사유) 통보
→ 발송 이력에 결과 기록, 실패 시 사유·결과코드 함께 기록

일시적 오류(카카오 시스템 오류, 처리 지연, 게이트웨이 오류 등)로 실패한 경우 자동으로 재시도합니다. 지갑 잔액 부족·후불 한도 초과는 재시도 대상이 아니며, 즉시 실패 처리와 함께 관리자에게 알림이 발송됩니다.

알림톡 템플릿 관리

카카오 알림톡 템플릿의 작성·검수 신청·취소·삭제를 관리자 화면에서 직접 수행합니다. 비즈뿌리오 콘솔을 따로 열 필요가 없습니다.

작성 위치는 두 곳입니다.

알림 설정 > 비즈뿌리오 탭 — 알림 항목의 [편집] 을 누르면 알림 템플릿 편집 창 안에 알림톡 템플릿 섹션과 문자(SMS) 섹션이 함께 열립니다. 알림톡 본문·유형·버튼, 대체 SMS/SMS 단독 여부와 문자 본문, 수신자 규칙을 한 창에서 고치고 하단 [저장] 한 번으로 모두 저장합니다(알림톡 검수는 [저장 후 검수 신청] — 작성 폼 하단의 검수자 전달 의견에 변수 예시값 등을 적으면 신청과 함께 카카오 검수자에게 전달됩니다). 이 채널에서는 코어의 제목/본문 입력이 숨겨지고 알림톡 본문이 그 자리를 대신합니다. 알림 목록의 각 행 하단에는 승인 여부(승인됨 / 미승인 (세부 상태))와 문자 설정 요약이 표시됩니다. 게시판·이커머스의 알림 설정 화면에서도 동일하게 동작합니다.
플러그인 설정 > 알림 템플릿 관리 — 전체 알림의 템플릿 상태를 한 화면에서 보고 검색·필터링합니다(자체 작성/SMS 본문 모달).

기본 흐름은 작성 → 검수 신청 → (카카오 승인) → 자동 발송 입니다. 승인된 시점의 내용이 발송 기준으로 저장되며, 발송할 때마다 카카오를 조회하지 않습니다.

메시지 유형(기본형·부가정보형·채널추가형·복합형)과 강조 유형(없음·강조표기·이미지·아이템리스트), 버튼(최대 5개)·바로연결(최대 10개)을 지원합니다. 본문에는 #{변수} 형식으로 알림 변수를 넣을 수 있습니다.

이미지 강조 유형에 쓸 이미지는 화면에서 직접 업로드하며, 카카오 규격에 따라 jpg/png · 500KB 이하 · 가로 500px 이상 · 가로:세로 2:1 비율이어야 합니다. 규격에 맞지 않으면 업로드 단계에서 사유와 함께 거부됩니다.

상태	발송 가능	설명
미작성	❌	템플릿 내용을 아직 작성하지 않은 상태
작성중	❌	저장했으나 검수를 신청하기 전 상태 (내용 수정 가능)
검수중	❌	카카오 검수 진행 중. 내용을 고치려면 먼저 [신청 취소]
승인	✅	검수 승인 완료 — 이 알림이 발생하면 알림톡이 발송됩니다
반려	❌	카카오 검수 반려. 화면에서 사유를 확인하고 수정 후 재신청
중지	❌	카카오에서 사용 중지된 템플릿
차단	❌	카카오에서 차단된 템플릿
휴면	❌	장기 미사용으로 휴면 전환. 화면의 [휴면 해제]로 복구

검수 결과는 30분 주기로 자동 확인하며, 편집 창의 [새로고침]으로 즉시 확인할 수도 있습니다.

검수중·승인된 템플릿은 편집 창에서 내용이 잠기고 요약만 표시됩니다. 검수중이면 [신청 취소] 후, 승인된 템플릿은 [수정 (승인 취소)] 를 눌러 승인을 먼저 취소해야 고칠 수 있습니다. 승인을 취소하면 그 즉시 해당 알림의 알림톡 발송이 중단되므로(대체 SMS 는 설정에 따라 계속 발송), 같은 창의 확인 박스에서 확인 후 진행합니다.

문자(SMS) 본문

알림마다 문자 본문을 따로 입력합니다(편집 창의 문자(SMS) 섹션). 쓰임은 두 가지이고 본문은 하나를 공유하며, 카카오 검수 대상이 아니므로 [저장] 즉시 반영됩니다.

대체 SMS — 알림톡 발송이 실패했을 때(수신 거부·미가입 등) 같은 번호로 문자를 대신 보냅니다.
SMS 단독 — 알림톡을 쓰지 않고 문자로만 보냅니다. 이 항목을 켜면 템플릿이 승인 상태여도 알림톡을 보내지 않습니다.

문자 본문은 언어별로 입력하며, 회원이 사용하는 언어의 본문으로 발송됩니다. 해당 언어의 본문이 비어 있으면 기본 언어 본문으로 발송하고, 기본 언어도 비어 있으면 그 알림의 문자 발송을 건너뜁니다. 알림톡 본문은 카카오가 승인한 원문 그대로만 발송할 수 있어 언어 구분이 없습니다.

발송 결과 코드

비즈뿌리오/카카오가 반환하는 결과 코드는 4가지로 분류되어 처리됩니다.

분류	처리 방침
성공	발송 완료
재시도 (일시 오류)	자동 재시도 대상 (예: 카카오 시스템 오류, 처리 지연, 게이트웨이 오류)
잔액 부족	즉시 실패 처리 + 관리자 자체 알림
영구 실패	즉시 실패 처리, 재시도하지 않음

주요 코드 예시:

코드	분류	사유
`1000` `4100` `6600` `7000`	성공	발송/리포트 성공
`9070`	잔액 부족	잔액 부족(문자)
`9071`	잔액 부족	후불 한도 초과
`7436`	잔액 부족	지갑 잔액 부족(알림톡)
`4400`	영구 실패	음영 지역
`7103`	영구 실패	발신 프로필 키 무효

발송 이력 화면에는 사유 (코드) 형식(예: "음영 지역 (4400)")으로 표시됩니다. 전체 코드 목록은 lang/ko/result_codes.php / lang/en/result_codes.php에 정의되어 있으며, lang에 없는 코드는 코드만 표시됩니다.

가용 훅 (Hook)

다른 모듈이나 플러그인에서 아래 훅에 연결해 잔액부족 상황을 확장 처리할 수 있습니다.

액션 훅

훅 이름	시점	인수
`sirsoft-message_bizppurio.balance.low`	잔액 부족·한도 초과로 발송 실패 시 (쿨다운 내 최초 1회)	`string $resultCode, string $channel`

훅 등록 예시

use App\Extension\HookManager;

HookManager::addAction(
    'sirsoft-message_bizppurio.balance.low',
    function (string $resultCode, string $channel) {
        // 예: 잔액 부족 시 Slack으로도 별도 알림
        SlackNotifier::send("비즈뿌리오 잔액 부족: 채널={$channel}, 코드={$resultCode}");
    },
    priority: 10
);

$resultCode는 잔액 부족(9070 문자 / 7436 알림톡) 또는 후불 한도 초과(9071) 코드입니다. 이 훅은 관리자 자체 알림(잔액부족/후불한도초과 안내)을 발화하는 지점과 동일하며, 채널별 쿨다운(기본 3600초) 동안 한 번만 실행됩니다.

API

전체 엔드포인트 레퍼런스는 docs/api/README.md를 참고하세요.

문서	내용
webhook.md	비즈뿌리오 발송 결과 리포트 수신
templates.md	알림톡 템플릿 라이프사이클 관리 (작성·검수 신청·상태 동기화·발송 설정)
alimtalk-templates.md	알림톡 카테고리·발신프로필 조회
token.md	비즈뿌리오 인증 토큰
dispatch-results.md	발송 결과 조회
report.md	발송 결과 리포트 URL 조회

권한

권한	설명
`sirsoft-message_bizppurio.messaging.view`	발송 이력, 알림톡 템플릿, 발송 결과 조회
`sirsoft-message_bizppurio.messaging.manage`	알림톡 템플릿 작성·검수 신청·신청/승인 취소·상태 동기화·삭제, 대체 SMS 설정 등 관리 작업

삭제 시 동작

플러그인을 삭제하면 이 플러그인이 알림 설정에 추가했던 문자·알림톡 채널이 함께 정리됩니다. 메일·사이트 내 알림 등 다른 채널과 알림 자체는 그대로 유지되며, 플러그인을 다시 설치하면 문자·알림톡 채널이 자동으로 복원됩니다.

보안 및 운영 참고

비즈뿌리오 비밀번호, API 키, 알림톡 발신프로필 키는 외부에 노출하지 마세요. 관리자 설정 화면에서만 입력하며 프론트엔드로 노출되지 않습니다.
운영 모드 전환 전 검수 모드에서 문자·알림톡 발송 흐름을 먼저 확인하세요. 운영 모드는 실제 발송과 비용이 발생합니다.
webhook URL을 비즈뿌리오 콘솔에 등록하지 않으면 발송 결과 확인이 불가능합니다.
검수와 운영은 별도의 비즈뿌리오 계정 사용을 권장합니다.
지갑 잔액/후불 한도를 주기적으로 확인하세요. 부족 시 관리자 알림이 발송되지만, 알림 자체도 같은 채널(문자/알림톡)을 사용하지 않는 별도 채널(예: 사이트 내 알림, 메일)로 함께 받는 것을 권장합니다.

테스트

플러그인을 G7 프로젝트에 배치한 뒤 G7 루트에서 PHP 테스트를 실행합니다.

php artisan test plugins/sirsoft-message_bizppurio/tests

프론트엔드 테스트와 빌드는 플러그인 디렉토리에서 실행합니다.

npm install
npm run test:run
npm run build

라이선스

MIT

15 KiB Raw Blame History