跳至主要内容

US-206: 配送員工作台

User Story​

作為 配送員 (ROLE_DELIVERY) 我想要 在專用工作台中管理配送任務並記錄簽收結果 以便 有效安排配送行程並確保簽收過程有跡可循

驗收標準 (Acceptance Criteria)​

Scenario 1: 查看待配送訂單列表​

  • Given 我是已登入的配送員
  • And 系統中有多筆待配送的訂單
  • When 我進入配送員工作台（/delivery）
  • Then 系統應顯示兩組訂單：
    • 「待出貨」：READY_FOR_DELIVERY 狀態
    • 「配送中」：OUT_FOR_DELIVERY 狀態
  • And 訂單應按配送日期升序排列
  • And 頁面標題應顯示待處理訂單總數

Scenario 2: 開始配送​

  • Given 我在配送員工作台中
  • And 看到一筆「待出貨」的訂單
  • When 我點擊「開始配送」按鈕
  • Then 系統應顯示確認對話框
  • When 我點擊「是」
  • Then 訂單狀態應變更為 OUT_FOR_DELIVERY
  • And 訂單應移動到「配送中」分組
  • And 系統應顯示成功通知

Scenario 3: 確認簽收（需上傳照片）​

  • Given 我在配送員工作台中
  • And 看到一筆「配送中」的訂單
  • When 我點擊「確認簽收」按鈕
  • Then 系統應顯示照片上傳對話框（PhotoUploadDialog）
  • And 對話框標題為「上傳簽收照片」
  • And 說明文字為「請上傳至少一張簽收照片以確認收貨」

Scenario 4: 上傳簽收照片並完成​

  • Given 照片上傳對話框已開啟
  • And 我已選擇至少一張簽收照片
  • When 我點擊「確認簽收」按鈕
  • Then 系統應上傳照片並更新訂單狀態為 DELIVERED
  • And 訂單應從列表中消失
  • And 系統應顯示成功通知

Scenario 5: 簽收照片驗證​

  • Given 照片上傳對話框已開啟
  • And 我尚未選擇任何照片
  • Then 「確認簽收」按鈕應為禁用狀態
  • And 必須上傳至少一張照片才能繼續

Scenario 6: 查看訂單詳情​

  • Given 我在配送員工作台中
  • When 我點擊任一訂單卡片
  • Then 系統應開啟訂單詳情抽屜
  • And 顯示完整訂單資訊，特別是配送地址和聯絡電話

Scenario 7: 取消照片上傳​

  • Given 照片上傳對話框已開啟
  • When 我點擊關閉按鈕或對話框外區域
  • Then 對話框應關閉
  • And 訂單狀態保持不變

業務規則 (Business Rules)​

  1. 權限控制

    • 僅 ROLE_DELIVERY 或更高角色可訪問配送員工作台
    • 路由受 RoleGuard 保護

  2. 狀態過濾

    • 顯示 READY_FOR_DELIVERY 和 OUT_FOR_DELIVERY 兩種狀態的訂單

  3. 照片要求

    • 確認簽收（OUT_FOR_DELIVERY → DELIVERED）必須上傳至少一張簽收照片
    • 照片類型標記為 delivery

  4. 狀態流轉

    • 開始配送：READY_FOR_DELIVERY → OUT_FOR_DELIVERY（無需照片）
    • 確認簽收：OUT_FOR_DELIVERY → DELIVERED（需要照片）

  5. 多租戶隔離

    • 僅顯示當前租戶的訂單

  6. 後續自動流轉

    • DELIVERED 狀態若訂單已支付，系統將自動流轉至 COMPLETED

UI/UX 需求 (UI/UX Requirements)​

頁面結構​

實作位置: src/applets/delivery-applet/delivery-applet.tsx

┌─────────────────────────────────────────────────────┐
│ [Truck] 配送員工作台  [Badge: N]            [刷新]  │
├─────────────────────────────────────────────────────┤
│                                                     │
│ ┌─ 待出貨 (Ready for Delivery) ───────────────────┐ │
│ │  ┌─────────────────────────────────────────────┐ │ │
│ │  │ 訂單 #ABC-20251201-0001                     │ │ │
│ │  │ 客戶: 王小明                                │ │ │
│ │  │ 地址: 台北市信義區...                       │ │ │
│ │  │ 配送日: 2025/12/02        [開始配送 🚚]     │ │ │
│ │  └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│                                                     │
│ ┌─ 配送中 (Out for Delivery) ────────────────────┐ │
│ │  ┌─────────────────────────────────────────────┐ │ │
│ │  │ 訂單 #ABC-20251201-0002                     │ │ │
│ │  │ 客戶: 李小華                                │ │ │
│ │  │ 地址: 台北市大安區...                       │ │ │
│ │  │ 配送日: 2025/12/02        [確認簽收 ✓]      │ │ │
│ │  └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
│                                                     │
└─────────────────────────────────────────────────────┘

照片上傳對話框​

┌─────────────────────────────────────────────────────┐
│                   上傳簽收照片                     X │
├─────────────────────────────────────────────────────┤
│                                                     │
│  請上傳至少一張簽收照片以確認收貨                   │
│                                                     │
│  ┌─────────────────────────────────────────────────┐ │
│  │                                                 │ │
│  │     [拖放照片或點擊上傳]                        │ │
│  │                                                 │ │
│  └─────────────────────────────────────────────────┘ │
│                                                     │
│  [簽收照片1] [簽收照片2]                           │
│                                                     │
│                              [取消]  [確認簽收]    │
│                                                     │
└─────────────────────────────────────────────────────┘

