FR-196.1 · 設計 v1.0(定稿)· 2026-11-12

設計 v1.0(定稿):租戶層通知管理

必收事件與群組推送改由租戶管理員決定;6 張開發卡、5 批(批 14~18)

🔴 這份是設計決策,不是現況。 內文的數字與待辦停在 2026-11-12 定稿當時,之後實作的改動不回頭改寫這裡;現況看 FR-196 定版 SPEC(本案 D-1 卡會把 spec/01~06 改成新現況)與本案 FINAL-SPEC.md。討論與六項決策的來龍去脈在 discussion.md。

D1~D6 定案 2026-11-12 6 張開發卡、5 批、三 repo 前置:FR-196 修正卡 R-2/R-3/R-4 合回 雛形:prototype/walkthrough.html

變更紀錄

日期 版本 內容
2026-11-12 v1.0 定稿。六項決策定案、6 張卡 5 批

1. 概述

FR-196 通知中心上線後決策者手測,裁示兩件事從「每個人自己決定」改成「租戶管理員決定」:哪些事件要推到租戶的 Discord 與 Telegram 群組、哪些事件是必收(全租戶站內與 Email 關不掉)。本案交付:套件 jedi-notification-center 0.2.0 多一張租戶規則表與兩條管理端點;主系統系統設定 › 通知管理頁的 Discord、Telegram 分頁各加一份「推送的事件」清單、新增「必收事件」分頁;個人通知設定頁拿掉 Discord/Telegram 欄。

設計目標:

  1. 規則只在一處算:套件既有的 effective_channels() 加租戶規則,notify、個人設定頁、摘要寄前複查三處自然一致。
  2. 舊客戶升級後行為不變:租戶沒存過規則就照出貨型錄,管理員存過一次才開始照自己的。
  3. 群組推送每個頻道各自判斷、各自一列外送紀錄、一個失敗不影響另一個。
  4. 不新增能力點:管理端點沿用通知管理頁既有的 system.notify-config.read/update。

不在範圍:管理員整個關掉某事件(全租戶都不發)、發送量與投遞紀錄管理頁、Discord/Telegram 個人綁定、排定維護分頁的任何改動。

2. 背景

FR-196 D3 裁「必收名單出貨寫死、不做租戶管理頁」,決策者 2026-11-12 手測後推翻:當初就講過必收要給管理員改。同日手測也發現個人通知設定頁的 Discord/Telegram 欄沒有意義:那兩個是租戶公頻,一則事件推一次,收件人裡任何一人勾了就推。

現況(程式碼與 DEV 實查,2026-11-12):

  • 套件型錄 notification_events 的 mandatory 欄標了九個必收;default_chat 標了四個預設推群組。effective_channels() 拿型錄預設與個人設定算三個管道的生效值,必收強制站內與 Email 為開。
  • 個人設定表 notification_user_settings 每人每事件一列,三個布林欄 inapp、email、chat。
  • notify() 對整則事件只呼叫一次主系統 send_chat(None, 文字),主系統把 Discord 與 Telegram 都推一遍;外送佇列(FR-137 表)為這一則寫一列,收件人欄固定字 chat。表的唯一索引是「事件、主題、階段、收件人」。
  • 租戶的 Discord webhook、Telegram bot 與 chat id 存 system_configs 群組 NOTIFY_CONFIG,各有 enabled;通知管理頁(路由 notify-config)讀寫它,守門 system.notify-config.read/update,Administrator、Billows Admin、Billows 系統管理員三個角色持有。
  • 修正卡 R-4(FR-196 批 12)要讓必收事件的 Email 當場寄,判斷用型錄 mandatory。

3. 需求

