fix: align private and channel update semantics

(cherry picked from commit c65f76f56278f74082c4fa792ed49104d5d33c38)

docs/channel-module.md

@@ -38,7 +38,7 @@ Date: 2026-06-01
 - `channels.setStickers`：files/sticker store 未接入前只允许 megagroup `inputStickerSetEmpty` 清空 no-op 兼容；非空 sticker set 返回 `STICKERSET_INVALID`，避免 TDesktop 误以为群贴纸集已持久化。`channels.reorderUsernames/toggleUsername/deactivateAllUsernames` 仍先做权限校验型兼容响应；Fragment/多 username 入口不改主 username，主 username 只允许 `channels.updateUsername` 设置或清除。
 - TDesktop 已有调用证据但非首批真实业务的入口统一注册为显式 stub：`channels.reportSpam/editLocation/convertToGigagroup/reportAntiSpamFalsePositive/setBoostsToUnblockRestrictions/setEmojiStickers/checkSearchPostsFlood/setMainProfileTab`。`channels.searchPosts` 已提升为公开频道/超级群帖子真实搜索，`checkSearchPostsFlood` 仍保持免费额度兼容 stub；二者共享 query 长度边界。`setBoostsToUnblockRestrictions` 按 Layer225 限制 0..8。`channels.restrictSponsoredMessages/updatePaidMessagesPrice/toggleAutotranslation` 已提升为最小真实设置持久化：分别回填 `ChannelFull.restricted_sponsored`、`Channel/ChannelFull.send_paid_messages_stars` + broadcast `Channel.broadcast_messages_allowed`、`Channel.autotranslation`，其中 `updatePaidMessagesPrice` 按 TDesktop 默认 app config 限制 stars<=10000，并允许 broadcast direct messages 用 `-1` 表示关闭；真实广告投放、boost/premium 校验、paid messages/monoforum/结算后续补。`channels.exportMessageLink`、`channels.readMessageContents`、`channels.getMessageAuthor`、`channels.deleteParticipantHistory`、`getInactiveChannels`、`getChannelRecommendations`、`toggleJoinToSend`、`toggleJoinRequest`、`toggleParticipantsHidden`、`toggleForum`、`toggleViewForumAsMessages`、`toggleAntiSpam`、`getLeftChannels`、`getGroupsForDiscussion`、`setDiscussionGroup` 已从该列表提升为真实实现。
 - `channels.getGroupsForDiscussion/setDiscussionGroup` 真实维护 broadcast channel 与 megagroup 的双向 `linked_chat_id`。候选列表只返回当前用户可管理的 supergroup，不返回 legacy basic group；设置时校验 access_hash、broadcast/group 类型、管理权限与 hidden prehistory，替换链接会同步清理旧 group/old broadcast，TDesktop 通过 `Channel.has_link` 和 `ChannelFull.linked_chat_id` 刷新讨论组入口。linked broadcast 发新 post 时会在 discussion megagroup 创建一条 forwarded root message，source post 保存 `discussion_channel_id/message_id`，`messages.getDiscussionMessage/getReplies/readDiscussion` 都映射到该 root 和 target channel read state。
-- TDesktop 已有源码调用但当前业务模型尚未维护独立 media/sticker/custom-emoji/saved-message tag assignment/poll/todo/scheduled 的 `messages.reportSpam/report/reportReaction/reportMessagesDelivery/reportReadMetrics/reportMusicListen/reportSponsoredMessage/getSavedReactionTags/updateSavedReactionTag/getDefaultTagReactions/getExtendedMedia/getAttachedStickers/getCustomEmojiDocuments/searchStickerSets/searchStickers/getEmojiKeywords/getEmojiKeywordsDifference/sendVote/getPollResults/getPollVotes/addPollAnswer/deletePollAnswer/getUnreadPollVotes/readPollVotes/appendTodoList/toggleTodoCompleted/getSearchCounters/getSearchResultsCalendar/getSearchResultsPositions/getOnlines/getWebPagePreview/uploadMedia/sendMedia/sendMultiMedia/getScheduledHistory/getScheduledMessages/sendScheduledMessages/deleteScheduledMessages` 均显式注册；统一做参数上限、peer 校验和空/零兼容响应，禁止落到未知 RPC。其中 `messages.readMessageContents` 已提升为 private exact-id real-partial：只校验当前账号可见 message box 并向其它 session 推 content-read update，不维护 media/reaction content-read 状态；channel/supergroup 的 `channels.readMessageContents` 会按可见消息 ID 清理当前作者视角的 unread reaction、重算 `channel_dialogs.unread_reactions_count`，并向当前账号 session 推 `updateMessageReactions` 让 TDesktop 立即去掉 dialog reaction 角标；`messages.getMessagesViews` 已维护 channel-scoped views 去重计数并返回 replies/comment 统计；`messages.getUnreadMentions/readMentions` 已维护 channel-scoped unread mention index，readMentions 返回 channel pts；`messages.sendReaction/getMessagesReactions/getMessageReactionsList/getUnreadReactions/readReactions/getRecentReactions/clearRecentReactions/getTopReactions` 已提升为 private + channel/supergroup emoji reaction 最小真实实现：private 写 `private_message_reactions` 并按双端 owner-visible message box 返回/推送 `updateMessageReactions`，channel 写 `channel_message_reactions` 并按消息作者维护 unread reaction 状态，history/getMessages/search 均回填 `message.reactions`，`add_to_recent` 写账号级最近 channel reaction 列表且 get/clear 支持 hash/notModified，`getTopReactions` 按账号使用次数排序并优先用真实 `available_reactions` catalog 兜底；`messages.getSavedReactionTags/updateSavedReactionTag` 已持久化账号级 emoji saved reaction tag 标题并向其它 session 推 `updateSavedReactionTags`，但 peer 维度 count 与 saved-message tag assignment 仍返回空；`messages.getForumTopics/getForumTopicsByID/createForumTopic/editForumTopic/updatePinnedForumTopic/reorderPinnedForumTopics/deleteTopicHistory` 已从纯空响应提升为真实最小 topic store：虚拟 General + root service message topic + bounded delete；`messages.getCommonChats` 已提升为真实共同超级群查询并回填 `users.getFullUser.common_chats_count`；`messages.report` 保持 TDesktop 分步举报 UI 所需的 choose option/add comment/reported 形态但暂不落库；report/metrics/music/sponsored 这类 telemetry 入口只返回 BoolTrue/reported，不写业务状态；TDesktop 资料页 shared media count 会用 `messages.search(limit=0, filter=photo/video/document/url/gif/music/roundVoice/poll)` 取 `messages.channelMessages.count`，当前显式返回空页/count=0，避免纯文本 channel history 污染 photos/videos/files 等计数；search calendar 空结果会回填请求 offset date/id，避免空月份重复拉取；default tag、sticker/custom emoji 与 extended media 均只返回空/notModified 或明确错误，不伪造 paid media 或 tag 绑定状态；poll/todo mutating 入口在缺少媒体 store 时返回可解释错误，不伪造 `updateMessagePoll` 或 todo service message；web preview 返回 `messageMediaEmpty` 且不会抓外网，`sendMedia(inputMediaWebPage)` 降级为纯文本发送，真实 photo/document/poll/album、todo、scheduled store 留待后续模型。
+- TDesktop 已有源码调用但当前业务模型尚未维护独立 media/sticker/custom-emoji/saved-message tag assignment/poll/todo/scheduled 的 `messages.reportSpam/report/reportReaction/reportMessagesDelivery/reportReadMetrics/reportMusicListen/reportSponsoredMessage/getSavedReactionTags/updateSavedReactionTag/getDefaultTagReactions/getExtendedMedia/getAttachedStickers/getCustomEmojiDocuments/searchStickerSets/searchStickers/getEmojiKeywords/getEmojiKeywordsDifference/sendVote/getPollResults/getPollVotes/addPollAnswer/deletePollAnswer/getUnreadPollVotes/readPollVotes/appendTodoList/toggleTodoCompleted/getSearchCounters/getSearchResultsCalendar/getSearchResultsPositions/getOnlines/getWebPagePreview/uploadMedia/sendMedia/sendMultiMedia/getScheduledHistory/getScheduledMessages/sendScheduledMessages/deleteScheduledMessages` 均显式注册；统一做参数上限、peer 校验和空/零兼容响应，禁止落到未知 RPC。其中 `messages.readMessageContents` 已提升为 private real-content-read：清理 owner 侧 `message_boxes.media_unread/reaction_unread`，有变化才生成 durable `updateReadMessagesContents`；channel/supergroup 的 `channels.readMessageContents` 会按可见消息 ID 清理当前作者视角的 unread reaction、重算 `channel_dialogs.unread_reactions_count`，并向当前账号 session 推 `updateMessageReactions` 让 TDesktop 立即去掉 dialog reaction 角标；`messages.getMessagesViews` 已维护 channel-scoped views 去重计数并返回 replies/comment 统计；`messages.getUnreadMentions/readMentions` 已维护 channel-scoped unread mention index，history/getMessages/difference/online update 按 viewer 回填 `mentioned/media_unread`，readMentions 返回 channel pts；`messages.sendReaction/getMessagesReactions/getMessageReactionsList/getUnreadReactions/readReactions/getRecentReactions/clearRecentReactions/getTopReactions` 已提升为 private + channel/supergroup emoji reaction 最小真实实现：private 写 `private_message_reactions` 并按双端 owner-visible message box 返回/推送 `updateMessageReactions`，channel 写 `channel_message_reactions` 并按消息作者维护 unread reaction 状态，history/getMessages/search 均回填 `message.reactions`，`add_to_recent` 写账号级最近 channel reaction 列表且 get/clear 支持 hash/notModified，`getTopReactions` 按账号使用次数排序并优先用真实 `available_reactions` catalog 兜底；`messages.getSavedReactionTags/updateSavedReactionTag` 已持久化账号级 emoji saved reaction tag 标题并向其它 session 推 `updateSavedReactionTags`，但 peer 维度 count 与 saved-message tag assignment 仍返回空；`messages.getForumTopics/getForumTopicsByID/createForumTopic/editForumTopic/updatePinnedForumTopic/reorderPinnedForumTopics/deleteTopicHistory` 已从纯空响应提升为真实最小 topic store：虚拟 General + root service message topic + bounded delete；`messages.getCommonChats` 已提升为真实共同超级群查询并回填 `users.getFullUser.common_chats_count`；`messages.report` 保持 TDesktop 分步举报 UI 所需的 choose option/add comment/reported 形态但暂不落库；report/metrics/music/sponsored 这类 telemetry 入口只返回 BoolTrue/reported，不写业务状态；TDesktop 资料页 shared media count 会用 `messages.search(limit=0, filter=photo/video/document/url/gif/music/roundVoice/poll)` 取 `messages.channelMessages.count`，当前显式返回空页/count=0，避免纯文本 channel history 污染 photos/videos/files 等计数；search calendar 空结果会回填请求 offset date/id，避免空月份重复拉取；default tag、sticker/custom emoji 与 extended media 均只返回空/notModified 或明确错误，不伪造 paid media 或 tag 绑定状态；poll/todo mutating 入口在缺少媒体 store 时返回可解释错误，不伪造 `updateMessagePoll` 或 todo service message；web preview 返回 `messageMediaEmpty` 且不会抓外网，`sendMedia(inputMediaWebPage)` 降级为纯文本发送，真实 photo/document/poll/album、todo、scheduled store 留待后续模型。
 - legacy chat 管理入口 `messages.getChats/getFullChat/addChatUser/deleteChatUser/editChatTitle/editChatPhoto/editChatAdmin/editChatAbout/editChatDefaultBannedRights/editChatParticipantRank` 统一映射到 megagroup/channel 语义；其中 `about` 与 default banned rights 真实持久化，default banned rights 参与普通成员发送和邀请权限校验。`editChatCreator` 已显式注册并校验 peer/user，但账号 2FA/SRP 与所有权转移事务未接入前返回可解释的密码错误，不进入 fallback。
 
 ## Reference Audit
