100 lines
2.8 KiB
Markdown
100 lines
2.8 KiB
Markdown
# 通知系统
|
||
|
||
## 概述
|
||
|
||
支持三类通知：系统公告（广播）、个人通知（定向）、事件驱动通知。
|
||
|
||
### 数据库
|
||
|
||
`notifications` 表（迁移 `011_add_notifications.sql`）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `scope` | `'all'` / `'user'` | 广播或定向 |
|
||
| `user_id` | INTEGER / NULL | 定向时指定用户 |
|
||
| `type` | VARCHAR | 通知类型 |
|
||
| `title` | VARCHAR | 标题 |
|
||
| `content` | TEXT | 正文 |
|
||
| `priority` | `high` / `normal` / `low` | 优先级 |
|
||
| `link` | VARCHAR | 点击跳转路径 |
|
||
| `is_read` | BOOLEAN | 已读标记 |
|
||
| `created_at` | TIMESTAMPTZ | 创建时间 |
|
||
| `expires_at` | TIMESTAMPTZ | 过期时间 |
|
||
|
||
### 通知类型
|
||
|
||
| type | 触发场景 | scope |
|
||
|------|---------|-------|
|
||
| `system_maintenance` | 系统维护 | `all` |
|
||
| `version_update` | 版本更新 | `all` |
|
||
| `payment_success` | 支付成功 | `user` |
|
||
| `member_expiry_soon` | 会员即将到期 | `user` |
|
||
| `member_expired` | 会员已过期 | `user` |
|
||
|
||
## API
|
||
|
||
### 用户接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/notifications` | 通知列表（分页） |
|
||
| PUT | `/api/notifications/{id}/read` | 标记已读 |
|
||
| PUT | `/api/notifications/read-all` | 全部已读 |
|
||
| GET | `/api/notifications/unread-count` | 未读数量 |
|
||
|
||
### 管理员接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/admin/notifications` | 创建通知（需管理员 JWT） |
|
||
| DELETE | `/api/admin/notifications/{id}` | 删除通知 |
|
||
|
||
## 命令行工具
|
||
|
||
```bash
|
||
# 系统广播
|
||
./scripts/send-notification.sh \
|
||
--all \
|
||
--type system_maintenance \
|
||
--title "系统维护通知" \
|
||
--content "将于今晚 22:00 进行系统维护，预计耗时 1 小时" \
|
||
--priority high
|
||
|
||
# 定向通知
|
||
./scripts/send-notification.sh \
|
||
--user 1 \
|
||
--type payment_success \
|
||
--title "会员开通成功" \
|
||
--content "您已成功开通包月会员" \
|
||
--link "/pkg-extra/upgrade/upgrade" \
|
||
--dev
|
||
|
||
# 预览（不执行）
|
||
./scripts/send-notification.sh --all --type version_update --title "测试" --dry-run
|
||
```
|
||
|
||
参数说明：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `--all` | 是* | 发送给所有用户 |
|
||
| `--user <id>` | 是* | 发送给指定用户（二选一） |
|
||
| `--type <type>` | 是 | 通知类型 |
|
||
| `--title <text>` | 是 | 标题 |
|
||
| `--content <text>` | 否 | 正文 |
|
||
| `--priority <lvl>` | 否 | 默认 `normal` |
|
||
| `--link <path>` | 否 | 跳转路径 |
|
||
| `--dev` | 否 | 操作开发库 |
|
||
| `--dry-run` | 否 | 预览不执行 |
|
||
|
||
## 后续规划
|
||
|
||
此功能将在后续集成到网页管理端，管理员可通过后台界面：
|
||
|
||
1. 查看通知列表
|
||
2. 创建系统公告（选择类型、填写内容、设置优先级）
|
||
3. 发送个人通知（选择用户）
|
||
4. 管理已有通知（编辑、删除）
|
||
5. 查看发送记录
|
||
|