Day25_網站完成了，該更新最終的設計圖了

前言

Day24 實際操作網站後，我們調整了成員搜尋方式，也補上 Admin 帳號的保護。程式來到第一個可交付版本，文件也該跟上了。

開發前的設計圖像施工藍圖，告訴團隊準備怎麼蓋；開發完成後的文件則像完工圖，記錄管線最後接到哪裡、哪面牆真的有蓋。施工途中只要改過位置，完工圖就得跟著修正。否則下一位維護者拿著舊圖找 API、資料表或畫面，很可能越找越困惑。

本文會重新核對 Vue 3 前端、ASP.NET Core 後端與共用規格，確認程式碼、API 契約、資料庫 Schema、C4 圖與 UI 文件說的是同一套系統。文件確認後，再把三個 Repository 各自合併回 main，留下第一版的基準。

文件不是做完才補的裝飾

文件常見的問題有兩種。開發前寫得很完整，後來程式改了，文件卻停在原地；或是請 Agent 產生一批 Markdown，卻沒有確認內容是否真的來自目前的程式碼。

這兩種情況都會得到「看起來有文件」的專案，但文件不一定可信。

可以把文件想成系統的地圖。地圖不需要畫出每一張桌椅，卻要標對道路、入口與邊界。對 ProjectManagementWeb 來說，各份文件回答的問題不同：

更新文件不需要把程式碼逐行翻成中文，也不能看到缺頁就自行補需求。Agent 可以整理現況、找出差異；遇到規格和實作不一致時，先把衝突列出來，再由人決定要調整程式還是規格。

先替三個 Repository 劃清責任

ProjectManagementWeb 不是把所有內容放在同一個資料夾，而是拆成三個 Repository：

ProjectManagementWeb
├── ProjectManagementWeb_FrontEnd   # Vue 3 畫面與前端契約
├── ProjectManagementWeb_BackEnd    # ASP.NET Core API、資料庫與後端契約
└── ProjectManagementWeb_Spec       # 跨前後端的共同規格

三邊都需要更新，但不要塞進同一份大 Prompt，讓 Agent 一次到處修改。我會先在各 Repository 處理它負責的文件，最後才回到規格 Repository 做整體對照。這樣比較容易看懂 Git diff，也比較不會誤改到別人的責任範圍。

更新前端文件

前端文件要反映目前的 Route、View、Store、Service 與 HTTP Adapter，而不是早期 Mock API 的想像。可以在前端 Session 使用：

請先閱讀目前 Repository 的 AGENTS.md、README.md、src、tests 與 docs。
這一輪只更新文件，不要修改 Vue 程式、測試或套件版本。

請依目前實作更新：
1. docs/ApiList.md
2. docs/Architecture.md
3. docs/BackendContract.md
4. README.md

請確認 API 路徑、HTTP 方法、Request／Response、驗證流程、
錯誤格式與 rowVersion 都能在現有程式中找到依據。
若前端實作與後端契約不同，先列出差異，不要自行選一邊改寫。
完成後回報修改檔案、依據與仍無法確認的項目。

更新後端文件

後端文件除了 API，還要反映 EF Core Migration、資料表限制、授權與執行流程：

請先閱讀目前 Repository 的 AGENTS.md、README.md、src、tests、
EF Core migrations、OpenAPI 設定與 docs。
這一輪只更新文件，不要修改後端程式、Migration、測試或套件版本。

請依目前實作更新：
1. docs/ApiList.md
2. docs/Architecture.md
3. docs/TableSchema.md
4. docs/E-R_Diagram.md
5. docs/FrontendContract.md
6. README.md

請區分「已實作」「規劃中」與「尚未驗證」，不可把待辦寫成已完成功能。
若文件、Migration 與程式碼互相矛盾，先列出檔案與差異，不要自行修改業務規則。
完成後回報修改檔案、依據與仍無法確認的項目。

更新共用規格

最後才處理 ProjectManagementWeb_Spec。這一輪要同時讀取前端與後端，但只允許修改規格 Repository：

