asd-backend/docs/NOTIFICATIONS.md

通知系统

概述

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

数据库

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}	删除通知

命令行工具

# 系统广播
./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. 查看发送记录