蝦皮自動化移交手冊

蝦皮廣告自動化移交手冊

Shopee Automation → AI Customer Service Handoff

這份手冊把「蝦皮廣告自動化」專案裡實戰驗證過的做法整理給 James—— 重點是三件事：怎麼開瀏覽器視窗並綁定登入 cookie、怎麼同時開多個實例登入不同蝦皮賣場、 怎麼在蝦皮頁面上活下來（彈窗、延遲、排錯）。這些概念可以直接搬去做智慧客服的側錄與 AI 模擬學習。

1. 這套系統在做什麼

System Overview

一句話：每天自動幫多個蝦皮賣場跑完「下載報表 → 爬資料 → 上傳 Google Sheets → 調整廣告預算 → LINE 通知」整條流水線，全程不用人碰。技術底座是 Python + Playwright（瀏覽器自動化，不是打 API——蝦皮沒有開放這些功能的 API，所以一切都靠「操作真實網頁」完成）。

登入

cookie 快取
免重複 OTP

→

下載報表

廣告＋商品表現

→

爬取資料

預算、購物車人數
600+ 筆逐頁掃

→

上傳 Sheets

多分頁＋核對

→

調整預算

依規則表
深夜自動復原

→

LINE 通知

結果與警告

流水線外面包了一層網頁管理介面（webapp）：FastAPI + SQLite 的本機服務，提供多帳號管理、一鍵執行、排程（每天／每週／每小時）、執行歷史、即時 log、暫停／中斷、跨帳號的通知總覽。引擎（流水線本體）與管理層（webapp）是分開的兩層—— 管理層不改引擎程式，而是把每個帳號的設定「注入環境變數」後啟動子程序，這是多帳號做法的關鍵（第 3 節細講）。

2. 介面展示

UI Walkthrough

以下是管理介面的真實畫面（用隔離測試實例＋假資料「測試賣場A／B」擷取，不含任何真實帳號資訊）。

主控台：每個帳號一張卡，卡內每個功能一列 — **主控台。**一個蝦皮帳號一張卡片；卡片裡「每個功能一列」，各自有狀態、白話結果摘要、下次排程與〔執行／歷史／排程〕按鈕。左卡可以看到三種狀態並存：完整流程成功（綠）、核對對不上（琥珀色警示）、預算復原成功；右卡有一列正在執行中（藍）。重點設計：**結果摘要講人話**（「✓ 全部完成 · 總耗時 18 分 42 秒」「✗ 失敗 1 項：下載廣告報表 — 逾時」），不逼使用者去讀 log。

通知總覽：跨帳號跨功能的最近執行結果 — **通知總覽。**跨所有帳號 × 所有功能的最近執行集中在一頁，頂部有成功／需注意／進行中計數與「只看需要注意」篩選，給「一眼看出哪個賣場出問題」用。左側彩色邊條依嚴重度著色，點任一列直接開右側運行狀況面板。

運行狀況面板：即時 log、暫停與中斷 — **運行狀況面板。**執行中的任務可以看即時 log、**暫停執行**（只凍結自動化程式、瀏覽器留著讓人手動操作截圖—— 用 psutil 在 OS 層 suspend 程序樹但跳過瀏覽器程序）或**中斷執行**。log 每一步都印「做了什麼、讀到幾筆」，出事時不用猜。

排程設定：每天／每週／每小時三種類型 — **排程設定。**每個功能各自排程，支援每天／每週／每小時（限定時段）三種類型，台北時間、背景服務到點自動跑。排程視窗鎖定在開啟時的那個功能，避免排錯對象。

帳號編輯表單：機敏欄位遮罩、連線檢查、申請教學 — **帳號設定表單。**三個值得抄的設計：①機敏欄位（密碼、金鑰、token）**存進資料庫後 API 不再回傳明碼**，編輯時留空＝沿用舊值；② Google Sheet／LINE 欄位旁有「檢查」鈕——按下去**真的連一次線**（開試算表、發測試訊息），錯誤翻成白話（「沒共用權限給 service account」）；③「申請教學」開一頁手把手教學，非工程師也能自己把金鑰申請完。

**登入頁。**本機服務（127.0.0.1）＋一組管理密碼（pbkdf2 雜湊儲存），桌面捷徑點開即用。

3. 核心概念：開視窗綁 cookie、多帳號隔離

