# 長照送餐系統 · 操作說明書

版本 1.0 · 2026-05-24 系統由 管理後台 (Admin) 與 騎手 PWA 兩部分組成

# 📑 目錄

# 系統網址與帳號

角色 網址 帳號 密碼
管理員 https://elder-delivery-admin.pages.dev admin@eldercare.local Admin1234
騎手 https://elder-delivery-rider.pages.dev rider1@eldercare.local Rider1234
騎手 2 同上 rider2@eldercare.local Rider1234

騎手端可在手機 Chrome / Safari 「加入主畫面」 安裝為 App。

# Part A · 管理後台 (Admin)

# A1. 登入

login

開啟後台網址，輸入 Email 和密碼。登入後預設導向「儀表板」。

# A2. 儀表板

dashboard

主要區塊：

區塊 說明
🚨 異常告警 自動偵測：未設座標長者數、今日已失敗站數、明日是否未建路線（晚於 18:00 才顯示）
📊 今日送餐進度 大數字 + 進度條（綠=送達、紅=失敗）
📈 4 個 stat 卡片 今日路線 / 騎手在線 / 啟用長者 / 近 7 日未送達 — 點擊進入對應頁
📉 近 7 日趨勢 折線圖：送達 / 未送達 / 待送
🥧 今日餐型分布 環形圖：今日各餐型份數
🚀 快速操作 6 個常用功能快捷鈕

整頁訂閱 Realtime — 騎手送達時即時更新。

# A3. 長者管理

caregivers list

列表欄位：# 預設順序 / 線 / 姓名 / 餐型徽章 / 電話 / 地址 (含導航地址) / 送達指示 / 服務頻率 (午晚矩陣) / 操作

操作按鈕：

篩選：上方搜尋框可搜姓名/地址；下拉可按線過濾。

📥 匯出 Excel：含完整 service_schedule 解碼成可讀文字。

編輯/新增長者對話框包含：

# A4. 線（路線分區）

lines

「線」= 地理區域，每條線會有自己的長者群、預設取餐點、預設順序。例：觀音線、新屋線。

欄位：排序 / 顏色 / 名稱 / 預設取餐點 / 說明 / 啟用 / 操作

新增線對話框：名稱、顏色（彩虹選色器）、說明、預設取餐點（後續建路線會自動套用）、排序、啟用。

# A5. 取餐點

pickup points

路線的起點（廚房 / 中央倉庫等）。

欄位：名稱 / 地址 / 座標 / 被使用 (幾條線當預設) / 啟用 / 操作

新增/編輯對話框：名稱、地址、Leaflet 地圖點選座標、備註、啟用。

刪除前會警告影響範圍（例：「3 條線使用此取餐點，刪除後需重設」）。

# A6. 餐型管理

meal types

「餐型」用於：

欄位：排序 / 代號 / 徽章預覽 (色彩+符號+標籤) / 標籤 / 說明 / 啟用 / 操作

新增餐型對話框：代號（英文）、標籤（中文）、徽章符號（emoji/SD/Si）、顏色（color picker）、說明、排序、啟用。

系統預設 8 種：正常餐盒 / 特殊餐盒 / 🈲海鮮 / 二分之一 / 泥狀(SD) / 稀飯(Si) / 不要炸物 / 不吃水餃。

# A7. 班別

shifts

3 個班別（早 / 中 / 晚）固定。

可調：班別中文名稱、開始/結束時間、基本薪資、是否啟用（停用後該班別不在派送選項中）。

每筆獨立「儲存」按鈕。

預設早餐停用、中晚啟用、薪資 $400。

# A8. 假日表

holidays

決定哪些日期套用 service_schedule.holiday 設定。

操作：

2026 全年 ROC 國定假日 18 天 + 補班 3 天 已預載。

# A9. 騎手管理

riders

欄位：姓名 / 電話 / Email (登入帳號) / 登入帳號 (已建立/無) / 車輛 / 評分 / 狀態 / 操作

操作按鈕：

+ 新增騎手 (含登入帳號) 對話框：

# A10. 管理員管理

admins

僅 super_admin 可建立 / 重設 / 停用其他管理員。

