FR-196 通知中心 交接現況(STATE)

這份是 living 檔:每棒就地 Edit,只描述「此刻」。歷史脈絡看同資料夾的 FR-196-LOG.md。

項目 值
最後更新 2026-11-14(第 3 棒首腦:收尾完成;之後只處理 bug)
branch BE、FE、jedi-packages 三 repo 皆 feature/FR-172,FR-196 與 FR-196.1 工作區都已合回並 push;未合進 main
母案卡 FR-196 CM-3875 https://app.notion.com/p/FR-196-jedi-notification-center-9-4-415346da4cd081ce8637d722cdda8715 ;FR-196.1 CM-3904 https://app.notion.com/p/FR-196-1-Discord-Telegram-0-2-0-6-5-14-18-416346da4cd08105a94afc3666860fb8
子卡 兩案全部子卡 Done(決策者收);收尾文件卡 CM-3937(FR-196.1.D-2,批 19)Not started,待工作坊派
套件 jedi-notification-center 0.2.0 已發 Nexus,主系統釘 ==0.2.0(從 site-packages 載入,不再走本機 .pth)
本棒角色 首腦(收尾+交接);之後的 bug 另開 session,接手讀本檔
Notion 回寫規範 docs/claude/notion-issue-tracker.md
接手前必讀 §0 讀序

🧭 原始需求 / WHY

這節寫一次,之後各棒不動。

  • 決策者原話(2026-11-11):「我們現在主系統的通知功能幾乎是半殘,只有任務的通知會顯示在右上角的工具列上面,這跟一般系統的通知中心差太多了。像是公告、系統通知、任務通知、更新通知等等還有很多其他我沒想到的,目前都只有透過 email 或是根本沒有通知。這對一個產品系統來說根本不及格。希望評估設計一下,依照現在外面成熟的產品的通知中心模式,最好是可以模組化,未來讓其他產品可以接上用,或是到時候可以先拔去 Agent 使用。」
  • 需求的演變:PM 2026-11-11 裁 Agent 主控台本案不做(原第四期拿掉,套件接口保留);決策者先裁分批開卡,隨後改三期一次開;收尾不開卡只開開發卡、半夜無人值守跑。
  • 目標模型:業務程式只呼叫一行 notify();新套件 jedi-notification-center 管型錄、收件匣、個人設定、外送決策(立即、摘要、勿擾)、合併、即時訊號;主系統用八張接口接既有名冊、範本、投遞、排程;前端鈴鐺變收件匣入口、通知中心頁、一頁通知設定(25 事件全部展開、9 個必收鎖住)、頁頂橫幅沿用既有那排補兩支。
  • 本棒在大圖的位置:討論稿 → 設計 → 22 張卡開完 → 工作坊一夜跑完 → 首腦實質驗收通過 → 定版 SPEC 八頁回寫 → 三 repo 合回 → 決策者手測 → 第 2 棒:手測回饋裁示定案、首腦直接改個人通知設定頁、開五張修正卡(批 11~13);FR-196.1(租戶層通知管理)裁示定案但設計與雛形未做。第 3 棒:FR-196.1 討論稿 v2、雛形兩份(第一版被退重做)、design v1.0、cards.py、母卡 CM-3904+六子卡 CM-3905~3910(批 14~18)。第 3 棒收尾:合回、套件 0.2.0 發版、主系統改釘、出貨基線重產、push、SUMMARY 與 analysis。現在是「已交付,之後只修 bug」。

§0 接手讀序

0.1 🔒 先懂需求 gate

  1. 本檔 🧭 WHY
  2. handoff/2026-11-14-FR-196-SUMMARY.md(交付了什麼、行為差異、已知待辦)
  3. FINAL-SPEC.md 與 spec/01~07(規格現況);FR-196.1 看 docs/features/FR-196.1-2611-tenant-notification-management/FINAL-SPEC.md
  4. docs/analysis/2026-11-14-notification-center-design-decisions.md(為什麼這樣設計、收尾抓到的兩個根因)
  5. 本檔 §2 已定裁示——不要重新討論

0.2 現況與待辦

  1. 本檔 §1、§3、§4
  2. FR-196-LOG.md 最後一個 block

0.3 修 bug 時常開的

  • 事件從哪裡發:spec/05 呼叫點表;套件行為:spec/04;排障:spec/07 排障表
  • 規則只在一處算:套件 domain/entities/notification_event.py 的 effective_channels()/effective_mandatory(),發通知、個人設定存檔、摘要寄前複查三處共用
  • 前端:鈴鐺 src/layout/NotificationBell.vue+useNotificationCenter.js;通知中心頁 src/views/notification/NotificationInboxView.vue+useNotificationInbox.js;個人頁 src/views/user-manage/NotificationSettingsView.vue;通知管理頁 src/views/notify-config/NotifyConfigForm.vue+src/components/notification/TenantEventRuleList.vue