@@ -114,7 +114,7 @@ username 与管理项方面，参考实现 的 `channels.checkUsername` 只校
 
 参考实现 的 `messages.toggleNoForwards` 已实现 channel 路径：先校验 access hash，再发布 `ToggleChannelNoForwardsCommand`，通过 channel 聚合返回 updates；`messages.setChatAvailableReactions` 和 `messages.setChatTheme` handler 仍未实现，但 `ChannelFullReadModel/ChannelFullMapper` 已有 `ReactionType/AvailableReactions/ReactionsLimit` 到 `chatReactions*` 的映射。telesrv 因此不把 reactions 当纯兼容噪声，而是持久化到 channel setting，并在 full channel 中恢复给 TDesktop。
 
-参考实现 对 TDesktop 长尾入口多采用空/BoolTrue 响应：`readMessageContents/reportSpam/setEmojiStickers/getInactiveChannels/getChannelRecommendations/checkSearchPostsFlood/setMainProfileTab` 等直接返回兼容值；`channels.getMessageAuthor` handler 存在但未实现。参考实现 的 `messages.readMessageContents` / `channels.readMessageContents` 会先查当前用户可见消息、过滤 mention/media_unread/reaction 内容状态，再向 not-me 推 `updateReadMessagesContents` 或 `updateChannelReadMessagesContents`；未找到 `channels.getMessageAuthor` 对应实现。telesrv 当前没有 media/reaction content-read 持久表，因此 private 与 channel 都只用现有 exact-id message store 校验可见消息，并把存在的 id 推给当前用户其它在线 session；缺失 id 仍按参考项目返回当前 pts/BoolTrue。`getMessageAuthor` 则按 Layer225/TDesktop monoforum 右键菜单的最小可用语义，只查可见 channel message 的 `SenderUserID` 并返回 user，完整 monoforum 管理员权限留后续模型。`deleteParticipantHistory` 做管理员权限后按固定 page size 分批删除；`searchPosts` 按 参考实现 的 PublicPosts 语义落到本项目公开 username channel_messages 查询，只返回公开频道/超级群文本消息，满页用 `next_rate + offset_peer + offset_id` seek 翻页，付费 flood/限额继续由 `checkSearchPostsFlood` 免费 stub 承接；`getInactiveChannels` 按 TDesktop Premium 限额弹窗消费方式返回当前用户 active 频道/超级群，`dates[i]` 与 `chats[i]` 对齐并按最久未活跃排序；`getChannelRecommendations` 则从空响应提升为公开 broadcast channel 推荐，指定来源时排除 source，无来源时排除当前账号已加入频道；`getGroupsForDiscussion/setDiscussionGroup` 是讨论组链路。telesrv 借鉴其删除边界：按 sender 分页取一批 message id，生成一条 channel delete update，通过 `offset` 提示客户端续删，禁止一次性展开超大历史。
+参考实现 对 TDesktop 长尾入口多采用空/BoolTrue 响应：`readMessageContents/reportSpam/setEmojiStickers/getInactiveChannels/getChannelRecommendations/checkSearchPostsFlood/setMainProfileTab` 等直接返回兼容值；`channels.getMessageAuthor` handler 存在但未实现。参考实现 的 `messages.readMessageContents` / `channels.readMessageContents` 会先查当前用户可见消息、过滤 mention/media_unread/reaction 内容状态，再向 not-me 推 `updateReadMessagesContents` 或 `updateChannelReadMessagesContents`；未找到 `channels.getMessageAuthor` 对应实现。telesrv 已为 private 接入 owner 侧 `media_unread/reaction_unread` 持久状态与 durable `read_message_contents`，channel mention/media unread 则来自 `channel_unread_mentions` viewer-state；channel unread reaction 继续由 `channels.readMessageContents/readReactions` 清理。`getMessageAuthor` 则按 Layer225/TDesktop monoforum 右键菜单的最小可用语义，只查可见 channel message 的 `SenderUserID` 并返回 user，完整 monoforum 管理员权限留后续模型。`deleteParticipantHistory` 做管理员权限后按固定 page size 分批删除；`searchPosts` 按 参考实现 的 PublicPosts 语义落到本项目公开 username channel_messages 查询，只返回公开频道/超级群文本消息，满页用 `next_rate + offset_peer + offset_id` seek 翻页，付费 flood/限额继续由 `checkSearchPostsFlood` 免费 stub 承接；`getInactiveChannels` 按 TDesktop Premium 限额弹窗消费方式返回当前用户 active 频道/超级群，`dates[i]` 与 `chats[i]` 对齐并按最久未活跃排序；`getChannelRecommendations` 则从空响应提升为公开 broadcast channel 推荐，指定来源时排除 source，无来源时排除当前账号已加入频道；`getGroupsForDiscussion/setDiscussionGroup` 是讨论组链路。telesrv 借鉴其删除边界：按 sender 分页取一批 message id，生成一条 channel delete update，通过 `offset` 提示客户端续删，禁止一次性展开超大历史。
 
 参考实现 的 `channels.getAdminLog` 当前返回空结果，但保留了 read model/query 模型：按 `channel_id`、action types、skip/limit 拉取 admin log event。telesrv 采用“有真实 event store、但只实现 TDesktop 首批可见 action”的路线，避免管理入口只能打开空页。
 
