mublo 기능 확장 가이드

확장은 무블로 기본 기능에 새 기능을 얹는 부품입니다. 게시판, 문의(Q&A), 매뉴얼처럼 필요한 것만 골라 켜고, 쓰지 않는 것은 꺼둘 수 있습니다. 확장은 관리자 화면의 확장 기능 메뉴(/admin/extensions)에서 한곳에 모아 관리합니다.

플러그인과 패키지

확장은 두 종류로 나뉩니다. 화면에서도 왼쪽은 플러그인, 오른쪽은 패키지로 나뉘어 보입니다.

• 플러그인 — 하나의 기능을 담은 가벼운 부품입니다. 예: 매뉴얼 플러그인.
• 패키지 — 여러 기능이 함께 묶인 큰 단위입니다. 패키지 안에는 부가 기능(패키지에 딸린 플러그인)이 들어 있을 수 있어, 패키지 카드에서 함께 켜고 끕니다.

부가 기능은 부모 패키지가 꺼져 있으면 함께 잠깁니다. 부가 기능을 쓰려면 먼저 그 패키지를 켜야 합니다.

켜고 끄기

쓰고 싶은 확장의 체크박스를 선택한 뒤, 오른쪽 위 저장 버튼을 누르면 적용됩니다. 체크를 해제하고 저장하면 꺼집니다. 저장할 때 확장 설치·정리 작업이 자동으로 처리됩니다.

• 필수 배지가 붙은 확장은 끌 수 없어 체크박스가 잠겨 있습니다.
• 다른 확장을 요구하는데 조건이 맞지 않으면 활성화가 거부되고 안내 문구가 표시됩니다.

확장이 더해 주는 것

확장을 켜면 사이트에 다음이 생깁니다.

• 관리자 메뉴 — 확장이 제공하는 관리 항목이 메뉴에 추가됩니다. 확장 기능 화면에서 카드를 드래그해 메뉴 노출 순서를 바꿀 수 있습니다.
• 관리 화면 — 해당 기능을 설정하고 운영하는 전용 화면이 열립니다.
• 블록 타입 — 페이지 편집기에서 쓸 수 있는 새 블록이 추가되기도 합니다.

확장은 서버에서 코드를 실행합니다. 직접 올리는 확장 파일은 출처가 분명한 것만 설치하세요.

확장(플러그인·킷 등)은 사이트에 새 기능을 더해 주지만, 아무 파일이나 올려서 설치하면 안 됩니다. mublo 는 설치할 때 그 확장이 어디서 왔고, 도중에 내용이 바뀌지 않았는지를 스스로 점검합니다. 운영자는 이 점검 결과만 확인하면 됩니다.

설치할 때 무엇을 점검하나요

확장 묶음(ZIP)을 설치하면 mublo 는 다음을 확인합니다.

• 내용 지문(checksum) — 확장 안의 모든 파일을 하나로 계산해 지문을 만듭니다. 파일이 하나라도 변조되면 지문이 달라져 걸러집니다.
• 서명(signature) — 확장 제작자(publisher)가 자기 열쇠로 남긴 서명이 있는지, 그 서명이 등록된 제작자의 공개키와 맞는지 확인합니다.
• 출처(source) — 어디서 받아 설치하는지를 함께 대조합니다. 제작자가 허용한 경로가 아니면 거부됩니다.

검증 결과 세 가지

'미검증'의 의미

서명 없음 상태는 곧바로 나쁜 확장이라는 뜻은 아니지만, mublo 가 출처와 무결성을 보증해 줄 수 없다는 뜻입니다. 신뢰할 수 있는 제작자가 준 것인지 스스로 판단해서 설치해야 합니다.

보안을 더 엄격히 하려면 서명된 확장만 설치 허용으로 서버를 설정할 수 있습니다. 이 경우 서명 없는 확장은 아예 설치되지 않아, 실수로 출처 불명 확장을 올리는 사고를 막아 줍니다.

정리

• 가능하면 검증됨(verified) 상태의 확장만 설치하세요.
• 서명 없는 확장은 제작자를 확실히 아는 경우에만, 필요성을 따져 설치하세요.
• 설치가 거부되면 억지로 우회하지 말고, 받은 파일이 손상·변조되지 않았는지부터 확인하세요.