0.4 ✅ 冷接自檢

  1. 通知為什麼做成獨立套件,不擴充 jedi-notification?(純投遞層,加進去會把「怎麼送」和「該不該送」綁死;交易信不進中心)
  2. 必收由誰決定?沒存過的租戶怎麼算?(租戶管理員在通知管理 › 必收事件決定;沒有列就照型錄的原廠建議 9 個)
  3. Discord/Telegram 推送為什麼不在個人設定?(群組是租戶公頻,一則推一次;改由管理員在兩個頻道分頁各勾一份)
  4. 改套件後主系統怎麼吃到?(套件已發版、主系統釘 0.2.0;改套件要走 path dependency 開發、發新版、改釘,見 jedi-package-dev skill)
  5. 頁面卡在「載入中」先看什麼?(瀏覽器主控台的完整錯誤堆疊;本案就是鈴鐺 badge 拋錯中斷整輪重繪)

§1 當前狀態(2026-11-14 實查)

git:三 repo 都在 feature/FR-172、working tree 乾淨、已全部 push。BE HEAD 至少到收尾 commit(SUMMARY/analysis/STATE/LOG);FE beaaba5c(通知管理頁與個人頁統一);套件 cea10649。

套件:jedi-notification-center 0.2.0 在 Nexus;主系統 pyproject.toml 釘 ==0.2.0,import jedi_notification_center 來自 .venv/.../site-packages。

出貨基線:188 基線庫已補套通知中心結構與 seed,scripts/init/02/04/99 重產(BE b4d8247fe);本機乾淨 init+migrate 驗證通過;test_plugin_capabilities_are_seeded 已轉綠。

DEV DB:FR-196、FR-196.1 全部 migration 已套;租戶規則表 notification_tenant_event_rules 0 列(沒人存過,照型錄走)。

服務:8000/8002/5180 在跑(2026-11-14 重啟過,吃釘版 0.2.0)。

Notion:兩案子卡全 Done;母卡 CM-3875、CM-3904 收尾時改 Done;收尾文件卡 CM-3937 Not started(批 19)。

§2 已定裁示(不要重新討論)

  • D1 鈴鐺只放通知;底部一行「我的待辦任務(N)」不計紅點(2026-11-11)。
  • D2+D3 一頁通知設定、事件全部展開各一行、不做類別總開關;必收名單出貨寫死、不做租戶管理頁(2026-11-11,決策者追問兩輪後定)。
  • D4 已讀/封存 90 天清、投遞紀錄 180 天、未讀永留;D5 即時放第三期;D6 Discord/Telegram 維持租戶頻道(可再議);D7 Agent 端收件匣不做(PM 裁);D8 新套件、交易信不進中心(2026-11-11)。
  • 重複設計盤點四處沿用:橫幅用既有四支補兩支、投遞紀錄擴 FR-137 表、去重靠合併鍵、設定頁另開路由(2026-11-11)。
  • 只開開發卡,驗收與收口由決策者與首腦做(2026-11-11)。

2026-11-12 決策者手測後裁示(第 2 棒,全部定案,不要重問):

  • 排定維護、原廠回覆兩個事件點了不跳頁;Agent 更新失敗/完成改連更新中心(product-update);已寫入收件匣的舊通知連結一起修。→ R-1
  • 鈴鐺下拉只放未讀;通知中心頁改表格;分段改未讀/已讀/全部/已封存。→ R-2、R-3
  • 必收事件的 Email 一律立即寄出,不受每日/每週彙整與勿擾時段延後(套件目前相反,且有測試驗舊行為)。→ R-4
  • 舊路由 /home 刪掉(2024-12 起無人導向,實際渲染合規資源庫,FR-196 型錄被它的名字誤導;登入與麵包屑首頁都是 /project/dashboard)。→ R-1(DB 登記)+R-3(FE 路由)
  • 系統設定的「通知設定」頁改名「通知管理」;使用者選單那頁叫「個人通知設定」(FE 已改)。
  • 個人通知設定頁版面:「Email 通知模式」(單選:即時寄送/每日彙整/每週彙整;勿擾時段只掛在即時寄送底下)+「通知開關」(類別分頁);說明一律收進標題後 (i);文案正式用語。已做並 commit(FE 99aed6b6),決策者看過。
  • FR-196.1 租戶層通知管理(推翻 D3「不做租戶管理頁」):
    • Discord/Telegram 推送不再是個人設定:個人頁拿掉那一欄。系統設定 › 通知管理的 Discord 分頁與 Telegram 分頁各加一份「推送的事件」勾選清單(決策者選 B,不是固定 4 個),預設勾出貨型錄 default_chat=true 的 4 個(task.assigned、task.batch_assigned、task.batch_completed、project.started);分頁沒啟用就不推。
    • 必收名單改由管理員設定:系統設定 › 通知管理新增「必收事件」分頁,25 個事件各一個勾選,原廠建議的 9 個預設勾選並標示「原廠建議」;管理員可以取消原廠的 9 個;勾了的事件全租戶站內與 Email 關不掉。
    • 不做:管理員整個關掉某事件(全租戶不發)——先不做。
  • 圖表規範:mermaid 字 18px、不縮、固定淺底、可點放大、頁不鎖窄欄;Artifact 自載 mermaid(2026-11-11,已進 memory 與 skill)。

