# 通知系统

## 概述

支持三类通知：系统公告（广播）、个人通知（定向）、事件驱动通知。

### 数据库

`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. 查看发送记录