xuqinmin12/lawless
1
0
派生 0
代码 工单 合并请求 Actions 1 软件包 项目 版本发布 百科 动态
9e9ef90ca7
lawless/docs/技术文档/TDD-09-推送与通知系统设计.md

1370 行
49 KiB
Markdown
原始文件 普通视图 文件历史

Initial commit: 洪荒大陆设计文档+代码骨架
2026-07-02 16:55:34 +08:00
# TDD-09 推送与通知系统设计
> 文档类型：技术设计文档（Technical Design Document）
> 版本：1.0
> 日期：2026-07-02
> 关联文档：TDD-04《数据库表结构设计》、TDD-05《API接口设计》、TDD-06《离线挂机结算系统设计》、TDD-07《反作弊与安全设计》、GDD-07《帮派门派社交系统设计》、GDD-13《佣兵大厅与悬赏系统》、GDD-14《稀有宝物流转与拍卖系统》、GDD-22《开放世界随机事件》
---
## 1. 文档信息
| 项目 | 说明 |
|------|------|
| 目标 | 为《洪荒大陆》挂机手游定义推送与通知系统的技术方案，覆盖游戏内通知中心、离线推送通道、推送策略控制、平台对接与内容安全。 |
| 读者 | 服务端开发（Nakama/Go）、客户端开发（Cocos Creator 3.x）、运维、测试 |
| 技术栈 | Nakama 3.x + Go插件 + PostgreSQL 16 + Valkey + Nacos 2.x + Cocos Creator 3.x |
| 核心约束 | 无任务系统、无赛季重置、概率/机遇驱动、文字战报、ATB行动条、功法加持、能量体系（非体力） |
| 游戏时间 | 现实:游戏 = 1:3 |
---
## 2. 系统总览
### 2.1 推送与通知的核心架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ 服务端事件源 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │挂机结算 │ │社交系统 │ │经济系统 │ │世界事件 │ │风险检测 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
│ └────────────┴────────────┴────────────┴────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ 通知调度引擎 │ │
│ │ (Nakama Runtime) │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 游戏内通知 │ │ 离线推送 │ │ 通知存储 │ │
│ │ (WebSocket)│ │ (APNs/FCM) │ │ (PostgreSQL)│ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 客户端 │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ 通知中心 │ │ 推送接收 │ │ 推送设置 │ │
│ │ (UI组件) │ │ (原生模块) │ │ (偏好管理) │ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### 2.2 设计原则
| 原则 | 说明 |
|------|------|
| **事件驱动** | 所有通知由游戏事件触发，不使用轮询机制 |
| **优先级分级** | 风险警告 > 社交通知 > 挂机通知 > 系统公告 |
| **在线优先** | 玩家在线时通过 WebSocket 实时推送，不发送离线推送 |
| **防打扰** | 支持免打扰时段、频率控制、同类消息合并 |
| **安全脱敏** | 离线推送内容不暴露游戏内敏感信息（如具体资源数量、坐标等） |
---
## 3. 推送类型分类
### 3.1 推送类型定义表
| 类型编码 | 类型名称 | 优先级 | 触发场景 | 推送时机 | 示例内容 |
|----------|----------|--------|----------|----------|----------|
| `RISK_WANTED` | 被通缉 | P0-紧急 | 角色被其他玩家发布悬赏 | 立即 | "你已被悬赏追杀，赏金XXX灵石" |
| `RISK_TRIBULATION` | 天罚预警 | P0-紧急 | 角色SAN值过低触发天罚倒计时 | 立即 | "天罚将在30分钟后降临" |
| `RISK_INVASION` | 洞府被入侵 | P0-紧急 | 其他玩家入侵角色洞府 | 立即 | "你的洞府正被XXX入侵" |
| `RISK_SAN_LOW` | SAN值过低 | P0-紧急 | 角色SAN值低于阈值 | 立即 | "你的精神状态岌岌可危" |
| `SOCIAL_DAO_COMPANION` | 道侣护法请求 | P1-高 | 道侣请求护法协助突破 | 立即 | "你的道侣XXX请求护法" |
| `SOCIAL_MASTER` | 师徒传功 | P1-高 | 师父发起传功邀请 | 立即 | "你的师父XXX邀请传功" |
| `SOCIAL_GUILD_SUMMON` | 帮派召集 | P1-高 | 帮主发起帮派集结 | 立即 | "帮派紧急召集，速回" |
| `SOCIAL_BOUNTY` | 追杀令 | P1-高 | 帮派发布追杀令 | 立即 | "帮派对XXX发布追杀令" |
| `IDLE_RESOURCE_FULL` | 资源满 | P2-中 | 挂机资源达到上限 | 延迟5分钟 | "你的XXX资源已满" |
| `IDLE_DISCIPLE_RETURN` | 弟子归来 | P2-中 | 弟子完成代派任务 | 延迟5分钟 | "弟子XXX完成任务归来" |
| `IDLE_REALM_BREAK` | 修炼突破条件达成 | P2-中 | 修为/材料满足突破条件 | 延迟5分钟 | "你已满足突破至XXX的条件" |
| `ECONOMY_AUCTION_WIN` | 拍卖成交 | P2-中 | 拍卖成功获得物品 | 结算后 | "你已成功拍得XXX" |
| `ECONOMY_AUCTION_OUTBID` | 被超价 | P2-中 | 拍卖出价被超越 | 立即 | "你在XXX拍卖中已被超越" |
| `ECONOMY_BOUNTY_SETTLE` | 悬赏结算 | P2-中 | 悬赏完成结算 | 结算后 | "悬赏XXX已结算" |
| `ECONOMY_MARKET_SOLD` | 交易行售出 | P2-中 | 交易行物品被购买 | 立即 | "你的XXX已售出" |
| `WORLD_APOCALYPSE` | 天启广播 | P2-中 | 天启事件触发 | 立即 | "天启降临，XXX" |
| `WORLD_DIVINE_BEAST` | 神兽现世 | P2-中 | 神兽刷新 | 立即 | "神兽XXX现世于XXX" |
| `WORLD_BOSS` | 世界Boss刷新 | P2-中 | 世界Boss刷新 | 立即 | "世界BossXXX已刷新" |
| `SYSTEM_MAINTENANCE` | 维护公告 | P3-低 | 服务器维护通知 | 提前1小时 | "服务器将于XXX维护" |
| `SYSTEM_UPDATE` | 版本更新 | P3-低 | 新版本发布 | 发布时 | "新版本XXX已发布" |
| `SYSTEM_ACTIVITY` | 活动开始 | P3-低 | 活动开启 | 活动开始 | "活动XXX已开始" |
### 3.2 推送类型编码规则
```
{CATEGORY}_{SPECIFIC_EVENT}
CATEGORY:
- RISK: 风险警告
- SOCIAL: 社交通知
- IDLE: 挂机通知
- ECONOMY: 经济通知
- WORLD: 世界事件
- SYSTEM: 系统通知
```
---
## 4. 推送策略
### 4.1 优先级分级策略
| 优先级 | 级别 | 在线行为 | 离线行为 | 频率限制 |
|--------|------|----------|----------|----------|
| P0-紧急 | 立即 | WebSocket实时推送 + 游戏内弹窗 | APNs/FCM即时推送 | 无限制 |
| P1-高 | 立即 | WebSocket实时推送 + 游戏内通知 | APNs/FCM即时推送 | 同类型5分钟/条 |
| P2-中 | 延迟 | WebSocket实时推送 | APNs/FCM延迟推送（5分钟合并） | 同类型10分钟/条 |
| P3-低 | 延迟 | WebSocket实时推送 | 不推送离线通知 | 同类型30分钟/条 |
### 4.2 免打扰时段设置
#### 4.2.1 玩家偏好配置
```json
{
"notification_preferences": {
"dnd_enabled": true,
"dnd_start_time": "23:00",
"dnd_end_time": "08:00",
"dnd_override_p0": true, // P0紧急消息是否突破免打扰
"category_settings": {
"RISK": { "enabled": true, "sound": true, "vibrate": true },
"SOCIAL": { "enabled": true, "sound": true, "vibrate": false },
"IDLE": { "enabled": true, "sound": false, "vibrate": false },
"ECONOMY": { "enabled": true, "sound": false, "vibrate": false },
"WORLD": { "enabled": true, "sound": true, "vibrate": false },
"SYSTEM": { "enabled": false, "sound": false, "vibrate": false }
}
}
}
```
#### 4.2.2 免打扰逻辑
```
IF 玩家处于免打扰时段:
IF 优先级 == P0 AND dnd_override_p0 == true:
正常推送
ELSE IF 优先级 == P0 AND dnd_override_p0 == false:
存入通知中心，不发送离线推送
ELSE:
存入通知中心，不发送离线推送
ELSE:
正常推送
```
### 4.3 推送频率控制
#### 4.3.1 合并同类消息
| 合并策略 | 适用场景 | 合并窗口 | 合并方式 |
|----------|----------|----------|----------|
| 资源满合并 | 多种资源同时满 | 5分钟 | "你的XXX、YYY、ZZZ资源已满" |
| 弟子归来合并 | 多个弟子同时归来 | 5分钟 | "弟子XXX、YYY完成任务归来" |
| 交易行售出合并 | 多件物品售出 | 10分钟 | "你的XXX等N件物品已售出" |
| 世界事件合并 | 多个世界事件 | 不合并 | 单独推送 |
#### 4.3.2 防刷屏机制
```go
// 推送频率控制配置
type PushRateLimit struct {
Category string `json:"category"`
MaxPerMinute int `json:"max_per_minute"`
MaxPerHour int `json:"max_per_hour"`
Cooldown time.Duration `json:"cooldown"`
}
// 默认配置
var DefaultRateLimits = map[string]PushRateLimit{
"RISK": {MaxPerMinute: 10, MaxPerHour: 60, Cooldown: 0},
"SOCIAL": {MaxPerMinute: 5, MaxPerHour: 30, Cooldown: 30 * time.Second},
"IDLE": {MaxPerMinute: 2, MaxPerHour: 10, Cooldown: 5 * time.Minute},
"ECONOMY": {MaxPerMinute: 3, MaxPerHour: 20, Cooldown: 2 * time.Minute},
"WORLD": {MaxPerMinute: 5, MaxPerHour: 30, Cooldown: 1 * time.Minute},
"SYSTEM": {MaxPerMinute: 1, MaxPerHour: 5, Cooldown: 10 * time.Minute},
}
```
### 4.4 在线状态判断
```go
// 玩家在线状态检查
type PlayerOnlineStatus struct {
CharacterID string `json:"character_id"`
IsOnline bool `json:"is_online"`
LastHeartbeat time.Time `json:"last_heartbeat"`
SessionID string `json:"session_id"`
}
// 推送决策逻辑
func shouldSendPush(status PlayerOnlineStatus, priority string) bool {
if status.IsOnline && time.Since(status.LastHeartbeat) < 30*time.Second {
// 玩家在线，通过WebSocket推送，不发送离线推送
return false
}
// 离线超过5分钟才发送离线推送（避免频繁切换）
if time.Since(status.LastHeartbeat) < 5*time.Minute {
return false
}
return true
}
```
---
## 5. 游戏内通知中心
### 5.1 通知中心数据模型
#### 5.1.1 notifications 表
```sql
CREATE TABLE notifications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
character_id UUID NOT NULL REFERENCES characters(id),
type VARCHAR(50) NOT NULL, -- 推送类型编码
category VARCHAR(20) NOT NULL, -- 分类：RISK/SOCIAL/IDLE/ECONOMY/WORLD/SYSTEM
priority SMALLINT NOT NULL DEFAULT 2, -- 优先级：0=P0, 1=P1, 2=P2, 3=P3
title VARCHAR(200) NOT NULL, -- 通知标题
content TEXT NOT NULL, -- 通知内容（支持模板变量）
payload JSONB, -- 附加数据（跳转参数等）
is_read BOOLEAN NOT NULL DEFAULT FALSE, -- 是否已读
read_at TIMESTAMPTZ, -- 阅读时间
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
expires_at TIMESTAMPTZ, -- 过期时间（可选）
-- 索引
INDEX idx_notifications_character_id (character_id),
INDEX idx_notifications_category (category),
INDEX idx_notifications_created_at (created_at),
INDEX idx_notifications_unread (character_id, is_read) WHERE is_read = FALSE
);
-- 按时间分区（可选，数据量大时）
-- CREATE TABLE notifications_partitioned (
-- LIKE notifications INCLUDING ALL
-- ) PARTITION BY RANGE (created_at);
```
#### 5.1.2 notification_templates 表
```sql
CREATE TABLE notification_templates (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
type VARCHAR(50) NOT NULL UNIQUE, -- 推送类型编码
category VARCHAR(20) NOT NULL,
priority SMALLINT NOT NULL DEFAULT 2,
title_template VARCHAR(200) NOT NULL, -- 标题模板
content_template TEXT NOT NULL, -- 内容模板
push_template TEXT, -- 离线推送内容模板（脱敏版）
sound VARCHAR(50), -- 提示音
vibrate BOOLEAN DEFAULT FALSE,
jump_type VARCHAR(50), -- 跳转类型
jump_params JSONB, -- 跳转参数模板
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
### 5.2 通知模板示例
```sql
-- 插入通知模板
INSERT INTO notification_templates (type, category, priority, title_template, content_template, push_template, jump_type) VALUES
('RISK_WANTED', 'RISK', 0, '被通缉', '你已被{{issuer_name}}悬赏追杀，赏金{{amount}}灵石', '你已被悬赏追杀', 'bounty_detail'),
('SOCIAL_DAO_COMPANION', 'SOCIAL', 1, '道侣护法请求', '你的道侣{{companion_name}}请求护法协助突破{{realm}}', '道侣请求护法', 'companion_request'),
('IDLE_RESOURCE_FULL', 'IDLE', 2, '资源满', '你的{{resource_names}}资源已满', '资源已满请及时收取', 'resource_panel'),
('ECONOMY_AUCTION_WIN', 'ECONOMY', 2, '拍卖成交', '你已成功拍得{{item_name}}，花费{{amount}}灵石', '拍卖成功', 'auction_detail'),
('WORLD_DIVINE_BEAST', 'WORLD', 2, '神兽现世', '神兽{{beast_name}}现世于{{location}}', '神兽现世', 'world_map');
```
### 5.3 通知操作与跳转
#### 5.3.1 跳转类型定义
| 跳转类型 | 说明 | 参数示例 |
|----------|------|----------|
| `bounty_detail` | 跳转到悬赏详情 | `{"bounty_id": "uuid"}` |
| `companion_request` | 跳转到道侣请求 | `{"request_id": "uuid"}` |
| `resource_panel` | 跳转到资源面板 | `{"resource_type": "spirit_stone"}` |
| `auction_detail` | 跳转到拍卖详情 | `{"auction_id": "uuid"}` |
| `world_map` | 跳转到世界地图 | `{"region_id": "uuid", "x": 100, "y": 200}` |
| `guild_main` | 跳转到帮派主页 | `{"guild_id": "uuid"}` |
| `market_order` | 跳转到交易行订单 | `{"order_id": "uuid"}` |
| `character_panel` | 跳转到角色面板 | `{"character_id": "uuid"}` |
#### 5.3.2 客户端跳转处理
```typescript
// 通知跳转处理
interface NotificationPayload {
jump_type: string;
jump_params: Record<string, any>;
}
class NotificationManager {
handleNotificationClick(notification: Notification): void {
const payload = notification.payload as NotificationPayload;
switch (payload.jump_type) {
case 'bounty_detail':
this.uiManager.openPanel('BountyDetailPanel', payload.jump_params);
break;
case 'companion_request':
this.uiManager.openPanel('CompanionRequestPanel', payload.jump_params);
break;
case 'resource_panel':
this.uiManager.openPanel('ResourcePanel', payload.jump_params);
break;
case 'auction_detail':
this.uiManager.openPanel('AuctionDetailPanel', payload.jump_params);
break;
case 'world_map':
this.uiManager.openPanel('WorldMapPanel', payload.jump_params);
break;
case 'guild_main':
this.uiManager.openPanel('GuildMainPanel', payload.jump_params);
break;
case 'market_order':
this.uiManager.openPanel('MarketOrderPanel', payload.jump_params);
break;
case 'character_panel':
this.uiManager.openPanel('CharacterPanel', payload.jump_params);
break;
default:
this.uiManager.openPanel('NotificationDetailPanel', { id: notification.id });
}
}
}
```
### 5.4 通知中心API
#### 5.4.1 获取通知列表
```
GET /api/v1/notifications
Authorization: Bearer <token>
Query Parameters:
- category: string (可选，筛选分类)
- is_read: boolean (可选，筛选已读/未读)
- page: int (默认1)
- page_size: int (默认20，最大50)
Response:
{
"code": 0,
"data": {
"total": 150,
"unread_count": 12,
"notifications": [
{
"id": "uuid",
"type": "RISK_WANTED",
"category": "RISK",
"priority": 0,
"title": "被通缉",
"content": "你已被XXX悬赏追杀，赏金1000灵石",
"payload": {
"jump_type": "bounty_detail",
"jump_params": {"bounty_id": "uuid"}
},
"is_read": false,
"created_at": "2026-07-02T10:30:00Z"
}
]
}
}
```
#### 5.4.2 标记通知已读
```
POST /api/v1/notifications/{id}/read
Authorization: Bearer <token>
Response:
{
"code": 0,
"data": {
"id": "uuid",
"is_read": true,
"read_at": "2026-07-02T10:35:00Z"
}
}
```
#### 5.4.3 批量标记已读
```
POST /api/v1/notifications/batch-read
Authorization: Bearer <token>
Request Body:
{
"notification_ids": ["uuid1", "uuid2", "uuid3"]
}
Response:
{
"code": 0,
"data": {
"updated_count": 3
}
}
```
#### 5.4.4 获取未读数量
```
GET /api/v1/notifications/unread-count
Authorization: Bearer <token>
Response:
{
"code": 0,
"data": {
"total_unread": 12,
"by_category": {
"RISK": 2,
"SOCIAL": 3,
"IDLE": 5,
"ECONOMY": 1,
"WORLD": 1,
"SYSTEM": 0
}
}
}
```
---
## 6. 平台对接
### 6.1 推送平台架构
```
┌─────────────────────────────────────────────────────────────────────┐
│ 推送调度服务 │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PushRouter │ │
│ │ - 根据设备类型选择推送通道 │ │
│ │ - 失败重试与降级策略 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┼──────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ APNs │ │ FCM │ │ 厂商通道 │ │
│ │ (iOS) │ │(Android)│ │ (华为等) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### 6.2 推送通道配置
#### 6.2.1 APNs (iOS)
```go
type APNsConfig struct {
// 认证方式：P8证书（推荐）或P12证书
AuthKeyPath string `json:"auth_key_path"` // P8证书路径
KeyID string `json:"key_id"` // P8 Key ID
TeamID string `json:"team_id"` // Apple Team ID
BundleID string `json:"bundle_id"` // App Bundle ID
// 环境配置
IsProduction bool `json:"is_production"` // true=生产环境，false=开发环境
// 连接配置
MaxIdleConns int `json:"max_idle_conns"` // 最大空闲连接数
IdleTimeout int `json:"idle_timeout"` // 空闲超时（秒）
}
// APNs 推送请求
type APNsRequest struct {
DeviceToken string `json:"device_token"`
Priority string `json:"priority"` // "10"=立即，"5"=省电模式
TTL int `json:"ttl"` // 消息存活时间（秒）
Topic string `json:"topic"` // Bundle ID
Payload APNsPayload `json:"payload"`
}
type APNsPayload struct {
Aps APSObject `json:"aps"`
// 自定义数据
CustomData map[string]interface{} `json:"custom_data,omitempty"`
}
type APSObject struct {
Alert AlertObject `json:"alert"`
Badge int `json:"badge,omitempty"`
Sound string `json:"sound,omitempty"`
ContentAvailable int `json:"content-available,omitempty"`
MutableContent int `json:"mutable-content,omitempty"`
}
type AlertObject struct {
Title string `json:"title"`
Body string `json:"body"`
LocKey string `json:"loc-key,omitempty"`
LocArgs []string `json:"loc-args,omitempty"`
}
```
#### 6.2.2 FCM (Android)
```go
type FCMConfig struct {
// 认证方式：服务账号JSON文件
ServiceAccountPath string `json:"service_account_path"`
ProjectID string `json:"project_id"`
// 连接配置
MaxIdleConns int `json:"max_idle_conns"`
IdleTimeout int `json:"idle_timeout"`
}
// FCM 推送请求
type FCMRequest struct {
Message FCMMessage `json:"message"`
}
type FCMMessage struct {
Token string `json:"token"`
Notification *FCMNotification `json:"notification,omitempty"`
Data map[string]string `json:"data,omitempty"`
Android *AndroidConfig `json:"android,omitempty"`
APNs *FCMAPNsConfig `json:"apns,omitempty"`
}
type FCMNotification struct {
Title string `json:"title"`
Body string `json:"body"`
ImageURL string `json:"image_url,omitempty"`
}
type AndroidConfig struct {
Priority string `json:"priority"` // "high" 或 "normal"
TTL string `json:"ttl"` // 消息存活时间
Notification *AndroidNotification `json:"notification,omitempty"`
}
type AndroidNotification struct {
ChannelID string `json:"channel_id"` // 通知渠道ID
Sound string `json:"sound"`
ClickAction string `json:"click_action"`
}
```
#### 6.2.3 华为/小米/OPPO/vivo 厂商通道
```go
// 华为 Push Kit
type HuaweiPushConfig struct {
AppID string `json:"app_id"`
AppSecret string `json:"app_secret"`
AuthURL string `json:"auth_url"`
PushURL string `json:"push_url"`
}
// 小米推送
type XiaomiPushConfig struct {
AppID string `json:"app_id"`
AppKey string `json:"app_key"`
AppSecret string `json:"app_secret"`
PushURL string `json:"push_url"`
}
// OPPO 推送
type OPPOPushConfig struct {
AppID string `json:"app_id"`
AppKey string `json:"app_key"`
MasterSecret string `json:"master_secret"`
PushURL string `json:"push_url"`
}
// vivo 推送
type VivoPushConfig struct {
AppID string `json:"app_id"`
AppKey string `json:"app_key"`
AppSecret string `json:"app_secret"`
PushURL string `json:"push_url"`
}
// 鸿蒙 Push Kit
type HarmonyPushConfig struct {
AppID string `json:"app_id"`
AppSecret string `json:"app_secret"`
PushURL string `json:"push_url"`
}
```
### 6.3 推送Token管理
#### 6.3.1 device_push_tokens 表
```sql
CREATE TABLE device_push_tokens (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
player_id UUID NOT NULL REFERENCES players(id),
character_id UUID NOT NULL REFERENCES characters(id),
device_id VARCHAR(100) NOT NULL, -- 设备唯一标识
platform VARCHAR(20) NOT NULL, -- ios/android/harmonyos
push_provider VARCHAR(20) NOT NULL, -- apns/fcm/huawei/xiaomi/oppo/vivo/harmony
push_token TEXT NOT NULL, -- 推送Token
device_model VARCHAR(100), -- 设备型号
os_version VARCHAR(20), -- 系统版本
app_version VARCHAR(20), -- 应用版本
is_active BOOLEAN DEFAULT TRUE, -- 是否有效
last_used_at TIMESTAMPTZ, -- 最后使用时间
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
-- 唯一约束：同一设备同一推送提供者只有一个有效Token
UNIQUE(device_id, push_provider, is_active) WHERE is_active = TRUE
);
-- 索引
CREATE INDEX idx_device_push_tokens_player_id ON device_push_tokens(player_id);
CREATE INDEX idx_device_push_tokens_character_id ON device_push_tokens(character_id);
CREATE INDEX idx_device_push_tokens_active ON device_push_tokens(is_active) WHERE is_active = TRUE;
```
#### 6.3.2 Token刷新机制
```go
// Token刷新服务
type TokenRefreshService struct {
db *sql.DB
cache *valkey.Client
}
// 客户端上报Token
func (s *TokenRefreshService) RegisterToken(ctx context.Context, req *RegisterTokenRequest) error {
// 1. 验证Token有效性（调用各平台API验证）
if err := s.validateToken(ctx, req.Platform, req.PushProvider, req.PushToken); err != nil {
return fmt.Errorf("invalid push token: %w", err)
}
// 2. 使旧Token失效（同一设备同一提供者）
_, err := s.db.ExecContext(ctx, `
UPDATE device_push_tokens
SET is_active = FALSE, updated_at = NOW()
WHERE device_id = $1 AND push_provider = $2 AND is_active = TRUE
`, req.DeviceID, req.PushProvider)
if err != nil {
return err
}
// 3. 插入新Token
_, err = s.db.ExecContext(ctx, `
INSERT INTO device_push_tokens
(player_id, character_id, device_id, platform, push_provider, push_token,
device_model, os_version, app_version, is_active, last_used_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, TRUE, NOW())
`, req.PlayerID, req.CharacterID, req.DeviceID, req.Platform, req.PushProvider,
req.PushToken, req.DeviceModel, req.OSVersion, req.AppVersion)
if err != nil {
return err
}
// 4. 更新缓存
s.cache.Set(ctx, fmt.Sprintf("push_token:%s:%s", req.DeviceID, req.PushProvider), req.PushToken, 24*7*time.Hour)
return nil
}
// 定时清理无效Token
func (s *TokenRefreshService) CleanupInvalidTokens(ctx context.Context) error {
// 清理30天未使用的Token
_, err := s.db.ExecContext(ctx, `
UPDATE device_push_tokens
SET is_active = FALSE, updated_at = NOW()
WHERE last_used_at < NOW() - INTERVAL '30 days' AND is_active = TRUE
`)
return err
}
```
#### 6.3.3 Token注册API
```
POST /api/v1/push-tokens
Authorization: Bearer <token>
Request Body:
{
"device_id": "device-uuid",
"platform": "ios",
"push_provider": "apns",
"push_token": "apns-device-token-here",
"device_model": "iPhone 14 Pro",
"os_version": "16.5",
"app_version": "1.0.0"
}
Response:
{
"code": 0,
"data": {
"token_id": "uuid",
"registered_at": "2026-07-02T10:30:00Z"
}
}
```
### 6.4 推送路由与降级策略
```go
// 推送路由器
type PushRouter struct {
providers map[string]PushProvider
db *sql.DB
cache *valkey.Client
}
// 推送提供者接口
type PushProvider interface {
Send(ctx context.Context, token string, payload *PushPayload) (*PushResult, error)
ValidateToken(ctx context.Context, token string) error
}
// 推送结果
type PushResult struct {
Success bool `json:"success"`
MessageID string `json:"message_id"`
Error string `json:"error,omitempty"`
Retryable bool `json:"retryable"`
}
// 推送路由逻辑
func (r *PushRouter) SendPush(ctx context.Context, characterID string, notification *Notification) error {
// 1. 获取玩家所有有效设备Token
tokens, err := r.getActiveTokens(ctx, characterID)
if err != nil {
return err
}
if len(tokens) == 0 {
return nil // 无有效Token，跳过
}
// 2. 构建推送内容（脱敏版）
payload := r.buildPushPayload(notification)
// 3. 按优先级发送（P0立即，P2延迟5分钟）
if notification.Priority <= 1 {
return r.sendImmediate(ctx, tokens, payload)
}
// 4. 延迟推送（放入队列）
return r.enqueueDelayed(ctx, tokens, payload, 5*time.Minute)
}
// 立即发送
func (r *PushRouter) sendImmediate(ctx context.Context, tokens []*DeviceToken, payload *PushPayload) error {
for _, token := range tokens {
provider, ok := r.providers[token.PushProvider]
if !ok {
continue
}
result, err := provider.Send(ctx, token.PushToken, payload)
if err != nil {
// 记录失败，后续重试
r.recordFailure(ctx, token, err)
continue
}
if !result.Success && result.Retryable {
// 可重试的失败，放入重试队列
r.enqueueRetry(ctx, token, payload, 3)
}
}
return nil
}
```
---
## 7. 推送内容安全
### 7.1 消息加密
#### 7.1.1 传输加密
```go
// 推送内容加密
type PushEncryptor struct {
key []byte // AES-256密钥
}
// 加密推送内容
func (e *PushEncryptor) Encrypt(payload *PushPayload) (*EncryptedPushPayload, error) {
// 1. 序列化为JSON
data, err := json.Marshal(payload)
if err != nil {
return nil, err
}
// 2. AES-256-GCM加密
block, err := aes.NewCipher(e.key)
if err != nil {
return nil, err
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return nil, err
}
nonce := make([]byte, gcm.NonceSize())
if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
return nil, err
}
ciphertext := gcm.Seal(nonce, nonce, data, nil)
return &EncryptedPushPayload{
Data: base64.StdEncoding.EncodeToString(ciphertext),
Timestamp: time.Now().Unix(),
}, nil
}
```
#### 7.1.2 内容脱敏策略
| 推送类型 | 脱敏规则 | 示例 |
|----------|----------|------|
| 被通缉 | 不暴露具体赏金数额 | "你已被悬赏追杀" |
| 资源满 | 不暴露具体资源数量 | "你的资源已满" |
| 拍卖成交 | 不暴露具体花费金额 | "拍卖成功" |
| 洞府被入侵 | 不暴露入侵者信息 | "你的洞府正被入侵" |
| 世界Boss | 保留Boss名称和位置 | "世界BossXXX已刷新" |
### 7.2 推送去重
#### 7.2.1 去重策略
```go
// 推送去重服务
type PushDeduplicator struct {
cache *valkey.Client
}
// 去重键生成
func (d *PushDeduplicator) generateDedupeKey(characterID string, notificationType string, relatedID string) string {
// 格式：push_dedupe:{character_id}:{type}:{related_id}
return fmt.Sprintf("push_dedupe:%s:%s:%s", characterID, notificationType, relatedID)
}
// 检查是否重复
func (d *PushDeduplicator) IsDuplicate(ctx context.Context, characterID string, notification *Notification) bool {
key := d.generateDedupeKey(characterID, notification.Type, notification.RelatedID)
// 检查是否已发送
exists, err := d.cache.Exists(ctx, key).Result()
if err != nil {
return false // 缓存错误，允许发送
}
return exists > 0
}
// 标记已发送
func (d *PushDeduplicator) MarkSent(ctx context.Context, characterID string, notification *Notification, ttl time.Duration) error {
key := d.generateDedupeKey(characterID, notification.Type, notification.RelatedID)
return d.cache.Set(ctx, key, "1", ttl).Err()
}
```
#### 7.2.2 去重规则
| 场景 | 去重键 | TTL |
|------|--------|-----|
| 同一悬赏重复通知 | `push_dedupe:{char_id}:RISK_WANTED:{bounty_id}` | 24小时 |
| 同一弟子归来 | `push_dedupe:{char_id}:IDLE_DISCIPLE_RETURN:{mission_id}` | 1小时 |
| 同一拍卖超价 | `push_dedupe:{char_id}:ECONOMY_AUCTION_OUTBID:{auction_id}` | 拍卖结束 |
| 同一世界事件 | `push_dedupe:{char_id}:WORLD_BOSS:{boss_id}` | Boss存活期间 |
### 7.3 推送追踪
#### 7.3.1 推送统计表
```sql
CREATE TABLE push_statistics (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
notification_id UUID NOT NULL,
character_id UUID NOT NULL,
push_provider VARCHAR(20) NOT NULL,
device_id VARCHAR(100) NOT NULL,
-- 发送状态
sent_at TIMESTAMPTZ,
delivered_at TIMESTAMPTZ, -- 到达时间（平台回调）
clicked_at TIMESTAMPTZ, -- 点击时间
-- 错误信息
error_code VARCHAR(50),
error_message TEXT,
-- 追踪ID
platform_message_id VARCHAR(100), -- 平台返回的消息ID
created_at TIMESTAMPTZ DEFAULT NOW(),
-- 索引
INDEX idx_push_statistics_character_id (character_id),
INDEX idx_push_statistics_sent_at (sent_at),
INDEX idx_push_statistics_platform_message_id (platform_message_id)
);
```
#### 7.3.2 统计指标
```go
// 推送统计服务
type PushStatisticsService struct {
db *sql.DB
}
// 统计指标
type PushMetrics struct {
TotalSent int64 `json:"total_sent"`
TotalDelivered int64 `json:"total_delivered"`
TotalClicked int64 `json:"total_clicked"`
DeliveryRate float64 `json:"delivery_rate"` // 到达率
ClickRate float64 `json:"click_rate"` // 点击率
// 按平台统计
ByProvider map[string]*ProviderMetrics `json:"by_provider"`
// 按类型统计
ByType map[string]*TypeMetrics `json:"by_type"`
}
type ProviderMetrics struct {
Sent int64 `json:"sent"`
Delivered int64 `json:"delivered"`
Clicked int64 `json:"clicked"`
ErrorRate float64 `json:"error_rate"`
}
type TypeMetrics struct {
Sent int64 `json:"sent"`
Delivered int64 `json:"delivered"`
Clicked int64 `json:"clicked"`
ClickRate float64 `json:"click_rate"`
}
// 获取统计指标
func (s *PushStatisticsService) GetMetrics(ctx context.Context, startTime, endTime time.Time) (*PushMetrics, error) {
// 实现略
return nil, nil
}
```
---
## 8. 通知调度引擎
### 8.1 Nakama Runtime 集成
```go
// 通知调度引擎（Nakama Go插件）
type NotificationEngine struct {
db *sql.DB
cache *valkey.Client
pushRouter *PushRouter
deduplicator *PushDeduplicator
rateLimiter *RateLimiter
statistics *PushStatisticsService
}
// 初始化通知引擎
func InitNotificationEngine(db *sql.DB, cache *valkey.Client) *NotificationEngine {
return &NotificationEngine{
db: db,
cache: cache,
pushRouter: NewPushRouter(db, cache),
deduplicator: NewPushDeduplicator(cache),
rateLimiter: NewRateLimiter(cache),
statistics: NewPushStatisticsService(db),
}
}
// 发送通知
func (e *NotificationEngine) SendNotification(ctx context.Context, req *SendNotificationRequest) error {
// 1. 验证请求
if err := req.Validate(); err != nil {
return err
}
// 2. 检查频率限制
if !e.rateLimiter.Allow(ctx, req.CharacterID, req.Type) {
return fmt.Errorf("rate limit exceeded for %s", req.Type)
}
// 3. 检查去重
if e.deduplicator.IsDuplicate(ctx, req.CharacterID, req.Notification) {
return nil // 重复消息，跳过
}
// 4. 获取玩家在线状态
isOnline, err := e.isPlayerOnline(ctx, req.CharacterID)
if err != nil {
return err
}
// 5. 存储通知到数据库
notificationID, err := e.storeNotification(ctx, req)
if err != nil {
return err
}
// 6. 如果在线，通过WebSocket推送
if isOnline {
e.sendWebSocket(ctx, req.CharacterID, req.Notification)
}
// 7. 如果离线，发送离线推送
if !isOnline && req.Priority <= 2 {
if err := e.pushRouter.SendPush(ctx, req.CharacterID, req.Notification); err != nil {
// 推送失败不阻塞主流程，记录日志
e.recordPushFailure(ctx, notificationID, err)
}
}
// 8. 标记已发送
e.deduplicator.MarkSent(ctx, req.CharacterID, req.Notification, 24*time.Hour)
// 9. 记录统计
e.statistics.RecordSent(ctx, notificationID, req.CharacterID)
return nil
}
```
### 8.2 事件触发器
```go
// 挂机结算触发通知
func (e *NotificationEngine) OnIdleSettlement(ctx context.Context, characterID string, result *IdleSettlementResult) {
// 资源满通知
if result.ResourceFull {
e.SendNotification(ctx, &SendNotificationRequest{
CharacterID: characterID,
Type: "IDLE_RESOURCE_FULL",
Priority: 2,
Notification: &Notification{
Title: "资源满",
Content: fmt.Sprintf("你的%s资源已满", strings.Join(result.FullResources, "、")),
Payload: map[string]interface{}{
"jump_type": "resource_panel",
"jump_params": map[string]interface{}{"resource_type": result.FullResources[0]},
},
},
})
}
// 弟子归来通知
if len(result.CompletedDisciples) > 0 {
e.SendNotification(ctx, &SendNotificationRequest{
CharacterID: characterID,
Type: "IDLE_DISCIPLE_RETURN",
Priority: 2,
Notification: &Notification{
Title: "弟子归来",
Content: fmt.Sprintf("弟子%s完成任务归来", strings.Join(result.CompletedDisciples, "、")),
Payload: map[string]interface{}{
"jump_type": "disciple_panel",
"jump_params": map[string]interface{}{},
},
},
})
}
}
// 拍卖超价触发通知
func (e *NotificationEngine) OnAuctionOutbid(ctx context.Context, characterID string, auctionID string, currentPrice int64) {
e.SendNotification(ctx, &SendNotificationRequest{
CharacterID: characterID,
Type: "ECONOMY_AUCTION_OUTBID",
Priority: 2,
Notification: &Notification{
Title: "被超价",
Content: "你在拍卖中已被超越",
Payload: map[string]interface{}{
"jump_type": "auction_detail",
"jump_params": map[string]interface{}{"auction_id": auctionID},
},
RelatedID: auctionID,
},
})
}
// 世界Boss刷新触发通知
func (e *NotificationEngine) OnWorldBossSpawn(ctx context.Context, bossID string, bossName string, location string) {
// 获取所有在线玩家
onlinePlayers, err := e.getOnlinePlayers(ctx)
if err != nil {
return
}
// 批量发送通知
for _, playerID := range onlinePlayers {
e.SendNotification(ctx, &SendNotificationRequest{
CharacterID: playerID,
Type: "WORLD_BOSS",
Priority: 2,
Notification: &Notification{
Title: "世界Boss刷新",
Content: fmt.Sprintf("世界Boss%s已刷新于%s", bossName, location),
Payload: map[string]interface{}{
"jump_type": "world_map",
"jump_params": map[string]interface{}{"boss_id": bossID},
},
RelatedID: bossID,
},
})
}
}
```
---
## 9. Nacos 动态配置
### 9.1 推送配置
```yaml
# Nacos 配置：push_config.yaml
push:
# 全局开关
enabled: true
# 优先级配置
priority:
p0_delay_seconds: 0
p1_delay_seconds: 0
p2_delay_seconds: 300
p3_delay_seconds: 1800
# 频率限制
rate_limit:
risk:
max_per_minute: 10
max_per_hour: 60
cooldown_seconds: 0
social:
max_per_minute: 5
max_per_hour: 30
cooldown_seconds: 30
idle:
max_per_minute: 2
max_per_hour: 10
cooldown_seconds: 300
economy:
max_per_minute: 3
max_per_hour: 20
cooldown_seconds: 120
world:
max_per_minute: 5
max_per_hour: 30
cooldown_seconds: 60
system:
max_per_minute: 1
max_per_hour: 5
cooldown_seconds: 600
# 去重配置
deduplication:
enabled: true
default_ttl_hours: 24
# 推送通道配置
providers:
apns:
enabled: true
is_production: false
max_retries: 3
retry_delay_seconds: 5
fcm:
enabled: true
max_retries: 3
retry_delay_seconds: 5
huawei:
enabled: true
max_retries: 3
retry_delay_seconds: 5
xiaomi:
enabled: true
max_retries: 3
retry_delay_seconds: 5
oppo:
enabled: true
max_retries: 3
retry_delay_seconds: 5
vivo:
enabled: true
max_retries: 3
retry_delay_seconds: 5
harmony:
enabled: true
max_retries: 3
retry_delay_seconds: 5
# 免打扰配置
dnd:
override_p0: true
min_offline_minutes: 5
# 通知保留配置
retention:
max_days: 30
cleanup_interval_hours: 24
```
---
## 10. 已确认决策记录表
| 决策编号 | 决策内容 | 状态 | 关联文档 | 备注 |
|----------|----------|------|----------|------|
| ✅P-01 | 推送类型分为6大类：RISK/SOCIAL/IDLE/ECONOMY/WORLD/SYSTEM | 已确认 | - | 基于游戏核心玩法 |
| ✅P-02 | 优先级分为4级：P0紧急/P1高/P2中/P3低 | 已确认 | - | 风险警告最高优先 |
| ✅P-03 | 在线玩家通过WebSocket实时推送，不发送离线推送 | 已确认 | TDD-05 | 避免重复推送 |
| ✅P-04 | 离线推送延迟5分钟合并同类消息 | 已确认 | - | 减少打扰 |
| ✅P-05 | 免打扰时段支持P0消息突破 | 已确认 | - | 紧急消息必须送达 |
| ✅P-06 | 推送内容脱敏，不暴露敏感信息 | 已确认 | TDD-07 | 安全要求 |
| ✅P-07 | 支持APNs/FCM/华为/小米/OPPO/vivo/鸿蒙7个推送通道 | 已确认 | - | 覆盖主流平台 |
| ✅P-08 | 推送Token有效期30天，过期自动清理 | 已确认 | - | Token生命周期管理 |
| ✅P-09 | 推送去重基于角色ID+类型+关联ID | 已确认 | - | 防止重复推送 |
| ✅P-10 | 通知中心数据保留30天 | 已确认 | - | 存储成本考虑 |
| ✅P-11 | 通知跳转支持8种跳转类型 | 已确认 | - | 覆盖主要场景 |
| ✅P-12 | 推送统计记录到达率和点击率 | 已确认 | - | 运营分析需求 |
| ✅P-13 | Nakama Runtime作为通知调度引擎 | 已确认 | TDD-05 | 与现有架构一致 |
| ✅P-14 | Nacos动态配置推送参数 | 已确认 | - | 支持热更新 |
| ✅P-15 | 推送频率限制：RISK 10条/分钟，SOCIAL 5条/分钟 | 已确认 | - | 防刷屏 |
---
## 11. 验收标准
### 11.1 功能验收
| 验收项 | 验收标准 | 验证方法 |
|--------|----------|----------|
| 推送类型覆盖 | 6大类20种推送类型全部实现 | 单元测试 + 集成测试 |
| 优先级分级 | P0/P1立即推送，P2延迟5分钟，P3不推送离线 | 测试不同优先级推送 |
| 免打扰时段 | 免打扰时段内不推送离线通知（P0可突破） | 设置免打扰测试 |
| 频率控制 | 同类型推送不超过频率限制 | 压力测试 |
| 消息合并 | 同类消息在窗口期内合并 | 测试合并逻辑 |
| 在线状态判断 | 在线玩家不发送离线推送 | 模拟在线/离线 |
| 通知中心 | 通知存储、查询、已读、跳转功能正常 | 功能测试 |
| Token管理 | Token注册、刷新、过期清理正常 | 功能测试 |
| 多平台推送 | 7个推送通道全部可用 | 各平台测试 |
| 内容脱敏 | 离线推送不包含敏感信息 | 代码审查 + 测试 |
| 推送去重 | 同一通知不重复推送 | 测试去重逻辑 |
| 推送统计 | 到达率、点击率统计正确 | 数据验证 |
### 11.2 性能验收
| 验收项 | 验收标准 | 验证方法 |
|--------|----------|----------|
| 通知写入延迟 | P99 < 50ms | 压力测试 |
| 通知查询延迟 | P99 < 100ms | 压力测试 |
| 推送发送延迟 | P99 < 200ms | 压力测试 |
| 并发推送能力 | 支持1000条/秒 | 压力测试 |
| 数据库查询 | 通知列表查询 < 50ms | 慢查询监控 |
| 缓存命中率 | Token缓存命中率 > 95% | 监控统计 |
### 11.3 安全验收
| 验收项 | 验收标准 | 验证方法 |
|--------|----------|----------|
| Token安全 | Token传输加密，存储加密 | 安全审计 |
| 内容加密 | 敏感推送内容加密传输 | 代码审查 |
| 权限控制 | 玩家只能查看自己的通知 | 权限测试 |
| 防刷屏 | 频率限制有效 | 压力测试 |
| 数据保留 | 过期通知自动清理 | 定时任务验证 |
### 11.4 可靠性验收
| 验收项 | 验收标准 | 验证方法 |
|--------|----------|----------|
| 推送送达率 | > 99% | 统计监控 |
| 通知不丢失 | 所有通知持久化到数据库 | 数据一致性检查 |
| 故障恢复 | 推送服务故障不影响游戏主流程 | 故障注入测试 |
| 重试机制 | 推送失败自动重试3次 | 测试重试逻辑 |
| 降级策略 | 推送服务不可用时通知正常存储 | 故障测试 |
---
## 12. 附录
### 12.1 推送类型完整列表
| 编码 | 名称 | 分类 | 优先级 | 在线推送 | 离线推送 |
|------|------|------|--------|----------|----------|
| RISK_WANTED | 被通缉 | RISK | P0 | 是 | 是 |
| RISK_TRIBULATION | 天罚预警 | RISK | P0 | 是 | 是 |
| RISK_INVASION | 洞府被入侵 | RISK | P0 | 是 | 是 |
| RISK_SAN_LOW | SAN值过低 | RISK | P0 | 是 | 是 |
| SOCIAL_DAO_COMPANION | 道侣护法请求 | SOCIAL | P1 | 是 | 是 |
| SOCIAL_MASTER | 师徒传功 | SOCIAL | P1 | 是 | 是 |
| SOCIAL_GUILD_SUMMON | 帮派召集 | SOCIAL | P1 | 是 | 是 |
| SOCIAL_BOUNTY | 追杀令 | SOCIAL | P1 | 是 | 是 |
| IDLE_RESOURCE_FULL | 资源满 | IDLE | P2 | 是 | 是 |
| IDLE_DISCIPLE_RETURN | 弟子归来 | IDLE | P2 | 是 | 是 |
| IDLE_REALM_BREAK | 修炼突破条件达成 | IDLE | P2 | 是 | 是 |
| ECONOMY_AUCTION_WIN | 拍卖成交 | ECONOMY | P2 | 是 | 是 |
| ECONOMY_AUCTION_OUTBID | 被超价 | ECONOMY | P2 | 是 | 是 |
| ECONOMY_BOUNTY_SETTLE | 悬赏结算 | ECONOMY | P2 | 是 | 是 |
| ECONOMY_MARKET_SOLD | 交易行售出 | ECONOMY | P2 | 是 | 是 |
| WORLD_APOCALYPSE | 天启广播 | WORLD | P2 | 是 | 是 |
| WORLD_DIVINE_BEAST | 神兽现世 | WORLD | P2 | 是 | 是 |
| WORLD_BOSS | 世界Boss刷新 | WORLD | P2 | 是 | 是 |
| SYSTEM_MAINTENANCE | 维护公告 | SYSTEM | P3 | 是 | 否 |
| SYSTEM_UPDATE | 版本更新 | SYSTEM | P3 | 是 | 否 |
| SYSTEM_ACTIVITY | 活动开始 | SYSTEM | P3 | 是 | 否 |
### 12.2 数据库表清单
| 表名 | 说明 | 分区 | 保留策略 |
|------|------|------|----------|
| notifications | 通知表 | 按月分区 | 30天 |
| notification_templates | 通知模板表 | - | 永久 |
| device_push_tokens | 设备推送Token表 | - | 30天未使用清理 |
| push_statistics | 推送统计表 | 按天分区 | 90天 |
### 12.3 API接口清单
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/notifications` | GET | 获取通知列表 |
| `/api/v1/notifications/{id}/read` | POST | 标记通知已读 |
| `/api/v1/notifications/batch-read` | POST | 批量标记已读 |
| `/api/v1/notifications/unread-count` | GET | 获取未读数量 |
| `/api/v1/push-tokens` | POST | 注册推送Token |
| `/api/v1/push-tokens/{id}` | DELETE | 删除推送Token |
| `/api/v1/push-tokens/refresh` | POST | 刷新推送Token |
---
**文档维护人**：移动端开发
**最后更新**：2026-07-02
**版本**：1.0
在新工单中引用 复制永久链接