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.
2026-05-19 17:17:43 +08:00
parent 51fbbd7101
commit ac7e1959cf
15 changed files with 400 additions and 1074 deletions
@@ -0,0 +1,90 @@
+# Src Guide
+
+`src` 是 template 使用者主要修改的區域。新增功能時，先從 route view、page component 與 page driver 開始，除非需求明確牽涉 app shell、登入、router guard 或 HTTP core，否則不要先改 template core。
+
+## 資料流
+
+```txt
+router -> AppShell -> layout -> view(Page Driver) -> Page Component -> Section -> Item
+                                      ↓
+                         page driver / command composable -> store -> service
+```
+
+## 主要目錄
+
+- `views/`：route entry，維持薄層，只做 route wiring 與 page driver 掛載。詳見 `src/views/GUIDE.md`。
+- `components/`：Vue UI 元件，依 pages / 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/PageIndex.vue`
+- `components/PageMaint.vue`
+- `components/maint/*`
+- `components/pages/*Maintenance.vue`
+- `components/sections/*`
+- `components/items/*`
+- `composables/page-drivers/*MaintenancePage.ts`
+- `composables/maint/*`
+- `composables/commands/*`
+- `stores/students.ts`
+- `stores/semesters.ts`
+- demo assets 與 demo language keys
+
+移除 demo 時，同步清理 route、menu/favorites/breadcrumb 流程、語系文案與不再使用的 import。
+
+## 新功能流程
+
+1. 新增或修改 `views/*` route entry。
+2. 若有完整頁面 UI，新增 `components/pages/PageXxx.vue`。
+3. 若有頁面資料協調或 route param 轉換，新增 `composables/page-drivers/useXxxPage.ts`。
+4. 若畫面有獨立區塊，拆到 `components/sections/*`。
+5. 若區塊內有欄位群組或單筆資料呈現，拆到 `components/items/*`。
+6. 跨頁共享狀態才新增或修改 `stores/*`。
+7. 外部 API 放在 `services/modules/*`。
+8. 在 `router/routes.ts` 新增 route。
+
+## 驗證
+
+- Vue / TypeScript 結構變更：`pnpm -s type-check`
+- 需要確認產物：`pnpm -s build`
+- route、layout 或主要畫面流程變更：啟動 dev server 並做瀏覽器檢查，除非使用者明確不需要。