3.1 功能需求

  • R1 通知管理頁 Discord 分頁與 Telegram 分頁各有一份 25 個事件的勾選清單,決定該事件發生時要不要推到該頻道;兩份可以不同。
  • R2 R1 的預設值=出貨型錄 default_chat 為真的四個事件(任務指派、批次指派、批次完成、專案啟動)。
  • R3 頻道 enabled 未開時,勾了也不推;開了自下一則事件起生效,不補推。
  • R4 通知管理頁新增「必收事件」分頁,25 個事件各一個開關;勾了的事件全租戶所有人的站內與 Email 無法關閉,且 Email 當場寄(與 R-4 一致)。
  • R5 R4 的預設值=原廠建議的九個,畫面上獨立一欄標示「原廠建議」;管理員可取消建議的、可勾非建議的;一顆「恢復原廠建議」把開關回到建議值(仍要儲存)。
  • R6 個人通知設定頁拿掉 Discord/Telegram 欄與「租戶尚未設定」提示;必收的鎖與標籤改讀租戶生效值。
  • R7 租戶沒存過規則時,所有行為與升級前相同。
  • R8 之後版本新增的事件,租戶沒有列的照型錄預設。
  • R9 管理端讀寫只有持 system.notify-config.read/update 的人能用;一般使用者 403。

3.2 限制條件

  • 套件 jedi-notification-center 不認識主系統任何表、任何路由、任何投遞實作(FR-196 D8 與套件 domain/ports.py 檔頭)。
  • 外送佇列是 FR-137 既有表,唯一索引「事件、主題、階段、收件人」不改(FR-196 重複設計盤點沿用)。
  • 套件 0.1.0 尚未推 Nexus;0.2.0 與 0.1.0 一起在收口發版。主系統 BE venv 目前用 .pth 指套件主資料夾,pyproject 沒釘這支。
  • FR-196 修正卡 R-2(套件)、R-4(套件)、R-3(FE 改名通知管理、動同一支 i18n)尚在批 11~12,本案批 14 之前要先合回。

4. 方案比較

4.1 租戶規則存哪

問題:每租戶每事件的「必收、推 Discord、推 Telegram」三個值要存在套件自己的新表,還是主系統通用設定表 system_configs 的一包 JSON。

候選方案:套件新表,每租戶每事件一列,外鍵到型錄、套 RLS,套件規則直接讀。主系統 system_configs 一包 JSON,不建表,但套件讀不到,要多一張接口讓主系統把 JSON 翻給套件,其他產品要各自實作;查一個事件得整包讀出來找;JSON 裡的事件代碼沒外鍵擋。

決定:套件新表 notification_tenant_event_rules。

理由:規則屬於通知中心的領域(限制條件第一條),放套件才是一份真相;JSON 方案等於資料在主系統、用它的邏輯在套件,中間靠翻譯程式串,是兩套。FR-196 的個人設定表就是同一個形狀,兩張表讀法一樣。前提改變(例如套件要支援沒有 RLS 生態的宿主)時 JSON 方案不會變得更好,仍是接口問題。

4.2 兩個頻道在表裡怎麼寫

問題:固定兩個布林欄 chat_discord、chat_telegram,還是一欄存頻道代號清單讓套件不認識頻道名。

候選方案:固定兩欄最直接,但套件程式從此寫死 Discord、Telegram 兩個名字,是套件第一個認識產品名詞的地方。代號清單要主系統接線時回「有哪些頻道、各自啟用沒」,套件與表不認識名字,日後加頻道只動主系統。

決定:固定兩欄。

理由:決策者追問後確認兩案畫面與功能完全相同,只差程式內部形狀;一個租戶每種頻道只有一組連線設定、短期不會加第三種,取最直接的寫法。若日後要加第三種頻道,屆時改成清單並搬資料,成本是一支 migration。

4.3 個人設定表的 chat 欄

問題:拿掉還是留著不用。

決定:拿掉。套件 003 migration DROP COLUMN,主線同步一支;個人設定 API 的請求與回應同步拿掉 chat。

理由:半套遷移留死欄是本專案踩過的坑(memory:狀態欄位半套遷移=死欄);既有值是個人聊天偏好,本案之後沒有語意,刪了不影響功能;套件還沒發版,併進 0.2.0 不多一次升級路徑。

4.4 管理端 API 放哪、守門用什麼

