文件維護規範

目的

這份文件規範 Common Process Documents 的寫作邊界與可信度標示。

這個 vault 的目標不是記錄所有實作細節，而是讓工程師能從業務問題、endpoint、table、log 或設定來源快速找到正確 trace 路徑。

文件狀態

每份長期文件開頭應標示文件狀態：

文件狀態：草稿 / 已對 legacy / 已對 new API / 已實測 / 待重驗
最後驗證：YYYY-MM-DD
來源：legacy code / new code / PHPUnit / staging curl / DB baseline / access log

狀態定義：

狀態	意義
草稿	只有初步整理，尚未完整對 code
已對 legacy	已確認 legacy controller / model / config
已對 new API	已確認 new endpoint / model / router / config
已實測	已用 PHPUnit、staging curl、DB baseline 或 log 驗過主要路徑
待重驗	規則可能已變，或只保留歷史判斷

不要把「從 code 推論」寫得像已實測結論。若只是推論，要明確標示。

文件邊界

Common Process Documents

放長期穩定規則：

• business flow 的長期 trace
• routing / endpoint 查詢方式
• payment / queue / auth / log / config / 限制與風控的共同規則
• 核心 table 的狀態與關聯
• 排查順序與常見陷阱

Repo Migration Docs

放單次移植與驗證紀錄：

• migration status
• access log 統計
• 實測 curl
• 一次性 request / bid / user id
• PHPUnit 覆蓋狀態
• staged diff / commit 範圍

案例文件

案例可以放具體 endpoint 或 trace，但仍應聚焦單一目的。例如：

• route 案例只示範怎麼找 route
• payment 案例只示範扣款分支
• queue 案例只示範 queue / log 判讀

不要把一支 API 的所有 business rule、DB side effect、測試紀錄都塞進同一份案例。

寫作原則

1. 每份文件開頭要說「回答什麼」與「不回答什麼」。
2. 完整業務流程放 業務流程/。
3. 單張 table 視角放 資料表流程/。
4. 跨流程規則放付款、queue、限制與風控、路由、身份驗證、設定、log 對應資料夾。
5. access log 統計與實測 ID 優先放 專案 migration detail。
6. 重要結論要能追到來源：legacy code、new code、測試、DB baseline 或 log。
7. 如果文件只描述查詢方法，不要混入 business side effect。

Endpoint 分流文件規則

legacy endpoint 如果用 path 參數分出多個業務流程，文件入口要用實際 path key 命名。

常見例子：

/quote_bids/change_status/{filter}/{id}.json
/xxx/{type}/...
/xxx/{action}/...

這類文件應該設計成：

change_status/README.md
change_status/reject_undo_reject.md
change_status/rating.md
change_status/invoice.md

不要用抽象分類當主要入口：

implemented_filters.md
other_filters.md
misc.md

原因：

• 讀者通常知道 endpoint path 或 filter，不知道文件作者的分類。
• 用 filter / action 命名可以直接從 access log、ALB rule、frontend path 反查文件。
• 總覽檔應只放索引、狀態、下一步；完整規則、side effect、測試結果要放到對應 filter / action 文件。

用詞規範

文件使用台灣常用技術用語，避免中國用語或容易造成語感不一致的詞。

API path、檔案、資料表、log、設定來源等動作，統一使用「查詢」。

新增或修改文件時，如果發現類似用語，先統一替換，再把規則補到這個章節。

DB / Queue 相關文件規則

涉及 pro360_api_82 DB / schema 查詢時，文件要提醒：

使用容器 PHP 8.2 + DBFactory。
先 SHOW COLUMNS，再 SELECT。
不要用本機 PHP 直接查 DB。

涉及 queue 驗證時，文件要提醒：

event_queue 或 event_queue_log_1 到 event_queue_log_4 任一存在都可接受。
task_event_queue 或 task_event_queue_log 任一存在都可接受。

event_queue notification worker 會寫分片 log；不要只查 event_queue_log 主表。

涉及付款 / transaction 排查時，文件要提醒先看 application log：

processWantToContactProvider
logQuoteBidTxn
其他付款 provider 對應 channel

涉及次數限制、rate limit 或風控 guard 時，文件要提醒：

寫明限制來源：DB count / Redis key / config / production-only guard。
寫明測試、staging、production 是否一致。
寫明測試 fixture 是否會受 live DB 時間窗或 Redis TTL 影響。
不要把測試 cleanup 用到的 table 誤認為限制來源。

建議模板

• 業務流程模板
• 路由案例模板
• 資料表流程模板
• 限制與風控規則模板