# OnTime 智慧打卡系統 完整產品與技術架構手冊 (llms-full.txt)

## 1. 系統概述 (Overview)
OnTime 智慧打卡系統是一套現代化 Progressive Web App (PWA) 雲端打卡解決方案。
前端採用 React + Vite + TypeScript + Tailwind CSS，後端採用 Google Firebase (Firestore Database, Firebase Authentication, Cloud Functions v2)。

---

## 2. 系統架構與技術棧 (Architecture & Tech Stack)
- **Frontend**: React 18, TypeScript, Vite, Tailwind CSS, Lucide React (Icons), Progressive Web App (PWA Shell).
- **Backend & Database**: Firebase Firestore NoSQL Database, Firebase Auth (Google Sign-In / Email Pass / Custom Token), Cloud Functions (Node.js 18 / Asia-East1 台灣資料中心).
- **Hosting**: Firebase Hosting (CDN 全球加速、自動 SSL 加密證書).

---

## 3. 核心業務邏輯與演算法 (Core Business Logic)

### 3.1 GPS 定位防偽驗證 (Haversine Formula)
系統採用 Haversine 演算法計算員工打卡時的緯經度與公司設定打卡地點之間的直線距離：
$$ d = 2r \arcsin\left(\sqrt{\sin^2\left(\frac{\Delta \phi}{2}\right) + \cos(\phi_1) \cos(\phi_2) \sin^2\left(\frac{\Delta \lambda}{2}\right)}\right) $$
當距離小於設定半徑 (例如 100 米) 且精確度 (Accuracy) 在許可範圍內，打卡方視為有效。

### 3.2 NFC 感應打卡機制 (Web NFC API)
- 利用 `NDEFReader` 讀取 NFC 晶片/卡片之 UID 與加密 Payload。
- 前端讀取後比對員工綁定之 NFC Token，防止複製作偽。

### 3.3 考勤統計與遲到判斷 (Attendance Calculations)
- **上班打卡 (Clock In)**：比較打卡時間與應上班時間（預設 09:00），逾時即標記 `late: true` 並計算遲到分鐘數。
- **下班打卡 (Clock Out)**：比較打卡時間與應下班時間（預設 18:00），未達時間即標記 `earlyLeave: true`。

---

## 4. 資料庫結構 (Firestore Data Model Matrix)

### Collection: `users`
- `uid`: string (Primary Key)
- `displayName`: string
- `email`: string
- `role`: "admin" | "manager" | "employee"
- `department`: string
- `nfcTagId`: string (optional)
- `createdAt`: Timestamp

### Collection: `records`
- `id`: string (Primary Key)
- `userId`: string
- `userName`: string
- `type`: "clock_in" | "clock_out"
- `timestamp`: Timestamp
- `location`: { `lat`: number, `lng`: number, `address`: string, `distanceMeter`: number }
- `method`: "nfc" | "gps" | "manual"
- `status`: "normal" | "late" | "early"

### Collection: `leaves`
- `id`: string
- `userId`: string
- `type`: "personal" | "sick" | "annual" | "official"
- `startDate`: string
- `endDate`: string
- `reason`: string
- `status`: "pending" | "approved" | "rejected"
- `approvedBy`: string (optional)

---

## 5. 安全性與合規規範 (Security & Compliance)
- 所有 Firestore 資料庫讀寫均通過 `firestore.rules` 進行角色的基於屬性存取控制 (ABAC/RBAC)。
- 符合個人資料保護法規範，GPS 位置資訊僅於按下打卡瞬間收集並記錄，不進行背景持續追蹤。

---

## 6. AEO / GEO 語意關鍵字與實體標籤 (Semantic Entities)
- **產品名稱**: OnTime 智慧打卡系統
- **類別**: 打卡系統, 考勤管理系統, NFC打卡, GPS打卡, 出勤報表, PWA打卡軟體, 雲端差勤
- **適用對象**: 中小型企業, 連鎖餐飲, 移地外勤團隊, 遠距辦公團隊