# LLM 開發操作指南

## 文件目的

本專案是給其他 Vue/Vuetify 專案使用的 template。LLM 協助修改時，預設應在 `src` 底下依分層規則新增或修改頁面、元件、store、service 與 composable。

本文件只保留全域操作順序與導覽。各層細節規範放在 `src/**/GUIDE.md`，避免重複維護。

## 建議閱讀順序

1. `README.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` 為準。

## GUIDE 索引

| 範圍 | 指南 |
|------|------|
| `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` |
| domain model 與 page model 型別 | `src/models/GUIDE.md` |
| 跨模組共用 API 型別 | `src/types/GUIDE.md` |
| i18n 文案 | `src/language/GUIDE.md` |

## 預設修改策略

一般功能需求優先修改：

- `src/views/*`
- `src/components/pages/*`
- `src/components/sections/*`
- `src/components/items/*`
- `src/composables/page-drivers/*`
- `src/composables/commands/*`
- `src/stores/*`
- `src/services/modules/*`
- `src/router/routes.ts`
- `src/language/*.json`

除非使用者明確要求，避免先修改 template core。template core 清單與 demo/example 邊界見 `src/GUIDE.md`。

## 常用判斷

- 新 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`。
- 定義 page model 或 domain model 型別：讀 `src/models/GUIDE.md`。
- 共用 API 型別定義：讀 `src/types/GUIDE.md`。
- 錯誤頁：讀 `src/views/GUIDE.md`（ErrorShell 模式）與 `src/router/GUIDE.md`（錯誤頁路由慣例）。
- 語系文案：讀 `src/language/GUIDE.md`。

## 修改前檢查

- 是否碰到 template core。
- 是否已有同類型範例可沿用。
- 是否需要新增 route。
- 是否應拆成 page / section / item。
- 是否應新增 page driver 或 command composable。
- 是否需要 store，或只需要頁面內 state。
- 是否應定義新的 model 型別（`src/models/`）。
- 是否需要更新語系、menu、breadcrumb、favorites。

## 完成前驗證

- Vue / TypeScript 結構有變更：`pnpm -s type-check`
- 需要確認產物可建置：`pnpm -s build`
- Markdown 或大量搬移：`git diff --check`
- route、layout 或主要畫面流程有變更：啟動 dev server 並用瀏覽器確認，除非使用者明確不需要。

如果無法執行驗證，回報原因，不要宣稱已驗證。