牌照與合規系統｜NEXUS-LEARN 技術架構

系統邊界

LMS 保存學習事實；合規系統保存學時入帳結果與合規快照。管理端調整須審批並保留沖正記錄。

01 / 分層架構圖

功能在技術層中的位置

01界面層 · Next.js

用戶端個人牌照、學時明細、缺口與截止日

統一管理端規則、牌照、台帳、風險看板與調整審批

02接口層 · Node.js

合規 API牌照、規則、台帳與快照查詢

權限本人／合規員資料範圍與調整審批

03業務功能層

規則與牌照版本、分類、年度要求

台帳與風險有效學時計算、缺口、停權建議

04異步處理層

Node.js Worker學時入帳、風險重算、提醒、狀態同步

05資料層

compliance_db牌照、規則版本、學時分錄、快照、調整

06外部與共用

內部事件LMS 學時事實、人員在職狀態

外部適配ReportNOW 停權接口；待確認

圖中箭頭表示由界面經 API 及業務模組進入處理與資料層；外部交互須經受控適配器。

02 / 功能模組

具體功能與責任

牌照與監管規則

IA／MPFA／SFC／IFPHK 分類、年度要求、規則版本及人員牌照檔案。

學時台帳

接收合資格的 LMS 學時事件，按人員、分類、規則版本冪等入帳，支援人工調整和沖正。

合規看板與聯動

個人進度、缺口、90／30／7 天提醒、綠黃紅風險、快照與停權／恢復處理。

03 / 系統交互

接口與資料同步

來源 → 目標	接口／方式	傳遞內容與規則
LMS → 合規	LearningHoursAwarded 事件	課程版本、學員、學時及證據引用
合規 → LMS	只讀 API／規則版本快取	課程監管分類與有效規則
人員 → 合規	Outbox 事件	牌照主體、在職及退出狀態
合規 → ReportNOW	審批任務＋外部適配	合規人員批准後發停權或恢復指令；記錄回執，外部契約待確認
合規 → 審計中心	Outbox 事件	規則變更、學時調整及快照證據

04 / 技術組成

落地約束

合規庫是學時台帳權威來源：M3 發 LearningHoursAwarded，M2 入帳後發 LicenceLedgerUpdated。
學時事件以事件 ID 去重；調整採新增沖正分錄，不覆蓋歷史。
風險自動建立停權或恢復待審批任務；合規人員批准後發送 ReportNOW 指令，記錄外部回執。

Next.jsNode.jsTypeScriptPostgreSQLOutbox + Worker物件儲存

05 / 關鍵時序

學習時長到合規台帳

sequenceDiagram
    participant 學員
    participant LMS as M3 LMS
    participant Outbox as M3 Outbox
    participant 合規 as M2 合規 Worker
    participant 審計 as M5 審計
    學員->>LMS: 完課、考核及問卷
    LMS->>LMS: 聚合心跳並核驗內部資格
    LMS->>Outbox: LearningHoursAwarded
    Outbox-->>合規: event_id、person_id、course_version_id、認可分鐘數、證據
    合規->>合規: 去重、處理亂序並選擇監管規則版本
    合規->>合規: 計算上限並寫入唯一台帳分錄
    合規-->>審計: LicenceLedgerUpdated(ledger_entry_id, rule_version)
    合規->>合規: 重算缺口與風險，必要時建立審批任務

實線為同步請求；虛線為回執或異步事件。外部接口以實際聯調契約為準。

接口／事件	資料權威與關鍵 ID	冪等、時限及失敗處理
LearningHoursAwarded	M3：completion_id、course_version_id、person_id、認可學習分鐘及 evidence_ref	同一完課事實的 event_id 穩定；M2 按事件及主體版本處理重複、亂序和遲到事件。
台帳分錄與 LicenceLedgerUpdated	M2：ledger_entry_id、rule_version、有效入帳分鐘及沖正分錄	來源事件和分錄唯一；規則變更或人工調整追加沖正，不覆蓋歷史；失敗可重試並告警。
停權／恢復審批與 ReportNOW	M2：風險快照、任務、決定、指令及回執	自動識別只建立待審批任務；拒絕不發送；未知回執先核對外部狀態再重試。