📂 Shopee File Auto-Archiver (蝦皮檔案自動歸檔系統)

蝦皮電商報表自動化歸檔系統：支援訂單與廣告報表之智能分類、正規化命名與異常辨識，大幅提升數據整理效率。

---

✨ 核心特色

• 智能分流：自動識別 00_Unclassified 資料夾中的檔案，並按「店家/年/月」路徑精確歸檔。
• 多格式支援：支援 .xlsx (訂單報表) 與 .csv (廣告報表) 兩種主流格式。
• 正則解析日期：採用 Regex 技術自動抓取檔名中的 8 碼日期（支援多日期格式，自動抓取最新日期）。
• 健全檢查機制：具備「檔案佔用 (Locked)」偵測與「重複檔案 (Skip)」跳過機制，保護數據完整性。
• 詳細執行日誌：每次執行均會生成 latest_sort_log.txt，清楚記錄移動成功、失敗或無法辨識的原因。

---

🚀 快速開始

1. 下載程式

請前往 Releases 頁面下載最新版本的 shopee_file_auto_archiver.exe。

2. 環境配置

確保執行檔放在以下任一位置：

• 01_Shopee 資料夾內
• 與 01_Shopee 平行的上一層目錄
• 或確保網路路徑 \\Ycpl-server\a02_電商部\03_平台管理\Online_Platform_Data\01_Shopee 可正常存取

3. 執行歸檔

雙擊執行 shopee_file_auto_archiver.exe，系統將自動開始掃描 00_Unclassified 資料夾並進行分流。

---

📂 資料夾架構說明

歸檔後的檔案將依以下規則存放：

• 訂單報表：01_Order_Data / [店家目錄] / [年] / [月]
• 廣告報表：02_Ads_Data / [店家目錄] / [年] / [月]
• 無法辨識：99_無法辨識（當檔名格式不符或找不到店家對應時）

完整目錄結構：

BASE_DIR (\\Ycpl-server\a02_電商部\03_平台管理\Online_Platform_Data\01_Shopee)
├── 00_Unclassified/          # 待分類檔案來源資料夾
├── 01_Order_Data/            # 訂單資料分類目標
│   └── {店家資料夾}/
│       └── {年份}/
│           └── {月份}/
├── 02_Ads_Data/              # 廣告資料分類目標
│   └── {店家資料夾}/
│       └── {年份}/
│           └── {月份}/
├── 99_無法辨識/              # 無法分類的檔案
└── latest_sort_log.txt       # 分類日誌檔案

---

📋 訂單報表 (Order Data)

此類檔案將被移動至：01_Order_Data / [店家目錄] / [年] / [月]

✅ 識別條件

1. 副檔名：.xlsx (不分大小寫)
2. 關鍵字：檔名必須包含 _sh 或 order (不分大小寫)

📏 命名格式規範

建議格式：

[店名]_[ShopID]_[報表類型]_[YYYYMMDD]_[其他資訊].xlsx

解析邏輯：

1. 分隔符號：使用底線 _ 進行切割。
2. 店家識別：
   • 程式會先檢查切割後的 第 2 段 (Index 1) 作為 Shop ID。
   • 若 Shop ID 不在 Mapping 中，則檢查 第 1 段 (Index 0) 作為店名。
   • 內容必須存在於 SHOP_MAPPING 清單中 (支援 Shop ID 或中文店名)。
   • 若兩者皆無法對應，檔案將移至「99_無法辨識」。
3. 日期識別：
   • 優先 (Regex)：使用 re.findall 搜尋檔名中所有符合格式 20xxxxxx 的 8 碼數字。
     • 若檔名中包含多個日期（例如：...20251104_20251204.xlsx），系統會自動選取最後一個日期進行分類。
     • 此設計適用於包含起始日期和結束日期的檔名格式。
   • 備援：若 Regex 完全失敗，嘗試讀取切割後的第 4 段 (Index 3) 前 8 碼。
   • 驗證：月份必須在 1-12 之間，否則視為無效日期。

❌ 常見錯誤範例

• ShopA_SH001.xlsx (錯誤：缺少日期)
• ShopA_訂單.xlsx (錯誤：缺少 _sh 關鍵字或 ID 無法對應)
• ShopA_SH001_2025-12-05.xlsx (錯誤：日期格式非 8 碼純數字，雖 Regex 可能抓到但建議統一)

---

📋 廣告報表 (Ads Data)

此類檔案將被移動至：02_Ads_Data / [店家目錄] / [年] / [月]

✅ 識別條件