問題:讀寫租戶規則的端點放套件還是主系統;守門新開能力點還是沿用。

決定:端點放套件(GET/PUT /notification-center/admin/tenant-rules),守門能力點名由主系統掛載時經 config 傳入,傳 system.notify-config.read/update;config 沒給就不掛這兩條。

理由:規則表與生效邏輯都在套件,端點跟著放,其他產品一起拿到;放主系統要跨層動套件的表。新開能力點要 seed、角色授權、權限樹與選單兩種語言,新裝機器漏一處就永遠 403(守衛測試 test_plugin_capabilities_are_seeded 存在的理由);通知管理頁既有兩顆已被三個管理員角色持有、頁面已登記、同頁其他分頁就是用它守,沿用零風險。

4.5 型錄 mandatory 欄的語意

決定:欄不動,語意改為「原廠建議」;SPEC 與欄位 COMMENT 改字。畫面「原廠建議」欄讀它,生效與否看租戶表;型錄 enabled 仍是出貨工具不給 UI。

理由:新事件隨版本登記時照舊在型錄標建議,租戶沒有列就自動採用建議(R8);改名或另存建議值要搬資料,沒有換來任何好處。

4.6 收件匣已寫入的「必收」標籤

決定:不同步。收件匣每列寫入時複製的 mandatory 記的是「寄出當時是必收」,與投遞紀錄同一性質;未讀數、鎖定、Email 強制都看即時規則。SPEC 寫明。

5. 決策摘要

六項全部 2026-11-12 定案,理由在第 4 節。

編號 題目 定案 對應需求
D1 租戶規則存哪 套件新表 notification_tenant_event_rules R1、R4、R7
D2 兩個頻道怎麼存 固定兩欄 chat_discord、chat_telegram R1
D3 個人設定表 chat 欄 拿掉,套件 003 與主線各一支 migration R6
D4 管理端 API 與守門 放套件;守門用 system.notify-config.read/update,由主系統經 config 傳入 R9
D5 型錄 mandatory 語意 不動欄位,語意改「原廠建議」 R5、R8
D6 收件匣舊標籤 不同步,當歷史 無

6. 架構設計

6.1 一則事件怎麼決定送到哪

