FSTS 系統架構
系統拓樸
[Browser]
↓ HTTP / REST
[Frontend: Next.js 15 / React 19 / TypeScript 5.6]
↓ fetch（Forward Proxy — app/api/[...path]/route.ts）
[Backend: ASP.NET Core 8 / C# / MediatR CQRS]
↓ EF Core 8 (SqlServer)
[MSSQL — 主業務資料庫]
[Backend]
↓ EF Core / SqlBulkCopy（動態切換 DbConnection）
[目標 DB — 轉檔寫入目標（可多個）]
關鍵約束：瀏覽器永遠不直接接觸後端位址；所有 API 請求透過 Next.js Forward Proxy 轉發至 http://localhost:5001/api/v1/*。1
Backend 架構
採 Clean Architecture + CQRS + MediatR。相依方向：外層可參考內層，內層絕不參考外層。2
src/
├── Oms.Domain/ 實體、列舉、領域例外、純計算 Domain Service
├── Oms.Application/ CQRS Command/Query/Handler、驗證、Repository 介面
├── Oms.Infrastructure/ DbContext、Repository 實作、JWT、外部服務
└── Oms.Api/ Controllers、Middleware、DI 組裝
層級職責
| 層 | 可依賴 | 禁止依賴 |
|---|---|---|
| Domain | 無（只純 C# + 標準庫） | Application、Infrastructure、Api |
| Application | Domain | Infrastructure、Api |
| Infrastructure | Domain、Application（僅介面） | Api |
| Api | 所有內層 | — |
Feature-based 組織
每個 Feature 在 Oms.Application/Features/{Feature}/ 下，包含：
Commands/— 寫入操作（Command + Validator + Handler 同一檔案）Queries/— 讀取操作（Query + Validator + Handler 同一檔案）DTOs/— Response record +ToResponse()extension
對應的 Controller 在 Oms.Api/Controllers/ 下，只呼叫 _mediator.Send(...)，不寫商業邏輯。3
Frontend 架構
前端採 Next.js App Router + Feature-based 目錄：
- 頁面路由：
app/{feature-slug}/... - Feature 模組：
features/{featureName}/— 元件、hooks、types、services - 共用元件：
shared/components/ - API 呼叫統一走
services/api/apiClient.ts
關鍵禁止：features 之間不可直接互相 import，共用邏輯一律升到 shared/。4
資料流（以「執行轉檔」為例）
1. User 在前端 /ini-mappings 頁按「執行轉檔」
2. 瀏覽器 POST /api/v1/ini-mappings/{id}/convert （實際到 Next.js Proxy）
3. Proxy 轉發到 Backend: http://localhost:5001/api/v1/ini-mappings/{id}/convert
4. IniMappingsController.ConvertAsync(id, file)
5. → _mediator.Send(new ConvertIniMappingCommand(id, file))
6. → ConvertIniMappingCommandHandler
a. 讀 IniMapping + IniLayout + DbConnection
b. 呼叫 IConverterFactory 取得 GenericConverter 或 OccursConverter
c. 解析 FD 檔 → SqlBulkCopy 寫入目標 DB
d. 寫入 Audit Log
e. 回傳 ConvertResult (總筆數/成功/失敗/耗時/錯誤明細)
7. Controller 回傳 200 OK + DTO
參見 核心流程 A。
架構守衛（禁止事項）
來自 architecture.md 與 repo 既定規範（原文見 fb.fsts repo 的 CLAUDE.md，依 llm-wiki 政策不同步 agent 憲章至中央；以下為摘錄）：
- Controller 不得注入 DbContext；所有 DB 操作必須透過
IRepository<T>介面 - Handler 以外的地方不得撰寫商業邏輯
- Domain 層不得參考 Application / Infrastructure / Api
- Controller 不得使用
[FromForm]接收純 JSON，必須用[FromBody] - Route 不得使用
[controller]佔位符，必須明確寫 kebab-case 路徑 - 連線字串、JWT Secret 不得硬編碼，必須用 User Secrets
- 前端不得直接
fetch/axios，必須透過apiClient.ts - 前端不得跳過 Next.js Forward Proxy 直呼後端
補充資訊
(未來 ingest 新來源會在此追加段落)