sam-docs/features/rd/onboarding-guide.md

# 온보딩 도움말기능 (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 파일)

```javascript
// @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 도움말 버튼 패턴

```html
<!-- 페이지 헤더에 ? 버튼 추가 -->
<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 클래스를 사용.

```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 (선택 사용)

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

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

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

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

---

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

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

---

## 관련 문서

- [R&D 메뉴 전체 개요](README.md)
- [Driver.js 공식 문서](https://driverjs.com/)

---

**최종 업데이트**: 2026-03-22