docs: reorganize architecture strategy documentation

Split current project diagnostics into a dedicated analysis document and
trim the main architecture strategy to focus on core guidance. This makes
the documentation easier to navigate and separates observed issues from
recommended architectural principles.docs: reorganize architecture strategy documentation

Split current project diagnostics into a dedicated analysis document and
trim the main architecture strategy to focus on core guidance. This makes
the documentation easier to navigate and separates observed issues from
recommended architectural principles.

docs/llm-development-guide.md

@@ -11,7 +11,8 @@
 1. `README.md`
 2. `src/README.md`
 3. `docs/add-page-example.md`
-4. `docs/frontend-layering.md`
+4. `docs/architecture-strategy.md`（新增功能與重構的最高準則）
+5. `docs/frontend-layering.md`（歷史參考，已被 `architecture-strategy.md` 取代）
 
 ## 預設不可修改的檔案
 
@@ -44,16 +45,22 @@
 目前主要資料流是：
 
 ```txt
-router -> App.vue -> layout -> view -> component -> composable/store -> service
+router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
+                                      ↓
+                         page driver / command composable -> store -> service
 ```
 
 判斷原則：
 
 - `router` 決定 route、layout meta、auth meta 與錯誤頁入口
-- `App.vue` 組裝 layout props、全域 UI 與 layout event
-- `views` 承接路由入口、頁面資料協調與頁面事件協調
-- `components` 承接畫面呈現、props/emits 與可拆分 UI 區塊
-- `composables` 承接可重用流程、頁面狀態機或較複雜的 UI state
+- `AppShell` 組裝 layout props、全域 UI 與 layout event
+- `views` 承接路由入口、頁面資料協調與頁面事件協調，應維持薄層
+- `components/pages` 組裝完整頁面與 page-level slot
+- `components/sections` 承接容器佈局，例如搜尋區、表格、dialog shell
+- `components/items` 承接單一資料單位或欄位群組呈現
+- `composables/page-drivers` 承接頁面資料協調與 page model 組裝
+- `composables/commands` 承接命令式副作用流程，例如 create/edit/save/delete
+- `composables` 其他子目錄承接可重用流程、頁面狀態機或較複雜的 UI state
 - `stores` 承接跨頁共享狀態、快取與全域顯示狀態
 - `services` 承接 HTTP client、API 模組、token、session 與錯誤處理
 
@@ -62,7 +69,8 @@ router -> App.vue -> layout -> view -> component -> composable/store -> service
 - 新 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/*`、`src/components/maint/*`、`src/composables/maint/*`
+- 維護頁：優先參考 `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/README.md`
 - API 呼叫：參考 `src/services/modules/*` 與使用它們的 store/composable
 - 全域提示：參考 `src/stores/snackbar.ts` 與 `src/composables/useApiCall.ts`
@@ -101,7 +109,12 @@ router -> App.vue -> layout -> view -> component -> composable/store -> service
 - `src/components/PageIndex.vue`
 - `src/views/maint/*`
 - `src/components/maint/*`
+- `src/components/pages/PageMaintenance.vue`
+- `src/components/sections/*`
+- `src/components/items/*`
 - `src/composables/maint/*`
+- `src/composables/page-drivers/*`
+- `src/composables/commands/*`
 - `src/components/PageMaint.vue`
 - `src/stores/students.ts`
 - `src/stores/semesters.ts`
@@ -202,7 +215,16 @@ router -> App.vue -> layout -> view -> component -> composable/store -> service
 - emit 使用者事件
 - 拆分表單、列表、工具列、dialog 等 UI
 
-不要把完整功能長期塞在單一 view。當畫面有多個區塊、表單、列表、dialog 或重複 UI 時，應拆到 feature components。
+不要把完整功能長期塞在單一 view。當畫面有多個區塊、表單、列表、dialog 或重複 UI 時，應拆到 page / section / item components。
+
+維護頁分層優先順序：
+
+1. `views/maint/*.vue`：只做 route-level wiring，目標 < 80 行。
+2. `components/pages/PageMaintenance.vue`：組裝維護頁外殼與主要 slot。
+3. `components/sections/*`：管理搜尋、表格、dialog shell 等區塊佈局。
+4. `components/items/*`：管理欄位群組或單一資料呈現，不直接呼叫 store/service。
+5. `composables/page-drivers/*`：集中 page model、分頁、搜尋、表單狀態與事件 wiring。
+6. `composables/commands/*`：集中新增、載入、儲存、刪除等 command 流程。
 
 ## Router 安排規則
 
@@ -231,11 +253,14 @@ route 集中放在 `src/router/routes.ts`。不要在 view 或 component 裡臨
 - `src/composables/useApiCall.ts`：包裝可重用 API 呼叫狀態與錯誤提示流程
 - `src/composables/layout/useAdminLayoutState.ts`：提供 layout shell 所需的狀態組裝
 - `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/commands/useCrudCommands.ts`：提供 CRUD command 流程，讓 view 不直接執行 store mutation 細節
 - `src/composables/maint/useMaintenanceCrudFlow.ts`：提供維護頁 CRUD 流程狀態
 - `src/composables/maint/useStudentMaintenanceForm.ts`：提供學生維護表單狀態
 - `src/composables/maint/useEditableStudentGrid.ts`：提供 editable grid 狀態
 
-新增 composable 時，用 `useXxx.ts` 命名。若只服務單一 feature，放在 `src/composables/<feature>`；若確定跨 feature 使用，才放在 `src/composables` 根目錄。
+新增 composable 時，用 `useXxx.ts` 命名。若是頁面資料協調，放在 `src/composables/page-drivers`；若是命令式副作用流程，放在 `src/composables/commands`；若只服務單一 feature，放在 `src/composables/<feature>`；若確定跨 feature 使用，才放在 `src/composables` 根目錄。
 
 ## Store 與 Service 資料流規則
 
@@ -289,7 +314,7 @@ import { mdiAccount } from '@mdi/js'
 - 是否只需要新增或修改 view
 - 是否需要新增 route
 - 是否需要拆 feature component
-- 是否已閱讀 `docs/frontend-layering.md`
+- 是否已閱讀 `docs/architecture-strategy.md`
 - 是否已參考 `src/` 裡相同類型的既有範例
 - 是否符合 Vue 3、Composition API、`<script setup lang="ts">` 的既有寫法