# 온보딩 도움말기능 (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 파일에서 간단한 코드 추가로 적용 가능 - Driver.js CSS는 **동적 로드** (가이드 `start()` 시점에만 로드, 전역 레이아웃 충돌 방지) --- ## 2. 알려진 제약 및 주의사항 > **경고: MNG 환경에서 Driver.js + HTMX 조합의 구조적 제약이 있다.** ### 2.1 HTMX 레이아웃 충돌 | 접근 방식 | 레이아웃 | 가이드 동작 | |----------|:--------:|:----------:| | **URL 직접 입력 / F5 새로고침** | ✅ 정상 | ✅ 정상 | | **사이드바 메뉴 클릭 (HTMX 네비게이션)** | ❌ 깨짐 | - | ### 2.2 원인 MNG는 **HTMX 듀얼 로드** 환경이다: - CDN: `htmx.org@1.9.10` (레이아웃 ``에서 동기 로드) - NPM: `htmx.org@2.0.8` (Vite 번들에서 모듈 로드) 사이드바의 `hx-boost="true"` + `hx-swap="outerHTML"` + `HX-Redirect` 응답 조합에서 두 HTMX 인스턴스 간 처리 충돌이 발생하여, 페이지 전체 리로드 시 레이아웃이 깨진다. ### 2.3 현재 대응 - 컨트롤러에서 `HX-Redirect`로 전체 페이지 리로드를 강제한다 (다른 RD 페이지와 동일 패턴) - Driver.js CSS는 `start()` 호출 시에만 동적 `import()`로 로드한다 - SAM 커스텀 테마는 JS에서 `