請先閱讀三個 Repository 的 AGENTS.md，以及目前前端、後端的程式碼、
docs、README、Migration、OpenAPI 與測試結果。

本次只允許修改 ProjectManagementWeb_Spec，不要修改前端與後端 Repository。
請依現行實作更新並互相核對：
1. C4
2. ImplementationBacklog.md
3. Spec.md
4. TestCases
5. UserStory.md
6. Flowchart
7. Schema.md
8. StaticData.md
9. UIMock

更新原則：
- C4、流程圖與 UI 文件要反映目前實作，不保留已淘汰的畫面與路徑。
- 已確認的 User Story 不可因程式目前不同就直接改寫；先列出落差。
- Test Case 的「通過」必須有實際測試紀錄，Skipped 或未執行不可算通過。
- 圖與 Markdown 內的相對連結都要檢查；Mermaid 原始檔要實際渲染確認。
- 完成後列出修改檔案、衝突、未決項目與驗證結果。

前端文件說清楚畫面如何呼叫 API，後端文件記錄 API 與資料如何運作，共用規格再把兩邊放回同一張系統地圖。每次修改都有明確範圍，審查 Git diff 時也不用在三個 Repository 之間猜來猜去。

Agent 更新完，還要由人對答案

Agent 回報「文件已更新」後，我還會做一輪人工核對：

1. 先看 git status 與 git diff，確認只改到預期文件，沒有順手修改程式或刪掉尚未完成的規格。
2. 從文件抽查幾個 API 路徑、欄位名稱與狀態碼，回到 Controller、DTO 與前端 Adapter 找證據。
3. 把 Table Schema 與 E-R 圖對回 EF Core Migration，確認 Primary Key、Foreign Key、UNIQUE Constraint、Nullability 與 Index 沒有畫錯。
4. 實際渲染 C4 與其他 Mermaid 圖，並檢查 Markdown 圖片與文件連結是否存在。
5. 對照測試執行紀錄。文件可以寫「尚未驗證」，不能把沒有執行的測試補成全綠。

如果程式與已確認的規格不同，這一輪先記下落差，不要直接改文件替程式背書。接下來要修改程式、調整規格，還是延後處理，都應該另外建立清楚的工作項目。

把文件同步寫進開發規範

這次整理完，不代表文件從此不會過期。下一個功能只要加入新欄位或新 API，程式和文件就可能再次分開。因此，我會在各 Repository 的 AGENTS.md 寫下對應的交付規則，讓 Agent 修改程式時知道該回頭檢查哪些文件。

前端可以加入：

若修改 Route、View、Store、Service、HTTP Adapter、環境變數或啟動方式，
送出 Pull Request 前必須同步檢查 README.md 與 docs。
只更新受影響的文件；若後端契約需要改變，先列出差異，不得自行修改後端 Repository。

後端則可以加入：

若修改公開 API、DTO、驗證授權、資料模型、Migration、背景工作或啟動方式，
送出 Pull Request 前必須同步檢查 README.md 與 docs。
只更新受影響的文件；跨 Repository 的規格差異要列入交付說明。

共用規格 Repository 可以加入：

若前端或後端的修改影響系統邊界、使用流程、公開 API、資料模型、
固定代碼、畫面或驗收條件，送出 Pull Request 前必須同步檢查並更新：
1. C4
2. UserStory.md
3. Flowchart
4. Schema.md 與 StaticData.md
5. UIMock
6. TestCases
7. ImplementationBacklog.md 與 Spec.md

更新內容必須能追溯到目前程式碼、Migration、API 契約或實際測試紀錄。
請區分「已實作」「規劃中」與「尚未驗證」；若實作與已確認規格衝突，
先列出差異與依據，不得自行改寫 User Story 或把尚未執行的測試標成通過。

規則寫進 AGENTS.md 後，每個 Repository 都知道自己要維護哪些文件，共用規格再負責跨系統的內容。比起只留一句「記得更新全部文件」，這種寫法更容易照著執行。

