電商儀表板文檔

主題

訂單編號顯示問題修復 ​

問題描述 ​

用戶反映 "order訂單編號欄位沒有顯示"，經過系統性分析發現：

根本原因 ​

  1. 資料庫層面：部分訂單記錄的 order_number 欄位為 NULL
  2. 前端顯示：formatTableId 函數對 NULL 值返回 -，不夠直觀
  3. 資料生成：種子資料中的部分訂單使用了簡單的 INSERT 語句，跳過了自動編號觸發器

技術分析 ​

資料庫設計 ✅: 
- orders.order_number 欄位存在
- generate_order_number() 函數正常
- generate_order_number_trigger 觸發器已建立

前端實現 ✅:
- OrderApiService.mapDbToEntity() 正確映射 order_number 
- columns.ts 中 orderNumber 欄位已配置
- formatTableId 函數運作正常

問題所在 ❌:
- 部分訂單記錄 order_number = NULL
- 前端對空值顯示不夠友善

解決方案 ​

Phase 1: 改善前端顯示 ✅ ​

1.1 新增專用格式化函數 ​

typescript
// /src/utils/index.ts
export const formatOrderNumber = (orderNumber: string | null | undefined, orderId?: string) => {
  if (orderNumber) {
    const { textCopyable } = require('@/components/data-table-common/columnFormat')
    return textCopyable(orderNumber, 'font-mono', 8)
  } else {
    if (orderId) {
      const shortId = orderId.slice(0, 8)
      return `${shortId} (待生成編號)`
    } else {
      return '待生成編號'
    }
  }
}

1.2 更新訂單清單顯示邏輯 ​

typescript
// /src/components/order/order-list/columns.ts
cell: ({ row }) => {
  const orderNumber = row.getValue('orderNumber') as string
  const orderId = row.getValue('id') as string
  return h('div', { class: 'flex items-center' }, [
    formatOrderNumber(orderNumber, orderId),
  ])
}

Phase 2: 修復資料庫資料 (可選) ​

2.1 資料庫修復遷移 ​

建立遷移檔案：/supabase/migrations/20250907000000_fix_missing_order_numbers.sql

sql
-- 為所有 NULL 的 order_number 生成自動編號
DO $$
DECLARE
    order_record RECORD;
    new_order_number TEXT;
    sequence_number INTEGER;
BEGIN
    FOR order_record IN 
        SELECT id, created_at 
        FROM orders 
        WHERE order_number IS NULL 
        ORDER BY created_at ASC
    LOOP
        SELECT NEXTVAL('order_number_seq') INTO sequence_number;
        new_order_number := 'ORD-' || 
                           TO_CHAR(order_record.created_at, 'YYYY') || 
                           '-' || 
                           LPAD(sequence_number::TEXT, 6, '0');
        
        UPDATE orders 
        SET order_number = new_order_number
        WHERE id = order_record.id;
    END LOOP;
END $$;

2.2 驗證觸發器功能 ​

sql
-- 檢查觸發器是否存在且正常運作
SELECT 
    trigger_name,
    event_manipulation,
    action_timing,
    action_statement
FROM information_schema.triggers 
WHERE event_object_table = 'orders' 
AND trigger_name = 'generate_order_number_trigger';

實施效果 ​

用戶體驗改善 ​

  • 修復前：訂單編號欄位顯示 -，無法識別訂單
  • 修復後：顯示 12345678 (待生成編號)，清楚標示狀態

開發維護 ​

  • 一致性：統一的訂單編號處理邏輯
  • 可擴展性：新訂單將自動生成編號
  • 除錯友善：清楚區分有編號和待生成編號的訂單

後續維護 ​

監控要點 ​

  1. 新建訂單是否自動生成編號
  2. order_number_seq 序列是否正常運作
  3. 觸發器是否在所有插入操作中生效

預防措施 ​

  1. 建議所有訂單建立都通過 create_order_with_items 函數
  2. 避免使用直接 INSERT 語句建立訂單
  3. 定期檢查是否有遺漏編號的訂單

相關檔案 ​

前端檔案 ​

  • /src/utils/index.ts - formatOrderNumber 函數
  • /src/components/order/order-list/columns.ts - 訂單清單欄位配置
  • /src/api/services/OrderApiService.ts - API 服務層

資料庫檔案 ​

  • /supabase/migrations/20250907000000_fix_missing_order_numbers.sql - 修復遷移
  • /supabase/migrations/20250526093319_order_payment_logic.sql - 原始觸發器定義
  • /test-order-numbers.sql - 檢查腳本

參考文檔 ​

修復完成時間: 2025-09-07
負責人: Claude Code
影響範圍: 訂單模組 - 前端顯示層