From 9ae91418e0706fe1cdd57b2c5f2325c0368a9dd7 Mon Sep 17 00:00:00 2001
From: skytek_xinliang <carl@skytek.com.tw>
Date: Tue, 19 May 2026 11:35:01 +0800
Subject: [PATCH] feat(shell): add app shell and maintenance page driver

Introduce reusable shell components for layout, tabs, and global overlays.
Add maintenance page model, wrapper component, and composable driver to
standardize maintenance page state, search, and pagination handling.feat(shell): add app shell and maintenance page driver

Introduce reusable shell components for layout, tabs, and global overlays.
Add maintenance page model, wrapper component, and composable driver to
standardize maintenance page state, search, and pagination handling.
---
 src/components/pages/PageMaintenance.vue      |  34 +++
 .../page-drivers/useMaintenancePage.ts        |  46 ++++
 src/models/page.ts                            |  12 ++
 src/models/student.ts                         |  13 ++
 src/shell/AppShell.vue                        |  35 +++
 src/shell/AppTabs.vue                         | 114 ++++++++++
 src/shell/GlobalOverlays.vue                  | 199 ++++++++++++++++++
 src/stores/menu.ts                            |   1 +
 src/stores/students.ts                        |  15 +-
 9 files changed, 456 insertions(+), 13 deletions(-)
 create mode 100644 src/components/pages/PageMaintenance.vue
 create mode 100644 src/composables/page-drivers/useMaintenancePage.ts
 create mode 100644 src/models/page.ts
 create mode 100644 src/models/student.ts
 create mode 100644 src/shell/AppShell.vue
 create mode 100644 src/shell/AppTabs.vue
 create mode 100644 src/shell/GlobalOverlays.vue

