AI 時代的 Clean Code：Work Item API Demo

這是 iThome 鐵人賽系列「AI 時代的 Clean Code：30 天讓 AI 產出的程式碼可讀、可驗證、可維護」的公開 C#／ASP.NET Core 主案例。

Work Item API 是可重跑的證據實驗室。它保留足以討論命名、函式、物件、測試、設計、並行與架構邊界的真實變更壓力，同時限制在一個小型 API，不延伸成完整產品。

Clone 新版系列基準

git clone --branch series-v2 https://github.com/eric861129/AI-CleanCode-API-Demo.git
Set-Location .\AI-CleanCode-API-Demo
git fetch origin --tags

series-v2 保留所有正式實驗的共同起點。各篇採用 Annotated Tag 與 Commit SHA 固定候選版本，不會把每一天的結果依序疊加到同一條 Branch。

公開 Prompt、候選比較、驗證結果與人工決策集中在 docs/evidence。每一篇的索引都附上 GitHub Compare 連結，讀者可以直接查看完整 Diff。

V2 系列行為基準

series-v2 Branch 從新版 30 天企劃重新建立。起始版本支援四項業務操作：

• POST /api/work-items：建立工作項目。
• PUT /api/work-items/{id}/assignee：指派負責人。
• PUT /api/work-items/{id}/complete：完成工作項目。
• POST /api/work-items/process-overdue：處理逾期項目與通知摘要。

系列行為基準會用契約測試固定 Route、Status Code、JSON 欄位、驗證訊息、狀態轉換、通知次數與副作用順序。它是所有正式 AI 候選的共同起點，不代表理想解答。

起點刻意保留下列問題，供後續文章逐步處理：

• Controller 同時負責驗證、時間判斷、EF Core 查詢、狀態修改、通知與回應映射。
• 優先序與狀態使用字串保存。
• 通知會在資料儲存前發生。
• 重跑逾期批次時，已逾期項目仍會再次通知。
• 通知 Gateway 直接接收 EF Core Entity。

固定時間來源、可控制通知結果與獨立 SQLite 資料庫屬於實驗基礎。它們用來排除時間漂移、外部服務與測試資料互相污染，不提前回答後續設計題。

Git 歷史

Repository 目前只保留新版系列使用的 series-v2、公開實驗 Branch 與 Annotated Tag。舊版 Day Branch 與舊版 Tag 已移除，避免讀者把兩套企劃的實驗座標混在一起。

V2 正式基準固定在 Commit cdcd870635128f13d7a3fe0813768ce91ce8b46e／Annotated Tag series-behavior-baseline-v1。每個正式 AI 實驗都從指定 Commit 建立隔離候選，文章引用真實 Commit SHA，Tag 負責導覽。

執行

需要 .NET 10 SDK。global.json 以 10.0.300 為基準，允許使用較新的 Patch。

dotnet restore .\AiCleanCode.sln --locked-mode
dotnet build .\AiCleanCode.sln --no-restore --configuration Release
dotnet test .\AiCleanCode.sln --no-build --configuration Release
dotnet run --project .\src\WorkItems.Api\WorkItems.Api.csproj --no-build --configuration Release

預設資料庫是 src/WorkItems.Api/workitems.db。若要改用其他位置，可設定 ConnectionStrings__WorkItems。

系列行為基準 Smoke Test

.\scripts\run-series-baseline-smoke.ps1

腳本會建立獨立 SQLite 資料庫、在背景啟動 API、執行四項業務操作、驗證重跑行為，再關閉由它啟動的 Process。

這是教學用 Demo，不建議直接作為 Production 專案範本。