mublo는 핵심 기능을 패키지와 플러그인으로 나눠 제공합니다. 필요한 것만 켜서 쓰고, 안 쓰는 기능은 꺼 두면 됩니다. 이 장에서는 자주 쓰는 대표 기능들을 하나씩 짚어 봅니다.

패키지 — 큰 단위 기능

여러 화면과 관리 기능이 묶인 규모 있는 기능입니다.

• 게시판(Board) — 공지·자유·자료실 등 여러 게시판을 만들고 운영합니다.
• 쇼핑몰(Shop) — 상품·장바구니·주문·결제·쿠폰·배송을 다루는 온라인 판매 기능입니다.

플러그인 — 필요한 기능만 골라 추가

단일 기능을 가볍게 더하는 확장입니다. 성격별로 나누면 다음과 같습니다.

모든 확장은 관리자 화면에서 켜고 끌 수 있습니다. 사이트에 꼭 필요한 기능부터 하나씩 켜 보고, 익숙해지면 늘려 나가는 방식을 권합니다.

다음 페이지부터는 각 기능을 실제로 켜고, 설정하고, 운영하는 방법을 차례로 안내합니다.

게시판(Board)은 공지, 자유게시판, 문의 등 글과 댓글이 오가는 공간을 만드는 확장입니다. 관리자에서 여러 개의 게시판을 만들고, 게시판마다 권한과 기능을 따로 정할 수 있습니다.

게시판 만들기

관리자의 게시판 관리 화면에서 새 게시판을 추가합니다. 만들 때 다음 두 가지가 필요합니다.

• 게시판 그룹: 게시판은 반드시 그룹에 속합니다. 그룹이 없으면 먼저 게시판 그룹 메뉴에서 그룹을 하나 만들어 주세요.
• 슬러그(주소): 게시판 주소에 쓰이는 이름입니다. 영문 소문자·숫자·하이픈(-)만, 2~50자로 입력합니다. 예: notice, free.

게시판명은 화면에 보이는 이름이고, 슬러그는 주소에 들어가는 영문 이름입니다. 둘은 다릅니다.

권한 정하기

권한은 회원 레벨(숫자)로 정합니다. 회원의 레벨이 설정한 값 이상이면 허용됩니다.

이 밖에 비회원 작성 허용, 비밀글 사용, 특정 회원을 게시판 관리자로 지정하는 설정, 레벨별 하루 작성 개수 제한도 둘 수 있습니다.

스킨과 기능

게시판마다 스킨(예: 기본형, 갤러리형)을 골라 목록·보기 화면의 모양을 바꿀 수 있습니다. 카테고리, 댓글, 리액션(좋아요 등), 파일 첨부 같은 기능도 게시판별로 켜고 끕니다.

글쓰기 흐름

운영자와 회원은 프론트 게시판에서 글쓰기 버튼을 눌러 에디터로 제목·내용을 작성하고 저장합니다. 켜 둔 기능에 따라 카테고리 선택, 파일 첨부, 비밀글 지정을 함께 할 수 있습니다.

이미 글이 등록된 게시판은 비밀 게시판(모든 글이 비밀글로 작성되는 1:1 문의형 게시판)으로 바꿀 수 없고, 글이 남아 있는 게시판은 삭제할 수 없습니다. 먼저 글을 정리해 주세요.

Shop은 mublo에서 상품 판매에 필요한 기능을 한데 묶은 공개 패키지입니다. 상품 등록부터 장바구니, 주문, 결제, 배송, 구매후기까지 쇼핑몰 운영에 필요한 흐름을 관리자 화면에서 다룰 수 있습니다.

Shop은 패키지이므로 관리자 > 패키지 관리에서 활성화해야 사용할 수 있습니다. 활성화하면 필요한 데이터베이스 준비와 관리자 메뉴 등록이 자동으로 이뤄집니다.

관리자 메뉴 구성

활성화 후 관리자 메뉴에 Mublo Shop 그룹이 생깁니다. 운영에 자주 쓰는 항목은 다음과 같습니다.

• 대시보드 — 쇼핑몰 현황을 한눈에 확인
• 쇼핑몰 설정 — 결제·기본 옵션 설정
• 카테고리 관리 / 상품 관리 — 분류를 만들고 상품을 등록
• 주문 관리 / 주문상태 설정 — 들어온 주문 처리와 상태 흐름 정의
• 배송 템플릿 · 쿠폰 관리 · 구매후기 · 상품문의 등 부가 기능

