消息中心

消息中心是用户侧的综合消息收件箱，按类型分类展示，支持搜索、批量操作和 SSE 实时推送。

与通知模块的关系：

通知模块（12）负责消息的生产与投递（触发 → 生成 → 渠道推送）
消息中心（13）负责消息的展示与管理（收件箱 → 分类阅读 → 搜索归档）

消息分类

type	说明	典型场景
`announcement`	系统公告	版本更新、服务维护
`alert`	业务告警	余额不足、用量超限、API Key 到期
`security`	安全通知	异地登录、密码修改
`billing`	账单与支付	充值成功、月度账单、退款到账
`membership`	会员消息	会员开通、到期提醒、权益变更
`promotion`	活动与优惠	代金券发放、限时优惠
`system`	系统任务	数据导出完成、认证审核结果

13.1 消息收件箱

消息列表

GET /api/v1/messages

查询参数	类型	说明
`type`	string	消息分类，支持多选逗号分隔：`alert,billing`
`is_read`	bool	`true` 已读 / `false` 未读
`priority`	string	`high` / `normal` / `low`
`page`	int	页码
`page_size`	int	每页条数

{
  "code": 0,
  "data": {
    "items": [
      {
        "msg_id": "msg_01HX...",
        "type": "alert",
        "priority": "high",
        "title": "余额不足提醒",
        "summary": "您的账户余额仅剩 10.00 元",
        "content": "您的账户余额仅剩 10.00 元，距余额耗尽预计还有 2 天，请及时充值。",
        "action": {
          "label": "立即充值",
          "url": "/wallet/recharge"
        },
        "is_read": false,
        "created_at": "2024-01-01T12:00:00Z",
        "expire_at": null
      }
    ],
    "total": 18,
    "page": 1,
    "page_size": 20
  }
}

消息详情（自动标记已读）

GET /api/v1/messages/{msg_id}

标记指定消息已读

PUT /api/v1/messages/{msg_id}/read

批量标记已读

PUT /api/v1/messages/batch-read

{
  "msg_ids": ["msg_01HX...", "msg_02HX..."]
}

全部标记已读：

{ "all": true }

删除消息

DELETE /api/v1/messages/{msg_id}

批量删除

DELETE /api/v1/messages/batch-delete

{ "msg_ids": ["msg_01HX...", "msg_02HX..."] }

各分类未读数

GET /api/v1/messages/unread-count

{
  "code": 0,
  "data": {
    "total": 8,
    "breakdown": {
      "announcement": 1,
      "alert": 3,
      "security": 0,
      "billing": 2,
      "membership": 1,
      "promotion": 1,
      "system": 0
    }
  }
}

13.2 消息搜索

GET /api/v1/messages/search

查询参数	类型	必填	说明
`q`	string	是	搜索关键词（标题 + 内容全文搜索）
`type`	string	否	限定分类
`start_date`	string	否	起始日期
`end_date`	string	否	结束日期
`page`	int	否	页码

{
  "code": 0,
  "data": {
    "items": [...],
    "total": 5,
    "keyword": "余额"
  }
}

13.3 实时消息推送（SSE）

GET /api/v1/messages/stream

建立 SSE 长连接，服务端实时推送新消息，用于前端顶栏 Badge 实时更新。

GET /api/v1/messages/stream
Authorization: Bearer <token>
Accept: text/event-stream

SSE 事件格式：

event: new_message
data: {"msg_id":"msg_02HX","type":"billing","title":"充值成功","priority":"normal","is_read":false}

event: unread_count
data: {"total":9,"breakdown":{"billing":3}}

event: ping
data: {"timestamp":1704067200}

ping 事件每 30 秒发送一次，用于保活。前端断线后应自动重连（EventSource 原生支持）。

13.4 消息订阅设置

查询订阅设置

GET /api/v1/messages/subscriptions

{
  "code": 0,
  "data": {
    "subscriptions": [
      { "type": "alert",        "in_app": true,  "email": true,  "sms": true  },
      { "type": "security",     "in_app": true,  "email": true,  "sms": true  },
      { "type": "billing",      "in_app": true,  "email": true,  "sms": false },
      { "type": "membership",   "in_app": true,  "email": true,  "sms": false },
      { "type": "announcement", "in_app": true,  "email": false, "sms": false },
      { "type": "promotion",    "in_app": true,  "email": false, "sms": false },
      { "type": "system",       "in_app": true,  "email": false, "sms": false }
    ]
  }
}

更新订阅设置

PUT /api/v1/messages/subscriptions

{
  "subscriptions": [
    { "type": "alert", "in_app": true, "email": true, "sms": true }
  ]
}

13.5 公告管理（管理员）

公告列表

GET /admin/v1/messages/announcements

查询参数	说明
`status`	`draft` / `published` / `unpublished`

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "ann_01HX...",
        "title": "GPT-4o 模型价格调整公告",
        "priority": "high",
        "status": "published",
        "target": {
          "user_type": "all"
        },
        "published_at": "2024-01-01T10:00:00Z",
        "expire_at": "2024-02-01T00:00:00Z",
        "stats": {
          "sent_count": 12800,
          "read_count": 6400,
          "read_rate": "50%"
        }
      }
    ]
  }
}

创建公告

POST /admin/v1/messages/announcements

{
  "title": "系统维护通知",
  "content": "平台将于 2024-01-10 02:00-04:00 进行例行维护，期间服务不可用。",
  "priority": "high",
  "target": {
    "user_type": "all",
    "membership_levels": []
  },
  "expire_at": "2024-01-11T00:00:00Z"
}

编辑公告

PUT /admin/v1/messages/announcements/{announcement_id}

删除公告

DELETE /admin/v1/messages/announcements/{announcement_id}

发布公告（立即或定时）

POST /admin/v1/messages/announcements/{announcement_id}/publish

{
  "publish_at": null
}

publish_at 为 null 表示立即发布，传入未来时间表示定时发布。

撤回公告

POST /admin/v1/messages/announcements/{announcement_id}/unpublish

公告触达统计

GET /admin/v1/messages/announcements/{announcement_id}/stats

{
  "code": 0,
  "data": {
    "sent_count": 12800,
    "read_count": 6400,
    "read_rate": "50%",
    "by_user_type": {
      "personal": { "sent": 10000, "read": 5200 },
      "enterprise": { "sent": 2800, "read": 1200 }
    }
  }
}

13-message-center-api.md