From b8664b5c3ee55474918396c0b9b7d5ce9b3cbb7d Mon Sep 17 00:00:00 2001
From: skytek_xinliang <carl@skytek.com.tw>
Date: Wed, 27 May 2026 11:10:34 +0800
Subject: [PATCH] refactor: simplify page models and view driver usage

Move simple page models into page components and build trivial computed
models directly in views to avoid unnecessary page drivers. Update views
to destructure page driver returns and rely on template ref unwrapping,
and document the guidance for when page drivers should be introduced.refactor: simplify page models and view driver usage

Move simple page models into page components and build trivial computed
models directly in views to avoid unnecessary page drivers. Update views
to destructure page driver returns and rely on template ref unwrapping,
and document the guidance for when page drivers should be introduced.
---
 src/components/pages/PageFunction.vue         |  4 +-
 src/components/pages/PageSettings.vue         |  4 +-
 src/composables/GUIDE.md                      | 17 ++++--
 .../useEditableGridMaintenancePage.ts         | 19 -------
 .../page-drivers/useFunctionPage.ts           | 18 -------
 .../page-drivers/useMaintenancePage.ts        | 46 ----------------
 .../useMasterDetailBMaintenancePage.ts        | 20 -------
 .../useMasterDetailCMaintenancePage.ts        | 20 -------
 .../page-drivers/useSettingsPage.ts           | 13 -----
 src/views/FncPage.vue                         |  9 +++-
 src/views/Home.vue                            | 14 ++---
 src/views/Settings.vue                        |  7 ++-
 src/views/demos/SectionFormPageDemo.vue       | 13 +++--
 src/views/demos/SectionQueryPageDemo.vue      | 11 ++--
 src/views/maint/EditableGrid.vue              | 15 ++++--
 src/views/maint/MasterDetailA.vue             | 46 ++++++++--------
 src/views/maint/MasterDetailB.vue             | 15 ++++--
 src/views/maint/MasterDetailC.vue             | 15 ++++--
 src/views/maint/SingleRecord.vue              | 53 ++++++++++---------
 19 files changed, 139 insertions(+), 220 deletions(-)
 delete mode 100644 src/composables/page-drivers/useEditableGridMaintenancePage.ts
 delete mode 100644 src/composables/page-drivers/useFunctionPage.ts
 delete mode 100644 src/composables/page-drivers/useMaintenancePage.ts
 delete mode 100644 src/composables/page-drivers/useMasterDetailBMaintenancePage.ts
 delete mode 100644 src/composables/page-drivers/useMasterDetailCMaintenancePage.ts
 delete mode 100644 src/composables/page-drivers/useSettingsPage.ts

diff --git a/src/components/pages/PageFunction.vue b/src/components/pages/PageFunction.vue
index d518c93..5758cfa 100644
--- a/src/components/pages/PageFunction.vue
+++ b/src/components/pages/PageFunction.vue
@@ -1,5 +1,7 @@
 <script setup lang="ts">