三個 Repository 的文件都核對完成後，我會把開發分支合併回 main，讓遠端保留同一個第一版基準。這次是個人專案，我在各 Repository 確認分支、測試與待提交檔案後，直接請 Codex 完成 Commit、Push 與合併：

幫我Commit並且push上去，然後合併到Main

這句 Prompt 很短，所以執行前仍要確認 Codex 操作的是哪個 Repository、目前位在哪個分支，以及這次會一起進入 main 的 Commit。若是多人協作，就不應跳過審查，而要改成建立 Pull Request，讓其他人確認差異後再合併。

文件確認後，用 Git Flow 接住後續開發

程式、測試與文件重新對齊後，這個專案有了第一個清楚的交付基準。接下來還會新增功能、調整既有流程，也可能在上線後遇到需要立刻處理的問題。這些變更不適合全部直接堆在 main 上。

Git Flow 會替不同類型的修改安排路線：main 保存目前可交付的版本，develop 整合下一版內容，feature/* 讓新功能獨立開發，hotfix/* 則處理正式版本的緊急問題。團隊只要看分支名稱，就能先判斷這項工作目前處於哪個階段。

把這個專案後續會走的路線畫出來，大致如下：

圖中的圓點代表 Commit。平常開發功能時，先從 develop 分出 feature/*，完成後透過 Pull Request 合併回 develop。等整合測試通過，再將這一版送進 main。如果正式環境出現需要立刻處理的問題，就從 main 分出 hotfix/*；修正完成後要同時合併回 main 與 develop，避免下一版又出現同一個問題。

從後續版本開始，如果改為多人協作，前端、後端與共用規格分屬三個 Repository，因此要各自走完審查與合併：

Frontend develop ── Pull Request ──> Frontend main
Backend  develop ── Pull Request ──> Backend  main
Spec     更新分支 ── Pull Request ──> Spec     main

前端檢查通過，不代表後端與共用規格也能跟著合併。三個 Repository 都要各自確認目前分支、待合併差異、測試結果與文件連結，也要檢查是否誤放秘密檔案。Pull Request 提供審查與討論的地方，但它不能代替測試。

main 不是「永遠不會出錯的分支」，它只是團隊共同約定的交付基準。合併完成後，我還會讀回遠端 main 的 Commit SHA，確認遠端收到的確實是剛才檢查過的版本。

到了第二版，分支的用途會更明顯。新功能可以在自己的分支調整，不會干擾目前可交付的版本；維護舊功能時，也能沿著 Commit 與 Pull Request 找回修改原因。若變更影響 API、資料庫或共用規格，相關文件應放在同一批修改中，避免程式更新後還得靠人猜契約是否改過。

Git Flow 不是所有專案的標準答案。小型專案也可以只保留 main，每項工作從短期分支送出 Pull Request。分支不必多，名稱和用途說得清楚就好；團隊也要知道程式與文件該經過哪些檢查，才能進入正式版本。

小結

第一版網站完成後，還不能只整理程式碼。API 契約、資料庫 Schema、C4 圖、UI 文件與測試紀錄也要反映目前的實作，下一次修改時才找得到可靠的依據。

這次先由 Agent 盤點三個 Repository，更新各自負責的文件，再由人回到程式、Migration、測試結果與 Git diff 核對。內容確認一致後，才把版本合併回 main。往後看到文件中的 API、資料表或測試狀態，都能繼續追到對應的程式與驗證紀錄。

文件與第一版基準整理好後，下一篇會開始替網站找一個正式運作的地方。我們會先認識雲端服務與 Google Cloud，再決定 Vue 前端、ASP.NET Core API 和 SQL Server 分別要放在哪裡。

專案連結

• ProjectManagementWeb Vue 3 前端
• ProjectManagementWeb ASP.NET Core 後端
• ProjectManagementWeb 共用規格

參考資料

• Pro Git：Branching Workflows
• Git 官方文件：git merge
• GitHub Docs：GitHub flow
• How to Write a Git Commit Message
• 為你自己學 Git：Git Flow 是什麼？為什麼需要這種東西？