实时通知与 AI 助手

通知与 AI 使用同一套前端，但连接方式不同。通知用 EventSource 接收刷新信号；AI 用 fetch 发起带 JSON 与 Bearer 头的流式 POST。

通知链路

登录后请求 POST /api/v1/notifications/stream-token 获取短期令牌。
建立 GET /api/v1/notifications/stream?streamToken=...。
接收 connected、心跳与 notification 事件。
收到信号后重新查询收件箱和未读统计。

通知事件不是离线消息重放队列。持久化收件箱是通知内容的依据，断线后通过查询补齐。多实例使用 Redis Pub/Sub 广播已提交通知的刷新信号，Pub/Sub 故障或断线期间不保证每条信号送达。

生产持久配置 app.notification.stream-token-secret，同一部署的所有实例保持相同且至少 32 字节；不同环境隔离 Redis、前缀和频道。

启用 AI 助手

在外置开发或生产 YAML 中填写：

yaml

art:
  ai-assistant:
    api-key: "填写客户模型密钥"
    base-url: https://api.deepseek.com
    chat-endpoint: /chat/completions
    model: deepseek-chat

示例对应当前默认模型适配方式，实际地址、模型与凭据须匹配供应商账号。最终 URL 由 base-url 与 chat-endpoint 组合，不要重复拼接路径。修改后重启；Docker 执行 sh scripts/deploy.sh config。

不填写密钥时其他模块仍可启动，AI 接口返回 503。Java 使用 JDK HttpClient 代理兼容流式聊天的模型服务，不依赖独立 AI 服务进程。

配置后如何确认可用

进入管理端 AI 助手发送一条简短问题。正常情况下，文字应逐步显示；若最后才一次出现，优先检查代理缓冲。浏览器 Network 中对应请求应为流式响应，观察 meta、delta、done 或 error 事件。

修改显示名称只影响界面；真正切换供应商要一起修改地址、接口路径、模型和密钥。供应商账号可调用的模型以客户实际服务为准。

第一次验证通知

用有发布权限的账号向一个实际测试用户发布通知，再用该用户查看收件箱和未读数。实时信号负责提醒刷新，收件箱负责保存内容；断线后重新进入收件箱仍应能查询已持久化通知。

HTTP 与事件

POST /api/v1/ai-assistant/chat/stream 接收 messages，使用现有 Bearer Token。有效登录账号可使用，不增加角色权限门槛；停用、删除账号不能调用。

事件	主要字段	前端用途
`meta`	provider、label、model	模型显示信息
`delta`	content	增量追加正文
`ping`	ts	保持连接
`done`	content、finishReason	完整回复与结束
`error`	message	已建流后的失败提示

Java 当前公开安全配置不要求请求签名，前端自动跳过签名头，仍携带 Authorization。请求签名与 SSE 连接不是互相替代关系。

建流前鉴权、参数、配置或限流错误返回实际 HTTP 400/401/429/503；建流后的上游错误通过 error 事件结束。排查时不能只看 HTTP 200。

上下文与资源限制

请求接受 user/assistant 消息，数量 1–20，每条最多 4000 字符；服务端添加系统提示。默认总会话超时 120000 毫秒、心跳 15000 毫秒，每实例最多 8 条并发 AI 流，超限直接返回 429，不排队。

可调整 max-context-messages、request-timeout-ms、heartbeat-ms、max-concurrent-streams 与 max-output-chars。字符上限不是模型 token 配额，容量需结合上游限额与实例资源验证。

AI 助手只提供对话，不执行业务操作、不读取业务表，也不保存对话历史；conversationTitle 兼容接收但不持久化。Java 不包含 AI 代码生成器。

网关与排障

流式响应应为 text/event-stream，代理关闭缓冲并允许超过心跳间隔的空闲连接。AI 一直挂起时检查是否收到 meta、delta 或 error；所有内容最后一次性出现时先查代理缓冲。

问题	优先核对
通知 401	短期令牌申请、过期与多实例密钥一致性
收不到通知	收件关系、事件信号和收件箱查询
AI 503	密钥、模型与上游连接配置
AI 429	实例并发上限和供应商额度
回复中断	客户端取消、代理超时、上游错误与会话总超时

源码入口：notifications/controller/NotificationController、NotificationStreamTokenService、NotificationRealtimeService；AI 位于 aiassistant/controller、AiChatStreamService。前端解析见流式请求。

实时通知与 AI 助手 ​

通知链路 ​

启用 AI 助手 ​

配置后如何确认可用 ​

第一次验证通知 ​

HTTP 与事件 ​

上下文与资源限制 ​

网关与排障 ​