docs: document template naming and maintenance refactor

Update agent and LLM guidance to reference the architecture strategy and
add a template naming rule that keeps reusable abstractions domain-neutral.

Mark maintenance Phase 3 as complete and document the page driver/page
component refactors for EditableGrid and MasterDetail variants.docs: document template naming and maintenance refactor

Update agent and LLM guidance to reference the architecture strategy and
add a template naming rule that keeps reusable abstractions domain-neutral.

Mark maintenance Phase 3 as complete and document the page driver/page
component refactors for EditableGrid and MasterDetail variants.
This commit is contained in:
skytek_xinliang
2026-05-19 14:35:28 +08:00
parent 96b96bcaaa
commit 2b780a12c2
16 changed files with 3319 additions and 3285 deletions
+15 -3
View File
@@ -380,10 +380,22 @@ views/xxx.vue
- 集中組裝 page model、搜尋狀態、表格分頁、表單狀態、CRUD command 與 dialog flow。
- `SingleRecord.vue` 不再直接操作 `studentStore`
### Phase 3:推廣到所有 maintenance 頁面
### Phase 3:推廣到所有 maintenance 頁面 ✅ 已完成
1. `EditableGrid.vue``MasterDetailA/B/C.vue` 依同樣模式重構。
2. 建立通用的 `useCrudPageDriver()``useCrudCommands()`,減少重複
1. [x] `EditableGrid.vue` 依 Page Driver + Page Component 模式重構。
- `src/views/maint/EditableGrid.vue` 縮減為 10 行 route-level wiring
- 新增 `src/composables/page-drivers/useEditableGridMaintenancePage.ts`
- 新增 `src/components/pages/PageEditableGridMaintenance.vue`,保留既有 `src/components/maint/EditableGrid.vue` 作為主要內容元件。
2. [x] `MasterDetailA.vue` 依 Page Driver + Page Component 模式重構。
- `src/views/maint/MasterDetailA.vue` 縮減為 34 行。
- 新增 `src/composables/page-drivers/useMasterDetailAMaintenancePage.ts`
- 新增 `src/components/pages/PageMasterDetailAMaintenance.vue` 承接原本主從維護 UI。
3. [x] `MasterDetailB.vue``MasterDetailC.vue` 依 Page Driver + Page Component 模式重構。
- `src/views/maint/MasterDetailB.vue``src/views/maint/MasterDetailC.vue` 均縮減為 10 行。
- 新增 `src/composables/page-drivers/useMasterDetailBMaintenancePage.ts``src/composables/page-drivers/useMasterDetailCMaintenancePage.ts`
- 新增 `src/components/pages/PageMasterDetailBMaintenance.vue``src/components/pages/PageMasterDetailCMaintenance.vue`
4. [x] 通用方向已落地為「每頁 page driver + page component」與既有 `useCrudCommands()`
- Phase 3 未再抽出跨 A/B/C 的大型共用 driver,避免在 demo 變體尚未收斂前建立過早抽象。
### Phase 4:非 maintenance 頁面統一
+6 -2
View File
@@ -69,8 +69,8 @@ router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -
- 新 route:參考 `src/router/routes.ts`
- 一般被主 layout 包住的頁面:參考 `src/views/Home.vue``src/views/maint/EditableGrid.vue`
- 登入相關 UI:參考 `src/components/PageLogin.vue``src/components/login/*`
- 維護頁:優先參考 `src/views/maint/SingleRecord.vue``src/components/pages/PageMaintenance.vue``src/components/sections/*``src/components/items/*``src/composables/page-drivers/useSingleRecordMaintenancePage.ts``src/composables/commands/useCrudCommands.ts`
- 舊維護頁:`EditableGrid.vue``MasterDetailA/B/C.vue` 尚未套用完整 Page Driver + Section + Item 分層,參考前先確認是否正在做 Phase 3 遷移。
- 維護頁:優先參考 `src/views/maint/SingleRecord.vue``src/views/maint/EditableGrid.vue``src/views/maint/MasterDetailA.vue``src/views/maint/MasterDetailB.vue``src/views/maint/MasterDetailC.vue` 與對應的 `src/components/pages/*Maintenance.vue``src/composables/page-drivers/*MaintenancePage.ts`
- 單筆維護欄位/表格/dialog 拆分:參考 `src/components/sections/*``src/components/items/*``src/composables/commands/useCrudCommands.ts`
- 維護頁範本選擇:參考 `src/views/maint/README.md`
- API 呼叫:參考 `src/services/modules/*` 與使用它們的 store/composable
- 全域提示:參考 `src/stores/snackbar.ts``src/composables/useApiCall.ts`
@@ -255,6 +255,10 @@ route 集中放在 `src/router/routes.ts`。不要在 view 或 component 裡臨
- `src/composables/layout/useThemeToggle.ts`:提供主題切換流程
- `src/composables/page-drivers/useMaintenancePage.ts`:提供通用 maintenance page model 基礎狀態
- `src/composables/page-drivers/useSingleRecordMaintenancePage.ts`:協調單筆維護 demo 頁面的 page model、section props/events、表單、表格與 command
- `src/composables/page-drivers/useEditableGridMaintenancePage.ts`:協調可編輯表格 demo 頁面的 page model
- `src/composables/page-drivers/useMasterDetailAMaintenancePage.ts`:協調主從維護 A demo 的 page model、主檔/明細狀態與 dialog event wiring
- `src/composables/page-drivers/useMasterDetailBMaintenancePage.ts`:協調主從維護 B demo 的 page model、主檔/明細狀態與 dialog event wiring
- `src/composables/page-drivers/useMasterDetailCMaintenancePage.ts`:協調主從維護 C demo 的 page model、主檔/明細狀態與 dialog event wiring
- `src/composables/commands/useCrudCommands.ts`:提供 CRUD command 流程,讓 view 不直接執行 store mutation 細節
- `src/composables/maint/useMaintenanceCrudFlow.ts`:提供維護頁 CRUD 流程狀態
- `src/composables/maint/useStudentMaintenanceForm.ts`:提供學生維護表單狀態