§3 下一步

⚠️ 建議清單,不是執行授權。接手方盤點完即停,等決策者發令。

本案已交付。之後的工作只有三類:

  1. 修 bug:決策者另開 session 回報。先照 §0 讀序冷接,看 §0.3 的檔案座標,根因查到判定那一行再修;改到套件要走發版流程。
  2. CM-3937 收尾文件卡驗收:工作坊派完後,照 closing-and-handoff 首腦驗收側驗 SPEC 三頁與使用手冊(mkdocs build --strict、表名對 db_schema、手冊無程式名詞)。
  3. 上線:決策者決定合進 main、上 STG/POC 時,走 version-bump skill 與 sql-migration skill 的上版段;STG/POC 未經放行一律不動。

§4 待辦與風險

  • 頻道啟用時的真機推送沒驗過(事實):套件測試有涵蓋「兩頻道各推一次、只勾一邊只推一邊」,但畫面與真機都還沒填測試 webhook 驗。有人回報群組沒收到時,先查 compliance.task_alert_notifications 有沒有 chat:discord/chat:telegram 列與 result。
  • 共用 venv 的 jedi-license-runtime 是 1.1.8,本線釘 1.1.7(事實):1.1.8 屬 FR-197.1(CM-3924)尚未合回。任何人跑 poetry update/install 會被降回 1.1.7;已在 CM-3924 卡上提醒合回時改釘。
  • 兩個不屬於本案的工作區未合回(事實):BE ws-CM-3546-CM-3558(FR-179)、FE ws-CM-3820-CM-3844(FR-194),各差 1 筆。
  • test_fr132_split_capability_grants 兩條紅(事實,M-1 起就有):通知中心兩顆能力點沒分類進 FR-132 的 split-capability-grants.md;補兩列即可。
  • 掃描警示仍對 SSP Party 聯絡人直寄(已判定合理):有帳號參與者已排除,不會收兩封。
  • socketio 模式沒起時紅點最慢 60 秒(設計如此)。
  • 鈴鐺 badge 不可加 :key(陷阱):加了未讀數一變就拋錯、整輪畫面停住;註解已寫在 NotificationBell.vue。

§5 Pre-flight

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current; git status --short | grep -v '^??'; git log --oneline -1
for p in 8000 8002 5180; do echo "$p: $(lsof -nP -iTCP:$p -sTCP:LISTEN -t | head -1)"; done
.venv/bin/python -c "import jedi_notification_center as m, importlib.metadata as md; print(m.__file__, md.version('jedi-notification-center'))"   # site-packages、0.2.0
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/api/1.0/notification-center/unread-count   # 401
tail -50 log/app.log | grep -i "traceback\|notification" | tail -5
# DEV 查現況一律 cmmgr(密碼同 .env 的 DB_PASSWORD);cm_app 受 RLS 看不到

§6 環境座標

  • DEV DB:本機 localhost:5432/guidant_ai_dev,查表用 cmmgr(密碼查 .env DB_PASSWORD);.env 的 DB_USER 是 cm_app。
  • BE log:log/app.log;重啟時的啟動輸出 log/restart-api.out、log/restart-socketio.out。
  • 套件源碼:~/Projects/Jedicogy/module/jedi-python-package/jedi-notification-center/(自己的 venv:env -u VIRTUAL_ENV poetry run pytest tests/ -q)。
  • FE:~/Projects/Billows/Audit-Manager/compliance-manager-fe/,npm run dev(5180)、npm run build:DEV。
  • FR 文件站:docs/features/FR-196-2611-notification-center/,python scripts/deliverables/render_index.py docs/features/FR-196-2611-notification-center/;本機看:cd docs/features && python3 -m http.server 8124。
  • 測試帳號:blsadmin(密碼見 test repo .env.e2e TEST_PASSWORD);登入 body 欄位是 username/password。

§7 行為規範提醒

  • 首腦不開 subagent;實作卡開 Notion 卡交工作坊;驗收實打端點不信回寫。
  • 收尾等令;push 常態授權但不推 main、不 force、推前 fetch。
  • 開發只動 DEV,不碰 STG/POC。
  • 補卡照 .claude/rules/workshop.md 六條;卡上分岔定死,半夜無人值守。
  • 文件只寫現況,沿革進 LOG 與 commit;圖表規範見 memory feedback_diagram_font_18px_no_shrink_fixed_light。