Quartz 5

README

7 min read

資料表流程

目的

這裡整理「以 DB table 為中心」的流程文件。

這類文件不是單純描述某支 API，而是說明一張核心資料表在不同流程中如何被建立、更新，以及它和其他資料表的關係。

完整 business flow 的入口不放在這裡，而是放在 業務流程。資料表流程 只回答「這張 table 在各流程中扮演什麼角色、哪些欄位會變、要怎麼查」。

文件架構

資料表流程 以核心 aggregate table 為第一層，不追求每張 table 都建一份文件。

現階段先用 README 章節區分「核心資料表」與「關聯與紀錄表」，暫時不搬現有資料夾。等文件數量變多、連結穩定後，再考慮實體切成：

資料表流程/
  核心資料表/
  關聯與紀錄表/

這樣可以先建立分類規則，又避免現在搬資料夾造成 Obsidian / Markdown 相對連結大規模失效。

每個核心資料夾建議維持同樣結構：

<table>/
  README.md
  狀態欄位總覽.md
  欄位/
  流程/
  關聯/
  案例/

欄位文件說明單一欄位如何被不同流程修改；流程文件只寫 table 視角，不重寫完整 API trace；關聯文件說明和其他核心 table 的依賴關係。

分類原則

核心資料表

可以作為排查入口、承載主要業務狀態，或跨多支 API / worker 都會共同修改的 table。

判斷標準：

  • 可從這張表開始 trace 一段完整業務流程。
  • 狀態欄位會被多個 API / worker 改變。
  • 常常需要和 log、queue、transaction、身份或付款一起判讀。
  • 文件值得有自己的 README.md、欄位/、流程/、關聯/。

關聯與紀錄表

需要搭配核心表判讀，通常不應一開始就獨立成第一層。

常見類型：

  • profile / session / credential table
  • activity / log / history table
  • reserve / form submission / match info 等流程附屬資料
  • payment method / provider response / block setting
  • enum / lookup / mapping table

這類表如果只服務單一核心 table，先放在核心 table 的 關聯/ 或 流程/。只有當它跨多個流程反覆成為排查入口時，再升級成獨立資料夾。

核心資料表

資料表說明
quote_requests案件主體，requestor、需求內容、狀態、copy/search_add/change_status 等流程的源頭
quote_bids報價 bid 狀態流，包含 search_add、consumer 聯絡 provider、扣款與 activity
quote_servicesprovider 服務主體，影響配對、服務啟用、category/service 關聯與 bid 的 service owner
usersrequestor / provider 身份、profile、session、phone、wallet、blocked / qualification 相關狀態
transactions交易與扣款紀錄，連結 quote bid contact charge、wallet/card/TapPay/Stripe 狀態
quote_activitiesquote flow 事件時間線，供聊天室、inbox、my work / my request、後台與部分統計判讀

關聯與紀錄表候選

這些表目前不急著獨立成第一層。先在相關核心表或流程文件中描述，避免資料表文件爆量。

資料表先放在哪裡何時升級成獨立文件
quote_request_reservesquote_requests/關聯/、quote_bids/流程/consumer_want_provider_quotereserve / direct reserve 成為獨立排查主題時
quote_form_submission_fieldsquote_requests/關聯/、search_addform submission 欄位規則需要跨 API 維護時
quote_request_match_infosquote_requests/關聯/、search_add / narrow matchmatch info 影響多個配對流程時
user_profilesusers/關聯/profile / phone / name 規則需要獨立 trace 時
api_sessionsusers/關聯/、專案身份驗證方式session token / device 規則跨多支 API 排查時
stripe_customersusers/關聯/、付款與扣款流程card / auto quote payment method 規則需要獨立判讀時
blocked_user_configs / blocked_chat_usersusers/關聯/、narrow match / contact chargeblock 規則反覆造成 contact error 時
event_queue / event_queue_log_1..event_queue_log_4Queue 與 Event 系統不放資料表流程第一層，因 queue 有自己的共同流程
task_event_queue / task_event_queue_logQueue 與 Event 系統不放資料表流程第一層，因 queue 有自己的共同流程

和業務流程的關係

以 search_add 為例：

業務流程/search_add.md
  -> 完整 API 到 DB / queue trace
 
資料表流程/quote_requests/...
  -> search_add 對 quote_requests 做了什麼
 
資料表流程/quote_bids/...
  -> search_add 產生 quote_bids 時的初始狀態
 
資料表流程/quote_services/...
  -> search_add 如何使用 provider service pool
 
資料表流程/users/...
  -> search_add 中 requestor / auto signup / session 如何判斷

不要在四個 table 文件各自重寫完整 search_add，否則後續會互相矛盾。

優先補文件的判斷

優先補「跨多支 API、排查時需要一起看的 table」。目前建議順序：

  1. quote_requests
  2. quote_bids
  3. quote_services
  4. users
  5. transactions

如果某張 table 只是 lookup table 或單一流程的附屬表，先寫在核心 table 的 關聯/ 或 流程/ 內，不必立刻獨立成第一層。

適合放在這裡的內容

  • 重要 table 的欄位意義
  • 狀態欄位如何變化
  • 哪些 API / worker / processor 會修改該 table
  • table 之間的關聯
  • 常用 SQL 與排查順序

不適合直接獨立成核心資料夾的內容

  • 單純 enum / lookup table：先放在引用它的核心 table 文件。
  • 單一 API 專用暫存表：先放在該 API 的流程文件。
  • queue payload 細節：放在 Queue 與 Event 系統。
  • 金流分支規則：放在 付款與扣款流程，資料表文件只保留 transaction 關聯與狀態判讀。

不適合放在這裡的內容

  • 單純 API curl 範例
  • 單次測試紀錄
  • 沒有資料表狀態關聯的產品規則

這些可以放在測試文件或 API migration details。

Graph View

Backlinks