skytek_xinliang
e90d412956
Document new GUIDE.md expectations for src-layer edits and add index entries for models and shared types. Clarify layout usage, composable placement, error page conventions, and model/type ownership so future changes follow the intended layer boundaries.docs: update LLM guides for models and layout rules Document new GUIDE.md expectations for src-layer edits and add index entries for models and shared types. Clarify layout usage, composable placement, error page conventions, and model/type ownership so future changes follow the intended layer boundaries.
86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
# 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 並用瀏覽器確認，除非使用者明確不需要。
|
||
|
||
如果無法執行驗證，回報原因，不要宣稱已驗證。
|