fix: docing

2026-05-22 11:17:32 +08:00
parent f3eb9782c6
commit 9e8cf28d77
4 changed files with 329 additions and 265 deletions
@@ -1,47 +1,65 @@
 ## 二、我們專案的現況診斷

-### 2.1 App.vue 過度臃腫（~590 行）
+本文件是 `docs/architecture-strategy.md` 第二章的現況快照。分層細節以 `docs/architecture-strategy.md` 與 `src/**/GUIDE.md` 為準。

-| 職責 | 行數 | 應屬層級 |
-|------|------|----------|
-| Layout 切換 | ~20 | App Shell |
-| Tabs 管理 | ~80 | Page Driver |
-| Breadcrumb 組裝 | ~40 | Layout |
-| Favorites 管理 | ~60 | Store |
-| Search Dialog | ~80 | App Shell / Widget |
-| Message Dialog | ~60 | App Shell / Widget |
-| Snackbar | ~10 | Global Overlay |
-| Logout / Force logout | ~30 | Auth Flow |
-| HTTP Toast | ~20 | Service Layer |
+### 2.1 App Shell 已拆分

- **問題**：App.vue 同時承擔 App Shell、Page Driver、Global Widget、Auth Flow 四種責任。
- **對比**：App Store 的 `App.svelte` 只有 161 行，只負責 `Navigation + PageResolver + Footer`。
+`App.vue` 目前只掛載 `src/shell/AppShell.vue`，不再承擔 layout props、tabs、搜尋 dialog、訊息 dialog 或 snackbar 的具體組裝。

-### 2.2 Views 過厚（SingleRecord.vue ~830 行）
+目前責任分布：

- 混雜：表格呈現、搜尋表單、dialog 模板、表單狀態、CRUD 流程、驗證邏輯、分頁、snackbar。
- **對比**：App Store 的 `ProductPage.svelte` 只有 77 行，只負責「把 page 轉成 DefaultPageRequirements + 一個 slot override」。
+| 職責 | 目前位置 |
+|------|----------|
+| 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.3 缺乏統一的頁面資料門面
+### 2.2 Views 已大幅變薄

-```
-現況：
-  view → store → service（直接鏈式呼叫）
-  view 自己管理 loading / error / dialog visible
+維護頁與一般頁面目前多數已轉為 route-level wiring：

-App Store：
-  UI → jet.dispatch(intent) → runtime → controller → page model
-  UI 只接收 page model，不管理載入狀態
+- `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
 ```

-### 2.4 Dialog 狀態與模板內嵌於 View
+- `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/*`：欄位群組或單筆資料呈現。

- `SingleRecord.vue` 內含 5 個 `ConfirmDialog` 實例 + 1 個大 form overlay。
- 任何 dialog 更動都需要修改 view 檔案。
+### 2.4 Dialog 與區塊拆分狀態

-### 2.5 沒有容器/內容分離的 Section 層
+維護頁的大型 dialog 與表單欄位已從 view 抽出：

- 表格、表單、搜尋區塊都是直接寫在 view 或 page component 中。
- 缺乏類似 `ShelfItemLayout` 的通用佈局抽象：「這一區是水平捲軸還是網格」應該由容器決定，裡面的內容元件不應該知道。
+- `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。