@@ -165,9 +165,9 @@ username 与管理项方面，参考实现 的 `channels.checkUsername` 只校
 - `ChannelMember.AvailableMinPts`：当前成员可恢复 channel difference 的 pts 下界；新加入/导入/受邀/重新加入成员初始化为加入前 `channels.pts`，`updates.getChannelDifference(pts=0)` 也会先抬到该值，避免入群前消息类 durable event 泄漏。
 - `ChannelMember.ReadInboxDate`：当前成员最后一次推进 `read_inbox_max_id` 的时间，用于 `messages.getMessageReadParticipants` 返回 `readParticipantDate.date`；不参与 channel pts。
 - `ChannelMember.SlowmodeLastSendDate`：普通成员最近一次成功发言时间，用于服务端按 channel 维度返回 `SLOWMODE_WAIT_X`；creator/admin 不受首批 slowmode 限制。
-- `ChannelMessage`：`ChannelID`、`ID`、`RandomID`、`SenderUserID`、`From`、`SendAs`、`Date`、`EditDate`、`Post`、`Silent`、`NoForwards`、`Body`、`Entities`、`ReplyTo`、`Forward`、`Action`、`Pts`、`Deleted`。
+- `ChannelMessage`：`ChannelID`、`ID`、`RandomID`、`SenderUserID`、`From`、`SendAs`、`Date`、`EditDate`、`Post`、`Silent`、`NoForwards`、`Body`、`Entities`、`ReplyTo`、`Forward`、`Action`、`Pts`、`Deleted`；`Mentioned` / `MediaUnread` 是按当前 viewer 回填的瞬时字段，不是全局消息真值。
 - `ChannelDialog`：当前 user 对 channel 的会话摘要，保存 `FolderID`、`Pinned`、`PinnedOrder`、`TopMessageID`、`ReadInboxMaxID`、`ReadOutboxMaxID`、`UnreadCount`、`UnreadMentions`、`UnreadMark`、`ViewForumAsMessages`、`NotifySettings`。channel message id 是 channel-scoped，跨频道 dialog 排序不能只看 `top_message_id`；统一按 `pinned DESC, pinned_order DESC, top_message_date DESC, top_message_id DESC, channel_id DESC` 排序，并用 `offset_date + offset_id + offset_peer(channel_id)` 做 seek cursor。folder include/exclude/read/archive/type 条件必须在 SQL `LIMIT` 前下推，避免 TDesktop dialogs 翻页重复顶部频道或自定义分组漏掉旧频道。
-- `ChannelUnreadMention`：按 `(user_id, channel_id, message_id)` 保存未读提及，`top_message_id` 支持 thread/topic 级清除；它是 owner 视角状态，不写入 `channel_update_events`，`messages.readMentions` 返回当前 channel pts 供客户端清本地 badge。
+- `ChannelUnreadMention`：按 `(user_id, channel_id, message_id)` 保存未读提及，`top_message_id` 支持 thread/topic 级清除，`media_unread` 表示该未读提及同时对应媒体内容未读；它是 owner 视角状态，不写入 `channel_update_events`，`messages.readMentions` 返回当前 channel pts 供客户端清本地 badge。
 - `ChannelUpdateEvent`：`ChannelID`、`Pts`、`PtsCount`、`Type`、`Date`、`MessageID`、`MessageIDs`、`SenderUserID`、`UserIDs`、`Payload`。
 - `ChannelAdminLogEvent`：`ChannelID`、`ID`、`UserID`、`Date`、`Type`、前后字符串/布尔/整数、前后 participant、相关 message、`Query`；用于 `channels.getAdminLog`，不参与 channel pts。
 
@@ -192,7 +192,7 @@ username 与管理项方面，参考实现 的 `channels.checkUsername` 只校
 | `channel_message_reactions` | hash(`channel_id`) | `(channel_id,message_id,reacted_user_id,reaction)` 当前 reaction 状态，支持 `sendReaction/getMessagesReactions/getMessageReactionsList` |
 | `private_message_reactions` | message id fk | `(private_message_id,user_id,reaction)` 当前私聊 reaction 状态，双端 message box 共享聚合，支持 private `sendReaction/getMessagesReactions/getMessageReactionsList` |
 | `user_saved_reaction_tags` | user_id prefix | 账号级 saved-message reaction tag 标题；支持 `messages.getSavedReactionTags/updateSavedReactionTag`，不承载 message assignment/count |
-| `channel_unread_mentions` | hash(`user_id`) | owner 视角未读提及索引，支持 `messages.getUnreadMentions/readMentions`，不复制 channel message body |
+| `channel_unread_mentions` | hash(`user_id`) | owner 视角未读提及/媒体未读索引，支持 `messages.getUnreadMentions/readMentions`，不复制 channel message body |
 | `channel_update_events` | hash(`channel_id`) | channel pts durable log，供 `updates.getChannelDifference` |
 | `channel_dialogs` | hash(`user_id`) | 当前账号对 channel 的 dialog/read/folder/pin/mute 摘要 |
 | `dialog_drafts` | hash(`user_id`) | user/channel peer 云草稿；支持 forum `top_msg_id`，不复制 channel message |
@@ -213,7 +213,7 @@ username 与管理项方面，参考实现 的 `channels.checkUsername` 只校
 - `channel_messages(discussion_channel_id, discussion_message_id) WHERE discussion_channel_id <> 0 AND discussion_message_id <> 0 AND NOT deleted` 支持 broadcast post 到 discussion root 的反查与排查。
 - `channel_message_viewers(channel_id, message_id, viewer_user_id)` 主键去重；`messages.getMessagesViews` 先按最多 100 个 id 过滤可见 `channel_messages`，只对首次插入的 viewer 更新 `channel_messages.views_count`，不按 viewer 做 count 聚合扫描。
 - `channel_message_reactions(channel_id, message_id, reaction_date DESC, reacted_user_id DESC, reaction_value ASC)` 支持最近 reaction 回填和列表 seek；`(channel_id,message_id,reaction_type,reaction_value,reaction_date DESC,reacted_user_id DESC)` 支持按单个 emoji 过滤，不使用 SQL OFFSET。
-- `channel_unread_mentions(user_id, channel_id, top_message_id, message_id DESC)` 支持当前账号 unread mentions seek；发送时只为解析出的 active/可见/未读成员插入，单条消息最多 100 个候选，清除时单批最多 1000 条。
+- `channel_unread_mentions(user_id, channel_id, top_message_id, message_id DESC)` 支持当前账号 unread mentions seek；发送/编辑时只为解析出的 active/可见/未读成员插入，单条消息最多 100 个候选，清除时单批最多 1000 条；`media_unread` 随同一行保存，供 history/getMessages/getChannelDifference/online update 按 viewer 回填 `message.media_unread`。
 - `channel_update_events(channel_id, pts)` 主键；`(channel_id, pts)` 升序扫描差量。
 - `channel_dialogs(user_id, folder_id, pinned DESC, pinned_order DESC, top_message_date DESC, top_message_id DESC, channel_id DESC)` 支持 dialogs seek；`default_send_as_peer_type/default_send_as_peer_id` 只保存当前 owner 的默认发送身份，不参与列表排序。
 - `dialog_drafts(user_id, date DESC, peer_type, peer_id, top_message_id)` 支持 `messages.getAllDrafts/clearAllDrafts` 有界扫描；draft 内容用 domain JSON 保存，业务层不持有 `tg.*`。
@@ -237,6 +237,16 @@ Redis miss 恢复来源：
 
 分配必须使用 Redis Lua 的初始化+递增原子脚本；批量 delete/clear 这类 `pts_count>1` 的操作必须一次性分配连续 range，PG fallback 也要实现 `NextChannelPtsN(current+count)`，不能用多次读取 `MAX(pts)+1` 模拟。事务失败但 pts 已分配时必须写 `noop` channel update 占位，避免 TDesktop channel PtsWaiter 永久 gap。
 
