docs: update LLM guides for completed architecture phase
Refresh the development guidance to point to layered src GUIDE files and document Phase 4 completion, including AppShell extraction and page driver/component adoption for non-maintenance pages.docs: update LLM guides for completed architecture phase Refresh the development guidance to point to layered src GUIDE files and document Phase 4 completion, including AppShell extraction and page driver/component adoption for non-maintenance pages.
This commit is contained in:
skytek_xinliang
@@ -397,10 +397,16 @@ views/xxx.vue
|
||||
4. [x] 通用方向已落地為「每頁 page driver + page component」與既有 `useCrudCommands()`。
|
||||
- Phase 3 未再抽出跨 A/B/C 的大型共用 driver，避免在 demo 變體尚未收斂前建立過早抽象。
|
||||
|
||||
### Phase 4：非 maintenance 頁面統一
|
||||
### Phase 4：非 maintenance 頁面統一 ✅ 已完成
|
||||
|
||||
1. `Home.vue`、`Settings.vue`、`FncPage.vue` 套用 Page Driver + Page Component 模式。
|
||||
2. `App.vue` 最終只保留 layout 切換與 `GlobalOverlays` 掛載。
|
||||
1. [x] `Home.vue`、`Settings.vue`、`FncPage.vue` 套用 Page Driver + Page Component 模式。
|
||||
- `src/views/Home.vue` 縮減為 17 行，新增 `src/components/pages/PageHome.vue` 與 `src/composables/page-drivers/useHomePage.ts`。
|
||||
- `src/views/Settings.vue` 縮減為 10 行，新增 `src/components/pages/PageSettings.vue` 與 `src/composables/page-drivers/useSettingsPage.ts`。
|
||||
- `src/views/FncPage.vue` 縮減為 10 行，新增 `src/components/pages/PageFunction.vue` 與 `src/composables/page-drivers/useFunctionPage.ts`。
|
||||
2. [x] `App.vue` 最終只保留 shell 掛載。
|
||||
- `src/App.vue` 縮減為 7 行，只掛載 `AppShell`。
|
||||
- `src/shell/AppShell.vue` 承接 layout 切換、layout props/events、breadcrumb actions、tabs router-view 與 `GlobalOverlays` 掛載。
|
||||
- `src/composables/layout/useAppShell.ts` 承接 menu 合併、favorite、breadcrumb、layout action、手動/強制登出流程。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+50
-304
@@ -2,332 +2,78 @@
|
||||
|
||||
## 文件目的
|
||||
|
||||
本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 在協助修改時，主要工作應集中在 `src` 底下新增或修改頁面、元件、store、service 與 composable，並讓一般頁面自然被 `MainLayout` 包住。
|
||||
本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 協助修改時，預設應在 `src` 底下依分層規則新增或修改頁面、元件、store、service 與 composable。
|
||||
|
||||
本文件描述的是後續 LLM 依照 template 修改專案時的預設操作規則，不是目前對話 session 的永久限制。若使用者明確要求修改 template shell 或登入頁入口，可依需求處理。
|
||||
本文件只保留全域操作順序與導覽。各層細節規範放在 `src/**/GUIDE.md`，避免重複維護。
|
||||
|
||||
建議閱讀順序：
|
||||
## 建議閱讀順序
|
||||
|
||||
1. `README.md`
|
||||
2. `src/README.md`
|
||||
3. `docs/add-page-example.md`
|
||||
4. `docs/architecture-strategy.md`（新增功能與重構的最高準則）
|
||||
5. `docs/frontend-layering.md`（歷史參考，已被 `architecture-strategy.md` 取代）
|
||||
2. `docs/architecture-strategy.md`
|
||||
3. `src/GUIDE.md`
|
||||
4. 依變更範圍閱讀對應的 `src/**/GUIDE.md`
|
||||
5. `docs/add-page-example.md`（需要新增頁面時）
|
||||
|
||||
## 預設不可修改的檔案
|
||||
`docs/frontend-layering.md` 是歷史參考，後續以 `docs/architecture-strategy.md` 與 `src/**/GUIDE.md` 為準。
|
||||
|
||||
以下檔案視為 template 核心邊界。LLM 依本文件處理一般功能需求時，不應修改：
|
||||
## GUIDE 索引
|
||||
|
||||
- `src/components/layouts/MainLayout.vue`
|
||||
- `src/views/Login.vue`
|
||||
| 範圍 | 指南 |
|
||||
|------|------|
|
||||
| `src` 總覽、資料流、template core、demo 邊界 | `src/GUIDE.md` |
|
||||
| route view 與薄 view 規則 | `src/views/GUIDE.md` |
|
||||
| maintenance demo view | `src/views/maint/GUIDE.md` |
|
||||
| Vue component 分層 | `src/components/GUIDE.md` |
|
||||
| layout 邊界 | `src/components/layouts/GUIDE.md` |
|
||||
| page driver、command、layout composable | `src/composables/GUIDE.md` |
|
||||
| route 與 guard | `src/router/GUIDE.md` |
|
||||
| AppShell、tabs、global overlays | `src/shell/GUIDE.md` |
|
||||
| Pinia store | `src/stores/GUIDE.md` |
|
||||
| HTTP service / ky / API module | `src/services/GUIDE.md` |
|
||||
| i18n 文案 | `src/language/GUIDE.md` |
|
||||
|
||||
如果一般功能需求看起來需要修改上述檔案，先停下來回報原因，並改從可修改檔案尋找解法。只有在使用者明確指定要調整 layout shell 或登入頁入口時，才可以修改。
|
||||
## 預設修改策略
|
||||
|
||||
## 優先修改的位置
|
||||
|
||||
一般功能需求應優先落在：
|
||||
一般功能需求優先修改：
|
||||
|
||||
- `src/views/*`
|
||||
- `src/views/<feature>/*`
|
||||
- `src/components/<feature>/*`
|
||||
- `src/composables/<feature>/*`
|
||||
- `src/components/pages/*`
|
||||
- `src/components/sections/*`
|
||||
- `src/components/items/*`
|
||||
- `src/composables/page-drivers/*`
|
||||
- `src/composables/commands/*`
|
||||
- `src/stores/*`
|
||||
- `src/services/*`
|
||||
- `src/services/modules/*`
|
||||
- `src/router/routes.ts`
|
||||
- `src/language/*.json`
|
||||
|
||||
新增頁面時，通常只需要新增 view、必要的 feature components，並在 `src/router/routes.ts` 加入 route。
|
||||
除非使用者明確要求，避免先修改 template core。template core 清單與 demo/example 邊界見 `src/GUIDE.md`。
|
||||
|
||||
## 依循 `src/` 既有慣例
|
||||
## 常用判斷
|
||||
|
||||
開始實作前，先檢查需求最接近的既有檔案，並沿用目前 `src/` 的責任分工、命名方式、資料流與 import 寫法。不要另起一套資料夾結構、狀態管理方式或 API 呼叫方式。
|
||||
|
||||
目前主要資料流是：
|
||||
|
||||
```txt
|
||||
router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
|
||||
↓
|
||||
page driver / command composable -> store -> service
|
||||
```
|
||||
|
||||
判斷原則：
|
||||
|
||||
- `router` 決定 route、layout meta、auth meta 與錯誤頁入口
|
||||
- `AppShell` 組裝 layout props、全域 UI 與 layout event
|
||||
- `views` 承接路由入口、頁面資料協調與頁面事件協調，應維持薄層
|
||||
- `components/pages` 組裝完整頁面與 page-level slot
|
||||
- `components/sections` 承接容器佈局，例如搜尋區、表格、dialog shell
|
||||
- `components/items` 承接單一資料單位或欄位群組呈現
|
||||
- `composables/page-drivers` 承接頁面資料協調與 page model 組裝
|
||||
- `composables/commands` 承接命令式副作用流程，例如 create/edit/save/delete
|
||||
- `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/SingleRecord.vue`、`src/views/maint/EditableGrid.vue`、`src/views/maint/MasterDetailA.vue`、`src/views/maint/MasterDetailB.vue`、`src/views/maint/MasterDetailC.vue` 與對應的 `src/components/pages/*Maintenance.vue`、`src/composables/page-drivers/*MaintenancePage.ts`
|
||||
- 單筆維護欄位/表格/dialog 拆分：參考 `src/components/sections/*`、`src/components/items/*`、`src/composables/commands/useCrudCommands.ts`
|
||||
- 維護頁範本選擇：參考 `src/views/maint/README.md`
|
||||
- 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/stores/app.ts`
|
||||
- `src/composables/layout/*`
|
||||
|
||||
以下內容偏向 demo/example，建立正式專案時可依需求替換或刪除：
|
||||
|
||||
- `src/views/Home.vue`
|
||||
- `src/components/PageIndex.vue`
|
||||
- `src/views/maint/*`
|
||||
- `src/components/maint/*`
|
||||
- `src/components/pages/PageMaintenance.vue`
|
||||
- `src/components/sections/*`
|
||||
- `src/components/items/*`
|
||||
- `src/composables/maint/*`
|
||||
- `src/composables/page-drivers/*`
|
||||
- `src/composables/commands/*`
|
||||
- `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 時，應拆到 page / section / item components。
|
||||
|
||||
維護頁分層優先順序：
|
||||
|
||||
1. `views/maint/*.vue`：只做 route-level wiring，目標 < 80 行。
|
||||
2. `components/pages/PageMaintenance.vue`：組裝維護頁外殼與主要 slot。
|
||||
3. `components/sections/*`：管理搜尋、表格、dialog shell 等區塊佈局。
|
||||
4. `components/items/*`：管理欄位群組或單一資料呈現，不直接呼叫 store/service。
|
||||
5. `composables/page-drivers/*`：集中 page model、分頁、搜尋、表單狀態與事件 wiring。
|
||||
6. `composables/commands/*`：集中新增、載入、儲存、刪除等 command 流程。
|
||||
|
||||
## 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/page-drivers/useMaintenancePage.ts`：提供通用 maintenance page model 基礎狀態
|
||||
- `src/composables/page-drivers/useSingleRecordMaintenancePage.ts`：協調單筆維護 demo 頁面的 page model、section props/events、表單、表格與 command
|
||||
- `src/composables/page-drivers/useEditableGridMaintenancePage.ts`：協調可編輯表格 demo 頁面的 page model
|
||||
- `src/composables/page-drivers/useMasterDetailAMaintenancePage.ts`：協調主從維護 A demo 的 page model、主檔/明細狀態與 dialog event wiring
|
||||
- `src/composables/page-drivers/useMasterDetailBMaintenancePage.ts`：協調主從維護 B demo 的 page model、主檔/明細狀態與 dialog event wiring
|
||||
- `src/composables/page-drivers/useMasterDetailCMaintenancePage.ts`：協調主從維護 C demo 的 page model、主檔/明細狀態與 dialog event wiring
|
||||
- `src/composables/commands/useCrudCommands.ts`：提供 CRUD command 流程，讓 view 不直接執行 store mutation 細節
|
||||
- `src/composables/maint/useMaintenanceCrudFlow.ts`：提供維護頁 CRUD 流程狀態
|
||||
- `src/composables/maint/useStudentMaintenanceForm.ts`：提供學生維護表單狀態
|
||||
- `src/composables/maint/useEditableStudentGrid.ts`：提供 editable grid 狀態
|
||||
|
||||
新增 composable 時，用 `useXxx.ts` 命名。若是頁面資料協調，放在 `src/composables/page-drivers`；若是命令式副作用流程，放在 `src/composables/commands`；若只服務單一 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、hooks 或錯誤正規化。
|
||||
|
||||
資料流優先順序：
|
||||
|
||||
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 hooks。
|
||||
|
||||
## 環境變數規則
|
||||
|
||||
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>
|
||||
```
|
||||
- 新 route：讀 `src/router/GUIDE.md`。
|
||||
- 一般頁面：讀 `src/views/GUIDE.md`、`src/components/GUIDE.md`、`src/composables/GUIDE.md`。
|
||||
- 維護頁：讀 `src/views/maint/GUIDE.md`。
|
||||
- layout / AppShell / tabs / global overlay：讀 `src/shell/GUIDE.md` 與 `src/components/layouts/GUIDE.md`。
|
||||
- API 串接：讀 `src/services/GUIDE.md`。
|
||||
- 跨頁共享狀態：讀 `src/stores/GUIDE.md`。
|
||||
- 語系文案：讀 `src/language/GUIDE.md`。
|
||||
|
||||
## 修改前檢查
|
||||
|
||||
開始改檔前先確認：
|
||||
|
||||
- 是否會碰到禁止修改檔案
|
||||
- 是否只需要新增或修改 view
|
||||
- 是否需要新增 route
|
||||
- 是否需要拆 feature component
|
||||
- 是否已閱讀 `docs/architecture-strategy.md`
|
||||
- 是否已參考 `src/` 裡相同類型的既有範例
|
||||
- 是否符合 Vue 3、Composition API、`<script setup lang="ts">` 的既有寫法
|
||||
- 是否碰到 template core。
|
||||
- 是否已有同類型範例可沿用。
|
||||
- 是否需要新增 route。
|
||||
- 是否應拆成 page / section / item。
|
||||
- 是否應新增 page driver 或 command composable。
|
||||
- 是否需要 store，或只需要頁面內 state。
|
||||
- 是否需要更新語系、menu、breadcrumb、favorites。
|
||||
|
||||
## 完成前驗證
|
||||
|
||||
修改完成後，至少執行與變更範圍相符的檢查：
|
||||
|
||||
- TypeScript 或 Vue 結構有變更：`pnpm type-check`
|
||||
- 需要確認產物可建置：`pnpm build`
|
||||
- route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認頁面被正確包在主 layout 中
|
||||
- Vue / TypeScript 結構有變更：`pnpm -s type-check`
|
||||
- 需要確認產物可建置：`pnpm -s build`
|
||||
- Markdown 或大量搬移：`git diff --check`
|
||||
- route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認，除非使用者明確不需要。
|
||||
|
||||
如果無法執行驗證，回報原因，不要宣稱已驗證。
|
||||
|
||||
Reference in New Issue
Block a user