skytek_xinliang
87fbc1dda8
Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.docs: refresh project guidance and environment setup Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.
303 lines
10 KiB
Markdown
303 lines
10 KiB
Markdown
# LLM 開發操作指南
|
||
|
||
## 文件目的
|
||
|
||
本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 在協助修改時，主要工作應集中在 `src` 底下新增或修改頁面、元件、store、service 與 composable，並讓一般頁面自然被 `MainLayout` 包住。
|
||
|
||
本文件描述的是後續 LLM 依照 template 修改專案時的預設操作規則，不是目前對話 session 的永久限制。若使用者明確要求修改 template shell 或登入頁入口，可依需求處理。
|
||
|
||
建議閱讀順序：
|
||
|
||
1. `README.md`
|
||
2. `src/README.md`
|
||
3. `docs/add-page-example.md`
|
||
4. `docs/frontend-layering.md`
|
||
|
||
## 預設不可修改的檔案
|
||
|
||
以下檔案視為 template 核心邊界。LLM 依本文件處理一般功能需求時，不應修改：
|
||
|
||
- `src/components/layouts/MainLayout.vue`
|
||
- `src/views/Login.vue`
|
||
|
||
如果一般功能需求看起來需要修改上述檔案，先停下來回報原因，並改從可修改檔案尋找解法。只有在使用者明確指定要調整 layout shell 或登入頁入口時，才可以修改。
|
||
|
||
## 優先修改的位置
|
||
|
||
一般功能需求應優先落在：
|
||
|
||
- `src/views/*`
|
||
- `src/views/<feature>/*`
|
||
- `src/components/<feature>/*`
|
||
- `src/composables/<feature>/*`
|
||
- `src/stores/*`
|
||
- `src/services/*`
|
||
- `src/router/routes.ts`
|
||
- `src/language/*.json`
|
||
|
||
新增頁面時，通常只需要新增 view、必要的 feature components，並在 `src/router/routes.ts` 加入 route。
|
||
|
||
## 依循 `src/` 既有慣例
|
||
|
||
開始實作前，先檢查需求最接近的既有檔案，並沿用目前 `src/` 的責任分工、命名方式、資料流與 import 寫法。不要另起一套資料夾結構、狀態管理方式或 API 呼叫方式。
|
||
|
||
目前主要資料流是：
|
||
|
||
```txt
|
||
router -> App.vue -> layout -> view -> component -> composable/store -> service
|
||
```
|
||
|
||
判斷原則：
|
||
|
||
- `router` 決定 route、layout meta、auth meta 與錯誤頁入口
|
||
- `App.vue` 組裝 layout props、全域 UI 與 layout event
|
||
- `views` 承接路由入口、頁面資料協調與頁面事件協調
|
||
- `components` 承接畫面呈現、props/emits 與可拆分 UI 區塊
|
||
- `composables` 承接可重用流程、頁面狀態機或較複雜的 UI state
|
||
- `stores` 承接跨頁共享狀態、快取與全域顯示狀態
|
||
- `services` 承接 HTTP client、API 模組、token、session 與錯誤處理
|
||
|
||
新增功能時，優先找相同類型的現有範例再修改：
|
||
|
||
- 新 route：參考 `src/router/routes.ts`
|
||
- 一般被主 layout 包住的頁面：參考 `src/views/Home.vue`、`src/views/maint/EditableGrid.vue`
|
||
- 登入相關 UI：參考 `src/components/PageLogin.vue` 與 `src/components/login/*`
|
||
- 維護頁：參考 `src/views/maint/*`、`src/components/maint/*`、`src/composables/maint/*`
|
||
- API 呼叫：參考 `src/services/modules/*` 與使用它們的 store/composable
|
||
- 全域提示：參考 `src/stores/snackbar.ts` 與 `src/composables/useApiCall.ts`
|
||
|
||
## Template Core 與 Demo 邊界
|
||
|
||
一般功能需求應避免先修改 template core。這些檔案支撐 app shell、route/layout、登入、全域狀態與 API 基礎設施：
|
||
|
||
- `src/main.ts`
|
||
- `src/App.vue`
|
||
- `src/router/index.ts`
|
||
- `src/router/guards.ts`
|
||
- `src/components/layouts/*`
|
||
- `src/views/Login.vue`
|
||
- `src/plugins/*`
|
||
- `src/styles/*`
|
||
- `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`
|
||
- `src/stores/auth.ts`
|
||
- `src/stores/menu.ts`
|
||
- `src/stores/breadcrumbs.ts`
|
||
- `src/stores/favorites.ts`
|
||
- `src/stores/messages.ts`
|
||
- `src/stores/snackbar.ts`
|
||
- `src/composables/layout/*`
|
||
|
||
以下內容偏向 demo/example，建立正式專案時可依需求替換或刪除：
|
||
|
||
- `src/views/Home.vue`
|
||
- `src/components/PageIndex.vue`
|
||
- `src/views/maint/*`
|
||
- `src/components/maint/*`
|
||
- `src/composables/maint/*`
|
||
- `src/components/PageMaint.vue`
|
||
- `src/stores/students.ts`
|
||
- `src/stores/semesters.ts`
|
||
- `src/views/FncPage.vue`
|
||
- `src/views/Settings.vue`
|
||
- `src/assets/logo.png`
|
||
- `src/assets/logo.svg`
|
||
- `src/assets/robot-svgrepo-com.svg`
|
||
|
||
`maint` 是可參考的 demo feature，不是所有新專案都必須保留的核心功能。
|
||
|
||
移除 demo/example 時，同步清理 `src/router/routes.ts`、相關 menu/favorites/breadcrumb 流程、語系文案、assets 與 import。
|
||
|
||
## 新增一般頁面的流程
|
||
|
||
1. 在 `src/views` 或 `src/views/<feature>` 新增頁面檔案。
|
||
2. 若頁面超過單一簡單畫面，將主要 UI 拆到 `src/components/<feature>`。
|
||
3. 若有可重用或狀態較多的流程，放到 `src/composables/<feature>`。
|
||
4. 若資料需要跨頁共享，才新增或修改 `src/stores`。
|
||
5. 在 `src/router/routes.ts` 新增 route。
|
||
6. 一般頁面的 route 必須使用 `meta: { layout: 'default' }`。
|
||
|
||
範例：
|
||
|
||
```ts
|
||
{
|
||
path: '/reports',
|
||
name: 'reports',
|
||
component: () => import('@/views/reports/Reports.vue'),
|
||
meta: { layout: 'default' },
|
||
}
|
||
```
|
||
|
||
使用 `layout: 'default'` 的頁面會由 `App.vue` 放進 `MainLayout` 的預設 slot，不需要也不可以直接 import 或包裝 `MainLayout.vue`。
|
||
|
||
完整範例見 `docs/add-page-example.md`。
|
||
|
||
## 何時使用 `layout: 'none'`
|
||
|
||
只有下列頁面應使用 `meta: { layout: 'none' }`：
|
||
|
||
- 登入頁
|
||
- 錯誤頁
|
||
- 維護中頁
|
||
- 明確要求不要被主框架包住的獨立頁
|
||
|
||
不要為了一般功能頁使用 `layout: 'none'`。
|
||
|
||
## Layout 邊界
|
||
|
||
`MainLayout` 只負責 app shell：
|
||
|
||
- drawer
|
||
- app bar
|
||
- breadcrumb
|
||
- favorites
|
||
- toolbar actions
|
||
- 主內容 slot
|
||
|
||
頁面專屬業務流程、資料規則、表單、列表、對話框、查詢條件與 CRUD 行為都不應放進 layout。
|
||
|
||
如果頁面需要在主內容區呈現特定畫面，請修改該 route 對應的 view 或 feature component。
|
||
|
||
如果頁面需要影響 breadcrumb、favorites、menu 或 toolbar，優先使用現有 store、route meta 或 `App.vue` 已經提供的 layout props/event 流程，不要修改 `MainLayout.vue`。
|
||
|
||
## Login 邊界
|
||
|
||
`src/views/Login.vue` 是登入頁入口。一般功能需求預設不修改這個檔案。
|
||
|
||
若需求是調整登入頁內部區塊，優先檢查並修改：
|
||
|
||
- `src/components/PageLogin.vue`
|
||
- `src/components/login/*`
|
||
- `src/stores/auth.ts`
|
||
- `src/stores/loginAnnouncements.ts`
|
||
- `src/services/modules/auth.ts`
|
||
|
||
若需求明確要求改變登入頁 route、guard 或登入後導向，優先檢查：
|
||
|
||
- `src/router/routes.ts`
|
||
- `src/router/guards.ts`
|
||
- `src/stores/auth.ts`
|
||
|
||
## View 與 Component 分工
|
||
|
||
`views` 是路由入口，負責：
|
||
|
||
- 接 route params/query
|
||
- 組合頁面資料
|
||
- 串接 store、service、composable
|
||
- 管理頁面專屬事件
|
||
- 組裝頁面主 component
|
||
|
||
`components/<feature>` 負責：
|
||
|
||
- 呈現頁面區塊
|
||
- 接 props
|
||
- emit 使用者事件
|
||
- 拆分表單、列表、工具列、dialog 等 UI
|
||
|
||
不要把完整功能長期塞在單一 view。當畫面有多個區塊、表單、列表、dialog 或重複 UI 時，應拆到 feature components。
|
||
|
||
## Router 安排規則
|
||
|
||
route 集中放在 `src/router/routes.ts`。不要在 view 或 component 裡臨時建立 route 設定。
|
||
|
||
一般 route 應包含：
|
||
|
||
- `path`
|
||
- `name`
|
||
- `component`
|
||
- `meta.layout`
|
||
|
||
需要登入才可進入的頁面使用既有 `requiresAuth` meta。訪客專用頁面使用既有 `guestOnly` meta。導航守衛流程放在 `src/router/guards.ts`，不要散落在頁面 component。
|
||
|
||
## Composable 使用規則
|
||
|
||
只有在邏輯有下列特性時才新增 composable：
|
||
|
||
- 會被多個元件使用
|
||
- 狀態流程明顯
|
||
- 有副作用或非簡單 UI 邏輯
|
||
- 從 component 抽出後可讓 component 責任更清楚
|
||
|
||
目前既有 composable 的使用定位：
|
||
|
||
- `src/composables/useApiCall.ts`：包裝可重用 API 呼叫狀態與錯誤提示流程
|
||
- `src/composables/layout/useAdminLayoutState.ts`：提供 layout shell 所需的狀態組裝
|
||
- `src/composables/layout/useThemeToggle.ts`：提供主題切換流程
|
||
- `src/composables/maint/useMaintenanceCrudFlow.ts`：提供維護頁 CRUD 流程狀態
|
||
- `src/composables/maint/useStudentMaintenanceForm.ts`：提供學生維護表單狀態
|
||
- `src/composables/maint/useEditableStudentGrid.ts`：提供 editable grid 狀態
|
||
|
||
新增 composable 時，用 `useXxx.ts` 命名。若只服務單一 feature，放在 `src/composables/<feature>`；若確定跨 feature 使用，才放在 `src/composables` 根目錄。
|
||
|
||
## Store 與 Service 資料流規則
|
||
|
||
只有在資料或狀態跨頁共享時才使用 store。單一頁面的暫時 UI 狀態應留在 view、feature component 或 composable。
|
||
|
||
store 檔案直接放在 `src/stores/*.ts`。不要建立 `src/stores/stores/*` 或其他重複巢狀 store 目錄。
|
||
|
||
service 放在 `src/services`，負責外部 API 與 HTTP 細節。component 不應直接處理底層 HTTP client、token、interceptor 或錯誤正規化。
|
||
|
||
資料流優先順序：
|
||
|
||
1. component 透過 props/emits 與 view 或 page component 溝通。
|
||
2. view 或 composable 協調頁面流程。
|
||
3. 跨頁共享狀態由 store 管理。
|
||
4. store 或 composable 呼叫 service。
|
||
5. service 回傳資料，不持有 UI 狀態。
|
||
|
||
不要讓 service import component、view 或 store。不要讓 component 直接繞過既有 store/composable 去操作 token、session 或 HTTP interceptor。
|
||
|
||
## 環境變數規則
|
||
|
||
template 提供 `.env.example` 作為範本。不要提交實際 `.env` 或 `.env.*.local`。
|
||
|
||
常用變數：
|
||
|
||
- `VITE_API_BASE_URL`：API base URL，預設使用 `/service/api` 搭配 Vite proxy。
|
||
- `VITE_SKIP_LOGIN`：登入示範開關，只有專案明確支援時才使用。
|
||
- `VITE_DEV_DEFAULT_USER_ID`、`VITE_DEV_DEFAULT_PASSWORD`：本機開發示範帳號，放在本機 env，不要寫進程式。
|
||
|
||
## Vuetify 使用規則
|
||
|
||
優先使用 Vuetify 原生元件、props、slots 與事件。當需求直接牽涉 Vuetify 元件行為、DOM、可及性輸出或 slot 結構時，先查官方 Vuetify API 文件，再修改實作。
|
||
|
||
icon 使用 `@mdi/js`：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { mdiAccount } from '@mdi/js'
|
||
</script>
|
||
|
||
<template>
|
||
<v-icon :icon="mdiAccount" />
|
||
</template>
|
||
```
|
||
|
||
## 修改前檢查
|
||
|
||
開始改檔前先確認：
|
||
|
||
- 是否會碰到禁止修改檔案
|
||
- 是否只需要新增或修改 view
|
||
- 是否需要新增 route
|
||
- 是否需要拆 feature component
|
||
- 是否已閱讀 `docs/frontend-layering.md`
|
||
- 是否已參考 `src/` 裡相同類型的既有範例
|
||
- 是否符合 Vue 3、Composition API、`<script setup lang="ts">` 的既有寫法
|
||
|
||
## 完成前驗證
|
||
|
||
修改完成後，至少執行與變更範圍相符的檢查：
|
||
|
||
- TypeScript 或 Vue 結構有變更：`pnpm type-check`
|
||
- 需要確認產物可建置：`pnpm build`
|
||
- route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認頁面被正確包在主 layout 中
|
||
|
||
如果無法執行驗證，回報原因，不要宣稱已驗證。
|