使用的組件​

組件來源用途
TaskGroup@/applets/shared按狀態分組顯示訂單
OrderDetailDrawer@/applets/shared訂單詳情側邊抽屜
PhotoUploadDialog@/applets/order-applet/components照片上傳對話框
Button@appfuse/appfuse-web/components操作按鈕

頁面圖示​

  • 工作台圖示: Truck (Lucide)
  • 開始配送: Truck
  • 確認簽收: CheckCircle
  • 刷新: RefreshCw

任務配置​

const DELIVERY_TASK_CONFIGS: TaskConfig[] = [
  {
    status: OrderStatus.READY_FOR_DELIVERY,
    label: 'Ready for Delivery',
    action: 'Start Delivery',
    targetStatus: OrderStatus.OUT_FOR_DELIVERY,
    icon: Truck,
    color: 'primary',
  },
  {
    status: OrderStatus.OUT_FOR_DELIVERY,
    label: 'Out for Delivery',
    action: 'Confirm Receipt',
    targetStatus: OrderStatus.DELIVERED,
    icon: CheckCircle,
    color: 'success',
    requiresPhoto: true,
    photoType: 'delivery',
  },
]

技術規格 (Technical Specifications)​

路由配置​

  • 路徑: /delivery
  • 權限守衛: RoleGuard requiredRole="ROLE_DELIVERY"
  • Lazy Loading: 是
  • Applet Registry ID: delivery

API 調用​

獲取訂單列表​

useOrderList(
  { status: [OrderStatus.READY_FOR_DELIVERY, OrderStatus.OUT_FOR_DELIVERY] },
  [{ id: 'deliveryDate', desc: false }]
)

更新訂單狀態（含照片）​

orderService.updateStatus(orderId, {
  newStatus: OrderStatus.DELIVERED,
  photoUrls: ['https://cdn.example.com/receipt1.jpg', ...]
})

狀態管理​

  • isUpdating: 狀態更新中標記
  • photoDialogOpen: 照片對話框開關
  • pendingAction: 待執行的操作
  • selectedOrderId, isDrawerOpen: 詳情抽屜狀態

照片上傳流程​

與 US-205 設計師工作台相同：

  1. 點擊「確認簽收」按鈕
  2. 設置 pendingAction 並開啟對話框
  3. 用戶選擇簽收照片
  4. 點擊確認，調用 API
  5. 關閉對話框

SBE 場景 (Specification by Example)​

詳細的測試場景與範例數據：

估算 (Estimation)​

  • Story Points: 5 點
  • 預估工時: 2-3 天
  • 複雜度: 中等

工作拆分​

  1. 組件實作 (1 天)

    • DeliveryApplet 主組件
    • 整合 TaskGroup、OrderDetailDrawer
    • PhotoUploadDialog 整合

  2. 照片上傳邏輯 (0.5 天)

    • pendingAction 狀態管理
    • 照片驗證邏輯

  3. API 整合 (0.5 天)

    • 狀態更新含照片
    • 錯誤處理

  4. 測試與調整 (0.5-1 天)

    • 功能測試
    • UI 調整

依賴 (Dependencies)​

前置條件​

  • US-202: 訂單狀態流轉 API
  • US-205: PhotoUploadDialog 組件（共用）
  • 共用組件: TaskGroup, OrderDetailDrawer

並行開發​

  • 可與 US-204、US-205 並行開發

外部依賴​

  • 圖片上傳服務
  • CDN 服務

測試策略 (Testing Strategy)​

單元測試​

  • 測試 DELIVERY_TASK_CONFIGS 配置
  • 測試 requiresPhoto 邏輯判斷

整合測試​

  • 測試開始配送流程
  • 測試確認簽收 + 照片上傳流程
  • 測試照片驗證

E2E 測試​

  • 測試完整配送流程：開始配送 → 上傳照片 → 確認簽收
  • 測試權限控制

手動測試​

完成定義 (Definition of Done)​

  • DeliveryApplet 組件實作完成
  • 正確顯示 READY_FOR_DELIVERY 和 OUT_FOR_DELIVERY 訂單
  • 開始配送功能正常運作
  • 確認簽收 + 照片上傳功能正常
  • 照片驗證邏輯正確
  • OrderDetailDrawer 整合完成
  • PhotoUploadDialog 整合完成
  • 空狀態畫面顯示正確
  • 權限控制驗證通過
  • 多語言支援
  • Code Review 通過
  • 產品經理驗收通過

備註 (Notes)​

設計決策​

為何確認簽收需要強制上傳照片？

  • 簽收照片是配送完成的法律證據
  • 解決「貨到付款」時的爭議問題
  • 提高客戶對配送過程的信任

照片存儲策略

  • 照片類型標記為 delivery
  • 與作品照片（production）區分
  • 照片 URL 存儲在訂單記錄中

與設計師工作台的對比​

特性設計師工作台配送員工作台
處理狀態CONFIRMED, IN_PRODUCTIONREADY_FOR_DELIVERY, OUT_FOR_DELIVERY
照片類型productiondelivery
照片用途記錄作品成果記錄簽收證明
新增訂單無無

未來優化​

  • 支援 GPS 定位記錄配送位置
  • 添加電子簽名功能
  • 支援配送路線規劃
  • 添加配送失敗處理流程

最後更新: 2025-12-20