ContactLoop

內部上手指南 · 請先登入

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

互動

Q&A 助理

下面輸入框可以直接問問題——常見題會先給你題庫速答;同時問題會送進下方的即時 Q&A 板,管理員會在上面回答,其他人也能留言、點讚。再往下是整理好的分類 FAQ。

嗨!我是 ContactLoop 新人助手。可以問我「stg 跟 cl1 差在哪」「.env 要填什麼」「Total Filtered 為什麼不對」之類的問題 👋

即時 Q&A 板

載入中…

完整 FAQ(整理好的速查)

概念
SW Manager 跟 Ava Messenger 到底差在哪?

SW Manager(Samurai World)是「策略中樞」:管 Contact 主檔、匯入、Segment 分群、Trigger 觸發、Asset 素材、App Integration。決定 什麼時候、對誰、做什麼。

Ava Messenger是「互動引擎」:實際執行對話、通話、Bot 回覆、IVR。決定 怎麼跟對方講話。

SW 透過 App Integration 用 API Key(=Ava Account ID)呼叫 Ava 開對話;Ava 完成後透過 Webhook 把 Journey Log / Opt-out 回寫 SW。兩者合起來才是 ContactLoop。

三個環境(stg / cl1 / prod)有什麼不同?我該用哪個?

stg(staging.sw.onramplab.com):開發整合測試,新人練習、QA 跑測試都在這,低風險可亂搞。

cl1(manager-cl1.contactloop.com):Pre-prod / 客戶預覽,中風險,部分新版頁面可能還沒跟上 stg。

prod(manager.contactloop.com):正式流量、真實客戶,高風險,勿任意匯入或觸發。

新人一律先用 stg。prod 帳號要特別申請,且操作會真的影響客戶。

帳號 / 設定
從 Ava 建帳號到 SW Segment 設定完成的完整流程是什麼?

必須先 Ava 再 SW,因為 SW 需要 Ava 產生的 API Key 當對接鍵。

Phase 1 · Ava 端:/auth/signup 註冊使用者(Nickname/Email/Password → 收信)→ /auth/signin 登入 → 右上使用者選單 → Profile → Google → Link 綁定 Google(沒綁不能建 Account)→ /accounts 建 Account(Name + Transfer Phone Number + Organization,會開 Twilio 子帳號)→ 該 Account 的 Settings → API tab 建立 API Token,記下 Account ID + API Token。

Phase 2 · SW 端:/auth/signin 登入 → 建/選 SW Account(需先加入 Organization 並指給 User 才看得到)→ /app-integrations 建 Ava 整合(Account ID 填 Ava Account ID,stg 勾 Sandbox)→ Configuration 下建 Asset 訊息樣板(Interaction Type / Template / Campaign,發什麼)→ Configuration 下建 Segment 並驗證計數(對誰 + 何時)→ 建立 Action(Channel + 選 Asset,記得點 Add)指派回 Segment(用哪個管道)→ /contacts/import 匯入名單(命中 Segment 規則且 Action 已指派者才會觸發 Ava)→ /contacts-27 查看聯絡人資料。Segment + Asset + Action(已指派)+ 匯入四者設好,整條流程才算接通。

第一次全程請在 stg 跑;Ava Account 一旦建立會產生真實 Twilio 門號費用,prod 勿任意練習。

怎麼切換 Account?

點左上角的帳號切換器。SW 有三代 UI 相容,測試程式會依序嘗試:最新版是 button.crumb-account-button 按鈕、中版是 button.BreadcrumbTrigger、舊版是 Ant Select 下拉。選好後帳號名後會顯示 (ID: nn)。Ava 則用階層式 cascader 選帳號。

登入 SW 之後,它怎麼決定我看得到哪些組織?為什麼會有一個空的組織?

只有一支 API。開啟 SW 自動登入後,前端只打 POST /auth/me,組織清單是這支的回應順便帶回來的 —— 沒有另外一支專門抓組織的 API。

