---
title: "通知中心 SPEC 06 前端 (FR-196)"
brand: "Guidant AI · **FR-196** 通知中心"
eyebrow: "FR-196 · 定版 SPEC · 06"
h1: "06 前端"
subtitle: "鈴鐺、通知中心頁、個人通知設定頁、通知管理頁三個分頁、兩支橫幅、排定維護表單；composable、路由、能力點、i18n、SocketIO 與輪詢"
lede: "前端改動都在 `compliance-manager-fe`。紅點數全站一份（composable 內單例），鈴鐺與通知中心頁共用；主路徑是 SocketIO 訊號，輪詢只當備援。頁面全部套全站 `dark-card` 與字級，清單分段用 `SegmentButtons`，沒有左側粗色邊框。"
---

## 元件與頁面 {#components nav="元件"}

| 檔 | 做什麼 |
|---|---|
| `src/layout/NotificationBell.vue` | 右上角鈴鐺：紅點＝`unread`；寬 34rem 的下拉，只放未讀（`/inbox/recent?unread_only=true`，標已讀後該筆離開下拉）：標題＋未讀 Tag＋「全部標為已讀」、類別分段（全部／任務／專案／掃描／系統／公告）、最近十筆未讀（圖示、標題、摘要、相對時間、`merged_count>1` 顯示「有 N 項更新」）、底部「查看全部通知」「個人通知設定」、最底一行「我的待辦任務（todo）」連 `my-tasks`（不計進紅點） |
| `src/views/notification/NotificationInboxView.vue` | 通知中心頁（路由 `/notification`）：工具列未讀／已讀／全部／已封存四段分段、類別 Dropdown（選項讀 `system_menus` `NOTIFICATION_CATEGORY`）、搜尋；清單是 `DataTable` 表格（勾選、類別、通知、時間、操作五欄）；每列前往、標已讀、封存，已讀分段的批次動作改為「標為未讀」；勾選批次標已讀與封存；空狀態依狀態顯示不同文案 |
| `src/views/notification/NotificationSettingsView.vue`＋`NotificationSettingRow.vue` | 個人通知設定頁（頁名「個人通知設定」，路由 `/user/notification-settings`，從右上角使用者選單進），上下兩張同樣式的卡，標題在卡內左上、說明一律收進標題後的 (i)（hover 顯示），頁面沒有常駐說明文字。**Email 通知模式**：單選「即時寄送／每日彙整／每週彙整」；勿擾時段只掛在「即時寄送」底下（`daily`／`weekly` 不看勿擾，並列會讓人以為可混用），是開關，開了才出兩個 `Calendar timeOnly`，關掉清空兩端（兩端同填同空）。**通知開關**：每個類別一個分頁，分頁列與表格合成同一張卡；每行站內、Email 兩個 `InputSwitch`，沒有聊天欄；必收那行兩格 `disabled`、鎖頭 icon 配 tooltip、「必收」Tag，是否必收讀 `GET /settings` 的租戶生效值。儲存 `:loading`，412 走 error-code toast |
| `src/views/notify-config/NotifyConfigForm.vue`＋`src/components/notification/TenantEventRuleList.vue` | 通知管理頁（`/system/notify-config`，守門 `system.notify-config.read`／`update`）有 Telegram、Discord、必收事件、排定維護四個分頁。Discord 與 Telegram 分頁在連線設定卡下方各有一張「推送的事件」卡，必收事件分頁一張卡，三張共用 `TenantEventRuleList`：一列一事件（名稱加灰字「什麼時候會發」）、類別分組標題帶「已選／總數」、右側開關；欄寬沿用個人設定頁同名的 `--settings-cols`，兩頁開關欄對齊。頻道未啟用時卡內上方一則 Message 提示勾了也不推。必收事件分頁多一欄「原廠建議」（✓ 或 —）與右上「恢復原廠建議」，後者只改畫面、要按儲存才生效。儲存與恢復按鈕 `v-can="CAP.SYSTEM_NOTIFY_CONFIG_UPDATE"`，授權唯讀時反灰；離開頁面的未存確認也計入規則清單 |
| `src/components/system/MaintenanceBanner.vue` | 頁頂橫幅：讀 `/maintenance/current`，有就顯示開始時間與長度；關閉記 `sessionStorage`（鍵含維護 id），收件匣那筆照留 |
| `src/components/product-update/NewVersionBanner.vue` | 「有新版」橫幅從儀表板移到頁頂那排；只給平台管理員（`v-if="userStore.isPlatformAdmin" v-can="CAP.SYSTEM_PRODUCT_UPDATE_READ"`） |
| `src/views/system-config/MaintenanceScheduleForm.vue` | 系統設定「排定維護」小表單：開始時間、長度、訊息；`v-can` `notification.banner.publish` |
| `src/layout/AppLayout.vue` | 橫幅那排：`LicenseExpiryBanner`、`FileProtectionOffBanner`、`NewVersionBanner`、`MaintenanceBanner`（Agent 離線、AI 額度另有既有元件） |
| `src/layout/AppTopbar.vue` | 鈴鐺整段換成 `<NotificationBell/>`；使用者選單多「個人通知設定」；舊的待辦清單、流程進站清單與 `TopbarStageQueue.vue` 已移除 |

## composable {#composables nav="composable"}

**`useNotificationCenter.js`** 是全站單例：`unread`、`todo`、`recent` 三個 ref，`refresh()` 打 `unread-count`，另有 `loadRecent(category)`、`markRead(uid)`、`markAllRead()`。用引用計數：第一個掛載的元件開 SocketIO 連線與輪詢，最後一個卸載的清掉，同時只有一條連線一個 timer。