diff --git a/src/components/pages/PageMaintenance.vue b/src/components/pages/PageMaintenance.vue
new file mode 100644
index 0000000..83c2072
--- /dev/null
+++ b/src/components/pages/PageMaintenance.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+import PageMaint from '@/components/PageMaint.vue'
+import type { MaintenancePageModel } from '@/models/page'
+
+defineProps<{
+  page: MaintenancePageModel
+}>()
+
+const emit = defineEmits<{
+  (e: 'create'): void
+  (e: 'edit', record: unknown): void
+  (e: 'view', record: unknown): void
+  (e: 'delete', record: unknown): void
+  (e: 'search', criteria: Record<string, unknown>): void
+}>()
+
+const searchPanelOpen = defineModel<boolean>('searchPanelOpen', { default: false })
+</script>
+
+<template>
+  <PageMaint
+    :title="page.title"
+    :search-panel-open="searchPanelOpen"
+    @toggle-search="searchPanelOpen = !searchPanelOpen"
+    @create="emit('create')"
+  >
+    <template #search-fields>
+      <slot name="search-fields" />
+    </template>
+    <template #table>
+      <slot name="table" />
+    </template>
+  </PageMaint>
+</template>
diff --git a/src/composables/page-drivers/useMaintenancePage.ts b/src/composables/page-drivers/useMaintenancePage.ts
new file mode 100644
index 0000000..23a920f
--- /dev/null
+++ b/src/composables/page-drivers/useMaintenancePage.ts
@@ -0,0 +1,46 @@
+import { computed, ref } from 'vue'
+import type { MaintenancePageModel } from '@/models/page'
+
+export interface UseMaintenancePageOptions {
+  title: string
+  records: unknown[]
+  itemsPerPage?: number
+}
+
+export function useMaintenancePage(options: UseMaintenancePageOptions) {
+  const search = ref<Record<string, unknown>>({})
+  const searchPanelOpen = ref(false)
+  const currentPage = ref(1)
+  const itemsPerPage = options.itemsPerPage ?? 10
+
+  const pageCount = computed(() =>
+    Math.max(1, Math.ceil(options.records.length / itemsPerPage))
+  )
+
+  const pageModel = computed<MaintenancePageModel>(() => ({
+    type: 'maintenance',
+    title: options.title,
+    records: options.records,
+    loading: false,
+    error: null,
+  }))
+
+  function load() {
+    // 由呼叫方在 load 中觸發資料載入；未來可擴充為非同步
+  }
+
+  function resetSearch() {
+    search.value = {}
+  }
+
+  return {
+    pageModel,
+    search,
+    searchPanelOpen,
+    currentPage,
+    itemsPerPage,
+    pageCount,
+    load,
+    resetSearch,
+  }
+}
diff --git a/src/models/page.ts b/src/models/page.ts
new file mode 100644
index 0000000..0a32be8
--- /dev/null
+++ b/src/models/page.ts
@@ -0,0 +1,12 @@
+export interface BasePageModel {
+  title: string
+  loading?: boolean
+  error?: string | null
+}
+
+export interface MaintenancePageModel extends BasePageModel {
+  type: 'maintenance'
+  records: unknown[]
+}
+
+export type PageModel = MaintenancePageModel
diff --git a/src/models/student.ts b/src/models/student.ts
new file mode 100644
index 0000000..2e32a29
--- /dev/null
+++ b/src/models/student.ts
@@ -0,0 +1,13 @@
+export interface StudentRecord {
+  id: number
+  studentId: string
+  name: string
+  department: string
+  grade: number
+  enrollYear: number
+  credits: number
+  advisor: string
+  email: string
+  phone: string
+  status: string
+}
diff --git a/src/shell/AppShell.vue b/src/shell/AppShell.vue
new file mode 100644
index 0000000..376d7a0
--- /dev/null
+++ b/src/shell/AppShell.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+import MainLayout from '@/components/layouts/MainLayout.vue'
+import PlainLayout from '@/components/layouts/PlainLayout.vue'
+import AppTabs from './AppTabs.vue'
+import GlobalOverlays from './GlobalOverlays.vue'
+import type { LayoutMenuItem } from '@/stores/menu'
+
+defineProps<{
+  menuItems?: LayoutMenuItem[]
+}>()
+
+const route = useRoute()
+
+const layoutMap = {
+  default: MainLayout,
+  none: PlainLayout,
+}
+
+const activeLayout = computed(
+  () => layoutMap[route.meta.layout as 'default' | 'none'] || MainLayout
+)
+const showTabs = computed(() => route.meta.layout === 'default')
+</script>
+
+<template>
+  <component :is="activeLayout">
+    <AppTabs :menu-items="menuItems" :show-tabs="showTabs">
+      <slot />
+    </AppTabs>
+  </component>
+
+  <GlobalOverlays :menu-items="menuItems" @search-select="$emit('searchSelect', $event)" />
+</template>
diff --git a/src/shell/AppTabs.vue b/src/shell/AppTabs.vue
new file mode 100644
index 0000000..e958e66
--- /dev/null
+++ b/src/shell/AppTabs.vue
@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import { mdiClose } from '@mdi/js'
+import { ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import type { LayoutMenuItem } from '@/stores/menu'
+
+const props = defineProps<{
+  menuItems?: LayoutMenuItem[]
+  showTabs?: boolean
+}>()
+
+const emit = defineEmits<{
+  (e: 'close', path: string): void
+}>()
+
+const route = useRoute()
+const router = useRouter()
+
+const tabs = ref<Array<{ title: string; path: string }>>([])
+const activeTab = ref<string | null>(null)
+
+function findTitle(path: string, items?: LayoutMenuItem[]): string | null {
+  const searchIn = items || []
+  for (const item of searchIn) {
+    if (item.path === path) return item.title
+    if (item.subItems?.length) {
+      const found = findTitle(path, item.subItems)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+function resolveTitle(path: string): string {
+  const fromProps = findTitle(path, props.menuItems)
+  if (fromProps) return fromProps
+
+  if (path === '/') return '首頁'
+  return path
+}
+
+watch(
+  () => route.path,
+  (newPath) => {
+    if (!props.showTabs) return
+
+    const existingTab = tabs.value.find((t) => t.path === newPath)
+    if (!existingTab) {
+      const title = resolveTitle(newPath)
+      tabs.value.push({ title, path: newPath })
+    }
+    activeTab.value = newPath
+  },
+  { immediate: true }
+)
+
+function closeTab(path: string) {
+  if (tabs.value.length <= 1) return
+
+  const index = tabs.value.findIndex((t) => t.path === path)
+  if (index === -1) return
+
+  tabs.value.splice(index, 1)
+
+  if (route.path === path) {
+    const nextTab = tabs.value[index] || tabs.value[index - 1]
+    if (nextTab) {
+      router.push(nextTab.path)
+    } else {
+      router.push('/')
+    }
+  }
+
+  emit('close', path)
+}
+
+defineExpose({ tabs, activeTab, closeTab })
+</script>
+
+<template>
+  <div v-if="showTabs" class="d-flex flex-column h-100">
+    <v-tabs
+      v-model="activeTab"
+      bg-color="background"
+      color="primary"
+      density="compact"
+      show-arrows
+      style="flex-shrink: 0"
+    >
+      <v-tab v-for="tab in tabs" :key="tab.path" border="sm" :to="tab.path" :value="tab.path">
+        {{ tab.title }}
+        <v-btn
+          aria-label="關閉頁籤"
+          class="pl-2"
+          color="grey"
+          density="compact"
+          :disabled="tabs.length <= 1"
+          icon
+          size="x-small"
+          variant="text"
+          @click.prevent.stop="closeTab(tab.path)"
+        >
+          <v-icon :icon="mdiClose" />
+        </v-btn>
+      </v-tab>
+    </v-tabs>
+
+    <div class="flex-grow-1 overflow-auto" style="min-height: 0" tabindex="0">
+      <slot />
+    </div>
+  </div>
+
+  <slot v-else />
+</template>
diff --git a/src/shell/GlobalOverlays.vue b/src/shell/GlobalOverlays.vue
new file mode 100644
index 0000000..d8a7e65
--- /dev/null
+++ b/src/shell/GlobalOverlays.vue
@@ -0,0 +1,199 @@
+<script setup lang="ts">
+import {
+  mdiBellOutline,
+  mdiCalendarOutline,
+  mdiHomeCityOutline,
+  mdiSchoolOutline,
+} from '@mdi/js'
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+import { HTTP_TOAST_EVENT } from '@/services/http-toast'
+import { useMessageStore } from '@/stores/messages'
+import { useSnackbarStore } from '@/stores/snackbar'
+import type { LayoutMenuItem } from '@/stores/menu'
+
+const props = defineProps<{
+  menuItems?: LayoutMenuItem[]
+}>()
+
+const emit = defineEmits<{
+  (e: 'searchSelect', item: { title: string; path: string; icon?: string }): void
+}>()
+
+const snackbar = useSnackbarStore()
+const messageStore = useMessageStore()
+
+const searchDialog = ref(false)
+const searchKeyword = ref('')
+const searchResults = ref<
+  Array<{ title: string; path: string; icon?: string; parents: string[] }>
+>([])
+
+const messageItems = [
+  { id: 1, title: '系統維護提醒', meta: '今天 09:00 · 資訊中心', icon: mdiBellOutline },
+  { id: 2, title: '教務處公告', meta: '昨天 16:20 · 教務處', icon: mdiSchoolOutline },
+  { id: 3, title: '宿舍申請結果', meta: '昨天 13:05 · 學務處', icon: mdiHomeCityOutline },
+  { id: 4, title: '課表異動通知', meta: '2 天前 · 教務處', icon: mdiCalendarOutline },
+]
+
+function buildSearchResults(
+  items: LayoutMenuItem[] | undefined,
+  keyword: string,
+  parents: string[] = []
+): Array<{ title: string; path: string; icon?: string; parents: string[] }> {
+  const results: Array<{ title: string; path: string; icon?: string; parents: string[] }> = []
+  for (const item of items || []) {
+    const currentParents = item?.title ? [...parents, item.title] : parents
+    if (item?.subItems?.length) {
+      results.push(...buildSearchResults(item.subItems, keyword, currentParents))
+    }
+    if (item?.path && item?.title) {
+      const hit = item.title.toLowerCase().includes(keyword)
+      if (hit) {
+        results.push({
+          title: item.title,
+          path: item.path,
+          icon: item.icon,
+          parents,
+        })
+      }
+    }
+  }
+  return results
+}
+
+function handleSearch(value: unknown) {
+  const keyword = String(value ?? '').trim()
+  searchKeyword.value = keyword
+  if (!keyword) {
+    searchResults.value = []
+    searchDialog.value = false
+    return
+  }
+  const lowered = keyword.toLowerCase()
+  searchResults.value = buildSearchResults(props.menuItems, lowered)
+  searchDialog.value = true
+}
+
+function handleSearchSelect(item: { title: string; path: string; icon?: string }) {
+  searchDialog.value = false
+  emit('searchSelect', item)
+}
+
+function resolveMessageItem(wrapped: unknown) {
+  if (wrapped && typeof wrapped === 'object' && 'raw' in (wrapped as object)) {
+    return (wrapped as { raw: (typeof messageItems)[0] }).raw
+  }
+  return wrapped as (typeof messageItems)[0]
+}
+
+function handleHttpToast(event: Event) {
+  const detail = (event as CustomEvent)?.detail
+  const message = detail?.message
+  if (!message) return
+
+  const level = detail?.level
+  const color =
+    level === 'error' ? 'error' : level === 'warning' ? 'warning' : 'info'
+  snackbar.show({ message, color, timeout: 3000, location: 'top right', variant: 'flat' })
+}
+
+onMounted(() => {
+  window.addEventListener(HTTP_TOAST_EVENT, handleHttpToast)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener(HTTP_TOAST_EVENT, handleHttpToast)
+})
+
+defineExpose({ handleSearch })
+</script>
+
+<template>
+  <v-dialog v-model="searchDialog" max-width="640">
+    <v-card>
+      <v-card-title class="text-h6 bg-primary-variant pa-4">搜尋結果</v-card-title>
+      <v-card-subtitle v-if="searchKeyword" class="pt-4">
+        關鍵字：{{ searchKeyword }}
+      </v-card-subtitle>
+      <v-card-text class="pt-2">
+        <v-alert
+          v-if="searchResults.length === 0"
+          class="mt-2"
+          density="compact"
+          type="info"
+          variant="tonal"
+        >
+          查無結果
+        </v-alert>
+        <v-list v-else density="compact">
+          <v-list-item
+            v-for="item in searchResults"
+            :key="item.path"
+            class="mb-2"
+            @click="handleSearchSelect(item)"
+          >
+            <template #prepend>
+              <v-icon v-if="item.icon" size="18" :icon="item.icon" />
+            </template>
+            <v-list-item-title>{{ item.title }}</v-list-item-title>
+            <v-list-item-subtitle v-if="item.parents?.length">
+              {{ item.parents.join(' / ') }}
+            </v-list-item-subtitle>
+          </v-list-item>
+        </v-list>
+      </v-card-text>
+      <v-card-actions>
+        <v-spacer />
+        <v-btn color="primary" variant="text" @click="searchDialog = false">關閉</v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+
+  <v-dialog v-model="messageStore.isOpen" max-width="720">
+    <v-card>
+      <v-card-title class="text-h6 bg-primary-variant pa-4">訊息清單</v-card-title>
+      <v-card-subtitle class="text-body-2 pt-4 text-medium-emphasis">
+        僅示意資料，不含延伸功能
+      </v-card-subtitle>
+      <v-card-text class="pa-4">
+        <v-data-iterator item-key="id" :items="messageItems" :items-per-page="-1">
+          <template #default="{ items }">
+            <v-list density="compact">
+              <v-list-item
+                v-for="wrapped in items"
+                :key="resolveMessageItem(wrapped).id"
+                border="sm"
+                class="pa-2 mb-1"
+              >
+                <template #prepend>
+                  <v-avatar color="primary" size="28" variant="tonal">
+                    <v-icon size="16" :icon="resolveMessageItem(wrapped).icon" />
+                  </v-avatar>
+                </template>
+                <v-list-item-title class="text-body-2 font-weight-medium">
+                  {{ resolveMessageItem(wrapped).title }}
+                </v-list-item-title>
+                <v-list-item-subtitle class="text-caption text-medium-emphasis">
+                  {{ resolveMessageItem(wrapped).meta }}
+                </v-list-item-subtitle>
+              </v-list-item>
+            </v-list>
+          </template>
+        </v-data-iterator>
+      </v-card-text>
+      <v-card-actions class="justify-end">
+        <v-btn color="primary" variant="text" @click="messageStore.close()">關閉</v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+
+  <v-snackbar
+    v-model="snackbar.visible"
+    :color="snackbar.color"
+    :location="snackbar.location as any"
+    :timeout="snackbar.timeout"
+    :variant="snackbar.variant"
+  >
+    {{ snackbar.message }}
+  </v-snackbar>
+</template>
diff --git a/src/stores/menu.ts b/src/stores/menu.ts
index 4b01f08..14ed286 100644
--- a/src/stores/menu.ts
+++ b/src/stores/menu.ts
@@ -6,6 +6,7 @@ import { menuApi, type MenuNode } from '@/services/modules/menu'
 export interface LayoutMenuItem {
   title: string
   path?: string
+  icon?: string
   navigable?: boolean
   subItems?: LayoutMenuItem[]
 }
diff --git a/src/stores/students.ts b/src/stores/students.ts
index 8dcda7a..3d89d35 100644
--- a/src/stores/students.ts
+++ b/src/stores/students.ts
@@ -1,19 +1,8 @@
+import type { StudentRecord } from '@/models/student'
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 
-export interface StudentRecord {
-  id: number
-  studentId: string
-  name: string
-  department: string
-  grade: number
-  enrollYear: number
-  credits: number
-  advisor: string
-  email: string
-  phone: string
-  status: string
-}
+export type { StudentRecord } from '@/models/student'
 
 const seedStudents: StudentRecord[] = [
   {