# Src Guide

`src` 是 template 使用者主要修改的區域。新增功能時，先從 route view 與 composable 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。

## 資料流

```txt
router -> AppShell -> layout -> view -> Section -> Item
                          ↓
             composable -> store -> service
```

## 主要目錄

- `views/`：route entry，維持薄層，只做 route wiring 與 page driver 掛載。詳見 `src/views/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`。
- `stores/`：跨頁共享狀態與快取。詳見 `src/stores/GUIDE.md`。
- `services/`：HTTP client、API module、token/session、錯誤處理。詳見 `src/services/GUIDE.md`。
- `language/`：Vue I18n 文案。詳見 `src/language/GUIDE.md`。

## Template Core

一般功能需求預設不修改：

- `main.ts`
- `App.vue`
- `shell/*`
- `components/layouts/*`
- `views/Login.vue`
- `router/index.ts`
- `router/guards.ts`
- `plugins/*`
- `styles/*`
- `services/client.ts`
- `services/interceptors.ts`
- `services/token.ts`
- `services/session.ts`
- `stores/auth.ts`
- `stores/menu.ts`
- `stores/breadcrumbs.ts`
- `stores/favorites.ts`
- `stores/messages.ts`
- `stores/snackbar.ts`
- `stores/app.ts`
- `composables/layout/*`

只有需求明確要求調整 template shell、登入、router guard、HTTP core 或全域狀態時才修改上述檔案。

## Demo / Example

下列檔案偏向示範功能，正式專案可依需求替換或移除：

- `views/Home.vue`
- `views/FncPage.vue`
- `views/Settings.vue`
- `views/maint/*`
- `components/maint/MaintShell.vue`
- `components/maint/*`
- `components/sections/*`
- `components/items/*`
- `composables/page-drivers/*MaintenancePage.ts`
- `composables/maint/*`
- `composables/useCrudCommands.ts`
- `stores/students.ts`
- `stores/semesters.ts`
- demo assets 與 demo language keys

移除 demo 時，同步清理 route、menu/favorites/breadcrumb 流程、語系文案與不再使用的 import。

## 新功能流程

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。

## 驗證

- Vue / TypeScript 結構變更：`pnpm -s type-check`
- 需要確認產物：`pnpm -s build`
- route、layout 或主要畫面流程變更：啟動 dev server 並做瀏覽器檢查，除非使用者明確不需要。