API 参考 / notifications

我的通知列表

GET /api/v1/notifications · listNotifications

返回当前登录用户在当前项目的站内通知（事件流 × 相关人的 per-user 物化投影），按创建时间倒序（最新在前）。 通知是 per-user 私有：actor 只来自 session，无法读取他人的通知。unreadOnly=true 只返回未读； response.unreadCount 恒为该用户当前未读总数（铃铛红点用），不受分页/过滤影响。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

unreadOnly
boolean
limit
integer

响应字段 · 200

items（必填）
Notification[]
items[].id（必填）
string
items[].type（必填）
enum —— 通知类型（投影规则）：work_item_assigned=指派给我的工作项变更；requirement_owned=我负责的需求状态流转；schedule_shifted=传播影响我的排期；mentioned=@提及我；project_takeover=项目接管；work_item_routed=轮到我处理；milestone_risk=里程碑风险（知会级，深链 /milestones/:id）；generation_job_updated=组织级 Blueprint 生成任务需要关注。；取值：work_item_assigned / requirement_owned / schedule_shifted / mentioned / project_takeover / work_item_routed / milestone_risk / generation_job_updated
items[].read（必填）
boolean
items[].eventType（必填）
string —— 触发通知的领域事件 type（如 work_item.updated）。
items[].actorId
string —— 触发该事件的用户 id（谁做的）。
items[].actorName
string —— 触发者的可读显示名（投影时经控制面解析，邮箱 local-part 兜底）。解析不到时为空串，前端据此降级构句（不伪造）。
items[].subjectType
enum —— 深链目标对象类型（回跳相关对象用）。；取值：requirement / work_item / milestone / generation_job
items[].subjectId
string —— 深链目标对象 id。项目对象通常为业务库 uuid；generation_job 为控制面 genj_* id。
items[].commentId
string —— mentioned 通知对应的评论 id，取自 comment.created 事件 payload.id；历史通知与非 mentioned 通知缺省，消费方降级到宿主讨论列表。
items[].title
string —— 人读摘要（如工作项 displayKey / 标题）。
items[].fromStatus
string —— 状态流转类通知的旧状态（取自事件 payload.fromStatus，状态名/key）。非流转类通知为空。
items[].toStatus
string —— 状态流转类通知的新状态（取自事件 payload.toStatus，状态名/key）。非流转类通知为空。
items[].toBucket
enum —— 新状态的语义桶（供状态 chip 取桶色）。投影时按 toStatus 查工作流状态节点的 semantic_category 解析；解析不到（无绑定工作流 / 旧状态）时为空，前端降级为纯文本状态、不渲染桶色 chip。；取值：backlog / unstarted / started / completed / canceled / triage / duplicate
items[].fromDate
string —— 排期变动类通知（schedule_shifted）的旧到期日（ISO date，取自 work_item.schedule_shifted 事件 payload.beforeDueOn）。非排期变动类通知为空，前端据空值降级为不带日期的排期调整句、不伪造日期。
items[].toDate
string —— 排期变动类通知（schedule_shifted）的新到期日（ISO date，取自事件 payload.afterDueOn）。fromDate/toDate 均非空时前端渲染「『{对象}』排期调整：{旧}→{新}」。
items[].projectId
string —— 通知所属项目 id。项目内 /notifications 端点也回填，供中央面 /me/notifications 跨项目聚合时区分来源项目。
items[].orgId
string —— 组织级控制面通知所属组织 id。generation_job_updated 必填，其余类型为空。
items[].draftId
string —— Blueprint 生成任务所属草案 id。generation_job_updated 必填，其余类型为空。
items[].subdomainPrefix
string —— 通知所属项目的子域前缀，供中央面 /me/notifications 聚合结果构建跨子域深链绝对 URL；项目内 /notifications 端点不回填（同域，无需）。
items[].projectName
string —— 通知所属项目的显示名。project_takeover 句式「{操作人} 接管了项目「{项目}」的{职责}」（稿 L4701）取此字段；其余类型可为空。
items[].dutyName
string —— project_takeover 专用：被接管的职责名（如「管理员职责」），投影时按接管授予的角色解析。非接管类通知为空。
items[].riskCount
integer —— milestone_risk 专用：该里程碑当前风险项计数，句式「里程碑「{名称}」存在风险项 {N} 个」（稿 L4700）取此字段。非风险类通知为 0/缺省。
items[].createdAt（必填）
string
unreadCount（必填）
integer —— 该用户当前未读通知总数（铃铛红点用），不受分页/过滤影响。

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/notifications?unreadOnly=…&limit=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "type": "work_item_assigned",
      "read": true,
      "eventType": "示例文本",
      "createdAt": "示例文本"
    }
  ],
  "unreadCount": 1
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…