SamProject/sam-docs

Fork 0

Files

김보곤 492de0ad93 docs: [rd] 온보딩 도움말기능 문서 추가

2026-03-22 20:26:01 +09:00

5.3 KiB

Raw Blame History

온보딩 도움말기능 (Driver.js 기반)

작성일: 2026-03-22 상태: 운영 중 프로젝트: SAM MNG (관리자 웹) 라우트: /rd/onboarding-guide

1. 개요

1.1 목적

SAM MNG의 각 화면에 처음 진입하는 사용자에게 주요 기능을 단계별로 안내하는 인터랙티브 투어를 제공한다. 배경을 흐리게(Dimming) 처리하고 대상 요소를 하이라이트하며, 툴팁으로 사용 방법을 설명한다.

1.2 핵심 원칙

Driver.js 라이브러리 기반 (NPM, Vite 번들)
SamOnboarding JS 래퍼 클래스로 프로젝트 전역에서 일관된 사용
localStorage로 완료 상태 저장 (첫 방문 시에만 자동 시작)
각 페이지 Blade 파일에서 간단한 코드 추가로 적용 가능

2. 기술 스택

항목	내용
라이브러리	`driver.js` (NPM)
번들링	Vite (`resources/js/app.js`에서 import)
래퍼 모듈	`resources/js/onboarding-guide.js`
상태 저장	`localStorage` (`sam_onboarding_{pageKey}`)
전역 객체	`window.SamOnboarding`, `window.GuideRegistry`

3. 파일 구조

mng/
├── resources/
│   └── js/
│       ├── app.js                          ← Driver.js import, 전역 등록
│       └── onboarding-guide.js             ← SamOnboarding 클래스, GuideRegistry
├── app/Http/Controllers/
│   └── RdController.php                    ← onboardingGuide() 메서드
├── routes/
│   └── web.php                             ← /rd/onboarding-guide 라우트
└── resources/views/rd/
    ├── onboarding-guide/
    │   └── index.blade.php                 ← 관리 페이지 (데모 체험, 개발자 가이드)
    └── index.blade.php                     ← RD 대시보드 (시범 적용)

4. 사용법

4.1 기본 사용 (Blade 파일)

// @push('scripts') 안에 추가
const guide = new SamOnboarding('page-key', [
    {
        element: '#target-id',
        title: '제목',
        description: '설명 텍스트 (HTML 가능)',
        side: 'bottom',      // top, bottom, left, right (선택)
        align: 'start',      // start, center, end (선택)
    },
    {
        element: '.another-element',
        title: '두 번째 스텝',
        description: '다음 설명',
    },
]);

// 첫 방문 시에만 자동 시작
guide.startIfFirstVisit();

// 또는 버튼 클릭으로 시작
document.getElementById('help-btn').onclick = () => guide.start();

4.2 도움말 버튼 패턴

<!-- 페이지 헤더에 ? 버튼 추가 -->
<button onclick="guide.start()" class="bg-white hover:bg-gray-100 text-gray-500 px-3 py-2 rounded-lg border transition" title="도움말 보기">
    <i class="ri-question-line"></i>
</button>

4.3 SamOnboarding 클래스 API

메서드	설명
`start()`	가이드 즉시 시작
`startIfFirstVisit()`	첫 방문(미완료) 시에만 자동 시작 (500ms 딜레이)
`reset()`	완료 상태 초기화 (다시 보기)
`isCompleted()`	완료 여부 반환 (`boolean`)

4.4 스텝 옵션

속성	필수	설명
`element`	*	CSS 셀렉터 (`#id`, `.class`)
`title`	*	툴팁 제목
`description`	*	설명 텍스트 (HTML 지원)
`side`		툴팁 위치: `top`, `bottom`, `left`, `right`
`align`		정렬: `start`, `center`, `end`

5. 적용 현황

페이지	pageKey	스텝 수	자동 시작	도움말 버튼
RD 대시보드	`rd-dashboard`	4	첫 방문	`?` 버튼
온보딩 데모	`onboarding-demo`	6	수동	데모 버튼

6. 커스터마이징

6.1 SAM 테마 스타일

Driver.js 기본 스타일을 SAM UI에 맞게 커스텀한다. sam-onboarding-popover CSS 클래스를 사용.

.sam-onboarding-popover .driver-popover {
    border-radius: 12px;
    box-shadow: 0 20px 60px rgba(0,0,0,0.15);
}
.driver-popover-next-btn {
    background-color: #4f46e5;  /* indigo-600 */
    border-radius: 8px;
}

6.2 한국어 버튼 텍스트

SamOnboarding 기본 설정:

버튼	텍스트
다음	`다음`
이전	`이전`
완료	`완료`
진행률	`{{current}} / {{total}}`

7. GuideRegistry (선택 사용)

여러 페이지의 가이드를 중앙에서 관리할 때 사용한다.

// 가이드 등록
GuideRegistry.register('my-page', [
    { element: '#btn', title: '버튼', description: '설명' },
]);

// 등록된 가이드 인스턴스 생성 및 시작
const guide = GuideRegistry.create('my-page');
guide.start();

// 등록된 모든 가이드 키 조회
const keys = GuideRegistry.keys(); // ['my-page', ...]

8. 새 페이지에 가이드 추가하기

가이드 대상 요소에 id 부여 (예: id="btn-create", id="data-table")
Blade 파일의 @push('scripts') 안에 SamOnboarding 코드 추가
(선택) 페이지 헤더에 ? 도움말 버튼 추가
온보딩 관리 페이지(/rd/onboarding-guide)에서 적용 확인

5.3 KiB Raw Blame History