linx6g/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/components/GUIDE.md
+12 -46
View File
@@ -1,55 +1,21 @@
# Src Guide
# Components Guide
`src` 是 template 使用者主要修改的區域。新增功能時，先從 route view、page component 與 page driver 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。
`components` 放 Vue UI 元件，依 sections / items / layouts / base 分層。頁面不再有獨立的 page component 層 — 頁面 UI 直接寫在 `views/*` 中。
Template Core 與 Demo/Example 的完整清單見 `src/README.md`。
## 子目錄
## 資料流
- `sections/`：獨立畫面區塊（搜尋面板、資料表格、表單面板），決定佈局，不關心單筆內容。詳見 `src/components/sections/GUIDE.md`。
- `items/`：單一資料單位的純粹呈現，不管理狀態。詳見 `src/components/items/GUIDE.md`。
- `layouts/`：App Shell 層的 layout 元件。詳見 `src/components/layouts/GUIDE.md`。
- `base/`：真正跨頁共用的基礎元件。詳見 `src/components/base/GUIDE.md`。
```txt
router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
↓
page driver / command composable -> store -> service
```
`PageMaint.vue` 是 maintenance 頁面的通用外殼元件，放在 `src/components/` 頂層。
## 主要目錄
## 規則
- `views/`：route entry，維持薄層，只做 route wiring 與 page driver 掛載。詳見 `src/views/GUIDE.md`。
- `components/`：Vue UI 元件，依 pages / 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`。
- `stores/`：跨頁共享狀態與快取。詳見 `src/stores/GUIDE.md`。
- `services/`：HTTP client、API module、token/session、錯誤處理。詳見 `src/services/GUIDE.md`。
- `language/`：Vue I18n 文案。詳見 `src/language/GUIDE.md`。
## 依 pageKind 選擇起點
`.spec.json` 中 `maintenanceContract.pageKind` 決定使用哪一種 demo 架構。完整欄位對照見 `docs/llm-development-guide.md` 的「`.spec.json` 對照指南」。
| pageKind | 參考 Demo | 讀取 GUIDE |
| ------------- | ------------------------------------------ | -------------------------------------------------------- |
| `query` | `src/views/demos/SectionQueryPageDemo.vue` | `src/components/sections/GUIDE.md`（SectionQueryPage） |
| `application` | `src/views/demos/SectionFormPageDemo.vue` | `src/components/sections/GUIDE.md`（SectionFormPage） |
| `maintenance` | `src/views/maint/*` | `src/views/maint/README.md` + `src/views/maint/GUIDE.md` |
| `auth` | `src/views/Login.vue` | `src/views/GUIDE.md` |
| `print` | query 或 application demo | 同 query / application |
| `chooser` | 不適用 demo | 轉為 route group 或 tab |
## 新功能流程
1. 依 `pageKind` 選擇最接近的 demo。
2. 在 `src/views/<domain>/` 新增 route view（薄層，只掛 page driver）。
3. 在 `src/composables/page-drivers/` 新增 page driver composable。
4. 在 `src/components/pages/` 新增 page component。
5. 若畫面有獨立區塊，拆到 `src/components/sections/*`。
6. 若區塊內有欄位群組，拆到 `src/components/items/*`。
7. 在 `src/services/modules/` 新增 API module。
8. 在 `src/models/` 定義 page model 與 domain model 型別。
9. 在 `src/router/routes.ts` 新增 route。
10. 在 `src/language/` 新增語系文案。
跨頁共享狀態才新增或修改 `src/stores/*`。
- 元件不直接 import store 或 service。
- 元件以 props 接收資料，以 emits 回報使用者意圖。
- 可複用元件不含 domain 名稱（如 `student`、`course`）。
## 驗證