跳到主要内容

ADR-001: File Storage Layer 分層設計

ADR = Architecture Decision Record

狀態​

Proposed - 2026-01-17

背景​

GST.Core.FileStorage 模組最初為永光 GMP 專案設計，需符合 FDA 21 CFR Part 11 合規要求，包含：

  • Hash Chain 資料完整性驗證
  • 雙重電子簽章（Execution + Review）
  • ALCOA+ 原則的完整 Audit Trail
  • WAL 緩衝機制防止資料遺失

然而，許多工業自動化案件並不需要 FDA Part 11 合規，但仍可受益於結構化的檔案儲存機制。

討論​

對一般案件（非合規）的價值分析​

功能一般案件價值建議
WAL 緩衝機制高 - 工廠常斷電，防資料遺失保留，預設啟用
JSON 結構化格式高 - 易讀取、分析、整合保留
目錄結構 {year}/{month}/{day}/高 - 便於管理和備份保留
查詢 API中 - 方便歷史資料查詢保留
Hash Chain低 - 增加運算開銷改為可選
雙重簽章低 - 只有合規案件需要改為可選
ALCOA+ 完整記錄低 - 過於嚴格改為可選

過度設計的疑慮​

  1. 效能開銷：Hash 計算對高頻採集（1Hz 以上）有影響
  2. 儲存空間：Hash Chain 增加每筆記錄約 100 bytes
  3. 複雜度：一般案件不需要雙簽章流程

決策​

採用分層設計，將 File Storage 分為基礎層（所有案件通用）和合規層（選配擴充）。所有案件共用同一套 Base Layer 程式碼，合規案件在其上啟用 Compliance Layer：

分層設計的核心意圖：

  • Base Layer 解決所有案件都需要的結構化儲存問題（JSON、WAL、目錄規劃、查詢 API）
  • Compliance Layer 在 Base Layer 之上透過 Feature Toggle 疊加 FDA Part 11 所需的驗證與簽章機制
  • 一般案件直接使用 Base Layer；合規案件啟用 Compliance Layer 的 Toggle 即可升級，不需切換程式碼路徑

決策樹：如何選配​

新案件啟動時，依下列流程判斷 FileStorageOptions 的設定：

對應的程式碼配置範例見下一節。

配置方式​

// 一般案件 - 簡單配置
services.AddFileStorage(options =>
{
    options.RootPath = @"D:\AppData\";
    options.EnableHashChain = false;      // 關閉 Hash Chain
    options.EnableWal = true;             // 保留 WAL
});

// Part 11 案件 - 完整配置
services.AddFileStorage(options =>
{
    options.RootPath = @"E:\GMP-Data\";
    options.EnableHashChain = true;       // 啟用 Hash Chain
    options.EnableWal = true;
    options.RequireDualSignature = true;  // 啟用雙簽章
});

Feature Toggle 清單​

選項預設值說明
EnableHashChainfalse啟用 Hash Chain 資料完整性
EnableWaltrue啟用 WAL 緩衝機制
RequireDualSignaturefalseBatch Records 需雙重簽章
StrictAuditTrailfalse啟用 ALCOA+ 嚴格模式

影響​

正面影響​

  1. 程式碼重用 - 同一套底層適用所有案件
  2. 升級路徑 - 客戶日後需合規，只需改配置
  3. 維護成本降低 - 只維護一套程式碼
  4. 測試覆蓋 - 共用測試案例

需要的改動​

  1. 新增 FileStorageOptions 配置類別
  2. 各 Store 實作加入 Feature Toggle 判斷
  3. 更新 DI 註冊擴充方法
  4. 補充單元測試（測試各種配置組合）

實作計畫​

階段內容Issue優先順序
Phase 1新增 FileStorageOptions 配置類別GST-16Medium
Phase 2重構現有 Store 支援 Feature ToggleGST-17Medium
Phase 3更新文件和範例GST-18Low

相關文件​

版本歷程​

日期版本變更
2026-01-171.0初版建立