欄位：名稱 / Email / 角色 (admin / super_admin 下拉) / 狀態 / 建立時間 / 操作

+ 新增管理員 對話框：顯示名稱、Email、初始密碼、角色 radio。

安全閘：不能對自己 disable / 刪除（避免鎖死）。

# A11. 建立派送清單（單線）

route planner

步驟：

  1. 選 日期 / 班別 / 線 / 騎手 / 取餐點
  2. 系統自動載入該線今天該服務的長者（依 service_schedule 過濾 + 假日表）
  3. 顯示餐型彙總（廚房準備參考）
  4. 站點順序清單（按 default_seq）：
    • 拖曳 ⋮⋮ 重新排序
    • 點「移除」剔除單站
    • 餐型徽章 + 送達指示醒目顯示
  5. ✨ 自動最佳化：OSRM 抓真實道路距離 → Held-Karp TSP → 全域最佳順序
  6. ↻ 恢復預設順序：按 default_seq 重排
  7. 右側地圖即時預覽（彩色 pin 對應餐型 + OSRM polyline）
  8. 「儲存派送清單」寫入 DB

# A12. 批次建立（多日多線）

batch planner

一次替「多日 × 多班別 × 多線」批量建路線，套用各長者的 default_seq + 餐型 + 送達指示。

選項：

執行結果表：每組 (日期 × 班別 × 線) 顯示 站數 + 動作 (建立 / 取代 / 略過)。

例：7 天 × 2 班 × 2 線 = 14 條路線一鍵完成。

# A13. 派送列表

routes list

欄位：班別 / 線 (色彩 tag) / 騎手 / 點數 (含已送達數) / 距離 / 預估時長 / 狀態 / 操作

操作：

可用日期切換瀏覽任意日期。

# A14. 路線詳細

route detail

頁首：線 (彩色 tag) + 班別 + 日期 + 狀態 tag

基本資訊：騎手 / 取餐點 / 總距離 / 預估時長 / 開始/完成時間 / 薪資

送達進度：百分比進度條

站點 (N) 表格：# / 長者 / 地址 / 距上一站 / 狀態 / 照片 (送達照片可點放大) / 備註 / 送達時間

整頁 Realtime — 騎手送達時自動更新進度。

# A15. 餐點彙總

meal summary

廚房檢視：當日各線 × 班別 × 餐型 統計。

內容：

# A16. 即時追蹤

live tracking

地圖區：所有上線騎手即時位置（5 分鐘內有上報視為在線，否則灰色）。 右側：進行中路線清單 + 全部騎手列表 (含最後上報時間)。

Rider PWA 在路線 in_progress 時每 30 秒上報 GPS。 Realtime 訂閱 → 騎手移動 marker 即時更新。

# A17. 未送達回訪

undelivered

期間內所有 status=failed 的站。

功能：

原因分布：上方橘色 chip 顯示「無人在家 × 3、地址錯誤 × 2 ...」

# A18. 收入報表

earnings

篩選：日期範圍 / 騎手 / 線 / 含未完成。

指標：總收入、完成班次、送達點數、送達率

分析：各騎手收入 / 各線執行統計 / 逐日收入長條圖

📥 匯出 Excel — 4 個 sheet：逐筆明細、各騎手、各線、逐日

# A19. 月結帳單

payslip

步驟：選騎手 + 選月份 → 自動列出當月完成班次

內容（可列印 / 另存 PDF）：

🖨 列印 / 另存 PDF：按下後在系統列印對話框選「儲存為 PDF」即可下載。中文字體完美（瀏覽器原生渲染，不依賴外部 TTF）。

# A20. 騎手回報處理

issues

狀態 tabs (含計數)：全部 / 待處理 / 處理中 / 已解決 / 已關閉

欄位：時間 / 騎手 / 類型 / 長者 / 內容 (含照片) / 優先度 (下拉) / 狀態 / 操作

操作：

騎手送出新回報後，系統會自動 email 通知所有 admin（5 分鐘內，需設 RESEND_API_KEY）。

# A21. 稽核日誌

audit log

10 個關鍵表的所有 insert / update / delete 自動記錄。

