From ad00f5c19573cbbee598b7085d949c595f50a2af Mon Sep 17 00:00:00 2001 From: skytek_xinliang Date: Wed, 27 May 2026 11:18:19 +0800 Subject: [PATCH] docs: clarify optional page drivers in page guide Update documentation to show that simple pages can define page models directly in views without creating a page driver. Adjust examples, section numbering, and naming guidance to better distinguish simple view state from reusable page-driver patterns.docs: clarify optional page drivers in page guide Update documentation to show that simple pages can define page models directly in views without creating a page driver. Adjust examples, section numbering, and naming guidance to better distinguish simple view state from reusable page-driver patterns. --- AGENTS.md | 2 +- docs/add-page-example.md | 82 +++++++++++++---------------------- docs/analyse-now.md | 65 --------------------------- docs/architecture-strategy.md | 51 ++++++++++------------ docs/what-apple-do.md | 81 ---------------------------------- src/GUIDE.md | 2 +- src/models/GUIDE.md | 2 +- src/views/GUIDE.md | 6 ++- 8 files changed, 59 insertions(+), 232 deletions(-) delete mode 100644 docs/analyse-now.md delete mode 100644 docs/what-apple-do.md diff --git a/AGENTS.md b/AGENTS.md index 09a228c..b6fce1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ - `src/services/modules/.ts` — service modules - Examples of correct vs. incorrect naming: - ❌ `PageStudentMaintenance.vue` → ✅ `PageMaintenance.vue` - - ❌ `useStudentMaintenancePage.ts` → ✅ `useMaintenancePage.ts` + - ❌ `useStudentMaintenancePage.ts` → ✅ `useSingleRecordMaintenancePage.ts` - ❌ `ItemStudentRow.vue` → ✅ `ItemDataRow.vue` - ❌ `useStudentCrudCommands.ts` → ✅ `useCrudCommands.ts` - ✅ `models/student.ts`, `stores/students.ts` — domain layer, specific names are correct diff --git a/docs/add-page-example.md b/docs/add-page-example.md index 58cf1d4..fcd9a95 100644 --- a/docs/add-page-example.md +++ b/docs/add-page-example.md @@ -7,18 +7,22 @@ 目前新增一般頁面的預設資料流： ```txt -router -> view -> page driver -> page component -> sections/items +router -> view -> (page driver) -> page component -> sections/items ↓ - store/composable -> service + store/composable -> service ``` -## 1. 新增 page driver +Page driver 不是必備層：若頁面邏輯只有簡單的 `computed` page model（無搜尋、無 dialog、無複雜事件協調），直接在 view 裡寫即可，不需要建立 page driver。 -頁面資料、事件與暫時 UI state 優先放在 page driver，view 只負責掛載。 +## 1. 新增 view（含 page model） -```ts -// src/composables/page-drivers/useReportsPage.ts +簡單頁面的 page model 直接在 view 裡用 `computed` 組裝，不需要額外建立 page driver。 + +```vue + + + + ``` -若資料來自 API，page driver 可呼叫 store 或 composable；底層 HTTP 細節仍放在 `services/modules/*`。 +若頁面需要協調多個 composable（搜尋、表單、CRUD flow、dialog 狀態），才建立 page driver。page driver 的慣例見 `src/composables/GUIDE.md`。 ## 2. 新增 page component @@ -66,10 +62,10 @@ export function useReportsPage() { ```vue - - -``` - -## 4. 加入 route +## 3. 加入 route route 加在 `src/router/routes.ts` 的 `routes` 陣列中，並放在 `/:pathMatch(.*)*` catch-all route 前面。 @@ -147,7 +125,7 @@ route 加在 `src/router/routes.ts` 的 `routes` 陣列中，並放在 `/:pathMa - 新功能若使用後端選單，優先調整後端選單資料或對應 API mock，不要把頁面專屬選單邏輯塞進 layout。 - 若只是新增 route，通常不需要修改 `MainLayout.vue` 或 `src/shell/*`。 -## 5. 需要 API 時新增 service module +## 4. 需要 API 時新增 service module ```ts // src/services/modules/reports.ts @@ -170,7 +148,7 @@ service 只封裝 HTTP 細節，不持有 UI 狀態。 `httpClient` 的 `baseURL` 來自 `VITE_API_BASE_URL`，沒有設定時預設 `/service/api`。開發模式下，Vite proxy 會將 `/service/*` 轉送到 `VITE_PROXY_TARGET`。 -## 6. 需要共享狀態時新增 store +## 5. 需要共享狀態時新增 store 只有跨頁共享、需要快取、或全域狀態才新增 store。單頁暫時狀態留在 view、component 或 composable。 @@ -202,7 +180,7 @@ export const useReportsStore = defineStore('reports', () => { }) ``` -## 7. 驗證 +## 6. 驗證 至少執行： diff --git a/docs/analyse-now.md b/docs/analyse-now.md deleted file mode 100644 index 2310a07..0000000 --- a/docs/analyse-now.md +++ /dev/null @@ -1,65 +0,0 @@ -## 二、我們專案的現況診斷 - -本文件是 `docs/architecture-strategy.md` 第二章的現況快照。分層細節以 `docs/architecture-strategy.md` 與 `src/**/GUIDE.md` 為準。 - -### 2.1 App Shell 已拆分 - -`App.vue` 目前只掛載 `src/shell/AppShell.vue`，不再承擔 layout props、tabs、搜尋 dialog、訊息 dialog 或 snackbar 的具體組裝。 - -目前責任分布： - -| 職責 | 目前位置 | -|------|----------| -| Layout 切換 | `src/shell/AppShell.vue` | -| Tabs / keep-alive router-view | `src/shell/AppTabs.vue` | -| Breadcrumb / favorites / menu wiring | `src/composables/layout/useAppShell.ts` + `AppShell.vue` | -| Search Dialog / Message Dialog / Snackbar | `src/shell/GlobalOverlays.vue` | -| Logout / force logout | `src/composables/layout/useAppShell.ts` | -| HTTP Toast | `src/services/http-toast.ts` + `GlobalOverlays.vue` | - -### 2.2 Views 已大幅變薄 - -維護頁與一般頁面目前多數已轉為 route-level wiring： - -- `Home.vue`：呼叫 `useHomePage()`，掛載 `PageHome`。 -- `Settings.vue`：呼叫 `useSettingsPage()`，掛載 `PageSettings`。 -- `FncPage.vue`：呼叫 `useFunctionPage()`，掛載 `PageFunction`。 -- `views/maint/*`：呼叫對應 page driver，掛載 `components/pages/*Maintenance.vue`。 - -`SingleRecord.vue` 已不再直接管理 store mutation、大型 dialog 模板、表格分頁與 CRUD 細節；這些流程已移到 page driver、section component、item component 與 command composable。 - -`Login.vue` 是 template core 例外，仍負責登入頁組合、功能開關、小型提示 dialog 與登入流程協調。登入頁的 captcha、announcement、忘記密碼與記住帳號流程已透過 composable / props / emits 拆分，後續調整應維持該模式。 - -### 2.3 Page Driver / Command / Page Component 已落地 - -目前已存在的主要分層： - -```txt -view -> page driver -> page component -> section/item - ↓ - command/store/service -``` - -- `src/composables/page-drivers/*`：組裝 page model、route/query 轉換與頁面事件。 -- `src/composables/commands/useCrudCommands.ts`：承接維護頁 CRUD 命令流程。 -- `src/components/pages/*`：完整頁面的主畫面組裝。 -- `src/components/sections/*`：搜尋區、表格區、表單 dialog/panel、表單/查詢頁外殼。 -- `src/components/items/*`：欄位群組或單筆資料呈現。 - -### 2.4 Dialog 與區塊拆分狀態 - -維護頁的大型 dialog 與表單欄位已從 view 抽出： - -- `SectionFormPanel.vue`：維護頁表單 overlay/dialog shell。 -- `MntDialogCard.vue`、`MntRecordNavToolbar.vue`：維護頁 dialog 內部骨架。 -- `ItemFormFieldGroup.vue`：表單欄位群組。 - -新增頁面時，若只是小型提示 dialog 且只屬於單一路由，可先留在 page driver / page component。若 dialog 包含大型表單、確認流程或可重用骨架，優先抽到 section 或 feature component。 - -### 2.5 仍需注意的邊界 - -- `src/models/page.ts` 目前主要服務 maintenance page model；部分頁面仍在各自 page driver 內定義局部 page model 型別。 -- `components/maint/*` 與 maintenance page components 屬於 demo / maintenance 領域，不應直接升格為全域 base 元件。 -- `src/components/base` 目前只放跨頁共用基礎元件，例如 `DraggableDialog`、`BaseFormTextField`、`BaseFormSelect`。 -- `src/stores/app.ts` 仍是 Pinia scaffold，尚未承擔實際 app state。 -- 一般功能需求不應修改 `App.vue`、`src/shell/*`、layout、router guard 或 HTTP core，除非需求明確牽涉這些 template core。 diff --git a/docs/architecture-strategy.md b/docs/architecture-strategy.md index 9159571..42fbc28 100644 --- a/docs/architecture-strategy.md +++ b/docs/architecture-strategy.md @@ -67,23 +67,15 @@ Read only when needed: [analyse now](./analyse-now.md) 範例： ```ts -// src/composables/usePageDriver.ts -export function useMaintenancePage() { - const studentStore = useStudentStore() - const { records, loading, error, load } = useCrudDriver({ - store: studentStore, - loadAction: () => studentStore.fetchStudents(), - }) - - const pageModel = computed(() => ({ - title: '單筆資料維護', - records: records.value, - loading: loading.value, - error: error.value, - })) - - return { pageModel, load } -} +// views/maint/Example.vue — 簡單頁面直接在 view 組裝 page model +const studentStore = useStudentStore() +const pageModel = computed(() => ({ + type: 'maintenance', + title: '單筆資料維護', + records: studentStore.students, + loading: false, + error: null, +})) ``` ### 3.3 查詢（Query）與命令（Command）分離 @@ -164,8 +156,8 @@ src/ │ └── DraggableDialog.vue │ ├── composables/ -│ ├── page-drivers/ ← 新增：頁面資料協調 -│ │ └── useMaintenancePage.ts +│ ├── page-drivers/ ← 新增：頁面資料協調（僅複雜頁面需要） +│ │ └── useSingleRecordMaintenancePage.ts │ ├── commands/ ← 新增：命令流程（對齊 Jet Action） │ │ └── useCrudCommands.ts │ ├── forms/ ← 維持/重組：表單狀態機 @@ -201,14 +193,10 @@ src/ ```vue