From 74eb10b2d08b8f3c1e2981fd765d3c6a45581022 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 21:19:51 +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=EA=B0=B1=EC=8B=A0=20(=EC=95=8C=EB=A0=A4=EC=A7=84?= =?UTF-8?q?=20=EC=A0=9C=EC=95=BD,=20=EC=9D=B4=EA=B4=80=20=EB=B0=A9?= =?UTF-8?q?=ED=96=A5,=20=EC=8A=A4=ED=81=AC=EB=A6=BD=ED=8A=B8=20=EC=A3=BC?= =?UTF-8?q?=EC=9D=98=EC=82=AC=ED=95=AD)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- features/rd/onboarding-guide.md | 171 ++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 65 deletions(-) diff --git a/features/rd/onboarding-guide.md b/features/rd/onboarding-guide.md index 6def630..203a04d 100644 --- a/features/rd/onboarding-guide.md +++ b/features/rd/onboarding-guide.md @@ -1,7 +1,7 @@ # 온보딩 도움말기능 (Driver.js 기반) > **작성일**: 2026-03-22 -> **상태**: 운영 중 +> **상태**: 운영 중 (알려진 제약 있음) > **프로젝트**: SAM MNG (관리자 웹) > **라우트**: `/rd/onboarding-guide` @@ -19,10 +19,52 @@ SAM MNG의 각 화면에 처음 진입하는 사용자에게 주요 기능을 ** - `SamOnboarding` JS 래퍼 클래스로 프로젝트 전역에서 일관된 사용 - `localStorage`로 완료 상태 저장 (첫 방문 시에만 자동 시작) - 각 페이지 Blade 파일에서 간단한 코드 추가로 적용 가능 +- Driver.js CSS는 **동적 로드** (가이드 `start()` 시점에만 로드, 전역 레이아웃 충돌 방지) --- -## 2. 기술 스택 +## 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에서 `