From cad44db4c7f8a52a7b862860d75f5366a69c2026 Mon Sep 17 00:00:00 2001
From: skytek_xinliang <carl@skytek.com.tw>
Date: Fri, 22 May 2026 15:09:54 +0800
Subject: [PATCH] docs(pages): clarify page driver component boundaries

Add inline comments to page components documenting how page models,
v-model state, and emitted user intents flow through the page driver.

This clarifies that page components remain presentation-focused while
routing, dialog state, CRUD side effects, and command handling stay in
the page driver or related composables.docs(pages): clarify page driver component boundaries

Add inline comments to page components documenting how page models,
v-model state, and emitted user intents flow through the page driver.

This clarifies that page components remain presentation-focused while
routing, dialog state, CRUD side effects, and command handling stay in
the page driver or related composables.
---
 .../pages/PageEditableGridMaintenance.vue     |   1 +
 src/components/pages/PageFunction.vue         |   1 +
 src/components/pages/PageHome.vue             |   3 +
 src/components/pages/PageMaintenance.vue      |   3 +
 .../pages/PageMasterDetailAMaintenance.vue    |   5 +
 .../pages/PageMasterDetailBMaintenance.vue    |   3 +
 .../pages/PageMasterDetailCMaintenance.vue    |   3 +
 .../pages/PageSectionQueryPageDemo.vue        |  69 +++
 src/components/pages/PageSettings.vue         |   1 +
 src/components/sections/SectionQueryPage.vue  |   2 +-
 src/composables/layout/useAppShell.ts         |  17 +
 .../page-drivers/useSectionsDemoPage.ts       | 410 ++++++++++++++++++
 src/router/routes.ts                          |  22 +
 src/views/GUIDE.md                            |   1 +
 src/views/demos/SectionQueryPageDemo.vue      |  16 +
 15 files changed, 556 insertions(+), 1 deletion(-)
 create mode 100644 src/components/pages/PageSectionQueryPageDemo.vue
 create mode 100644 src/composables/page-drivers/useSectionsDemoPage.ts
 create mode 100644 src/views/demos/SectionQueryPageDemo.vue

