TimePlate 完整使用者手冊

版本： 1.0.1 最後更新： 2026 年 6 月 適用： TimePlate iOS / Android App 涵蓋模式： 管理員模式 (Admin) | 員工模式 (Employee) | 簡易模式 (Simple) 產品： SlashHub Limited

---

免責聲明

TimePlate 係 SlashHub Limited 嘅軟件產品。SlashHub Limited 並非閣下嘅僱主，不負責人工計算、勞工法例合規、或 GPS／藍牙／人臉辨識嘅準確性。所有打卡記錄、工時、合規數據應由貴公司獨立核對。如需協助請聯絡 support@slashhub.hk。

---

目錄

1. 開始使用
2. 註冊與加入餐廳
3. 登入與身份驗證
4. 離線模式與網絡狀態
5. 通知系統
6. 三大模式總覽
7. 打卡驗證流程（所有模式通用）
8. 管理員模式 (Admin)
9. 員工模式 (Employee)
10. 簡易模式 (Simple)
11. 帳號設定
12. 建立新公司（四步驟精靈）
13. 權限控制管理（老闆專用）
14. 訂閱與方案
15. 常見問題 FAQ
16. 疑難排解
17. 附錄

---

1. 開始使用

1.1 下載與安裝

1. iOS： 喺 App Store 搜尋「TimePlate」→ 點「取得」/「下載」。
2. Android： 喺 Google Play Store 搜尋「TimePlate」→ 點「安裝」。
3. 首次開啟會見到藍色 Splash 畫面 + TimePlate logo，然後自動跳轉到登入畫面。

1.2 語言切換

TimePlate 支援 English 同 繁體中文（香港）。任何時候：

• 登入畫面： 右上角 🌐 地球 icon → 即時切換 EN ↔ 中文
• 已登入： 帳號頁面 → 語言 → 揀 English 或 繁體中文

語言會記住，下次開 App 維持不變。

---

2. 註冊與加入餐廳

2.1 註冊新帳號

步驟：登入畫面 → 點右上角「Create Account / 註冊」

1. 選擇身份：
   • 老闆 (Owner) — 建立新公司，之後再邀請員工
   • 員工 (Employee) — 使用邀請碼加入現有公司
2. 填寫：
   • 姓名（自動大階首字母）
   • 電郵地址（email keyboard）
   • 密碼（6 個字元以上）
3. 根據角色：
   • 老闆：填寫「公司名稱」
   • 員工：填寫「邀請碼」（由管理員提供，系統會自動轉大階）
4. 同意三項法律條款（剔選框）：
   • EULA（終端用戶許可協議）
   • Terms of Service（服務條款）
   • Privacy Policy（私隱政策）
   • 撳條款文字會打開 LegalModal 彈窗詳細閱讀
5. 點 「Create Account」（老闆）或 「Join Company」（員工）。

完成後：

• ✅ 畫面顯示綠色剔 +「Account Created!」
• 老闆：「Your restaurant "XXX" is ready」— 下一步登入
• 員工：「You have joined "XXX"」— 下一步登入
• ⚠️ 註冊唔會自動登入，你要撳「Go to Login」去登入畫面

2.2 加入餐廳（已註冊、第一次登入後）

登入後如果未綁定任何餐廳，會自動跳去「Join Restaurant」頁：

方法一：邀請碼（建議）

1. 喺「有邀請碼？」輸入管理員俾你嘅 10 位英數字碼（例如 ABC123XYZ9）。
2. 點「加入」。
3. 成功 → 綠色剔提示 + 自動 redirect 到主畫面。
4. 失敗 → 紅色錯誤訊息（過期 / 用盡 / 無效）。

方法二：手動搜尋

1. 點「無邀請碼？用手動搜尋」展開。
2. 輸入 公司 ID + 分店 ID（管理員提供）。
3. 點「搜尋」。
4. 確認公司名 + 分店名 + 地址正確。
5. 點「Send Join Request」。
6. 管理員會喺 Admin → Join Requests 審批。

查看申請狀態

頁面下方「My Join Requests」區塊：

• 🟡 Pending — 等待管理員批准
• 🟢 Approved — 已批准，自動加入
• 🔴 Rejected — 被拒絕

---

3. 登入與身份驗證

3.1 登入方法

3.2 登入畫面詳細操作

1. 頂行：
   • 左：「Create Account」按鈕（跳註冊）
   • 右：🌐 語言切換
2. 時鐘 icon + Title： TimePlate logo、登入標題、副標題
3. 表單卡片：
   • 如果之前有 session（未過期）：顯示「指紋 / Face ID 登入」大掣
   • 錯誤提示（紅色 banner，例如密碼錯、超過嘗試次數）
   • 輸入框：
     • 電郵或電話（自動識別，電話模式會顯示區號選擇器）
     • 密碼（可點眼睛 icon 顯示／隱藏）
   • 選項：
     • ☐ 記住我 — 儲存 email 方便下次登入
     • ☐ 生物識別 — 啓用 Face ID / 指紋快速登入（需要裝置支援）
4. 登入按鈕： 藍色全寬，disabled 直到輸入完整
5. 法律條款連結（EULA / 服務條款 / 私隱政策）

3.3 多間餐廳選擇畫面

如果你同時屬於多間餐廳，登入後會見到「Select Restaurant」：

• 每間餐廳卡片顯示：彩色底、餐廳名縮寫（大字母 icon）、名字、角色徽章（Owner / Manager / Staff）
• 你嘅角色顏色：Owner = 綠色、Manager = 藍色、Staff = 灰色
• 撳任何一張即切換到該餐廳
• 底部「Use another account」可登出用另一個帳號

3.4 生物識別（Face ID / 指紋）

啓用方法：

1. 登入畫面 → 剔選「生物識別」；或
2. 帳號頁 → 安全性 → Biometric Login 開關

使用：

• 下一次開 App 時，如果 Firebase session 未過期，會自動顯示生物識別登入掣
• 一按即 Face ID / 指紋驗證 → 直接入主畫面

安全提示：

• 密碼唔會儲存喺裝置上
• 如果 Firebase session 過期（一段長時間無用過），會要求用密碼重新登入

3.5 連線錯誤畫面

如果登入後出現「Connection Error」：

1. 檢查手機網絡連線
2. 撳「Retry」重新載入
3. 仍然唔得 → 撳「Sign Out」重新登入
4. 聯絡管理員確認後台服務正常

---

4. 離線模式與網絡狀態

4.1 網絡狀態指示器

App 頂層包咗一個 NetworkBanner 組件，會顯示：

4.2 離線排隊機制

• 當離線時打卡，系統會將打卡請求放入 offline queue
• 連返線時 自動 flush 佢哋去伺服器
• 你也可以撳琥珀色橫額手動強制同步
• Queue 滿（超過上限）：最舊嘅請求會被丟棄，顯示黃色 toast 提示
• 衝突（伺服器回報 409）：顯示藍色 info toast「{類型} duplicate skipped」
• ⚠️ 切換餐廳時：offline queue 會被清空，避免跨公司資料混亂

---

5. 通知系統

5.1 運作方式

• 系統每 30 秒 自動向伺服器查詢新通知（GET /api/notifications）
• 每條新通知會以 toast 形式顯示 5 秒
• 同一 session 內唔會重複顯示同一條通知

5.2 通知顏色對應

5.3 收取通知注意事項

• 需要手機系統通知權限（iOS：設定 → TimePlate → 通知 → 允許）
• 需要在 App 帳號頁開「Toast 通知」開關
• 離線時唔會收到通知，直到網絡恢復

---

6. 三大模式總覽

6.1 模式對應角色

6.2 模式切換方式

6.3 模式功能矩陣

                    ┌──────────┬──────────┬──────────┐
                    │  Admin   │ Employee │  Simple  │
