Console 顶栏铃铛未读角标在审批处理完成后不更新

[baozhoutao]

现象

在 Console 审批中心 /_console/apps/<app>/system/approvals:「待我审批」有 1 条,点击【同意】处理完成后,列表正确刷新为空(显示「暂无请求」),但页面右上角顶栏铃铛图标的红色未读角标仍显示 1,不随之更新。刷新页面后依旧为 1,直到用户手动「全部已读」。

• 平台版本:@objectstack/* 17.1.0(项目依赖锁定版本)
• 复现项目:steedos-labs/os-project-titanwind-ehr#1684(含截图)

项目侧已排查(证据在上面项目 issue 的归属排查评论里)

• 审批中心页面、顶栏铃铛组件、未读计数均为平台 Console SPA 实现,项目仓库无相关代码;
• 实测抓包:角标数 = Console 前端直查 sys_inbox_message + sys_notification_receipt(filter channel=inbox)在前端 join 出的未读收件箱消息数;
• 「同意」由平台 approvals API 执行;「标记已读」走平台服务端路由 POST /api/v1/notifications/read(MessagingService.markRead() 系统上下文写回执),项目对回执表仅有读权,无从修复。

请平台确认根因(二选一)

1. 前端缓存 bug:若角标语义是「待审批数」,则审批处理后角标缓存未失效(列表数据已刷新、角标未刷新);
2. 语义/机制缺口(现象更像这种):角标语义本是「未读收件箱消息数」,该未读项是业务侧经 MessagingService.emit() 推送的「…待审批」站内消息;审批完成后平台无任何机制将关联 inbox 消息标已读/撤回,角标恒挂。

判别方法(点【同意】后不刷新页面直查库):

SELECT im.title, r.state FROM sys_inbox_message im
LEFT JOIN sys_notification_receipt r ON r.notification_id = im.notification_id
WHERE im.user_id = '<审批人id>';

仍有 state != 'read' 且标题为「…待审批」的行 → 情形 2;收件箱干净而角标仍 1 → 情形 1。

诉求

• 明确角标的产品语义(未读消息数 vs 待办审批数);
• 若为情形 2:建议审批完成时联动 markRead/recall 对应 inbox 消息,或将 MessagingService.markRead()/recall() 开放给插件调用——否则任何经 emit() 推「待审批」类消息的项目都会遇到同一问题(该项目 30+ 处业务 Hook 走此扇出点);
• 若为情形 1:请修复角标缓存失效逻辑。

关联

• 项目侧复现与归属排查:steedos-labs/os-project-titanwind-ehr#1684
• 同链路历史问题(项目侧记录):铃铛恒 0(内建表未授权)、通知红点不消失(is_read 回写 403)

[os-zhuang]

Triage: routed to the decision inbox (needs-user-decision, domain:services, type Feature). Root-cause determination is already decisive from the card's own evidence: the badge survives a full page reload, so this is Case 2 (no server-side linkage marks the business-emitted inbox message read) — a frontend cache cannot survive a reload. The fix is therefore not a repair but a surface decision: either open MessagingService markRead/recall to plugin callers, or give approvals-linked notifications a lifecycle. Both expand public API, which is the manual floor. Chinese four-facet analysis below.

os-decision-facets(四棱卡面块;标记按字面文本写入)

一句话问题:业务插件能往用户的站内收件箱推「待审批」消息,却没有任何合法途径在审批办完后把这条消息标已读 —— 于是铃铛红点永远挂着,用户被训练成「红点不可信」,真正的新消息也没人看了。

选项与真实代价:

• A. 把 markRead/recall 开放给插件调用(带权限约束:只能动自己 emit 的消息):业务上 = 推消息的人自己负责收尾,30+ 处业务 Hook 当天就能修;像邮件系统给发件人一个「撤回」按钮。真实代价:公开 API 面 +2,永久维护义务;要防插件越权动别人的消息。
• B. 审批完成时平台自动联动(approvals 模块办结时按 related_to 撤销关联 inbox 消息):业务上 = 项目零改造,平台包办。真实代价:平台要能识别「哪条消息关联哪张审批单」—— 业务侧 emit 时若没写关联字段,平台无从联动;等于还得先定义一个关联契约,面更大。
• C. 角标语义改为「待办审批数」:业务上 = 换语义绕开问题。真实代价:铃铛本来就是收件箱语义,改语义动的是所有非审批消息的展示,波及面最大。
• D. 不动:业务上 = 客户验收测试员每次都要手动「全部已读」,红点失去信号价值。

四棱:

• ① 项目长远合理性:A 是最小正交能力(谁 emit 谁可收尾),契约清楚;B 需要新的消息-单据关联契约,C 改既有语义,都更重。
• ② 实际业务拉动:真实客户项目(EHR,17.1.0)当场撞上,30+ 处业务 Hook 同款;此前同链路已出过两单(内建表未授权、is_read 回写 403),说明「插件推送后无法管理生命周期」是成型的缺口,不是孤例。
• ③ 防 AI 犯错:A 给 AI 写业务 Hook 时一条可机械遵守的完整模式(emit 时留 handle,办结时 markRead);B 的隐式联动是 AI 猜不到的魔法,联动条件差一个字段就静默失效。
• ④ 创业阶段不扩散:A 面最小且有真实拉动;但它仍是公开 API 扩面,按聚焦原则需要你点头,不宜代裁。
• 推荐:A(回退:D + 文档写明「emit 的消息目前无法程序化标已读」,把缺口讲诚实)。回一个字母即可。

置信缺口(本分析看不见什么):MessagingService.markRead 现有实现是否已按 user_id 天然隔离(若是,A 的越权防护近乎免费);项目侧 emit 时是否已带 related_to 关联字段(若普遍带,B 的联动契约成本比估计低)。裁后执行:A 则立 services 卡(API + 权限约束 + 回执写路径实测)并回链项目单;objectui 侧另核角标是否需在 markRead 后即时刷新(小卡,随裁定补)。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: Option A — open MessagingService.markRead()/recall() to plugin callers, constrained to one's own messages: a plugin may only mark-read/retract inbox messages it emitted itself, so the emitter is responsible for closing out its own notifications (emit with a handle, mark-read/recall on completion). This confirms the root cause as Case 2 (a semantic/mechanism gap — no server-side linkage marks the business-emitted inbox message read — established by the badge surviving a full reload), not a frontend cache bug. Options B (implicit platform-side linkage), C (changing the badge semantics), and D (do nothing) are not taken. Per triage's post-ruling plan: the services card covers the API, the permission constraint (verify whether markRead already isolates by user_id), and a measured receipt-write path, with a backlink to the reporting project issue; a small objectui follow-up checks whether the badge refreshes immediately after markRead.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code

[os-sam]

Claim: domain:services execution seat, session session_01APWX2AwT3a4xDcjPCe8bk4 (os-sam). Branch claude/issue-10753-messaging-markread-plugin-callers. R5 batch.

pm:queue → pm:dispatched + needs:contract-review + assigned in one write, before this comment. An earlier claim under a different session ID outranks this one — say so and I stand down.

Decision re-read done, both comments. The maintainer ruling (5377365787, 2026-08-22, decision-inbox digest, verbatim 「接受所有」) is the non-relitigable frame:

Option A — open MessagingService.markRead()/recall() to plugin callers, constrained to one's own messages: a plugin may only mark-read/retract inbox messages it emitted itself, so the emitter is responsible for closing out its own notifications.

Options B (implicit platform-side linkage via related_to), C (changing the badge to "pending approvals" semantics) and D (do nothing) are not taken — ⛔ do not re-argue them, and do not reach for B's linkage contract as a shortcut.

Root cause is settled and must not be re-diagnosed: Case 2, a mechanism gap, not a frontend cache bug — established by the badge surviving a full page reload.

Triage's post-ruling plan, carried into the dispatch:

• The API, plus the permission constraint — and the first thing to establish is whether markRead already isolates by user_id. Triage flagged this as an open confidence gap: if it does, the cross-plugin guard is nearly free; if it does not, the guard is the substance of the card, not a detail.
• A measured receipt-write path, not an asserted one.
• A backlink to the reporting project issue.
• ⛔ The objectui half (does the badge refresh immediately after markRead) is a separate small card, not this one. Do not reach into the sibling repo.

Clause-②: yes — judged from card content, not paths: this widens the public API surface, which triage named as the manual floor for both A and B. ⛔ Draft and stays draft; needs:contract-review on card and PR; this seat will not flip ready, will not enqueue, will not arm auto-merge, and will not clear the label. This seat measures at claude-opus-5, below CONTRACT_REVIEW_TIER.

---

Generated by Claude Code

[os-sam]

os-dev-report

{
 "issue": 10753,
 "status": "needs_decision",
 "branch": "claude/issue-10753-messaging-markread-plugin-callers",
 "pr": null,
 "premise_still_valid": true,
 "user_id_isolation_finding": "YES for recipient-scoping, NO on the axis this card needs. markRead(userId, ids) (packages/services/service-messaging/src/messaging-service.ts:497) keys every receipt read/write on the caller-supplied userId — upsertReadReceipt where = (notification_id, user_id, channel:'inbox') at :614, listInbox where = (user_id) at :378 — so one call can only touch the named user's receipts. But userId is a plain parameter, not an authenticated context: the only production caller (packages/runtime/src/domains/notifications.ts:144,:198) binds it to the session user, while an in-process plugin can pass any userId. And the isolation that exists is by RECIPIENT, not by EMITTER: nothing anywhere records who emitted a message, so the ruled constraint 'only messages it emitted itself' has zero existing support. Triage's hoped-for 'nearly free' is false in the direction that matters.",
 "guard_mechanism": "Does not pre-exist — it would have to be invented, which is the dispatch's named stop condition. Measured absences: (1) sys_notification carries only topic/payload/severity/dedup_key/source_object/source_id/actor_id/created_at (packages/platform-objects/src/audit/sys-notification.object.ts); writeEvent (messaging-service.ts:822) writes nothing identity-shaped beyond actor_id, which is 'user who caused the event', not the emitting plugin. (2) sys_inbox_message likewise has no emitter column (packages/services/service-messaging/src/objects/inbox-message.object.ts). (3) EmitInput has no emitter field. (4) The kernel hands every plugin ONE shared PluginContext (packages/core/src/kernel.ts:65,:91) — getService carries no caller identity, so a kernel-derived emitter id does not exist today either. Any guard therefore needs a new provenance field on sys_notification (a platform object in packages/platform-objects — outside the declared carrier) plus an EmitInput widening. Options and recommendation in open_questions.",
 "summary": "Step 0 stop, per the dispatch's own instruction. The ruling's frame is confirmed (premise valid): the mechanism gap is real, recall() does not exist, and nothing links completion to the emitted message. But the guard the ruling constrains the surface with — 'a plugin may only act on messages it emitted itself' — has no existing field to key on, on any row, and no trustworthy caller identity exists in the DI. Building it means adding a provenance column to the engine-owned platform object sys_notification (packages/platform-objects, outside this card's declared file surface) and widening EmitInput — the exact shape the dispatch says the PM seat must re-grade rather than have me fold in silently. No code was written; the branch was pushed empty as the write probe and is ready for the follow-up round.",
 "tests": "None run — no code written. Step 0 was a source measurement; every claim above carries file:line. Gates not run: zero diff on the branch.",
 "files_touched": [],
 "ablation": "Not applicable — no code written. (Reporting the template field honestly rather than fabricating a prediction.)",
 "unread_count_moves": "Not measured — the receipt-write path that would move it is exactly the undecided surface. The count mechanism itself was verified server-derived: listInbox unreadCount is a true total over sys_inbox_message joined with sys_notification_receipt (messaging-service.ts:370-458), consistent with the badge surviving reload (Case 2 confirmed, not re-diagnosed).",
 "gates": "Not run — empty branch, no diff to derive a gate union from.",
 "open_questions": [
 {
 "question": "Q1 (the substance): what emitter identity keys the 'own messages' guard?",
 "options": [
 "A1 — self-declared emitter handle: optional `emitter` on EmitInput, persisted as `emitter_id` on sys_notification; new plugin-facing markRead/recall verify the stored emitter_id matches the presented one; mismatch (including legacy NULL rows) refused 403 + PERMISSION_DENIED (standard ADR-0112 catalog, no new ledger entry) with the mismatch named. Costs: +1 EmitInput field, +2 methods, +1 column on one engine-owned table — but that table lives in packages/platform-objects, outside this card's carrier.",
 "A2 — kernel-minted per-plugin identity: per-plugin contexts or a scoped service factory binding the messaging facade to the consuming plugin's registered name. Costs: re-architects core's single shared PluginContext (kernel.ts:65) across every plugin — core-package blast radius for a guard whose adversary is accidental misuse by trusted in-process code.",
 "A3 — no persisted identity; holding the notificationId IS the capability. Zero schema cost but unenforceable: notification ids are readable platform-wide (sys_notification enable.apiMethods ['get','list'], and every recipient's listInbox exposes them), so 'a different plugin cannot act' has no refusal to pin — fails the ruling's own verification bar."
 ],
 "recommendation": "A1, on all four axes. Real business need: the reporting EHR pattern is emit-in-a-hook → close-out-in-a-later-hook; a stable self-declared handle serves it exactly, and nothing in the card needs cryptographic identity. Long-term soundness: honest about the trust model — in-process plugins already hold the data engine and can write receipts directly, so this guard is a discipline boundary against accidental cross-plugin interference, not a security boundary; A1 says so, enforces at the service, and refuses loudly per ADR-0112 with no consumer fallbacks. AI-safety: one mechanical pattern for AI-written hooks (emit with emitter, keep notificationId, close out with the same emitter), and the failure A1 admits — a mistyped own-id — fails LOUDLY at close-out, never silently; A3 fails this axis outright, A2 buys marginal safety at core-rework cost. Startup scope: A1 is the minimal surface; A2 is unjustified by the threat model. What forces this to a decision instead of a PR: the emitter_id column on sys_notification is a provenance column on a platform object outside the declared carrier — the dispatch's named re-grade shape — plus legacy rows (NULL emitter_id) become closeable by nobody, acceptable under the pipeline's 90d retention but worth ruling out loud."
 },
 {
 "question": "Q2: recall() semantics — it does not exist anywhere today (Zone-2 assumption #1 is half false), so its meaning must be defined, not opened.",
 "options": [
 "(a) hard retract: delete the notification's sys_inbox_message rows and cancel its pending/unclaimed inbox deliveries in the outbox; receipts become inert. Already-sent external channels (email/sms) are out of reach and the contract says so — recall retracts what the platform still holds. Badge AND list entry go away.",
 "(b) soft retract: upsert 'dismissed' receipts for all recipients — the message stays listed, marked read."
 ],
 "recommendation": "(a) — it is what 撤回 means to the user who filed the card; (b) is markAllRead wearing a different name."
 },
 {
 "question": "Q3: does the plugin-facing surface need a spec/contracts declaration?",
 "options": [
 "Implementation-first: land the surface + exported types entirely in service-messaging; consumers keep today's measured pattern (per-package structural surfaces over getService('messaging') — ApprovalMessagingSurface, plugin-approvals/src/approval-service.ts:146; MessagingServiceSurface, service-automation notify-node). No spec edit.",
 "Also declare the emitter-scoped trio on INotificationService (packages/spec/src/contracts/notification-service.ts) — but spec has zero ownership in this lane, so this is a second re-grade."
 ],
 "recommendation": "Implementation-first (创业阶段聚焦; the DIP contract can follow under the PR's already-mandated contract review), declared here rather than discovered later."
 }
 ],
 "surprises": [
 "recall() does not exist anywhere on MessagingService or the messaging domain — the dispatch's Zone-2 assumption #1 ('exposes markRead() and recall() today') is half false; recall must be designed from scratch.",
 "markRead is already technically reachable by EVERY plugin via the shared getService('messaging') — today's gap is the INVERSE of the ruled constraint: any plugin can mark any user's messages read, unconstrained and undeclared. The ruled surface is therefore both an API widening (declared) and the first tightening of in-process power on this path (enforced).",
 "The kernel has a single shared PluginContext for all plugins (core/src/kernel.ts:65,:91) — no per-plugin identity exists anywhere in the DI, which is what makes every non-self-declared identity design expensive."
 ],
 "out_of_scope_findings": []
}

Generated by Claude Code

---

Generated by Claude Code