FSTS 架構決策紀錄（ADR）
docs/project/project.architecture-decisions.md是待填寫的決策模板，六大主題（A–F）共 13 項 checklist，目前所有[ ]尚未勾選、決策理由：{理由}多為佔位符。本頁摘要模板架構，實際選型尚未定案。回到 Planning 總覽。
狀態說明：本頁標記為
status: draft，原因是原始模板使用{YYYY-MM-DD}等佔位符、所有項目皆為待決策。實際決策一旦完成，應在原始 raw 更新內容並重新 ingest（觸發 hash-drift）。
一句話
此模板定義六大技術決策領域：錯誤處理、橫切面 Middleware、共用基礎設施、排程任務、報表套件、DI 註冊方式，供技術負責人於專案初始化時依實際選型填寫並勾選 [x]。1
六大決策主題
| 類別 | 項目 | 說明 |
|---|---|---|
| A | 錯誤處理體系 | A1 自訂 Exception、A2 Filter/Handler、A3 驗證錯誤格式 |
| B | 橫切面 Middleware | B1 Request Logging、B2 Security Headers、B3 Rate Limiting、B4 Response Compression、B5 驗證訊息在地化 |
| C | 共用基礎設施 | C1 強型別 Options Pattern、C2 CurrentUserService |
| D | 排程任務 | D1 排程框架選型、D2 分工規則 |
| E | 報表套件 | E1 Excel 匯出、E2 PDF 匯出 |
| F | DI 註冊方式 | F1 DI Extension Methods |
A. 錯誤處理體系（範例項）
| ID | 項目 | 內容 |
|---|---|---|
| A1 | 自訂 Exception 類型體系 | BusinessException、ValidationException、NotFoundException、UnauthorizedException、ForbiddenException、其他專案特定 |
| A2 | Exception Filter / Handler | 依 Exception 類型自動對應 HTTP StatusCode + Log Level + 統一回傳格式；整合 UserId / Controller / Action / 異常詳情 |
| A3 | 驗證錯誤格式定義 | ValidateErrors 型別（Dictionary<string, string[]> 或其他） |
D. 排程框架候選
| 選項 | 授權 | 特色 | 適用 |
|---|---|---|---|
| Quartz.NET | Apache 2.0 | 輕量、RAM Store、無需額外 DB | Cron 排程任務 |
| Hangfire | LGPL / 商業版 | 有 Dashboard、需要 DB 表 | 需監控的背景任務 |
| BackgroundService（內建） | 免費 | 最輕量、無 Cron 支援 | 常駐型任務 |
D2 分工建議：常駐任務 → BackgroundService（WebSocket 連線保持、定時輪詢）；Cron 排程 → Quartz.NET / Hangfire（每日報表、夜間資料清洗）。
E1. Excel 匯出候選
| 選項 | 授權 | 說明 |
|---|---|---|
| NPOI | Apache 2.0 | 純 .NET、Linux 相容 |
| ClosedXML | MIT | API 較友善 |
| EPPlus | 商業版 / GPL | 功能豐富，商業需付費 |
E2. PDF 匯出候選
| 選項 | 授權 | 說明 |
|---|---|---|
| Puppeteer Sharp | MIT | HTML + CSS 模板，排版精確；Dockerfile 需裝 Chromium + fonts-noto-cjk + PUPPETEER_EXECUTABLE_PATH |
| QuestPDF | 社群版有限制 | DSL 撰寫，商業需付費 |
| LibreOffice（Word→PDF） | LGPL | Container image 較大，轉換偶有跑版 |
決策修訂紀錄（模板欄位）
模板預留以下欄位待填：7
| 日期 | 項目 | 修訂內容 | 決策者 |
|---|---|---|---|
{YYYY-MM-DD} | {項目編號} | {修訂說明} | {決策者} |
確認不融合的項目（模板欄位）
供記錄評估過但決定不引入的技術或模式，及決策理由。目前尚無條目。8
相關頁面
- 後端規範：FSTS 後端編碼規範
- 前端規範：FSTS 前端編碼規範
- SA 規格：SA 規格書（M01–M23）
補充資訊
(未來 ingest 新來源會在此追加段落。一旦原始 ADR 實際填入選型，請觸發 re-ingest。)