├───────────────────┼──────────┼──────────┼──────────┤
│ 打卡 (Check-in/out)│    ✓     │    ✓     │    ✓     │
│ 休息 (Break)      │    ✓     │    ✓     │    ✓     │
│ 自己班表          │    ✓     │    ✓     │    ✓     │
│ 自己假期          │    ✓     │    ✓     │    ✓     │
│ 同事更表          │    ✓     │    ✓     │    ✓     │
│ 請假              │    ✓     │    ✓     │    ✓     │
│ 換班申請          │ feature  │ feature  │ feature  │
│ 月度統計圖表      │    ✓     │    ✓     │    ✗     │
│ Live Attendance   │    ✓     │    ✗     │    ✗     │
│ 排班 (Schedules)  │    ✓     │    ✗     │    ✗     │
│ 員工管理          │    ✓     │    ✗     │    ✗     │
│ 審批 (Approvals)  │    ✓     │    ✗     │    ✗     │
│ 報表 (Reports)    │    ✓     │    ✗     │    ✗     │
│ 店舖設定          │    ✓     │    ✗     │    ✗     │
│ 訂閱管理          │    ✓     │    ✗     │    ✗     │
│ 活動紀錄 (Log)    │    ✓     │    ✗     │    ✗     │
│ 人臉註冊          │    ✓     │    ✓     │    ✓     │
│ 工資單 (Payslips) │ feature  │ feature  │    ✗     │
│ 報銷 (Expense)    │ Admin審批 │ Employee申請│ ✗     │
└───────────────────┴──────────┴──────────┴──────────┘

---

7. 打卡驗證流程（所有模式通用）

呢個係 TimePlate 最重要嘅功能。打卡嘅流程根據店舖設定唔同，可以有以下驗證步驟。

7.1 一鍵打卡（最快，無需任何驗證）

如果店舖設定無驗證要求：

1. 撳藍色「Check In」大按鈕
2. ✅ 即時成功，畫面顯示紀錄

7.2 需要驗證嘅完整流程

按打卡掣
  │
  ├─ [需要 GPS?]
  │    └─ 取得位置 → 比對坐標/半徑 → 在範圍? → 是 → 下一步
  │                                              → 否 → 錯誤提示
  │
  ├─ [需要 BLE / Beacon?]
  │    └─ 掃描藍牙 → 找到對應裝置 → 下一步
  │                  找不到 → 可跳過 (Skip) 或繼續掃描
  │
  ├─ [需要人臉辨識?]
  │    └─ 開相機 → 3 秒倒數 → 自拍 → 上傳 → 比對 → 分數夠 → 下一步
  │                                                     分數低 → 再影 / Skip
  │
  └─ 提交 (Submitting)
       └─ 成功 → ✅ 綠色確認
           失敗 → 錯誤訊息

7.3 驗證方式詳細說明

7.3.1 GPS 位置驗證

• 原理： App 取得手機 GPS 坐標，同店舖設定嘅坐標 + 半徑比對（Haversine 公式）
• 權限： 需要位置權限（使用 App 期間）
• 流程：
  1. 系統自動請求位置權限（如未俾）
  2. 取得位置（expo-location high accuracy）
  3. 自動計算距離
  4. 在範圍內 → 自動 confirm，去下一步
  5. 範圍外 → 顯示錯誤 toast + 震動，跳返 idle
• 管理員設定： Settings → 揀分店 → Basic → lat/lng + radius（預設 100m）

7.3.2 藍牙 Beacon (BLE) 驗證

• 原理： App 掃描附近藍牙裝置，匹配店舖設定嘅 device name / UUID
• 組件： BleScanner（可嵌入任何頁面）
• 流程：
  1. 畫面顯示藍色虛線卡 + 藍牙 icon +「Scan」按鈕
  2. 撳 Scan → 開始 15 秒掃描，顯示「Searching...」+ 找到裝置數
  3. 找到匹配裝置 → 自動停止 → 綠色「✅ Connected:{name}」
  4. 找不到 → 可撳「Skip BLE →」跳過（如果店舖容許）
  5. 或撳「Can't use BLE?」切換到手動輸入模式（輸入 manager 提供嘅 code）
• Android 備註： Android 12+ 需要 BLUETOOTH_SCAN / BLUETOOTH_CONNECT / ACCESS_FINE_LOCATION 權限
• 唔支援 BLE 裝置： 會顯示琥珀色提示

7.3.3 人臉辨識驗證

• 原理： App 用前置鏡頭拍 selfie → 上傳 → 同已註冊嘅 face image 比對 → 回傳相似度分數
• 組件： CameraCapture
• 流程：
  1. 如果 BLE 已通過，會顯示綠色「✓ Bluetooth Verified」提示
  2. 相機自動開啟（facing="front"，倒影顯示）
  3. 畫面中央有白色圓圈做對位引導
  4. 3 秒倒數（3 → 2 → 1）後自動拍攝
  5. 預覽相片：
     • ✅「Captured」（確認）— 呢個只係視覺確認，無動作
     • 🔄「Retake」— 重新拍攝
     • ❌ X 關閉 — 取消拍攝、清除相片
  6. 撳「Next」（由 parent 控制）— 開始上傳：
     • Upload 到 GCS（presigned URL）
     • 再 call POST /api/face/verify
     • 回傳 face score（相似度 %）
  7. 分數達標 → ✅ 通過，去下一步
  8. 分數太低 → 可撳「Skip」跳過（如店舖容許）
• 事前準備： 員工必須先喺帳號頁註冊人臉照（見 11.2）
• 權限： 需要相機權限

7.3.4 NFC 驗證 / QR Code 驗證

• NFC： 手機輕貼店內 NFC tag（需要裝置支援 NFC）
• QR Code： App 掃描店內 QR code
• 呢兩種方法由店舖設定決定是否啓用，打卡時會自動顯示對應步驟

7.4 多更 (Split Shifts)

今日完成 check-out 後，可以再開新一更：

1. 綠色「今日完成」卡片下有「Start New Shift #2」按鈕
2. 撳一下 → 打卡按鈕重新變藍色 → 可以再 check-in
3. 每日可以有多個 shift，系統會分別紀錄每更嘅 check-in / out 時間同工時
4. Dashboard 嘅今日摘要會列出全部更次

7.5 休息 (Break) 功能

需要 break_tracking feature flag 解鎖

操作：

1. Check-in 後，打卡掣下方出現「☕ 開始休息 (Start Break)」灰色掣
2. 撳一下 → 休息開始（按鈕變黃色「結束休息 (XX min)」）
3. 再撳一下 → 休息結束，返回工作
4. 如果撳 Check Out 而目前係休息中 → 系統自動先結束休息、再執行 check-out 驗證流程

計算方式：

• 總工時 (Total Hours) = check-in 到 check-out 嘅總時間
• 淨工時 (Net Hours) = 總工時 − 休息總時間
• 儀表板上會顯示「Working Hours: HH:MM」即時倒數

7.6 安全機制

• Idempotency Key： 每次打卡用 UUID，確保重複提交唔會產生重複記錄
• Scope 保護： 當用戶快速切換餐廳時，回傳嘅資料如果係舊餐廳嘅，會被自動捨棄
• 離線隊列： 離線時打卡請求會排隊，但切換餐廳時會清空避免跨公司混亂

---

8. 管理員模式 (Admin)

適用於：Owner（老闆）& Manager（經理）

8.1 底部導航 5 Tab

┌─────────┬──────────────┬────────────────────────────┐
│ 圖示    │ Tab 名稱     │ 路由                       │
├─────────┼──────────────┼────────────────────────────┤
│ 📊      │ Dashboard    │ /(admin)/                  │
│ 🕒      │ Live         │ /(admin)/live-attendance    │
│ 📅      │ Schedules    │ /(admin)/schedules          │
│ 👥      │ Employees    │ /(admin)/employees           │
│ ▦       │ More         │ /(admin)/more                │
└─────────┴──────────────┴────────────────────────────┘

右上角一律有兩個按鈕：👤 個人帳號 ｜ 🕒 切換到員工打卡模式

8.2 儀表板 (Dashboard)

路徑：第 1 個 tab

8.2.1 頂部資訊列

• 姓名 + 角色徽章（Owner = 琥珀色 / Manager = 靛色）
• 餐廳名
• 右上：👤 帳號 / 🕒 切換員工模式
• 多餐廳時：顯示「Switch ›」切換條

8.2.2 四張統計卡

1. 店舖數 (Stores) — 藍色 icon
2. 員工數 (Employees) — 紫色 icon
3. 已打卡 (Checked-in) — 綠色 icon
4. 準時率 (On-time Rate) — 翠綠色 icon（百分比）