舊版本曾經是「先拿使用者,再打 GET /users/{id}/organizations 補資料」。那條路已經隨著 Organizations 這個 feature flag 一起移除,現在前端的 loadUserOrganizations() 只是把回應裡的欄位讀出來,不發任何請求。

後端的 AuthController::me() 做三件事:確保這個使用者至少有一個個人組織(沒有就自動補建)、把每個組織底下的 account 一起載出來、再依可見範圍過濾 account。

所以那個空的組織是哪來的:就是自動補建的個人組織。新帳號還沒被指派到任何組織時,它一樣會存在,而且裡面沒有任何 account。

登入後預設落在哪:挑第一個擁有至少一個 account 的組織 —— 這條規則就是為了跳過上面那個空組織。如果真的每個組織都沒有 account,才退回清單的第一個。

flowchart TD
  A["開啟 SW,session 仍有效"] --> B["POST /auth/me<br>(整個流程只有這一支請求)"]
  B --> C["確保有個人組織<br>沒有就自動補建一個空的"]
  C --> D["載出每個組織底下的 account"]
  D --> E["依可見範圍過濾 account"]
  E --> F["回應:organizations[]<br>每個都帶著自己的 accounts[]"]
  F --> G["前端直接讀回應<br>不再發第二個請求"]
  G --> H{"有沒有組織<br>擁有至少一個 account?"}
  H -->|有| I["落在第一個有 account 的組織"]
  H -->|沒有| J["退回清單第一個<br>通常就是那個自動補建的空組織"]

程式位置:前端 samurai-world-client/src/modules/auth/services/AuthService.ts(送出 /auth/me)與 src/modules/account/components/Accountable.tsx(讀取組織、決定預設落點);後端 samurai-world-backend/Modules/Auth/Http/Controllers/AuthController.php 的 me()。

Account ID 在哪設定?為什麼 .env 裡找不到?

Account ID 寫在 auto_cl/conftest.py 的 ENV_CONFIG 裡,不在 .env。例如 stg 的 sw_nucleus.account_id 是 "93"、cl1 是 "38"、prod 是 "361"。換帳號要改程式碼,且每個環境 ID 都不同,不能互通。

.env 必填欄位有哪些?

基本跑頁面測試只需要該環境的 SW / Ava 帳密,例如 stg:STG_SW_EMAIL、STG_SW_PASSWORD、STG_AVA_EMAIL、STG_AVA_PASSWORD。

跑 Nucleus(SMS 整合流程)還需要 QUO_API_KEY、QUO_phoneNumberId、QUO_participants_stg。要收信通知需 SMTP_EMAIL/PASSWORD;要 Teams 通知需 TEAMS_WEBHOOK_URL;要上傳 R2 需 R2_*。範本見 .env.example。

Admin 頁面進不去、一直 403?

