---
title: "通知中心 — 設計文件 (FR-196)"
brand: "Guidant AI · **FR-196** 通知中心"
eyebrow: "FR-196 · 設計文件 v1.0 · 2026-11-11（D1～D8 定案；已過稿；22 張開發卡 10 批，三期一次開）"
h1: "通知中心 — 設計文件 v1.0"
subtitle: "把產品裡所有「要讓人知道一件事」的動作收進同一個入口；鈴鐺、收件匣、通知設定、系統橫幅；做成獨立套件，其他產品能裝"
lede: "本文件把討論稿的八項定案落成可派工的設計：新套件 **jedi-notification-center** 負責事件型錄、收件匣、個人設定、路由與摘要；既有 jedi-notification 維持純投遞；主系統十四個寄信點各改成一行呼叫；鈴鐺換成讀收件匣；三個新頁面（收件匣、通知設定、橫幅）；三期交付，第一期就看得到東西。Agent 主控台本案不做（PM 2026-11-11 裁），套件的 port 契約保留讓日後能裝。本版列出**要開哪些資料表、哪些 API**，決策者過稿後才拆卡。"
chips: [
  {text: "D1～D8 定案（2026-11-11）", kind: ok},
  {text: "新套件 jedi-notification-center；新開 5 張表、擴充 1 張既有表；主系統 8＋2 條 API", kind: accent},
  {text: "三期：看得見 → 全部事件改走中心 → 即時與橫幅；Agent 主控台不做（PM 裁）", kind: accent},
  {text: "拆卡表與 Notion 卡待決策者過稿後再做", kind: warn},
  {text: "陷阱：交易信不進中心；收件人存 user_id 不存信箱；即時頻道只推訊號；橫幅沿用既有四支不另開", kind: crit}
]
footer: "FR-196 · 設計文件 v1.0 · 2026-11-11 · 討論稿：[Artifact 討論稿](https://claude.ai/artifact/1ttV3B84VKnAtBnfqpWvuu) · 沿革見 LOG 與 git log"
---

