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

2026-03-22 20:26:01 +09:00
parent f83fa1821c
commit 492de0ad93
3 changed files with 197 additions and 1 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -214,6 +214,7 @@ DB 도메인별:
 | [construction-pmis/bim-viewer.md](features/construction-pmis/bim-viewer.md) | BIM 뷰어 (Three.js 기반 웹 3D 건물 모델 뷰어) |
 | [rd/README.md](features/rd/README.md) | R&D 메뉴 전체 개요 |
 | [rd/fire-shutter-drawing-guide-rail.md](features/rd/fire-shutter-drawing-guide-rail.md) | 방화셔터 가이드레일 SVG/3D 렌더링 기술 명세 |
+| [rd/onboarding-guide.md](features/rd/onboarding-guide.md) | 온보딩 도움말기능 (Driver.js 기반 인터랙티브 투어) |
 | [notification-settings/README.md](features/notification-settings/README.md) | 서비스 알림설정 (5개 테이블, API 엔드포인트, 알림음 시스템, Gap 분석) |

 ---
--- a/features/rd/README.md
+++ b/features/rd/README.md
@@ -21,6 +21,7 @@ R&D 메뉴는 SAM 플랫폼의 **연구개발 및 내부 도구** 모음이다.
 | [planning-design.md](planning-design.md) | 기획디자인 스토리보드 에디터 기술 명세 |
 | [design-insight.md](design-insight.md) | 디자인 인사이트 UI/UX 연구 도구 (100종 패턴, AI 프롬프트) |
 | [fire-shutter-drawing-guide-rail.md](fire-shutter-drawing-guide-rail.md) | 방화셔터 도면 가이드레일 SVG/3D 렌더링 |
+| [onboarding-guide.md](onboarding-guide.md) | 온보딩 도움말기능 (Driver.js 기반 인터랙티브 투어) |

 ### 1.3 하위 메뉴 구조

@@ -37,7 +38,8 @@ R&D
 │   └── 문서              /rd/ai-quotation/{id}/document
 ├── 기획디자인             /rd/planning-design
 ├── 디자인 인사이트         /rd/design-insight
-└── 방화셔터 도면           /rd/fire-shutter-drawing
+├── 방화셔터 도면           /rd/fire-shutter-drawing
+└── 온보딩 도움말기능        /rd/onboarding-guide
 ```

 ---
@@ -75,6 +77,7 @@ R&D
 | `documentQuotation()` | `GET /rd/ai-quotation/{id}/document` | AI 견적 문서 |
 | `planningDesign()` | `GET /rd/planning-design` | 기획디자인 |
 | `designInsight()` | `GET /rd/design-insight` | 디자인 인사이트 |
+| `onboardingGuide()` | `GET /rd/onboarding-guide` | 온보딩 도움말기능 |

 ### 2.3 HTMX 전체 페이지 로드 규칙

@@ -99,6 +102,7 @@ if ($request->header('HX-Request')) {
 | **기획디자인** | **Blade + Alpine.js (SPA)** | **없음 (localStorage)** | **없음** | **운영 중** |
 | **디자인 인사이트** | **Blade + Alpine.js (SPA)** | **없음 (localStorage)** | **없음** | **운영 중** |
 | **방화셔터 도면** | **Blade + JS (SVG/Three.js)** | **RdController** | **없음** | **운영 중** |
+| **온보딩 도움말기능** | **Blade + Driver.js** | **RdController** | **localStorage** | **운영 중** |

 ---

@@ -108,6 +112,7 @@ if ($request->header('HX-Request')) {
 - [디자인 인사이트](design-insight.md) — UI/UX 연구 도구 (100종 패턴, AI 프롬프트 복사)
 - [방화셔터 도면 가이드레일](fire-shutter-drawing-guide-rail.md) — 가이드레일 SVG/3D 렌더링 기술 명세
 - [조직도 관리 기술문서](../../projects/org-chart/) — 조직도 시스템 상세 (별도 프로젝트 문서)
+- [온보딩 도움말기능](onboarding-guide.md) — Driver.js 기반 인터랙티브 투어 시스템

 ---

--- a/features/rd/onboarding-guide.md
+++ b/features/rd/onboarding-guide.md
@@ -0,0 +1,190 @@
+# 온보딩 도움말기능 (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