# Src 開發入口

`src` 是 template 使用者主要修改的區域。新增功能時，先從 `views` 與 `router/routes.ts` 開始，除非需求明確牽涉 app shell，否則不要先改 layout。

## 常見開發流程

1. 在 `src/views` 或 `src/views/<feature>` 新增 route view。
2. 在 `src/router/routes.ts` 加入 route。
3. 一般頁面使用 `meta: { layout: 'default' }`，讓內容被 `MainLayout` 包住。
4. 畫面超過單一簡單區塊時，拆到 `src/components/<feature>`。
5. 可重用流程或較複雜 UI state 放到 `src/composables/<feature>`。
6. 跨頁共享狀態放到 `src/stores/*.ts`。
7. API 呼叫放到 `src/services/modules/<domain>.ts`。

## 主要資料流

```txt
router -> App.vue -> layout -> view -> component -> composable/store -> service
```

責任分工：

- `router`：route、layout meta、auth meta 與錯誤頁入口。
- `App.vue`：根據 route meta 組裝 layout、全域 UI 與 layout event。
- `views`：路由入口、頁面資料協調與頁面事件協調。
- `components`：畫面呈現、props/emits 與可拆分 UI 區塊。
- `composables`：可重用流程、頁面狀態機或較複雜 UI state。
- `stores`：跨頁共享狀態、快取與全域顯示狀態。
- `services`：HTTP client、API 模組、token、session 與錯誤處理。

## Template Core

一般功能開發時，優先視為 template core：

App shell：

- `src/main.ts`
- `src/App.vue`

Layout：

- `src/components/layouts/MainLayout.vue`
- `src/components/layouts/PlainLayout.vue`
- `src/components/layouts/main-layout/*`

Login entry：

- `src/views/Login.vue`

Router core：

- `src/router/index.ts`
- `src/router/guards.ts`

Plugin / theme core：

- `src/plugins/*`
- `src/styles/*`

HTTP core：

- `src/services/client.ts`
- `src/services/interceptors.ts`
- `src/services/token.ts`
- `src/services/session.ts`
- `src/services/error.ts`
- `src/services/http-error.ts`
- `src/services/http-toast.ts`

Global stores：

- `src/stores/auth.ts`
- `src/stores/menu.ts`
- `src/stores/breadcrumbs.ts`
- `src/stores/favorites.ts`
- `src/stores/messages.ts`
- `src/stores/snackbar.ts`

Layout composables：

- `src/composables/layout/*`

這些檔案支撐 app shell、登入、路由、全域狀態與 API 基礎設施。只有需求明確要求修改 template core 時才調整。

`src/router/routes.ts` 是功能開發時可新增 route 的入口，但不要改壞既有 layout meta、auth meta 與 catch-all route 規則。

登入 route 入口是 `src/views/Login.vue`。若只是調整登入畫面內容，優先修改 `src/views/Login.vue` 與 `src/components/login/*`。

`src/services/modules/auth.ts` 與 `src/services/modules/menu.ts` 是預設後端契約的 API adapter。接新後端時常需要調整，但不要把 UI 狀態放進 service module。

## Demo / Example

以下內容偏向示範資料與範例頁，建立新專案時可依需求替換或刪除：

- `src/views/Home.vue`

- `src/views/maint/*`
- `src/components/maint/*`
- `src/composables/maint/*`
- `src/components/maint/MaintShell.vue`
- `src/stores/students.ts`
- `src/stores/semesters.ts`
- `src/views/FncPage.vue`
- `src/views/Settings.vue`
- `src/language/*.json` 中與 starter home、maint、學生資料相關的文案
- `src/assets/logo.png`
- `src/assets/logo.svg`
- `src/assets/robot-svgrepo-com.svg`

刪除 demo/example 時，也要同步清理：

- `src/router/routes.ts`
- `src/stores/menu.ts` 中依賴的選單資料流程
- 相關 `src/language/*.json` 文案
- 不再被 import 的 demo components、composables、stores 與 assets

## 新頁面最小範例

```ts
// src/router/routes.ts
{
  path: '/reports',
  name: 'reports',
  component: () => import('@/views/reports/Reports.vue'),
  meta: { layout: 'default', requiresAuth: true },
}
```

```vue
<!-- src/views/reports/Reports.vue -->
<script setup lang="ts">
import ReportsTable from '@/components/reports/ReportsTable.vue'
</script>

<template>
  <ReportsTable />
</template>
```

更多範例見 `docs/add-page-example.md`。

## 文件導覽

- `docs/add-page-example.md`：新增頁面範例。
- `docs/frontend-layering.md`：完整分層與責任邊界。
- `docs/llm-development-guide.md`：LLM 操作邊界。

## 驗證

```bash
pnpm type-check
pnpm build
```