Quartz 5

search_add

5 min read

search_add

文件狀態：草稿 / 部分已對 new API / 待補完整來源鏈
最後驗證：2026-05-07
來源：Common Process Documents 整理、repo 既有 search_add 測試與 DB baseline 經驗；待補 legacy / new code 逐段來源

目的

search_add 是 consumer 發案主流程。它會建立 requestor context、寫入案件需求、找可配對 provider service，並建立對應的 quote bids 與 downstream queue。

這份文件是完整 trace 入口。單張 table 的欄位細節請回到：

search_add 本身通常不是扣款主線；扣款多發生在後續正式 contact provider。相關規則見 quote_bid_contact_charge。

主流程簡圖

consumer submit search_add
-> 驗 API key / session / security hash 或 auto signup context
-> 建立或解析 users / user_profiles / api_sessions
-> 建立 quote_requests
-> 寫 quote_form_submission_fields
-> 寫 quote_request_match_infos
-> 依 category / location / service rule 找 quote_services
-> 建立 quote_bids
-> 更新 quote_requests sent/contact counters
-> 寫 quote_activities
-> 送 event_queue / task_event_queue
-> 回 search_add response

Actor 與身份

search_add 的 actor 可能是已登入 user，也可能是 auto signup / hash flow 建立出來的 requestor。

排查時先確認：

session actor 是誰
quote_requests.user_id 是誰
user_profiles 是否有電話 / 姓名
api_sessions 是否被建立或沿用

身份驗證與 session 規則請看 專案身份驗證方式。

主要資料表順序

階段主要資料表說明
requestorusers, user_profiles, api_sessions找既有 user、auto signup、建立 session 或 profile
requestquote_requests案件主體，後續 bid / form / queue 都回到這筆 request
formquote_form_submission_fields表單答案與需求欄位
match metadataquote_request_match_infossearch_add 配對相關資訊
provider servicequote_services, quote_service_categories可被配對的 provider service 與 category 設定
bidsquote_bids對每個 provider service 建立 bid / auto quote / narrow match 狀態
activityquote_activitiesrequest / bid activity
asyncevent_queue, task_event_queue通知、統計、後續 worker 任務

Table 視角

quote_requests

quote_requests 是 search_add 的主體結果。排查成功與否時先找到 request id，再往下查 bids / form / queue。

常看欄位：

id
user_id
quote_category_id
match_type
sent_count
auto_quote_sent_count
auto_quote_contact_count
contact_charge_quote_count
contact_charge_contact_count
is_closed
is_archived
is_expired

users

users 在 search_add 中是 requestor，不是 provider。若流程走 auto signup，要同時查 user_profiles 與 api_sessions。

常看欄位 / 關聯：

users.id
users.email
users.phone
users.device_id
users.is_phone_confirmed
user_profiles.phone
api_sessions.user_id
api_sessions.device_id

quote_services

quote_services 是 provider service pool。search_add 會依 category、location、provider/service 狀態找可配對服務，再用它建立 quote_bids.quote_service_id。

排查 provider 為什麼有 / 沒有被配對時，不能只看 quote_bids，也要回查 quote_services 與 quote_service_categories。

quote_bids

quote_bids 是 search_add 的配對結果。search_add 建 bid 不代表 consumer 已正式聯絡 provider。

關鍵判斷：

quote_bids.is_want_to_contact_provider = 0
quote_bids.contact_provider_on = NULL

正式聯絡與扣款通常發生在後續 want_to_contact_provider 或 narrow match accept。

transactions

search_add 主線通常不應被當成 quote bid contact charge。若看到 transaction，要確認是不是 downstream contact、wallet/card 補款、測試資料殘留，或其他流程造成。

transaction 判讀請看 transactions 與 quote_bid_contact_charge。

Queue / Event 判讀

search_add 會送多種 downstream queue。排查時不要假設 row 一定還在原 queue table。

event_queue OR event_queue_log_1..event_queue_log_4
task_event_queue OR task_event_queue_log

queue / log 判讀規則請看 Queue 與 Event 系統。

第一輪排查 SQL

查 request

SELECT
  id,
  user_id,
  quote_category_id,
  match_type,
  sent_count,
  auto_quote_sent_count,
  auto_quote_contact_count,
  contact_charge_quote_count,
  contact_charge_contact_count,
  is_closed,
  is_archived,
  is_expired,
  created
FROM quote_requests
WHERE id = <quote_request_id>;

查 bids

SELECT
  id,
  quote_request_id,
  quote_service_id,
  provider_user_id,
  is_auto_quote,
  is_narrow_match,
  narrow_status_id,
  is_contact_charge,
  is_want_to_contact_provider,
  contact_provider_on,
  quote_status_id,
  provider_status_id,
  total_site_fee,
  quote_user_subscription_log_id
FROM quote_bids
WHERE quote_request_id = <quote_request_id>
ORDER BY id DESC;

查 requestor

SELECT
  u.id,
  u.email,
  u.phone,
  u.device_id,
  u.is_phone_confirmed,
  up.phone AS profile_phone,
  up.first_name
FROM users u
LEFT JOIN user_profiles up ON up.user_id = u.id
WHERE u.id = <requestor_user_id>;

查 form fields

SELECT *
FROM quote_form_submission_fields
WHERE quote_request_id = <quote_request_id>
ORDER BY id;

查 match info

SELECT *
FROM quote_request_match_infos
WHERE quote_request_id = <quote_request_id>
ORDER BY id DESC;

判讀原則

  • 先用 quote_requests.id 當 trace anchor。
  • search_add 成功不等於 provider 已被正式聯絡。
  • 是否正式聯絡看 quote_bids.is_want_to_contact_provider。
  • 是否扣款看 transactions，不要從 search_add response 推論。
  • queue 相關驗證要接受 queue 或 log 任一存在。
  • 若要查 DB / schema，依專案 AGENTS 規則使用容器 PHP + DBFactory，不要用本機 PHP。

Graph View

Backlinks