temp

docs/NOTIFICATIONS.md

@@ -0,0 +1,98 @@
+# 通知系统
+
+## 概述
+
+支持三类通知：系统公告（广播）、个人通知（定向）、事件驱动通知。
+
+### 数据库
+
+`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. 查看发送记录