Day21 讓前端與後端兩個 Session 分頭完成第一版程式。Vue 前端已經能操作畫面，ASP.NET Core Web API 也能處理資料與權限，但兩邊各自執行成功，不代表接在一起就會成功。
可以把前端和後端想成兩段準備接在一起的水管。兩邊都有開口，看起來也都能通水，但接頭的尺寸、螺紋與方向只要有一項不同，硬接只會漏水。API 文件就是接頭的規格表：路徑是接頭位置，Request 是前端送出的資料，Response 是後端回傳的資料，HTTP 狀態碼則告訴前端這次成功、資料有誤，還是沒有權限。
IBM 將 API Integration 說明為透過 API 連接應用程式、系統與工作流程，讓彼此交換資料與服務。放到這個專案裡，就是把仍在使用 Mock 資料的 Vue 前端，改成呼叫真正的 ASP.NET Core API。
這一篇不會一開始就叫 Codex 修改程式。我會先讓前端與後端各自整理文件，再開啟規劃模式比對兩邊的契約。遇到沒有答案的地方就停下來問，不讓 Agent 自己猜。
前端與後端需要的文件不完全相同。前端比較在意畫面會呼叫哪些 API、資料要怎麼送，以及錯誤發生時該怎麼顯示；後端除了 API，還要說明資料表、權限、交易與並行控制。
不過，文件名稱寫得很完整，不代表內容一定正確。文件必須根據目前的程式碼與實際 API 產生，完成後還要回頭核對。否則很容易拿著一份過期地圖找新地址。
我先回到 Day21 的前端 Session，請 Codex 根據目前的 Vue 專案整理 docs 與 README.md，以下是我的Prompt：
請幫我產生 `docs` 得資料夾底下，產生以下文件內容：
1. ApiList.md (API 清單)
2. Architecture.md (架構圖 Diagram Level3)
3. BackendContract.md (後端／API 契約)
並且幫我為這個專案，產生一個README.md的檔案，如果已經存在且程式碼有變動，請再根據現在專案的程式碼，幫我更新README.md
這三份文件各自回答不同問題：
ApiList.md：前端目前呼叫哪些路徑、使用什麼 HTTP 方法，以及可能收到哪些狀態碼。Architecture.md：畫面、Store、Service Interface、HTTP Adapter 與後端之間怎麼分工。BackendContract.md：前端真正依賴的欄位、型別、分頁格式、錯誤格式與驗證流程。README.md 則負責讓剛加入專案的人知道怎麼安裝、啟動與驗證。它和 API 契約用途不同，不要把所有細節都塞進同一份檔案。
接著切到後端 Session，請 Codex 從 Controller、DTO、EF Core Migration 與目前的設定整理文件，以下是我的Prompt：
請幫我產生 `docs` 得資料夾底下，產生以下文件內容：
1. ApiList.md (API 清單)
2. Architecture.md (架構圖 Diagram Level3)
3. TableSchema.md (資料庫)
4. E-R\_Diagram.md(E-R 圖)
5. FrontendContract.md (前端／API 契約)
並且幫我為這個專案，產生一個README.md的檔案，如果已經存在且程式碼有變動，請再根據現在專案的程式碼，幫我更新README.md
後端文件多了 TableSchema.md 與 E-R_Diagram.md，因為資料如何保存、哪些欄位不能重複，以及資料表之間怎麼關聯，都是後端實作的一部分。前端不需要知道每個 Index，卻需要知道哪些操作可能因為資料衝突而收到 409 Conflict。
這裡說的「契約」不是要簽名蓋章的合約，而是前端與後端共同遵守的溝通格式。API 路徑、HTTP 方法、Request、Response、驗證方式與錯誤狀態，都屬於 API Contract 的一部分。
在 API 串接的相關資料中，常會看到以下幾個名詞：
| 名詞 | 白話說明 |
|---|---|
| API Integration | 讓兩個原本分開的應用程式透過 API 交換資料與功能。這一篇做的，就是把 Vue 前端接到 ASP.NET Core 後端。 |
| API Contract | 前後端共同遵守的介面規則。它會寫清楚請求送到哪裡、要帶什麼資料，以及成功或失敗時會收到什麼。 |
| Contract-first | 先把 API 契約談好，再讓前端與後端各自開發。前端可以先按照契約製作 Mock，不必等後端完成。 |
| Mock | 依照預定契約做出的模擬版本。它能讓前端先完成畫面與操作，但不能證明正式後端已經接得上。 |
| Server-first | 先完成後端 API，再從實際程式產生或整理 OpenAPI 文件。文件比較貼近現況，但仍要檢查產生出來的介面是否容易理解與使用。 |
OpenAPI Initiative 另外提到 Legacy API，也就是替已經存在、甚至已經上線的 API 補上標準化契約，讓其他程式比較容易理解與呼叫。
本系列不是完全照著單一方式走。Day12 先整理 API 契約，Day21 讓前端按照契約製作 Mock，這一段接近 Contract-first；後端完成後，Day22 又從 Controller、DTO 與 OpenAPI 回頭核對實際介面，這部分則帶有 Server-first 的做法。簡單來說，就是先用契約分工，再用真正寫出來的程式校正契約。
OpenAPI Initiative 提到，前後端可以先同意一份 API 契約，再各自並行開發；前端也能依照契約建立 Mock。這個專案前一階段確實用了 Mock，但實作完成後仍要重新比對，因為程式在開發過程中可能已經改變。
這次的文件比對發現，前端仍保留早期的「建議 API」與 Mock 假設，後端文件則描述已經實作的 /api/v1 契約。這時不能因為兩邊都有 ApiList.md，就假設內容相同。
我會先檢查這幾類差異：
| 檢查項目 | 容易發生的問題 | 這個專案的例子 |
|---|---|---|
| API 路徑與方法 | 路徑相似，但 Method 不同 | GET、POST、PUT、PATCH 是否對得上 |
| 欄位名稱與型別 | 前端送字串，後端等待 GUID | projectId、taskId、roleId |
| 驗證方式 | 登入成功，後續請求卻一直 401 | 記憶體中的 Access Token 與 HttpOnly Refresh Cookie |
| 安全檢查 | 前端漏送必要的 Header | Auth POST 需要 CSRF Token |
| 錯誤格式 | 後端已說明原因，前端只顯示「發生錯誤」 | Problem Details 與欄位驗證訊息 |
| 並行修改 | 後寫入的人蓋掉先前修改 | Base64 格式的 rowVersion 與 409 Conflict |
| 權限 | 畫面藏起按鈕就以為安全 | 前端控制顯示，後端仍要逐次授權 |
這張表不是要初學者一次記住所有名詞。先抓住一個原則：只要前端送出的內容和後端等待的內容不同，就要先決定共同規則，再改程式。
文件準備好後，我回到 Day21 預留的全端調整 Session，開啟規劃模式並輸入：
請先讀取以下兩個專案的`docs`資料夾底下的文件，之後進行前後端網頁的串接，如果有不合理的地方請提出給我確認後再繼續
ProjectManagementWeb_Backend
ProjectManagementWeb_FrontEnd
這段 Prompt 最重要的不是資料夾名稱，而是「先唯讀盤點」和「有衝突先問」。如果直接說「幫我完成串接」，Agent 可能為了讓程式跑起來，默默選擇其中一邊。程式也許能執行，規則卻已經被改掉。
比對過程中，Codex 找到幾個文件沒有說清楚的地方，例如資料由哪一端產生、狀態如何變更，以及權限要怎麼處理。這些都會影響實際操作，不能讓 Agent 自己選一個看起來合理的答案。
以下畫面就是其中一個例子。管理員同時修改角色與帳號啟用狀態時，可以拆成兩支 API，也可以由一支 API 一次處理。兩種方式都能寫成程式，實際採用哪一種，仍要回到系統規則確認。
我確認完規則後，Codex 才把結果放進串接計畫。這樣做多花了一點討論時間，卻能避免前後端各自理解，做到一半才回頭修改。
問題回答完後，Codex 才整理出完整計畫：以前端現有的 Service Interface 為邊界，把 Mock Adapter 換成正式 HTTP Adapter；後端補齊已確認的契約；兩邊共同處理 CSRF、JWT Refresh、rowVersion、權限與錯誤格式。
看到計畫後，我會再檢查四件事：
fetch 散落在每個 Vue 元件裡。build 成功。確認計畫後，才讓 Codex 開始實作。
這次串接完成後，Codex 回報後端 build、單元測試、SQL Server 整合測試，以及前端格式檢查、型別檢查、單元測試、production build 與 Playwright 測試結果。它也保留一項未驗證的邊界：真正寄送 Email 仍需要有效的 SMTP 設定。
這裡要分清楚三句話：
build 通過：程式可以編譯或打包。前兩項都很重要，但不能替第三項作保證。測試沒有寫到的操作、文案看不懂、按鈕位置不合理，或外部 Email 沒有真的寄出，都可能等到手動操作時才被發現。這正好會接到 Day23。
確認變更範圍、測試結果與秘密檔案後，我才請 Codex 替兩個 Repository 分別建立 commit 並 push，以下是我的Prompt：
[@GitHub](plugin://github@openai-curated-remote)
請先檢查兩個 Repository 的 git status、git diff、目前分支與待提交檔案，
確認沒有 .env、Token、密碼或其他敏感資料後，分別建立 Commit。
Commit message 使用「串接 V1 完成」，並 push 到目前追蹤的遠端分支。
完成後請回報兩個 Repository 的本機 Commit SHA 與遠端 SHA。
commit 與 push 是兩個動作。前者把版本保存在本機，後者才把版本送到遠端。要求回報 SHA，是為了確認「已經 push」不是一句沒有核對的完成訊息。
前後端串接不是把 Mock URL 換成正式 URL 就結束。兩邊還要對齊路徑、欄位、驗證、權限、錯誤格式與資料版本。文件讓這些差異能被看見，規劃模式則提供一個在修改程式前停下來問問題的機會。
這次 Codex 負責讀文件、找差異、整理選項與執行修改；人負責決定業務規則、確認計畫，以及判斷哪些測試證據足夠。Agent 可以很快接管線，但接頭規格仍要有人拍板。
下一篇會真的啟動前端、後端與資料庫，從使用者角度操作系統。因為「Agent 說測過了」和「使用者真的能完成工作」，中間還隔著一輪手動測試。
iThome鐵人賽
看影片追技術