ContactLoop

內部上手指南 · 請先登入

沒有密碼?請向管理員索取。

SW Manager 功能說明

聯絡人怎麼進到系統

有兩條路,而且它們對「同一個人再送一次」的處理完全不同 —— 這是最容易誤判成 bug 的地方。

兩條路的差別

送法 誰在用 同一個人再送一次
API(upsert) 客戶的系統,用 API token 認證 先找找看這個人在不在 → 找到就更新他,並記下 Returned Date
畫面上的 Import Contact 我們自己(手動、少量) 一律當成新的建立 → 撞到重複就整批失敗
⚠️

畫面上的匯入沒有「更新」這個選項。重貼一次已經存在的資料,會看到 Import Failed 加上 Can not create/update contact with duplicated [traffic_source and external_lead_id] value。那不是壞掉 —— 它撞上的是資料庫層級的唯一限制。

API 怎麼判斷「是不是同一個人」

有順序,前面的比對成功就不往下走:

flowchart TD
  A["收到一筆聯絡人"] --> B{"有 lead 編號<br>而且有來源?"}
  B -->|是| C["用 lead 編號 + 來源找"]
  B -->|否| D["用 email 找"]
  C --> E{"找到了?"}
  E -->|否| D
  E -->|是| U
  D --> F{"找到了?"}
  F -->|否| G["用電話找"]
  F -->|是| U
  G --> H{"找到了?"}
  H -->|是| U["更新這個人<br>寫入 Returned Date"]
  H -->|否| N["建立新的聯絡人<br>Returned Date 留空"]

Returned Date 是什麼

同一個人之前就在系統裡,後來又被送進來一次 —— 第二次進來的時間才會被記成 Returned Date。新建立的聯絡人,這個欄位是空的:不是 0、不是今天,是沒有值。

所以只有上面那條「更新」的路會寫入它。畫面匯入永遠走新建,不會產生 Returned Date。

💡

為什麼 Returned Date 篩選常常篩不到東西?因為我們測試時造的資料都是新建的、只送過一次,整批都沒有這個時間。而正式環境有 539 萬筆有值(2026-10-05 查)—— 客戶就是用 API 在重複送名單。
想實際驗這個篩選,要走 API 的 upsert,不能用畫面匯入。

量級差很多

畫面匯入是把資料貼進文字框,適合少量手動操作。API 那條承受的是真實流量:2026-09-18 曾經因為客戶批次重跑,把佇列堆到 22.7K(P1 事件 LT763)。測試時要知道自己測的是哪一條 —— 把畫面匯入測完,不等於涵蓋了「聯絡人進資料」這件事。

程式位置:比對順序在 samurai-world-backend/Modules/Contact/Jobs/ContactUpsert.php;Returned Date 的寫入點在 Modules/Contact/Contracts/ContactProcessor.php(只在更新既有聯絡人時寫);重複的限制來自 contacts 表上 (account_id, external_lead_id, traffic_source) 的唯一索引。API 的欄位與參數見 /doc/contacts-v2。