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.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
+24 -9
View File
@@ -1,32 +1,47 @@
# Views Guide
`views` 是 route entry。View 應維持薄層,負責掛載 page driver 與 page component,不承載大段 UI、dialog、表單欄位或 store mutation 細節
`views` 是 route entry。View 自含 page model 組裝與頁面 UI,若邏輯複雜才抽到 page driver composable
## 規則
- 使用 `<script setup lang="ts">`
- 直接 route component 放在 `src/views``src/views/<feature>`
- 一般 view 目標 < 80 行。
- route params/query 的解析可在 view 做簡單轉換;超過簡單轉換時放進 page driver。
- 不直接 import 或包住 `MainLayout.vue`
- 不直接定義大型 `<v-dialog>``<v-overlay>`、大型表格或大型表單
- 複雜 UI 拆到 `components/sections/*``components/items/*`
## 建議形狀
簡單頁面:直接在 view 組裝 page model 與 template。
```vue
<script setup lang="ts">
import PageReports from '@/components/pages/PageReports.vue'
import { useReportsPage } from '@/composables/page-drivers/useReportsPage'
const { pageModel } = useReportsPage()
import { computed } from 'vue'
const pageModel = computed(() => ({ title: '我的頁面' }))
</script>
<template>
<PageReports :page="pageModel" />
<v-card>{{ pageModel.title }}</v-card>
</template>
```
若頁面只是簡單的 `computed` 組裝(無搜尋、無 dialog、無複雜事件),直接在 view 寫 page model,不需要建立 page driver。以 destructure 方式取用 composable 回傳值,模板不寫 `.value`
複雜頁面:透過 page driver composable 協調多個資料來源
```vue
<script setup lang="ts">
import PageMaint from '@/components/PageMaint.vue'
import { useXxxPage } from '@/composables/page-drivers/useXxxPage'
const { pageModel, search, handleSave, ... } = useXxxPage()
</script>
<template>
<PageMaint :title="pageModel.title" @create="handleCreate">
<template #table>...</template>
</PageMaint>
</template>
```
以 destructure 方式取用 composable 回傳值,模板不寫 `.value`
## Login.vue 開關