From f61432ad8a8a7775c0bc46d16f861bae27dbf53e Mon Sep 17 00:00:00 2001
From: skytek_xinliang <carl@skytek.com.tw>
Date: Mon, 1 Jun 2026 14:44:39 +0800
Subject: [PATCH] fixing adn docing

---
 src/GUIDE.md                                     |  4 ++--
 src/README.md                                    |  2 +-
 src/components/GUIDE.md                          |  2 +-
 src/components/{ => maint}/MaintShell.vue        |  0
 src/components/sections/SectionFormPage.vue      |  3 ---
 src/components/sections/SectionQueryPage.vue     |  8 +-------
 src/composables/GUIDE.md                         | 16 +++++-----------
 .../useSingleRecordMaintenancePage.ts            |  2 +-
 .../{commands => }/useCrudCommands.ts            |  0
 src/views/GUIDE.md                               |  2 +-
 src/views/demos/SectionFormPageDemo.vue          | 10 +++++++---
 src/views/demos/SectionQueryPageDemo.vue         |  7 +------
 src/views/maint/GUIDE.md                         |  2 +-
 src/views/maint/MasterDetailA.vue                |  2 +-
 src/views/maint/MasterDetailB.vue                |  2 +-
 src/views/maint/MasterDetailC.vue                |  2 +-
 src/views/maint/SingleRecord.vue                 |  2 +-
 17 files changed, 25 insertions(+), 41 deletions(-)
 rename src/components/{ => maint}/MaintShell.vue (100%)
 rename src/composables/{commands => }/useCrudCommands.ts (100%)

diff --git a/src/GUIDE.md b/src/GUIDE.md
index 8cb86a6..d969aea 100644
--- a/src/GUIDE.md
+++ b/src/GUIDE.md
@@ -57,13 +57,13 @@ router -> AppShell -> layout -> view -> Section -> Item
 - `views/FncPage.vue`
 - `views/Settings.vue`
 - `views/maint/*`
-- `components/MaintShell.vue`
+- `components/maint/MaintShell.vue`
 - `components/maint/*`
 - `components/sections/*`
 - `components/items/*`
 - `composables/page-drivers/*MaintenancePage.ts`
 - `composables/maint/*`
-- `composables/commands/*`
+- `composables/useCrudCommands.ts`
 - `stores/students.ts`
 - `stores/semesters.ts`
 - demo assets 與 demo language keys
diff --git a/src/README.md b/src/README.md
index 931eed2..d5f74ab 100644
--- a/src/README.md
+++ b/src/README.md
@@ -97,7 +97,7 @@ Layout composables：
 - `src/views/maint/*`
 - `src/components/maint/*`
 - `src/composables/maint/*`
-- `src/components/MaintShell.vue`
+- `src/components/maint/MaintShell.vue`
 - `src/stores/students.ts`
 - `src/stores/semesters.ts`
 - `src/views/FncPage.vue`
diff --git a/src/components/GUIDE.md b/src/components/GUIDE.md
index b4ad7ec..2f831ac 100644
--- a/src/components/GUIDE.md
+++ b/src/components/GUIDE.md
@@ -9,7 +9,7 @@
 - `layouts/`：App Shell 層的 layout 元件。詳見 `src/components/layouts/GUIDE.md`。
 - `base/`：真正跨頁共用的基礎元件。詳見 `src/components/base/GUIDE.md`。
 
-`MaintShell.vue` 是 maintenance 頁面的通用外殼元件，放在 `src/components/` 頂層。
+`MaintShell.vue` 是 maintenance 頁面的通用外殼元件，放在 `src/components/maint/`。
 
 ## 規則
 
