docs: reorganize component guide structure and indexes
Update documentation rules for GUIDE.md files to keep higher-level guides focused on constraints, conventions, and indexes. Add base and section component guides to the LLM development index, clarify component layering responsibilities, and fix architecture references from README to GUIDE.md.docs: reorganize component guide structure and indexes Update documentation rules for GUIDE.md files to keep higher-level guides focused on constraints, conventions, and indexes. Add base and section component guides to the LLM development index, clarify component layering responsibilities, and fix architecture references from README to GUIDE.md.
This commit is contained in:
+19
-11
@@ -1,25 +1,29 @@
|
||||
# Components Guide
|
||||
|
||||
`components` 放 Vue UI 元件。元件以 props 接收資料,以 emits 回報事件;不要直接處理 route、HTTP client、token/session 或全域流程。
|
||||
`src/components` 放 Vue UI 元件,包含 layout、page component、feature/domain component 與少量跨頁共用元件。
|
||||
|
||||
## 分層
|
||||
|
||||
- `pages/`:完整頁面組裝,檔名使用 `Page` 前綴。
|
||||
- `sections/`:頁面區塊容器,例如搜尋區、表格、dialog shell、panel。
|
||||
- `items/`:單筆資料、欄位群組或原子級呈現。
|
||||
- `layouts/`:app shell layout。詳見 `src/components/layouts/GUIDE.md`。
|
||||
- `base/`:真正跨頁共用且不屬於特定 domain 的基礎元件。
|
||||
- `login/`:登入頁專用 UI。
|
||||
- `maint/`:maintenance demo 舊有或領域型 UI 元件。
|
||||
| 目錄 | 說明 | 指南 |
|
||||
|------|------|------|
|
||||
| `pages/` | 完整頁面組裝,檔名使用 `Page` 前綴 | — |
|
||||
| `sections/` | 頁面區塊容器,例如搜尋區、表格、dialog shell、panel | `sections/GUIDE.md` |
|
||||
| `items/` | 單筆資料、欄位群組或原子級呈現 | `items/GUIDE.md` |
|
||||
| `layouts/` | App shell layout | `layouts/GUIDE.md` |
|
||||
| `base/` | 真正跨頁共用且不屬於特定 domain 的基礎元件 | `base/GUIDE.md` |
|
||||
| `login/` | 登入頁專用 UI | — |
|
||||
| `maint/` | maintenance demo 舊有或領域型 UI 元件 | — |
|
||||
|
||||
## 規則
|
||||
|
||||
- 不假設元件全域註冊;使用時明確 import。
|
||||
- route component 放在 `views`,不要放在 `components`。
|
||||
- 不要假設 `src/components` 會自動全域註冊元件;需要使用元件時,依照目前 Vue SFC 慣例明確 import。
|
||||
- 直接被 route 載入的檔案放在 `src/views`,不要放在 `src/components`。
|
||||
- 負責完整頁面主畫面組裝的元件使用 `Page` 前綴。
|
||||
- 只服務單一功能或 domain 的元件,放在對應資料夾,不要放進 `base`。
|
||||
- layout 元件只處理 app shell 與框架 UI,不放頁面專屬業務流程。
|
||||
- `pages` 可組合 sections/items,但不直接處理 API。
|
||||
- `sections` 決定布局與區塊互動,不知道 route。
|
||||
- `items` 不知道自己在表格、grid 或 dialog 中。
|
||||
- 只服務單一 domain 的元件放在 domain/feature 目錄,不放進 `base`。
|
||||
|
||||
## 命名
|
||||
|
||||
@@ -27,3 +31,7 @@
|
||||
- Section component:`SectionXxx.vue`
|
||||
- Item component:`ItemXxx.vue`
|
||||
- Layout component:依 shell/區塊命名,例如 `MainLayout.vue`
|
||||
|
||||
## 資料流
|
||||
|
||||
component 以 props 接收資料,以 emit 回報使用者事件。需要跨頁共享的狀態交給 `src/stores`;可重用流程或較複雜 UI state 放到 `src/composables`。
|
||||
|
||||
Reference in New Issue
Block a user