通知模块

通知模块负责平台各类事件触发的消息推送，支持站内信、邮件、短信三种投递渠道，是消息的生产与投递基础设施。

用户侧的消息收件箱详见 13-message-center-api.md。

12.1 通知记录（用户）

通知列表

GET /api/v1/notifications

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "notif_01HX...",
        "type": "balance.low",
        "title": "余额不足提醒",
        "content": "您的账户余额仅剩 10.00 元，请及时充值。",
        "is_read": false,
        "channels": ["in_app", "email"],
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "unread_count": 3,
    "total": 25
  }
}

通知详情

GET /api/v1/notifications/{notification_id}

标记已读

PUT /api/v1/notifications/{notification_id}/read

全部标记已读

PUT /api/v1/notifications/read-all

删除通知

DELETE /api/v1/notifications/{notification_id}

未读数量

GET /api/v1/notifications/unread-count

{
  "code": 0,
  "data": { "unread_count": 3 }
}

12.2 通知偏好设置（用户）

查询偏好设置

GET /api/v1/notifications/preferences

{
  "code": 0,
  "data": {
    "preferences": [
      {
        "event_type": "balance.low",
        "threshold": "20.00",
        "channels": { "in_app": true, "email": true, "sms": false }
      },
      {
        "event_type": "usage.quota_exceeded",
        "threshold_percent": 90,
        "channels": { "in_app": true, "email": true, "sms": true }
      },
      {
        "event_type": "membership.expired",
        "days_before": 7,
        "channels": { "in_app": true, "email": true, "sms": false }
      },
      {
        "event_type": "apikey.expired",
        "days_before": 3,
        "channels": { "in_app": true, "email": true, "sms": false }
      }
    ]
  }
}

更新偏好设置

PUT /api/v1/notifications/preferences

{
  "preferences": [
    {
      "event_type": "balance.low",
      "threshold": "50.00",
      "channels": { "in_app": true, "email": true, "sms": true }
    }
  ]
}

12.3 通知发送管理（管理员）

发送全平台公告

POST /admin/v1/notifications/broadcast

{
  "title": "系统维护通知",
  "content": "平台将于 2024-01-10 02:00-04:00 进行例行维护...",
  "channels": ["in_app", "email"],
  "target": {
    "user_type": "all"
  }
}

target.user_type 枚举：all / personal / enterprise

通知模板列表

GET /admin/v1/notifications/templates

{
  "code": 0,
  "data": {
    "items": [
      {
        "template_id": "tpl_balance_low",
        "event_type": "balance.low",
        "channel": "email",
        "subject": "【余额提醒】您的账户余额不足",
        "body": "尊敬的 {{nickname}}，您的账户余额仅剩 {{balance}} 元...",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

更新通知模板

PUT /admin/v1/notifications/templates/{template_id}

{
  "subject": "【余额提醒】您的账户余额不足，请及时充值",
  "body": "尊敬的 {{nickname}}，您的账户余额仅剩 {{balance}} 元，预计还可使用 {{days}} 天..."
}

发送日志

GET /admin/v1/notifications/send-logs

{
  "code": 0,
  "data": {
    "items": [
      {
        "log_id": "nlog_01HX...",
        "event_type": "balance.low",
        "channel": "email",
        "user_id": "u_01HX...",
        "recipient": "user@example.com",
        "status": "success",
        "sent_at": "2024-01-01T12:00:00Z"
      }
    ],
    "success_rate": "98.5%"
  }
}