diff --git a/src/components/MaintShell.vue b/src/components/maint/MaintShell.vue
similarity index 100%
rename from src/components/MaintShell.vue
rename to src/components/maint/MaintShell.vue
diff --git a/src/components/sections/SectionFormPage.vue b/src/components/sections/SectionFormPage.vue
index 173d779..4a33eac 100644
--- a/src/components/sections/SectionFormPage.vue
+++ b/src/components/sections/SectionFormPage.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 interface Props {
   title: string
-  backLabel?: string
   error?: string
   loading?: boolean
   message?: string
@@ -10,7 +9,6 @@ interface Props {
 }
 
 withDefaults(defineProps<Props>(), {
-  backLabel: '返回',
   resetLabel: '清除',
   submitLabel: '存檔',
 })
@@ -50,7 +48,6 @@ const emit = defineEmits<{
             {{ submitLabel }}
           </v-btn>
           <v-btn type="button" variant="tonal" @click="emit('reset')">{{ resetLabel }}</v-btn>
-          <v-btn type="button" variant="text" @click="emit('back')">{{ backLabel }}</v-btn>
         </v-row>
       </v-card>
     </v-container>
diff --git a/src/components/sections/SectionQueryPage.vue b/src/components/sections/SectionQueryPage.vue
index ee39688..ba225e7 100644
--- a/src/components/sections/SectionQueryPage.vue
+++ b/src/components/sections/SectionQueryPage.vue
@@ -6,9 +6,7 @@ interface Props {
   loading?: boolean
 }
 
-withDefaults(defineProps<Props>(), {
-  backLabel: '返回',
-})
+withDefaults(defineProps<Props>(), {})
 
 const emit = defineEmits<{
   search: []
@@ -38,9 +36,5 @@ const emit = defineEmits<{
     </v-card>
 
     <slot name="sections" />
-
-    <v-row class="pa-4">
-      <v-btn variant="tonal" @click="emit('back')">{{ backLabel }}</v-btn>
-    </v-row>
   </v-container>
 </template>
diff --git a/src/composables/GUIDE.md b/src/composables/GUIDE.md
index 1aaa458..76d8f28 100644
--- a/src/composables/GUIDE.md
+++ b/src/composables/GUIDE.md
@@ -4,12 +4,13 @@
 
 ## 子目錄
 
-- `page-drivers/`：頁面資料協調與 page model 組裝。
-- `commands/`：命令式副作用流程，例如 create/edit/save/delete。
-- `layout/`：AppShell / layout 狀態與事件協調。
+- `page-drivers/`：頁面資料協調與 page model 組裝（僅複雜頁面使用）。
 - `maint/`：maintenance demo 的表單、CRUD、editable grid 狀態。
+- `layout/`：AppShell / layout 狀態與事件協調。
 
-頂層也可放通用 composable，例如 `useApiCall.ts`：封裝 loading / data / error / execute 模式、自動 snackbar 錯誤提示與取消請求過濾。適合為單一 API 呼叫提供輕量狀態管理，但不替代 page driver 或 command composable。
+頂層放通用 composable：
+- `useApiCall.ts`：封裝 loading / data / error / execute 模式。
+- `useCrudCommands.ts`：通用 CRUD 狀態機（新增 / 編輯 / 檢視 / 儲存 / highlight）。
 
 ## 新增規則
 
@@ -40,11 +41,4 @@ const { pageModel, search, handleSubmit } = useXxxPage()
 ```
 模板中直接使用，不寫 `.value`：`:page="pageModel"`、`v-model="search"`。
 
-## Commands
-
-Command composable 負責副作用流程，不負責畫面布局：
-
-- 新增 / 編輯 / 刪除 / 儲存
-- 儲存前確認
-- 成功後重新載入或 highlight
 - 與 store/service 的 mutation 流程
diff --git a/src/composables/page-drivers/useSingleRecordMaintenancePage.ts b/src/composables/page-drivers/useSingleRecordMaintenancePage.ts
index 404b3aa..8914b36 100644
--- a/src/composables/page-drivers/useSingleRecordMaintenancePage.ts
+++ b/src/composables/page-drivers/useSingleRecordMaintenancePage.ts
@@ -1,6 +1,6 @@
 import { computed, ref, watch } from 'vue'
 import { useDisplay } from 'vuetify'
-import { useCrudCommands } from '@/composables/commands/useCrudCommands'
+import { useCrudCommands } from '@/composables/useCrudCommands'
 import { useMaintenanceCrudFlow } from '@/composables/maint/useMaintenanceCrudFlow'
 import {
   type StudentFormState,
diff --git a/src/composables/commands/useCrudCommands.ts b/src/composables/useCrudCommands.ts
similarity index 100%
rename from src/composables/commands/useCrudCommands.ts
rename to src/composables/useCrudCommands.ts
diff --git a/src/views/GUIDE.md b/src/views/GUIDE.md
index 93578c5..58a8fd1 100644
--- a/src/views/GUIDE.md
+++ b/src/views/GUIDE.md
@@ -29,7 +29,7 @@ const pageModel = computed(() => ({ title: '我的頁面' }))
 
 ```vue
 <script setup lang="ts">
-import MaintShell from '@/components/MaintShell.vue'
+import MaintShell from '@/components/maint/MaintShell.vue'
 import { useXxxPage } from '@/composables/page-drivers/useXxxPage'
 const { pageModel, search, handleSave, ... } = useXxxPage()
 </script>
diff --git a/src/views/demos/SectionFormPageDemo.vue b/src/views/demos/SectionFormPageDemo.vue
index 84bc5d8..ead87e1 100644
--- a/src/views/demos/SectionFormPageDemo.vue
+++ b/src/views/demos/SectionFormPageDemo.vue
@@ -4,12 +4,12 @@ import BaseFormTextField from '@/components/base/BaseFormTextField.vue'
 import SectionFormPage from '@/components/sections/SectionFormPage.vue'
 import { useSectionsDemoPage } from '@/composables/page-drivers/useSectionsDemoPage'
 
-const { demoForm, handleFormBack, handleFormSubmit, pageModel, resetDemoForm } = useSectionsDemoPage()
+const { demoForm, handleFormBack, handleFormSubmit, pageModel, resetDemoForm } =
+  useSectionsDemoPage()
 </script>
 
 <template>
   <SectionFormPage
-    back-label="回到列表"
     reset-label="清除"
     submit-label="送出"
     :message="pageModel.formMessage"
@@ -27,7 +27,11 @@ const { demoForm, handleFormBack, handleFormSubmit, pageModel, resetDemoForm } =
           <BaseFormSelect v-model="demoForm.owner" label="單位" :items="pageModel.ownerOptions" />
         </v-col>
         <v-col cols="12" md="3">
-          <BaseFormSelect v-model="demoForm.category" label="類型" :items="pageModel.categoryOptions" />
+          <BaseFormSelect
+            v-model="demoForm.category"
+            label="類型"
+            :items="pageModel.categoryOptions"
+          />
         </v-col>
         <v-col cols="12">
           <BaseFormTextField v-model="demoForm.description" label="說明" />
diff --git a/src/views/demos/SectionQueryPageDemo.vue b/src/views/demos/SectionQueryPageDemo.vue
index 5b271fe..43428d7 100644
--- a/src/views/demos/SectionQueryPageDemo.vue
+++ b/src/views/demos/SectionQueryPageDemo.vue
@@ -8,12 +8,7 @@ const { handleQueryBack, handleQuerySearch, pageModel, queryFilters } = useSecti
 </script>
 
 <template>
-  <SectionQueryPage
-    back-label="回到列表"
-    title="查詢頁DEMO"
-    @back="handleQueryBack"
-    @search="handleQuerySearch"
-  >
+  <SectionQueryPage title="查詢頁DEMO" @back="handleQueryBack" @search="handleQuerySearch">
     <template #filters>
       <v-col cols="12" md="4">
         <BaseFormTextField v-model="queryFilters.keyword" label="關鍵字" />
diff --git a/src/views/maint/GUIDE.md b/src/views/maint/GUIDE.md
index 768c8e6..a10f590 100644
--- a/src/views/maint/GUIDE.md
+++ b/src/views/maint/GUIDE.md
@@ -1,6 +1,6 @@
 # Maintenance Views Guide
 
-`views/maint` 是維護頁 demo。所有檔案都是自含的 route entry，UI 與流程直接在 view 中組合 `MaintShell`、`components/sections`、`components/items` 與 composable。
+`views/maint` 是維護頁 demo。所有檔案都是自含的 route entry，UI 與流程直接在 view 中組合 `components/maint/MaintShell`、`components/sections`、`components/items` 與 composable。
 
 ## 目前範本
 
diff --git a/src/views/maint/MasterDetailA.vue b/src/views/maint/MasterDetailA.vue
index 4b06601..e47cb25 100644
--- a/src/views/maint/MasterDetailA.vue
+++ b/src/views/maint/MasterDetailA.vue
@@ -5,7 +5,7 @@ import DetailSidePanel from '@/components/maint/master-detail/DetailSidePanel.vu
 import MasterFileFormFields from '@/components/maint/MasterFileFormFields.vue'
 import MntDialogCard from '@/components/maint/MntDialogCard.vue'
 import MntRecordNavToolbar from '@/components/maint/MntRecordNavToolbar.vue'
-import MaintShell from '@/components/MaintShell.vue'
+import MaintShell from '@/components/maint/MaintShell.vue'
 import SectionDataTable from '@/components/sections/SectionDataTable.vue'
 import SectionSearchPanel from '@/components/sections/SectionSearchPanel.vue'
 import { useMasterDetailAMaintenancePage } from '@/composables/page-drivers/useMasterDetailAMaintenancePage'
diff --git a/src/views/maint/MasterDetailB.vue b/src/views/maint/MasterDetailB.vue
index ae8ecc1..48e7eb6 100644
--- a/src/views/maint/MasterDetailB.vue
+++ b/src/views/maint/MasterDetailB.vue
@@ -511,7 +511,7 @@ import DetailFullHeightPanel from '@/components/maint/master-detail/DetailFullHe
 import MasterFileFormFields from '@/components/maint/MasterFileFormFields.vue'
 import MntDialogCard from '@/components/maint/MntDialogCard.vue'
 import MntRecordNavToolbar from '@/components/maint/MntRecordNavToolbar.vue'
-import MaintShell from '@/components/MaintShell.vue'
+import MaintShell from '@/components/maint/MaintShell.vue'
 import { useMaintenanceCrudFlow } from '@/composables/maint/useMaintenanceCrudFlow'
 import { useStudentMaintenanceForm } from '@/composables/maint/useStudentMaintenanceForm'
 import { type CourseRecord, type SemesterRecord, useSemesterStore } from '@/stores/semesters'
diff --git a/src/views/maint/MasterDetailC.vue b/src/views/maint/MasterDetailC.vue
index 4abd33d..59123f4 100644
--- a/src/views/maint/MasterDetailC.vue
+++ b/src/views/maint/MasterDetailC.vue
@@ -498,7 +498,7 @@ import DetailSimpleList from '@/components/maint/master-detail/DetailSimpleList.
 import MasterFileFormFields from '@/components/maint/MasterFileFormFields.vue'
 import MntDialogCard from '@/components/maint/MntDialogCard.vue'
 import MntRecordNavToolbar from '@/components/maint/MntRecordNavToolbar.vue'
-import MaintShell from '@/components/MaintShell.vue'
+import MaintShell from '@/components/maint/MaintShell.vue'
 import { useMaintenanceCrudFlow } from '@/composables/maint/useMaintenanceCrudFlow'
 import { useStudentMaintenanceForm } from '@/composables/maint/useStudentMaintenanceForm'
 import { type CourseRecord, type SemesterRecord, useSemesterStore } from '@/stores/semesters'
diff --git a/src/views/maint/SingleRecord.vue b/src/views/maint/SingleRecord.vue
index d3311a7..63e9ce6 100644
--- a/src/views/maint/SingleRecord.vue
+++ b/src/views/maint/SingleRecord.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import MaintShell from '@/components/MaintShell.vue'
+import MaintShell from '@/components/maint/MaintShell.vue'
 import SectionDataTable from '@/components/sections/SectionDataTable.vue'
 import SectionFormPanel from '@/components/sections/SectionFormPanel.vue'
 import SectionSearchPanel from '@/components/sections/SectionSearchPanel.vue'