前端操作觀測
文件狀態：架構規範
最後驗證：2026-05-14
來源：只能操作前端、沒有前端 repo code 時的 Network log 觀測需求
這裡放什麼
這個區塊用來記錄「前端頁面 / 使用者操作 / 實際打出的 API」之間的關係。
適用情境：
- 沒有前端程式碼，只能從瀏覽器操作和 DevTools Network 觀察。
- 要知道某個頁面會打哪些 API。
- 要知道某支 API 被哪些頁面或操作使用。
- 要整理 migration / LB 切流前後，前端實際行為是否符合預期。
不放什麼
- 不放一次性 session token、完整 JWT、驗證碼、個資。
- 不取代 API 業務流程文件。
- 不取代 專案 migration detail。
- 不把所有 Network requests 無篩選地倒進來。
資料模型
頁面 Page
-> 操作 Operation
-> API Detail三者分工：
| 類型 | 回答問題 | 位置 |
|---|---|---|
| 頁面 Page | 這是哪頁、怎麼進入、有哪些可操作項目 | 頁面/ |
| 操作 Operation | 使用者怎麼點、打哪些 API、成功/失敗畫面如何判斷；這是主要觀測文件 | 操作/ |
| API Detail | 這支 API 的 method/path/request/response、routing、side effect、被哪些頁面與操作使用 | API/ |
案例 Case 只放一次性驗證與排查摘要。穩定知識要回填到 Page / Operation / API Detail，不要長期維護重複內容。
正向與反向關聯
正向關聯由文件內的 Obsidian wikilink 建立：
頁面 -> 操作 -> API Detail反向關聯用兩種方式取得：
- Obsidian Backlinks：從 API Detail 看哪些頁面 / 操作連到它。
- API Detail 內手動維護「出現位置」區塊。
API Detail 內建議固定寫：
## 出現位置
- 頁面：[[../頁面/...]]
- 操作：[[../操作/...]]命名規則
頁面
頁面/<產品區域>__<頁面_slug>.md例：
頁面/staging__pro_search_cleaning.md
頁面/dashboard__works_detail.md操作
操作/<流程>__<動作>.md例：
操作/quote_bid__submit_review.md
操作/search_add__submit_request.mdAPI Detail
API/<METHOD>__<path_slug>.mdpath slug 規則：
/改成__{id}或實際 id 改成語意參數.json保留在標題，不一定放在檔名
例：
API/POST__quote_bids__change_status__reviews__quote_bid_id.md
API/POST__quote_requests__search_add.md建議觀測流程
- 開 DevTools Network。
- 勾選 Preserve log。
- 勾選 Disable cache。
- 清空 Network。
- 從頁面初始狀態開始操作。
- 每次操作只做一件事。
- 記錄 API 順序、method、path、status、response body。
- 將敏感資訊遮蔽後再貼進文件。
- 若同一 API 在不同頁面出現，更新 API Detail 的「出現位置」。
紀錄粒度
建議只記錄會影響業務或 migration 的 API：
- 會寫 DB 的 POST / PUT / PATCH / DELETE。
- 會影響頁面狀態判斷的 GET。
- CORS / LB / origin 切流相關 API。
- response shape 對前端重要的 API。
可以忽略：
- GA / GTM / pixel。
- 靜態資源。
- 重複 polling，除非它影響狀態判斷。
- browser extension request。
安全規則
貼 curl 或 header 前必須處理：
X-PRO360-User-Session-Token：遮蔽或只保留末 4 碼。- JWT / id_token：不要貼完整值。
- 手機、email：非測試帳號要遮蔽。
- 驗證碼：不要記錄。
- Cookie：不要貼完整值。
和其他文件的關係
- API path 的長期索引：../索引/API Endpoint 索引
- API routing / LB / CORS：../API 路由與遷移/README
- response shape 相容性：../API 路由與遷移/api_response_contract
- search_add 這類完整業務流程：../業務流程/README