1. 副檔名：.csv (不分大小寫)
2. 關鍵字：檔名必須包含 蝦皮廣告 (不分大小寫)
3. 分隔符號：支援 -蝦皮廣告 或 _蝦皮廣告 兩種格式

📏 命名格式規範

標準格式 (蝦皮預設)：

[店名]-蝦皮廣告-[類型]-[YYYY_MM_DD].csv

解析邏輯：

1. 分隔符號：支援兩種格式：
   • -蝦皮廣告 (例如：萌寵要當家-蝦皮廣告_2024_01_15.csv)
   • _蝦皮廣告 (例如：萌寵要當家_蝦皮廣告_2024_01_15.csv)
   • 程式會自動偵測檔名中包含的分隔符號類型。
2. 店家識別：
   • 程式會先檢查檔名是否包含 -蝦皮廣告 或 _蝦皮廣告，若無則直接報錯。
   • 取切割後的 左側部分 作為店名。
   • 若店名為空字串，檔案將移至「99_無法辨識」。
   • 店家識別邏輯：
     • 首先檢查完整的前綴部分是否在 SHOP_MAPPING 中
     • 若不在，則將前綴部分以底線 _ 分割，逐一檢查每個部分
     • 若找到任何部分在 Mapping 中，則使用該對應
     • 若所有部分都不在 Mapping 中，檔案將移至「99_無法辨識」
3. 日期識別：
   • Regex：搜尋格式為 YYYY_MM_DD 的字串 (例如：2025_12_05)。
   • 年份必須以 20 開頭。
   • 驗證：月份必須在 1-12 之間，否則視為無效日期。

❌ 常見錯誤範例

• 蝦皮廣告-2025_12_05.csv (錯誤：開頭無店名)
• 萌寵要當家-蝦皮廣告-20251205.csv (錯誤：日期格式非底線分隔 YYYY_MM_DD)

---

🛠️ 錯誤處理與疑難排解

伺服器連線錯誤

程式啟動時會自動檢查伺服器連線狀態。若無法連線，會顯示詳細的錯誤訊息和解決建議。

常見錯誤類型

🔒 防毒軟體阻擋 UNC 路徑

• 症狀：無法存取伺服器資料夾，但網路連線正常
• 可能原因：防毒軟體（如 Windows Defender、卡巴斯基等）阻擋 UNC 路徑存取
• 解決方法：
  1. 檢查防毒軟體設定，將以下路徑加入白名單： \\Ycpl-server\a02_電商部\03_平台管理\Online_Platform_Data\01_Shopee
  2. 暫時關閉防毒軟體的即時防護功能（測試用）
  3. 聯絡 IT 部門協助設定防毒軟體例外規則
  4. 確認 Windows Defender 或其他安全軟體未阻擋網路路徑

🌐 網路連線問題

• 症狀：無法解析伺服器名稱或無法存取網路路徑
• 可能原因：網路連線中斷、不在同一網域、伺服器離線
• 解決方法：
  1. 檢查網路連線是否正常
  2. 確認是否可以存取其他網路資料夾
  3. 嘗試在檔案總管中手動連線到：\\Ycpl-server
  4. 確認是否在同一網域或內網環境
  5. 聯絡 IT 部門確認伺服器狀態

🔐 權限不足

• 症狀：路徑存在但無法讀取或寫入
• 可能原因：帳號權限不足、資料夾分享權限設定問題
• 解決方法：
  1. 確認您的帳號是否有權限存取該資料夾
  2. 聯絡系統管理員確認權限設定
  3. 嘗試以系統管理員身分執行此程式
  4. 確認資料夾分享權限設定

❓ 未知錯誤

• 症狀：發生未預期的錯誤
• 解決方法：
  1. 確認伺服器是否正常運作
  2. 檢查路徑是否正確
  3. 查看程式顯示的詳細錯誤訊息
  4. 聯絡 IT 部門尋求協助

程式執行錯誤

Log 檔初始化失敗

• 症狀：程式無法建立日誌檔案
• 可能原因：Log 檔案正在被其他程式開啟
• 解決方法：關閉可能開啟該檔案的程式（如記事本、Excel）後重試

找不到來源資料夾

• 症狀：程式顯示找不到 00_Unclassified 資料夾
• 可能原因：
  1. 資料夾不存在
  2. 資料夾名稱或路徑已變更
  3. 權限不足無法存取該資料夾
• 解決方法：確認資料夾是否存在，或聯絡系統管理員

檔案分類異常處理

無法成功分類的檔案將被移動至：99_無法辨識

Log 錯誤代碼對照：