상품

상품 관리에서 상품을 등록하고, 여러 장의 이미지와 옵션(단일/조합/추가 선택)을 붙일 수 있습니다. 상품은 카테고리로 분류하며, 반복되는 상세 안내는 상품정보 템플릿으로 재사용합니다. 등록한 상품은 페이지 빌더의 상품 블록으로 원하는 페이지에 배치할 수 있습니다.

주문과 결제

고객은 장바구니에 담아 주문하며, 회원뿐 아니라 비회원 주문도 지원합니다. 주문 상태는 고정된 것이 아니라 주문상태 설정에서 흐름을 직접 정의하고, 상태가 바뀔 때 알림·포인트·재고 처리 같은 동작을 연결할 수 있습니다.

결제 수단은 다음을 제공합니다.

실제 카드·간편결제 승인은 Shop이 직접 처리하지 않고 결제 플러그인과 연결해 동작합니다. 쇼핑몰 설정 > 결제에서 사용할 결제 플러그인을 선택하세요. 결제 연동 없이도 무통장입금 방식으로 운영을 시작할 수 있습니다.

FAQ 플러그인은 자주 묻는 질문을 카테고리별로 정리해 방문자에게 보여 주는 기능입니다. 배송, 결제, 회원 같은 주제로 질문을 묶어 두면 문의를 크게 줄일 수 있습니다.

설치하기

관리자 메뉴에서 FAQ 관리로 들어갑니다. 처음 사용할 때는 데이터베이스 준비가 필요하다는 안내 화면이 뜨는데, 지금 설치하기 버튼을 누르면 자동으로 준비가 끝나고 관리 화면으로 넘어갑니다. 한 번만 하면 됩니다.

카테고리 만들기

관리 화면 왼쪽이 카테고리 영역입니다. 추가 버튼을 눌러 카테고리명(예: 배송)을 적고 저장합니다.

• 정렬 순서: 숫자가 작을수록 위에 표시됩니다.
• 활성: 꺼 두면 화면에 노출되지 않습니다.

카테고리를 삭제하면 그 안에 들어 있던 FAQ 질문도 함께 사라집니다. 삭제 전에 한 번 더 확인하세요.

질문과 답변 등록

왼쪽에서 카테고리를 고르면 오른쪽에 그 카테고리의 질문 목록이 나옵니다. FAQ 추가 버튼을 눌러 질문을 적고, 답변은 편집기에 입력합니다. 답변에는 글자 꾸미기와 이미지를 넣을 수 있습니다.

• 목록의 연필 아이콘으로 수정, 휴지통 아이콘으로 삭제합니다.
• 왼쪽 손잡이 모양을 드래그하면 질문 순서가 바로 저장됩니다.
• 사용/미사용으로 특정 질문만 잠시 숨길 수 있습니다.

화면에서 보이는 모습

등록한 내용은 사이트의 /faq 주소에서 전체 목록으로 확인할 수 있고, 관리 화면 오른쪽 위 FAQ 보기 버튼으로도 바로 열어 볼 수 있습니다. 위쪽의 FAQ 스킨 선택에서 보여지는 디자인을 고른 뒤 저장하면 프론트 화면에 적용됩니다.

지금 보고 계신 이 사용설명서도 매뉴얼 플러그인으로 만들었습니다. 책(사용설명서) 아래에 페이지를 트리(목차) 구조로 쌓아 올려, 운영자가 직접 안내 문서를 작성하고 사이트 방문자에게 보여줄 수 있습니다.

준비 — 설치하기

플러그인 관리에서 매뉴얼을 활성화한 뒤 관리자 메뉴의 매뉴얼 관리로 들어갑니다. 처음이라면 안내에 따라 설치 버튼을 한 번 눌러 주세요. 매뉴얼을 담을 표(책·페이지)가 자동으로 만들어집니다.

1단계 — 책 만들기

책은 하나의 사용설명서 묶음입니다(예: 운영자편, 개발자편). 매뉴얼 관리 화면에서 새 책을 추가하고 아래 항목을 채웁니다.

• 제목 — 목록과 화면 상단에 표시됩니다(필수).
• 슬러그 — 주소에 쓰이는 영문 이름입니다. 비워 두면 자동으로 만들어집니다.
• 설명 — 목록에 보이는 짧은 안내(선택).
• 노출 여부·정렬 순서 — 공개할지, 목록에서 몇 번째로 보일지.