+## Viewer State / Difference Nudge
+
+`tg.Message.mentioned` 与 `media_unread` 对 channel/supergroup 来说是 viewer-specific 状态，来源只允许是 `channel_unread_mentions` 等 owner 视角 unread 表，不写入 `channel_messages` 全局行：
+
+1. 发送或编辑 channel message 时，RPC 层解析 mention-name entity / `@username`，store 只为 active、可见、未读且不是 sender 自己的成员写 unread mention。带媒体的 mention 同行保存 `media_unread=true`。
+2. `messages.getHistory`、`messages.getMessages`、`updates.getChannelDifference` 与在线 `updateNewChannelMessage/updateEditChannelMessage` 都按当前 viewer 重取 unread mention 状态，再设置 TL `mentioned/media_unread`。未被 mention 的 viewer 看到同一条消息时两个 flag 必须为 false。
+3. `messages.readMentions` 清理当前 owner 的 unread mention 后，后续 history/difference 不再带 `mentioned/media_unread`。编辑移除 mention 会删除旧 unread mention；新增 mention 会补写新 owner 的 unread mention，供在线和离线差量恢复。
+4. 账号级 `updates.getDifference` 不承载 channel message 本体。若请求 date 之后当前用户 active joined channel 有 `channel_update_events`，RPC 层追加计算型 `updateChannelTooLong(channel_id, pts)` nudge，提示 TDesktop 随后调用 `updates.getChannelDifference`；该 nudge 不写 `user_update_events`，不推进账号 pts，也不影响 account difference 连续性。
+5. create/invite/join/leave/import/hide request 等 membership/state 操作即使没有 service message pts，也必须在 RPC response 和在线推送里带 `updateChannel`。megagroup 有可见 service message 时返回/推送 `updateNewChannelMessage` 占 channel pts，同时追加 `updateChannel` 刷新 participant count/self state；broadcast invite/join/leave 不占 channel pts，但仍带 viewer-specific chats 与 `updateChannel`。
+
 ## Create Flow
 
 `messages.createChat`：

docs/compatibility-matrix.md

