SW Manager 功能說明SW Manager features
聯絡人怎麼進到系統How contacts get into the system
有兩條路,而且它們對「同一個人再送一次」的處理完全不同 —— 這是最容易誤判成 bug 的地方。There are two routes, and they handle "the same person sent again" completely differently — the single most common source of false bug reports here.
兩條路的差別The two routes
| 送法Route | 誰在用Who uses it | 同一個人再送一次Same person sent again |
|---|---|---|
| API(upsert)API (upsert) | 客戶的系統,用 API token 認證The customer's system, authenticated by API token | 先找找看這個人在不在 → 找到就更新他,並記下 Returned DateLooks the person up first — if found, updates them and stamps Returned Date |
| 畫面上的 Import ContactThe Import Contact screen | 我們自己(手動、少量)Us, by hand, in small batches | 一律當成新的建立 → 撞到重複就整批失敗Always treated as a create — a duplicate fails the whole batch |
畫面上的匯入沒有「更新」這個選項。重貼一次已經存在的資料,會看到 Import Failed 加上 Can not create/update contact with duplicated [traffic_source and external_lead_id] value。那不是壞掉 —— 它撞上的是資料庫層級的唯一限制。The import screen has no update path. Re-pasting rows that already exist gives you Import Failed and Can not create/update contact with duplicated [traffic_source and external_lead_id] value. Nothing is broken — it hit a database-level uniqueness rule.
API 怎麼判斷「是不是同一個人」How the API decides "same person"
有順序,前面的比對成功就不往下走:In order — the first match wins:
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 留空"]
flowchart TD
A["A contact arrives"] --> B{"Has a lead id<br>and a traffic source?"}
B -->|yes| C["Look up by lead id + source"]
B -->|no| D["Look up by email"]
C --> E{"Found?"}
E -->|no| D
E -->|yes| U
D --> F{"Found?"}
F -->|no| G["Look up by phone"]
F -->|yes| U
G --> H{"Found?"}
H -->|yes| U["Update the person<br>stamp Returned Date"]
H -->|no| N["Create a new contact<br>Returned Date stays empty"]
Returned Date 是什麼What Returned Date means
同一個人之前就在系統裡,後來又被送進來一次 —— 第二次進來的時間才會被記成 Returned Date。新建立的聯絡人,這個欄位是空的:不是 0、不是今天,是沒有值。The same person was already in the system and got submitted again — that second arrival is what Returned Date records. A newly created contact has nothing in this field: not zero, not today, just empty.
所以只有上面那條「更新」的路會寫入它。畫面匯入永遠走新建,不會產生 Returned Date。So only the update branch above ever writes it. The import screen always creates, and never produces a Returned Date.
為什麼 Returned Date 篩選常常篩不到東西?因為我們測試時造的資料都是新建的、只送過一次,整批都沒有這個時間。而正式環境有 539 萬筆有值(2026-10-05 查)—— 客戶就是用 API 在重複送名單。
想實際驗這個篩選,要走 API 的 upsert,不能用畫面匯入。Why does the Returned Date filter so often match nothing? Test data we create by hand is newly created and sent once, so none of it carries the timestamp. Production holds 5.39M contacts that do (checked 2026-10-05) — customers resubmit their lists through the API.
To exercise the filter for real, use the API upsert, not the import screen.
量級差很多The two routes are not the same scale
畫面匯入是把資料貼進文字框,適合少量手動操作。API 那條承受的是真實流量:2026-09-18 曾經因為客戶批次重跑,把佇列堆到 22.7K(P1 事件 LT763)。測試時要知道自己測的是哪一條 —— 把畫面匯入測完,不等於涵蓋了「聯絡人進資料」這件事。The import screen is a paste-into-a-textarea form, fine for small manual batches. The API route carries real traffic: on 2026-09-18 a customer's batch re-run pushed the queue to 22.7K (P1 incident LT763). Know which route you are testing — covering the import screen does not cover contact ingestion.
程式位置:比對順序在 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。Where the code lives: the match order is in samurai-world-backend/Modules/Contact/Jobs/ContactUpsert.php; the Returned Date write is in Modules/Contact/Contracts/ContactProcessor.php (update path only); the duplicate rule is the unique index on (account_id, external_lead_id, traffic_source). API fields and parameters live at /doc/contacts-v2.