From 16343b62c7f624cf27ddaa9332aa115ce84ed284 Mon Sep 17 00:00:00 2001
From: zenn <zenn.message@gmail.com>
Date: Fri, 3 Jul 2026 18:27:32 +0900
Subject: [PATCH] =?UTF-8?q?HTML=20=EB=AC=B8=EC=84=9C=20=ED=8E=98=EC=9D=B4?=
 =?UTF-8?q?=EC=A7=80=20=EB=92=A4=EB=A1=9C=EA=B0=80=EA=B8=B0=20=EA=B7=BC?=
 =?UTF-8?q?=EB=B3=B8=20=EC=88=98=EC=A0=95=20=EB=B0=8F=20=ED=8E=98=EC=9D=B4?=
 =?UTF-8?q?=EC=A7=80=20=EC=9D=B4=EB=8F=99=20=EB=A1=9C=EB=94=A9=20=ED=94=BC?=
 =?UTF-8?q?=EB=93=9C=EB=B0=B1=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- /pages/:slug HTML 문서 페이지 클라이언트 소프트 이동을 전체 페이지 이동으로 전환하는 글로벌 미들웨어 추가
- app.vue에 브랜드 컬러 기반 NuxtLoadingIndicator 상단 진행바 추가로 이동 로딩 피드백 제공
- v1.10.33

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 app.vue                                  |  5 ++-
 docs/map.md                              |  3 +-
 docs/update.md                           |  6 ++++
 middleware/pages-html-document.global.js | 40 ++++++++++++++++++++++++
 package.json                             |  2 +-
 5 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 middleware/pages-html-document.global.js

diff --git a/app.vue b/app.vue
index b2425a6..b8ce315 100644
--- a/app.vue
+++ b/app.vue
@@ -12,8 +12,10 @@ const { data: appSiteSettings } = await useFetch('/api/site-settings', {
   })
 })
 