篩選：日期範圍 / 資料表 (含計數) / 動作

欄位：時間 / 操作者 (email + 角色) / 動作 / 資料表 / 主鍵 / 變更欄位 chips / 詳細

詳細對話框：

已自動套用到：caregivers / riders / admins / lines / meal_types / shifts / pay_rules / holidays / pickup_points / routes

# A22. 批次設定座標

pending coords

Excel 匯入時可能很多長者沒有座標 (coord_source='pending')。此頁用於批次修正。

操作：

# A23. 線批次重排序

line reorder

一條線的全部長者一次重排 default_seq。

操作：

改的是「預設順序」(default_seq)，影響每天派送的初始排序，但每天可在「建立派送清單」單獨微調。

# A24. Excel 匯入長者

import

4 步驟 wizard：

  1. 上傳：選 .xlsx / .xls / .csv 檔
  2. 欄位對應：系統自動偵測（標題含「姓名/地址/餐型...」自動 map），可手動調整 + 選預設線
  3. 預覽：前 5 列效果 + 全部驗證
  4. 完成：成功/失敗統計

支援欄位：姓名* / 電話 / 地址* / 導航地址 / 導航備註 / 餐型 / 送達指示 / 緯度 / 經度 / 必須拍照 / 飲食備註 / 服務日 / 服務班別

服務日寫法：「一二三四五」、「每天」、留空都可 服務班別寫法：「午晚」、「中餐/晚餐」、留空(=午+晚)

無座標的長者匯入後可在 A22「批次設定座標」逐個修正。

# Part B · 騎手 PWA

360px 寬手機介面，建議加入主畫面當 App 使用。

# B1. 登入

橘色「餐」logo + 送餐騎手標題 + Email/密碼 + 登入。

登入後 session 持久存活，下次開 App 直接到今日任務。

# B2. 今日任務

內容：

底部 4 tab：📋 今日 / 📅 班表 / 💬 回報 / 👤 我的

# B3. 路線詳細（送餐）

頁面結構（從上到下）：

  1. ← 返回 按鈕
  2. 線徽章 + 班別
  3. 進度 (送達/總數) + 開始送餐 按鈕
  4. 地圖 (Leaflet)：取餐點 🏠 + 編號 pin (顏色對應餐型) + 灰色 polyline 連線
  5. 下一站卡片（橘色框框醒目）
    • 序號 + 長者姓名 + 餐型徽章 + 📷 必拍標籤
    • 地址
    • 🧭 導航備註（藍色背景）
    • 📝 送達指示（黃色背景）
    • 飲食備註
    • 3 顆按鈕：📍 導航 / ✓ 送達 / 跳過
  6. 站點順序 全部列表
    • 已送達 = 綠 / 未送達 = 紅 / 待送 = 餐型色

操作流程：

  1. 到第一站附近 → 點 📍 導航 → 跳到手機原生 Google Maps / Apple Maps（自動用 navigation_address）
  2. 送到後 → 點 ✓ 送達 → 對話框：拍照（必拍長者強制）+ 備註 → 確認
  3. 沒送到 → 點 跳過 → 選原因（無人在家 / 電話聯絡不上 / 地址錯誤 / 拒收 / 住院 / 其他）+ 備註
  4. 全部完成 → 主卡片變「完成」按鈕

GPS 上報：路線在 in_progress 期間，App 每 30 秒自動回傳 GPS（admin 即時追蹤地圖看得到）。

# B4. 班表設定

週切換 + 每日 × 班別矩陣 → 勾選你可以送餐的時段。

後台「建立派送清單」會依此分派路線。

# B5. 我的回報

功能：列出所有自己回報的問題 + 管理員回覆

狀態色帶（左邊 4px）：紅=待處理 / 橘=處理中 / 綠=已解決 / 灰=已關閉

新回報 對話框：

收到回覆：藍色卡片標示「管理員回覆 · M/D HH:mm」，Realtime 推送（不用刷新）

# B6. 個人資料 + 通知偏好

基本資料：頭像 / 姓名 / 電話 / 評分

本月收入：金額大字 + 已完成班數 + 累計班次

通知偏好：

登出 按鈕（紅色 outline）