2단계 — 페이지(목차) 쓰기

책을 열면 왼쪽이 목차, 페이지가 실제 내용입니다. 페이지를 추가할 때는 다른 페이지 아래(하위)로 넣어 단계를 나눌 수 있고, 깊이 제한은 없습니다. 본문은 이 문서처럼 MubloEditor로 글·그림·표를 넣어 작성합니다.

목차 순서나 상하 관계는 트리에서 끌어다 놓기(드래그)로 바꾼 뒤 저장하면 그대로 반영됩니다.

방문자가 보는 화면

완성된 매뉴얼은 사이트에서 /manual 주소로 목록이 열리고, 책을 고르면 왼쪽 목차와 본문이 함께 나옵니다. 특정 페이지 주소를 그대로 공유해 원하는 항목으로 바로 연결할 수도 있습니다.

책을 지우면 그 안의 페이지가 함께 사라지고, 페이지를 지우면 그 아래 하위 페이지도 함께 지워집니다. 삭제 전에 목차를 한 번 더 확인하세요.

mublo 의 알림은 성격이 다른 세 갈래로 나뉩니다. 사이트 안에서 보이는 내부 알림(종 아이콘), 문자·이메일 같은 외부 발송, 그리고 앱·브라우저로 밀어주는 푸시 알림 입니다. 각각 담당하는 계약(인터페이스)이 분리되어 있어, 확장 기능을 만들 때 목적에 맞는 것만 골라 쓰면 됩니다.

내부 알림 — 종 아이콘

회원이 로그인했을 때 화면 위쪽 종 아이콘에 쌓이는 알림입니다. 댓글, 쪽지처럼 사이트 안에 기록이 남아야 하는 개인 알림이 여기에 해당합니다. 확장에서는 MemberNotificationPublisherInterface 의 publish() 하나만 호출하면 저장·읽음 관리·목록 표시가 알아서 처리됩니다.

알림 한 건은 MemberNotification 값으로 만듭니다. 제목·내용은 일반 문자열이며, 클릭 시 이동 주소(targetUrl)는 사이트 내부 상대 경로만 허용됩니다(예: /board/notice/12). 외부 주소로는 보낼 수 없어 안전합니다.

deduplicationKey 를 지정하면 같은 회원에게 같은 알림이 중복 저장되지 않고 기존 알림 ID 가 돌아옵니다. 같은 사건이 여러 번 발생해도 종에 하나만 뜨게 하려면 활용하세요.

외부 발송 — 문자·이메일·알림톡

사이트 밖으로 나가는 메시지는 NotificationGatewayInterface 가 담당합니다. send() 에 채널(sms·email·alimtalk 등), 템플릿 코드, 수신자, 치환 변수를 넘기면 됩니다. 지원 채널과 등록된 템플릿 목록은 getSupportedChannels()·getChannelTree() 로 조회합니다. 실제 발송 연동은 발송 기능을 제공하는 확장(패키지)이 이 계약을 구현하는 방식으로 붙습니다.

푸시 — 모바일·브라우저 알림

앱이나 브라우저로 밀어주는 알림은 전용 푸시 계약(인터페이스)을 사용합니다. 수신 지점 하나를 기기(Installation)라 부르며, 웹 브라우저·안드로이드 앱·iOS 앱이 각각 하나의 기기가 됩니다.

• dispatchToMember() — 특정 회원의 활성 기기 전체(또는 지정 타입)에 전송
• dispatchToInstallation() — 특정 기기 한 대에 전송
• dispatchToTopic() — 도메인 구독자 전체에 브로드캐스트

댓글·쪽지처럼 알림함에도 남아야 하는 개인 알림이라면, 먼저 publish() 로 종 아이콘에 발행한 뒤 필요할 때 푸시로 함께 전달하는 순서를 권장합니다. 푸시만 보내면 화면 종에는 남지 않습니다.

포인트(잔액)는 회원이 활동으로 모으거나 결제·혜택에 사용하는 사이버 머니입니다. 글쓰기 적립, 관리자 수동 지급, 상품 결제 차감처럼 늘어나고 줄어드는 모든 변화를 mublo 는 한 곳에서 관리합니다.

원장(장부) 개념을 쉽게