Cookie Binding & Account Isolation

3.1 cookie 快取：登入一次，之後直接還原身分

蝦皮登入要手機簡訊 OTP，不可能每次自動化都收一次。做法：

第一次：開 Playwright 瀏覽器 → 人工輸入帳密＋OTP（程式用 wait_for_url(timeout=120_000) 留 120 秒手動窗口）→ 登入成功後 context.cookies() 整包存成 cookies.json。
之後每次：開新瀏覽器 context 先 context.add_cookies(存檔)，再開賣家中心頁面驗證「是否已登入」（is_logged_in()：看頁面有沒有登入後才有的元素）。有效→直接開工；失效→退回人工登入流程重存。
每次成功執行完回寫最新 cookie（蝦皮會滾動更新 session），讓下一次繼續免登入。

這就是「開視窗並綁定登入 cookie」的全部：cookie 檔＝一個身分。要幾個身分就存幾份檔案，開幾個瀏覽器 context 各自載入各自的檔。

3.2 帳號隔離：一個帳號一個資料夾

多帳號的關鍵不是改程式，是隔離檔案系統。引擎所有路徑（cookie、下載資料、log）都經過一個路徑解析模組，由環境變數 SHOPEE_ACCOUNT_DIR 決定根目錄：

accounts/
├─ 賣場A/
│  ├─ cookies.json          ← 賣場A 的身分（master）
│  ├─ modes/full/           ← 「完整流程」功能的工作區（自己的 cookie 副本、下載、log）
│  └─ modes/only-scrape/    ← 另一個功能的工作區
└─ 賣場B/
   └─ cookies.json          ← 賣場B 的身分，跟 A 完全不相干

管理層跑某帳號時，把該帳號的所有設定（帳密、Sheet ID、LINE token、資料夾路徑）注入環境變數後 subprocess 啟動引擎——引擎自己完全不知道「多帳號」這件事，它只看環境變數。這招讓 48 處讀設定的舊程式一行都不用改。

⚠ 血淚教訓：cookie 檔絕對不能讓兩個同時跑的程序「共用」。 兩邊都會在登入後回寫檔案，並發寫入會把 cookie 寫壞、兩邊一起掉登入。正確做法是「續種」：master cookie 複製一份給每個功能各自用（_seed_function_cookie），跑完把較新的登入狀態回寫 master（_writeback_master_cookie）。做客服多開時一樣：一個實例一份 cookie 檔。

3.3 轉換賣場：一個登入帳號管多個賣場

蝦皮有「子帳號」制度：一個登入身分可以管理多個賣場。登入成功後直接導向 /portal/shop（實測可直達，比點右上選單穩），在賣場列表用「賣場帳號」欄位比對目標、點「詳情」進入該賣場後台，然後把選完賣場的 cookie 存起來——之後快速路徑醒來就已經在對的賣場。

安全設計：找不到指定賣場就直接報錯停止，絕不「將就用當前賣場」——在錯的賣場上跑自動化（改預算、回客訴）比不跑更糟。做客服系統時同理：每個實例啟動先驗證「我現在是誰、在哪個賣場」，驗證不過就停。

4. 蝦皮頁面實戰細節

Surviving Shopee Pages

4.1 彈窗：三種類型、三套對策

蝦皮頁面隨時會冒視窗擋住你要點的東西，這是自動化最大死因。實戰遇到三類：

類型	長相與時機	對策
不定期促銷 modal最陰險	不定時彈出（例：宅配開通邀請），含「拒絕／接受」＋右上 X。可能在操作中途冒出來，剛好蓋住要點的按鈕，程式就一直捲動找不到目標。	統一的 `close_all_popups()`：在可見 modal 內依序試「右上 X → 安全文字鈕（我知道了／稍後／關閉／取消）→ 拒絕」。關鍵是有一份 AVOID 清單：絕不點「接受／同意／開通／確定／前往」這類會替使用者做決定的按鈕。每個關鍵動作（捲動前、點匯出前）都再呼叫一次，把「剛剛才彈出來」的也清掉。
密碼重驗 modalsession 過期	session 過期時蝦皮不跳轉登入頁，而是在當前頁面蓋一個要求重輸密碼的 modal，整頁被遮住。	寫一個「檢查並處理」函式（短超時、沒彈窗時零成本），在每個長操作前都呼叫一次：每個步驟開始前、進頁面後、切換條件後、點匯出前。當保險絲用，寧可多查。
業務流程彈窗預期內	特定操作觸發的確認窗（例：調預算時的「關鍵學習階段」提醒）。	偵測 → 點取消 → 該筆標「跳過」（不是失敗、不重試、不中斷後續）。關閉後一定驗證彈窗真的消失了再繼續，不能點完就當關掉了。

