互動Interactive
Q&A 助理Q&A assistant
下面輸入框可以直接問問題——常見題會先給你題庫速答;同時問題會送進下方的即時 Q&A 板,管理員會在上面回答,其他人也能留言、點讚。再往下是整理好的分類 FAQ。Type a question in the box below — common ones get an instant answer from the FAQ; the question is also posted to the live Q&A board underneath, where admins answer and anyone can comment or like. Further down is the categorized FAQ.
即時 Q&A 板Live Q&A board
編輯後張貼到 Q&A 板Edit and post to the Q&A board
完整 FAQ(整理好的速查)Full FAQ (quick reference)
SW Manager 跟 Ava Messenger 到底差在哪?What's the real difference between SW Manager and Ava Messenger?
SW Manager(Samurai World)是「策略中樞」:管 Contact 主檔、匯入、Segment 分群、Trigger 觸發、Asset 素材、App Integration。決定 什麼時候、對誰、做什麼。SW Manager (Samurai World) is the "strategy hub": it manages the Contact master record, imports, Segment grouping, Trigger, Asset, and App Integration. It decides when, to whom, what.
Ava Messenger是「互動引擎」:實際執行對話、通話、Bot 回覆、IVR。決定 怎麼跟對方講話。Ava Messenger is the "interaction engine": it actually runs conversations, calls, Bot replies, and IVR. It decides how to talk to the person.
SW 透過 App Integration 用 API Key(=Ava Account ID)呼叫 Ava 開對話;Ava 完成後透過 Webhook 把 Journey Log / Opt-out 回寫 SW。兩者合起來才是 ContactLoop。SW calls Ava to open a conversation via App Integration using an API Key (= Ava Account ID); when Ava finishes it writes the Journey Log / Opt-out back to SW via Webhook. Together they're ContactLoop.
三個環境(stg / cl1 / prod)有什麼不同?我該用哪個?What's the difference between the three environments (stg / cl1 / prod)? Which should I use?
stg(staging.sw.onramplab.com):開發整合測試,新人練習、QA 跑測試都在這,低風險可亂搞。stg (staging.sw.onramplab.com): dev integration testing; new-hire practice and QA tests happen here. Low risk — break things freely.
cl1(manager-cl1.contactloop.com):Pre-prod / 客戶預覽,中風險,部分新版頁面可能還沒跟上 stg。cl1 (manager-cl1.contactloop.com): Pre-prod / customer preview. Medium risk; some new pages may lag behind stg.
prod(manager.contactloop.com):正式流量、真實客戶,高風險,勿任意匯入或觸發。prod (manager.contactloop.com): live traffic, real customers. High risk — don't import or trigger carelessly.
新人一律先用 stg。prod 帳號要特別申請,且操作會真的影響客戶。New hires always start in stg. A prod account requires special approval, and actions there affect real customers.
從 Ava 建帳號到 SW Segment 設定完成的完整流程是什麼?What's the full flow from creating an Ava account to finishing a SW Segment?
必須先 Ava 再 SW,因為 SW 需要 Ava 產生的 API Key 當對接鍵。Ava must come before SW, because SW needs the API Key Ava generates as the join 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 1 · Ava side: /auth/signup to register a user (Nickname/Email/Password → confirm email) → /auth/signin to log in → link Google via the user menu → Profile → Google → Link (required to create an Account) → /accounts to create an Account (Name + Transfer Phone Number + Organization; a Twilio sub-account is provisioned) → that Account's Settings → API tab to create an API Token; note down 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(已指派)+ 匯入四者設好,整條流程才算接通。Phase 2 · SW side: /auth/signin to log in → create/pick a SW Account (must be added to an Organization and assigned to the User before it's visible) → /app-integrations create the Ava integration (Account ID = Ava Account ID, check Sandbox in stg) → under Configuration create an Asset message template (Interaction Type / Template / Campaign, what) → under Configuration create a Segment and verify its count (to whom + when) → create an Action (Channel + pick the Asset, remember to click Add) and assign it to the Segment (which channel) → /contacts/import to import a list (only contacts matching the Segment rule with an assigned Action trigger Ava) → /contacts-27 to review the contacts. Only when Segment + Asset + Action (assigned) + import are all set is the flow connected end to end.
第一次全程請在 stg 跑;Ava Account 一旦建立會產生真實 Twilio 門號費用,prod 勿任意練習。Run the whole thing in stg the first time; creating an Ava Account incurs real Twilio number charges, so don't practice in prod.
怎麼切換 Account?How do I switch accounts?
點左上角的帳號切換器。SW 有三代 UI 相容,測試程式會依序嘗試:最新版是 button.crumb-account-button 按鈕、中版是 button.BreadcrumbTrigger、舊版是 Ant Select 下拉。選好後帳號名後會顯示 (ID: nn)。Ava 則用階層式 cascader 選帳號。Click the top-left account switcher. SW has three coexisting UI generations; the test tries them in order: newest is the button.crumb-account-button, mid is button.BreadcrumbTrigger, legacy is an Ant Select dropdown. After selecting, the account name shows (ID: nn). Ava uses a hierarchical cascader to pick accounts.
登入 SW 之後,它怎麼決定我看得到哪些組織?為什麼會有一個空的組織?After signing in to SW, how does it decide which organizations I can see? And why is there an empty one?
只有一支 API。開啟 SW 自動登入後,前端只打 POST /auth/me,組織清單是這支的回應順便帶回來的 —— 沒有另外一支專門抓組織的 API。Just one API call. When SW signs you in, the front end calls POST /auth/me and nothing else — the organization list comes back inside that same response. There is no separate endpoint for organizations.
舊版本曾經是「先拿使用者,再打 GET /users/{id}/organizations 補資料」。那條路已經隨著 Organizations 這個 feature flag 一起移除,現在前端的 loadUserOrganizations() 只是把回應裡的欄位讀出來,不發任何請求。Older builds fetched the user first and then called GET /users/{id}/organizations to fill in the rest. That path was removed along with the Organizations feature flag; loadUserOrganizations() now just reads a field off the response and makes no request of its own.
後端的 AuthController::me() 做三件事:確保這個使用者至少有一個個人組織(沒有就自動補建)、把每個組織底下的 account 一起載出來、再依可見範圍過濾 account。On the backend, AuthController::me() does three things: make sure the user has at least one personal organization (creating one if absent), eager-load each organization's accounts, then filter those accounts by what the user may see.
所以那個空的組織是哪來的:就是自動補建的個人組織。新帳號還沒被指派到任何組織時,它一樣會存在,而且裡面沒有任何 account。So where does the empty organization come from: it is that auto-provisioned personal organization. A new account that has not been assigned anywhere still gets one, and it holds no accounts.
登入後預設落在哪:挑第一個擁有至少一個 account 的組織 —— 這條規則就是為了跳過上面那個空組織。如果真的每個組織都沒有 account,才退回清單的第一個。Which organization you land on: the first organization that owns at least one account — the rule exists precisely to skip that empty one. Only when no organization owns an account does it fall back to the first entry.
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>通常就是那個自動補建的空組織"]
flowchart TD
A["Open SW with a valid session"] --> B["POST /auth/me<br>(the only request in this flow)"]
B --> C["Ensure a personal organization<br>create an empty one if absent"]
C --> D["Eager-load each organization's accounts"]
D --> E["Filter accounts by visibility"]
E --> F["Response: organizations[]<br>each already carrying its accounts[]"]
F --> G["Front end reads the response<br>no second request"]
G --> H{"Does any organization<br>own at least one account?"}
H -->|yes| I["Land on the first one that does"]
H -->|no| J["Fall back to the first entry<br>usually the auto-provisioned empty org"]
程式位置:前端 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()。Where the code lives: front end samurai-world-client/src/modules/auth/services/AuthService.ts (issues /auth/me) and src/modules/account/components/Accountable.tsx (reads the organizations, picks the default); backend me() in samurai-world-backend/Modules/Auth/Http/Controllers/AuthController.php.
Account ID 在哪設定?為什麼 .env 裡找不到?Where is the Account ID configured? Why isn't it in .env?
Account ID 寫在 auto_cl/conftest.py 的 ENV_CONFIG 裡,不在 .env。例如 stg 的 sw_nucleus.account_id 是 "93"、cl1 是 "38"、prod 是 "361"。換帳號要改程式碼,且每個環境 ID 都不同,不能互通。The Account ID lives in ENV_CONFIG inside auto_cl/conftest.py, not in .env. For example stg's sw_nucleus.account_id is "93", cl1 is "38", prod is "361". Switching accounts means editing code, and each environment's ID is different — they don't carry over.
.env 必填欄位有哪些?Which .env fields are required?
基本跑頁面測試只需要該環境的 SW / Ava 帳密,例如 stg:STG_SW_EMAIL、STG_SW_PASSWORD、STG_AVA_EMAIL、STG_AVA_PASSWORD。For basic page tests you only need that environment's SW / Ava credentials, e.g. 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。Running Nucleus (the SMS integration flow) also needs QUO_API_KEY, QUO_phoneNumberId, QUO_participants_stg. For email notifications add SMTP_EMAIL/PASSWORD; for Teams notifications TEAMS_WEBHOOK_URL; for R2 uploads R2_*. See .env.example for the template.
Admin 頁面進不去、一直 403?Can't get into Admin pages — keeps 403?
正常。/admin/*(如 admin/contacts、admin/actions)與 Configuration / Settings 類頁面需要 system-admin 權限,一般帳號會被擋 403。測試 test_sw_page_api_checks.py 因此只覆蓋非 Admin 頁面,避免把 403 誤判成 bug。要測 Admin 頁面得先用具備 system-admin 權限的帳號。That's expected. /admin/* (e.g. admin/contacts, admin/actions) and Configuration / Settings pages require system-admin permission; a normal account gets 403. That's why test_sw_page_api_checks.py only covers non-Admin pages, to avoid mistaking a 403 for a bug. To test Admin pages you need an account with system-admin permission.
為什麼 Returned Date 篩不到任何資料?Why does the Returned Date filter never match anything?
不是壞掉,是你手上的資料裡沒有「回頭客」。「Returned」指的是同一個人之前就在系統裡、後來又被送進來一次,而只有 API 的 upsert 會寫入這個時間;畫面上的 Import Contact 一律當成新建,撞到重複就整批失敗。所以我們手動造的測試資料永遠沒有它,怎麼篩都是空的 —— 正式環境則有 539 萬筆有值。Nothing is broken — your data has no returning contacts. "Returned" means the same person was already in the system and got submitted again, and only the API upsert ever stamps it; the Import Contact screen always creates, failing the whole batch on a duplicate. Test data made by hand never carries it, so the filter looks dead — while production holds 5.39M contacts that do.
完整說明(比對順序、唯一索引、兩條路的量級差異)見 聯絡人怎麼進到系統。Full explanation (match order, the unique index, how differently the two routes scale) in How contacts get into the system.
刷新按鈕(Refresh)和「Loaded N / N」怎麼不見了?Where did Refresh and "Loaded N / N" go?
兩種情況會看不到,都是正常的:你在 Actions 系列的六個報表頁(那些頁面本來就沒有這組控制項,跟設定無關),或是 Contacts 頁切到了伺服器端載入(資料分塊取,「總共載入幾筆」本身就不存在)。網址加 ?ssrm=0 可以切回一般模式。Two situations hide it, both expected: you are on one of the six Actions report pages (they never have the strip, regardless of settings), or a Contacts page switched to server-side loading (rows arrive block by block, so a total has no meaning). Add ?ssrm=0 to the URL to force client-side.
完整說明(模式怎麼決定、Download 為什麼會變灰)見 表格的載入模式。Full explanation (how the mode is chosen, why Download greys out) in How the grids load their rows.
Actions 頁面的 "Total: Filtered" 為什麼數字不對?Why is the "Total: Filtered" number on the Actions page wrong?
已知 bug(Trello f1cfO0nU)。時間範圍過大時,產生 grid 的 Elasticsearch terms aggregation 超過 bucket_limit(60000),回應的 meta.completeness.capped=true,導致 Total: Filtered 嚴重低估(3 個月範圍差約 2.4 倍)。Known bug (Trello f1cfO0nU). When the time range is too large, the Elasticsearch terms aggregation that builds the grid exceeds bucket_limit (60000), the response sets meta.completeness.capped=true, and Total: Filtered is badly undercounted (a 3-month range is off by ~2.4x).
測試 TestActionsTotalCompletenessRegression 會斷言 capped=false,後端修復前預期失敗(xfail),不會讓 CI 變紅;修復後會自動轉 XPASS 提醒可以拿掉 xfail。The test TestActionsTotalCompletenessRegression asserts capped=false; until the backend is fixed it's expected to fail (xfail) so it doesn't turn CI red. Once fixed it auto-flips to XPASS, signaling the xfail can be removed.
Contacts-27 / Contacts (old) / Contacts Grid (old) 差在哪?What's the difference between Contacts-27 / Contacts (old) / Contacts Grid (old)?
Contacts-27(新版):主要列表,打 /api/contacts/grid,ag-grid 風格,回應 data.rows / data.lastRow。2026-08 前端改版後的標準頁。Contacts-27 (new): the main list, calls /api/contacts/grid, ag-grid style, returns data.rows / data.lastRow. The standard page after the 2026-08 frontend revamp.
Contacts (old):舊版,size=20 分頁,回應 data.result.contacts / meta。Contacts (old): legacy, size=20 pagination, returns data.result.contacts / meta.
Contacts Grid (old):舊版 ag-grid,同樣打 /api/contacts/grid。Contacts-26 (old) 則打 size=500,結構與 Contacts-27 相同。Contacts Grid (old): legacy ag-grid, also calls /api/contacts/grid. Contacts-26 (old) calls size=500 with the same structure as Contacts-27.
新舊並存是為了遷移過渡,新人操作請用 Contacts-27。Old and new coexist for migration; new hires should use Contacts-27.
SMS 驗證為什麼改用 Quo?Toky 不能用了嗎?Why did SMS verification switch to Quo? Is Toky unusable now?
2026-08 起 SMS 從 Toky 換成 Quo。Toky 已停止 SMS 發送服務、只剩接收,所以測試用的 lead 號碼與模擬發送都改用 Quo API。讀取驗證與模擬 lead 發訊都走 api.quo.com/v1/messages,Authorization header 直接帶 API Key(非 Bearer 格式)。號碼用 E.164 格式(+1…)。From 2026-08 SMS moved from Toky to Quo. Toky stopped SMS sending and only receives, so test lead numbers and simulated sends now use the Quo API. Read verification and simulated lead messaging both go through api.quo.com/v1/messages, with the API Key placed directly in the Authorization header (not Bearer format). Numbers use E.164 format (+1…).
怎麼只跑某一個測試?How do I run just one test?
單支檔:pytest tests/test_sw_segments.py --env stg -vOne file: pytest tests/test_sw_segments.py --env stg -v
單一方法:pytest tests/test_sw_segments.py::TestSW::test_sw_segments_count2 --env stg -vOne method: 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)By marker: pytest -m Ava --env stg -v (Ava only), pytest -m "not Sms" --env stg -v (exclude SMS)
Windows 記得先 $env:PYTHONUTF8=1 避免編碼問題。On Windows, run $env:PYTHONUTF8=1 first to avoid encoding issues.
測試影片與報告在哪裡?Where are the test videos and reports?
報告: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 份歸檔。Report: reports/report.html; log: reports/test.log; video: videos/ (filename carries environment + timestamp; a single continuous video includes the linked-page visits); API stats: reports/api_metrics.json. On anomalies it also emits reports/ava_link_issues.json and reports/sw_page_api_issues.json. runs/ auto-keeps the latest 10 archives.
Ava 連結驗證失敗代表什麼?What does an Ava link-verification failure mean?
test_ava_link.py 會對每個 account 抽 3–5 則對話,點擊 Ava 發送的連結驗證 HTTP 狀態。chrome-error:// / about: 代表瀏覽器層連不上;HTTP ≥ 400 代表連結頁面異常。測試整體仍會 PASSED(連結異常不中止測試),但會把異常寫進 reports/ava_link_issues.json,Email / Teams 通知會附專屬異常表格,需人工確認。test_ava_link.py samples 3–5 conversations per account and clicks the links Ava sent to verify the HTTP status. chrome-error:// / about: means the browser layer can't connect; HTTP ≥ 400 means the linked page is broken. The overall test still PASSED (link issues don't abort the run), but anomalies are written to reports/ava_link_issues.json, and the Email / Teams notification attaches a dedicated anomaly table for manual review.
通知信出現 Gmail 535 錯誤怎麼解?How do I fix a Gmail 535 error in notification emails?
535 是 SMTP 認證失敗。確認 SMTP_EMAIL 與 SMTP_PASSWORD 正確——Gmail 不能用主密碼,必須在 Google 帳號安全設定裡建立 App Password 並用那組密碼。535 is an SMTP auth failure. Check that SMTP_EMAIL and SMTP_PASSWORD are correct — Gmail won't accept your main password; you must create an App Password in your Google account security settings and use that.
CL1 的某些頁面 API 檢查為什麼是 xfail?Why are some CL1 page API checks xfail?
這是「環境版本落差」,不是壞掉。stg 通常是最新版,cl1 / prod 的前端部署會晚一點跟上。例如 2026-08 實測:stg 的 Marketing Sources / Endpoint Attributes / Technographics 已改打 /api/contacts/grid,但 cl1 還在打舊版 /api/contacts?…size=500。It's an "environment version lag", not a breakage. stg is usually the newest; cl1 / prod frontends deploy a bit later. Example from 2026-08: stg's Marketing Sources / Endpoint Attributes / Technographics already call /api/contacts/grid, but cl1 still calls the legacy /api/contacts?…size=500.
這類情況登記在 KNOWN_ENV_LAG_XFAILS,標成 xfail 避免每次 CI 跑都被通知洗版;等 cl1 部署跟上會自動轉 XPASS,屆時就可拿掉該設定。These are listed in KNOWN_ENV_LAG_XFAILS and marked xfail so CI runs don't spam notifications; when cl1 catches up it auto-flips to XPASS and the setting can be removed.