FSTS 核心業務流程
本頁彙整 FSTS 的三條核心業務流程與關鍵商業規則。
流程 A｜FD 檔案轉入資料庫
這是 FSTS 的核心業務流。1
① 建立 INI Layout（定義如何「讀」FD 檔）
↓ 手動建立欄位 OR 上傳 COBOL FD 原始碼自動解析（Import FD）
② 建立 INI Mapping（定義「寫到哪」）
→ 選擇 Layout、目標 DB Connection、目標資料表名稱
→ 設定 ConverterType（Generic / Occurs）
→ 若為 Occurs：設定 OCCURS 群組 → 明細表對應
③ 建立目標資料表（可選）
→ 系統依 Layout 欄位自動產生 DDL 並在目標 DB 執行
④ 執行轉檔
→ 上傳 FD 檔案（支援 UTF-8 / Big5 / ASCII / AUTO 自動偵測）
→ 系統逐行解析、依 Mapping 寫入目標表（SqlBulkCopy 批次）
→ 回傳：總筆數、成功筆數、失敗筆數、耗時、錯誤明細
⑤ 轉檔結果自動寫入 Audit Log
涉及的實體與 Controller：
- Layout 管理： iniLayouts
- Mapping 管理： iniMappings
- 連線設定： dbConnections
- 操作紀錄： auditLogs
流程 B｜OCCURS 展開
COBOL FD 的特殊轉檔情境。2
一筆 FD 記錄（固定長度）
├── Header 欄位（is_occurs_field=0）→ 寫入主檔表（1 筆）
└── OCCURS × N（is_occurs_field=1）→ 展開後寫入明細表（N 筆）
FK 欄位由 ini_mapping_occurs.fk_fields 指定
關鍵規則：一個 Layout 只需填入一組 OCCURS 模板欄位，系統自動展開 N 次（不需填 N 組）。3
流程 C｜使用者登入與授權
① 帳號/密碼登入（Account 自動轉小寫比對）
② 帳號不存在 OR 密碼錯誤 → 記錄失敗登入紀錄 → 回傳錯誤
③ 帳號已停用（IsActive=false）→ 記錄失敗登入紀錄 → 拒絕登入
④ 登入成功 → 回傳 JWT（含 permissions 逗號分隔清單）
⑤ 後續每個 API 請求 → [RequirePermission] 比對 JWT permissions claim
商業規則（Business Rules）
所有 BR-XXX 由 BA Analyst 維護，其他人不得修改。5
| 編號 | 規則 | 備註 |
|---|---|---|
| BR-001 | Layout Code 唯一 | 建立 INI Layout 時，Code 不可重複（跨所有 Layout） |
| BR-002 | Mapping Code 唯一 | 建立 INI Mapping 時，Code 不可重複（跨所有 Mapping） |
| BR-003 | Mapping 參照必須存在 | 建立 Mapping 時，指定的 LayoutId 與 ConnectionId 必須已存在，否則驗證失敗 |
| BR-004 | TruncateBefore 選項 | Mapping 可設定轉檔前先清空目標表（TRUNCATE），預設關閉，需謹慎使用 |
| BR-005 | OCCURS 單一模板 | 一個 Layout 只需填一組 OCCURS 模板欄位，系統自動展開 N 次 |
| BR-006 | 系統角色不可刪除 | IsSystem=true 的角色（Admin / User）不可刪除 |
| BR-007 | 停用帳號不可登入 | User.IsActive=false 的帳號登入時直接拒絕並記錄失敗原因 |
| BR-008 | 分頁大小上限 | 所有分頁查詢 PageSize 上限 500（InclusiveBetween(1, 500)） |
| BR-009 | 自動稽核 | 所有 API 操作由 AuditActionFilter 自動記錄，排除 GET /nav-menu-items |
| BR-010 | 異動紀錄寫入規則 | 各模組 Handler 在 commit 成功後呼叫 IWriteChangeLogService.WriteAsync()；例外不中斷主業務（降級 Serilog Error） |
| BR-011 | 委託回報查詢規則 + 客戶基本資料複合主鍵唯一 | OrderDetail / MatchDetail 唯讀；remainShare = Max(0, OrderShare - CancelShare - MatchShare)；ProcessFlag 空白與 ‘0’ 語意相同；客戶 BrokerNo + AccountNo 不可重複 |
注意：源檔案中 BR-011 有兩組規則共用同一編號，屬於待整理狀態。此情況已同步給 BA。
權限規則摘要
| 操作 | 所需權限 | 角色預設 |
|---|---|---|
| 查看 IniLayout | IniLayouts.View | User + Admin |
| 建立／修改／刪除 Layout 欄位 | IniLayouts.Create/Edit/Delete | 僅 Admin |
| 從 FD 匯入 Layout | IniLayouts.Import | 僅 Admin |
| 執行轉檔 | IniMappings.Edit | 僅 Admin |
| 查看 Audit Log | AuditLogs.View | 所有角色 |
| 匯出 Audit Log | AuditLogs.Export | 僅 Admin |
| 查看 ChangeLog / OrderReport | {Resource}.View | Admin + User |
| 管理角色 / 使用者 | {Resource}.* | 僅 Admin |
關鍵 API 契約語意
POST /api/v1/ini-mappings/{id}/convert（執行轉檔）
- 商業意圖：依指定 Mapping 設定，將上傳的 FD 檔案解析並批次寫入目標資料庫
- 商業副作用：寫入目標表資料；若
TruncateBefore=true則先清空目標表；自動產生 Audit Log - 失敗語意：Mapping 或 DbConnection 不存在時拒絕；FD 檔案格式不符 Layout 定義時回傳錯誤明細
POST /api/v1/ini-layouts/{id}/import-fd（從 FD 匯入 Layout）
- 商業意圖：上傳 COBOL FD 原始碼，系統自動解析欄位結構並建立
IniLayoutField - 商業副作用：建立
IniLayoutField記錄；若已有欄位則覆蓋（依實作決定） - 失敗語意：COBOL FD 語法解析失敗時回傳錯誤
POST /api/v1/ini-layouts/{id}/generate-ddl（產生目標表 DDL）
- 商業意圖：依 Layout 欄位定義，在目標 DB Connection 自動建立對應資料表
- 商業副作用：在目標 DB 執行
CREATE TABLEDDL - 失敗語意：目標 DB 連線失敗；資料表已存在時依設定決定是否覆蓋 7
補充資訊
(未來 ingest 新來源會在此追加段落)