From 492de0ad9382cf166d13ae74a61b649106a9ff25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sun, 22 Mar 2026 20:26:01 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[rd]=20=EC=98=A8=EB=B3=B4=EB=94=A9=20?= =?UTF-8?q?=EB=8F=84=EC=9B=80=EB=A7=90=EA=B8=B0=EB=8A=A5=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- INDEX.md | 1 + features/rd/README.md | 7 +- features/rd/onboarding-guide.md | 190 ++++++++++++++++++++++++++++++++ 3 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 features/rd/onboarding-guide.md diff --git a/INDEX.md b/INDEX.md index c4aea73..d21445e 100644 --- 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 분석) | --- diff --git a/features/rd/README.md b/features/rd/README.md index a095c96..a096f94 100644 --- 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 기반 인터랙티브 투어 시스템 --- diff --git a/features/rd/onboarding-guide.md b/features/rd/onboarding-guide.md new file mode 100644 index 0000000..6def630 --- /dev/null +++ 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 + + +``` + +### 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