-import type { FunctionPageModel } from '@/composables/page-drivers/useFunctionPage'
+export interface FunctionPageModel {
+  fncId: string
+}
 
 defineProps<{
   page: FunctionPageModel
diff --git a/src/components/pages/PageSettings.vue b/src/components/pages/PageSettings.vue
index 29fe0f4..92357ec 100644
--- a/src/components/pages/PageSettings.vue
+++ b/src/components/pages/PageSettings.vue
@@ -1,5 +1,7 @@
 <script setup lang="ts">
-import type { SettingsPageModel } from '@/composables/page-drivers/useSettingsPage'
+export interface SettingsPageModel {
+  title: string
+}
 
 defineProps<{
   page: SettingsPageModel
diff --git a/src/composables/GUIDE.md b/src/composables/GUIDE.md
index c78f681..1aaa458 100644
--- a/src/composables/GUIDE.md
+++ b/src/composables/GUIDE.md
@@ -22,14 +22,23 @@
 
 ## Page Driver
 
-Page driver 負責：
+Page driver 只應在「需要協調多個 composable / store / route」時才成立。若頁面邏輯只有：
 
+- 組裝一個 `computed` page model（3-5 個欄位）
+- 沒有搜尋、沒有 dialog、沒有複雜事件
+
+則**不要建立 page driver**，直接在 view 裡寫 `computed` 即可。
+
+當需要 page driver 時，它負責：
 - route param/query 轉成頁面資料
-- 組裝 page model
-- 組裝 page component 需要的 props/events
 - 協調 store、command composable、表單 composable
+- 組裝 page component 需要的 props/events
 
-View 只呼叫 page driver 並掛載 page component。
+View 以 destructure 方式取用 page driver 回傳值：
+```ts
+const { pageModel, search, handleSubmit } = useXxxPage()
+```
+模板中直接使用，不寫 `.value`：`:page="pageModel"`、`v-model="search"`。
 
 ## Commands
 
diff --git a/src/composables/page-drivers/useEditableGridMaintenancePage.ts b/src/composables/page-drivers/useEditableGridMaintenancePage.ts
deleted file mode 100644
index 986ec36..0000000
--- a/src/composables/page-drivers/useEditableGridMaintenancePage.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { computed } from 'vue'
-import type { MaintenancePageModel } from '@/models/page'
-import { useStudentStore } from '@/stores/students'
-
-export function useEditableGridMaintenancePage() {
-  const studentStore = useStudentStore()
-
-  const pageModel = computed<MaintenancePageModel>(() => ({
-    type: 'maintenance',
-    title: '可編輯表格維護示範',
-    records: studentStore.students,
-    loading: false,
-    error: null,
-  }))
-
-  return {
-    pageModel,
-  }
-}
diff --git a/src/composables/page-drivers/useFunctionPage.ts b/src/composables/page-drivers/useFunctionPage.ts
deleted file mode 100644
index 4259a1d..0000000
--- a/src/composables/page-drivers/useFunctionPage.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { computed } from 'vue'
-import { useRoute } from 'vue-router'
-
-export interface FunctionPageModel {
-  fncId: string
-}
-
-export function useFunctionPage() {
-  const route = useRoute()
-
-  const pageModel = computed<FunctionPageModel>(() => ({
-    fncId: String(route.params.fncId ?? ''),
-  }))
-
-  return {
-    pageModel,
-  }
-}
diff --git a/src/composables/page-drivers/useMaintenancePage.ts b/src/composables/page-drivers/useMaintenancePage.ts
deleted file mode 100644
index 23a920f..0000000
--- a/src/composables/page-drivers/useMaintenancePage.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-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/composables/page-drivers/useMasterDetailBMaintenancePage.ts b/src/composables/page-drivers/useMasterDetailBMaintenancePage.ts
deleted file mode 100644
index 5cb9c37..0000000
--- a/src/composables/page-drivers/useMasterDetailBMaintenancePage.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { computed } from 'vue'
-
-import type { MaintenancePageModel } from '@/models/page'
-import { useStudentStore } from '@/stores/students'
-
-export function useMasterDetailBMaintenancePage() {
-  const studentStore = useStudentStore()
-
-  const pageModel = computed<MaintenancePageModel>(() => ({
-    type: 'maintenance',
-    title: '主從資料維護示範B',
-    records: studentStore.students,
-    loading: false,
-    error: null,
-  }))
-
-  return {
-    pageModel,
-  }
-}
diff --git a/src/composables/page-drivers/useMasterDetailCMaintenancePage.ts b/src/composables/page-drivers/useMasterDetailCMaintenancePage.ts
deleted file mode 100644
index 42895c6..0000000
--- a/src/composables/page-drivers/useMasterDetailCMaintenancePage.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { computed } from 'vue'
-
-import type { MaintenancePageModel } from '@/models/page'
-import { useStudentStore } from '@/stores/students'
-
-export function useMasterDetailCMaintenancePage() {
-  const studentStore = useStudentStore()
-
-  const pageModel = computed<MaintenancePageModel>(() => ({
-    type: 'maintenance',
-    title: '主從資料維護示範C',
-    records: studentStore.students,
-    loading: false,
-    error: null,
-  }))
-
-  return {
-    pageModel,
-  }
-}
diff --git a/src/composables/page-drivers/useSettingsPage.ts b/src/composables/page-drivers/useSettingsPage.ts
deleted file mode 100644
index 6101239..0000000
--- a/src/composables/page-drivers/useSettingsPage.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { computed } from 'vue'
-
-export interface SettingsPageModel {
-  title: string
-}
-
-export function useSettingsPage() {
-  const pageModel = computed<SettingsPageModel>(() => ({
-    title: '設定頁面',
-  }))
-
-  return { pageModel }
-}
diff --git a/src/views/FncPage.vue b/src/views/FncPage.vue
index 4a6aa7c..0d12081 100644
--- a/src/views/FncPage.vue
+++ b/src/views/FncPage.vue
@@ -1,8 +1,13 @@
 <script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
 import PageFunction from '@/components/pages/PageFunction.vue'
-import { useFunctionPage } from '@/composables/page-drivers/useFunctionPage'
+import type { FunctionPageModel } from '@/components/pages/PageFunction.vue'
 
-const { pageModel } = useFunctionPage()
+const route = useRoute()
+const pageModel = computed<FunctionPageModel>(() => ({
+  fncId: String(route.params.fncId ?? ''),
+}))
 </script>
 
 <template>
diff --git a/src/views/Home.vue b/src/views/Home.vue
index 11edc13..0a5dee3 100644
--- a/src/views/Home.vue
+++ b/src/views/Home.vue
@@ -2,16 +2,16 @@
 import PageHome from '@/components/pages/PageHome.vue'
 import { useHomePage } from '@/composables/page-drivers/useHomePage'
 
-const page = useHomePage()
+const { handleMessageCenter, handleNews, handleQuick, isNewsDialogOpen, pageModel, selectedNews } = useHomePage()
 </script>
 
 <template>
   <PageHome
-    v-model:news-dialog-open="page.isNewsDialogOpen.value"
-    :page="page.pageModel.value"
-    :selected-news="page.selectedNews.value"
-    @message-center="page.handleMessageCenter"
-    @news="page.handleNews"
-    @quick="page.handleQuick"
+    v-model:news-dialog-open="isNewsDialogOpen"
+    :page="pageModel"
+    :selected-news="selectedNews"
+    @message-center="handleMessageCenter"
+    @news="handleNews"
+    @quick="handleQuick"
   />
 </template>
diff --git a/src/views/Settings.vue b/src/views/Settings.vue
index 07b1c35..e78c267 100644
--- a/src/views/Settings.vue
+++ b/src/views/Settings.vue
@@ -1,8 +1,11 @@
 <script setup lang="ts">
+import { computed } from 'vue'
 import PageSettings from '@/components/pages/PageSettings.vue'
-import { useSettingsPage } from '@/composables/page-drivers/useSettingsPage'
+import type { SettingsPageModel } from '@/components/pages/PageSettings.vue'
 
-const { pageModel } = useSettingsPage()
+const pageModel = computed<SettingsPageModel>(() => ({
+  title: '設定頁面',
+}))
 </script>
 
 <template>
diff --git a/src/views/demos/SectionFormPageDemo.vue b/src/views/demos/SectionFormPageDemo.vue
index fbea6b2..678fba8 100644
--- a/src/views/demos/SectionFormPageDemo.vue
+++ b/src/views/demos/SectionFormPageDemo.vue
@@ -2,16 +2,15 @@
 import PageSectionFormPageDemo from '@/components/pages/PageSectionFormPageDemo.vue'
 import { useSectionsDemoPage } from '@/composables/page-drivers/useSectionsDemoPage'
 
-// Demo view 維持薄層，只掛 page driver，並把 page model / actions 傳給 page component。
-const page = useSectionsDemoPage()
+const { demoForm, handleFormBack, handleFormSubmit, pageModel, resetDemoForm } = useSectionsDemoPage()
 </script>
 
 <template>
   <PageSectionFormPageDemo
-    v-model:demo-form="page.demoForm.value"
-    :page="page.pageModel.value"
-    @back="page.handleFormBack"
-    @reset="page.resetDemoForm"
-    @submit="page.handleFormSubmit"
+    v-model:demo-form="demoForm"
+    :page="pageModel"
+    @back="handleFormBack"
+    @reset="resetDemoForm"
+    @submit="handleFormSubmit"
   />
 </template>
diff --git a/src/views/demos/SectionQueryPageDemo.vue b/src/views/demos/SectionQueryPageDemo.vue
index e1d16e4..392d28e 100644
--- a/src/views/demos/SectionQueryPageDemo.vue
+++ b/src/views/demos/SectionQueryPageDemo.vue
@@ -2,15 +2,14 @@
 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()
+const { handleQueryBack, handleQuerySearch, pageModel, queryFilters } = useSectionsDemoPage()
 </script>
 
 <template>
   <PageSectionQueryPageDemo
-    v-model:query-filters="page.queryFilters.value"
-    :page="page.pageModel.value"
-    @back="page.handleQueryBack"
-    @search="page.handleQuerySearch"
+    v-model:query-filters="queryFilters"
+    :page="pageModel"
+    @back="handleQueryBack"
+    @search="handleQuerySearch"
   />
 </template>
diff --git a/src/views/maint/EditableGrid.vue b/src/views/maint/EditableGrid.vue
index eac0dfa..ef01ee7 100644
--- a/src/views/maint/EditableGrid.vue
+++ b/src/views/maint/EditableGrid.vue
@@ -1,10 +1,19 @@
 <script setup lang="ts">
+import { computed } from 'vue'
 import PageEditableGridMaintenance from '@/components/pages/PageEditableGridMaintenance.vue'
-import { useEditableGridMaintenancePage } from '@/composables/page-drivers/useEditableGridMaintenancePage'
+import type { MaintenancePageModel } from '@/models/page'
+import { useStudentStore } from '@/stores/students'
 
-const page = useEditableGridMaintenancePage()
+const studentStore = useStudentStore()
+const pageModel = computed<MaintenancePageModel>(() => ({
+  type: 'maintenance',
+  title: '可編輯表格維護示範',
+  records: studentStore.students,
+  loading: false,
+  error: null,
+}))
 </script>
 
 <template>
-  <PageEditableGridMaintenance :page="page.pageModel.value" />
+  <PageEditableGridMaintenance :page="pageModel" />
 </template>
diff --git a/src/views/maint/MasterDetailA.vue b/src/views/maint/MasterDetailA.vue
index 9b2ca4a..f0a4b00 100644
--- a/src/views/maint/MasterDetailA.vue
+++ b/src/views/maint/MasterDetailA.vue
@@ -2,33 +2,37 @@
 import PageMasterDetailAMaintenance from '@/components/pages/PageMasterDetailAMaintenance.vue'
 import { useMasterDetailAMaintenancePage } from '@/composables/page-drivers/useMasterDetailAMaintenancePage'
 
-const page = useMasterDetailAMaintenancePage()
+const {
+  currentPage, formState, itemsPerPage, masterDetailEvents, masterDetailProps,
+  openAddDialog, openEditDialog, openViewDialog, pageCount, pageModel, pageSummary,
+  resetSearch, search, searchPanelOpen, snackbarVisible, students, tableHeaders,
+} = useMasterDetailAMaintenancePage()
 </script>
 
 <template>
   <PageMasterDetailAMaintenance
-    v-model:search="page.search.value"
-    v-model:search-panel-open="page.searchPanelOpen.value"
-    v-bind="page.masterDetailProps.value"
-    :current-page="page.currentPage.value"
-    :grade-label="page.formState.gradeLabel"
-    :headers="page.tableHeaders.value"
-    :items="page.students.value"
-    :items-per-page="page.itemsPerPage"
-    :page="page.pageModel.value"
-    :page-count="page.pageCount.value"
-    :page-summary="page.pageSummary.value"
-    :row-props="page.formState.rowProps"
-    :status-color="page.formState.statusColor"
-    @create="page.openAddDialog"
-    @edit="page.openEditDialog"
-    @reset-search="page.resetSearch"
-    @update:current-page="page.currentPage.value = $event"
-    @view="page.openViewDialog"
-    v-on="page.masterDetailEvents"
+    v-model:search="search"
+    v-model:search-panel-open="searchPanelOpen"
+    v-bind="masterDetailProps"
+    :current-page="currentPage"
+    :grade-label="formState.gradeLabel"
+    :headers="tableHeaders"
+    :items="students"
+    :items-per-page="itemsPerPage"
+    :page="pageModel"
+    :page-count="pageCount"
+    :page-summary="pageSummary"
+    :row-props="formState.rowProps"
+    :status-color="formState.statusColor"
+    @create="openAddDialog"
+    @edit="openEditDialog"
+    @reset-search="resetSearch"
+    @update:current-page="currentPage = $event"
+    @view="openViewDialog"
+    v-on="masterDetailEvents"
   />
 
-  <v-snackbar v-model="page.snackbarVisible.value" color="success" location="bottom right" :timeout="2200">
+  <v-snackbar v-model="snackbarVisible" color="success" location="bottom right" :timeout="2200">
     儲存成功
   </v-snackbar>
 </template>
diff --git a/src/views/maint/MasterDetailB.vue b/src/views/maint/MasterDetailB.vue
index 0a6aac1..81ab36f 100644
--- a/src/views/maint/MasterDetailB.vue
+++ b/src/views/maint/MasterDetailB.vue
@@ -1,10 +1,19 @@
 <script setup lang="ts">
+import { computed } from 'vue'
 import PageMasterDetailBMaintenance from '@/components/pages/PageMasterDetailBMaintenance.vue'
-import { useMasterDetailBMaintenancePage } from '@/composables/page-drivers/useMasterDetailBMaintenancePage'
+import type { MaintenancePageModel } from '@/models/page'
+import { useStudentStore } from '@/stores/students'
 
-const page = useMasterDetailBMaintenancePage()
+const studentStore = useStudentStore()
+const pageModel = computed<MaintenancePageModel>(() => ({
+  type: 'maintenance',
+  title: '主從資料維護示範B',
+  records: studentStore.students,
+  loading: false,
+  error: null,
+}))
 </script>
 
 <template>
-  <PageMasterDetailBMaintenance :page="page.pageModel.value" />
+  <PageMasterDetailBMaintenance :page="pageModel" />
 </template>
diff --git a/src/views/maint/MasterDetailC.vue b/src/views/maint/MasterDetailC.vue
index 75a2ffd..0c94cd7 100644
--- a/src/views/maint/MasterDetailC.vue
+++ b/src/views/maint/MasterDetailC.vue
@@ -1,10 +1,19 @@
 <script setup lang="ts">
+import { computed } from 'vue'
 import PageMasterDetailCMaintenance from '@/components/pages/PageMasterDetailCMaintenance.vue'
-import { useMasterDetailCMaintenancePage } from '@/composables/page-drivers/useMasterDetailCMaintenancePage'
+import type { MaintenancePageModel } from '@/models/page'
+import { useStudentStore } from '@/stores/students'
 
-const page = useMasterDetailCMaintenancePage()
+const studentStore = useStudentStore()
+const pageModel = computed<MaintenancePageModel>(() => ({
+  type: 'maintenance',
+  title: '主從資料維護示範C',
+  records: studentStore.students,
+  loading: false,
+  error: null,
+}))
 </script>
 
 <template>
-  <PageMasterDetailCMaintenance :page="page.pageModel.value" />
+  <PageMasterDetailCMaintenance :page="pageModel" />
 </template>
diff --git a/src/views/maint/SingleRecord.vue b/src/views/maint/SingleRecord.vue
index 0412f76..92f4340 100644
--- a/src/views/maint/SingleRecord.vue
+++ b/src/views/maint/SingleRecord.vue
@@ -5,48 +5,53 @@ import SectionFormPanel from '@/components/sections/SectionFormPanel.vue'
 import SectionSearchPanel from '@/components/sections/SectionSearchPanel.vue'
 import { useSingleRecordMaintenancePage } from '@/composables/page-drivers/useSingleRecordMaintenancePage'
 
-const page = useSingleRecordMaintenancePage()
+const {
+  commands, currentPage, departments, flow, formPanelEvents, formPanelProps,
+  formState, gradeOptions, itemsPerPage, pageCount, pageModel, pageSummary,
+  resetSearch, search, searchPanelOpen, snackbarVisible,
+  statuses, students, tableHeaders,
+} = useSingleRecordMaintenancePage()
 </script>
 
 <template>
   <PageMaintenance
-    v-model:search-panel-open="page.searchPanelOpen.value"
-    :page="page.pageModel.value"
-    @create="page.commands.openAddDialog"
+    v-model:search-panel-open="searchPanelOpen"
+    :page="pageModel"
+    @create="commands.openAddDialog"
   >
     <template #search-fields>
       <SectionSearchPanel
-        v-model="page.search.value"
-        :departments="page.departments"
-        :grade-options="page.gradeOptions"
-        :statuses="page.statuses"
-        @reset="page.resetSearch"
+        v-model="search"
+        :departments="departments"
+        :grade-options="gradeOptions"
+        :statuses="statuses"
+        @reset="resetSearch"
       />
     </template>
     <template #table>
       <SectionDataTable
-        v-model:current-page="page.currentPage.value"
-        :grade-label="page.formState.gradeLabel"
-        :headers="page.tableHeaders.value"
-        :items="page.students.value"
-        :items-per-page="page.itemsPerPage"
-        :page-count="page.pageCount.value"
-        :page-summary="page.pageSummary.value"
-        :row-props="page.formState.rowProps"
-        :status-color="page.formState.statusColor"
-        @delete="page.flow.requestDeleteConfirmation"
-        @edit="page.commands.openEditDialog"
-        @view="page.commands.openViewDialog"
+        v-model:current-page="currentPage"
+        :grade-label="formState.gradeLabel"
+        :headers="tableHeaders"
+        :items="students"
+        :items-per-page="itemsPerPage"
+        :page-count="pageCount"
+        :page-summary="pageSummary"
+        :row-props="formState.rowProps"
+        :status-color="formState.statusColor"
+        @delete="flow.requestDeleteConfirmation"
+        @edit="commands.openEditDialog"
+        @view="commands.openViewDialog"
       />
     </template>
   </PageMaintenance>
 
   <SectionFormPanel
-    v-bind="page.formPanelProps.value"
-    v-on="page.formPanelEvents"
+    v-bind="formPanelProps"
+    v-on="formPanelEvents"
   />
 
-  <v-snackbar v-model="page.snackbarVisible.value" color="success" location="bottom right" :timeout="2200">
+  <v-snackbar v-model="snackbarVisible" color="success" location="bottom right" :timeout="2200">
     儲存成功
   </v-snackbar>
 </template>