---
title: "通知中心 — 定版 SPEC (FR-196)"
brand: "Guidant AI · **FR-196** 通知中心"
eyebrow: "FR-196 · 定版 SPEC · 現況描述"
h1: "▸ 通知中心 定版 SPEC"
subtitle: "交付了什麼、現在長什麼樣；細節拆在 spec/ 七頁；租戶層管理見 FR-196.1"
lede: "主系統的通知收進同一個樞紐：新套件 **jedi-notification-center** 負責事件型錄、收件匣、個人設定、租戶規則、外送決策、合併與即時訊號；主系統用八張接口把它接上既有的使用者名冊、範本、投遞、排程；前端鈴鐺變成收件匣入口、多一頁通知中心、一頁個人通知設定、兩支頁頂橫幅；系統設定的通知管理頁由租戶管理員決定必收事件與群組推送。本頁只放摘要與索引，每個主題的完整規格在 `spec/` 底下各一頁。"
chips: [
  {text: "25 個事件、5 類、9 個原廠建議必收（租戶可改）", kind: accent},
  {text: "套件 0.2.0、10 條套件端點＋2 條主系統端點", kind: accent},
  {text: "6 張新表＋1 張既有表擴欄；8 支 migration", kind: accent},
  {text: "Agent 主控台不在本案", kind: plain}
]
footer: "FR-196 · 定版 SPEC · 數字為 DEV 實查與工作區程式碼實讀 · 設計理由見 design.md、討論稿 discussion.md"
---

## 一句話 {#tldr nav="一句話"}

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

## 交付物總表 {#deliverables nav="交付物"}

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

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

## 端到端 {#flow nav="流程"}

```{.mermaid cap="圖 1　一筆通知從業務程式到瀏覽器。第 1 步是業務程式唯一寫的那一行；立即寄與排進摘要由第 6 步分岔；第 9 步是 SocketIO 訊號，連不上時瀏覽器退回每 60 秒輪詢。"}
%%{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()：到時的摘要同人同批合成一封寄出
```

## 這一輪沒做完的 {#remaining nav="沒做完的"}

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

## 延伸出去的 FR {#downstream nav="延伸 FR"}

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

閱讀順序：先本頁，再 [01 事件型錄](spec/01-事件型錄.md) 看有哪些事件，之後依角色挑一頁：後端看 [04](spec/04-套件接線.md)、[05](spec/05-主系統接線.md)，前端看 [06](spec/06-前端.md)，維運看 [07](spec/07-維運與收口.md)。

## 這份文件的定位 {#scope nav="本頁定位"}

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