# 常見操作流程

# 流程 1：每日例行（管理員）

06:00 — 系統自動推播當日任務給騎手（已建好的路線）
       管理員上 dashboard 確認進度條 0/N
06–10 — 騎手陸續送餐，dashboard realtime 更新百分比
        遇異常會出現「N 站未送達」紅色告警
10:30 — 全部完成 → dashboard 進度條滿
        進「未送達回訪」處理失敗點
21:00 — 系統自動提醒明日未建路線
       去「批次建立」一鍵建立明日所有線

# 流程 2：新增長者（管理員）

1. 長者 → 長者名單 → + 新增長者
2. 填基本資料（姓名/電話/地址）
3. 選線、餐型（可自由填）
4. 在地圖上點座標
5. 設「服務時段矩陣」(平日只送晚餐？週末午晚？)
6. 設送達指示（信箱 / 籃子 / 拍照?）
7. 家屬通知（開關 + email）
8. 儲存

# 流程 3：建立明日所有路線（批次）

1. 派送 → 批次建立 (多線)
2. 日期範圍：明日 ~ 明日
3. 班別：勾午餐 + 晚餐
4. 線：勾全部
5. 乾跑模式 ✓ → 按「預覽」看結果
6. 確認 → 取消乾跑、按「執行批次建立」→ 確認
7. 進「派送列表」一筆筆派發騎手（點「轉派」選人）

# 流程 4：騎手送餐（騎手 App）

1. 6:00 收推播 → 打開 App
2. 點今日任務 → 進路線詳細
3. 「開始送餐」→ 系統自動上報 GPS
4. 對下一站卡片：
   - 📍 導航 → 跳原生地圖
   - 到了 → ✓ 送達 → 拍照（如需）+ 備註 → 確認
5. 沒送到 → 跳過 → 選原因
6. 全部完成 → 「完成」按鈕

# 流程 5：月底發薪資（管理員）

1. 收入 / 帳單 → 月結帳單
2. 選騎手 + 月份
3. 看「實領金額」+ 班別小計 + 逐筆明細
4. 按「🖨 列印 / 另存 PDF」
5. 系統列印對話框 → 選「儲存為 PDF」→ 下載
6. PDF 寄給騎手簽收

# 疑難排解

問題 解法
騎手 App 沒看到今日任務 確認後台已派路線且 rider_id 是該騎手；確認日期是「今日」
地圖跳不出 / 破圖 已修復，若仍發生請 hard reload (Cmd+Shift+R)
Excel 匯入後座標都是 0 預期行為，去「批次設定座標」用 Nominatim 自動查或手動點
騎手送達後 admin 沒立刻看到 Realtime 應該秒更新；若延遲，刷新派送列表頁
PDF 中文亂碼 用「列印 / 另存 PDF」（瀏覽器原生），不要用截圖另存
Worker cron 沒跑 wrangler tail --name elder-delivery 看 log
家屬沒收 email 需在 worker 設 RESEND_API_KEY secret，並到 Resend 驗證寄件網域
找不到「設定 → 管理員」按鈕 該頁僅 super_admin 可見；admin 角色看不到

# 技術架構（給工程師）

Admin (Vue 3 + Element Plus)     ─ https://elder-delivery-admin.pages.dev
Rider PWA (Next.js 14 App Router) ─ https://elder-delivery-rider.pages.dev
Workers (Cloudflare)              ─ https://elder-delivery.pinter-tw.workers.dev
                                    · 5 個 cron (06:00 推播 / 21:00 提醒 / 04:00 清照片 / 03:00 ping / 每5分鐘 queue)
                                    · /upload R2 photo upload
                                    · /admin/* 帳號管理 API
DB / Auth / Realtime              ─ Supabase (Postgres + RLS)
照片儲存                          ─ Cloudflare R2 (10GB free, zero egress)
路線最佳化                        ─ Held-Karp TSP + OSRM (router.project-osrm.org)
推播                              ─ Web Push (VAPID) / Resend (email)

月成本：$0（Cloudflare free + Supabase free + R2 free + OSRM 公共服務）

Repo：https://github.com/pinterhuang/elder-delivery