skytek_xinliang
87fbc1dda8
Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.docs: refresh project guidance and environment setup Add env example defaults for Vite API and login settings, document template structure and page creation flow, and align agent guidance with current LLM development rules. Also allow committing the env example while keeping local env files ignored.
154 lines
4.2 KiB
Markdown
154 lines
4.2 KiB
Markdown
# Src 開發入口
|
||
|
||
`src` 是 template 使用者主要修改的區域。新增功能時，先從 `views` 與 `router/routes.ts` 開始，除非需求明確牽涉 app shell，否則不要先改 layout。
|
||
|
||
## 常見開發流程
|
||
|
||
1. 在 `src/views` 或 `src/views/<feature>` 新增 route view。
|
||
2. 在 `src/router/routes.ts` 加入 route。
|
||
3. 一般頁面使用 `meta: { layout: 'default' }`，讓內容被 `MainLayout` 包住。
|
||
4. 畫面超過單一簡單區塊時，拆到 `src/components/<feature>`。
|
||
5. 可重用流程或較複雜 UI state 放到 `src/composables/<feature>`。
|
||
6. 跨頁共享狀態放到 `src/stores/*.ts`。
|
||
7. API 呼叫放到 `src/services/modules/<domain>.ts`。
|
||
|
||
## 主要資料流
|
||
|
||
```txt
|
||
router -> App.vue -> layout -> view -> component -> composable/store -> service
|
||
```
|
||
|
||
責任分工：
|
||
|
||
- `router`：route、layout meta、auth meta 與錯誤頁入口。
|
||
- `App.vue`：根據 route meta 組裝 layout、全域 UI 與 layout event。
|
||
- `views`：路由入口、頁面資料協調與頁面事件協調。
|
||
- `components`：畫面呈現、props/emits 與可拆分 UI 區塊。
|
||
- `composables`：可重用流程、頁面狀態機或較複雜 UI state。
|
||
- `stores`：跨頁共享狀態、快取與全域顯示狀態。
|
||
- `services`：HTTP client、API 模組、token、session 與錯誤處理。
|
||
|
||
## Template Core
|
||
|
||
一般功能開發時，優先視為 template core：
|
||
|
||
App shell：
|
||
|
||
- `src/main.ts`
|
||
- `src/App.vue`
|
||
|
||
Layout：
|
||
|
||
- `src/components/layouts/MainLayout.vue`
|
||
- `src/components/layouts/PlainLayout.vue`
|
||
- `src/components/layouts/main-layout/*`
|
||
|
||
Login entry：
|
||
|
||
- `src/views/Login.vue`
|
||
|
||
Router core：
|
||
|
||
- `src/router/index.ts`
|
||
- `src/router/guards.ts`
|
||
|
||
Plugin / theme core：
|
||
|
||
- `src/plugins/*`
|
||
- `src/styles/*`
|
||
|
||
HTTP core：
|
||
|
||
- `src/services/client.ts`
|
||
- `src/services/interceptors.ts`
|
||
- `src/services/token.ts`
|
||
- `src/services/session.ts`
|
||
- `src/services/error.ts`
|
||
- `src/services/http-error.ts`
|
||
- `src/services/http-toast.ts`
|
||
|
||
Global stores：
|
||
|
||
- `src/stores/auth.ts`
|
||
- `src/stores/menu.ts`
|
||
- `src/stores/breadcrumbs.ts`
|
||
- `src/stores/favorites.ts`
|
||
- `src/stores/messages.ts`
|
||
- `src/stores/snackbar.ts`
|
||
|
||
Layout composables：
|
||
|
||
- `src/composables/layout/*`
|
||
|
||
這些檔案支撐 app shell、登入、路由、全域狀態與 API 基礎設施。只有需求明確要求修改 template core 時才調整。
|
||
|
||
`src/router/routes.ts` 是功能開發時可新增 route 的入口，但不要改壞既有 layout meta、auth meta 與 catch-all route 規則。
|
||
|
||
登入 route 入口是 `src/views/Login.vue`。若只是調整登入畫面內容，優先修改 `src/components/PageLogin.vue` 與 `src/components/login/*`。
|
||
|
||
`src/services/modules/auth.ts` 與 `src/services/modules/menu.ts` 是預設後端契約的 API adapter。接新後端時常需要調整，但不要把 UI 狀態放進 service module。
|
||
|
||
## Demo / Example
|
||
|
||
以下內容偏向示範資料與範例頁，建立新專案時可依需求替換或刪除：
|
||
|
||
- `src/views/Home.vue`
|
||
- `src/components/PageIndex.vue`
|
||
- `src/views/maint/*`
|
||
- `src/components/maint/*`
|
||
- `src/composables/maint/*`
|
||
- `src/components/PageMaint.vue`
|
||
- `src/stores/students.ts`
|
||
- `src/stores/semesters.ts`
|
||
- `src/views/FncPage.vue`
|
||
- `src/views/Settings.vue`
|
||
- `src/language/*.json` 中與 starter home、maint、學生資料相關的文案
|
||
- `src/assets/logo.png`
|
||
- `src/assets/logo.svg`
|
||
- `src/assets/robot-svgrepo-com.svg`
|
||
|
||
刪除 demo/example 時，也要同步清理：
|
||
|
||
- `src/router/routes.ts`
|
||
- `src/stores/menu.ts` 中依賴的選單資料流程
|
||
- 相關 `src/language/*.json` 文案
|
||
- 不再被 import 的 demo components、composables、stores 與 assets
|
||
|
||
## 新頁面最小範例
|
||
|
||
```ts
|
||
// src/router/routes.ts
|
||
{
|
||
path: '/reports',
|
||
name: 'reports',
|
||
component: () => import('@/views/reports/Reports.vue'),
|
||
meta: { layout: 'default', requiresAuth: true },
|
||
}
|
||
```
|
||
|
||
```vue
|
||
<!-- src/views/reports/Reports.vue -->
|
||
<script setup lang="ts">
|
||
import ReportsTable from '@/components/reports/ReportsTable.vue'
|
||
</script>
|
||
|
||
<template>
|
||
<ReportsTable />
|
||
</template>
|
||
```
|
||
|
||
更多範例見 `docs/add-page-example.md`。
|
||
|
||
## 文件導覽
|
||
|
||
- `docs/add-page-example.md`：新增頁面範例。
|
||
- `docs/frontend-layering.md`：完整分層與責任邊界。
|
||
- `docs/llm-development-guide.md`：LLM 操作邊界。
|
||
|
||
## 驗證
|
||
|
||
```bash
|
||
pnpm type-check
|
||
pnpm build
|
||
```
|