> 狀態：**v1.0 定案、已開卡**｜日期：2026-11-11｜母卡 [CM-3875](https://app.notion.com/p/FR-196-jedi-notification-center-9-4-415346da4cd081ce8637d722cdda8715)、子卡 CM-3876～CM-3897｜前作 FR-020（通知設定）、FR-078（jedi-notification 資安掃描）、FR-137（任務提醒信與寄信紀錄表）、FR-150（PM 手動提醒）
> 開發 branch：主 repo 目前在 `feature/FR-172`；runner 開工 `git branch --show-current` 再確認，不對就停下問，不切

> 🔴 **這份是設計決策，不是現況。** 上線後的畫面與 API 現況看 SPEC 頁。定稿後若設計有異動，開 `design-v1.1.md`，本檔不改。

## 變更紀錄 {#changelog nav="變更紀錄"}

| 日期 | 版本 | 內容 |
|---|---|---|
| 2026-11-11 | v1.0 | 決策者過稿；先裁分批開卡建第一期 9 張，後改三期都開，補第二、三期 13 張，共 22 張 10 批寫進 `handoff/cards.py`（斷言過）、純畫面雛形 `prototype/index.html`。PM 裁 Agent 主控台不做：第四期整段拿掉，Agent 離線／更新完成失敗三個主系統端事件留在第二期；套件 port 契約保留。首版。討論稿八項定案（D2 與 D3 合併為「一頁通知設定、23 事件全部展開、8 個必收」）落成資料表、API、套件契約與三期分工；同日做重複設計盤點，修四處：橫幅沿用既有元件不另開 API、投遞紀錄擴充 FR-137 既有表不另開、去重戳改靠合併鍵、通知設定頁另開路由不掛個人資料頁；拆卡待過稿 |

## 1. 需求背景與端到端 {#background nav="背景"}

主系統今天只會在兩種情況主動提醒使用者：右上角鈴鐺裡的「指派給我的待辦任務」與「流程進到我負責的站」，以及 Email。程式碼裡總共十四種信，收件人由各段業務程式自己決定，使用者沒有任何地方可以選「這種信我不要收」；公告發布沒有提示；掃描掃出嚴重弱點、系統有新版、有人用本機管理員登入 Agent 都只寄信；輪次結束、關卡退回、Agent 離線、排定維護這類事件今天完全沒有任何提醒。

鈴鐺現在的實作是把「寄信紀錄表」反查出來當收件匣用：只存信箱不存使用者、只有四種事件寫進來、沒有已讀。這張表（`compliance.task_alert_notifications`）在本案降級為投遞紀錄，不再被鈴鐺反查。

### 做完之後

1. **鈴鐺**顯示未讀通知數，點開是最近十筆，依類別切換；底部固定一行「我的待辦任務（N）」連到任務頁，N 不計進紅點。
2. **通知中心頁**是完整收件匣：表格列出每一則，分未讀／已讀／全部／已封存，可按類別、搜尋，可標已讀、封存、勾選批次。
3. **通知設定頁**在個人設定裡：25 個事件全部展開各一行，站內、Email、聊天工具三個開關；9 個必收事件鎖住。表下方是 Email 摘要與勿擾時段。
4. **系統橫幅**：授權到期與 Agent 離線沿用頁面頂部既有的橫幅元件；新版可更新、排定維護兩種沒有橫幅的事件補兩支掛進同一排。橫幅與收件匣各自獨立，關閉橫幅不影響收件匣那筆。
5. **公告**發布時自動產生「公告」類通知給發送範圍內的人。
6. **所有十四個寄信點**改成一行「通知」呼叫，信的主旨與內文範本沿用；Email 由中心照設定決定寄不寄。
7. **Agent 相關事件**（離線、恢復、更新完成、更新失敗）由主系統發給租戶管理員；Agent 主控台本身不裝通知中心（PM 裁）。

```{.mermaid cap="圖 1　一筆通知從發生到被看到。第 1 步是業務程式唯一要寫的那一行；第 2 到 9 步是套件的事。第一期未讀數每 60 秒輪詢，第三期改成 SocketIO 推訊號。"}
%%{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 DB as notification_inbox
  participant D as jedi-notification（投遞）
  participant W as 瀏覽器（鈴鐺）
  B->>C: notify(event="task.assigned", recipients=[user_id], subject={type, uid}, params)
  C->>C: 查事件型錄（類別、預設管道、必收）
  C->>C: 查每位收件人的設定（三個管道、摘要、勿擾）
  C->>DB: 每位收件人寫一列未讀（含連結參數、合併鍵）
  alt 設定含 Email 且不在勿擾時段
    C->>D: 立即寄（主旨與內文由產品端範本產）
  else 選了每日摘要或在勿擾時段
    C->>DB: 寫 outbound 列，排程到時間一次寄
  end
  C-->>W: 未讀數變了（第一期：瀏覽器每 60 秒 GET；第三期：SocketIO 推訊號）
  W->>W: 鈴鐺紅點 5 → 6
  W->>DB: 點開那筆 → PATCH 已讀，依連結參數跳頁
```

## 2. 分工概述 {#overview nav="概述"}

**整案一句話**：一個「事件進來、通知出去」的樞紐套件，業務程式只呼叫一行；誰收、走哪個管道、要不要彙整、存在哪裡由樞紐決定；使用者在鈴鐺與收件匣看到、在通知設定頁自己調。

三期，每期怎麼判定完成：

1. **第一期：看得見**。套件骨架與五張表、鈴鐺換成收件匣、通知中心頁、未讀數每 60 秒更新；先接四種事件（新任務指派、流程進站、掃描新增嚴重弱點、新公告）。原有 Email 照舊寄不動。**檢查**：指派一張任務給自己，一分鐘內鈴鐺紅點出現，點開看到那筆，點進去到任務頁，回來那筆變已讀、紅點少一；發一則公告，範圍內的人鈴鐺多一筆。
2. **第二期：全部事件改走中心，加通知設定頁**。型錄 25 列全部接上（含 10 個今天沒有的）；14 個寄信點改成一行呼叫；通知設定頁（25 行、9 個鎖住）。**檢查**：把「新任務指派給我」的 Email 關掉，請人指派一張任務給你，站內有、信箱沒有；開回來再試，信有；「掃描新增嚴重弱點」那行是鎖的點不動。
3. **第三期：即時、橫幅、合併、摘要**。接回 SocketIO 通知頻道；補兩支橫幅掛進既有那排；同一物件短時間多筆合併；Email 每日、每週摘要與勿擾時段。**檢查**：兩個瀏覽器各登一個帳號，A 指派任務給 B，B 不重整三秒內鈴鐺變；更新中心偵測到新版，平台管理員每頁頂部出現橫幅，關掉後不再出現但收件匣有。
前置作業（決策者）：批 1 之前要有一張環境卡把主系統改走 jedi-notification-center 的本機路徑（套件是新的，第一版就發 Nexus 也可以，由決策者裁）；第二期驗收 Agent 離線事件要一台真的 Agent 能停容器；第三期驗收要兩個帳號兩個瀏覽器。

## 3. 決策定案（D1～D8） {#decisions nav="決策定案"}

八項全部於 2026-11-11 定案，D2 與 D3 討論後合併。每列寫定案、為什麼、排除了什麼；設計其餘各節以這張表為準。

| 編號 | 定案 | 為什麼 | 排除了什麼 |
|---|---|---|---|
| D1 | 鈴鐺只放通知；底部固定一行「我的待辦任務（N）」連到任務頁，N 不計進紅點 | 通知是「發生了一件事」看過可標已讀；待辦是「還沒做完的工作」看過還在；混在一起紅點數沒有意義 | 鈴鐺上下兩段都放清單：未讀數混淆、待辦永遠清不空、鈴鐺永遠亮 |
| D2＋D3 | 只做一頁「個人通知設定」：25 個事件依類別分頁展開各一行、三個管道開關；5 個類別只當分組不做總開關；9 個必收鎖住、名單出貨寫死；不做租戶層管理頁 | 決策者裁：純類別級做不到「同一類裡只關一個」；可展開版多一個動作；全部展開最直接。管理員層級的三件事（關掉整租戶某事件、看發送量、增減必收）有客戶要再補一頁，資料層不用改 | 管理員通知管理頁＋個人偏好頁兩頁；類別總開關；可展開兩層 |
| D4 | 未讀永遠留；已讀與封存 90 天後清；投遞紀錄另留 180 天；天數進系統設定 | 收件匣會一直長；投遞紀錄給客服排障 | 不限保留 |
| D5 | 即時推播放第三期，第一期每 60 秒輪詢未讀數 | 通知不是聊天，一分鐘延遲沒人抱怨；先把事件接齊 | 第一期就接 SocketIO |
| D6 | Discord、Telegram 維持租戶層級頻道，不做個人綁定（先照此，可再議） | 客戶多半把這兩個當團隊公頻；個人綁定要做綁定流程與驗證，多一整塊 | 個人綁定（列第五期候選） |
| D7 | Agent 主控台的收件匣與主系統不同步（後 PM 裁 Agent 主控台本案不做，此項只剩「Agent 狀態由主系統發」） | 主控台的人就在那台機器前面；主系統管理員要的是「Agent 狀態」，由主系統自己發 | 雙向同步（與 FR-192 一樣重）；Agent 端收件匣（PM 裁不做） |
| D8 | 新套件 jedi-notification-center，依賴 jedi-notification 當外送實作；交易信（OTP、設密碼）不經過中心 | jedi-notification 是純投遞，塞進去投遞與路由綁死，Agent 要裝就得連 SMTP 那堆一起帶 | 擴充 jedi-notification |

## 4. 現況接入點 {#inventory nav="現況盤點"}

按元件分段，每段寫現在是什麼、本案動它哪裡、reuse／extend／new。

**jedi-notification 1.2.4（投遞套件）**：三條管道（SMTP、Discord、Telegram）的實際投遞邏輯，產品裡 12 個呼叫點走 library 用法直接建 `NotificationService` 送。本案 **reuse 不動**：新套件把它當「外送」實作，交易信（登入 OTP、建帳號設密碼，`common/iam_ports.py`）繼續直接用它。

**`compliance.task_alert_notifications`（FR-137 寄信紀錄表）**：每封提醒信一列，存信箱、結果、對應任務；鈴鐺的「流程進站」從它反查。本案 **extend**：這張表已經有「同物件同收件人只寄一次」的唯一索引與 claim 去重、結果與錯誤欄、手動觸發者欄，`job_due_mail_sender.send_digest` 也已會把多張任務合成一封摘要信——這些正是外送佇列要的，不另開表。本案加四欄（`inbox_id`、`channel`、`scheduled_at`、`digest_batch`）讓它同時當外送佇列與投遞紀錄（§5.2 表 5-5）；鈴鐺不再反查它；`MyStageNotificationsQuery` 與 `/flow-engine/stage-notifications/mine` 端點退役（第二期）。

**鈴鐺（FE `src/layout/AppTopbar.vue` 第 484～540 行、`TopbarStageQueue.vue`）**：混放待辦任務與流程進站，頁面載入抓一次。本案 **new 一支元件取代**：`NotificationBell.vue` 讀收件匣，底部一行待辦任務連結；`TopbarStageQueue.vue` 退役。

**14 個寄信點**（表 4-1）：各段業務程式自己組主旨、自己決定收件人、自己呼叫寄信。本案 **extend**：每處改成一行 `notification_center.notify(...)`，主旨與內文範本沿用既有 i18n 鍵（搬到產品端的事件範本表）。

**SocketIO（`core/extensions.py`、`config/socketio_namespaces.py`、jedi-iam `AuthenticatedNamespace`）**：問卷共編在用；舊的 `/socket/notification` 頻道因沒人用已拔掉。本案第三期 **reuse 接回**：新 namespace `/socket/notification-center`，只推「未讀數變了」訊號，瀏覽器收到再用 REST 拉。

**jedi-bulletin 1.2.2（公告套件）**：發布流程、發送範圍（全公司／指定部門）、`bulletin_org_units` 橋表。本案 **extend 一行**：`add_bulletin` 成功後呼叫 `notify(event="bulletin.published", recipients=範圍內使用者)`；收件人解析由主系統的 port 做（套件不認識使用者）。

**頁面頂部橫幅（FE `src/layout/AppLayout.vue` 第 115～125 行；`LicenseExpiryBanner`、`FileProtectionOffBanner`、`AgentOfflineBanner`、`AiQuotaBanner`）**：已有四支橫幅元件掛在同一排，各自有資料來源與關閉邏輯（授權到期走 license store 的 `dismiss`）。本案 **reuse 不另開**：授權到期、Agent 離線兩個事件的橫幅就是既有這兩支；新版可更新、排定維護兩個事件沒有橫幅，各補一支照 `AiQuotaBanner`（51 行、`hint-bar` class）的形狀掛進同一排，資料來源分別是更新中心既有的檢查結果與新的 `/maintenance` 讀端點。通知中心不做 `/banners` API、型錄不加 `banner` 欄。

**既有的「通知過了沒」去重戳**（新版通知 `notified_version`、Agent 憑證到期 `remote_agents.cert_expiry_notified_at`、FR-137 表的唯一索引）：各自記一件事通知過沒。本案 **extend 收斂**：第二期把這兩處改接 `notify()` 時，去重改靠收件匣的 `merge_key`（同事件同主題未讀就不重發），各自的戳不再更新、欄位留著不刪；FR-137 表的唯一索引沿用當外送層去重。

**管理員判定（`core/plugins/license.py::TenantAdminDirectory`）**：超管旗標、管理員角色、`iam.tenant.update` 能力點三者聯集；授權到期與新版通知在用。本案 **reuse**：事件型錄裡「租戶管理員」「平台管理員」這兩種收件人全部走它，不另寫一份。

**插件掛載骨架（`core/plugins/bulletin.py`、jedi-bulletin `plugin/contract.py`）**：adapters dataclass＋守門四件無預設值＋`register(app, adapters, mount_api)`＋套件自帶 `migrations/*.sql` 由宿主決定何時套。本案 **照型 new**：jedi-notification-center 用同一套契約形狀，主系統 `core/plugins/notification_center.py` 掛載。

**背景排程（APScheduler `core/scheduler_*.py`）與 worker（`background_jobs`）**：摘要信、保留天數清理、Agent 離線判定要排程。本案 **extend**：新 `core/scheduler_notification.py` 加三個 tick（摘要每小時掃一次到時的、清理每日 03:00、離線判定每分鐘）。

**系統設定（`public.system_configs`、`read_tenant_config_value`）**：租戶層設定值。本案 **extend**：新 group `NOTIFICATION_CENTER` 三個 key（已讀保留天數、投遞紀錄保留天數、Agent 離線判定分鐘數）。

表 4-1　十四個寄信點（第二期每處改成一行呼叫；主旨 i18n 鍵沿用進事件範本表）

| 檔案:行 | 事件代碼 | 現在的收件人決定法 |
|---|---|---|
| `app/flow_engine/service/workflow_execution_service.py:1246` | `task.assigned` | 被指派者 |
| `app/flow_engine/service/workflow_execution_service.py:1183` | `task.batch_assigned` | 被指派者，彙整一封 |
| `app/task_alert/service/job_due_mail_sender.py:102`、`job_due_reminder_service.py` | `task.due` | 處理人，每日排程 |
| `app/task_alert/service/manual_job_due_reminder_service.py:155` | `task.manual_reminder` | PM 勾選 |
| `app/flow_engine/service/stage_entered_notify_service.py:117` | `stage.entered` | 該站能力點持有者；無人時 PM |
| `app/flow_control/service/job_batch_complete_service.py:221` | `task.batch_completed` | PM；另推 Discord／Telegram |
| `app/flow_control/service/project_service.py:684`、`:726` | `project.started` | 專案成員；另推 Discord／Telegram |
| `app/task_alert/service/scan_alert_app_service.py:74` | `scan.critical_found` | 專案 PM、資安負責人 |
| `app/task_alert/service/support_end_reminder_service.py:73` | `license.expiring` | 租戶管理員 |
| `app/product_update/service/product_update_flow.py:370` | `system.update_available` | 平台管理員（`TenantAdminDirectory`） |
| `core/plugins/_agent_local_admin_notice.py` | `agent.local_admin_login` | 租戶管理員 |
| `core/scheduler_agent.py::_agent_cert_expiry_notice_tick`（套件內） | `agent.cert_expiring` | 租戶管理員 |
| `common/iam_ports.py:97`（OTP）、建帳號設密碼信 | 不進中心 | 交易信，直接用 jedi-notification |
| `app/notify_config/service/notify_config_test_service.py` | 不進中心 | 測試訊息，直接用 jedi-notification |

## 5. 詳細設計 {#design nav="詳細設計"}

### 5.1 套件 jedi-notification-center：職責與邊界

套件只認識五個概念：**事件代碼**（字串，如 `task.assigned`）、**收件人**（宿主的使用者識別，整數或字串由宿主定）、**主題物件**（`subject_type`＋`subject_uid`，用來組連結與合併）、**參數**（dict，給範本與連結用）、**管道**（`inapp`／`email`／`chat`）。它不認識任務、專案、掃描、Agent，也不認識路由。

套件做的事：事件型錄查詢、收件人設定查詢與預設值、寫收件匣、決定每個管道立即送還是排進 outbound、摘要彙整、保留天數清理、收件匣與設定的 REST API。

套件不做的事，由宿主透過 port 提供：

| port | 宿主要給什麼 | 主系統實作 | 其他產品（本案不做，契約保留） |
|---|---|---|---|
| `IRecipientDirectory` | 使用者 id → 信箱、語系、暱稱；角色名 → 使用者 id 清單（`tenant_admin`、`platform_admin`、`project_members(project_uid)`） | `TenantAdminDirectory`＋`UserDomainService`＋`ProjectParticipantDomainService` | 本案不做；日後主控台本機帳號表 |
| `ITemplateRenderer` | 事件代碼＋參數＋語系 → 標題、摘要、Email 主旨與內文 | 既有 i18n 鍵（表 4-1 的 `*_mail_subject`）搬進事件範本表 | 主控台 i18n |
| `ILinkResolver` | 事件代碼＋主題物件 → 前端路由名與參數（JSON） | 事件型錄表的 `link_route`／`link_params_template` 欄 | 同 |
| `IDeliveryGateway` | 把一封 Email 或一則聊天訊息送出去 | jedi-notification `NotificationService` | 不送（Agent 只有站內） |
| `IRealtimeNotifier` | 通知某使用者「未讀數變了」 | 第一期 no-op；第三期 SocketIO emit | no-op |
| `IStorage` | SQLAlchemy session provider 與方言 | Postgres，走 `jedi_common` 的 `get_session()` | SQLite |
| `IClock`、`ITenantContext` | 現在時間；目前租戶 id | 既有 | 固定單租戶 |

掛載契約照 jedi-bulletin：`NotificationCenterAdapters` dataclass（守門四件無預設值：`auth_required`、`capability_required`、`current_user_context`、`response_builder`；七張 port），`register(app, adapters, mount_api=True)` 回 `PluginHandle`；`plugin/migrations.py::iter_migrations()` 提供 SQL，宿主決定何時套；`CAPABILITIES` 列出兩顆能力點（`notification.inbox.read` 全員預設有、`notification.banner.publish` 平台管理員發「排定維護」用）。

### 5.2 資料表（新開五張、擴充一張；Postgres）

全部在 `public` schema、前綴 `notification_`。tenant-scoped 表帶 `tenant_id`＋`org_unit_id`，套 RLS 與 `cm_app` GRANT，照 jedi-bulletin `002-bulletin-rls-grants.sql` 的形狀。

**表 5-1　`notification_events`（事件型錄；出貨 seed 25 列；管理員不改、runner 登記新事件走 seed migration）**

| 欄位 | 型別 | 說明 |
|---|---|---|
| `code` | varchar(64) PK | 事件代碼，如 `task.assigned`；程式呼叫時帶它 |
| `category` | varchar(32) not null | `task`／`project`／`scan_agent`／`system`／`bulletin`，對應 `system_menus` group `NOTIFICATION_CATEGORY` |
| `mandatory` | boolean not null default false | 必收：站內與 Email 鎖住 |
| `default_inapp`／`default_email`／`default_chat` | boolean not null | 使用者沒設過時的預設（站內 true、Email 照表 4-1 現況、chat false） |
| `merge_window_sec` | integer null | 合併視窗秒數；null 不合併（第三期用） |
| `link_route` | varchar(128) null | 前端路由名 |
| `link_params_template` | jsonb null | 路由參數樣板，如 `{"project": "{project_uid}", "job": "{job_uid}"}` |
| `title_key`、`summary_key`、`mail_subject_key`、`mail_body_key` | varchar(128) | i18n 鍵（產品端範本） |
| `enabled` | boolean not null default true | 整個系統停用某事件（出貨工具，不給 UI） |
| `sort` | integer | 通知設定頁排序 |

**表 5-2　`notification_inbox`（收件匣；每位收件人一列）**

| 欄位 | 型別 | 說明 |
|---|---|---|
| `id` | bigserial PK | |
| `uid` | varchar(36) unique | API 對外 |
| `tenant_id`、`org_unit_id` | integer | RLS 用；`org_unit_id` 取收件人的 |
| `recipient_user_id` | integer not null | 🔴 存使用者 id，不存信箱（FR-137 表存信箱是鈴鐺反查錯位的根因） |
| `event_code` | varchar(64) not null FK → events | |
| `category` | varchar(32) not null | 從型錄複製，列表篩選不 join |
| `subject_type`、`subject_uid` | varchar(32)、varchar(64) | 主題物件（如 `job_execution`＋uid） |
| `merge_key` | varchar(160) null | `event_code:subject_uid`，第三期合併用；第一期就寫 |
| `merged_count` | integer not null default 1 | 合併後的筆數 |
| `title`、`summary` | varchar(255)、text | 渲染後的文字（寫入當下用收件人語系渲染，之後不重算） |
| `params` | jsonb | 原始參數，給連結與重渲染 |
| `link` | jsonb null | `{"route": ..., "params": {...}}`，`ILinkResolver` 解好存起來 |
| `mandatory` | boolean | 從型錄複製，列表顯示「必收」標籤 |
| `read_at`、`archived_at` | timestamptz null | 三態：都 null 未讀；`read_at` 有已讀；`archived_at` 有封存 |
| `created_at` | timestamptz not null | |

索引：`(recipient_user_id, archived_at, read_at, created_at desc)`（鈴鐺與清單）、`(merge_key, recipient_user_id, created_at desc)`（合併）、`(created_at)`（清理）。

**表 5-3　`notification_user_settings`（通知設定；每人每事件一列）**：複合主鍵 `tenant_id`＋`user_id`＋`event_code`，三個布林欄 `inapp`、`email`、`chat`，加 `updated_at`。沒有列就用型錄的預設值，所以新帳號不需要預先灌 25 列。必收事件的 `inapp`／`email` 在 API 層拒改（回 412），資料層不加約束，因為必收名單是型錄的屬性，未來若改由管理員調整不必動這張表。

**表 5-4　`notification_user_profile`（通知設定頁下方的兩個設定；每人一列）**

| 欄位 | 型別 | 說明 |
|---|---|---|
| `tenant_id`、`user_id` | 複合 PK | |
| `email_digest` | varchar(16) not null default `immediate` | `immediate`／`daily`／`weekly`（值進 `system_menus` group `NOTIFICATION_DIGEST`） |
| `digest_hour` | smallint default 9 | 每日或每週寄出時刻 |
| `digest_weekday` | smallint null | 每週：1～7 |
| `quiet_from`、`quiet_to` | time null | 勿擾時段（本地時刻；租戶時區由宿主 `IClock` 給） |
| `updated_at` | timestamptz | |

**表 5-5　`compliance.task_alert_notifications`（既有表擴充；外送佇列兼投遞紀錄）**

這張表已有：唯一索引（同物件同收件人只寄一次）與 `claim` 去重、`recipient_email`、`sent_at`、`result`、`error`、`triggered_by`。本案加四欄，既有欄與既有寫入者不動：

| 新增欄位 | 型別 | 說明 |
|---|---|---|
| `inbox_id` | bigint null FK → `notification_inbox` | 這封外送對應哪筆站內通知；舊資料 null |
| `channel` | varchar(16) not null default `email` | `email`／`chat`；舊資料全是 email |
| `scheduled_at` | timestamptz null | 立即＝now；摘要＝下個 digest 時刻；勿擾＝時段結束；null＝舊資料（已寄） |
| `digest_batch` | varchar(64) null | 同一人同一批摘要的鍵，寄出時合成一封；`send_digest` 既有合信邏輯沿用 |

`result` 多一個值 `skipped`（寄出前使用者改設定關掉）。`object_type` 沿用當事件代碼的前身，第二期各寄信點改接後統一寫事件代碼。

**系統橫幅不經過通知中心**：橫幅是頁面頂部既有的那一排元件（§4），各自讀自己的資料來源。通知中心只負責同一事件在收件匣留一筆；關閉橫幅與標已讀互不影響。排定維護由平台管理員在系統設定的「排定維護」小表單建一筆（新表 `notification_maintenance`：`tenant_id`、`starts_at`、`duration_min`、`message`、`created_user`、`created_at`，一筆建立時同時 `notify(system.maintenance_scheduled)` 給全租戶使用者），橫幅元件讀 `GET /maintenance/current`。

**與既有表的關係**：`compliance.task_alert_notifications` 擴充後繼續是唯一的投遞紀錄表，第二期起由套件的外送層寫入、各寄信點不再直接寫；既有讀取端（任務提醒紀錄頁、`count_by_result`）照常可用。`system_menus` 新增兩個 group：`NOTIFICATION_CATEGORY`（5 值）、`NOTIFICATION_DIGEST`（3 值），phase=seed migration。

### 5.3 主系統 API（套件掛的 8 條＋產品端 2 條）

全部前綴 `/api/1.0/notification-center`，JWT 必須；回應走 `return_response` 信封。

| 動詞 | 路徑 | 做什麼 | 要點 |
|---|---|---|---|
| GET | `/unread-count` | 鈴鐺紅點數與待辦任務數 | 回 `{unread: 5, todo: 12}`；`todo` 由產品端 port 給（D1）；輕量，第一期每 60 秒輪詢 |
| POST | `/inbox/list` | 收件匣分頁 | body：`page`、`page_size`、`state`（`unread`／`all`／`archived`）、`category`、`keyword`；回 `data[]`＋`meta`；每筆含 `uid`、`event_code`、`category`、`title`、`summary`、`link`、`mandatory`、`merged_count`、`read_at`、`created_at` |
| GET | `/inbox/recent` | 鈴鐺下拉最近十筆（未封存） | 與 list 同形狀，固定 10 筆、可帶 `category` |
| PATCH | `/inbox/<uid>/read` | 標已讀 | 冪等；點通知跳頁時前端先打這支 |
| PATCH | `/inbox/<uid>/archive` | 封存 | 封存後不計未讀 |
| POST | `/inbox/batch` | 批次 | body：`uids[]`、`action` ∈ `read`／`archive`／`unread`；`read_all` 時 `uids` 省略帶 `scope`（`all`／`category`） |
| GET | `/settings` | 通知設定頁資料 | 回 25 列（型錄 join 個人設定，沒設過的用預設），每列含 `code`、`category`、`mandatory`、`inapp`、`email`、`chat`；加 `profile`（摘要、勿擾）與 `chat_available`（租戶有沒有設 Discord／Telegram） |
| PUT | `/settings` | 存通知設定 | body：`events[]`（code＋三個布林）＋`profile`；必收事件的 `inapp`／`email` 若與型錄不符回 412 `NC_412001`；全表覆寫，不做 PATCH |
| POST | `/maintenance` | 建「排定維護」（產品端 route，不在套件） | 能力點 `notification.banner.publish`；body：`starts_at`、`duration_min`、`message`；寫 `notification_maintenance` 一筆並 `notify` 全租戶使用者 |
| GET | `/maintenance/current` | 橫幅元件讀目前有效的維護排程（產品端） | 回最近一筆 `starts_at + duration` 未過的；沒有回 null |

退役（第二期）：`GET /flow-engine/stage-notifications/mine`、FE `API.STAGE_NOTIFICATIONS_MINE`。`GET /flow-engine/task/queue` 保留，鈴鐺底部那行用它的數字。

錯誤碼：新檔 `common/code/notification_center_error_code.py`，前綴 `NC_`：`NC_404001` 通知不存在、`NC_412001` 必收事件不可關、`NC_400001` 設定值不在選單、`NC_403001` 無發橫幅能力點。FE `error-code.json` 同步四條。

### 5.4 套件內部 API（業務程式呼叫的那一行）

業務程式只接觸這一個函式。它不回傳通知物件，呼叫端不需要知道寫了幾列、寄了幾封。

```python
from jedi_notification_center import notify

notify(
    event="task.assigned",
    recipients=[user_id],                 # 或 recipients=Role("tenant_admin") 由 port 展開
    subject=("job_execution", job.uid),
    params={"project_uid": p.uid, "project_name": p.name, "job_uid": job.uid,
            "job_name": job.name, "assigner": me.nickname},
)
```

行為：型錄查不到 `event` 寫 warning 不炸（舊 image 跑新事件時不會 500）；`recipients` 空就直接 return；在 `@transaction` 內呼叫時收件匣寫入與業務寫入同一交易，外送排在 commit 後（照 `stage_entered_notify_service._send_after_commit` 的做法）。`Role(...)` 展開走 `IRecipientDirectory`。

### 5.5 前端（主系統）

四個新元件加一支 composable；鈴鐺舊元件退役。全部套全站 `dark-card` 與字級，不自訂版面。

| 檔案 | 做什麼 |
|---|---|
| `src/layout/NotificationBell.vue`（新） | 取代 `AppTopbar.vue` 第 484～540 行與 `TopbarStageQueue.vue`：紅點＝`unread`；下拉＝`/inbox/recent`＋類別 SegmentButtons（small）；底部「全部標為已讀」「查看全部通知」「通知設定」；最底一行「我的待辦任務（todo）」連 `my-tasks` |
| `src/views/notification/NotificationInboxView.vue`（新，路由 `/notification`） | 收件匣：工具列（未讀／已讀／全部／已封存四段 SegmentButtons、類別 Dropdown、搜尋 IconField）；`DataTable` 五欄（勾選、類別、通知、時間、操作）；每列動作「前往」「標已讀」「封存」；勾選批次；全站 `dark-card`，不自訂字級 |
| `src/views/notification/NotificationSettingsView.vue`（新，路由 `/user/notification-settings`，從右上角使用者選單進；既有 `UserProfileForm.vue` 681 行無分頁結構，不往裡掛） | 25 行分 5 組，三個 InputSwitch；必收那行兩格 `disabled`＋Tag「必收」；下方摘要 SegmentButtons、勿擾兩個時間；儲存 `:loading` |
| `src/components/product-update/UpdateAvailableBanner.vue`、`src/components/system/MaintenanceBanner.vue`（新，照 `AiQuotaBanner` 形狀掛進 `AppLayout` 第 124 行那排） | 前者讀更新中心既有檢查結果（只平台管理員），後者讀 `/maintenance/current`；關閉記 sessionStorage；`hint-bar` class，🔴 不准左側粗色邊框 |
| `src/composables/useNotificationCenter.js`（新） | 60 秒輪詢 `unread-count`；第三期改訂 SocketIO 事件後再拉 |
| `src/config/api/api.js` | 加 `NOTIFICATION_CENTER_*` 常數；刪 `STAGE_NOTIFICATIONS_MINE` |
| `src/config/locales/i18n/{zh-tw,en}/notification-center.json`（新）、`menu.json` | 頁名、25 個事件名、類別名、設定頁文案；menu.json 中英文都要補（🔴 每次加頁面都漏） |

### 5.6 第三期：即時、合併、摘要、橫幅

- **即時**：`config/socketio_namespaces.py` 加 `("jedi_notification_center.realtime.handler", "NotificationCenterNamespace", "/socket/notification-center")`；handler 繼承 jedi-iam `AuthenticatedNamespace`，連線即 join `user:<id>` room；`IRealtimeNotifier.emit(user_id)` 送 `{"event": "unread_changed"}`，不帶內容。瀏覽器收到後打 `unread-count` 與（下拉開著時）`inbox/recent`。資安邊界：頻道只有訊號，沒有第二條資料出口。
- **合併**：`notify()` 寫入前查同收件人同 `merge_key` 且 `created_at` 在 `merge_window_sec` 內且未讀的那筆，有就 `merged_count+1`、更新 `title`（範本吃 `{count}`）與 `created_at`，不新增；Email 不合併（每事件一封或進摘要）。
- **摘要**：`notification_outbound.scheduled_at` 由設定決定；`core/scheduler_notification.py` 每小時掃 `scheduled_at <= now and result='pending'`，同人同 `digest_batch` 合成一封（範本 `digest_mail_body_key`，列出每筆標題與連結）。勿擾：`scheduled_at` 推到 `quiet_to`。
- **橫幅**：補兩支掛進既有那排（§5.5）；授權到期、Agent 離線沿用既有兩支。

### 5.7 Agent 相關事件（主系統端，第二期）

Agent 主控台本案不裝通知中心（PM 2026-11-11 裁）。主系統端仍發三個與 Agent 有關的事件給租戶管理員：`agent.offline`／`agent.reconnected`（心跳 observer 掛點，離線超過 `NOTIFICATION_CENTER/agent_offline_minutes` 分鐘判定；恢復時再發一筆）、`agent.update_completed`／`agent.update_failed`（更新回報事件）、`agent.cert_expiring`（既有排程改接）。Agent 離線橫幅沿用既有 `AgentOfflineBanner`。

日後要讓 Agent 主控台也裝：套件的七張 port 已預留，換 `IStorage`（SQLite）與 `IRecipientDirectory`（主控台帳號表）兩張、其餘 no-op 即可，不必改套件本體。

### 5.8 安全邊界

- 通知內容只放標題、摘要、連結參數；不放密碼、token、弱點細節。點進去照既有頁面權限判定，收件匣不是繞過權限的第二條路。
- 收件匣與設定表受 RLS；API 只回 `recipient_user_id = 當前使用者` 的列，`uid` 猜中別人的回 404 不分「不存在」與「不是你的」。
- Email 外送內容與現在相同，沒有新增外洩面；`recipient_address` 留紀錄給客服，受 RLS。
- SocketIO 頻道只推 `unread_changed` 訊號；握手走 jedi-iam 的 token 驗證。
- `POST /maintenance` 要能力點；其他事件只能由程式發，沒有「任意發通知給任意人」的 API。
- 保留天數清理走排程、`cmmgr` 身分，寫 log 不寫稽核事件（量大）。

## 6. 拆分（22 張開發卡、10 批；三期一次開） {#breakdown nav="拆分"}

三期全部開卡（決策者 2026-11-11 先裁分批、再改三期都開）：批 1～4 第一期、批 5～8 第二期（F-5 退役在批 8）、批 8～10 第三期。拆卡表的真相源是 `handoff/cards.py`（兩個斷言：依賴在更早的批；同批同 repo 不改同一檔），本節與 Notion 卡都從它產。只開開發卡；驗收與收口由決策者與首腦做，見 §7。

批＝能同時派的一組；一批全驗完再派下一批。每張卡的完整內容（改哪些檔、新開檔、驗收）在 `cards.py` 與 Notion 子卡。

| 卡 | 期 | 批 | repo | 做什麼 | reuse／extend／new | 依賴 | model/effort |
|---|---|---|---|---|---|---|---|
| E-1 | 第一期 | 1 | main | 環境卡 | reuse | 無 | sonnet/low |
| P-1 | 第一期 | 1 | jedi-packages | jedi-notification-center 0.1.0 套件骨架 | new（新套件，照型） | 無 | opus/high |
| S-1 | 第一期 | 2 | main | 主線 seed migration | reuse | P-1 | sonnet/medium |
| P-2 | 第一期 | 2 | jedi-packages | jedi-notification-center REST 層 | extend（P-1 的套件） | P-1 | opus/medium |
| M-1 | 第一期 | 3 | main | 主系統掛載 jedi-notification-center | 照型 new | P-1、P-2、S-1 | opus/high |
| F-3 | 第一期 | 3 | fe | FE 登記型檔 owner | extend | S-1 | sonnet/medium |
| F-1 | 第一期 | 4 | fe | FE 鈴鐺元件 NotificationBell.vue 取代 AppTopbar 第 484～540 行與 TopbarStageQueue.vue | new 一支元件取代舊段（AppTopbar 598 行已接近上限，鈴鐺整段抽出去）；reuse 既有 `v-styleclass` 下拉與 `v-badge`；分段用 SegmentButtons（small）；`useNotificationCenter.js` 輪詢照 `useUserUtil().getTaskQueue` 的呼叫方式；`TopbarStageQueue.vue` 退役刪檔 | M-1、F-3 | opus/medium |
| F-2 | 第一期 | 4 | fe | FE 通知中心頁 NotificationInboxView.vue（路由 /notification） | new 頁面（照雛形 index.html 畫面 2 結構）；reuse `dark-card`、SegmentButtons（small）、IconField 搜尋、既有 DataTable 不用（分組清單用 list）；點「前往」用 `link.route`＋`link.params` 做 `router.push`，先 PATCH read | M-1、F-3 | opus/medium |
| M-2 | 第一期 | 4 | main | 主系統第一期四個事件接入 notify() | extend 四處 | M-1 | opus/medium |
| P-3 | 第二期 | 5 | jedi-packages | jedi-notification-center 外送層 | extend（套件） | P-2 | opus/high |
| S-2 | 第二期 | 5 | main | 主線 migration | extend 既有表（設計 §5.2 表 5-5） | S-1 | sonnet/medium |
| F-4 | 第二期 | 5 | fe | FE 通知設定頁 NotificationSettingsView.vue 換成真頁 | extend F-3 的佔位頁（同檔換內容）；照雛形第三個分頁；分組標題只是文字不是開關；儲存打 `PUT /settings` 全表覆寫；412 時 toast 既有 error-code i18n | F-3、M-1 | opus/medium |
| M-3 | 第二期 | 6 | main | 主系統外送接線 | extend | P-3、S-2、M-2 | opus/high |
| M-4 | 第二期 | 7 | main | 主系統其餘寄信點改接 notify()（第 5～14 處） | extend 十處各改一行＋拿掉既有寄信；收件人 | M-3 | opus/high |
| M-5 | 第二期 | 7 | main | 主系統今天沒有的事件補發（第二期） | extend 各處加一行 notify | M-3 | opus/medium |
| M-6 | 第二期 | 7 | main | 退役第一期前的舊鈴鐺端點與查詢 | 刪除（reuse 無） | M-3 | sonnet/low |
| F-5 | 第二期 | 8 | fe | FE 退役舊鈴鐺殘留 | 刪除；grep 無引用才刪 | F-1、M-6 | sonnet/low |
| P-4 | 第三期 | 8 | jedi-packages | jedi-notification-center 合併 | extend `notify_service` | P-3 | opus/medium |
| P-5 | 第三期 | 8 | jedi-packages | jedi-notification-center 即時 namespace | 照型 new | P-3 | opus/medium |
| S-3 | 第三期 | 8 | main | 主線 seed | extend seed | S-2 | sonnet/low |
| M-7 | 第三期 | 9 | main | 主系統第三期接線 | extend | P-4、P-5、S-3、M-4 | opus/medium |
| F-6 | 第三期 | 10 | fe | FE 第三期 | extend `useNotificationCenter.js`（socket 照 `useSurveySocket.js` 的 io 用法）；兩支橫幅照 `AiQuotaBanner.vue`（`hint-bar`、關閉記 sessionStorage）；表單照 `notify-config/NotifyConfigForm.vue` 形狀放系統設定；api.js／menu.json／i18n 新鍵本卡自己加（第三期 FE 只有本卡，無撞） | F-4、F-5、M-7 | opus/medium |

登記型共用檔的 owner：`scripts/sql/manifest.tsv`＝S-1（批 2）／S-2（批 5）／S-3（批 8）各自那批；FE `api.js`／`router`／`menu.json`／`notification-center.json`／`AppTopbar.vue` 使用者選單＝F-3（批 3），F-4 只加 i18n 鍵，F-6 獨自一批可全碰；FE `error-code.json`＝M-1；`core/plugins/__init__.py`／`di_containers/containers.py`＝M-1；`config/socketio_namespaces.py`／`config/app_modules.py`＝M-7；`core/plugins/_notification_center_ports.py` M-1 建、M-2／M-3／M-7 各自那批加 class。

每期做完的樣子：第一期鈴鐺紅點與下拉、通知中心頁、四個事件進收件匣、個人通知設定頁佔位、Email 照舊；第二期 25 個事件全部進收件匣、Email 由設定決定、通知設定真頁、舊鈴鐺端點退役；第三期即時紅點、合併、兩支橫幅、排定維護、摘要與勿擾生效。

## 7. 合回後收口清單與端到端驗收 {#acceptance nav="收口與驗收"}

收口（不開卡，決策者與首腦做）：套件發版推 Nexus、主系統改回釘版、出貨基線重產（五張新表＋一張擴欄＋兩個 seed group＋能力點）、SPEC 頁（鈴鐺、通知中心、通知設定三頁；橫幅併入既有頁）、menu i18n 守衛跑過。

端到端驗收照 §2 三期的「檢查」逐條做；另加：

- 用一個沒設過任何通知設定的新帳號登入，通知設定頁 25 行全部顯示預設值，存一次後 DB 多 25 列。
- 把 `NOTIFICATION_CENTER/inbox_retention_days` 設 1，造一筆已讀通知，把 `created_at` 改成兩天前，跑清理 tick，那筆消失、未讀的不消失。
- 用 `cm_app` 身分 `SELECT` 收件匣，只看得到自己租戶。
- Agent 離線事件（第二期）：停一台 Agent 容器超過設定分鐘數，管理員收件匣多一筆；起回來多一筆恢復。

## 8. 風險與陷阱 {#risks nav="風險"}

- **收件人存信箱**是 FR-137 表的錯位根因（鈴鐺要用 user_id 反查信箱再比對）；本案一律存 `recipient_user_id`。
- **交易信進中心**會讓使用者關掉 OTP 信把自己鎖在外面；OTP、設密碼、測試訊息三處永遠直接用 jedi-notification。
- **型錄查不到事件就 500**：舊 image 配新事件碼會炸；`notify()` 查不到寫 warning 回 None。
- **鈴鐺紅點把待辦算進去**：D1 明確分開，`unread-count` 回兩個數字。
- **即時頻道推內容**：變成第二條資料出口，資安掃描會標；只推訊號。
- **套件認識路由**：其他產品與主系統路由不同；連結由 `ILinkResolver` 解成 `{route, params}` 存起來，套件不解讀。
- **menu.json 只補中文**：守衛只比前端路由與資料庫、只查中文；四個新頁中英文一次補。
- **左側粗色邊框**：橫幅與通知列都不准，交稿前 `grep border-left`。
- **重複設計**：橫幅已有四支、投遞紀錄已有一張表、去重戳已有兩處——本版已改為沿用；拆卡時 reuse／extend 欄要對回 §4，runner 看到「另開一支 Banner」「另開 outbound 表」就是走錯。
- **時區**：勿擾時段與摘要時刻是本地時刻，容器 `TZ=UTC` 會差 8 小時；套件收 `IClock` 給租戶時區（照 jedi-bulletin `now_provider` 的教訓）。
- **已讀通知保留 90 天**會讓收件匣在大租戶長得很快；索引以 `(recipient_user_id, archived_at, read_at, created_at desc)` 為主，清理走批次 delete 限制每批 5000 列。

## 9. 這份文件的定位 {#positioning nav="定位"}

設計文件：為什麼這樣決定、要開哪些表與 API。拆卡表在 `handoff/cards.py`，純畫面雛形在 `prototype/index.html`（鈴鐺、收件匣、通知設定、橫幅四個畫面；runner 只取結構與資訊順序，文案依 i18n 重寫）。上線後現況看 SPEC 頁，本檔不改；設計異動開 `design-v1.1.md`。