另外每次偵測到彈窗都自動截圖存檔，管理介面直接顯示縮圖——事後排錯時能看到「當時畫面長怎樣」，價值極高。

4.2 繞過「真人點擊」檢查：方法 6

蝦皮部分元件（Vue popover）會驗 isTrusted，JavaScript 的 element.click() 根本不觸發。實測有效的固定招式（專案內代號「方法 6」）：

mouse.move(x, y)  →  等 200ms  →  mouse.down()  →  等 100ms  →  mouse.up()

用 Playwright 的低階滑鼠事件模擬完整的「移過去、按下、放開」節奏。200ms／100ms 的時序是 probe 實測出來的，不要亂改。 客服系統要在聊天頁點任何「假按鈕」（div 做的）時，優先試這招。

4.3 延遲與重試：慢不是錯，錯才是錯

頁面載入慢 → 重載重試迴圈：等不到目標元素時，「重新載入頁面 → 清彈窗 → 再等元素」重試 N 次（逾時與次數走環境變數可調），全失敗才報錯。機器忙、多開並行時特別需要。
整批工作 → 每項獨立重試：例如每個時間範圍的報表各自重試 3 次，一項失敗不拖垮整批；失敗的用「失敗標記版」繼續上傳並發警告，絕不靜默跳過。
strict 模式，不 fallback：下載報表找不到「含今天日期」的那筆時，寧可跳過並警告，也不點列表第一筆——那會抓到舊資料，錯的資料比沒資料更危險。
暫時性網路錯誤分開處理：DNS 抖動、連線逾時這類「等一下就好」的錯誤，用關鍵字辨識後遞增等待重試（5→10→20 秒）；權限錯誤、找不到資源這類「等再久也沒用」的錯誤立刻報，不空等。
伺服器冷卻期要尊重：蝦皮會擋連續匯出，實測兩次匯出之間要等 70 秒。這種數字寫成具名常數，並註明「實測值，不要動」。

4.4 排錯三件套

探勘腳本（probes）：對每個要自動化的頁面先寫小腳本 dump DOM 結構、試選擇器，確認可行才寫正式邏輯。腳本保留在 repo——蝦皮改版時重新探勘，不用從零猜。實戰發現：蝦皮很多真實資料（如商品 ID）DOM 上根本沒有，要從 Vue 元件內部拿（element.__vueParentComponent），這種只有探勘挖得出來。
讓程式有聲：每一步 log 講事實——「讀到 632 列、有效 630 列、拒絕 2 列（空白列）」。錯誤訊息陳述事實不猜測（❌「可能是網路問題」）。出事時 log 就是答案。
自動截圖：彈窗、失敗當下都截圖落檔。畫面比千行 log 好懂。

另一個省大量時間的原則：跨來源比對用穩定 ID，不用顯示名稱。蝦皮的名稱有全形空格、會被改名；所有字串先過統一的清洗函式（全形空格、多空白正規化），比對一律用商品 ID。客服側錄比對「哪個買家、哪筆訂單」時同理。

5. 多開架構：同時跑多個瀏覽器不打架

Concurrency Model

每次執行都開一顆獨立的 Chrome（獨立 context、獨立 cookie、獨立下載資料夾）。要同時跑多個，靠三層規則管秩序：

層級	規則	為什麼
佇列	以「帳號＋功能」為單位各開一條佇列＋一個工人。不同帳號、或同帳號不同功能→真並行；同帳號同功能→排隊。	同功能同時跑兩次會互搶自己的下載檔和 cookie；不同帳號本來就毫無關係，不該互等。
寫入互鎖	會「改到蝦皮上的錢」的功能（調預算、復原）同帳號一次只准一個在跑（per 帳號的鎖）；唯讀功能不拿鎖、完全並行。	「調整」和「復原」同時跑會對同一筆預算互相打架，這是財務風險，必須硬擋。
全域上限	同時最多 N 顆瀏覽器（semaphore，預設 2，可設定）。超過的維持排隊，輪到才開。	實測同時開太多 Chrome 會把機器塞爆：頁面載入逾時、元素等不到，全部的 run 一起變慢變炸。上限 2 反而整體最快。

