index

Common Process Documents

目的

這個 vault 用來整理跨專案、跨 API、跨資料表的共同流程知識。

文件不是 API migration checklist，也不是單張 table dictionary。它的重點是讓工程師能從一個業務問題出發，快速知道要看哪些程式、資料表、queue、付款與 log。

建議入口

排查或理解流程時，優先從業務流程進入，再依需要跳到資料表、付款、queue、身份驗證或 log 文件。

業務流程
-> 資料表流程
-> 付款與扣款流程 / Queue 與 Event 系統 / 專案身份驗證方式 / log 文件

文件區塊

區塊	用途
API Endpoint 索引	從外部 API path 反查業務流程、路由案例與 migration detail
前端頁面與 API 索引	從瀏覽器頁面與操作反查實際打出的 API，並建立 API detail 的正反向關聯
Log channel 與 error code 索引	從 Slack channel、application log、API error code 反查排查入口
業務流程	以完整 business flow 為入口，例如 search_add、narrow match、contact provider
前端操作觀測	沒有前端 code 時，用 DevTools Network 建立頁面、操作、API detail 的觀測紀錄
資料表流程	以核心 table 為中心，說明欄位狀態、跨表關聯、常用 SQL
付款與扣款流程	wallet、card、TapPay、Stripe、transaction 與付款排查
Queue 與 Event 系統	event_queue、task_event_queue、event actions、queue/log 判讀
限制與風控規則	提出需求次數上限、Redis 防連點、production-only guard、測試與正式環境差異
API 路由與遷移	新舊 API path 查詢、Mapping / fallback、endpoint migration checklist
專案身份驗證方式	API key、session token、security hash、常見驗證流程
設定與環境來源	DB、時區、語系、Slack/log、金流 key、寫死常數等分散設定的來源地圖
Log 與告警流程	application log、Monolog、Slack notification、告警判讀與排查
測試工具人	固定測試 user / provider 的目前狀態、用途、付款能力與常用狀態調整欄位

維護文件

文件	用途
文件維護規範	文件狀態、寫作邊界、Common docs / 專案 migration docs 的分工
模板/業務流程	新增業務流程文件時使用
模板/路由案例	新增 endpoint route trace 案例時使用
模板/前端頁面	新增前端頁面觀測文件時使用
模板/前端操作	新增前端操作 API sequence 文件時使用
模板/API Detail	新增前端觀測到的 API detail 文件時使用
模板/資料表流程	新增 table 視角文件時使用
模板/限制與風控規則	新增次數限制、rate limit、production-only guard 文件時使用

維護原則

1. 完整流程放 業務流程/，不要拆散在多個 table 文件中。
2. 資料表流程/ 只放核心 table 視角，不追求每張 table 都獨立。
3. 跨多支 API 的規則要獨立成共同區塊，例如付款、queue、限制與風控、路由、身份驗證、設定、log / 告警。
4. 每份文件開頭要說明「這份文件回答什麼，不回答什麼」。
5. 實測 curl、一次性 response、特定 ID 案例應放 案例/，不要混進規則文件。
6. 重要文件要標示文件狀態、最後驗證日期與來源。

目前優先流程

流程	入口
search_add 發案 / 配對 / 建 bid	業務流程/search_add
search_add 提出需求上限 / 風控	限制與風控規則/search_add
provider 送出報價	業務流程/provider_送出報價
quote bid 正式聯絡 provider	業務流程/quote_bid_contact
narrow match 邀請 / 回應	業務流程/narrow_match
quote bid contact charge	付款與扣款流程/quote_bid_contact_charge