Log 訊息標頭	原因說明	建議排查方向
[UNKNOWN] 格式不符 (parts<2)	檔名結構不符合 _ 分隔規則 (訂單)	檢查檔名是否有足夠的底線分隔
[UNKNOWN] 無對應店鋪 ID ({shop_id}) 亦無對應名稱 ({shop_name})	解析出的 ID 和店名都不在 Mapping 表中	檢查 SHOP_MAPPING 是否需新增該店家
[UNKNOWN] 廣告檔名格式錯誤 (找不到 '蝦皮廣告' 關鍵字或分隔符號不符)	廣告檔名中沒有 -蝦皮廣告 或 _蝦皮廣告 關鍵字	確認檔名格式是否正確
[UNKNOWN] 廣告檔名格式錯誤 (店名為空)	廣告檔名以 -蝦皮廣告 開頭，左側無文字	補上店名
[UNKNOWN] 無對應店鋪名稱: {shop_name}	廣告檔名中的店名不在 Mapping 表中	檢查 SHOP_MAPPING 是否需新增該店家
[UNKNOWN] 日期解析失敗	找不到符合的日期格式	檢查日期是否為 20xxxxxx (訂單) 或 20xx_xx_xx (廣告)
[UNKNOWN] 日期解析失敗 (月份無效: {month})	解析出的月份不在 1-12 範圍內	檢查日期格式是否正確
[UNKNOWN] 日期解析失敗 (Regex 與固定位置皆無效)	訂單檔名結構不足，無法解析日期	確認檔名格式是否完整
[UNKNOWN] 解析日期發生錯誤	日期解析過程中發生例外錯誤	檢查檔名格式是否符合規範
[LOCKED] 檔案被佔用 (請關閉 Excel)	檔案被其他程式 (如 Excel) 佔用	關閉檔案後重新執行
[SKIP] 檔案已存在，跳過	目標資料夾已存在同名檔案	確認是否為重複下載，或手動更名後再跑
[OK] 移動成功	檔案成功移動至目標資料夾	無需處理
[ERROR] 移動失敗	檔案移動時發生其他錯誤	檢查檔案權限或路徑是否正確

常見問題 FAQ

• [LOCKED] 檔案被佔用：請確認該 Excel 檔案是否已關閉，關閉後重新執行即可。
• [UNKNOWN] 日期解析失敗：請檢查訂單檔名是否包含 YYYYMMDD (8碼) 或廣告檔名是否包含 YYYY_MM_DD。
• 伺服器連線失敗：請確認網路連線正常，並確認防毒軟體未阻擋 \\Ycpl-server 的存取權限。

---

🔧 Shop Mapping 維護

若有新店家加入，需修改原始 Python 腳本 (shopee_file_auto_archiver.py) 中的 SHOP_MAPPING 字典，然後重新打包成 exe：

SHOP_MAPPING = {
    # 格式："識別關鍵字": "資料夾名稱"
    # 每個店家需要兩個對應：
    # 1. Shop ID 對應 (例如："SH0099")
    # 2. 店名對應 (例如："新店家名稱")
    "SH0099": "SH0099_新店家名稱", 
    "新店家名稱": "SH0099_新店家名稱",
}

注意事項：

• 每個店家必須同時提供 Shop ID 和店名的對應，確保兩種識別方式都能正常運作。
• 資料夾名稱格式建議為：{ShopID}_{店名}，以保持一致性。
• 修改後請測試確認新店家檔案能正確分類。
• exe 版本：若使用 exe 版本，修改 Mapping 後需重新打包成 exe 才能生效。

---

📝 使用範例

訂單檔案範例

萌寵要當家_SH0001_訂單_20240115.xlsx
→ 移動至：01_Order_Data/SH0001_萌寵要當家/2024/01/

萌寵要當家_SH0001_訂單_20251104_20251204.xlsx
→ 移動至：01_Order_Data/SH0001_萌寵要當家/2025/12/
(系統會自動選取最後一個日期 20251204)

廣告檔案範例

萌寵要當家-蝦皮廣告-2024_01_15.csv
→ 移動至：02_Ads_Data/SH0001_萌寵要當家/2024/01/

萌寵要當家_蝦皮廣告_2024_01_15.csv
→ 移動至：02_Ads_Data/SH0001_萌寵要當家/2024/01/
(支援兩種分隔符號格式)

無法辨識的檔案

未知格式檔案.xlsx
→ 移動至：99_無法辨識/

---

⚖️ 授權條款

本專案採用 MIT 授權條款。詳細資訊請參閱 LICENSE 檔案。

---

Developed by Bruce Yang | 2026-01-06