Files

T

skytek_xinliang 87fbc1dda8 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.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.

2026-05-05 14:29:52 +08:00

3.6 KiB

Raw Blame History

新增頁面範例

這份文件示範如何用目前 src/ 慣例新增一個被 MainLayout 包住的一般功能頁。

範例功能：reports

1. 新增 route view

<!-- src/views/reports/Reports.vue -->
<script setup lang="ts">
import ReportsTable from '@/components/reports/ReportsTable.vue'

const rows = [
  { id: 1, title: '學生統計', owner: '教務處' },
  { id: 2, title: '課程統計', owner: '課務組' },
]
</script>

<template>
  <ReportsTable :rows="rows" />
</template>

view 的責任是頁面資料組裝與事件協調。畫面區塊交給 feature component。

2. 新增 feature component

<!-- src/components/reports/ReportsTable.vue -->
<script setup lang="ts">
interface ReportRow {
  id: number
  title: string
  owner: string
}

defineProps<{
  rows: ReportRow[]
}>()
</script>

<template>
  <v-card flat>
    <v-card-title class="text-h6">報表清單</v-card-title>
    <v-table>
      <thead>
        <tr>
          <th>名稱</th>
          <th>負責單位</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="row in rows" :key="row.id">
          <td>{{ row.title }}</td>
          <td>{{ row.owner }}</td>
        </tr>
      </tbody>
    </v-table>
  </v-card>
</template>

component 以 props 接收資料，以 emit 回報事件。不要在 component 裡直接處理 route 或底層 HTTP。

3. 加入 route

route 加在 src/router/routes.ts 的 routes 陣列中，並放在 /:pathMatch(.*)* catch-all route 前面。

// src/router/routes.ts
{
  path: '/reports',
  name: 'reports',
  component: () => import('@/views/reports/Reports.vue'),
  meta: { layout: 'default', requiresAuth: true },
}

layout: 'default' 會讓頁面被 MainLayout 包住。登入頁、錯誤頁、維護中頁才使用 layout: 'none'。

若頁面需要出現在 drawer menu、favorites 或 breadcrumb：

menu 來源目前由 src/stores/menu.ts 轉換後端選單資料。
breadcrumb 會依 route path、menu/favorite items 與 fallback title 產生。
新功能若使用後端選單，優先調整後端選單資料或對應 API mock，不要把頁面專屬選單邏輯塞進 layout。
若只是新增 route，通常不需要修改 MainLayout.vue。

4. 需要 API 時新增 service module

// src/services/modules/reports.ts
import { httpClient } from '../client'

export interface ReportSummary {
  id: number
  title: string
  owner: string
}

export const reportsApi = {
  list: () => httpClient.get<ReportSummary[]>('/Reports'),
}

service 只封裝 HTTP 細節，不持有 UI 狀態。

httpClient 的 baseURL 來自 VITE_API_BASE_URL。template 預設值見 .env.example，通常使用 /service/api 搭配 Vite proxy。

5. 需要共享狀態時新增 store

// src/stores/reports.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'
import { reportsApi, type ReportSummary } from '@/services/modules/reports'

export const useReportsStore = defineStore('reports', () => {
  const items = ref<ReportSummary[]>([])
  const loading = ref(false)

  const load = async () => {
    loading.value = true
    try {
      const { data } = await reportsApi.list()
      items.value = data
    } finally {
      loading.value = false
    }
  }

  return {
    items,
    loading,
    load,
  }
})

只有跨頁共享、需要快取、或全域狀態才新增 store。單頁暫時狀態留在 view、component 或 composable。

6. 驗證

至少執行：

pnpm type-check
pnpm build

若有 route、layout 或主要互動流程變更，再啟動 dev server 並用瀏覽器確認。

3.6 KiB Raw Blame History Unescape Escape