docs: refresh template documentation and examples
Update README and frontend layering docs to reflect the current template core structure, use relative repository links, and remove outdated demo guidance. Add expanded API response examples for common features and ignore local Codex configuration.docs: refresh template documentation and examples Update README and frontend layering docs to reflect the current template core structure, use relative repository links, and remove outdated demo guidance. Add expanded API response examples for common features and ignore local Codex configuration.
This commit is contained in:
skytek_xinliang
@@ -0,0 +1,91 @@
|
||||
# Maintenance View 複製指南
|
||||
|
||||
## 文件目的
|
||||
|
||||
`src/views/maint/*.vue` 是維護頁 demo/example。新增相似維護頁時，可以複製最接近的檔案再替換欄位、資料來源、文案、route 與 component import。
|
||||
|
||||
這份指南只說明應該從哪個 view 開始複製，不代表新功能一定要留在 `maint` 目錄。正式 feature 若有自己的 domain，優先建立 `src/views/<feature>`、`src/components/<feature>` 與 `src/composables/<feature>`。
|
||||
|
||||
## 共通規則
|
||||
|
||||
複製任何維護頁後，至少同步調整：
|
||||
|
||||
- `src/router/routes.ts` 的 `path`、`name`、`component` 與 `meta.layout`
|
||||
- 頁面標題、查詢欄位、表格欄位與 action 文案
|
||||
- form 型別、初始值、驗證規則與送出流程
|
||||
- store、service、composable 與 component import
|
||||
- 對應的語系、menu、breadcrumb 或 favorites 資料
|
||||
|
||||
一般維護頁 route 使用 `meta: { layout: 'default' }`。不要在 view 內直接 import 或包住 `MainLayout.vue`。
|
||||
|
||||
## 檔案選擇
|
||||
|
||||
### `EditableGrid.vue`
|
||||
|
||||
適合複製的情況：
|
||||
|
||||
- 頁面主體是可直接編輯的表格
|
||||
- view 只需要當 route 入口
|
||||
- 主要 UI 與狀態已經能放在單一 feature component
|
||||
|
||||
目前這個檔案只載入 `@/components/maint/EditableGrid.vue`。如果新頁面需要同樣的薄 view 形狀，優先複製這個檔案，再把 component import 換成新的 feature component。
|
||||
|
||||
### `SingleRecord.vue`
|
||||
|
||||
適合複製的情況：
|
||||
|
||||
- 主畫面是查詢條件加資料表
|
||||
- 使用者從資料表開啟單筆資料 dialog
|
||||
- dialog 只維護一個主檔表單
|
||||
- 需要新增、檢視、修改、刪除、換筆、未儲存變更確認
|
||||
|
||||
這是單主檔維護頁範本。若新需求沒有明細檔、巢狀清單或 master-detail 操作，優先從這個檔案開始。
|
||||
|
||||
### `MasterDetailA.vue`
|
||||
|
||||
適合複製的情況：
|
||||
|
||||
- dialog 需要同時呈現主檔與明細檔
|
||||
- desktop 需要主檔 card 搭配側邊明細 panel
|
||||
- 明細有獨立編輯狀態，使用者會先選一筆明細再編輯內容
|
||||
- mobile 需要在 master/detail panel 之間切換
|
||||
|
||||
這個版本的重點是 `DetailSidePanel` 與 `DetailNavigation`。如果明細內容比較像側邊抽屜或右側檢視編輯區，優先複製這個檔案。
|
||||
|
||||
### `MasterDetailB.vue`
|
||||
|
||||
適合複製的情況：
|
||||
|
||||
- dialog 需要主檔加多組可展開的明細群組
|
||||
- 明細適合用 collapse/accordion 方式呈現
|
||||
- desktop 希望主檔與明細在同一個 full-height card 內操作
|
||||
- mobile detail 需要全高明細 panel
|
||||
|
||||
這個版本的重點是 `DetailCollapseGropus` 與 `DetailFullHeightPanel`。如果明細資料有群組、階層或大量列項，優先複製這個檔案。
|
||||
|
||||
### `MasterDetailC.vue`
|
||||
|
||||
適合複製的情況：
|
||||
|
||||
- dialog 需要主檔加簡化明細清單
|
||||
- 明細操作比 `MasterDetailB.vue` 輕量
|
||||
- desktop 主要是在主檔表單下方操作簡單清單
|
||||
- mobile 需要獨立明細 panel，但不需要 full-height collapse 群組
|
||||
|
||||
這個版本的重點是 `DetailSimpleList` 與 `CourseMobilePanel`。如果明細資料較少、互動較直接，優先複製這個檔案。
|
||||
|
||||
## 不建議直接複製的情況
|
||||
|
||||
- 只新增一般靜態或 dashboard 頁面：參考 `src/views/Home.vue`
|
||||
- 只新增登入頁區塊：修改 `src/components/login/*`
|
||||
- 只新增共用 dialog 或基礎元件：放到適合的 feature component，必要時才放 `src/components/base`
|
||||
- 新頁面屬於正式 domain：複製後應改放到新 domain 目錄，不要把所有正式功能都塞進 `maint`
|
||||
|
||||
## 複製後的瘦身方向
|
||||
|
||||
`SingleRecord.vue`、`MasterDetailA.vue`、`MasterDetailB.vue`、`MasterDetailC.vue` 仍偏厚。若複製後要長期維護，優先把下列內容拆出：
|
||||
|
||||
- 大段表單欄位拆到 `src/components/<feature>`
|
||||
- 可重用的表格 action、dialog content 或 detail panel 拆到 feature component
|
||||
- 表單狀態、CRUD 流程、明細編輯流程拆到 `src/composables/<feature>`
|
||||
- 跨頁共享資料或快取才放到 `src/stores`
|
||||
Reference in New Issue
Block a user