@@ -126,7 +126,7 @@ status 取值：done(真实实现) / stub(兼容响应) / todo(已发现未实
 | method | status | behavior | note |
 |---|---|---|---|
 | updates.getState | done | real | auth_key+user 维度持久化 update_states；账号级当前 pts 报告**最大连续已提交 pts**（MaxContiguousPts，非 allocator 最大已分配值），避免同设备换号/多账号串差分，也避免越过在途空洞 |
-| updates.getDifference | done | real | 按 user_id 从 user_update_events 拉取 pts 后增量；只返回从客户端 pts 起**连续**的事件（遇在途空洞即截断），超 100 条置 differenceSlice；支持 new_message、read_history_inbox/read_history_outbox（私聊与 channel peer，channel read 映射 updateReadChannelInbox）、edit_message、message_reactions（输出带最新 `message.reactions` 的 affected message + `updateMessageReactions`，并按 viewer 重取最新聚合，避免 TDesktop 离线恢复时本地 message cache 不刷新）、delete_messages、contacts_reset、dialog pinned/order/manual unread、peer_settings、dialog filters/folder peers 与 noop gap；消息事件携带 fwd/reply 所需 users/chats，payload 来自 durable log。**账号级绝不返回 `differenceTooLong`**：已核对 TDesktop 基线 `api_updates.cpp:516`——对账号级 differenceTooLong 只打一行日志、不读 pts 且漏 `setRequesting(false)`，会永久锁死 update 引擎（`:689` 早退，重连/新 session 不可恢复）；落后客户端改用 `differenceSlice` 续传。因此 `user_update_events` **永久保留、不做 retention 裁剪**（对齐 参考实现），详见 docs/performance-audit.md 附录 C |
+| updates.getDifference | done | real | 按 user_id 从 user_update_events 拉取 pts 后增量；只返回从客户端 pts 起**连续**的事件（遇在途空洞即截断），超 100 条置 differenceSlice；支持 new_message、read_history_inbox/read_history_outbox（私聊与 channel peer，channel read 映射 updateReadChannelInbox）、edit_message、message_reactions（输出带最新 `message.reactions` 的 affected message + `updateMessageReactions`，并按 viewer 重取最新聚合，避免 TDesktop 离线恢复时本地 message cache 不刷新）、read_message_contents、delete_messages、contacts_reset、dialog pinned/order/manual unread、peer_settings、dialog filters/folder peers 与 noop gap；消息事件携带 fwd/reply 所需 users/chats，payload 来自 durable log。若请求 date 后存在当前账号 active channel 的 channel durable events，会追加计算型 `updateChannelTooLong(channel_id,pts)` nudge，提示 TDesktop 再走 `updates.getChannelDifference`；该 nudge 不写 `user_update_events`，不消耗账号 pts。**账号级绝不返回 `differenceTooLong`**：已核对 TDesktop 基线 `api_updates.cpp:516`——对账号级 differenceTooLong 只打一行日志、不读 pts 且漏 `setRequesting(false)`，会永久锁死 update 引擎（`:689` 早退，重连/新 session 不可恢复）；落后客户端改用 `differenceSlice` 续传。因此 `user_update_events` **永久保留、不做 retention 裁剪**（对齐 参考实现），详见 docs/performance-audit.md 附录 C |
 | updates.getChannelDifference | done | real-channel | 超级群/频道使用 channel 维度 durable log：`channel_update_events(channel_id, pts, pts_count, ...)`；按 channel pts 返回 `channelDifferenceEmpty/channelDifference/channelDifferenceTooLong`，limit cap=100；`pts < 0` 或 `pts > current_channel_pts` 返回 `PERSISTENT_TIMESTAMP_INVALID`；当前 member 的 `available_min_pts` 会抬高请求 pts，避免新加入/重新加入成员拉到入群前消息类 durable 事件；公共 username 频道允许非成员以只读预览身份拉可见差分并返回 synthetic read dialog，私有频道和禁看用户仍返回权限错误；当 `current_channel_pts-pts > cap` 时返回带当前 dialog pts 和最新有界消息快照的 `channelDifferenceTooLong`，避免大频道旧 pts 客户端循环拉大量页；普通 difference 优先使用事件 payload 中的 message 快照，连续编辑/删除后不会被当前消息状态污染；`updateChannelParticipant` 不进入 channel pts log，成员权限/封禁状态靠在线 `updateChannelParticipant/updateChannel` 与 `channels.getFullChannel/getParticipants/getParticipant` 刷新；本页消息的 sender/send_as/fwd_from/reply_to/action peers 会随 users/chats 返回，禁止复用 user_update_events |
 
 ### 兼容硬约束：pts / pts_count（跨所有产生 update 的 RPC）
@@ -162,9 +162,9 @@ outbox 多 worker 并发 + 发送事务乱序提交 → **主动推送可能乱
 | messages.getMessageEditData | done | real-text-only | 参考实现/参考实现 的编辑前校验语义：按 peer/msg_id 校验消息存在与作者/管理员 edit_messages 权限；当前只支持文本消息编辑，没有媒体 caption 状态，因此返回 `messages.messageEditData{caption=false}` |
 | messages.getWebPagePreview | stub | empty-preview | TDesktop 输入框链接预览入口；参考实现 空预览与 参考实现 空文本校验，`message` trim 后为空返回 `MESSAGE_EMPTY`，entities/text 有界，返回 `messages.webPagePreview{media=messageMediaEmpty}`，不抓取外网、不落缓存 |
 | messages.uploadMedia / messages.sendMedia / messages.sendMultiMedia | done | photo/document/sticker | 接入 files/media 存储（documents/photos/file_blobs + 本地 blob backend）与消息 media 快照列；`resolveInputMedia` 解析 `inputMediaUploadedPhoto/Document`（组装上传分片→建 Photo/Document）与 `inputMediaPhoto/Document`（按服务端 document id 引用已存在资源，含贴纸）→ `domain.MessageMedia`，经 sendOutgoing 走与文本相同的 pts/box/outbox/在线推送/离线 difference；私聊与 channel 均支持；`sendMedia(inputMediaEmpty/WebPage)` 仍降级为纯文本 `sendMessage`；`uploadMedia` 返回可复用 `messageMedia`；sendMultiMedia 各条作为独立消息发送（grouped_id 相册聚合留 todo）；geo/contact/poll/todo/dice/story 等仍返回 `MEDIA_INVALID`；album cap=10，caption/entities/random_id/peer/access_hash 均校验 |
-| messages.readMessageContents | done | real-partial | TDesktop 普通消息内容已读入口；校验 id cap=100、message_id 范围与当前账号 exact 可见私聊消息，对存在消息向当前账号其它在线 session 推 `updateReadMessagesContents`；当前无 media/reaction content-read 持久状态，返回当前账号 affectedMessages 且不生成新 pts |
+| messages.readMessageContents | done | real-content-read | TDesktop 普通消息内容已读入口；校验 id cap=100、message_id 范围与当前账号 exact 可见私聊消息；私聊 incoming media 写入 recipient box 时置 `media_unread`，对端 reaction 写入消息作者 box 时置 `reaction_unread` 并重算 dialog unread reaction 计数。事务内只清理实际 unread 的 message boxes；有变化才分配 user pts、写 durable `updateReadMessagesContents` + dispatch_outbox，其它在线 session 与离线 `updates.getDifference` 可恢复；重复调用/不可见 id/已读 id 返回当前 affectedMessages 且 `pts_count=0` |
 | messages.getMessagesViews | done | real-channel-views | TDesktop 频道浏览计数入口；channel/supergroup peer 校验 access_hash 与 id cap=100，`increment=true` 时按 `(channel_id,message_id,viewer_user_id)` 去重后递增 `channel_messages.views_count`，按请求顺序返回显式 `views` 与 replies/comment context；不存在、删除或本地清历史前不可见的 id 返回空 `messageViews`；forwards 计数与 forwarded-channel source views 透传仍待媒体/转发统计模型补齐 |
-| messages.getUnreadMentions | done | real-channel-mentions | Channel/supergroup peer 维护 `channel_unread_mentions(user_id,channel_id,message_id)` 独立索引；sendMessage 解析 mention-name entity 与 `@username`，写入 active 且可见成员；查询按 user+channel+top_msg_id+message_id seek，limit cap=100，返回 channel context |
+| messages.getUnreadMentions | done | real-channel-mentions | Channel/supergroup peer 维护 `channel_unread_mentions(user_id,channel_id,message_id,media_unread)` 独立索引；sendMessage 解析 mention-name entity 与 `@username`，写入 active 且可见成员；history/getMessages/getChannelDifference/online update 按 viewer 回填 `message.mentioned/media_unread`，readMentions 后同一 viewer 不再带 flag；查询按 user+channel+top_msg_id+message_id seek，limit cap=100，返回 channel context |
 | messages.readMentions | done | real-channel-mentions | Channel/supergroup peer 按 top_msg_id 有界清除 unread mention，单次最多 1000 条，重算 `channel_dialogs.unread_mentions_count`；返回 current channel pts/offset，供 TDesktop channel PtsWaiter 消费 |
 | messages.reportSpam / messages.report | stub | reported-bounded | TDesktop peer bar/消息举报入口；校验 peer/access_hash/message id/option/comment 上限，不落 report 表；`report` 空 option 返回举报原因，`other` 返回 addComment，其余合法 option 返回 reported，非法 option 返回 `OPTION_INVALID` |
 | messages.reportReaction / messages.reportMessagesDelivery / messages.reportReadMetrics / messages.reportMusicListen / messages.reportSponsoredMessage | stub | telemetry-noop | TDesktop 反应举报、Gateway 送达、阅读指标、音乐播放、广告举报入口；校验 peer/access_hash/id vector/metrics/document/duration/random_id 上限后返回 BoolTrue 或 sponsored reported，不落 telemetry/report 表 |
@@ -288,7 +288,7 @@ outbox 多 worker 并发 + 发送事务乱序提交 → **主动推送可能乱
 | channels.updateColor | done | real-appearance | 持久化 `channels.color/profile_color` 与 background emoji id，保留 color flag 显式 0；校验 access_hash + change_info 后返回/推送带 `Channel.color/profile_color` 的 `updateChannel`；boost level 暂不强制，避免本地测试频道外观入口失效 |
 | channels.updateEmojiStatus | done | real-minimal | 支持 `emojiStatusEmpty` 清除与普通 `emojiStatus(document_id,until)` 持久化并输出到 `Channel.emoji_status`；collectible emoji status 缺少 gift/read model 时返回 `EMOJI_STATUS_INVALID`，不伪造 collectible 元数据 |
 | channels.exportMessageLink | done | real-message-link | 校验 channel/access_hash、msg_id 范围和当前成员可见的单份 channel message；公开 channel 返回 `t.me/{username}/{msg_id}`，私有 channel 返回 `t.me/c/{channel_id}/{msg_id}`，`thread=true` 且消息有 reply root 时追加 `?thread={root_id}`；`grouped/html` 与 public discussion `comment=` 精细链接后续补 |
-| channels.readMessageContents | done | real-partial | 校验 channel/access_hash、id vector cap=100 与可见 exact message；对存在消息向当前用户其它在线 session 推 `updateChannelReadMessagesContents`，当前无 media/reaction content-read 持久状态，不生成 pts |
+| channels.readMessageContents | done | real-channel-content-read | 校验 channel/access_hash、id vector cap=100 与可见 exact message；按当前作者视角清理 visible messages 的 unread reaction、重算 `channel_dialogs.unread_reactions_count`，并向当前账号其它 session 推 `updateChannelReadMessagesContents` / `updateMessageReactions` 刷新 TDesktop 角标；不生成 channel pts |
 | channels.reportSpam | stub | ok | 校验 channel、participant 与 id cap=100 后返回 BoolTrue；风控/举报队列后续补 |
 | channels.getLeftChannels | done | real-left-export | TDesktop takeout/export 路径；按当前 user 的 left channel/supergroup membership 返回有界 pageSize=100，offset<=10000，带 full count 与 left channel flag；最终非空页返回 `messages.chats`，越界空页返回空 `messages.chatsSlice` 让导出流程结束 |
 | channels.getInactiveChannels | done | real-least-active | Premium limits 路径；按当前用户 active 频道/超级群的可见 top message date 旧到新返回，dates 与 chats 对齐，limit cap=100；不实现 Premium 限额策略 |
@@ -359,7 +359,9 @@ outbox 多 worker 并发 + 发送事务乱序提交 → **主动推送可能乱
 | contacts.search | done | real | TDesktop 搜索框 peer 分支；strip `@`、空/过短查询报 SEARCH_QUERY_EMPTY/QUERY_TOO_SHORT，limit cap=50；联系人 user 进 MyResults，非联系人 user 进 Results；公开 username channel/supergroup 同步返回 PeerChannel + Chats，当前已加入的放 MyResults，其它公开命中放 Results 并以 left chat 标记只读预览，避免 TDesktop 误显示已加入；用户搜索走手机号前缀/username/姓名/owner 保存姓名索引，公开频道搜索走 username/title trgm 索引 |
 | contacts.resolveUsername | done | real | 按大小写不敏感 username 解析 user 或公开 channel/supergroup peer；channel 返回 PeerChannel + Chats；不存在返回 USERNAME_NOT_OCCUPIED，非法格式返回 USERNAME_INVALID |
 | contacts.resolvePhone | done | real-partial | 按手机号解析 user peer；当前阶段未接完整 privacy，默认已知手机号可解析，未命中返回 PHONE_NOT_OCCUPIED |
-| contacts.getBlocked | stub | empty | Settings 隐私/安全预取；第一阶段无 blocklist，limit cap=50 |
+| contacts.block | done | real-blocklist | 写入当前 owner blocklist，幂等；同步刷新 peer settings，story-only block flag 当前按主 blocklist 处理，完整 stories privacy 留后续 |
+| contacts.unblock | done | real-blocklist | 从当前 owner blocklist 删除 peer，幂等；同步刷新 peer settings |
+| contacts.getBlocked | done | real-blocklist | Settings 隐私/安全预取；`contacts.block/unblock/getBlocked` 维护 `owner_user_id + blocked_user_id` 唯一 blocklist，limit cap=100，按 date/user_id 返回 `peerBlocked` + users；`contacts.getPeerSettings` 按当前 owner block 状态返回 block/unblock action。当前不扩展完整 Telegram privacy key 体系，blocklist 是本阶段 send/edit/delete 的唯一 privacy gate |
 | contacts.getTopPeers | stub | disabled | 第一阶段不维护 top peers 统计 |
 | contacts.getSponsoredPeers | stub | empty | 第一阶段不做 sponsored peers，TDesktop 搜索框分支返回 sponsoredPeersEmpty |
 | users.getUsers | done | real | InputUserSelf 与已知 InputUser 返回用户（含 777000 官方账号）；未登录则跳过（空列表） |

docs/message-module.md

@@ -27,8 +27,9 @@ Date: 2026-05-31
 | table | partition key | purpose |
 |---|---|---|
 | `private_messages` | `sender_user_id` HASH | 共享私聊消息主体；`sender_user_id + random_id` 保证发送幂等 |
-| `message_boxes` | `owner_user_id` HASH | owner 视角消息盒；TDesktop 看到的 message id 即 `box_id` |
+| `message_boxes` | `owner_user_id` HASH | owner 视角消息盒；TDesktop 看到的 message id 即 `box_id`，并保存当前 owner 的 `media_unread/reaction_unread` 内容已读状态 |
 | `dialogs` | `user_id` HASH | 会话摘要；`folder_id=0/1` 表示主列表/归档，置顶、manual unread、action bar 隐藏均是 owner 视角 |
+| `contact_blocks` | `owner_user_id` HASH | 当前 owner 的 blocklist；`owner_user_id + blocked_user_id` 唯一，作为本阶段私聊 privacy gate |
 | `dialog_filters` / `dialog_filter_settings` | `user_id` HASH | TDesktop 自定义 dialog filter、filter 顺序与 folder tags 开关；不把自定义 filter 伪装成 dialogs.folder_id |
 | `user_update_events` | `user_id` HASH | 账号级 pts durable log；承载新消息、已读 inbox/outbox、文本编辑、删除消息，也承载 contacts reset、dialog pinned/order/manual unread、peer settings、dialog filters 与 folder peers 等 owner 视角状态事件 |
 | `dispatch_outbox` | `target_user_id` HASH | transactional outbox，事务后批量推送在线 session；投递成功即删除，仅保留未完成任务 |
@@ -48,7 +49,7 @@ Redis miss 时分别从 `MAX(user_update_events.pts)` 与 `MAX(message_boxes.box
 
 1. 写 `private_messages`，遇到同 `sender_user_id + random_id` 直接返回原消息盒。
 2. Redis 分配 sender/recipient 的 `box_id` 与 `pts`。
-3. 写 sender/recipient `message_boxes`，并保存 `silent/noforwards/reply_to/fwd_from` 元数据；reply 会把当前 owner 的 `reply_to_msg_id` 翻译成对端 owner 视角的 box_id。
+3. 写 sender/recipient `message_boxes`，并保存 `silent/noforwards/reply_to/fwd_from` 元数据；reply 会把当前 owner 的 `reply_to_msg_id` 翻译成对端 owner 视角的 box_id。incoming media 在 recipient box 上置 `media_unread=true`，sender 自己始终为 false。
 4. upsert 双方 `dialogs`。
 5. 写双方 `user_update_events(new_message)`。
 6. 写双方 `dispatch_outbox`，sender 侧带 `exclude_session_id`。
@@ -56,6 +57,8 @@ Redis miss 时分别从 `MAX(user_update_events.pts)` 与 `MAX(message_boxes.box
 
 若事务失败但 Redis 已分配 pts，store 会尽力写 `noop` 事件占位，避免 pts 回退；PG 不可用时该补偿也可能失败，后续需要告警指标覆盖。
 
+如果 recipient 已 block sender，`SendPrivateText` 仍写 sender outbox/dialog/update，保证当前用户能看到自己发出的消息；但不创建 recipient message box、不推进 recipient pts、不写 recipient dispatch_outbox，也不会进入 recipient 离线 `updates.getDifference`。该规则同样适用于 `messages.sendMedia/sendMultiMedia` 和私聊转发，因为它们共用 `sendOutgoing`/`SendPrivateText`。
+
 ## Forward / Reply Flow
 
 `messages.forwardMessages` 当前覆盖私聊文本转发，参考实现 的业务语义但保持 telesrv 的 owner 视角模型：
@@ -80,6 +83,16 @@ Redis miss 时分别从 `MAX(user_update_events.pts)` 与 `MAX(message_boxes.box
 
 `messages.getOutboxReadDate` 复用 sender 侧 durable `read_history_outbox` 事件：先校验当前 owner 的 `msg_id` 是该 peer 下可见 outgoing message，再取最早一条 `max_id >= msg_id` 的 outbox read event 日期返回 `outboxReadDate`；未被读到返回 `MESSAGE_NOT_READ_YET`。PG 上有 `(user_id, peer_type, peer_id, max_id, date) WHERE event_type='read_history_outbox'` partial index，避免 TDesktop 已读详情查询扫全量 update log。
 
+## Content Read Flow
+
+`messages.readMessageContents` 处理 TDesktop 打开媒体/反应等“内容已读”入口，不等同于 history read 水位：
+
+1. 私聊 incoming media 创建 recipient message box 时置 `media_unread=true`；sender 自己为 false。
+2. 私聊 reaction 写入时，若反应者不是原消息作者，会把原作者 owner 视角的 message box 标记 `reaction_unread=true`，并重算该 dialog 的 `unread_reactions_count`。
+3. `readMessageContents` 在事务内锁定当前 owner 的 exact message boxes，只清理 `media_unread OR reaction_unread` 的行；不可见 id、已删除 id、已经 read 的 id 都不生成新 pts。
+4. 实际清理时为当前 owner 分配连续 user pts，写 `user_update_events(read_message_contents)` 与 `dispatch_outbox`，TL 转换为 `updateReadMessagesContents{messages,pts,pts_count}`。重复调用返回当前 affectedMessages，`pts_count=0`。
+5. 该事件排除当前 auth_key/session，其它在线 session 走 reliable outbox，离线设备通过 `updates.getDifference` 恢复。
+
 ## Edit Flow
 
 `messages.editMessage` 当前只支持私聊文本编辑：
@@ -92,12 +105,16 @@ Redis miss 时分别从 `MAX(user_update_events.pts)` 与 `MAX(message_boxes.box
 
 如果文本和 entities 完全未变化，返回 `MESSAGE_NOT_MODIFIED`；非作者编辑返回 `MESSAGE_AUTHOR_REQUIRED`。
 
+若 peer 已 block 当前用户，私聊 edit 会返回 `EDIT_MESSAGES_FORBIDDEN`，避免修改对方侧已存在的 message box。该 gate 只来自 `contact_blocks`；完整 Telegram privacy keys 暂不扩展。
+
 ## Delete Flow
 
 `messages.deleteMessages` / `messages.deleteHistory` 以 owner 视角软删除 `message_boxes`，不会删除共享 `private_messages` 主体。默认 deleteHistory 清空后如果该 peer 已无可见消息，则删除当前 owner 的 dialog；后续任意新消息会通过正常 send/upsert 路径重建 dialog。`just_clear=true` 对齐 参考实现 语义：清空历史但保留一个空 dialog（当前阶段不生成 `messageActionHistoryClear` 服务消息）。
 
 `revoke=true` 时按 `(message_sender_id, private_message_id)` 找到同一私聊消息在其它 owner 下的 message_box 并软删除。每个受影响 owner 都生成自己的 `updateDeleteMessages`，`message_ids` 是该 owner 视角 box_id，`pts_count=len(message_ids)`，并写入 `user_update_events + dispatch_outbox`。如果删除后仍有可见消息，dialog 的 top/unread 会按剩余消息重算；否则删除 dialog 或在 `just_clear` 下保留空 dialog。
 
+若 `revoke=true` 会影响已 block 当前用户的一方，RPC 层返回 `DELETE_MESSAGES_FORBIDDEN`；`revoke=false` 或本地清理仍只影响当前 owner，可继续执行。
+
 全清也必须让所有被删的 owner 视角 message_id 最终进入 update/difference，但不能合成一个超大 update。`messages.deleteHistory` 单次最多删除 `MaxDeleteHistoryBatch=1000` 条，按 box_id 倒序批量软删并返回 `affectedHistory.offset=1` 表示客户端应继续发起下一批；每一批各自产生一条有界 `updateDeleteMessages`。`messages.deleteMessages` 单次 id 数限制为 `MaxDeleteMessageIDs=1000`，服务端还会丢弃 `<=0` 或超过 TL/PG int4 可表达范围的 id。
 
 ## Query Path
@@ -106,7 +123,7 @@ Redis miss 时分别从 `MAX(user_update_events.pts)` 与 `MAX(message_boxes.box
 - `messages.search` / `messages.searchGlobal` 当前只覆盖当前 owner 私聊文本搜索；查询仍限定在 `owner_user_id` HASH 分区内，文本条件由 `pg_trgm` GIN 索引兜底。参考实现 的经验，未接外部全文搜索前禁止无索引大表模糊扫；后续群组/频道/全局多 peer 搜索应接专用搜索索引或 FTS。
 - `messages.getDialogs` 以 `user_id` 分区定位当前账号，再按 `top_message_date/top_message_id/peer_id` 做 seek pagination；folder_id=0/1 直接走 `dialogs.folder_id`，folder_id>=2 先取当前账号 `dialog_filters` 后按 include/exclude/contact 规则过滤；`hash` 与 `count` 基于当前筛选后的完整会话集计算。
 - `messages.getDialogFilters` 返回 `dialogFilterDefault` + 当前账号持久化 filters；`messages.updateDialogFilter/updateDialogFiltersOrder/toggleDialogFilterTags` 与 `folders.editPeerFolders` 都是 owner 视角写入，归档只允许 folder_id 0/1，自定义 filters 从 ID 2 开始。
-- `updates.getDifference` 只按 `user_id + pts` 顺序扫描 `user_update_events`，多设备各自的 `(auth_key_id,user_id)` state 只记录消费位置，不参与账号事件归属；离线设备通过同一条 durable log 恢复新消息、已读 inbox/outbox、文本编辑、删除消息、联系人 reset、dialog pinned/order/manual unread、peer settings、dialog filters/order/reload 与 folder peers 变化，置顶顺序、peer settings flags、filter payload 与 folder peers 会随事件负载持久化。
+- `updates.getDifference` 只按 `user_id + pts` 顺序扫描 `user_update_events`，多设备各自的 `(auth_key_id,user_id)` state 只记录消费位置，不参与账号事件归属；离线设备通过同一条 durable log 恢复新消息、已读 inbox/outbox、内容已读、文本编辑、删除消息、联系人 reset、dialog pinned/order/manual unread、peer settings、dialog filters/order/reload 与 folder peers 变化，置顶顺序、peer settings flags、filter payload 与 folder peers 会随事件负载持久化。
 
 ## 参考实现 Comparison
 
@@ -249,4 +266,4 @@ go test ./internal/loadtest/ -run TestMessageSendBaseline -v -count=1 -timeout 3
 - `private_messages` / `message_boxes` 增 `media` JSONB 快照列：发送在事务内随 body/entities 一起写双端盒子，历史 `getHistory`/`getMessages`/dialog preview 读取时随消息一并解码，无需 join `documents`/`photos`。转发复制源消息 media（同一文档引用）；文本编辑保留 media。
 - `tgMessage` 在 media 非空时 `SetMedia(MessageMediaPhoto/Document)`，客户端经 `upload.getFile` 从 blob backend 下载。Document id 在 domain/store 中保持 telesrv-owned 正数；外部 seed source id 在导入阶段归一，`InputDocument` / `inputDocumentFileLocation` 入站直接按服务端 id 解析，避免把第三方导出 id 当成本服资源身份。
 - 仅媒体消息（无 caption）：放宽 `private_messages` body 非空 CHECK 为 `body<>'' OR media<>'{}'`。
-- 范围外：grouped_id 相册聚合（sendMultiMedia 当前各条独立成消息）、geo/contact/poll/todo/dice/story media 仍 `MEDIA_INVALID`。
+- 范围外：grouped_id 相册聚合（sendMultiMedia 当前各条独立成消息）、geo/contact/poll/todo/dice/story media 仍 `MEDIA_INVALID`。

docs/persistence-layer.md

@@ -58,13 +58,14 @@ DDL 见 [`deploy/migrations/0001_init.up.sql`](../deploy/migrations/0001_init.up
 - **`app_configs`** —— `help.getAppConfig` 的 data-backed JSON config，包含 TDesktop read mark、quote reply 与 native anti-spam 管理入口所需参数。
 - **`countries` / `country_codes`** —— `help.getCountriesList` 的登录页国家区号目录。
 - **`update_states`** —— `auth_key_id + user_id` 维度的设备状态快照。账号级 pts 以 `user_update_events` 为权威，设备退出/换号只清当前 auth_key 状态，不删除账号事件。
-- **`user_update_events`** —— 按 `user_id` HASH 分区的账号级增量事件队列。承载 `new_message`、`read_history_inbox/read_history_outbox`（私聊与 channel peer）、`edit_message`、`delete_messages`、`contacts_reset`、dialog 置顶/顺序/manual unread/peer settings、dialog filter/order/reload、folder peers、channel 本地清空后的 `channel_available_messages`、当前账号 forum 展示模式 `channel_view_forum_as_messages` 与 allocator gap 的 `noop`，供 `updates.getDifference` 和 outbox worker 补偿错过的推送；设置类事件通过 `UpdateEventStore.AppendWithDispatch` 与 `dispatch_outbox` 同事务写入，并持久化 `event_peers` / `peer_settings` / `message_ids` / `dialog_filter` / `filter_order` / `folder_peers` 负载，避免状态只存在在线 push 中。
+- **`user_update_events`** —— 按 `user_id` HASH 分区的账号级增量事件队列。承载 `new_message`、`read_history_inbox/read_history_outbox`（私聊与 channel peer）、`edit_message`、`read_message_contents`、`delete_messages`、`contacts_reset`、dialog 置顶/顺序/manual unread/peer settings、dialog filter/order/reload、folder peers、channel 本地清空后的 `channel_available_messages`、当前账号 forum 展示模式 `channel_view_forum_as_messages` 与 allocator gap 的 `noop`，供 `updates.getDifference` 和 outbox worker 补偿错过的推送；设置类事件通过 `UpdateEventStore.AppendWithDispatch` 与 `dispatch_outbox` 同事务写入，并持久化 `event_peers` / `peer_settings` / `message_ids` / `dialog_filter` / `filter_order` / `folder_peers` 负载，避免状态只存在在线 push 中。account difference 中的 `updateChannelTooLong` channel nudge 是按 channel events + request date 计算出来的提示，不写入本表、不消耗账号 pts。
 - **`contacts`** —— 当前账号通讯录关系与 owner 视角联系人资料。`contact_phone/contact_first_name/contact_last_name/note/note_entities` 均只属于 `(user_id, contact_user_id)`，同一个全局 user 在不同 owner 的通讯录中可以有不同姓名、电话和备注；`mutual` 由双方是否互存维护，删除一方联系人会清理对方 reverse mutual。
+- **`contact_blocks`** —— 当前账号 blocklist，按 `owner_user_id` HASH 分区；`(owner_user_id, blocked_user_id)` 唯一，按 `date DESC, blocked_user_id DESC` 返回 `contacts.getBlocked`。当前 full privacy keys 未接入，私聊 send/edit/delete 的拒绝来源仅为这张表。
 - **`private_messages`** —— 共享私聊消息主体，按 `sender_user_id` HASH 分区；`sender_user_id + random_id` 唯一保证 `messages.sendMessage/forwardMessages` 幂等；文本编辑更新共享 body/entities/edit_date；silent/noforwards/reply_to/fwd_from 元数据随消息持久化。
-- **`message_boxes`** —— owner 视角消息盒，按 `owner_user_id` HASH 分区；每个账号看到自己的 `box_id`、peer、outgoing、pts、edit_date 与删除状态，历史/搜索走该表索引。删除只软删 owner 视角 message_box，`revoke` 通过 `(message_sender_id, private_message_id)` 定位其它 owner 视角并软删；编辑会同步所有可见 owner 视角盒子。该反向定位与分区键不一致，规划会展开全部 owner 分区，后续应增加 unpartitioned box 映射或先推导 owner_user_id 后再按 owner 分区点查。
+- **`message_boxes`** —— owner 视角消息盒，按 `owner_user_id` HASH 分区；每个账号看到自己的 `box_id`、peer、outgoing、pts、edit_date、`media_unread/reaction_unread` 与删除状态，历史/搜索走该表索引。删除只软删 owner 视角 message_box，`revoke` 通过 `(message_sender_id, private_message_id)` 定位其它 owner 视角并软删；编辑会同步所有可见 owner 视角盒子。`messages.readMessageContents` 只锁定当前 owner exact ids 且仅清理 unread 状态为 true 的行，有变化才写 `read_message_contents` durable event。该反向定位与分区键不一致，规划会展开全部 owner 分区，后续应增加 unpartitioned box 映射或先推导 owner_user_id 后再按 owner 分区点查。
 - **`dialogs`** —— 当前账号会话摘要，按 `user_id` HASH 分区；只允许 `user` peer，支持 top message、置顶过滤、folder_id=0/1 主列表/归档与 offset 分页，并保存当前 owner 的 `pinned_order`、manual `unread_mark` 与 `hidden_peer_settings_bar`。列表查询 join `contacts` 时优先返回当前 owner 保存的联系人姓名/电话，避免不同账号看同一 peer 串备注；相关状态变化会写入账号级 durable update log，离线设备可通过 `updates.getDifference` 恢复。
 - **`channels` / `channel_messages` / `channel_message_viewers` / `channel_update_events`** —— 超级群/频道单份消息模型，按 `channel_id` HASH 分区；`channels.pts` 是 channel-scoped durable log 水位，`channels.forum/forum_tabs` 持久化 megagroup topics 开关与 TDesktop tabs/list 布局，`channels.participants_hidden` 持久化隐藏成员设置并由 `ChannelFull.participants_hidden` 恢复 TDesktop UI，`channels.antispam` 持久化 native anti-spam 开关并由 `ChannelFull.antispam` 恢复管理入口，`channels.color_set/color/color_background_emoji_id/profile_color_set/profile_color/profile_color_background_emoji_id/emoji_status_document_id/emoji_status_until` 持久化频道外观并回填 `Channel.color/profile_color/emoji_status`，`channels.linked_chat_id` 维护 broadcast 与 discussion megagroup 的双向链接并走 `channels_linked_chat_idx` 反查，`channel_update_events(channel_id, pts)` 存 new/edit/delete/pin/noop 的恢复负载，成员权限/封禁变化不进入该 log；`channel_messages(channel_id, id)` 走 seek pagination 并保存 `views_count` 聚合列，`channel_message_viewers(channel_id,message_id,viewer_user_id)` 用主键完成 views 去重递增，`reply_to_msg_id/reply_to_top_id` 支撑 thread/comment 分页，`discussion_channel_id/discussion_message_id` 把 broadcast post 映射到 linked megagroup root，禁止按成员写扩散。
-- **`channel_members` / `channel_dialogs` / `channel_unread_mentions`** —— 成员权限、读水位、owner 视角 channel dialog 与未读提及索引，分别按 `channel_id` / `user_id` / `user_id` HASH 分区；`available_min_id` 限制成员可见历史消息，`available_min_pts` 限制 `updates.getChannelDifference` 起点，避免新成员或重新加入成员恢复到入群前的消息类 durable 事件。`channel_dialogs.unread_count` 是小超级群普通未读缓存字段，不是 broadcast/大超级群真值；大频道读取 dialog/full channel 时按 `channel_members.read_inbox_max_id`、`available_min_id`、`channels.top_message_id` 与未删除消息动态派生普通未读。`channel_dialogs.default_send_as_peer_type/default_send_as_peer_id` 保存当前 owner 的默认发送身份，由 `channels.getFullChannel` 输出为 `channelFull.default_send_as`，不参与历史分页或 dialog 排序；`channel_dialogs.view_forum_as_messages` 是当前账号本地 forum 展示模式，由 `Dialog/ChannelFull.view_forum_as_messages` 恢复 UI，并通过账号级 durable update 同步多 session。`channel_unread_mentions(user_id,channel_id,message_id)` 不复制消息正文，发送时只写解析出的 active/可见/未读成员，清除后重算 `channel_dialogs.unread_mentions_count`。共同超级群查询已迁到 `user_channel_member_index(user_id, channel_id)`，排除 broadcast 与非 active/deleted 成员；后续 `channels.getLeftChannels`、joined/admined channel 列表和启动 dialog 聚合也必须从 user 维度 read model 或两步 channel_id 列表读取，不能直接用 `channel_members WHERE user_id=...` 反向扫 `channel_id` 分区。
+- **`channel_members` / `channel_dialogs` / `channel_unread_mentions`** —— 成员权限、读水位、owner 视角 channel dialog 与未读提及索引，分别按 `channel_id` / `user_id` / `user_id` HASH 分区；`available_min_id` 限制成员可见历史消息，`available_min_pts` 限制 `updates.getChannelDifference` 起点，避免新成员或重新加入成员恢复到入群前的消息类 durable 事件。`channel_dialogs.unread_count` 是小超级群普通未读缓存字段，不是 broadcast/大超级群真值；大频道读取 dialog/full channel 时按 `channel_members.read_inbox_max_id`、`available_min_id`、`channels.top_message_id` 与未删除消息动态派生普通未读。`channel_dialogs.default_send_as_peer_type/default_send_as_peer_id` 保存当前 owner 的默认发送身份，由 `channels.getFullChannel` 输出为 `channelFull.default_send_as`，不参与历史分页或 dialog 排序；`channel_dialogs.view_forum_as_messages` 是当前账号本地 forum 展示模式，由 `Dialog/ChannelFull.view_forum_as_messages` 恢复 UI，并通过账号级 durable update 同步多 session。`channel_unread_mentions(user_id,channel_id,message_id,media_unread)` 不复制消息正文，发送/编辑时只写解析出的 active/可见/未读成员，清除后重算 `channel_dialogs.unread_mentions_count`；history/getMessages/getChannelDifference/online update 按 viewer 用它回填 `mentioned/media_unread`。共同超级群查询已迁到 `user_channel_member_index(user_id, channel_id)`，排除 broadcast 与非 active/deleted 成员；后续 `channels.getLeftChannels`、joined/admined channel 列表和启动 dialog 聚合也必须从 user 维度 read model 或两步 channel_id 列表读取，不能直接用 `channel_members WHERE user_id=...` 反向扫 `channel_id` 分区。
 - **`channel_invites` / `channel_invite_importers`** —— 邀请链接、导入者与 join request read model，均按 `channel_id` HASH 分区；invite 保存 `usage_count/requested_count`，importer 以 `(channel_id,user_id)` 保证同一用户只有一个 pending/approved 状态，管理页查询走 `admin/revoked/offset_link` 与 `requested/link/date/user_id` seek 索引，禁止按超大 limit 或 hash 反查做全表扫。public `channels.toggleJoinRequest` 使用 `channels.join_request` 与 `channel_invite_importers(invite_id=0, requested=true)` 表达非 invite-link pending request；管理员实时提醒用 bounded `updatePendingJoinRequests` + full channel 回填，不为每条 pending 状态生成无界 durable updates。
 - **`dialog_filters` / `dialog_filter_settings`** —— 当前账号自定义 dialog filter、filter 顺序与 folder tags 开关，按 `user_id` HASH 分区；自定义 filter 从 ID 2 开始，归档只由 `dialogs.folder_id=1` 表达，避免一列同时承担归档状态和任意筛选规则。
 - **`dispatch_outbox`** —— 按 `target_user_id` HASH 分区的 transactional outbox。发送事务内写入，RPC outbox worker 用 `FOR UPDATE SKIP LOCKED` 批量 claim，成功标记 delivered，失败退避重试；排除当前设备使用 `exclude_auth_key_id + exclude_session_id`，避免一个设备换号或多账号登录时误过滤。按 target 分区适合投递完成/失败按用户更新，但全局 claim/cleanup 与分区键不一致，规划会展开所有分区；上量前需引入 ready queue 或 worker shard read model。
@@ -145,6 +146,7 @@ internal/store/
 - **P4.3 删除消息/清空历史**：`messages.deleteMessages/deleteHistory` 已支持 owner 视角软删除、`revoke` 对端清理、dialog top 重算/删除/`just_clear` 保留空 dialog、`updateDeleteMessages` durable payload（`message_ids` + `pts_count=len(message_ids)`）与 outbox 投递；后续新消息会正常重建被删除的 dialog。—— ✅
 - **P4.4 Dialog 分组/归档**：`messages.getDialogFilters/updateDialogFilter/updateDialogFiltersOrder/toggleDialogFilterTags` 与 `folders.editPeerFolders` 已接入 PG-backed 服务；集成测试覆盖 folder_id 0/1 主列表/归档、自定义 filter、tags 和归档还原。—— ✅
 - **P4.5 TDesktop 搜索入口**：`contacts.search` 已支持联系人/非联系人用户搜索，`contacts.getSponsoredPeers` 返回空 sponsored peers，`messages.searchGlobal` 接当前 owner 私聊文本搜索；查询保护与索引设计参考实现，避免客户端搜索框卡在 Loading。—— ✅
+- **P4.6 内容已读与 blocklist privacy gate**：`message_boxes.media_unread/reaction_unread`、`user_update_events(read_message_contents)`、`contact_blocks` 已落地；`messages.readMessageContents` 只在实际清理 unread 内容状态时分配 pts 并 durable 推送，被 block 后私聊 send 只写 sender outbox，edit/revoke delete 会返回 forbidden。—— ✅
 
 ## 7. 与铁律的关系