搬到客服場景：2~3 個模擬器各綁一個賣場＝「不同帳號」層級，天生可以並行；但「同一個賣場的自動回覆」屬於會寫入的動作，要像 writer 鎖一樣同帳號序列化，避免對同一個買家重複回兩句。全域上限依機器規格抓（先從 2 開始實測往上調）。

6. 給智慧客服的應用藍圖

Blueprint for AI Customer Service

6.1 目標場景

開 2~3 個瀏覽器實例（「模擬器」），各自綁定不同賣場的登入 cookie，同時進到各賣場的蝦皮聊聊（客服訊息）頁面： ①智慧側錄——持續讀取買家訊息與客服人員的真實回覆，結構化存下來當訓練資料； ②模擬學習——讓 AI 讀側錄資料學回覆風格，先做「建議回覆」給人工採用，成熟後再逐步自動化。

6.2 需求對照表：客服要的每件事，這個專案都有現成做法

客服系統需求	直接沿用的做法（本專案已實戰驗證）
開視窗並綁定登入 cookie免每次掃碼／OTP	3.1 的 cookie 快取流程：首次人工登入留 120 秒窗口 → 存 cookies.json → 之後 `add_cookies` 還原身分 → 用「頁面上有沒有登入後元素」驗證 → 每次跑完回寫最新 cookie。
兩三個模擬器登不同賣場	3.2 的帳號隔離：一個賣場一個資料夾（cookie／資料／log 全隔離）＋設定用環境變數注入；配 3.3 轉換賣場處理「一個登入管多賣場」。一個實例一份 cookie 檔，絕不共用。
同時跑不互撞	5 的三層並行模型：帳號間真並行、會寫入的動作同帳號互鎖、全域瀏覽器數上限。
頁面隨時被彈窗打斷	4.1 的 `close_all_popups` 模式＋AVOID 清單（絕不點「接受／開通」）＋每個關鍵動作前重查＋彈窗自動截圖。聊聊頁一樣會被促銷 modal 蓋住。
側錄訊息、拿到穩定資料	4.4 的探勘方法論：先 probe 聊天列表與訊息 DOM；顯示層拿不到的欄位（買家 ID、訂單編號）從 Vue 元件內部撈（`__vueParentComponent`）；跨來源比對用 ID 不用暱稱；字串統一清洗。
模擬人類操作（點擊、輸入）	4.2 的方法 6 滑鼠時序繞 `isTrusted`；操作間留自然延遲。
登入態突然失效	4.1 的密碼重驗 modal 偵測：每個長操作前檢查、失效時處理或通知人工補登入，而不是整條線悄悄死掉。
長時間掛著不出事	4.3 的重試哲學（每項獨立、暫時性錯誤遞增等待、strict 不將就）＋「讓程式有聲」的 log 紀律＋管理介面的排程／暫停／中斷／通知總覽（第 2 節畫面）。

6.3 建議的起步順序（小步走，每步可驗證）

單實例 cookie 登入：先做到「一個賣場，人工登入一次，之後程式自己還原身分開到聊聊頁」。這步通了，地基就有了。
聊天頁探勘：寫 probe dump 聊天列表、訊息串的 DOM／Vue 結構，確定買家 ID、訊息、時間戳從哪拿。先探勘再寫邏輯，順序不要反。
側錄落庫：單實例持續讀訊息、結構化存 SQLite（設計好資料欄位再動手：賣場、買家 ID、方向、內容、時間、關聯訂單）。
多實例隔離：複製成 2~3 個實例，一實例一資料夾一 cookie。此時才需要並行規則。
AI 掛上去：側錄資料餵模型做「建議回覆」，人工採用率當成熟度指標；最後才考慮自動送出（送出＝寫入動作，記得上互鎖）。

💡 兩個提醒：①自動化動作只做「安全動作」——AVOID 清單的精神是絕不替賣場做不可逆的決定（同意條款、開通服務、送出承諾），客服自動回覆上線前務必訂好同等級的白名單；②蝦皮改版是常態，把選擇器、時序、網址集中放設定，並保留 probe 腳本，改版時重探勘即可，不用重寫。