校園服務台代理技能 是做什麼的？
此技能定義了開發、增強和維護 校園服務台 網頁應用程式的技術標準、工作流程和最佳實踐。每當您新增功能、重構元件、更新狀態工作流程或修改此專案的資料模型時，請使用本指南。
1. 撰寫乾淨、可重複使用的 React 元件
維護模組化、低耦合的元件架構：
- 單一職責原則：每個元件必須做好一件事。
- 表單邏輯和輸入項歸屬於
IssueForm.jsx。 - 公開搜尋、篩選和工單卡片顯示歸屬於
TicketList.jsx。 - 分析指標、視覺進度條和管理表格歸屬於
AdminDashboard.jsx。 - 模態檢查和歷史時間軸歸屬於
TicketModal.jsx。 - 通知歸屬於
Toast.jsx。
- 表單邏輯和輸入項歸屬於
- Props 與 State 設計：
- 盡可能將狀態保持在區域範圍內。僅當狀態需要在不同視圖間共用時（例如全域的
tickets、activeTab、toasts），才將其提升至App.jsx。 - 盡可能使用純展示型子元件，並透過 props 清晰地傳遞回呼函式（
onSelectTicket、onUpdateStatus、onDeleteTicket）。 - 避免重複的狀態；使用
useMemo計算衍生值（例如篩選後的工單、KPI 統計）。
- 盡可能將狀態保持在區域範圍內。僅當狀態需要在不同視圖間共用時（例如全域的
- 命名慣例與乾淨程式碼：
- 元件檔案使用 PascalCase（
AdminDashboard.jsx、IssueForm.jsx）。 - 工具和常數檔案使用 camelCase（
storage.js、constants.js）。 - 事件處理函式應遵循
handle[Action]模式（例如handleSubmit、handleStatusChange）。 - 保留註解和文件字串。使用清晰具描述性的變數名稱撰寫不言自明的程式碼。
- 元件檔案使用 PascalCase（
- 零重量級外部依賴：
- 維持輕量化架構：使用原生 React 鉤子、純內嵌 SVG 作為圖示，以及範圍限定 CSS 類別，避免引入龐大的第三方元件庫。
2. 建立響應式且無障礙的使用者介面
校園服務台入口網站必須在所有裝置（手機、平板、筆電、大螢幕）上提供流暢的使用者體驗：
- 流暢版面與中斷點：
- 採用行動優先或桌面優先設計，搭配一致的中斷點：
- 桌面：最大容器寬度
1240px，使用多欄網格（5 個指標卡片、2 欄分析圖表、2 欄表單）。 - 平板（
<= 1024px）：將 5 欄指標網格折疊為 3 或 2 欄；將分析圖表堆疊成單欄。 - 手機（
<= 768px）：將頁首導覽、表單輸入項堆疊為 1 欄；啟用資料表格的水平捲動。 - 小螢幕（
<= 480px）：全寬指標卡片、堆疊的操作按鈕，以及固定在底部的 Toast 通知。
- 桌面：最大容器寬度
- 採用行動優先或桌面優先設計，搭配一致的中斷點：
- 無障礙性（a11y）：
- 所有互動元素必須使用適當的語意化 HTML（
<button>、<input>、<select>、<textarea>）。 - 表單控制項必須有對應的
<label htmlFor="...">元素，並搭配相符的id屬性。 - 模態對話框必須具有
role="dialog"、aria-modal="true"，並支援透過背景點擊和 Escape 鍵關閉。 - 互動式圖示或僅圖示按鈕必須包含具描述性的
aria-label或title屬性。 - 維持狀態徽章和優先級標籤上文字的可及性色彩對比度。
- 所有互動元素必須使用適當的語意化 HTML（
- 視覺回饋與轉場效果：
- 互動元素必須清楚顯示
:hover、:focus和:active狀態。 - 聚焦的表單欄位必須顯示高對比的焦點環（
var(--primary-ring)）。 - 使用微動畫（Toast 滑入、模態框縮放、按鈕旋轉器）來通知使用者背景動作，而不造成版面位移。
- 互動元素必須清楚顯示
3. 驗證學生問題表單
所有透過 IssueForm.jsx 提交的問題，在進行狀態變更或儲存之前，必須遵循嚴格的客戶端驗證規則：
驗證規則矩陣
| 欄位 | 規則 | 錯誤訊息 |
|---|---|---|
| 姓名 | 必填，去除前後空白後不可為空 | "請提供您的姓名。" |
| 校園電子郵件 | 必填，符合正則表達式 /^[^\s@]+@[^\s@]+\.[^\s@]+$/ | "請輸入有效的電子郵件地址。" |
| 地點/房間 | 必填，去除前後空白後不可為空 | "請指定建築物、大廳或校園位置。" |
| 類別 | 必填，必須與 CATEGORIES 清單相符 | 預設自動選取 |
| 優先級 | 必填，必須與 PRIORITIES（低、中、高、緊急）相符 | 預設值為 '中' |
| 問題主旨/標題 | 必填，去除前後空白後，長度 $ | |
| ge 5$ 個字元 | "標題長度至少需要 5 個字元。" | |
| 詳細描述 | 必填，去除前後空白後，長度 $ | |
| ge 15$ 個字元 | "描述的長度至少需要 15 個字元。" |
驗證實作步驟
- 維護一個
errors狀態物件，將欄位名稱對應到錯誤字串。 - 當使用者修改某個欄位的輸入時（
handleChange），清除該欄位的特定錯誤。 - 在
handleSubmit時檢查所有規則。如果存在錯誤，則阻止提交，並使用.input-error和.field-error高亮顯示無效欄位。 - 成功時：
- 產生唯一 ID（例如
TCK-XXXX）。 - 指派初始狀態為
待處理。 - 記錄初始提交時間戳記和歷史節點。
- 重設表單欄位和錯誤狀態。
- 觸發成功 Toast 通知，並導航至工單追蹤器視圖。
- 產生唯一 ID（例如
4. 管理待處理、處理中和已解決狀態
校園服務台遵循嚴格的 3 階段生命週期：
[ 待處理 ] ───► [ 處理中 ] ───► [ 已解決 ]
▲ ▲ │
└──────────────────────┴─────────────────────┘ (必要時可重新開啟)
狀態定義與視覺設計系統
待處理：- 意義：由學生/員工提交的新問題，等待分類或指派。
- 色彩主題：琥珀色（
#d97706），背景#fef3c7，邊框#fde68a。 - 進度階段：步驟 1 啟用。
處理中：- 意義：技術人員或校園部門已認領該工單，並正在積極調查或修復。
- 色彩主題：皇家藍（
#2563eb），背景#dbeafe，邊框#bfdbfe。 - 進度階段：步驟 1 和 2 啟用。
已解決：- 意義：修復完成、設備更換或服務恢復。
- 色彩主題：翡翠綠（
#059669），背景#d1fae5，邊框#a7f3d0。 - 進度階段：步驟 1、2 和 3 啟用。
生命週期規則與稽核歷史
- 每次狀態轉換都必須將一個事件附加到工單的
history陣列：{ status: newStatus, timestamp: new Date().toISOString(), note: `狀態已更新為 ${newStatus}` } - 更新內部工作人員備註必須更新
adminNote和updatedAt，而不重設工單原始的createdAt。 - 更新必須立即同步至
localStorage（campus_helpdesk_tickets_v1）。
5. 維持儀表板統計資料的準確性
管理儀表板提供即時的營運可視性。所有 KPI 指標和圖表計算都必須從單一事實來源 tickets 陣列動態衍生：
指標計算
- 總工單數： $$\text{總數} = \text{tickets.length}$$
- 待處理數量： $$\text{待處理} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
- 處理中數量： $$\text{處理中} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
- 已解決數量： $$\text{已解決} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
- 解決率 (%)： $$\text{解決率} = \begin{cases} \text{Math.round}\left(\frac{\text{已解決}}{\text{總數}} \times 100\right), & \text{if 總數} > 0 \ 0, & \text{otherwise} \end{cases}$$
- 高與緊急優先級佇列： $$\text{緊急/高} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Urgent' \lor t.\text{priority} === 'High').\text{length}$$
- 類別與優先級分佈：
- 即使計數為 0，也要計算所有預定義類別和優先級的計數，以防止 UI 閃爍或除以零。
- 確保進度條寬度百分比總和 $\le 100%$。
將所有統計計算包裝在 React 的 useMemo 鉤子中，並以 [tickets] 作為依賴項，以維持效能。
6. 測試變更和執行建置
在提交任何程式碼變更或將任務標記為完成之前，請透過靜態分析和生產環境建置步驟驗證應用程式：
驗證協議
-
導航至專案目錄：
cd "campus-helpdesk" -
執行靜態程式碼檢查：
npm run lint- 必須以退出碼
0結束。 - 確保沒有未使用的導入、變數或未跳脫的 JSX 實體。
- 必須以退出碼
-
執行生產環境建置：
npm run build- 驗證 Vite 是否順利完成生產環境資產捆綁，沒有任何錯誤或警告。
- 驗證
dist/index.html、dist/assets/*.css和dist/assets/*.js是否成功建立。
-
驗證 LocalStorage 持久性：
- 測試提交工單是否更新
localStorage.getItem('campus_helpdesk_tickets_v1')。 - 測試更新工單狀態在頁面重新整理後是否仍然保留。
- 測試「重設範例資料」和「全部清除」功能。
- 測試提交工單是否更新
7. 誠實回報錯誤
在回報系統狀態或錯誤時，正直和誠實至關重要：
- 不要掩蓋失敗：如果發生建置錯誤、語法錯誤或 lint 失敗，請報告確切的錯誤訊息、檔案名稱和行號。
- 根本原因解釋：解釋錯誤發生的原因（例如缺少導入、儲存解析器中未處理的 null 情況、損壞的 prop 合約）。
- 僅報告已驗證的修復：在未重新執行驗證命令（
npm run lint/npm run build）並確認退出碼為0之前，不要聲稱問題已解決。 - 對使用者透明：如果發生意外的瀏覽器限制或 localStorage 配額問題，請主動向使用者解釋該限制，並提供明確的技術選項。