From 579965ed5c7bed12bc06493b6a843fcc5393ad7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sat, 14 Feb 2026 15:09:45 +0900 Subject: [PATCH] =?UTF-8?q?docs:=EB=B0=94=EB=A1=9C=EB=B9=8C=20=EC=B9=B4?= =?UTF-8?q?=EC=B9=B4=EC=98=A4=ED=86=A1=20=EC=97=B0=EB=8F=99=20=EA=B0=9C?= =?UTF-8?q?=EB=B0=9C=EB=AC=B8=EC=84=9C=20=EC=B4=88=EC=95=88=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- INDEX.md | 1 + features/barobill-kakaotalk/README.md | 252 ++++++++++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 features/barobill-kakaotalk/README.md diff --git a/INDEX.md b/INDEX.md index 2505615..4b055a2 100644 --- a/INDEX.md +++ b/INDEX.md @@ -122,6 +122,7 @@ docs/ | 문서 | 설명 | |------|------| +| [barobill-kakaotalk/README.md](features/barobill-kakaotalk/README.md) | 바로빌 카카오톡 (알림톡/친구톡) 연동 | | [boards/README.md](features/boards/README.md) | 게시판 시스템 구현 | | [boards/mng-implementation.md](features/boards/mng-implementation.md) | MNG 게시판 구현 상세 | | [hr/hr-api-analysis.md](features/hr/hr-api-analysis.md) | HR API 분석 (근태/직원/부서) | diff --git a/features/barobill-kakaotalk/README.md b/features/barobill-kakaotalk/README.md new file mode 100644 index 0000000..846c63d --- /dev/null +++ b/features/barobill-kakaotalk/README.md @@ -0,0 +1,252 @@ +# 바로빌 카카오톡 (알림톡/친구톡) 연동 + +> **문서 버전**: 0.1 (초안) +> **작성일**: 2026-02-14 +> **최종 수정**: 2026-02-14 +> **상태**: 개발 중 (사전 준비 단계) +> **대상 프로젝트**: MNG + +--- + +## 1. 개요 + +### 1.1 목적 + +바로빌(Barobill) 플랫폼의 카카오톡 알림톡/친구톡 API를 SAM에 연동하여, +고객사에 카카오톡 메시지를 자동 또는 수동으로 발송하는 기능을 제공한다. + +### 1.2 사전 요구사항 (미완료) + +| 항목 | 상태 | 설명 | +|------|------|------| +| 법인 명의 휴대폰 준비 | **대기** | 카카오톡 채널 가입에 법인 명의 번호 필요 | +| 카카오톡 채널 개설 | **대기** | [카카오비즈니스](https://business.kakao.com) 에서 채널 생성 | +| 바로빌 카카오톡 서비스 신청 | **대기** | 바로빌 관리자 페이지에서 카카오톡 서비스 활성화 | +| 채널 연동 (바로빌↔카카오) | **대기** | 바로빌 관리 URL에서 채널 연동 처리 | +| 알림톡 템플릿 등록/검수 | **대기** | 카카오 검수 승인 필요 (1~3 영업일) | + +### 1.3 알림톡 vs 친구톡 + +| 구분 | 알림톡 | 친구톡 | +|------|--------|--------| +| **용도** | 정보성 메시지 (주문확인, 배송안내 등) | 광고성 메시지 (프로모션, 이벤트 등) | +| **수신 대상** | 모든 카카오톡 사용자 | 채널 친구 추가한 사용자만 | +| **템플릿** | 필수 (카카오 사전 검수) | 불필요 (자유 형식) | +| **광고 표시** | 불가 | 필수 (`(광고)` 표기) | +| **이미지 첨부** | 불가 | 가능 (이미지/와이드 이미지) | +| **비용** | 건당 약 8~9원 | 건당 약 15~20원 | +| **SMS 대체발송** | 설정 가능 | 설정 가능 | + +--- + +## 2. 아키텍처 + +### 2.1 시스템 구조 + +``` +SAM MNG (브라우저) + │ + ├─ [페이지] /barobill/kakaotalk/* ← Blade 뷰 + │ KakaotalkController (페이지 렌더링) + │ + └─ [API] /api/admin/barobill/kakaotalk/* ← AJAX 호출 + BarobillKakaotalkController + │ + └─ BarobillService (SOAP 클라이언트) + │ + └─ 바로빌 KAKAOTALK.asmx (WSDL) + │ + └─ 카카오톡 서버 +``` + +### 2.2 바로빌 SOAP API 엔드포인트 + +| 환경 | WSDL URL | +|------|----------| +| **테스트** | `https://testws.baroservice.com/KAKAOTALK.asmx?WSDL` | +| **운영** | `https://ws.baroservice.com/KAKAOTALK.asmx?WSDL` | + +--- + +## 3. 구현 현황 + +### 3.1 완료된 항목 + +| 구분 | 파일 | 설명 | +|------|------|------| +| SOAP 서비스 | `app/Services/Barobill/BarobillService.php` | kakaotalk SOAP 클라이언트 + 15개 API 메서드 추가 | +| API 컨트롤러 | `app/Http/Controllers/Api/Admin/Barobill/BarobillKakaotalkController.php` | 15개 API 엔드포인트 | +| 페이지 컨트롤러 | `app/Http/Controllers/Barobill/KakaotalkController.php` | 6개 페이지 (index, channels, templates, send, history, guide) | +| 라우트 (web) | `routes/web.php` | `/barobill/kakaotalk/*` 6개 라우트 | +| 라우트 (api) | `routes/api.php` | `/api/admin/barobill/kakaotalk/*` 14개 라우트 | +| 대시보드 뷰 | `views/barobill/kakaotalk/index.blade.php` | 채널 상태 요약, 빠른 메뉴 | +| 채널 관리 뷰 | `views/barobill/kakaotalk/channels/index.blade.php` | 채널 목록, 관리 URL 연결 | +| 템플릿 관리 뷰 | `views/barobill/kakaotalk/templates/index.blade.php` | 채널별 템플릿 조회, 상세 모달 | +| 발송 뷰 | `views/barobill/kakaotalk/send/index.blade.php` | 알림톡/친구톡 탭, 발송 폼 | +| 전송내역 뷰 | `views/barobill/kakaotalk/history/index.blade.php` | 전송키 조회, 예약 취소 | +| 사용법 가이드 뷰 | `views/barobill/kakaotalk/guide.blade.php` | 초보자용 8단계 가이드 | +| 메뉴 등록 | DB (menus 테이블) | 로컬/서버 모두 등록 완료 | + +### 3.2 미완료 / 검증 필요 항목 + +| 항목 | 상태 | 비고 | +|------|------|------| +| 채널 API 실제 호출 테스트 | **대기** | 카카오 채널 개설 후 가능 | +| 템플릿 조회 테스트 | **대기** | 템플릿 등록/검수 후 가능 | +| 알림톡 발송 테스트 | **대기** | 채널+템플릿 준비 후 가능 | +| 친구톡 발송 테스트 | **대기** | 채널 친구 추가 후 가능 | +| SMS 대체발송 테스트 | **대기** | 바로빌 SMS 서비스 활성화 필요 | +| 대량 발송 테스트 | **대기** | 단건 테스트 완료 후 | +| 에러 핸들링 고도화 | **대기** | 실제 API 응답 확인 후 개선 | + +--- + +## 4. API 메서드 목록 + +### 4.1 BarobillService 카카오톡 메서드 + +| 메서드 | SOAP Action | 설명 | +|--------|-------------|------| +| `getKakaotalkChannels` | `GetKakaotalkChannels` | 채널 목록 조회 | +| `getKakaotalkChannelManagementUrl` | `GetKakaotalkChannelManagementURL` | 채널 관리 URL (바로빌 페이지) | +| `getKakaotalkTemplates` | `GetKakaotalkTemplates` | 템플릿 목록 조회 | +| `getKakaotalkTemplateManagementUrl` | `GetKakaotalkTemplateManagementURL` | 템플릿 관리 URL | +| `sendATKakaotalk` | `SendATKakaotalk` | 알림톡 단건 발송 | +| `sendATKakaotalkEx` | `SendATKakaotalkEx` | 알림톡 단건 발송 (버튼 포함) | +| `sendATKakaotalks` | `SendATKakaotalks` | 알림톡 대량 발송 | +| `sendFTKakaotalk` | `SendFTKakaotalk` | 친구톡 텍스트 단건 | +| `sendFTKakaotalks` | `SendFTKakaotalks` | 친구톡 텍스트 대량 | +| `sendFIKakaotalk` | `SendFIKakaotalk` | 친구톡 이미지 | +| `sendFWKakaotalk` | `SendFWKakaotalk` | 친구톡 와이드 이미지 | +| `getSendKakaotalk` | `GetSendKakaotalk` | 전송 결과 단건 조회 | +| `getSendKakaotalks` | `GetSendKakaotalks` | 전송 결과 다건 조회 | +| `cancelReservedKakaotalk` | `CancelReservedKakaotalk` | 예약 전송 취소 | + +### 4.2 REST API 엔드포인트 + +| Method | URL | 설명 | +|--------|-----|------| +| GET | `/api/admin/barobill/kakaotalk/channels` | 채널 목록 | +| GET | `/api/admin/barobill/kakaotalk/channels/management-url` | 채널 관리 URL | +| GET | `/api/admin/barobill/kakaotalk/templates` | 템플릿 목록 | +| GET | `/api/admin/barobill/kakaotalk/templates/management-url` | 템플릿 관리 URL | +| POST | `/api/admin/barobill/kakaotalk/send/alimtalk` | 알림톡 단건 | +| POST | `/api/admin/barobill/kakaotalk/send/alimtalk-bulk` | 알림톡 대량 | +| POST | `/api/admin/barobill/kakaotalk/send/friendtalk` | 친구톡 텍스트 | +| POST | `/api/admin/barobill/kakaotalk/send/friendtalk-image` | 친구톡 이미지 | +| POST | `/api/admin/barobill/kakaotalk/send/friendtalk-wide` | 친구톡 와이드 | +| GET | `/api/admin/barobill/kakaotalk/send/{sendKey}` | 전송 결과 단건 | +| POST | `/api/admin/barobill/kakaotalk/send/results` | 전송 결과 다건 | +| DELETE | `/api/admin/barobill/kakaotalk/send/{sendKey}/cancel` | 예약 취소 | + +--- + +## 5. WSDL 데이터 타입 + +### 5.1 핵심 타입 + +``` +KakaotalkChannel +├── ChannelId (string) 채널 ID (@로 시작) +├── ChannelName (string) 채널명 +└── Status (int) 상태 + +KakaotalkTemplate +├── ChannelId (string) 채널 ID +├── TemplateName (string) 템플릿 이름 +├── TemplateContent (string) 템플릿 본문 +├── TemplateExtra (string) 부가 정보 +├── Status (int) 검수 상태 +└── Buttons (array) 버튼 목록 + +KakaotalkATMessage (알림톡) +├── ReceiverName (string) 수신자 이름 +├── ReceiverNum (string) 수신자 번호 (01012345678) +├── Title (string) 제목 (강조 표시용) +├── Message (string) 메시지 (템플릿 변수 치환 후) +├── SmsMessage (string) SMS 대체 메시지 +└── SmsSubject (string) SMS 대체 제목 + +KakaotalkFTMessage (친구톡) +├── ReceiverName (string) 수신자 이름 +├── ReceiverNum (string) 수신자 번호 +├── Message (string) 메시지 (자유 형식) +├── SmsMessage (string) SMS 대체 메시지 +├── SmsSubject (string) SMS 대체 제목 +└── Buttons (array) 버튼 목록 + +KakaotalkButton +├── Name (string) 버튼 텍스트 +├── ButtonType (string) WL(웹링크), AL(앱링크), BK(봇키워드), MD(메시지전달) +├── Url1 (string) 모바일 URL +└── Url2 (string) PC URL +``` + +--- + +## 6. 메뉴 구조 + +### 6.1 사이드바 메뉴 + +``` +바로빌 > 카카오톡 +├── 카카오톡 (대시보드) /barobill/kakaotalk +├── 채널관리 /barobill/kakaotalk/channels +├── 템플릿관리 /barobill/kakaotalk/templates +├── 발송 /barobill/kakaotalk/send +├── 전송내역 /barobill/kakaotalk/history +└── 사용법 /barobill/kakaotalk/guide +``` + +### 6.2 메뉴 DB 정보 + +| 환경 | 부모 메뉴 ID (카카오톡) | 하위 메뉴 ID 범위 | +|------|------------------------|-------------------| +| 로컬 | 15614 | 15615 ~ 15619 | +| 서버 | 15470 | 15471 ~ 15475 | + +--- + +## 7. 다음 단계 (TODO) + +### 7.1 사전 준비 (비개발) + +1. [ ] 법인 명의 휴대폰으로 카카오톡 채널 개설 +2. [ ] 바로빌 관리자에서 카카오톡 서비스 신청 +3. [ ] 바로빌 채널 관리 URL에서 카카오 채널 연동 +4. [ ] 알림톡 템플릿 등록 및 카카오 검수 대기 + +### 7.2 개발 (채널 연동 후) + +1. [ ] 테스트 서버에서 `GetKakaotalkChannels` 호출 → 채널 목록 확인 +2. [ ] `GetKakaotalkTemplates` 호출 → 템플릿 목록 확인 +3. [ ] 알림톡 테스트 발송 → 응답/상태 확인 +4. [ ] 친구톡 테스트 발송 +5. [ ] 에러 응답 코드 정리 및 핸들링 보강 +6. [ ] SMS 대체발송 테스트 +7. [ ] 대량 발송 테스트 (수신자 다건) +8. [ ] 운영 서버 전환 (`testws` → `ws`) + +### 7.3 추후 고도화 + +- [ ] 발송 이력 DB 저장 (현재는 바로빌 API 조회만) +- [ ] 자동 발송 연동 (주문 확인, 배송 알림 등) +- [ ] 발송 통계 대시보드 +- [ ] 엑셀 업로드 대량 발송 +- [ ] 주소록(고객 DB) 연동 + +--- + +## 8. 참고 자료 + +- [바로빌 API 문서](https://dev.barobill.co.kr) +- [카카오비즈니스 채널 관리](https://business.kakao.com) +- [카카오 알림톡 가이드](https://kakaobusiness.gitbook.io) + +--- + +## 변경 이력 + +| 날짜 | 버전 | 변경 내용 | +|------|------|----------| +| 2026-02-14 | 0.1 | 초안 작성 - 코드 구현 완료, 실 서비스 연동 대기 |