正常。/admin/*(如 admin/contacts、admin/actions)與 Configuration / Settings 類頁面需要 system-admin 權限,一般帳號會被擋 403。測試 test_sw_page_api_checks.py 因此只覆蓋非 Admin 頁面,避免把 403 誤判成 bug。要測 Admin 頁面得先用具備 system-admin 權限的帳號。

報表與篩選
為什麼 Returned Date 篩不到任何資料?

不是壞掉,是你手上的資料裡沒有「回頭客」。「Returned」指的是同一個人之前就在系統裡、後來又被送進來一次,而只有 API 的 upsert 會寫入這個時間;畫面上的 Import Contact 一律當成新建,撞到重複就整批失敗。所以我們手動造的測試資料永遠沒有它,怎麼篩都是空的 —— 正式環境則有 539 萬筆有值。

完整說明(比對順序、唯一索引、兩條路的量級差異)見 聯絡人怎麼進到系統。

刷新按鈕(Refresh)和「Loaded N / N」怎麼不見了?

兩種情況會看不到,都是正常的:你在 Actions 系列的六個報表頁(那些頁面本來就沒有這組控制項,跟設定無關),或是 Contacts 頁切到了伺服器端載入(資料分塊取,「總共載入幾筆」本身就不存在)。網址加 ?ssrm=0 可以切回一般模式。

完整說明(模式怎麼決定、Download 為什麼會變灰)見 表格的載入模式。

Actions 頁面的 "Total: Filtered" 為什麼數字不對?

已知 bug(Trello f1cfO0nU)。時間範圍過大時,產生 grid 的 Elasticsearch terms aggregation 超過 bucket_limit(60000),回應的 meta.completeness.capped=true,導致 Total: Filtered 嚴重低估(3 個月範圍差約 2.4 倍)。

測試 TestActionsTotalCompletenessRegression 會斷言 capped=false,後端修復前預期失敗(xfail),不會讓 CI 變紅;修復後會自動轉 XPASS 提醒可以拿掉 xfail。

頁面差異
Contacts-27 / Contacts (old) / Contacts Grid (old) 差在哪?

Contacts-27(新版):主要列表,打 /api/contacts/grid,ag-grid 風格,回應 data.rows / data.lastRow。2026-08 前端改版後的標準頁。

Contacts (old):舊版,size=20 分頁,回應 data.result.contacts / meta。

Contacts Grid (old):舊版 ag-grid,同樣打 /api/contacts/grid。Contacts-26 (old) 則打 size=500,結構與 Contacts-27 相同。

新舊並存是為了遷移過渡,新人操作請用 Contacts-27。

SMS / 測試
SMS 驗證為什麼改用 Quo?Toky 不能用了嗎?

2026-08 起 SMS 從 Toky 換成 Quo。Toky 已停止 SMS 發送服務、只剩接收,所以測試用的 lead 號碼與模擬發送都改用 Quo API。讀取驗證與模擬 lead 發訊都走 api.quo.com/v1/messages,Authorization header 直接帶 API Key(非 Bearer 格式)。號碼用 E.164 格式(+1…)。

怎麼只跑某一個測試?

單支檔:pytest tests/test_sw_segments.py --env stg -v

單一方法:pytest tests/test_sw_segments.py::TestSW::test_sw_segments_count2 --env stg -v

依 marker:pytest -m Ava --env stg -v(只跑 Ava)、pytest -m "not Sms" --env stg -v(排除 SMS)

Windows 記得先 $env:PYTHONUTF8=1 避免編碼問題。

測試影片與報告在哪裡?

報告:reports/report.html;log:reports/test.log;影片:videos/(檔名帶環境與時間戳,單一連續影片含連結頁面訪問);API 統計:reports/api_metrics.json。有異常時額外產生 reports/ava_link_issues.json 與 reports/sw_page_api_issues.json。runs/ 會自動保留最新 10 份歸檔。

Ava 連結驗證失敗代表什麼?

test_ava_link.py 會對每個 account 抽 3–5 則對話,點擊 Ava 發送的連結驗證 HTTP 狀態。chrome-error:// / about: 代表瀏覽器層連不上;HTTP ≥ 400 代表連結頁面異常。測試整體仍會 PASSED(連結異常不中止測試),但會把異常寫進 reports/ava_link_issues.json,Email / Teams 通知會附專屬異常表格,需人工確認。

通知信出現 Gmail 535 錯誤怎麼解?

535 是 SMTP 認證失敗。確認 SMTP_EMAIL 與 SMTP_PASSWORD 正確——Gmail 不能用主密碼,必須在 Google 帳號安全設定裡建立 App Password 並用那組密碼。

CL1 的某些頁面 API 檢查為什麼是 xfail?

這是「環境版本落差」,不是壞掉。stg 通常是最新版,cl1 / prod 的前端部署會晚一點跟上。例如 2026-08 實測:stg 的 Marketing Sources / Endpoint Attributes / Technographics 已改打 /api/contacts/grid,但 cl1 還在打舊版 /api/contacts?…size=500。

這類情況登記在 KNOWN_ENV_LAG_XFAILS,標成 xfail 避免每次 CI 跑都被通知洗版;等 cl1 部署跟上會自動轉 XPASS,屆時就可拿掉該設定。