+const siteAccentColor = computed(() => normalizeBrandColor(appSiteSettings.value?.brandColor || DEFAULT_BRAND_COLOR))
+
 const siteAccentStyle = computed(() => ({
-  '--site-accent': normalizeBrandColor(appSiteSettings.value?.brandColor || DEFAULT_BRAND_COLOR)
+  '--site-accent': siteAccentColor.value
 }))
 
 useHead(() => ({
@@ -32,6 +34,7 @@ useHead(() => ({
 
 <template>
   <div class="site-app" :style="siteAccentStyle">
+    <NuxtLoadingIndicator :color="siteAccentColor" :height="3" :throttle="80" :duration="5000" />
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>
diff --git a/docs/map.md b/docs/map.md
index cc738a7..3ef4694 100644
--- a/docs/map.md
+++ b/docs/map.md
@@ -10,7 +10,7 @@
 | layouts/post.vue | 개별 게시물 — `default`와 동일, 오른쪽 컬럼 전체 높이 구분선 |
 | layouts/admin.vue | 관리자 전체, 320px 밝은 Ghost형 사이드바(대시보드 `/admin` 활성 링크·사이트 보기 새 창·콘텐츠 구간 여백), 우측 전체 높이 캔버스, 멤버 수 표시, 하단 사용자 드롭다운·설정, `내 프로필` 멤버 편집 이동, 게시글 `+` 새 글 진입, 글 작성/수정 화면의 전체 화면 편집 모드와 문서 스크롤 잠금, **`/admin/settings`에서는 사이드바 숨김·본문 전체 화면·설정용 문서 스크롤 잠금** |
 | layouts/page.vue | 고정 페이지 전체 화면 |
-| app.vue | 공개 사이트 설정 기반 파비콘 head 링크, 페이지 제목이 있으면 제목만 쓰고 없으면 사이트 이름을 쓰는 title template, 브랜드 컬러 `--site-accent` 적용 |
+| app.vue | 공개 사이트 설정 기반 파비콘 head 링크, 페이지 제목이 있으면 제목만 쓰고 없으면 사이트 이름을 쓰는 title template, 브랜드 컬러 `--site-accent` 적용, 페이지 이동 로딩 진행바(`NuxtLoadingIndicator`, 브랜드 컬러) |
 | error.vue | 공개 404/서버 오류 화면, 홈 이동 버튼 |
 
 ## Composables
@@ -416,6 +416,7 @@
 | composables/useMenuState.js | 좌측 메뉴 열림 상태·`closeMenu`(모바일 백드롭 등), 모바일은 마운트 시 항상 닫힘 시작·`menuMounted`로 첫 페인트 슬라이드 플래시 방지 |
 | composables/useThemeMode.js | 사용자 화면 라이트/다크 테마 상태 관리 |
 | middleware/admin-auth.global.js | 관리자 페이지 접근 인증 |
+| middleware/pages-html-document.global.js | HTML 문서 모드 고정 페이지(`/pages/:slug`) 클라이언트 소프트 이동을 전체 페이지 이동으로 전환(뒤로가기 잔상 방지) |
 | scripts/dev-server.js | 로컬 개발 서버 링크 요약 출력 |
 | scripts/migrate-database.js | 로컬·NAS DB 마이그레이션 적용/상태/baseline 실행 |
 | scripts/migrate-development-db.js | 기존 로컬 개발 DB 마이그레이션 명령 호환 래퍼 |
diff --git a/docs/update.md b/docs/update.md
index f780a29..832f039 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,11 @@
 # 업데이트 이력
 
+## v1.10.33
+
+- HTML 문서 모드 페이지 뒤로가기 시 홈으로 돌아가지 못하던 문제를 근본 수정.
+- `/pages/:slug` HTML 문서 페이지로의 클라이언트 소프트 이동을 막고 전체 페이지 이동으로 전환하는 글로벌 미들웨어 `pages-html-document.global.js` 추가.
+- 페이지 이동 로딩 피드백을 위해 `app.vue`에 브랜드 컬러 기반 `NuxtLoadingIndicator` 상단 진행바 추가(모바일에서 클릭·뒤로가기 반응 확인 가능).
+
 ## v1.10.32
 
 - HTML 문서 모드 페이지 진입 후 뒤로가기 시 주소는 홈이지만 페이지 화면이 남던 문제 수정.
diff --git a/middleware/pages-html-document.global.js b/middleware/pages-html-document.global.js
new file mode 100644
index 0000000..6defcb4
--- /dev/null
+++ b/middleware/pages-html-document.global.js
@@ -0,0 +1,40 @@
+/**
+ * HTML 문서 모드 고정 페이지(`/pages/:slug`)로의 클라이언트 소프트 이동을 막고 전체 페이지 이동으로 전환한다.
+ *
+ * SPA로 소프트 진입한 뒤 원문 HTML을 받으려고 새로고침하면, 직전 문서(예: 홈)가
+ * "라우터는 페이지 경로인데 URL은 홈"인 어긋난 상태로 뒤로가기 캐시에 남아 뒤로가기 시
+ * 홈으로 돌아가지 못하는 문제가 있다. 클라이언트 이동 단계에서 전체 페이지 이동으로 처리하면
+ * 직전 문서가 깨끗하게 유지되어 뒤로가기가 정상 동작한다.
+ *
+ * @param {import('#app').RouteLocationNormalized} to - 이동 대상 라우트
+ * @returns {Promise<ReturnType<typeof abortNavigation> | void>} 내비게이션 중단 여부
+ */
+export default defineNuxtRouteMiddleware(async (to) => {
+  if (import.meta.server) {
+    return
+  }
+
+  const nuxtApp = useNuxtApp()
+  if (nuxtApp.isHydrating) {
+    return
+  }
+
+  const match = to.path.match(/^\/pages\/([^/]+)\/?$/)
+  if (!match) {
+    return
+  }
+
+  const slug = decodeURIComponent(match[1])
+
+  let page = null
+  try {
+    page = await $fetch(`/api/pages/${slug}`)
+  } catch {
+    return
+  }
+
+  if (page?.renderMode === 'html_document') {
+    window.location.assign(to.fullPath)
+    return abortNavigation()
+  }
+})
diff --git a/package.json b/package.json
index aa2d593..f389750 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sori.studio",
-  "version": "1.10.32",
+  "version": "1.10.33",
   "private": true,
   "type": "module",
   "imports": {