最新消息系統透過 Swagger API 文件生成 HTTP 實作

[abc873693]

評估：Swagger Codegen 於 Announcement API 的適用性

背景

評估是否能透過 Swagger/OpenAPI codegen 自動產生 AnnouncementHelper 的 API 實作，以減少手寫樣板程式碼。

結論

不適用。 產生的程式碼僅能覆蓋 HTTP 呼叫骨架，無法涵蓋現有的業務邏輯，且會增加額外維護成本。

原因

1. 無 OpenAPI 規格檔 — 後端未提供 Swagger spec，需額外撰寫與維護
2. 大量自定義邏輯無法被生成
   • ApiResult<T> sealed class 錯誤分類（401/403/404 各有不同語意處理）
   • HTTP 204 空回應的特殊處理
   • 登入後自動設定 Authorization header 及儲存憑證
   • 呼叫前動態注入 organization、locale 至 tags
   • Client 端資料排序（sortedData）
   • Token 過期時的 reLogin 重試機制
3. Model 層衝突 — 現有 model 已使用 freezed + json_serializable 生成，codegen 會產生重複且風格不同的 model classes
4. 非標準 REST 設計 — 部分端點不符合慣例（如 POST /announcements 是查詢而非建立），codegen 的假設會不正確

目前做法

維持手寫 Dio + ApiResult sealed class 架構，透過 _execute / _executeAuth 泛型方法統一錯誤處理，已在 refactor/134-announcement-api 中完成重構。