%%{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 R as notification_tenant_event_rules
  participant U as notification_user_settings
  participant H as 主系統(頻道設定、投遞)
  B->>C: notify(事件, 收件人, 主題, 參數)
  C->>C: 查型錄(類別、原廠建議必收、預設管道)
  C->>R: 查這個租戶對這個事件的規則
  C->>U: 查每位收件人的站內/Email 設定
  C->>C: 每人生效值=個人設定;租戶必收則站內與 Email 強制開
  C->>C: 寫收件匣;Email 照個人彙整/勿擾排期,租戶必收則當場寄
  C->>H: chat_channels_provider():{discord: 啟用?, telegram: 啟用?}
  loop 每個「租戶勾選且啟用」的頻道
    C->>H: 外送佇列寫一列(收件人 chat:<頻道>)→ send_chat(<頻道>, 文字)
  end
  C-->>B: 回寫進收件匣的列數
圖 1 加入租戶規則後的 notify()。第 3 步是本案新增的查詢;第 5 步必收看租戶生效值;第 7~8 步群組推送每個頻道各自判斷、各自一列外送。第 3 步查不到列就用型錄(R7、R8)。

生效值仍只在 effective_channels() 這一條算(加 tenant_rule 參數);個人設定頁的 412、摘要信寄前的 _still_wanted 都呼叫它,所以自然跟著變。R-4 在 _plan_email 加的「必收當場寄」判斷,本案在同一行把型錄欄換成生效值,不另開分支。

6.2 資料設計

新表 notification_tenant_event_rules(套件 003 migration 建;主線同步一支;RLS 與 GRANT 照套件 002 的形狀)

欄位 型別 說明
tenant_id integer 與 event_code 複合主鍵;外鍵 tenants(宿主生態存在時)
event_code varchar(64) 外鍵 notification_events.code
mandatory boolean not null 租戶是否列為必收
chat_discord boolean not null default false 推到租戶的 Discord 頻道
chat_telegram boolean not null default false 推到租戶的 Telegram 頻道
updated_at、updated_user timestamptz、varchar(50) 最後改的人與時間

cm_app 權限 SELECT/INSERT/UPDATE/DELETE(PUT 全表覆寫要刪)。沒有列=照型錄:mandatory 取型錄 mandatory,兩個 chat 欄取型錄 default_chat。

既有表改動:notification_user_settings 刪 chat 欄;notification_events.mandatory 的 COMMENT 改「原廠建議必收;生效與否看租戶規則表」。

外送佇列(FR-137 表,不改結構):群組推送的 recipient_email 從固定字 chat 改為 chat:discord/chat:telegram,唯一索引才不會把兩個頻道當重複。讀回時 chat 與 chat: 開頭都視為聊天列,舊資料不壞。

6.3 API

套件新增兩條,掛在既有前綴 /api/1.0/notification-center 下,進 routing.py 的凍結清單:

  • GET /admin/tenant-rules:回 events(25 列:code、category、vendor_mandatory、mandatory、chat_discord、chat_telegram)與 channels_enabled({discord, telegram})。
  • PUT /admin/tenant-rules:body events 全表覆寫(每列 code、mandatory、chat_discord、chat_telegram);未列的事件回到型錄預設;回 GET 形狀。

守門:NotificationCenterPluginConfig 加 admin_read_capability、admin_update_capability,預設 None;兩個都給才掛這兩條。主系統傳 system.notify-config.read/update。

既有 GET/PUT /settings:請求與回應拿掉 chat;chat_available 欄保留(主系統仍可能要顯示)但個人頁不再用。

套件接口改動:NotificationCenterAdapters 加 chat_channels_provider: Callable[[], dict],回 {"discord": bool, "telegram": bool};IDeliveryGateway.send_chat(channel, text) 的 channel 改為必帶代號。

6.4 前端

三份清單共用一個元件:一列一事件、灰字一行「什麼時候會發」、類別分組標題帶「已選 / 總數」、右側開關;格線與個人通知設定頁的列元件共用同一組欄寬變數,兩頁對齊。通知管理頁 Discord、Telegram 分頁在連線設定卡下方各放一張「推送的事件」卡(自己一顆儲存;頻道未啟用時卡內上方一行 Message 提示);「必收事件」分頁一張卡,多「原廠建議」一欄(✓ 或 —)與右上「恢復原廠建議」。個人通知設定頁拿掉第三欄與提示。畫面對照 prototype/walkthrough.html 四個頁籤;文案依 i18n 重寫,雛形只定結構。

6.5 安全邊界

  • 管理端點只回當前租戶的規則;PUT 的 tenant_id 取自身分不取 body。
  • 規則表套 RLS(FOR ALL、FORCE),與其他四張 tenant-scoped 表同形。
  • 改規則不寫稽核事件(與通知管理頁其他分頁、個人設定同等級;updated_user 留誰改的)。
  • 不新開能力點,不擴大任何角色的權限面。

7. 實作規劃

6 張開發卡 5 批,批 14~18(FR-196 母卡已用到批 13)。拆卡真相源 handoff/cards.py(兩個斷言:依賴在更早的批;同批同 repo 不改同一檔),本節與 Notion 卡都從它產。只開開發卡;套件發版、改回釘版、出貨基線重產在第 8 節收口清單。

依賴脈絡:P-1 一張套件卡把規則、表、端點、拿掉 chat 全做完(同一條規則線拆開反而要多張卡等來等去);E-1 把主系統 venv 指到 P-1 的工作區、S-1 把套件 003 包進主線,兩張互不碰檔同批;M-1 接線要 import 到 0.2.0 才測得到;F-1 要 M-1 的端點;D-1 收文件。

卡 批 repo 做什麼 reuse/extend/new 依賴 model/effort
P-1 14 jedi-packages jedi-notification-center 0.2.0 extend 無 opus/high
E-1 15 main 環境卡 reuse P-1 sonnet/low
S-1 15 main 主線 migration reuse P-1 sonnet/medium
M-1 16 main 主系統接線 extend P-1、E-1、S-1 opus/medium
F-1 17 fe FE 通知管理頁 extend M-1 opus/high
D-1 18 main 定版 SPEC 與 design 對齊 extend S-1、M-1、F-1 sonnet/medium

每張卡的改哪些檔、新開檔、驗收在 cards.py 與 Notion 子卡。登記型共用檔 owner:scripts/sql/manifest.tsv=S-1;套件 routing.py/contract.py=P-1;FE api.js/notification-center.json/menu.json=F-1(本案 FE 只有一張,無撞);core/plugins/notification_center.py/_notification_center_ports.py=M-1。

前置作業(批 14 之前,首腦確認):FR-196 修正卡 R-2、R-4 合回套件 repo feature/FR-172,R-3 合回 FE;P-1 的工作區要從合回後的 HEAD 開。

8. 驗收標準與收口

端到端驗收(合回後 DEV,首腦做):

  1. 租戶 102 沒有規則列時,指派任務 → 收件匣有列、Email 照個人設定、Discord/Telegram 未啟用不推(R7)。
  2. 通知管理 › Discord 分頁填測試 webhook 並啟用,勾「你有新的任務」存檔 → 指派任務 → 外送表出現 chat:discord 一列 result=sent,Discord 頻道收到;Telegram 分頁沒勾 → 沒有 chat:telegram 列(R1、R3)。
  3. Telegram 分頁也啟用並勾同一事件 → 再指派 → 兩列各自 sent(R1)。
  4. 必收事件分頁取消「授權即將到期」存檔 → 任一使用者開個人通知設定頁,該列鎖頭消失、Email 關得掉、存檔不 412(R4、R6)。
  5. 必收事件分頁勾「有新公告」存檔 → 個人頁該列鎖住;發一則公告 → 關了 Email 的人也收到信且當場寄(R4)。
  6. 「恢復原廠建議」→ 九個勾回來 → 儲存 → 個人頁九個鎖回來(R5)。
  7. 一般使用者 token 打 GET /admin/tenant-rules 403(R9)。
  8. 個人頁沒有 Discord/Telegram 欄;PUT /settings 帶 chat 回 400(R6)。
  9. DEV 驗完把租戶 102 兩個頻道關回未啟用。

收口清單(首腦,不開卡):套件 0.2.0 與主專案補釘一起在 FR-196 收口做;主系統 venv .pth 改回主資料夾;出貨基線重產帶入 S-1;FR-196 母卡與本案母卡 Done;push。

9. 風險與未決事項

  • R-4 與本案 P-1 改同一行:R-4 在批 12、P-1 在批 14,順序有保證;但若 R-4 驗不過被退回重做,P-1 的工作區要從重做後的 HEAD 開。緩解:前置作業寫進母卡,首腦派 P-1 前核。
  • 舊外送列收件人 chat:排程撿到會照舊記失敗(聊天本來就只當場送),主系統讀回時兩種都認;不搬資料。
  • 主系統 venv 指向:E-1 改指工作區後,工作坊若清掉 .worktrees/<母卡號> 主系統會 import 失敗;收口第一步就是改回主資料夾(FR-196 同一個坑)。
  • DEV 手測要真憑證:驗收第 2、3 項要填一組測試用 Discord webhook 與 Telegram bot,驗完關掉;憑證不進任何文件。

10. 參考文件

  • discussion.md:現況盤點、六項決策的來龍去脈、邊界情境十二條。
  • prototype/walkthrough.html:四個畫面審稿版;prototype/index.html 純畫面給 runner。
  • FR-196 design §3 D1~D8、§5.2 表 5-1~5-4;FR-196 定版 SPEC。
  • 套件:jedi-notification-center/jedi_notification_center/domain/entities/notification_event.py、app/service/notify_service.py、plugin/contract.py、migrations/002。