跳至主要内容

US-204: 店員工作台

User Story​

作為 店員 (ROLE_SALES) 我想要 在專用工作台中查看並確認待處理的訂單 以便 快速處理新訂單並推進訂單流程

驗收標準 (Acceptance Criteria)​

Scenario 1: 查看待確認訂單列表​

  • Given 我是已登入的店員
  • And 系統中有多筆「待確認」狀態的訂單
  • When 我進入店員工作台（/sales）
  • Then 系統應顯示所有 PENDING_CONFIRMATION 狀態的訂單
  • And 訂單應按配送日期升序排列（最緊急的在前）
  • And 頁面標題應顯示待處理訂單總數的 Badge
  • And 每張訂單卡片應顯示：訂單編號、客戶名稱、配送日期、總金額

Scenario 2: 確認單筆訂單​

  • Given 我在店員工作台中
  • And 看到一筆待確認訂單
  • When 我點擊訂單卡片上的「確認訂單」按鈕
  • Then 系統應顯示確認對話框「確定要確認訂單嗎？」
  • And 對話框提供「是」與「否」選項
  • When 我點擊「是」
  • Then 訂單狀態應變更為 CONFIRMED
  • And 訂單應從列表中消失
  • And 系統應顯示成功通知「狀態更新成功」
  • And 待處理數量 Badge 應更新

Scenario 3: 查看訂單詳情​

  • Given 我在店員工作台中
  • And 看到一筆訂單卡片
  • When 我點擊訂單卡片（非操作按鈕區域）
  • Then 系統應從右側滑入訂單詳情抽屜（OrderDetailDrawer）
  • And 顯示完整訂單資訊（客戶、商品、地址、備註等）

Scenario 4: 快速新增訂單​

  • Given 我在店員工作台中
  • When 我點擊「新增訂單」按鈕
  • Then 系統應導航至訂單創建頁面 /orders/new?from=sales
  • And 創建完成後應可返回店員工作台

Scenario 5: 手動刷新列表​

  • Given 我在店員工作台中
  • When 我點擊「刷新」按鈕
  • Then 系統應重新載入訂單列表
  • And 刷新按鈕的圖示應顯示旋轉動畫
  • And 載入完成後動畫停止

Scenario 6: 無待處理任務​

  • Given 我是已登入的店員
  • And 系統中沒有待確認的訂單
  • When 我進入店員工作台
  • Then 系統應顯示空狀態畫面
  • And 顯示訊息「沒有待處理的任務」和「所有訂單已確認」

業務規則 (Business Rules)​

  1. 權限控制

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

  2. 狀態過濾

    • 僅顯示 PENDING_CONFIRMATION 狀態的訂單
    • 其他狀態的訂單不可見

  3. 排序規則

    • 按配送日期升序排列
    • 最緊急（配送日期最近）的訂單優先顯示

  4. 狀態流轉

    • 確認操作將訂單狀態從 PENDING_CONFIRMATION 變更為 CONFIRMED
    • 狀態變更後自動觸發列表刷新

  5. 多租戶隔離

    • 僅顯示當前租戶的訂單

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

頁面結構​

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

┌─────────────────────────────────────────────────────┐
│ [圖示] 店員工作台  [Badge: N]    [新增訂單] [刷新]  │
├─────────────────────────────────────────────────────┤
│                                                     │
│ ┌─ 待確認 (Pending Confirmation) ─────────────────┐ │
│ │                                                 │ │
│ │  ┌───────────────────────────────────────────┐  │ │
│ │  │ 訂單 #ABC-20251201-0001                   │  │ │
│ │  │ 客戶: 王小明                              │  │ │
│ │  │ 配送日: 2025/12/02                        │  │ │
│ │  │ 金額: NT$1,500            [確認訂單]      │  │ │
│ │  └───────────────────────────────────────────┘  │ │
│ │                                                 │ │
│ │  ┌───────────────────────────────────────────┐  │ │
│ │  │ 訂單 #ABC-20251201-0002                   │  │ │
│ │  │ ...                                        │  │ │
│ │  └───────────────────────────────────────────┘  │ │
│ │                                                 │ │
│ └─────────────────────────────────────────────────┘ │
│                                                     │
└─────────────────────────────────────────────────────┘

