skytek_xinliang
4d66718b05
Add VITE_PROXY_TARGET to the example environment file and use it in the Vite dev proxy configuration with a localhost fallback. Expand the LLM development guide with env file loading order, version-control rules, and variable descriptions. Also clean up ignored local tool paths in .gitignore and remove duplicated README env examples.chore: document env files and configure proxy target Add VITE_PROXY_TARGET to the example environment file and use it in the Vite dev proxy configuration with a localhost fallback. Expand the LLM development guide with env file loading order, version-control rules, and variable descriptions. Also clean up ignored local tool paths in .gitignore and remove duplicated README env examples.
123 lines
5.0 KiB
Markdown
123 lines
5.0 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`。
|
||
|
||
## 環境變數（.env 檔案）
|
||
|
||
Vite 會依 mode 自動載入對應層級的 `.env` 檔案，優先順序由高到低：
|
||
|
||
```
|
||
.env.[mode].local ← 本機覆蓋，不提交（最高優先）
|
||
.env.[mode] ← mode 專用
|
||
.env.local ← 本機覆蓋，不提交
|
||
.env ← 所有 mode 通用
|
||
```
|
||
|
||
專案實際使用與版本控制規則：
|
||
|
||
| 檔案 | 用途 | Git |
|
||
|------|------|-----|
|
||
| `.env.example` | 範本檔，列出所有可用變數與說明 | 提交 |
|
||
| `.env` | 所有 Vite 指令皆載入（serve / build） | 忽略 |
|
||
| `.env.development` | `vite serve`（mode=development）載入 | 忽略 |
|
||
| `.env.development.local` | 本機開發機密值（帳號密碼等） | 忽略 |
|
||
| `.env.production` | `vite build`（mode=production）載入 | 忽略 |
|
||
|
||
**新增環境變數時應遵守的順序：**
|
||
|
||
1. 在 `.env` 或 `.env.development` 中新增變數並給定預設值
|
||
2. 在 `.env.example` 中加入該變數的說明與格式，供其他開發者參考
|
||
3. 若變數包含機密資訊（帳號、密碼、token），僅放在 `.env.development.local`，不要寫入 `.env.example` 的預設值
|
||
|
||
**現有變數說明：**
|
||
|
||
| 變數 | 適用檔案 | 說明 |
|
||
|------|----------|------|
|
||
| `VITE_PROXY_TARGET` | `.env`, `.env.development`, `.env.development.local` | dev server proxy 目標後端 URL |
|
||
| `VITE_API_BASE_URL` | `.env`, `.env.development`, `.env.production` | API 請求 base URL，dev 用相對路徑走 proxy，prod 用完整 URL |
|
||
| `VITE_SKIP_LOGIN` | `.env.development` | 登入示範開關，`true` 時略過登入流程 |
|
||
| `VITE_DEV_DEFAULT_USER_ID` | `.env.development.local` | 本機開發示範帳號 |
|
||
| `VITE_DEV_DEFAULT_PASSWORD` | `.env.development.local` | 本機開發示範密碼 |
|
||
|
||
## 修改前檢查
|
||
|
||
- 是否碰到 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 並用瀏覽器確認，除非使用者明確不需要。
|
||
|
||
如果無法執行驗證，回報原因，不要宣稱已驗證。
|