---
title: "通知中心 SPEC 03 API (FR-196)"
brand: "Guidant AI · **FR-196** 通知中心"
eyebrow: "FR-196 · 定版 SPEC · 03"
h1: "03 API"
subtitle: "套件掛的 8 條＋租戶規則 2 條、主系統的 2 條；請求與回應欄位、錯誤碼、守門"
lede: "全部前綴 `/api/1.0/notification-center`，JWT 必帶（無 token 401）。套件八條與租戶規則兩條由 `register()` 掛成一個 blueprint，守門（要登入、要能力點）由主系統透過 adapters 給；排定維護兩條是主系統自己的 route。回應走全站信封 `{status, data, meta?}`，錯誤走 `{error_code, msg}`。"
---

## 端點一覽 {#list nav="一覽"}

| 動詞 | 路徑 | 做什麼 | 能力點 |
|---|---|---|---|
| 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` 傳入，兩個都給才掛這兩條。

## 收件匣 {#inbox nav="收件匣"}

**`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}`。

## 通知設定 {#settings nav="通知設定"}

**`GET /settings`** 回：

```json
{
  "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：

```json
{
  "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`。

## 租戶規則 {#tenant-rules nav="租戶規則"}

**`GET /admin/tenant-rules`** 回：

```json
{
  "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。

## 排定維護 {#maintenance nav="排定維護"}

**`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`。橫幅元件每次載入頁面打一次。

## 錯誤碼 {#errors nav="錯誤碼"}

套件定義、主系統 `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 | 沒有發布系統橫幅的權限 |

## 退役的端點 {#retired nav="退役"}

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