使用的共用組件​

組件來源用途
TaskGroup@/applets/shared按狀態分組顯示訂單
TaskCard@/applets/shared單張訂單卡片（內含於 TaskGroup）
OrderDetailDrawer@/applets/shared訂單詳情側邊抽屜
Button@appfuse/appfuse-web/components操作按鈕

頁面圖示​

  • 工作台圖示: ClipboardCheck (Lucide)
  • 新增訂單: Plus
  • 刷新: RefreshCw
  • 確認訂單按鈕: CheckCircle

任務配置​

const SALES_TASK_CONFIGS: TaskConfig[] = [
  {
    status: OrderStatus.PENDING_CONFIRMATION,
    label: 'Pending Confirmation',
    action: 'Confirm Order',
    targetStatus: OrderStatus.CONFIRMED,
    icon: CheckCircle,
    color: 'primary',
  },
]

技術規格 (Technical Specifications)​

路由配置​

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

API 調用​

獲取訂單列表​

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

更新訂單狀態​

orderService.updateStatus(orderId, { newStatus: OrderStatus.CONFIRMED })

狀態管理​

  • 使用 React Query 管理訂單列表快取
  • useOrderListInvalidation 用於狀態更新後刷新列表
  • 本地狀態：isUpdating、selectedOrderId、isDrawerOpen

錯誤處理​

  • API 錯誤時顯示 prompt.error(message)
  • 支援 ErrorResponse 錯誤類型的訊息提取

SBE 場景 (Specification by Example)​

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

估算 (Estimation)​

  • Story Points: 3 點
  • 預估工時: 1-2 天
  • 複雜度: 低

工作拆分​

  1. 組件實作 (0.5 天)

    • SalesApplet 主組件
    • 整合 TaskGroup 與 OrderDetailDrawer

  2. 狀態管理 (0.5 天)

    • React Query 查詢設定
    • 狀態更新邏輯

  3. 路由與權限 (0.25 天)

    • 路由配置
    • RoleGuard 整合

  4. 測試與調整 (0.25-0.75 天)

    • 功能測試
    • UI 調整

依賴 (Dependencies)​

前置條件​

  • US-202: 訂單狀態流轉 - 確認操作的 API
  • 共用組件: TaskGroup, TaskCard, OrderDetailDrawer

並行開發​

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

外部依賴​

  • @/services/sales/order-queries - 訂單查詢 hooks
  • @/services/sales/order-service - 訂單服務 API

測試策略 (Testing Strategy)​

單元測試​

  • 測試 SALES_TASK_CONFIGS 配置正確性
  • 測試狀態分組邏輯

整合測試​

  • 測試確認訂單流程（點擊按鈕 → 確認對話框 → API 調用 → 列表更新）
  • 測試 OrderDetailDrawer 開啟/關閉

E2E 測試​

  • 測試完整的確認訂單流程
  • 測試權限控制（非 ROLE_SALES 無法訪問）

手動測試​

完成定義 (Definition of Done)​

  • SalesApplet 組件實作完成
  • 正確顯示 PENDING_CONFIRMATION 訂單
  • 確認訂單功能正常運作
  • OrderDetailDrawer 整合完成
  • 新增訂單導航正常
  • 刷新功能正常
  • 空狀態畫面顯示正確
  • 權限控制驗證通過
  • 多語言支援
  • Code Review 通過
  • 產品經理驗收通過

備註 (Notes)​

設計決策​

為何使用單頁面設計而非 AppletShell？

  • 店員工作台是任務導向的單頁面應用
  • 無內部子路由需求
  • 簡化 UI 以提升操作效率

為何提供「新增訂單」快捷入口？

  • 店員是最常創建訂單的角色
  • 減少導航步驟，提升工作效率
  • 使用 ?from=sales 參數支援完成後返回

未來優化​

  • 支援批量確認訂單
  • 添加訂單篩選功能（按日期範圍）
  • 支援鍵盤快捷鍵操作

最後更新: 2025-12-20