diff --git a/src/components/pages/PageEditableGridMaintenance.vue b/src/components/pages/PageEditableGridMaintenance.vue
index 177cc43..56c84b6 100644
--- a/src/components/pages/PageEditableGridMaintenance.vue
+++ b/src/components/pages/PageEditableGridMaintenance.vue
@@ -8,5 +8,6 @@ defineProps<{
 </script>
 
 <template>
+  <!-- Page component 接收 page model，再把頁面標題轉交給既有 editable grid feature component。 -->
   <EditableStudentGrid :title="page.title" />
 </template>
diff --git a/src/components/pages/PageFunction.vue b/src/components/pages/PageFunction.vue
index 13c4691..d518c93 100644
--- a/src/components/pages/PageFunction.vue
+++ b/src/components/pages/PageFunction.vue
@@ -7,6 +7,7 @@ defineProps<{
 </script>
 
 <template>
+  <!-- Page component 只呈現 page driver 解析後的功能代碼，不直接讀 route params。 -->
   <v-sheet height="100%" width="100%">
     {{ page.fncId }}
   </v-sheet>
diff --git a/src/components/pages/PageHome.vue b/src/components/pages/PageHome.vue
index 5f3534f..f49eee5 100644
--- a/src/components/pages/PageHome.vue
+++ b/src/components/pages/PageHome.vue
@@ -7,16 +7,19 @@ defineProps<{
   selectedNews: HomeNewsItem | null
 }>()
 
+// 首頁互動都往上 emit，讓 page driver 統一處理 dialog、訊息中心與 snackbar。
 const emit = defineEmits<{
   news: [item: HomeNewsItem]
   'message-center': []
   quick: [item: HomeQuickItem]
 }>()
 
+// 新聞 dialog 開關是 PageIndex 的雙向 UI 狀態，由 view/page driver 持有。
 const isNewsDialogOpen = defineModel<boolean>('newsDialogOpen', { default: false })
 </script>
 
 <template>
+  <!-- PageHome 作為 page component，把 page model 拆給既有 PageIndex 外殼與事件。 -->
   <PageIndex
     v-model:is-news-dialog-open="isNewsDialogOpen"
     :news-items="page.newsItems"
diff --git a/src/components/pages/PageMaintenance.vue b/src/components/pages/PageMaintenance.vue
index 83c2072..4d65718 100644
--- a/src/components/pages/PageMaintenance.vue
+++ b/src/components/pages/PageMaintenance.vue
@@ -6,6 +6,7 @@ defineProps<{
   page: MaintenancePageModel
 }>()
 
+// PageMaintenance 只轉發維護頁使用者意圖，CRUD 副作用交給 page driver / command composable。
 const emit = defineEmits<{
   (e: 'create'): void
   (e: 'edit', record: unknown): void
@@ -14,10 +15,12 @@ const emit = defineEmits<{
   (e: 'search', criteria: Record<string, unknown>): void
 }>()
 
+// 搜尋面板開關是頁面 UI 狀態，用 v-model 交回 view/page driver。
 const searchPanelOpen = defineModel<boolean>('searchPanelOpen', { default: false })
 </script>
 
 <template>
+  <!-- PageMaint 提供維護頁外殼；搜尋欄位與表格內容由 slot 交給各頁組合。 -->
   <PageMaint
     :title="page.title"
     :search-panel-open="searchPanelOpen"
diff --git a/src/components/pages/PageMasterDetailAMaintenance.vue b/src/components/pages/PageMasterDetailAMaintenance.vue
index e3c7ca5..6ab3df3 100644
--- a/src/components/pages/PageMasterDetailAMaintenance.vue
+++ b/src/components/pages/PageMasterDetailAMaintenance.vue
@@ -73,6 +73,7 @@ defineProps<{
 
 const form = defineModel<StudentFormState>('form', { required: true })
 const detailFormModel = defineModel<SemesterRecord | null>('detailForm', { required: true })
+// 主檔表單、子檔表單與搜尋條件都由 page driver 持有，Page component 只透過 v-model 回寫。
 const search = defineModel<{
   studentId: string
   name: string
@@ -82,6 +83,7 @@ const search = defineModel<{
 }>('search', { required: true })
 const searchPanelOpen = defineModel<boolean>('searchPanelOpen', { required: true })
 
+// 主從維護頁的 CRUD 與導覽意圖都往上 emit，讓 page driver / command composable 統一處理。
 const emit = defineEmits<{
   (e: 'add-semester'): void
   (e: 'cancel-detail-edit'): void
@@ -122,11 +124,13 @@ const emit = defineEmits<{
 </script>
 
 <template>
+  <!-- PageMaintenance 提供維護頁外殼；主從頁在 slots 中組合搜尋、表格與子檔內容。 -->
   <PageMaintenance
     v-model:search-panel-open="searchPanelOpen"
     :page="page"
     @create="emit('create')"
   >
+    <!-- 搜尋欄位沿用 SectionSearchPanel，搜尋條件透過 v-model 回到 page driver。 -->
     <template #search-fields>
       <SectionSearchPanel
         v-model="search"
@@ -136,6 +140,7 @@ const emit = defineEmits<{
         @reset="emit('reset-search')"
       />
     </template>
+    <!-- 主檔表格沿用 SectionDataTable，列操作只 emit 使用者意圖。 -->
     <template #table>
       <SectionDataTable
         :current-page="currentPage"
diff --git a/src/components/pages/PageMasterDetailBMaintenance.vue b/src/components/pages/PageMasterDetailBMaintenance.vue
index 235618e..451957d 100644
--- a/src/components/pages/PageMasterDetailBMaintenance.vue
+++ b/src/components/pages/PageMasterDetailBMaintenance.vue
@@ -1,10 +1,12 @@
 <template>
+  <!-- Page component 組合 PageMaint 外殼、主檔表格、子檔區與 dialog；流程狀態集中在本頁 script。 -->
   <page-maint
     :search-panel-open="searchPanelOpen"
     :title="page.title"
     @create="openAddDialog"
     @toggle-search="searchPanelOpen = !searchPanelOpen"
   >
+    <!-- 搜尋欄位放在 PageMaint 的 search-fields slot，讓外殼固定、欄位由頁面決定。 -->
     <template #search-fields>
       <v-col cols="12" md="2">
         <div id="search-student-id-label" class="text-body-2 text-medium-emphasis pl-2">學號</div>
@@ -78,6 +80,7 @@
         <v-btn color="primary" disabled :prepend-icon="mdiMagnify" variant="tonal">查詢</v-btn>
       </v-col>
     </template>
+    <!-- table slot 放主檔表格與列操作，操作事件再交給頁面流程函式處理。 -->
     <template #table>
       <v-data-table
         v-model:page="currentPage"
diff --git a/src/components/pages/PageMasterDetailCMaintenance.vue b/src/components/pages/PageMasterDetailCMaintenance.vue
index 574d3d7..2252601 100644
--- a/src/components/pages/PageMasterDetailCMaintenance.vue
+++ b/src/components/pages/PageMasterDetailCMaintenance.vue
@@ -1,10 +1,12 @@
 <template>
+  <!-- Page component 組合 PageMaint 外殼、主檔表格、子檔區與 dialog；流程狀態集中在本頁 script。 -->
   <page-maint
     :search-panel-open="searchPanelOpen"
     :title="page.title"
     @create="openAddDialog"
     @toggle-search="searchPanelOpen = !searchPanelOpen"
   >
+    <!-- 搜尋欄位放在 PageMaint 的 search-fields slot，讓外殼固定、欄位由頁面決定。 -->
     <template #search-fields>
       <v-col cols="12" md="2">
         <div id="search-student-id-label" class="text-body-2 text-medium-emphasis pl-2">學號</div>
@@ -78,6 +80,7 @@
         <v-btn color="primary" disabled :prepend-icon="mdiMagnify" variant="tonal">查詢</v-btn>
       </v-col>
     </template>
+    <!-- table slot 放主檔表格與列操作，操作事件再交給頁面流程函式處理。 -->
     <template #table>
       <v-data-table
         v-model:page="currentPage"
diff --git a/src/components/pages/PageSectionQueryPageDemo.vue b/src/components/pages/PageSectionQueryPageDemo.vue
new file mode 100644
index 0000000..8131d0f
--- /dev/null
+++ b/src/components/pages/PageSectionQueryPageDemo.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import BaseFormSelect from '@/components/base/BaseFormSelect.vue'
+import BaseFormTextField from '@/components/base/BaseFormTextField.vue'
+import SectionQueryPage from '@/components/sections/SectionQueryPage.vue'
+import type {
+  ReportFilters,
+  SectionsDemoPageModel,
+} from '@/composables/page-drivers/useSectionsDemoPage'
+
+defineProps<{
+  page: SectionsDemoPageModel
+}>()
+
+// Page component 只接收 page driver 組好的 page model；查詢條件用 v-model 回寫給 view/page driver。
+const queryFilters = defineModel<ReportFilters>('queryFilters', { required: true })
+
+// 使用者意圖往上 emit，由 page driver 決定查詢、返回等副作用。
+const emit = defineEmits<{
+  (e: 'back'): void
+  (e: 'search'): void
+}>()
+</script>
+
+<template>
+  <SectionQueryPage
+    back-label="回到列表"
+    title="查詢頁DEMO"
+    @back="emit('back')"
+    @search="emit('search')"
+  >
+    <!-- SectionQueryPage 決定查詢頁外殼；欄位內容由 filters slot 交給頁面自行組合。 -->
+    <template #filters>
+      <v-col cols="12" md="4">
+        <BaseFormTextField v-model="queryFilters.keyword" label="關鍵字" />
+      </v-col>
+      <v-col cols="12" md="4">
+        <BaseFormSelect v-model="queryFilters.owner" label="單位" :items="page.ownerOptions" />
+      </v-col>
+    </template>
+
+    <!-- results slot 放查詢結果；資料仍由 page model 提供，這裡只負責呈現。 -->
+    <template #results>
+      <v-alert v-if="page.queryMessage" class="mb-3" type="success" variant="tonal">
+        {{ page.queryMessage }}
+      </v-alert>
+      <v-table density="compact">
+        <thead class="bg-primary">
+          <tr>
+            <th>名稱</th>
+            <th>單位</th>
+            <th>狀態</th>
+            <th>更新日</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-if="page.reports.length === 0">
+            <td class="text-center" colspan="4">尚無查詢結果</td>
+          </tr>
+          <tr v-for="row in page.reports" :key="row.id">
+            <td>{{ row.title }}</td>
+            <td>{{ row.owner }}</td>
+            <td>{{ row.status }}</td>
+            <td>{{ row.updatedAt }}</td>
+          </tr>
+        </tbody>
+      </v-table>
+    </template>
+  </SectionQueryPage>
+</template>
diff --git a/src/components/pages/PageSettings.vue b/src/components/pages/PageSettings.vue
index 01abcd4..29fe0f4 100644
--- a/src/components/pages/PageSettings.vue
+++ b/src/components/pages/PageSettings.vue
@@ -7,5 +7,6 @@ defineProps<{
 </script>
 
 <template>
+  <!-- Page component 只呈現 page driver 組好的設定頁 model。 -->
   <div>{{ page.title }}</div>
 </template>
diff --git a/src/components/sections/SectionQueryPage.vue b/src/components/sections/SectionQueryPage.vue
index 115012c..ee39688 100644
--- a/src/components/sections/SectionQueryPage.vue
+++ b/src/components/sections/SectionQueryPage.vue
@@ -18,7 +18,7 @@ const emit = defineEmits<{
 
 <template>
   <v-container fluid class="pt-2 px-1">
-    <v-card>
+    <v-card class="mb-2">
       <v-card-title class="text-title-large bg-primary">{{ title }}</v-card-title>
       <v-card-text class="pa-4">
         <v-alert v-if="error" class="mb-4" type="error" variant="tonal">{{ error }}</v-alert>
diff --git a/src/composables/layout/useAppShell.ts b/src/composables/layout/useAppShell.ts
index 6dfdb16..62895d6 100644
--- a/src/composables/layout/useAppShell.ts
+++ b/src/composables/layout/useAppShell.ts
@@ -29,6 +29,23 @@ const fixedMenuItems: LayoutMenuItem[] = [
       { title: '可編輯表格維護', icon: mdiTableEdit, path: '/editable-grid-maintenance' },
     ],
   },
+  {
+    title: '範例頁面',
+    navigable: false,
+    subItems: [
+      {
+        title: 'SectionQueryPage',
+        icon: mdiFileDocumentOutline,
+        path: '/demos/sections/query-page',
+      },
+      { title: 'SectionFormPage', icon: mdiFileDocumentOutline, path: '/demos/sections/form-page' },
+      {
+        title: 'SectionSearchPanel',
+        icon: mdiFileDocumentOutline,
+        path: '/demos/sections/search-panel',
+      },
+    ],
+  },
   { title: '登入頁', path: '/login' },
 ]
 
diff --git a/src/composables/page-drivers/useSectionsDemoPage.ts b/src/composables/page-drivers/useSectionsDemoPage.ts
new file mode 100644
index 0000000..f9232d6
--- /dev/null
+++ b/src/composables/page-drivers/useSectionsDemoPage.ts
@@ -0,0 +1,410 @@
+import { computed, ref, watch } from 'vue'
+import type { StudentRecord } from '@/models/student'
+import { useSnackbarStore } from '@/stores/snackbar'
+import type {
+  SaveSummaryItem,
+  StudentFormState,
+} from '@/composables/maint/useStudentMaintenanceForm'
+
+export interface ReportSummary {
+  id: number
+  title: string
+  owner: string
+  status: string
+  updatedAt: string
+}
+
+export interface ReportFilters {
+  keyword: string
+  owner: string
+}
+
+export interface DemoFormState {
+  title: string
+  owner: string
+  category: string
+  description: string
+}
+
+export interface MaintenanceSearchState {
+  studentId: string
+  name: string
+  department: string
+  grade: number | null
+  status: string
+}
+
+export interface SectionsDemoPageModel {
+  title: string
+  ownerOptions: string[]
+  categoryOptions: string[]
+  queryMessage: string
+  formMessage: string
+  reports: ReportSummary[]
+  departments: string[]
+  gradeOptions: GradeOption[]
+  enrollYears: number[]
+  statuses: string[]
+  maintenanceHeaders: Array<Record<string, unknown>>
+  maintenanceItems: StudentRecord[]
+  maintenanceItemsPerPage: number
+  maintenancePageCount: number
+  maintenancePageSummary: string
+  formPanelProps: FormPanelProps
+}
+
+interface GradeOption {
+  title: string
+  value: number
+}
+
+type FieldErrors = Record<keyof StudentFormState, string[]>
+
+interface FormPanelProps {
+  confirmCloseVisible: boolean
+  confirmDeleteVisible: boolean
+  confirmNavigateVisible: boolean
+  confirmSaveVisible: boolean
+  confirmSwitchVisible: boolean
+  departments: string[]
+  dialogSubtitle: string
+  dialogTitle: string
+  dialogVisible: boolean
+  enrollYears: number[]
+  errorSummary: Array<{ field: string; message: string }>
+  fieldErrors: FieldErrors
+  gradeOptions: GradeOption[]
+  hasNextRecord: boolean
+  hasPrevRecord: boolean
+  isDirty: boolean
+  isEditMode: boolean
+  isFormLocked: boolean
+  isFormReadonly: boolean
+  isLoading: boolean
+  isSaving: boolean
+  isViewMode: boolean
+  pendingDeleteLabel: string
+  saveSummary: SaveSummaryItem[]
+  statuses: string[]
+}
+
+const reports: ReportSummary[] = [
+  { id: 1, title: '學生統計', owner: '教務處', status: '已發布', updatedAt: '2026-05-01' },
+  { id: 2, title: '課程統計', owner: '課務組', status: '草稿', updatedAt: '2026-05-08' },
+  { id: 3, title: '系統使用量', owner: '資訊中心', status: '已發布', updatedAt: '2026-05-15' },
+]
+
+const ownerOptions = ['全部', '教務處', '課務組', '資訊中心']
+const categoryOptions = ['一般報表', '申請表單', '維護資料']
+const departments = ['資訊工程', '企業管理', '應用外語', '視覺設計', '財務金融']
+const gradeOptions: GradeOption[] = [
+  { title: '大一', value: 1 },
+  { title: '大二', value: 2 },
+  { title: '大三', value: 3 },
+  { title: '大四', value: 4 },
+]
+const enrollYears = [2026, 2025, 2024, 2023]
+const statuses = ['在學', '休學', '畢業']
+const maintenanceItemsPerPage = 5
+
+const students: StudentRecord[] = [
+  {
+    id: 1,
+    studentId: 'S2026001',
+    name: '王小明',
+    department: '資訊工程',
+    grade: 1,
+    enrollYear: 2026,
+    credits: 18,
+    advisor: '陳教授',
+    email: 'ming@example.edu',
+    phone: '0912000001',
+    status: '在學',
+  },
+  {
+    id: 2,
+    studentId: 'S2025007',
+    name: '林雅婷',
+    department: '企業管理',
+    grade: 2,
+    enrollYear: 2025,
+    credits: 42,
+    advisor: '李教授',
+    email: 'yating@example.edu',
+    phone: '0912000002',
+    status: '在學',
+  },
+  {
+    id: 3,
+    studentId: 'S2024012',
+    name: '張志豪',
+    department: '應用外語',
+    grade: 3,
+    enrollYear: 2024,
+    credits: 86,
+    advisor: '黃教授',
+    email: 'zhihao@example.edu',
+    phone: '0912000003',
+    status: '休學',
+  },
+]
+
+const maintenanceHeaders = [
+  { title: '學號', key: 'studentId', sortable: true, width: 120 },
+  { title: '姓名', key: 'name', sortable: true, width: 100 },
+  { title: '系所', key: 'department', sortable: true, width: 140 },
+  { title: '年級', key: 'grade', sortable: true, width: 90 },
+  { title: 'Email', key: 'email', sortable: true, width: 200 },
+  { title: '狀態', key: 'status', sortable: true, width: 90 },
+  { title: '操作', key: 'actions', sortable: false, width: 220 },
+]
+
+const defaultQueryFilters: ReportFilters = {
+  keyword: '',
+  owner: '全部',
+}
+
+const defaultDemoForm: DemoFormState = {
+  title: '',
+  owner: '教務處',
+  category: '一般報表',
+  description: '',
+}
+
+const defaultMaintenanceSearch: MaintenanceSearchState = {
+  studentId: '',
+  name: '',
+  department: '',
+  grade: null,
+  status: '',
+}
+
+const defaultFormPanelForm: StudentFormState = {
+  studentId: '',
+  name: '',
+  department: departments[0] ?? '',
+  grade: gradeOptions[0]?.value ?? 1,
+  enrollYear: enrollYears[0] ?? 2026,
+  credits: 0,
+  advisor: '',
+  email: '',
+  phone: '',
+  status: statuses[0] ?? '',
+}
+
+function createEmptyFieldErrors(): FieldErrors {
+  return {
+    studentId: [],
+    name: [],
+    department: [],
+    grade: [],
+    enrollYear: [],
+    credits: [],
+    advisor: [],
+    email: [],
+    phone: [],
+    status: [],
+  }
+}
+
+export function useSectionsDemoPage() {
+  const snackbar = useSnackbarStore()
+  const queryFilters = ref<ReportFilters>({ ...defaultQueryFilters })
+  const demoForm = ref<DemoFormState>({ ...defaultDemoForm })
+  const maintenanceSearch = ref<MaintenanceSearchState>({ ...defaultMaintenanceSearch })
+  const maintenanceCurrentPage = ref(1)
+  const formPanelVisible = ref(false)
+  const formPanelForm = ref<StudentFormState>({ ...defaultFormPanelForm })
+  const fieldErrors = ref<FieldErrors>(createEmptyFieldErrors())
+  const queryMessage = ref('')
+  const formMessage = ref('')
+
+  const filteredReports = computed(() => {
+    const keyword = queryFilters.value.keyword.trim().toLowerCase()
+    const owner = queryFilters.value.owner
+    return reports.filter((item) => {
+      const keywordMatched =
+        !keyword ||
+        item.title.toLowerCase().includes(keyword) ||
+        item.owner.toLowerCase().includes(keyword)
+      const ownerMatched = owner === '全部' || item.owner === owner
+      return keywordMatched && ownerMatched
+    })
+  })
+
+  const maintenanceItems = computed(() => {
+    const keywordId = maintenanceSearch.value.studentId.trim().toLowerCase()
+    const keywordName = maintenanceSearch.value.name.trim().toLowerCase()
+    return students.filter((item) => {
+      const idMatched = !keywordId || item.studentId.toLowerCase().includes(keywordId)
+      const nameMatched = !keywordName || item.name.toLowerCase().includes(keywordName)
+      const departmentMatched =
+        !maintenanceSearch.value.department || item.department === maintenanceSearch.value.department
+      const gradeMatched =
+        maintenanceSearch.value.grade == null || item.grade === maintenanceSearch.value.grade
+      const statusMatched = !maintenanceSearch.value.status || item.status === maintenanceSearch.value.status
+      return idMatched && nameMatched && departmentMatched && gradeMatched && statusMatched
+    })
+  })
+
+  const maintenancePageCount = computed(() =>
+    Math.max(1, Math.ceil(maintenanceItems.value.length / maintenanceItemsPerPage))
+  )
+
+  const maintenancePageSummary = computed(() => {
+    const total = maintenanceItems.value.length
+    if (total === 0) return '第 0-0 筆 / 共 0 筆'
+    const start = (maintenanceCurrentPage.value - 1) * maintenanceItemsPerPage + 1
+    const end = Math.min(maintenanceCurrentPage.value * maintenanceItemsPerPage, total)
+    return `第 ${start}-${end} 筆 / 共 ${total} 筆`
+  })
+
+  const isFormPanelDirty = computed(
+    () => JSON.stringify(formPanelForm.value) !== JSON.stringify(defaultFormPanelForm)
+  )
+
+  const formPanelProps = computed<FormPanelProps>(() => ({
+    confirmCloseVisible: false,
+    confirmDeleteVisible: false,
+    confirmNavigateVisible: false,
+    confirmSaveVisible: false,
+    confirmSwitchVisible: false,
+    departments,
+    dialogSubtitle: formPanelForm.value.studentId || '尚未輸入學號',
+    dialogTitle: 'SectionFormPanel 範例',
+    dialogVisible: formPanelVisible.value,
+    enrollYears,
+    errorSummary: [],
+    fieldErrors: fieldErrors.value,
+    gradeOptions,
+    hasNextRecord: false,
+    hasPrevRecord: false,
+    isDirty: isFormPanelDirty.value,
+    isEditMode: false,
+    isFormLocked: false,
+    isFormReadonly: false,
+    isLoading: false,
+    isSaving: false,
+    isViewMode: false,
+    pendingDeleteLabel: formPanelForm.value.name || '目前資料',
+    saveSummary: [],
+    statuses,
+  }))
+
+  const pageModel = computed<SectionsDemoPageModel>(() => ({
+    title: '新增頁面與 Section 範例',
+    ownerOptions,
+    categoryOptions,
+    queryMessage: queryMessage.value,
+    formMessage: formMessage.value,
+    reports: filteredReports.value,
+    departments,
+    gradeOptions,
+    enrollYears,
+    statuses,
+    maintenanceHeaders,
+    maintenanceItems: maintenanceItems.value,
+    maintenanceItemsPerPage,
+    maintenancePageCount: maintenancePageCount.value,
+    maintenancePageSummary: maintenancePageSummary.value,
+    formPanelProps: formPanelProps.value,
+  }))
+
+  watch(maintenancePageCount, (value) => {
+    if (maintenanceCurrentPage.value > value) maintenanceCurrentPage.value = value
+  })
+
+  function handleQuerySearch() {
+    queryMessage.value = `查詢完成，共 ${filteredReports.value.length} 筆`
+  }
+
+  function handleQueryBack() {
+    snackbar.show({ message: '查詢頁返回事件', color: 'info' })
+  }
+
+  function handleFormSubmit() {
+    formMessage.value = demoForm.value.title.trim()
+      ? `已送出：${demoForm.value.title.trim()}`
+      : '請輸入標題後再送出'
+  }
+
+  function resetDemoForm() {
+    demoForm.value = { ...defaultDemoForm }
+    formMessage.value = ''
+  }
+
+  function handleFormBack() {
+    snackbar.show({ message: '表單頁返回事件', color: 'info' })
+  }
+
+  function resetMaintenanceSearch() {
+    maintenanceSearch.value = { ...defaultMaintenanceSearch }
+    maintenanceCurrentPage.value = 1
+  }
+
+  function handleMaintenanceAction(action: string, record: StudentRecord) {
+    snackbar.show({ message: `${action}：${record.studentId} ${record.name}`, color: 'info' })
+  }
+
+  function openFormPanel() {
+    formPanelVisible.value = true
+  }
+
+  function closeFormPanel() {
+    formPanelVisible.value = false
+  }
+
+  function handleFormPanelVisibleChange(value: boolean) {
+    formPanelVisible.value = value
+  }
+
+  function handleFormPanelSave() {
+    formPanelVisible.value = false
+    snackbar.show({ message: 'SectionFormPanel 儲存事件', color: 'success' })
+  }
+
+  function clearFormPanelFieldError(field: keyof StudentFormState | string) {
+    const key = field as keyof StudentFormState
+    if (!fieldErrors.value[key]?.length) return
+    fieldErrors.value[key] = []
+  }
+
+  function gradeLabel(grade: number) {
+    return gradeOptions.find((option) => option.value === grade)?.title ?? `年級 ${grade}`
+  }
+
+  function statusColor(status: string) {
+    if (status === '在學') return 'success'
+    if (status === '休學') return 'warning'
+    if (status === '畢業') return 'secondary'
+    return 'default'
+  }
+
+  function rowProps() {
+    return {}
+  }
+
+  return {
+    demoForm,
+    formPanelForm,
+    maintenanceCurrentPage,
+    maintenanceSearch,
+    pageModel,
+    queryFilters,
+    clearFormPanelFieldError,
+    closeFormPanel,
+    gradeLabel,
+    handleFormBack,
+    handleFormPanelSave,
+    handleFormPanelVisibleChange,
+    handleFormSubmit,
+    handleMaintenanceAction,
+    handleQueryBack,
+    handleQuerySearch,
+    openFormPanel,
+    resetDemoForm,
+    resetMaintenanceSearch,
+    rowProps,
+    statusColor,
+  }
+}
diff --git a/src/router/routes.ts b/src/router/routes.ts
index 9e64c0e..08cea1b 100644
--- a/src/router/routes.ts
+++ b/src/router/routes.ts
@@ -49,6 +49,28 @@ export const routes: RouteRecordRaw[] = [
     component: () => import('@/views/maint/EditableGrid.vue'),
     meta: { layout: 'default' },
   },
+  {
+    path: '/demos/sections',
+    redirect: '/demos/sections/query-page',
+  },
+  {
+    path: '/demos/sections/query-page',
+    name: 'demo-section-query-page',
+    component: () => import('@/views/demos/SectionQueryPageDemo.vue'),
+    meta: { title: 'SectionQueryPage 示範', layout: 'default' },
+  },
+  {
+    path: '/demos/sections/form-page',
+    name: 'demo-section-form-page',
+    component: () => import('@/views/demos/SectionFormPageDemo.vue'),
+    meta: { title: 'SectionFormPage 示範', layout: 'default' },
+  },
+  {
+    path: '/demos/sections/search-panel',
+    name: 'demo-section-search-panel',
+    component: () => import('@/views/demos/SectionSearchPanelDemo.vue'),
+    meta: { title: 'SectionSearchPanel 示範', layout: 'default' },
+  },
   {
     path: '/:fncId([0-9A-Z]{5,6})',
     name: 'fnc-page',
diff --git a/src/views/GUIDE.md b/src/views/GUIDE.md
index a9ae71f..1f6f819 100644
--- a/src/views/GUIDE.md
+++ b/src/views/GUIDE.md
@@ -39,5 +39,6 @@ const page = useReportsPage()
 
 ## 子目錄
 
+- `views/demos` 是一般頁面與 section 使用方式的 demo route entry，仍需維持薄 view。
 - `views/maint` 是 maintenance demo route entry。詳見 `src/views/maint/GUIDE.md`。
 - `views/errors` 是錯誤頁入口，通常使用 `meta.layout = 'none'`。每個錯誤頁（`Forbidden.vue`、`ServerError.vue`、`NotFound.vue` 等）只傳入 props 給共用的 `ErrorShell.vue`，不再各自重複佈局邏輯。`ErrorShell.vue` 提供標題、圖示、顏色、描述、後端訊息、操作按鈕（返回上頁 / 回首頁 / 前往登入）等 slots。
diff --git a/src/views/demos/SectionQueryPageDemo.vue b/src/views/demos/SectionQueryPageDemo.vue
new file mode 100644
index 0000000..e1d16e4
--- /dev/null
+++ b/src/views/demos/SectionQueryPageDemo.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import PageSectionQueryPageDemo from '@/components/pages/PageSectionQueryPageDemo.vue'
+import { useSectionsDemoPage } from '@/composables/page-drivers/useSectionsDemoPage'
+
+// Demo view 維持薄層，只掛 page driver，並把 page model / actions 傳給 page component。
+const page = useSectionsDemoPage()
+</script>
+
+<template>
+  <PageSectionQueryPageDemo
+    v-model:query-filters="page.queryFilters.value"
+    :page="page.pageModel.value"
+    @back="page.handleQueryBack"
+    @search="page.handleQuerySearch"
+  />
+</template>