FR-196 · 定版 SPEC · 03

03 API

套件掛的 8 條+租戶規則 2 條、主系統的 2 條;請求與回應欄位、錯誤碼、守門

全部前綴 /api/1.0/notification-center,JWT 必帶(無 token 401)。套件八條與租戶規則兩條由 register() 掛成一個 blueprint,守門(要登入、要能力點)由主系統透過 adapters 給;排定維護兩條是主系統自己的 route。回應走全站信封 {status, data, meta?},錯誤走 {error_code, msg}。

§1

端點一覽

動詞 路徑 做什麼 能力點
GET /unread-count 鈴鐺紅點數與待辦任務數 notification.inbox.read
POST /inbox/list 收件匣分頁 同上
GET /inbox/recent 鈴鐺下拉最近十筆 同上
PATCH /inbox/<uid>/read 標已讀 同上
PATCH /inbox/<uid>/archive 封存 同上
POST /inbox/batch 批次標已讀、封存、全部標已讀 同上
GET /settings 通知設定頁資料 同上
PUT /settings 存通知設定(整表覆寫) 同上
POST /maintenance 建一筆排定維護並通知全租戶 notification.banner.publish
GET /maintenance/current 橫幅讀目前有效的維護 登入即可
GET /admin/tenant-rules 讀本租戶的必收與群組推送規則 system.notify-config.read
PUT /admin/tenant-rules 全表覆寫本租戶的規則 system.notify-config.update

notification.inbox.read 出貨 seed 給所有角色;notification.banner.publish 給 Administrator。/admin/tenant-rules 不新開能力點:守門是通知管理頁既有的 system.notify-config.read/update(Administrator、Billows Admin、Billows 系統管理員持有),能力點名由主系統掛載時經 NotificationCenterPluginConfig.admin_read_capability/admin_update_capability 傳入,兩個都給才掛這兩條。

§2

收件匣

GET /unread-count 回 {"unread": 11, "todo": 146}。unread 是未讀且未封存的筆數;todo 是「我的待辦任務」數,由主系統 todo_count_provider 接既有的 task queue 給,與紅點分開顯示。

POST /inbox/list body:

欄位 型別 說明
page、page_size integer 分頁;page_size 上限由套件常數 MAX_PAGE_SIZE 定
state unread/read/all/archived 預設 all;read 只回已讀;archived 只回封存的,其餘不含封存
category string 可空 五類之一
keyword string 可空 標題模糊比對,最長 100

回 data[]+meta(page、page_size、total、total_pages、has_next、has_prev)。每筆:

欄位 說明
uid 對外識別
event_code、category
title、summary 寫入時渲染好的文字
link {"route": "my-tasks", "params": {...}} 或 null;前端 router.push 用
mandatory 顯示「必收」標籤
merged_count 大於 1 顯示「有 N 項更新」
read_at、archived_at、created_at

GET /inbox/recent?category=&unread_only= 固定 10 筆、不含封存,形狀同上;unread_only=true 只回未讀(鈴鐺下拉用),預設回全部。

PATCH /inbox/<uid>/read、/archive 冪等;回該筆。uid 不是本人的或不存在都回 404 NC_404001,不分兩種情況。

POST /inbox/batch body:action ∈ read/archive/unread/read_all;uids[](read_all 時省略,改帶 scope ∈ all/category 與 category)。回 {"updated": N}。

§3

通知設定

GET /settings 回:

{
  "events": [{"code": "task.assigned", "category": "task", "mandatory": false,
              "inapp": true, "email": true}, "…共 25 列,依型錄 sort"],
  "profile": {"email_digest": "immediate", "digest_hour": 9, "digest_weekday": null,
              "quiet_from": null, "quiet_to": null},
  "chat_available": false
}

events 是型錄 left join 個人設定,沒設過的用預設;mandatory 是租戶生效值(套用租戶規則後),個人設定頁的鎖與「必收」標籤讀它。chat_available 由主系統 chat_available_provider 給(租戶有沒有啟用 Discord 或 Telegram),個人設定頁不再使用。

PUT /settings body 只收這些欄位,多給的鍵會 400:

{
  "events": [{"code": "task.assigned", "inapp": true, "email": false}, "…"],
  "profile": {"email_digest": "daily", "digest_hour": 9, "digest_weekday": null,
              "quiet_from": "22:00", "quiet_to": "08:00"}
}

整表覆寫;帶 chat 等未定義的鍵回 400。生效為必收的事件,inapp 或 email 為 false 回 412 NC_412001;email_digest 不在三個值內回 400 NC_400001;時間格式 HH:MM。

§4

租戶規則

GET /admin/tenant-rules 回:

{
  "events": [{"code": "task.assigned", "category": "task", "vendor_mandatory": false,
              "mandatory": false, "chat_discord": true, "chat_telegram": true}, "…共 25 列,依型錄 sort"],
  "channels_enabled": {"discord": true, "telegram": false}
}

vendor_mandatory 是型錄的原廠建議;mandatory、chat_discord、chat_telegram 是租戶生效值,沒存過規則的事件回型錄預設。channels_enabled 由主系統 chat_channels_provider 給,前端據此在頻道未啟用時提示「勾了也不推」。

PUT /admin/tenant-rules body {"events": [{"code", "mandatory", "chat_discord", "chat_telegram"}, …]},多給的鍵回 400。全表覆寫:請求有列的事件寫入,未列的事件回到型錄預設;回 GET 的形狀。tenant_id 取自登入身分、不取 body;updated_user 記登入者。只回與改當前租戶的規則,一般使用者兩條都 403。

§5

排定維護

POST /maintenance body {"starts_at": "2026-11-20T02:00:00+08:00", "duration_min": 30, "message": "…"}。寫 notification_maintenance 一筆,並發 system.maintenance_scheduled 給全租戶使用者。無能力點 403 NC_403001。回建立的那筆(含 created_user_name、ends_at)。

GET /maintenance/current 回最近一筆 starts_at + duration_min 尚未過去的;沒有回 null。橫幅元件每次載入頁面打一次。

§6

錯誤碼

套件定義、主系統 common/code/notification_center_error_code.py 轉出、FE error-code.json 中英各一條:

碼 HTTP 意思
NC_404001 404 通知不存在(含不是你的)
NC_412001 412 必收事件的站內與 Email 不可關閉
NC_400001 400 設定值不在選單內
NC_403001 403 沒有發布系統橫幅的權限
§7

退役的端點

GET /flow-engine/stage-notifications/mine(舊鈴鐺的「流程站等你接手」)已移除,連同 MyStageNotificationsQuery、MyStageNotificationsAppService、FE API.STAGE_NOTIFICATIONS_MINE。GET /flow-engine/task/queue 保留,鈴鐺底部那行待辦數用它。