FR-196.1 · 設計 v1.0(定稿)· 2026-11-12
必收事件與群組推送改由租戶管理員決定;6 張開發卡、5 批(批 14~18)
🔴 這份是設計決策,不是現況。 內文的數字與待辦停在 2026-11-12 定稿當時,之後實作的改動不回頭改寫這裡;現況看 FR-196 定版 SPEC(本案 D-1 卡會把 spec/01~06 改成新現況)與本案 FINAL-SPEC.md。討論與六項決策的來龍去脈在 discussion.md。
| 日期 | 版本 | 內容 |
|---|---|---|
| 2026-11-12 | v1.0 | 定稿。六項決策定案、6 張卡 5 批 |
FR-196 通知中心上線後決策者手測,裁示兩件事從「每個人自己決定」改成「租戶管理員決定」:哪些事件要推到租戶的 Discord 與 Telegram 群組、哪些事件是必收(全租戶站內與 Email 關不掉)。本案交付:套件 jedi-notification-center 0.2.0 多一張租戶規則表與兩條管理端點;主系統系統設定 › 通知管理頁的 Discord、Telegram 分頁各加一份「推送的事件」清單、新增「必收事件」分頁;個人通知設定頁拿掉 Discord/Telegram 欄。
設計目標:
effective_channels() 加租戶規則,notify、個人設定頁、摘要寄前複查三處自然一致。system.notify-config.read/update。不在範圍:管理員整個關掉某事件(全租戶都不發)、發送量與投遞紀錄管理頁、Discord/Telegram 個人綁定、排定維護分頁的任何改動。
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。表的唯一索引是「事件、主題、階段、收件人」。system_configs 群組 NOTIFY_CONFIG,各有 enabled;通知管理頁(路由 notify-config)讀寫它,守門 system.notify-config.read/update,Administrator、Billows Admin、Billows 系統管理員三個角色持有。mandatory。default_chat 為真的四個事件(任務指派、批次指派、批次完成、專案啟動)。enabled 未開時,勾了也不推;開了自下一則事件起生效,不補推。system.notify-config.read/update 的人能用;一般使用者 403。domain/ports.py 檔頭)。.pth 指套件主資料夾,pyproject 沒釘這支。問題:每租戶每事件的「必收、推 Discord、推 Telegram」三個值要存在套件自己的新表,還是主系統通用設定表 system_configs 的一包 JSON。
候選方案:套件新表,每租戶每事件一列,外鍵到型錄、套 RLS,套件規則直接讀。主系統 system_configs 一包 JSON,不建表,但套件讀不到,要多一張接口讓主系統把 JSON 翻給套件,其他產品要各自實作;查一個事件得整包讀出來找;JSON 裡的事件代碼沒外鍵擋。
決定:套件新表 notification_tenant_event_rules。
理由:規則屬於通知中心的領域(限制條件第一條),放套件才是一份真相;JSON 方案等於資料在主系統、用它的邏輯在套件,中間靠翻譯程式串,是兩套。FR-196 的個人設定表就是同一個形狀,兩張表讀法一樣。前提改變(例如套件要支援沒有 RLS 生態的宿主)時 JSON 方案不會變得更好,仍是接口問題。
問題:固定兩個布林欄 chat_discord、chat_telegram,還是一欄存頻道代號清單讓套件不認識頻道名。
候選方案:固定兩欄最直接,但套件程式從此寫死 Discord、Telegram 兩個名字,是套件第一個認識產品名詞的地方。代號清單要主系統接線時回「有哪些頻道、各自啟用沒」,套件與表不認識名字,日後加頻道只動主系統。
決定:固定兩欄。
理由:決策者追問後確認兩案畫面與功能完全相同,只差程式內部形狀;一個租戶每種頻道只有一組連線設定、短期不會加第三種,取最直接的寫法。若日後要加第三種頻道,屆時改成清單並搬資料,成本是一支 migration。
問題:拿掉還是留著不用。
決定:拿掉。套件 003 migration DROP COLUMN,主線同步一支;個人設定 API 的請求與回應同步拿掉 chat。
理由:半套遷移留死欄是本專案踩過的坑(memory:狀態欄位半套遷移=死欄);既有值是個人聊天偏好,本案之後沒有語意,刪了不影響功能;套件還沒發版,併進 0.2.0 不多一次升級路徑。
問題:讀寫租戶規則的端點放套件還是主系統;守門新開能力點還是沿用。
決定:端點放套件(GET/PUT /notification-center/admin/tenant-rules),守門能力點名由主系統掛載時經 config 傳入,傳 system.notify-config.read/update;config 沒給就不掛這兩條。
理由:規則表與生效邏輯都在套件,端點跟著放,其他產品一起拿到;放主系統要跨層動套件的表。新開能力點要 seed、角色授權、權限樹與選單兩種語言,新裝機器漏一處就永遠 403(守衛測試 test_plugin_capabilities_are_seeded 存在的理由);通知管理頁既有兩顆已被三個管理員角色持有、頁面已登記、同頁其他分頁就是用它守,沿用零風險。
決定:欄不動,語意改為「原廠建議」;SPEC 與欄位 COMMENT 改字。畫面「原廠建議」欄讀它,生效與否看租戶表;型錄 enabled 仍是出貨工具不給 UI。
理由:新事件隨版本登記時照舊在型錄標建議,租戶沒有列就自動採用建議(R8);改名或另存建議值要搬資料,沒有換來任何好處。
決定:不同步。收件匣每列寫入時複製的 mandatory 記的是「寄出當時是必收」,與投遞紀錄同一性質;未讀數、鎖定、Email 強制都看即時規則。SPEC 寫明。
六項全部 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 | 收件匣舊標籤 | 不同步,當歷史 | 無 |
%%{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: 回寫進收件匣的列數
生效值仍只在 effective_channels() 這一條算(加 tenant_rule 參數);個人設定頁的 412、摘要信寄前的 _still_wanted 都呼叫它,所以自然跟著變。R-4 在 _plan_email 加的「必收當場寄」判斷,本案在同一行把型錄欄換成生效值,不另開分支。
新表 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: 開頭都視為聊天列,舊資料不壞。
套件新增兩條,掛在既有前綴 /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 改為必帶代號。
三份清單共用一個元件:一列一事件、灰字一行「什麼時候會發」、類別分組標題帶「已選 / 總數」、右側開關;格線與個人通知設定頁的列元件共用同一組欄寬變數,兩頁對齊。通知管理頁 Discord、Telegram 分頁在連線設定卡下方各放一張「推送的事件」卡(自己一顆儲存;頻道未啟用時卡內上方一行 Message 提示);「必收事件」分頁一張卡,多「原廠建議」一欄(✓ 或 —)與右上「恢復原廠建議」。個人通知設定頁拿掉第三欄與提示。畫面對照 prototype/walkthrough.html 四個頁籤;文案依 i18n 重寫,雛形只定結構。
PUT 的 tenant_id 取自身分不取 body。updated_user 留誰改的)。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 開。
端到端驗收(合回後 DEV,首腦做):
chat:discord 一列 result=sent,Discord 頻道收到;Telegram 分頁沒勾 → 沒有 chat:telegram 列(R1、R3)。GET /admin/tenant-rules 403(R9)。PUT /settings 帶 chat 回 400(R6)。收口清單(首腦,不開卡):套件 0.2.0 與主專案補釘一起在 FR-196 收口做;主系統 venv .pth 改回主資料夾;出貨基線重產帶入 S-1;FR-196 母卡與本案母卡 Done;push。
chat:排程撿到會照舊記失敗(聊天本來就只當場送),主系統讀回時兩種都認;不搬資料。.worktrees/<母卡號> 主系統會 import 失敗;收口第一步就是改回主資料夾(FR-196 同一個坑)。prototype/index.html 純畫面給 runner。jedi-notification-center/jedi_notification_center/domain/entities/notification_event.py、app/service/notify_service.py、plugin/contract.py、migrations/002。