# Views Guide

`views` 是 route entry。View 自含 page model 組裝與頁面 UI，若邏輯複雜才抽到 page driver composable。

## 規則

- 使用 `<script setup lang="ts">`。
- 直接 route component 放在 `src/views` 或 `src/views/<feature>`。
- route params/query 的解析可在 view 做簡單轉換；超過簡單轉換時放進 page driver。
- 不直接 import 或包住 `MainLayout.vue`。
- 複雜 UI 拆到 `components/sections/*` 或 `components/items/*`。

## 建議形狀

簡單頁面：直接在 view 組裝 page model 與 template。

```vue
<script setup lang="ts">
import { computed } from 'vue'
const pageModel = computed(() => ({ title: '我的頁面' }))
</script>

<template>
  <v-card>{{ pageModel.title }}</v-card>
</template>
```

複雜頁面：透過 page driver composable 協調多個資料來源。

```vue
<script setup lang="ts">
import MaintShell from '@/components/maint/MaintShell.vue'
import { useXxxPage } from '@/composables/page-drivers/useXxxPage'
const { pageModel, search, handleSave, ... } = useXxxPage()
</script>

<template>
  <MaintShell :title="pageModel.title" @create="handleCreate">
    <template #table>...</template>
  </MaintShell>
</template>
```

以 destructure 方式取用 composable 回傳值，模板不寫 `.value`。

## Login.vue 開關

`Login.vue` 是登入頁的完整入口，登入頁功能開關集中在 view 內宣告，透過 composable 往下傳遞，不在子元件各自決定是否啟用。

- `withCaptcha`：控制驗證碼 UI、captcha API 載入/刷新，以及登入 payload 是否帶 captcha 資料。關閉時不應發出 captcha API，也不應檢查或送出 captcha 欄位。
- `withAnnouncement`：控制公告 UI、公告 mock data/composable 資料流與公告詳情互動。關閉時公告板、手機公告列與公告對話框資料來源都應停用。
- `withForgotPassword`：控制忘記密碼連結與事件。關閉時 UI 不顯示，也不應觸發忘記密碼事件。
- `withRememberAccount`：控制記住帳號 UI 與 localStorage 讀寫。關閉時不顯示 checkbox、不讀寫記住帳號 storage，送出資料固定視為未記住帳號。

新增登入頁選配功能時，優先維持同樣模式：view 宣告開關、composable 負責資料流與 side effect、form component 只依 props 呈現 UI 與發出事件。

## 子目錄

- `views/demos` 是一般頁面與 section 使用方式的 demo route entry，仍需維持薄 view。
- `views/maint` 是 maintenance demo route entry。詳見 `src/views/maint/GUIDE.md`。
- `views/errors` 是錯誤頁入口，通常使用 `meta.layout = 'none'`。每個錯誤頁（`Forbidden.vue`、`ServerError.vue`、`NotFound.vue` 等）只傳入 props 給共用的 `ErrorShell.vue`，不再各自重複佈局邏輯。`ErrorShell.vue` 提供標題、圖示、顏色、描述、後端訊息、操作按鈕（返回上頁 / 回首頁 / 前往登入）等 slots。