docs: reorganize component guide structure and indexes

Update documentation rules for GUIDE.md files to keep higher-level
guides focused on constraints, conventions, and indexes. Add base and
section component guides to the LLM development index, clarify component
layering responsibilities, and fix architecture references from README to
GUIDE.md.docs: reorganize component guide structure and indexes

Update documentation rules for GUIDE.md files to keep higher-level
guides focused on constraints, conventions, and indexes. Add base and
section component guides to the LLM development index, clarify component
layering responsibilities, and fix architecture references from README to
GUIDE.md.
This commit is contained in:
skytek_xinliang
2026-05-20 17:06:09 +08:00
parent 4d66718b05
commit 8af82f5900
10 changed files with 296 additions and 74 deletions
+1 -1
View File
@@ -443,4 +443,4 @@ views/xxx.vue
---
*本文件取代 `docs/frontend-layering.md` 與 `src/components/README.md` 成為新增功能與重構的最高準則。既有檔案可保留作為歷史參考,但後續開發以本文為準。*
*本文件取代 `docs/frontend-layering.md` 與 `src/components/GUIDE.md` 成為新增功能與重構的最高準則。既有檔案可保留作為歷史參考,但後續開發以本文為準。*
+2 -37
View File
@@ -24,6 +24,8 @@
| route view 與薄 view 規則 | `src/views/GUIDE.md` |
| maintenance demo view | `src/views/maint/GUIDE.md` |
| Vue component 分層 | `src/components/GUIDE.md` |
| base 元件 | `src/components/base/GUIDE.md` |
| section 元件 | `src/components/sections/GUIDE.md` |
| layout 邊界 | `src/components/layouts/GUIDE.md` |
| page driver、command、layout composable | `src/composables/GUIDE.md` |
| route 與 guard | `src/router/GUIDE.md` |
@@ -64,43 +66,6 @@
- 錯誤頁:讀 `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 URLdev 用相對路徑走 proxyprod 用完整 URL |
| `VITE_SKIP_LOGIN` | `.env.development` | 登入示範開關,`true` 時略過登入流程 |
| `VITE_DEV_DEFAULT_USER_ID` | `.env.development.local` | 本機開發示範帳號 |
| `VITE_DEV_DEFAULT_PASSWORD` | `.env.development.local` | 本機開發示範密碼 |
## 修改前檢查
- 是否碰到 template core。