# 个人客户站内通知

为个人客户增加通知入口，支持查询通知、查看未读数以及标记已读。进入首页时自动查询未读通知并弹窗展示；多条通知使用左右滑动查看，弹窗打开时第一条自动标记已读，滑动查看其他通知时立即标记对应通知已读。弹窗支持关闭。所有接口均需要登录，使用 `Bearer Token` 鉴权。

## 查询通知列表

`GET /api/c/v1/notifications`

查询当前客户可见的未过期业务通知，按创建时间和通知 ID 倒序排列。

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `page` | 否 | 页码，默认 1，范围 1～10000 |
| `page_size` | 否 | 每页数量，默认 20，范围 1～50 |
| `is_read` | 否 | 已读状态；`false` 仅查询未读，`true` 仅查询已读，不传时查询全部 |

返回：包含通知列表 `items`、当前页 `page`、每页数量 `size` 和总数 `total`。通知项包含标题、正文、类型、类别、级别、关联资源、已读状态及创建/已读时间。

## 标记单条通知已读

`PUT /api/c/v1/notifications/{id}/read`

将当前客户可见的指定通知标记为已读。通知不存在、属于其他客户或已经已读时，也返回成功，接口幂等。

返回：`{ "success": true }`

## 全部标记已读

`PUT /api/c/v1/notifications/read-all`

将当前客户可见的未过期未读业务通知全部标记为已读，重复调用幂等。

返回：`{ "updated_count": 3 }`

## 查询未读数

`GET /api/c/v1/notifications/unread-count`

查询当前客户未过期业务通知的未读数量；平台同步和系统运维通知不计入结果。

返回：`{ "count": 3, "display_count": "3" }`，数量超过 99 时 `display_count` 为 `99+`。

## 首页未读通知弹窗

- 用户进入首页后，调用 `GET /api/c/v1/notifications`，传入 `is_read=false`、`page=1`、`page_size=50`，只展示当前未读通知。
- 有多条未读通知时默认展示第一条，弹窗打开后立即调用单条已读接口标记第一条。
- 用户左右滑动切换到其他通知时，视为已查看并立即调用单条已读接口标记当前通知。
- 点击关闭图标只关闭弹窗，不会将未查看的其他通知批量标记为已读；下次进入首页仍可继续展示剩余未读通知。
- 通知的 `ref_type`、`ref_id`、`ref_key` 仅用于资源定位或展示，不直接拼接页面路由。

## 通用约定

- 所有接口均使用 `Bearer Token` 鉴权。
- 未登录、参数错误、无权访问和服务异常沿用统一错误响应。