**`useNotificationInbox.js`** 給通知中心頁：`filters`（state、category、keyword）、分頁、`DataTable` 勾選（列物件陣列）、`runBatch(action)`；標已讀與封存後呼叫 `useNotificationCenter().refresh()` 讓紅點同步。另匯出 `useNotificationText()`（`textOf`／`agoText`）與 `CATEGORY_ICONS`，鈴鐺和通知中心頁共用。

**`useNotificationSettings.js`** 給個人設定頁：GET 後依類別分組；PUT 前只留 `code`、`inapp`、`email` 三欄與 profile 五欄（多給的鍵後端回 400）；時間欄位在 `Date` 與 `HH:MM` 之間轉換。

**`useTenantNotificationRules.js`** 給通知管理頁：`GET /admin/tenant-rules` 一次，三個分頁共用同一份實例。`PUT` 是全表覆寫，所以每個分頁儲存時只用「本分頁的欄位」的畫面值、其他欄位用伺服器值送出，存完套回時保留其他分頁還沒存的畫面改動；否則在 Discord 分頁按儲存會順便把必收分頁尚未確認的改動一起送出。

## 即時與輪詢 {#realtime nav="即時與輪詢"}

`useNotificationCenter.js`：`io(API.SOCKET_NOTIFICATION_CENTER, {auth: {token}})` 連 `/socket/notification-center`；收 `unread_changed` → `refresh()`。連上時輪詢退到每 5 分鐘補漏；連不上（斷網、socketio 程序沒開）退回每 60 秒。卸載時斷線。`socketio` 模式沒跑時功能照常，只是紅點最慢一分鐘更新。

## 路由、能力點、API 常數 {#config nav="路由與常數"}

| 項 | 值 |
|---|---|
| 路由 | `/notification`（name `notification-inbox`）；`/user/notification-settings`（name `notification-settings`）；系統設定的通知頁是 `/system/notify-config`（name `notify-config`，頁名「通知管理」）；沒有 `/home` 路由，型錄 `link_route` 為空的事件點了不跳頁 |
| 能力點（`capabilities.js`） | `NOTIFICATION_INBOX_READ: 'notification.inbox.read'`、`NOTIFICATION_BANNER_PUBLISH: 'notification.banner.publish'` |
| API 常數（`api.js`） | `NOTIFICATION_CENTER_UNREAD_COUNT`、`_INBOX_LIST`、`_INBOX_RECENT`、`_INBOX_ITEM`（＋`/<uid>/read`、`/archive`）、`_INBOX_BATCH`、`_SETTINGS`、`_MAINTENANCE`、`_MAINTENANCE_CURRENT`、`_ADMIN_TENANT_RULES`、`SOCKET_NOTIFICATION_CENTER` |
| 移除 | `STAGE_NOTIFICATIONS_MINE` |

通知點「前往」用 `link.route` 與 `link.params` 做 `router.push`，先 PATCH 已讀再跳。

## i18n {#i18n nav="i18n"}

| 檔（zh-tw、en 各一） | 內容 |
|---|---|
| `notification-center.json` | 頁名、工具列、空狀態、設定頁文案、`tenant_rules.*`（三個清單卡的文案與 25 個事件的「什麼時候會發」）、`categories.<key>` 五類、`events.<類別>.<事件>.title`／`.summary` |
| `notification-inbox.json` | 通知中心頁專用 |
| `menu.json` | 「通知中心」「個人通知設定」兩頁名；系統設定那頁（`/system/notify-config`）名「通知管理」 |
| `error-code.json` | `NC_404001`、`NC_412001`、`NC_400001`、`NC_403001` |
| `options.json` | 摘要三選項 |

兩種語言鍵數相同，守衛會比。

## UI 規範自檢 {#rules nav="UI 規範"}

- 禁左側粗色邊框：`grep -rn border-left src/layout/NotificationBell.vue src/views/notification src/views/user-manage/NotificationSetting* src/components/system` 為 0。
- 不自訂字級、字型、紙面版面；卡片 `dark-card`；分段 `SegmentButtons`（small）。
- icon-only 按鈕配 `v-tooltip`；async 呼叫配 `:loading`。
- 文案全部來自 i18n 檔，不從雛形複製。

## 驗收動作 {#acceptance nav="驗收"}

1. 指派一張任務給自己：一分鐘內（socketio 開著時三秒內）鈴鐺紅點出現；點開看到那筆；點進去到任務頁；回來那筆變已讀、紅點少一。
2. 通知中心頁切「未讀」只剩未讀；類別篩選、搜尋有效；勾兩筆批次封存後切「已封存」看得到。
3. 個人通知設定頁關掉「新任務指派給我」的 Email，請人指派一張：站內有、信箱沒有；「掃描新增嚴重弱點」那行鎖住點不動；頁上沒有聊天欄。
4. 通知管理 › 必收事件取消「授權即將到期」並儲存：個人設定頁該列鎖頭消失、Email 關得掉；按「恢復原廠建議」九個勾回來，儲存後九個鎖回來。
5. 通知管理 › Discord 分頁啟用頻道、勾「新任務指派給我」並儲存，指派任務後外送表出現 `chat:discord` 一列；Telegram 分頁沒勾就沒有 `chat:telegram` 列。
6. 管理員建一筆明天的排定維護：全員頁頂出現橫幅，關掉後重整不再出現，收件匣仍有那筆。