mublo 는 회원의 포인트를 다룰 때 가계부와 같은 방식을 씁니다. 지급이든 차감이든 모든 변화를 한 줄씩 기록으로 남기고, 그 기록은 절대 지우거나 고치지 않습니다. 이렇게 쌓인 기록 전체를 원장이라고 부릅니다.

• 원장(이력) = 진짜 정답. 지급·차감 한 건마다 남는 지워지지 않는 기록입니다.
• 현재 잔액 = 원장을 모두 더한 값을 빠르게 보여주기 위한 요약본입니다.

각 기록에는 얼마가 바뀌었는지(금액), 바뀌기 전 잔액과 바뀐 후 잔액, 사유와 회원에게 보여줄 안내 문구가 함께 저장됩니다. 그래서 언제 왜 포인트가 늘고 줄었는지 나중에도 정확히 확인할 수 있습니다.

지급과 차감

포인트를 더하고 빼는 일은 모두 하나의 입구를 거칩니다. 잘못 두 번 눌러도 중복으로 처리되지 않도록 안전장치가 들어 있고, 처리 도중 문제가 생기면 변화 전체가 없던 일로 되돌아갑니다. 그래서 "기록은 남았는데 잔액은 안 바뀌는" 어긋남이 생기지 않습니다.

• 지급: 플러스(+) 금액. 활동 적립, 이벤트 보상, 관리자 수동 지급 등.
• 차감: 마이너스(-) 금액. 결제, 회수 등.

기본 정책은 잔액이 0 밑으로 내려가는 차감을 막습니다. 보유 포인트보다 많이 빼려 하면 "잔액이 부족합니다"로 실패하고, 회원 포인트는 그대로 유지됩니다.

이력 확인과 무결성

회원 상세 화면에서 그 회원의 최근 포인트 내역을 볼 수 있고, 전체 포인트 로그는 회원·출처·기간으로 걸러서 확인할 수 있습니다. 만약 요약된 현재 잔액과 원장 합계가 어긋나면, 시스템은 원장을 정답으로 삼아 잔액을 바로잡습니다. 이때도 이력은 손대지 않고, 복구 사실만 별도로 기록해 둡니다.

포인트 이력은 지워지지 않는 장부입니다. 잘못 지급했더라도 기록을 삭제하지 마세요. 반대 방향으로 한 번 더 조정(회수)하면 이력이 이유까지 남아 훨씬 안전합니다.

AI 도우미는 블록 에디터에서 HTML 타입 칸의 내용을 AI로 만들거나 고쳐주는 기능입니다. 코드를 몰라도 원하는 화면을 말로 설명하면 초안을 받아볼 수 있습니다. 이 기능은 도메인(사이트) 단위로 설정하고 사용량도 사이트별로 따로 집계됩니다.

공급자와 모델 설정

관리자의 AI 설정 화면에서 사용할 공급자를 고르고, 그 공급자의 API 키를 입력합니다. 공급자와 선택 가능한 모델은 설치 시 만들어진 config/ai.php의 허용 목록에서만 고를 수 있습니다. 공급자를 바꾸면 바뀐 공급자의 키를 새로 입력해야 합니다.

지원 모델 목록의 기준은 매뉴얼이 아니라 항상 config/ai.php 파일입니다. 이 파일은 설치 후 운영자가 관리하며, Core 업데이트가 덮어쓰지 않습니다.

API 키 관리

입력한 API 키는 암호화되어 저장되고, 관리자 화면을 포함한 어떤 응답에도 원문이 다시 나오지 않습니다(설정 여부만 표시). 키를 확장 기능이 훔쳐볼 수도 없습니다 — AI 호출은 코어가 대신 수행하고 결과만 돌려줍니다.

일일 한도

사이트마다 하루 요청 횟수 한도가 있습니다. 기본값은 50회이며, 관리자가 상향할 수 있는 최대치는 1000회입니다. 한도는 사이트 단위로 매일 집계됩니다.

사용 시 알아둘 점

• AI가 만든 결과는 코어가 자동으로 안전하게 정리(새니타이즈)하므로, 위험한 스크립트나 외부 요청은 걸러집니다.
• 생성 결과에는 반응형 품질 검사가 함께 나오지만 게시를 막지는 않습니다. 경고를 확인하고 진행할지는 운영자가 결정합니다.
• 결과가 마음에 들지 않으면 수정 요청으로 다시 다듬을 수 있으며, 이때도 한도가 차감됩니다.