FR-196 · 定版 SPEC · 現況描述

▸ 通知中心 定版 SPEC

交付了什麼、現在長什麼樣;細節拆在 spec/ 七頁;租戶層管理見 FR-196.1

主系統的通知收進同一個樞紐:新套件 jedi-notification-center 負責事件型錄、收件匣、個人設定、租戶規則、外送決策、合併與即時訊號;主系統用八張接口把它接上既有的使用者名冊、範本、投遞、排程;前端鈴鐺變成收件匣入口、多一頁通知中心、一頁個人通知設定、兩支頁頂橫幅;系統設定的通知管理頁由租戶管理員決定必收事件與群組推送。本頁只放摘要與索引,每個主題的完整規格在 spec/ 底下各一頁。

25 個事件、5 類、9 個原廠建議必收(租戶可改) 套件 0.2.0、10 條套件端點+2 條主系統端點 6 張新表+1 張既有表擴欄;8 支 migration Agent 主控台不在本案
§1

一句話

任何「要讓人知道一件事」的動作,業務程式只呼叫一行 notify(事件, 收件人, 主題, 參數);套件照事件型錄與每個人的設定決定寫收件匣、寄 Email、推聊天頻道、立刻送或併進摘要;使用者在右上角鈴鐺看未讀數、在通知中心頁篩選處理、在個人通知設定頁逐事件決定站內與 Email 要不要收;哪些事件必收、哪些推到租戶的 Discord 與 Telegram 群組,由租戶管理員在通知管理頁決定,沒設過就照出貨型錄。交易信(登入 OTP、建帳號設密碼、測試信)與沒有帳號的聯絡人仍直接寄信,不經過中心。

§2

交付物總表

每一列對應 spec/ 一頁,點進去看完整規格。

主題 內容 頁
事件型錄 25 個事件、5 個類別、9 個原廠建議必收、每個事件的預設管道、合併視窗、點了跳哪一頁、收件人規則 01 事件型錄
資料表 notification_events、notification_inbox、notification_tenant_event_rules、notification_user_settings(站內與 Email 兩欄)、notification_user_profile、notification_maintenance 六張新表,compliance.task_alert_notifications 擴四欄當外送佇列;索引、RLS、system_menus 兩組字典值、system_configs 三個鍵 02 資料表
API 套件掛的 10 條(紅點數、收件匣列表、最近、已讀、封存、批次、設定讀寫、租戶規則讀寫)與主系統 2 條(排定維護建與讀);請求與回應欄位、四顆錯誤碼 03 API
套件 jedi-notification-center 0.2.0 的公開面、八張接口、notify() 行為、生效值規則(個人設定加租戶規則)、外送決策(立即、摘要、勿擾)、群組推送分頻道、合併、即時訊號 04 套件接線
主系統接線 掛載檔(含租戶規則端點的守門指定)、八張接口的實作、頻道可用性、五個角色展開、四個排程、十七處呼叫點、仍直接寄信的三處 05 主系統接線
前端 鈴鐺、通知中心頁、個人通知設定頁(站內與 Email 兩欄)、通知管理頁三個規則分頁、兩支橫幅、排定維護表單;四支 composable、路由、能力點、i18n、SocketIO 與輪詢 06 前端
維運與收口 八支 migration 與 manifest、重啟、出貨基線重產、套件發版與改回釘版、守衛測試 07 維運與收口
§3

端到端

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'18px'},'fontSize':18,'flowchart':{'useMaxWidth':false,'nodeSpacing':44,'rankSpacing':52,'padding':14},'sequence':{'useMaxWidth':false,'messageFontSize':17,'noteFontSize':16,'actorFontSize':18,'width':200,'height':64,'messageMargin':52,'boxMargin':14,'actorMargin':80,'mirrorActors':false}}}%%
sequenceDiagram
  autonumber
  participant B as 業務程式
  participant C as jedi-notification-center
  participant I as notification_inbox
  participant O as task_alert_notifications(外送佇列)
  participant D as jedi-notification(投遞)
  participant W as 瀏覽器
  B->>C: notify(event, recipients, subject, params)
  C->>C: 查型錄(類別、必收、預設管道、合併視窗、連結樣板)
  C->>C: Role 展開成 user_id(宿主 IRecipientDirectory)
  C->>C: 每位收件人:個人設定 left join 預設,再套租戶規則;生效必收則強制站內與 Email
  C->>I: 合併視窗內有未讀同主題 → merged_count+1;否則新列
  C->>O: 每個開啟的管道 enqueue(立即=now;摘要=下個時刻;勿擾=時段結束)
  C->>D: scheduled_at ≤ now 的當場寄並 mark sent/failed;租戶勾選且啟用的群組頻道各寫一列、各推一次
  C-->>W: IRealtimeNotifier.unread_changed(user_id)
  W->>C: GET unread-count;下拉開著時 GET inbox/recent
  Note over O,D: 每小時 :05 run_outbound():到時的摘要同人同批合成一封寄出
圖 1 一筆通知從業務程式到瀏覽器。第 1 步是業務程式唯一寫的那一行;立即寄與排進摘要由第 6 步分岔;第 9 步是 SocketIO 訊號,連不上時瀏覽器退回每 60 秒輪詢。
§4

這一輪沒做完的

沒做完的事 說明 誰接
出貨基線重產 兩顆能力點、六張表、八支 migration 還沒進 scripts/init/;守衛 test_plugin_capabilities_are_seeded 在重產前會紅 收口(首腦),見 07
套件發版 0.2.0 還沒推 Nexus(0.1.0 也未發),主專案目前走本機路徑 收口
SPEC 手冊頁 docs/spec-site/current/ 鈴鐺、通知中心、通知設定三頁 收口
租戶層其餘管理 管理員整個關掉某事件(全租戶都不發)、看發送量與投遞紀錄;型錄 enabled 欄已留,沒有 UI。必收名單與群組推送已由 FR-196.1 交付 有客戶要再開 FR
Discord/Telegram 個人綁定 現在是租戶頻道,群組推送由租戶規則決定 候選
瀏覽器桌面推播 落地版 http+IP 環境跑不起來,且要出網 不做
§5

延伸出去的 FR

目前只有一條:FR-192(Agent 主控台意見回饋)。型錄預留了 feedback.replied,原廠回覆功能上線時由該案直接發事件,不必動通知中心。

閱讀順序:先本頁,再 01 事件型錄 看有哪些事件,之後依角色挑一頁:後端看 04、05,前端看 06,維運看 07。

§6

這份文件的定位

你想知道 看哪份
現在長什麼樣、怎麼接、有哪些事件與表 本頁與 spec/ 七頁(定版,隨現況改寫);租戶層管理摘要見 FR-196.1 定版 SPEC
為什麼這樣決定、排除了什麼 design.md(設計,凍結)、discussion.md(討論稿)
畫面示意 prototype/index.html
哪一棒做了什麼 Notion 母卡 CM-3875 與子卡回寫、git log