8.2.3 今日狀態 (Today's Status)

• ✅ 準時人數
• ⚠️ 遲到人數
• ❌ 缺席人數
• 下面有圓餅圖顯示比例

8.2.4 週趨勢 (Weekly Trend)

• 柱狀圖顯示過去 7 日打卡量
• 用 BarChart 組件渲染

8.2.5 店舖快捷列

• 顯示所有分店名 chips
• 撳任何一間→跳去 Settings

8.2.6 快速連結 (Quick Links)

六張卡片捷徑：

1. 管理員工 👥
2. 管理班次 📅
3. 即時出勤 🕒
4. 假期審批 ✅
5. 報表分析 📈
6. 店舖設定 ⚙️

下拉刷新： 重新載入所有數據。

8.3 即時出勤 (Live Attendance)

路徑：第 2 個 tab (/live-attendance)

8.3.1 畫面結構

• 頂部： 店舖過濾 chips（All + 各分店名）| 右上角平面圖 icon
• 主體： 每位員工一張卡片
• 額外操作： useRefreshOnFocus + 每分鐘自動更新工作時數

8.3.2 員工狀態

8.3.3 平面圖視角 (Floor View)

• 右上角 layout icon 切換
• 改成格仔顯示 (grid)，每格係一個員工
• 仍在開發中嘅 stations 支援

8.3.4 權限檢查

• 如果角色唔係 owner / manager → 顯示「Forbidden」訊息
• 非管理員自動跳轉去員工模式

8.4 排班 (Schedules)

路徑：第 3 個 tab (/schedules)

8.4.1 畫面結構

┌──────────────────────────────────┐
│  Header: Building2 + "Schedules" │
│  [Copy] [Shift Manager] [Assign] │
├──────────────────────────────────┤
│  店舖 chips 橫向滑動              │
├──────────────────────────────────┤
│  4 統計卡：員工/已排班/班次/總時數│
├──────────────────────────────────┤
│  ← 週導航 →   覆蓋率迷你 bar     │
├──────────────────────────────────┤
│  🔍 搜尋員工  展開/摺疊          │
├──────────────────────────────────┤
│  網格：                           │
│  員工 x 日期 = 班次彩格           │
├──────────────────────────────────┤
│  批量指派面板 (可 toggle)         │
└──────────────────────────────────┘

8.4.2 每週導航

• ← 前一週 / → 後一週（7 日為單位）
• 顯示日期範圍 YYYY-MM-DD ~ YYYY-MM-DD
• 每週覆蓋率 mini bar（紅色 = 人手不足 < 40%）

8.4.3 排班網格 (Schedule Grid)

• 頂行：7 日標題（星期 + MM-DD）+ 每曰覆蓋人數
• 正文：每列 = 一個員工，每格 = 該日班次
• 班次以顏色區分（shift color map）
• 每格顯示：班名 · 時間 · 時數
• 每日每人只能一個班次（如有衝突會標示）
• 最後一列 = 本週總工時（超過 40h 會變琥珀色）

展開/摺疊： 點「員工 (n) 展開/摺疊」→ toggle 完整 7 日 / 淨係今日

8.4.4 單一格操作

• 點一下班次格 → 打開 Edit Schedule Modal（可改班次或刪除）
• 長按班次格 → 直接確認刪除

8.4.5 批量指派面板 (Batch Assign)

撳右上角「Assign Shifts」按鈕 toggle 面板，有三個 steps：

Step 1：揀員工

• 所有員工變成可選 chips
• 顯示 n/total 計數
• 「Select all / Deselect all」連結
• 如有多個部門：部門 chips 可一次揀晒

Step 2：揀班次

• 上半：班次模板（From template）— 撳一下自動建立對應 shift
• 下半：現有班次（存入住 shift）— 大卡片顯示

Step 3：揀日子

• 7 日 chips（Mon-Sun + Date）
• 快速設定按鈕：
  • 🏢 週一~五 — 揀 Mon-Fri
  • 🏖️ 週末 — 揀 Sat-Sun
  • 📅 全部 — 揀晒 7 日
  • ❌ 清除 — 全部取消

確認排班：

• 顯示「n 人 × m 天 = total shifts」
• 如有衝突，顯示 ⚠️ 「X 個衝突」+ Alert 可選擇繼續或取消
• 撳「確認排班」→ POST batch → 成功 toast → 網格即時更新

8.4.6 複製 / 移動整週

撳 📋 Copy icon → 打開 Copy/Move Modal：

• Copy（複製）：將本週所有排班複製到下一週（保留本週）
• Move（移動）：搬過去後刪除本週原稿
• 如有目標週已存在嘅排班 → 顯示「X already exist, skipped」
• 確認後執行 batch POST

8.4.7 班次管理員 (Shift Manager)

撳 ⏰ Shift Manager icon → 打開 Modal：

新增班次：

• 名稱（例如「早班」、「晚班」）
• 開始時間（HH:MM 24h）
• 結束時間（HH:MM 24h）
• 遲到容許分鐘 (Grace Minutes)
• 所屬店舖（Modal 內揀）

現有班次列表（按店舖分組）：

• 每個班次：顏色 dot + 名稱 + 時間 + 容許分鐘
• ✏️ 編輯
• 🗑️ 刪除（Owner only — 如果唔係 Owner 會彈 Alert「Restricted」）

8.4.8 搜尋員工

🔍 搜尋框（「Search in {shop}」）+ ❌ 清除 → 過濾員工

8.4.9 權限

• Manager 可以排班、編輯班次
• 唯一限制： Manager 唔可以刪除班次（Delete 掣只對 Owner 顯示）

8.5 員工管理 (Employees)

路徑：第 4 個 tab (/employees)

8.5.1 員工列表

每位員工卡片顯示：

• 圓形 avatar（姓名首字母 / 大頭相）
• 姓名 + 角色徽章 + 雇用類型徽章
• 所屬店舖列表（chips）
• 部門、職位
• 🟢 在線（已 check-in）/ ⚪ 離線
• ✏️ 編輯 icon

8.5.2 頂部操作

• 店舖 tab 過濾（橫向滑動）+「All」chip
• 🔍 搜尋框 — 按姓名過濾
• 📋 Bulk Mode — 啓用後可多選員工做批次操作
• ➕ 新增員工 — 跳轉到 Employee Detail Add Mode

8.5.3 進階篩選 (Filter)

撳 Filter icon → 顯示篩選面板：

• 雇用類型： 全職 / 兼職 / 實習 / 臨時 / 合約
• 角色： 員工 / 經理 / 老闆
• 排序： 姓名 / 部門
• 顯示老闆： 開關（預設隱藏）

8.5.4 編輯員工資料

撳 ✏️ → 打開行內編輯：

• 基本資料： 姓名、員工編號
• 工作資料： 部門、職位、雇用類型
• 店舖分配： 可選多間（multi-select chips）+ 主要店舖 (Primary Shop)
• 點「Save」儲存

8.5.5 批次操作 (Bulk Mode)

1. 點右上角 ☑️ CheckSquare → 開 Bulk Mode
2. 每個員工左邊出現剔選框
3. 揀好之後底部浮起「Bulk Action」列：
   • 🏷️ 批次改雇用類型
   • 🏢 批次指派店舖
   • 🗑️ 批次刪除（Owner only）

8.5.6 員工詳情頁 (Employee Detail)

路徑：點任何員工卡片進入 (/employee-detail?uid=...)

頂部：

• 返回箭頭
• 角色徽章 + 雇用類型徽章 + 員工編號
• 👑 轉讓所有權（Owner only，撳後確認 Alert）
• 🗑️ 刪除員工（確認 Alert）

今日狀態：

• 🟢 綠色 — 已 check-out（顯示 Check-in → Check-out、工時、淨工時）
• 🟡 黃色 — 已 check-in（顯示時間 + 即時工時）
• 如休息中 → 額外顯示「休息中」徽章

快速操作列：

• 代簽入（綠色） — 幫員工補簽入（Proxy Check-in）
• 代簽出（橙色） — 幫仲喺度嘅員工簽出（Proxy Checkout）
• 編輯 ✏️ — Edit mode toggle

四張資料卡：

1. 聯絡資料： Email（可點 ⇒ mailto:）、電話（可點 ⇒ tel:）、入職日期
2. 工作 & 薪酬（藍紫高亮）： 部門、職位、時薪 HK$/h、月薪 HK$/月
3. 假期配額（進度條）： 年假 🟦（藍）/ 病假 🟥（紅）/ 私人 🟧（琥珀），各上限 20 日
4. 人臉識別（如有）： 56×56 人臉相 +「已登記臉部」

所屬分店： chips 列表 / 「未分配分店」

打卡統計：

• 準時率 %
• 三格數字：準時 / 遲到 / 缺席
• 平均每日工時
• 最近 5 條記錄（狀態 + 日期 + 時間 + 工時）

快速連結：

• 跳去 /attendance（出勤紀錄）
• 跳去 /live-attendance（即時出勤）
• 跳去 /reports（報表）

8.5.7 預覽 Edit Mode（員工詳情頁）

• 切換編輯模式後顯示完整表單
• 可以改晒所有基本資料 + 工作資料 + 薪酬 + 假期配額
• 一鍵「Save」

8.5.8 Add Mode（新增員工）

1. 從 Employee 列表撳 ➕ 或直接導航 /employee-detail?add=1
2. 揀驗證方法：電郵 / 電話 / 兩者
3. 填寫：
   • 姓名（必填）
   • 電郵 / 電話（根據驗證方法）
   • 角色：Staff / Manager
   • 雇用類型：全職 / 兼職 / 實習 / 臨時 / 合約
   • 店舖分配（multi-select）
   • 部門、職位、員工編號
   • 時薪、月薪
   • 假期配額
4. 撳「Save」→ POST /api/auth/register → 系統自動產生帳號同初始密碼
5. 可以撳「Clear」重置表單

8.6 更多 (More) 頁

路徑：第 5 個 tab (/more)

呢頁係所有進階功能嘅入口，按功能分組顯示為圖標格仔（2 列排列）：

8.6.1 管理 (Management)

8.6.2 分析 (Analytics)

8.6.3 團隊 (Team)

8.6.4 匯入與歷史 (Import & History)

8.6.5 業務 (Business)

8.6.6 設定 (Configuration)

底部：

• 👤 個人資訊卡（姓名、email、角色）+「View」按鈕跳帳號
• 🕒 「員工身份」按鈕 — 一鍵切換去 Employee Mode 打卡

8.7 設定 (Settings)

路徑：More → Settings (/settings) 角色：Owner / Manager

呢個係全 App 最複雜嘅設定頁面，每間店舖獨立設定。

8.7.1 頂部

• 標題「Settings」+ 角色徽章（Owner 琥珀 / Manager 藍）
• 右上：
  • Cancel（紅色，只有 draft 存在時顯示）— 清除所有未儲存變更
  • + New Store — 開 Create Store Modal（Owner + Manager 可用）

8.7.2 店舖 Tab 列

橫向滑動，每間店舖一個 pill：

• 名稱 | Unsaved（如有未儲存變更）
• 🗑️ 垃圾桶（刪除店舖，Owner + Manager 可用）
• 撳任何一個 tab → 切換到該店嘅設定

8.7.3 每個店舖嘅 Basic Tab

基本資料：

• 店舖名稱（TextInput）
• 地址（TextInput）
• Active / Disabled 撥動開關
• 負責經理：chips（None + 所有 manager/owner）

打卡驗證方法：

• GPS — 可開關（至少保留一個，系統唔會讓你全部關閉）
• BLE — 需要 subscription（否則顯示 💡 提示 toast）
• Face — 需要 subscription
• 已鎖定嘅方法會變暗，點擊會顯示「Requires higher plan」提示

8.7.4 Advanced Tab

店舖功能 (Shop Features)：

• 8 個可開關功能 chips：
  • Break Tracking（休息追蹤）
  • Overtime（加班計算）
  • Shift Swap（換班）
  • Schedule Management（更表管理）
  • Leave Management（假期管理）
  • Expense（報銷）
  • Pay Slips（糧單）
  • Employment History（雇用歷史）
• 被 plan 鎖定嘅 feature 會顯示 💡 提示

硬件設備 (Hardware Devices)：

• NFC Tag ID — 輸入框 + 🔄 refresh（生成 UUID）
• BLE Device Name — 輸入框
• QR Code Token — 輸入框 + 🔄 refresh

GPS & 位置 (GPS & Location)：

• 地理圍欄半徑（米，預設 100）
• 緯度、經度輸入
• 🧭 Navigation icon → 請求位置權限 → 自動填入目前位置
• 時區顯示（預設 Asia/Hong_Kong）

Stations（崗位）：

• 用 chips 顯示已有 stations
• 輸入框 + ➕ 按鈕新增
• ❌ 移除

Closing Checklist（收工清單）：

• 用 chips 顯示 item（✅ + 標籤 + ❌）
• 輸入框 + ➕ 按鈕新增

邀請碼 (Employee Invite Code)：

• 大號粗體追蹤字型顯示該店專屬邀請碼
• 📋 Copy — 彈出 Alert 顯示 code
• 🔄 Refresh — 重新產生新碼（舊碼即時失效）
• 如未有 code → 顯示「Generate Invite Code」按鈕

8.7.5 儲存

• 每間店獨立一個儲存掣（喺 card 內部底部）
• 有變更先會顯示
• 撳 Save → PUT /api/shop/{id} → 綠色 ✅「Saved」提示 2 秒自動消失

8.7.6 Create Store Modal

撳「+ New Store」→ Modal 彈窗：

• 店舖名稱（必填）
• 地址
• GPS 緯度/經度 + 🧭「Use my location」按鈕
• 半徑（預設 100）
• 負責經理 chips

8.8 出勤紀錄 (Attendance Records)

路徑：More → /attendance 角色：Owner / Manager（非 admin 自動 redirect 去員工模式）

呢個係管理員用嚟瀏覽、編輯、手動補打卡記錄嘅完整頁面。

8.8.1 頂部篩選欄

[Today] [7 Days] [30 Days]          [🔍 搜尋員工]
[All│On Time│Late│Absent│Early Leave]   [← shop chips →]
[起日 YYYY-MM-DD] [終日 YYYY-MM-DD]    [🔍 Search]

• 日期快速 chips： Today / 7 Days / 30 Days
• 自訂日期範圍： 兩個 TextInput + Search 按鈕
• 狀態 chips： All / On Time / Late / Absent / Early Leave
• 店舖 chips： All + 各分店
• 搜尋框： 按員工姓名搜尋

8.8.2 記錄列表

• 按店舖分組（header 顯示該店員工數 + 總工時）
• 再按日期分組
• 每條記錄卡片可撳展開：

摺疊狀態顯示：

• 狀態 icon（準時/遲到/早退/缺席）
• 狀態徽章
• 驗證方法縮寫（「GPS+Face」、「BLE」、「Manual」等）
• Check-in → Check-out 時間
• 總工時 chip
• 淨工時（如有）
• GPS 精確度
• 打卡相片縮圖（如有）
• 日期、店舖

展開狀態（點擊卡片）顯示詳細資料：

時段 (Time & Duration)

• Check-in 時間 + 日期
• Check-out 時間 + 日期
• 總工時、淨工時
• 加班時數
• 遲到分鐘
• Station
• Schedule ID
• Split Shift 編號
• 備註（需要 attendance_metadata flag）

打卡分析 (Attendance Analysis)

• 滿鐘 ✔/✘
• Hours Variance ±h
• Time Match
• Check-in Match
• Check-out Match （只喺 isFullHours 存在時顯示）

GPS 位置

• Check-in 位置（lat/lng、accuracy）
• Check-out 位置（lat/lng、accuracy）
• View Map 連結 → 打開 Google Maps

驗證方法

• Check-in 方法字串
• NFC / BLE / Face 徽章 chips

人臉辨識

• 已驗證 ✅
• 相似度分數 %
• Check-in 相 + Check-out 相

打卡相片廊

• 縮圖列表 → 點開全螢幕 Photo Viewer Modal

休息時段 (Break Timeline)

• 每次休息：開始 → 結束 + 持續分鐘
• 總休息時間
• 每次休息的人臉驗證狀態

收工清單 (Closing Checklist)

• 每個 item：狀態 dot + 時間

香港僱傭條例相關

• 法定假日 2 倍薪酬
• 休息日 1.5 倍薪酬
• Holiday Pay Rate
• OT Rate Multiplier

Metadata（需要 attendance_metadata flag）

• Record ID
• Created By / Creator Role
• Created At / Updated At

8.8.3 操作按鈕

Edit Time（紫色）：

• 打開 Edit Time Modal
• 預設顯示當前 check-in / check-out 時間
• 兩個滾輪選擇器：時（24h）+ 分（60min）
• 「Clear (reopen)」琥珀色 pill — 清除打咗 check-out 時間令記錄 reopen
• Save → POST /api/attendance/edit → 成功 toast「Times updated」

代簽出 / Proxy Checkout（橙色）：

• 只喺記錄 open（check-in 咗未 check-out）時顯示
• 撳一下 → POST /api/attendance/proxy-checkout → 成功 toast「已代 XXX 簽出」

8.8.4 手動補打卡 (Manual Entry)

撳「+ 補打卡」→ 打開 補打卡 Modal：

1. 揀員工： 員工 chips（或如果唔在列表，用手打）
2. 揀店舖： shop chips
3. 揀日期： 過去 14 日 date strip（顯示星期 + MM-DD）
4. Check-in 時間： 時（24h scroll）+ 分（60min scroll）
5. Check-out 時間： 時 + 分（如需要）+「× 清除簽出時間」連結
6. 備註（optional）： TextInput
7. 撳「確認補打卡」
8. 提交後 reload 列表

8.8.5 其他細節

• 下拉刷新 pull-to-refresh
• Skeleton loading state
• EmptyState 顯示「No attendance records. Try adjusting the date range or filters.」
• 所有時間使用 Asia/Hong_Kong 時區
• en-HK locale 格式化日期顯示

8.9 審批 (Approvals)

路徑：More → /approvals

8.9.1 Tabs

兩個 tabs：Leave Approvals | Shift Swaps（需要 shift_swap 功能）

8.9.2 假期審批

• 過濾 pills：Pending / All（預設 Pending）
• 每張申請卡片：
  • 員工頭像 + 姓名 + 店舖名
  • 假類徽章（年假 🟦 / 病假 🟩 / 私人 🟧）
  • 起訖日期
  • 原因（optional）
  • 狀態 pill：Pending（黃）/ Approved（綠）/ Rejected（紅）
  • 兩個按鈕（Pending 狀態時）：✅ Approve / ❌ Reject
• 每 30 秒自動 polling 更新
• pull-to-refresh

8.9.3 換班申請審批

• 列表類似假期審批
• 顯示：申請人、想換嘅日期、原因
• ✅ Approve / ❌ Reject

8.10 假期管理 (Admin Leave)

路徑：More → /leave

• Header：標題 + 待批數量 + 🔄 Refresh
• Filter pills：Pending / All
• 每張申請卡片（同上 8.9.2）
• ✅ Approve / ❌ Reject（Pending 時）
• pull-to-refresh

8.11 報表 (Reports)

路徑：More → /reports

8.11.1 頂部

• 標題「Reports & Analytics」
• 統計數字：N records · N stores
• 綠色「Export XLSX」按鈕（匯出 Excel）

8.11.2 篩選

• 店舖 chips（多店時顯示）
• 日期範圍：From YYYY-MM-DD / To YYYY-MM-DD
• 🔍 Search 按鈕

8.11.3 統計卡

5 張卡（30% 寬度）：

• 總記錄 (Total) / 準時 (On Time) / 遲到 (Late) / 缺席 (Absent) / 總時數 (Hours)

8.11.4 圖表

• 圓餅圖 (PieChart)： 狀態分佈（準時/遲到/缺席）
• 柱狀圖 (BarChart)： 每日打卡量

8.11.5 記錄列表

• {n} records header
• 交替行顏色
• 欄位：姓名、日期 + check-in、→、check-out、狀態 pill、時數

8.11.6 匯出 XLSX

撳「Export XLSX」：

1. GET /api/report/export?start=...&end=...&shopIds=...
2. 用 WebBrowser.openBrowserAsync(url) 開放下載連結（安全性檢查：必須 https + 有 dot）
3. 如果冇記錄或 export error → Alert 提示

8.12 活動紀錄 (Activity Log)

路徑：More → /activity 需要：activity_log flag，否則 redirect 去 More

8.12.1 頂部

• 標題「Activity Log」+ 總數 + 已啟用 filter
• 🔄 Refresh 按鈕

8.12.2 類別過濾 chips（22 種）

橫向滑動，可選： all / employee / attendance / leave / schedule / shop / auth / checkin / checkout / system / shift / store / subscription / swap / break / overtime / health / pos / restaurant / expense / payroll / setting

8.12.3 級別過濾（可展開）

• Filter icon + 提示 + ▼ 展開
• 展開後顯示：all / info / success / warning / error

8.12.4 活動列表

按日期分組（Today / Yesterday / 星期 X / 完整日期），每條：

• 左 4px 邊框按 severity 顏色
• 動作 icon（根據 action 字串對應 LogIn / LogOut / UserPlus / CheckCircle 等）
• 動作名稱 + 時間戳（en-HK + Asia/Hong_Kong）
• 訊息（最多 2 行）
• Footer：actor 名 / shop / 類別 chip / 來源 label（mobile / web_admin / system）

8.12.5 載入更多

底部「Load more (50)」按鈕 — 撳一下加載下一頁（50 條）

8.13 加入請求 (Join Requests)

路徑：More → /join-requests

• 每 30 秒自動 polling
• 列表：申請人姓名 + email/phone + 狀態 pill + Shop
• Approve（綠色） — PUT /api/request-join/...
• Reject（紅色） — PUT /api/request-join/...
• EmptyState + pull-to-refresh

8.14 批次匯入 (Batch Import)

路徑：More → /batch-import 需要：batch_employee_import flag

1. 頁面顯示格式指南（amber 卡）：
   • 提供 JSON 範本
   • 撳「Use Sample」自動填入範本 JSON
2. JSON 輸入框（monospace，min-height 200）
3. 撳「Import Employees」：
   • 系統解析 JSON → 驗證格式
   • POST /api/batch-import/employees + defaultShopIds
4. 結果列表：
   • ✅ CheckCircle = 已建立
   • ⚠️ AlertTriangle = 跳過
   • ❌ XCircle = 失敗（顯示原因）

JSON 範本格式：

[
  { "name": "John Doe", "email": "john@example.com", "employmentType": "full_time" },
  { "name": "Jane Smith", "email": "jane@example.com", "employmentType": "part_time" }
]

8.15 雇用歷史 (Employment History)

路由：More → /employment-history 需要：employment_history flag

8.15.1 員工列表

• 🔍 搜尋欄（姓名 / email 過濾）
• 每位員工一張卡片：頭像 + 姓名 + 部門 · 職位 · email +「View History」連結

8.15.2 時間線視圖（揀咗某員工後）

• 垂直時間線，左側彩色圓點（紫色=employee、綠色=attendance、青色=schedule、琥珀色=leave）
• 每條記錄：
  • 動作名稱（attendance_checkin →「attendance checkin」）
  • 訊息
  • 日期 + 時間
  • 「by {actorName}」
  • before/after diff（灰框，列出變更嘅欄位：{key}: {old} → {new}）

8.16 遠端打卡審批 (Remote Check-in)

路由：More → /remote-checkin 需要：remote_checkin flag

• Header：標題 + {n} pending
• 申請卡片：MapPin icon + 員工名 + 日期 + 原因
• ✅ Approve / ❌ Reject → PATCH /api/remote-checkin/{id}
• EmptyState + pull-to-refresh

8.17 餐廳管理 (Restaurants)

路由：More → /restaurants 需要：restaurant_multi_manage flag

• 列表：用戶所屬嘅所有餐廳
• 每間卡片：icon + 名稱 + 「Current」pill（如是當前）+ n stores + 角色 pill
• 撳任何一間 → selectRestaurant(id) + redirect
• ➕ + New Restaurant → 開 CreateCompanyModal（見 12）
• pull-to-refresh

8.18 報銷審批 (Admin Expense)

路由：More → /expense 需要：expense_reimbursement flag

• Tab pills：All / Pending / Approved / Rejected
• 每張申請卡：
  • 員工名、類別 pill（Travel 🟦 / Meal 🟧 / Supplies 🟣 / Other ⚪）、狀態 pill、金額 HK$X.XX、日期、原因、收據 URL（如有）
  • Pending 時：✅ Approve / ❌ Reject（Reject 會彈 Modal 輸入原因）
• 每 30 秒 polling + useRefreshOnFocus

8.19 班次模板 (Shift Templates)

路由：More → /shift-templates 需要：shift_template flag

• ➕ + New Template → 打開 Modal
• 每個模板卡片：彩色 icon + 名稱 + 時間 + Grace Minutes + Break Duration + 描述 + 應用店舖 chips
• ✏️ Edit / 🗑️ Delete
• Modal 內欄位： 名稱（必填）、開始時間、結束時間、Grace Minutes（預設 15）、Break Duration、顏色（hex）、Apply to Shops（multi-select chips）

8.20 智能排班 (Smart Schedule)

路由：More → /smart-schedule 需要：smart_scheduling flag

• Shop selector chips
• ← 週導航 →
• Coverage Forecast 卡： 7 日 tiles（員工數 + 覆蓋率 %）
• AI Suggestions 卡： 列出每個 shift 需要嘅建議員工數
• pull-to-refresh

8.21 部門管理 (Department Manage)

路由：More → /department-manage 需要：department_position_manage flag

• 兩個 tabs：Departments (n) / Positions (n)
• ➕ + Add New → Modal（name input）
• 列表：icon + 名稱 + 🗑️ Delete
• Positions 會顯示所屬部門 ID

8.22 Admin Leave / Admin Expense / Admin Remote Check-in

呢啲係 Approvals 以外嘅獨立管理頁面，結構類似但各自獨立過濾。

---

9. 員工模式 (Employee)

適用於：所有員工 (Staff) + Admin 切換到員工身份打卡

9.1 底部導航 5 Tab

┌─────────┬──────────────┬─────────────────────┐
│ 圖示    │ Tab 名稱     │ 路由                │
├─────────┼──────────────┼─────────────────────┤
│ 🏠      │ Dashboard    │ /(employee)/dashboard│
│ 🕒      │ Attendance   │ /(employee)/attendance│
│ ▦       │ Roster       │ /(employee)/roster   │
│ 📅      │ Schedule     │ /(employee)/schedule  │
│ 📄      │ Leave        │ /(employee)/leave    │
└─────────┴──────────────┴─────────────────────┘

右上角亦有 👤 個人帳號 ｜ 🕒 切換到 Admin（Owner/Manager 先見到）

9.2 儀表板 (Dashboard)

路徑：第 1 個 tab

9.2.1 頂部資訊列

• 姓名 + 角色徽章（彩色旁）
• 餐廳名 + 目前店舖名（如有多店）
• 今日日期 + 星期
• 右上：👤 帳號 / 🕒 Admin 切換（如有）
• 多餐廳時顯示切換條

9.2.2 法定假期警告

如果今日係香港法定假期 → 紅色橫額顯示「Statutory Holiday Warning」

9.2.3 大型打卡按鈕

畫面最矚目嘅元素：

驗證方法提示： 按鈕下方細字顯示需要嘅驗證步驟，例如「GPS + BLE + Face」

9.2.4 驗證流程

當你按打卡掣後，如果需要驗證，會順序顯示以下畫面（按店舖設定）：

1. BLE 步驟（如需）— 掃描 + skip 選項
2. 相機步驟（如需）— 3 秒倒數 selfie + retake
3. Face 步驟（如需）— 顯示「Verifying...」
4. GPS 步驟（如需）— 定位中 +「Confirm Check-in」
5. Submitting — 等待伺服器回應

詳細驗證流程見 第 7 章。

9.2.5 今日完成摘要（Check-out 後）

綠色卡片顯示：

• ✅「Check-in Complete」
• Check-in HH:MM → Check-out HH:MM
• 總工時（今日全部 shift 加總）
• 多更 (Split Shifts) 清單（如有）
• 狀態：early leave 會有橙色提示
• 「Start New Shift」按鈕（再開一更）

9.2.6 休息按鈕

Check-in 後出現，灰底「☕ Start Break」，撳後變黃底「End Break (XX min)」

9.2.7 本月統計卡片

四格數字：準時 / 遲到 / 缺席 + 圓餅圖 + 總工時 + 工作日數 + 每週工時分佈柱狀圖

9.2.8 快速操作

三張功能卡片：

1. 📅 My Schedule — 跳去 Schedule tab
2. 📄 Apply Leave — 跳去 Leave tab
3. ▦ My Roster — 跳去 Roster tab

兩個次要按鈕（需要對應 feature flag）：4. 💰 Expense — 報銷 5. ↔️ Shift Swap — 換班

9.3 出勤 (Attendance)

路徑：第 2 個 tab

9.3.1 頂部

• 標題「Attendance」+ 目前店舖 pill
• 今日班次提示（Shift Name · HH:MM–HH:MM，如有）
• 店舖切換 chips（橫向滑動）

9.3.2 打卡按鈕

同 Dashboard 一樣嘅打卡掣（只喺今日 view 顯示）

9.3.3 日期導航

← Prev  │  YYYY-MM-DD (星期) [Today]  │  Next →

• ← Prev — 去前一日
• Next → — 去後一日（今日時 disabled）
• Quick chips：Today / Prev（高亮已選）

9.3.4 記錄列表

今日冇記錄：「No attendance today. Use the dashboard to check in.」 其他日冇記錄：「No attendance this day」

有記錄： 每條 timeline card：

• 左：彩色 dot（藍=進行中、琥珀=遲到、橙=早退、翠綠=準時）+ 灰色連線
• 中：check-in HH:MM → check-out HH:MM（或藍色「In Progress」pill）+ shift 名 pill + station pill + 狀態 pill
• 右：X.Xh + 橙色 +X.Xh 加班 badge + 綠色 Net X.Xh + ▼ 展開箭頭

展開後：

• 三張時間卡：Check-in / Check-out / Total Hours（indigo 高亮，如有 Net 顯示綠色 pill）
• 加班橙色 banner（如有）
• 遲到 amber banner（如有）
• 早退橙色 banner（如有）
• 休息時段： ☕ Coffee icon + 每次休息 start → end + 持續分鐘 + 總分鐘
• 驗證卡： Check-in/out method + station + GPS 座標（如有）
• 強制簽出： 如果係 method === 'force' 顯示橙色 alert
• 遠端簽出： 如果係 method === 'remote' 顯示黃色 alert

9.3.5 下拉刷新

RefreshControl → 重新載入今日記錄

9.4 更表 (Roster)

路徑：第 3 個 tab

9.4.1 畫面

• 店舖切換 chips（橫向）+「All」
• ← 前週 / → 後週 + 日期範圍
• 每週 7 日，每日一張卡片：

每日卡片：

• 星期 + 日期（今日藍色 highlight）
• 無更：灰色「這個同事今日冇更」
• 有更：每位同事一行（頭像 icon + 姓名 + 班次名 + 時段 + 工時）
• 本人 row 會有 highlight
• 已 check-in 同事：顯示 Check-in HH:MM → Check-out HH:MM
• 缺席：紅色「❗Absent」

9.4.2 換班申請 (Request Swap)

需要 shift_swap 功能

底部橙色「↔️ Request Swap」：

1. 系統自動填入你呢週第一個班
2. 修改日期（YYYY-MM-DD）
3. 填寫原因（optional）
4. 撳「Submit Swap Request」
5. 管理員會喺 Approvals 頁睇到

9.5 班表 (Schedule)

路徑：第 4 個 tab

9.5.1 頂部

• 月份 + 年份
• 店舖過濾 chips（橫向）

9.5.2 統計卡

4 張：本月工作日 / 準時 / 遲到 / 缺席

9.5.3 每週工時柱狀圖

7 條 bar（星期日至六），顯示平均每星期某日有幾多工時

9.5.4 月曆

• 標準月曆顯示
• 有班嘅日子下方有 🟣 圓點
• 過去日子：✅ 準時 / ⚠️ 遲到 / ❌ 缺席
• 今日：藍色邊框
• 點任何日子 → 展開日詳情面板

9.5.5 月份切換

← Prev | 月份 | Next →

9.5.6 日詳情面板

• 標題：日期（+「Today」徽章）
• 班次列表：班名、時段、店舖、工時
• 打卡紀錄：check-in → check-out、工時、station
• 未來日子顯示「Upcoming Shift」

9.6 假期 (Leave)

路徑：第 5 個 tab 需要：leave_management flag（否則顯示鎖畫面）

9.6.1 假期額度

三條進度條：年假 🌴 / 病假 🏥 / 私人假 📋（used/total）

9.6.2 月度使用柱狀圖

過去月份每月用咗幾多日假（只喺有批核記錄時顯示）

9.6.3 申請假期

撳「+ Apply Leave」展開表單：

1. 揀假類：年假 / 病假 / 私人假（三個大 icon buttons）
2. 起始日 YYYY-MM-DD
3. 結束日 YYYY-MM-DD
4. 原因（multi-line）
5. 撳「Submit」

9.6.4 申請列表

每張卡片：假類 emoji + 狀態 🟡 待批 / 🟢 已批 / 🔴 已拒 + 起訖日 + 原因

9.7 隱藏功能（經 Dashboard 快速操作進入）

呢啲頁面冇 tab，要由 Dashboard 嘅 Quick Actions 進入。

9.7.1 糧單 (Payslips)

需要：pay_slip_view flag

• 列表：每張白色卡片顯示 HK$netPay（大號）+ 期間 start → end + 狀態 pill（🟢 final / 🟡 draft）
• 三格 mini stats：工時、時薪、工作日數
• 扣減（如有）：紅色 label / -HK$ 金額
• 唯讀 — 冇下載按鈕，需要 official PDF 請聯絡管理員

9.7.2 雇用歷史 (Employment History)

需要：employment_history flag

• 垂直時間線
• 每條：彩色圓點 icon + 動作名 + 日期時間 + 「by actor」
• Diff 展示變更：{key}: {old} → {new}

9.7.3 遠端打卡 (Remote Check-in)

需要：remote_checkin flag

申請：

1. 揀店舖（shop chips）
2. 輸入原因（必填）
3. 撳「Submit」

我嘅申請列表：

• 原因 + status pill（🟡 Pending / 🟢 Approved / 🔴 Rejected）+ 日期
• 如已批准：顯示「Approved by: {name}」

9.7.4 報銷 (Expense)

需要：expense_reimbursement flag

提交報銷：

1. 撳「Submit Expense」
2. 填寫：Title（必填）、Amount（>=0）、Category（Travel/Meal/Supplies/Other）、Description、Receipt URL、Date（YYYY-MM-DD）
3. 撳「Submit」

我嘅申請列表：

• Title + category pill + status pill + HK$amount + 日期 + 原因 + 收據 URL

---

10. 簡易模式 (Simple)

適用於：唔太熟手機嘅員工 設計：大頭、大字、大掣、純色、冇圖表

10.1 開啟 / 關閉

1. 員工模式 → 帳號頁 → 顯示模式 → 撥動「Simple Mode」開關
2. App 立即跳轉到 Simple Dashboard

⚠️ Owner / Manager 開咗都唔會生效，照用 Admin Mode

10.2 介面結構

┌────────────────────────────────┐
│ Header（藍底白字大標題）        │
│ 4xl 姓名 + 店舖 + 日期          │
│ 右：「設定」按鈕                 │
├────────────────────────────────┤
│                                 │
│  大型打卡掣（~240px 高）        │
│  🔵 藍色 = 上班（Check In）    │
│  🟠 橙色 = 下班（Check Out）   │
│      + 大字 HH:MM 即時工時      │
│  🟡 黃色 = 結束休息             │
│      + XX min 已休息時間        │
│  下面：驗證方法提示              │
│                                 │
├────────────────────────────────┤
│  ☕ 休息按鈕（如已上班）         │
├────────────────────────────────┤
│                                 │
│ 📅 大藍掣 — 班表                │
│ 📄 大橙掣 — 申請假              │
│ 👥 大紫掣 — 同事更表            │
│                                 │
├────────────────────────────────┤
│  💡 黃色提示卡片                 │
└────────────────────────────────┘

10.3 打卡

同員工模式嘅打卡邏輯完全一樣，但：

• 字體更大（4xl 標題、2xl 按鈕文字）
• 按鈕更高（60px 以上）
• 驗證流程中嘅每個步驟字體都加大
• 休息按鈕更顯眼

10.4 三個功能掣

10.4.1 班表 (Schedule) — 藍掣

• 頂：藍底白字 +「← 返回」button
• 店舖切換（如多店，大 chips）
• 本週彙總：「本週 X 個班」
• ← 前一週 / → 後一週（大灰掣）
• 每日一大張卡：
  • 大日期數字 + 星期
  • 狀態徽章（今日 / 準時 / 遲到 / 缺席）
  • 有班：🕒 班次 icon + 名 + 時段 + 店舖
  • 休息日：「休息日」字樣
• 底部黃色提示卡

10.4.2 申請假 (Leave) — 橙掣

• 頂：橙底白字 +「← 返回」
• 三張統計卡：待批 / 已批 / 總共（大數字）
• 三條進度條：假期額度
• 大橙掣「申請假」：
  1. 揀類型（年假 / 病假 / 私人 — 三個大掣）
  2. 開始日期（大字輸入框）
  3. 結束日期
  4. 原因（多行）
  5. 提交
• 申請列表（每張大卡）：類型徽章 + 狀態 icon + 日期 + 原因
• 底部黃色提示卡

10.4.3 同事更表 (Roster) — 紫掣

• 頂：紫底白字 +「← 返回」
• 店舖切換器
• ← 前週 / → 後週
• 每位員工一張大卡：
  • 大圓形 avatar
  • 姓名（自己姓名旁邊顯示「(我)」+ 藍底 highlight）
  • 「呢個星期 X 次」
  • 每日一行：星期 + 日期 | 班次 icon + 名 + 時段 | 今日徽章 / 打卡狀態
• 換班掣（需要 flag）：大橙掣「申請換班」
• 底部黃色提示卡

10.5 設定 / 帳號

主頁右上角「設定」掣 → 去 Account 頁（同員工模式共用）

---

11. 帳號設定

所有模式都經 👤 icon 或「設定」掣進入

11.1 個人檔案

• 大頭相（人臉註冊相 / 首字母 circle）
• 姓名、電郵 / 電話
• 角色徽章 + 雇用類型徽章
• 員工編號
• 餐廳、部門、職位、電話

11.2 人臉註冊 (Face Registration)

註冊流程：

1. 撳「Register」或「Update」掣
2. 相機自動開（前置鏡頭）
3. 對住自己 → 撳「Capture」
4. 確認相片 →「Upload」
5. Uploading... → 綠色「Face registered successfully」✅

更新人臉：

• 撳「Update」→ 重複以上步驟
• 人臉相會更新，用於打卡時嘅 Face Recognition

人臉驗證相片畫廊：

• 列出所有打卡時拍嘅人臉相
• 方便核對

11.3 餐廳管理

• 目前餐廳 + 角色 + 🟢 Active 徽章
• 多餐廳切換列表
• Connect New — 跳去 Join Restaurant 流程
• New Restaurant — 開 CreateCompanyModal（見第 12 章）
• Refresh — 重新同步餐廳列表

11.4 登入方法

• 顯示已連結嘅登入方法（電郵 / 電話）
• 修改電郵： 輸入新 email → Change
• 修改電話： 揀區號 + 輸入新號碼 → Change
• 連結另一方法： 如果只有電話，可加電郵 + 密碼（反之亦然）

11.5 安全性

• 修改密碼： 撳 → 系統發送密碼重設電郵到你嘅 email
• 生物識別： Face ID / 指紋開關
• Toast 通知： App 內彈出通知開關

11.6 其他

• 語言： English / 繁體中文（立即切換）
• 顯示模式： Simple Mode 開關
• App Info： 顯示版本號
• 登出： 紅色按鈕（清除所有本地資料，包括 offline queue、快取、生物識別設定）

---

12. 建立新公司（四步驟精靈）

路由：帳號頁 → Restaurant → New Restaurant → CreateCompanyModal

Step 1 — 公司資料：

• 公司名（必填）
• 公司類型：Restaurant / Cafe / Bar / Fast Food / Retail / Hotel / School / Hospital / Office / Factory / Other（揀 Other 可自訂）
• 地址、電話 (+852)、電郵、商業登記
• 描述

Step 2 — 店舖資料：

• 店舖名（必填，預設「{公司名} Main」）
• 地址
• GPS 坐標（預設香港中心 22.3193, 114.1694 +「Use my location」自動填入）
• Geofence 半徑（預設 100m）

Step 3 — 方案：

• 預設「Free」plan（免費使用基本打卡功能）
• 可睇 HK Basic / HK Pro 資料，但呢個精靈入面唔可以揀付費方案（要之後去 Subscription 升級）

Step 4 — 確認：

• 三張摘要卡：Company / Shop / Plan
• 撳「Create」→ POST /api/restaurant-manage/create
• 完成後顯示 ✅「{CompanyName} is ready」

---

13. 權限控制管理（老闆專用）

路徑：Admin → More → Access Control 需要：permission_module_config flag + Owner 角色

你係 Owner，可以為每個員工設定每個模組嘅權限級別：

13.1 員工列表

• 搜尋（姓名／UID）
• 顯示所有 Manager + Staff（Owner 唔顯示）
• 撳任何一個 → 進入權限編輯

13.2 權限編輯器

三個預設按鈕：

• 🔴 No Access — 所有模組設為無權限
• 👁️ View Only — 所有模組設為唯讀
• ✅ Full Access — 所有模組設為完整權限

模組列表（21 個模組，分 6 組）：

每個模組：

• 顯示 icon + 名稱 + 目前權限 pill
• 點一下循環切換： none → view → edit → none...
• 已修改嘅 row 會有 light indigo highlight +「Modified」標籤
• 橙色 lock icon = 目前有 override（唔係角色預設）

13.3 底部操作欄

• Reset to default — 還原角色預設權限
• Save — 儲存所有變更（disabled 直至有修改）

---

14. 訂閱與方案

路徑：Admin → More → Subscription 角色：Owner / Manager

14.1 方案概覽

顯示：

• 餐廳名 + 目前方案名
• Active subscriptions（如有）
• 方案名稱、價格、間隔、狀態 pill（active / trialing / past_due / canceled）
• 使用量 vs 上限（進度條 + %）：Stores / Employees

14.2 方案等級

四級方案（按月 / 按年）：

每個方案卡片可點開睇詳細 feature list（16 個功能 flag 顯示 ✅ / ❌）。

14.3 付款

• HK Pro 年繳（目前唯一可線上付款）： 撳「Subscribe」→ 跳轉 Airwallex checkout
• Manage Billing： 撳 → Airwallex customer portal（管理付款方式、查看發票）
• Enterprise： 撳「Contact Sales」→ mailto:sales@timeplate.app

14.4 訂閱歷史

• 全部 subscriptions（不論狀態）
• 每條：方案名、金額、間隔、日期範圍、狀態 pill

---

15. 常見問題 FAQ

15.1 登入與帳號

Q：我忘記密碼點算？ A：帳號頁 → 安全性 → Change Password → 系統發送重設電郵。或者叫管理員幫手。

Q：可唔可以用同一個帳號登入兩部手機？ A：可以，Firebase session 係跨裝置嘅。

Q：我電話號碼變咗，點 update？ A：帳號頁 → 登入方法 → 喺電話 row 輸入新號碼 → Change。

15.2 打卡

Q：打卡按下去冇反應？ A：檢查：

1. 頂部紅色「No internet connection」banner？— 等網絡恢復
2. GPS / 藍牙 / 相機權限有冇俾？
3. 重啟 App
4. 以上唔得 → 叫管理員手動補卡

Q：唔小心打多咗一更？ A：唔可以自己刪除。請管理員去 Admin → 出勤紀錄 → 編輯 / 刪除。

Q：忘記 check-out？ A：叫管理員 Admin → 出勤紀錄 → 找記錄 → Edit Time 加 check-out 時間；或 Proxy Checkout。

Q：打卡失敗但好似入咗紀錄？ A：系統有 idempotency 保護，正常唔會重複。如有重複 → 管理員手動刪除。

Q：離線時打卡點算？ A：打卡請求會排入 offline queue，連返線時自動 flush。也可撳 amber 橫額手動同步。

15.3 假期 / 換班

Q：遞交假期後幾時知批冇？ A：通知會喺 30 秒內 push。Status 喺 Leave tab 顯示。

Q：申請咗假但想取消？ A：請管理員幫手 reject。

Q：換班可以指定同邊個換嗎？ A：目前版本係公開申請，任何同事都可接。

15.4 簡易模式

Q：我開咗 Simple Mode 但見到普通畫面？ A：Simple Mode 只對 Staff 角色生效。Owner / Manager 唔適用。

Q：Simple Mode 有冇糧單 / 報銷？ A：冇。Simple Mode 專為簡化設計，只保留打卡、班表、假期、更表。其他功能請切換返一般模式。

15.5 管理員

Q：Manager 可以刪除班次嗎？ A：唔可以。只有 Owner 先可以刪除班次。Manager 刪除時會彈「Restricted: Owners only」。

Q：點樣可以一次過加好多個員工？ A：使用 Batch Import（More → Batch Import），用 JSON 格式匯入。

Q：啲員工 join 咗但未 approve？ A：去 More → Join Requests 度 approve。

Q：點樣產生邀請碼俾新員工？ A：Settings → 揀分店 → Advanced → Invite Code → Generate。

---

16. 疑難排解

16.1 連線錯誤 (Connection Error)

現象： 登入後畫面顯示「Unable to load your data」

解決：

1. 確認網絡
2. 撳 Retry
3. 登出再登入
4. 仍然唔得 → 聯絡 support@slashhub.hk

16.2 GPS 範圍錯誤

現象： 「You're not within store range」

解決：

1. 行近啲間舖
2. 確保 GPS 開咗 / 未開飛航模式
3. 室內行去窗邊 / 門口
4. 坐標錯 → 叫管理員改

16.3 BLE 掃唔到 Beacon

現象： BLE 步驟一直「Searching...」

解決：

1. 確認手機藍牙開咗
2. Android 確認附近權限開咗
3. 重啟藍牙 Off → On
4. 接近 Beacon
5. 撳「Skip BLE」
6. 通知管理員檢查 Beacon

16.4 人臉辨識唔過

現象：「Face score too low」

解決：

1. Retry，行去光位、唔好戴口罩
2. 更新人臉相（帳號頁 → 人臉註冊）
3. 叫管理員幫你 skip 人臉
4. 叫管理員手動補卡

16.5 通知收唔到

解決：

1. iOS：設定 → TimePlate → 通知 → 允許
2. Android：設定 → 應用程式 → TimePlate → 通知 → 允許
3. App 內：帳號頁 → Toast 通知開關 on

16.6 顯示混合亂碼

解決：

1. 帳號頁 → 語言 → 重新揀
2. 完全關 App 重開
3. 仍不行 → report to support

16.7 簡易模式卡死

解決：

1. 主頁右上「設定」→ 帳號頁 → 關 Simple Mode
2. 登出再登入

16.8 切換餐廳資料冇更新

解決：

1. 下拉 refresh
2. 完全關 App 重開
3. 帳號頁 → Restaurant → Refresh

16.9 邀請碼話 Invalid

可能原因：

• 已過期
• 已用盡
• 輸入錯
• 已加入咗

解決： 叫管理員產生新碼

---

17. 附錄

17.1 路由地圖（完整）

/login                         登入
/signup                        註冊
/join-restaurant               加入餐廳
/account                       帳號設定

/(admin)
  /                            儀表板 (tab 1)
  /live-attendance              即時出勤 (tab 2)
  /schedules                    排班 (tab 3)
  /employees                    員工列表 (tab 4)
  /more                         更多功能 (tab 5)
  --- 從 More 進入 ---
  /attendance                   出勤紀錄
  /employee-detail              員工詳情
  /approvals                    審批
  /leave                        假期管理
  /shift-templates              班次模板
  /department-manage            部門管理
  /expense                      報銷審批
  /reports                      報表
  /activity                     活動紀錄
  /smart-schedule               智能排班
  /join-requests                加入請求
  /batch-import                 批次匯入
  /employment-history           雇用歷史
  /remote-checkin               遠端打卡審批
  /restaurants                  餐廳管理
  /settings                     店舖設定
  /subscription                 訂閱管理

/(employee)
  /dashboard                    儀表板 (tab 1)
  /attendance                   出勤 (tab 2)
  /roster                       更表 (tab 3)
  /schedule                     班表 (tab 4)
  /leave                        假期 (tab 5)
  --- 從 Dashboard 進入 ---
  /payslips                     糧單
  /employment-history           雇用歷史
  /remote-checkin               遠端打卡
  /expense                      報銷

/(simple)
  /                            主畫面（打卡 + 功能掣）
  /schedule                     班表
  /leave                        申請假
  /roster                       同事更表

17.2 權限角色一覽表

17.3 功能對應 Subscription 方案

17.4 技術備註

• 時區： 所有時間使用 Asia/Hong_Kong
• 定位： expo-location（foreground permissions only）
• 藍牙： react-native-ble-plx（Android 12+ 需要 BLUETOOTH_SCAN + BLUETOOTH_CONNECT + ACCESS_FINE_LOCATION）
• 人臉： 相片上傳至 GCS → Face Verification API → 回傳 score
• 推送通知： 每 30 秒 polling，不是即時 push
• 離線隊列： AsyncStorage-based，App 內 NetworkBanner 自動 flush
• 資料快取： DataCacheContext scope = uid:restaurantId，切餐廳會清空

17.5 聯絡支援

• 電郵： support@slashhub.hk
• 銷售： sales@timeplate.app
• 官方網站： https://timeplate.app
• 隱私政策 / 服務條款 / EULA： App 內登入畫面 or 官方網站

---

© 2026 SlashHub Limited — TimePlate v1.0.1