skytek/skt-vuetify-templates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: simplify page architecture and component guidance

Browse Source 
Update the src documentation to emphasize building pages from route views,
composables, sections, and items instead of a dedicated pages layer.

Clarify the recommended data flow and new feature workflow so template users
start from views and only introduce page-driver composables when coordination
logic becomes complex.docs: simplify page architecture and component guidance

Update the src documentation to emphasize building pages from route views,
composables, sections, and items instead of a dedicated pages layer.

Clarify the recommended data flow and new feature workflow so template users
start from views and only introduce page-driver composables when coordination
logic becomes complex.
This commit is contained in:
skytek_xinliang
2026-05-27 11:50:40 +08:00
parent ad00f5c195
commit 7b99087cbb
25 changed files with 2797 additions and 3174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/GUIDE.md
+12 -14
View File
@@ -1,19 +1,19 @@
# Src Guide
`src` 是 template 使用者主要修改的區域。新增功能時，先從 route view、page component 與 page driver 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。
`src` 是 template 使用者主要修改的區域。新增功能時，先從 route view 與 composable 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。
## 資料流
```txt
router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
↓
page driver / command composable -> store -> service
router -> AppShell -> layout -> view -> Section -> Item
↓
composable -> store -> service
```
## 主要目錄
- `views/`：route entry，維持薄層，只做 route wiring 與 page driver 掛載。詳見 `src/views/GUIDE.md`。
- `components/`：Vue UI 元件，依 pages / sections / items / layouts / base 分層。詳見 `src/components/GUIDE.md`。
- `components/`：Vue UI 元件，依 sections / items / layouts / base 分層。詳見 `src/components/GUIDE.md`。
- `composables/`：page driver、command flow、layout flow 與可重用狀態流程。詳見 `src/composables/GUIDE.md`。
- `router/`：route、layout meta、auth meta 與 guard。詳見 `src/router/GUIDE.md`。
- `shell/`：AppShell、tabs、global overlays。詳見 `src/shell/GUIDE.md`。
@@ -60,7 +60,6 @@ router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -
- `components/PageIndex.vue`
- `components/PageMaint.vue`
- `components/maint/*`
- `components/pages/*Maintenance.vue`
- `components/sections/*`
- `components/items/*`
- `composables/page-drivers/*MaintenancePage.ts`
@@ -74,14 +73,13 @@ router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -
## 新功能流程
1. 新增或修改 `views/*` route entry。
2. 若有完整頁面 UI，新增 `components/pages/PageXxx.vue`。
3. 若有複雜的資料協調（多 composable、搜尋狀態、CRUD flow、dialog 狀態），新增 `composables/page-drivers/useXxxPage.ts`。簡單頁面直接在 view 用 `computed` 組裝 page model。
4. 若畫面有獨立區塊，拆到 `components/sections/*`。
5. 若區塊內有欄位群組或單筆資料呈現，拆到 `components/items/*`。
6. 跨頁共享狀態才新增或修改 `stores/*`。
7. 外部 API 放在 `services/modules/*`。
8. 在 `router/routes.ts` 新增 route。
1. 新增或修改 `views/*` route entry，直接在 view 裡組裝 page model 與 UI。
2. 若有複雜的資料協調（多 composable、搜尋狀態、CRUD flow、dialog 狀態），新增 `composables/page-drivers/useXxxPage.ts`。簡單頁面直接在 view 用 `computed` 組裝。
3. 若畫面有獨立區塊，拆到 `components/sections/*`。
4. 若區塊內有欄位群組或單筆資料呈現，拆到 `components/items/*`。
5. 跨頁共享狀態才新增或修改 `stores/*`。
6. 外部 API 放在 `services/modules/*`。
7. 在 `router/routes.ts` 新增 route。
## 驗證