FR-196 · 設計文件 v1.0 · 2026-11-11(D1~D8 定案;已過稿;22 張開發卡 10 批,三期一次開)

通知中心 — 設計文件 v1.0

把產品裡所有「要讓人知道一件事」的動作收進同一個入口;鈴鐺、收件匣、通知設定、系統橫幅;做成獨立套件,其他產品能裝

本文件把討論稿的八項定案落成可派工的設計:新套件 jedi-notification-center 負責事件型錄、收件匣、個人設定、路由與摘要;既有 jedi-notification 維持純投遞;主系統十四個寄信點各改成一行呼叫;鈴鐺換成讀收件匣;三個新頁面(收件匣、通知設定、橫幅);三期交付,第一期就看得到東西。Agent 主控台本案不做(PM 2026-11-11 裁),套件的 port 契約保留讓日後能裝。本版列出要開哪些資料表、哪些 API,決策者過稿後才拆卡。

D1~D8 定案(2026-11-11) 新套件 jedi-notification-center;新開 5 張表、擴充 1 張既有表;主系統 8+2 條 API 三期:看得見 → 全部事件改走中心 → 即時與橫幅;Agent 主控台不做(PM 裁) 拆卡表與 Notion 卡待決策者過稿後再做 陷阱:交易信不進中心;收件人存 user_id 不存信箱;即時頻道只推訊號;橫幅沿用既有四支不另開

狀態:v1.0 定案、已開卡|日期:2026-11-11|母卡 CM-3875、子卡 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,本檔不改。

變更紀錄

日期 版本 內容
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. 需求背景與端到端

主系統今天只會在兩種情況主動提醒使用者:右上角鈴鐺裡的「指派給我的待辦任務」與「流程進到我負責的站」,以及 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 裁)。
%%{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 已讀,依連結參數跳頁
圖 1 一筆通知從發生到被看到。第 1 步是業務程式唯一要寫的那一行;第 2 到 9 步是套件的事。第一期未讀數每 60 秒輪詢,第三期改成 SocketIO 推訊號。

2. 分工概述

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

三期,每期怎麼判定完成:

  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)

八項全部於 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. 現況接入點

按元件分段,每段寫現在是什麼、本案動它哪裡、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. 詳細設計

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(業務程式呼叫的那一行)

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

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 批;三期一次開)

三期全部開卡(決策者 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. 合回後收口清單與端到端驗收

收口(不開卡,決策者與首腦做):套件發版推 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. 風險與陷阱

  • 收件人存信箱是 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. 這份文件的定位

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