Appearance
Comment 是由明确主体创建、附着于内容或内容片段、可被回复和治理的协作记录。评论系统不仅保存一段文字,还要维护线程关系、锚点版本、编辑与删除历史、解决状态和每个动作的授权。
本文聚焦:
前置知识:
评论不是对象正文的替代品。已经形成的决定应写入权威内容或决策记录;评论线程保留讨论过程与来源。
一个可维护的评论至少包含:
comment_id
container_id
thread_id
parent_comment_id
author_id
body
anchor
created_at
updated_at
version
resolution
deleted_state
visibility
W3C Web Annotation Data Model 将注释建模为 Body 与 Target 的关联,并提供 selector 与 state 表达目标片段和目标版本。产品可以借鉴这个结构,不必为了实现评论而完整采用 JSON-LD。
根评论建立主题、锚点和初始可见范围。回复继承线程锚点,除非产品明确支持回复附着到另一个片段。让每条回复各自漂移到不同锚点,会使“解决线程”没有清晰对象。
深层嵌套会同时增加:
常见选择:
协作文档通常优先单层或有限层级,并用“回复某人”表达局部语境。
线程内部通常按服务端创建序稳定排序;相同时间使用 comment_id 或序列号消除不确定性。根线程可按锚点位置、最近活动或未解决优先排序,但切换排序不能改变线程身份。
新回复插入后不能让键盘焦点和阅读位置突然跳到列表顶部。
flowchart LR C["Comment"] --> T["Target 业务对象"] T --> V["Target version"] T --> S["Selector 目标片段"] S --> P["稳定节点 ID"] S --> Q["文本引用与前后文"] S --> G["画布对象与局部坐标"] V --> R["重定位策略"]
单纯保存 x=420, y=180 只能对应某个缩放、布局和版本。可靠锚点应先识别稳定内容节点,再用位置或文本选择器细化。
x=420, y=180
可组合:
Text Position Selector 体积小但对前文插入敏感;Text Quote Selector 用 exact、prefix、suffix 重定位,但重复文本可能产生多个匹配。二者结合并记录版本,可提高恢复概率。
字符位置要说明计数方式。W3C 模型以 Unicode code point 表达位置,并建议不要截断 grapheme cluster。JavaScript 字符串索引基于 UTF-16 code unit,不能直接假设与该模型相同。
优先保存图层、节点或组件实例 ID;局部归一化坐标只表达节点内部位置。节点移动时评论跟随节点,节点删除时线程进入失联状态。
若评论附着在像素渲染结果,还需记录画布版本、页面或帧 ID、缩放无关坐标和可选截图摘要。截图只能帮助回忆,不能替代可授权的目标数据。
音视频评论保存媒体 ID、版本和时间范围。转码后若时间轴改变,需要媒资系统提供映射;不要按播放器当前像素位置保存。
目标删除、文本大改或版本不可读时:
stateDiagram-v2 [*] --> Open Open --> Resolved: "有权限者确认议题已处理" Resolved --> Reopened: "后续变化使问题再次成立" Reopened --> Resolved: "再次确认" Open --> Archived: "容器归档或策略迁移" Resolved --> Archived Archived --> Open: "对象恢复且策略允许"
线程仍需要关注。新建线程默认 open,但“评论”不一定都代表待办;产品可提供纯讨论与待解决两种动机,避免所有闲聊都进入未解决统计。
解决表示讨论对应的问题已处理或无需处理,不代表评论被删除。需要记录:
默认折叠已解决线程可以减少噪声,但必须可查找和回看。
重开不是把 resolved=false 覆盖掉。它是新的状态事件,需要保留重开人、原因和版本。若内容修改使原问题重新出现,可由人明确重开;系统自动重开需有可解释规则。
resolved=false
对象归档不一定删除评论。归档线程通常只读,并继承对象保留策略。
作者可在策略允许期内编辑正文;版主可以处理违规内容,但不应伪装成作者编辑。编辑锚点、正文和可见范围是不同风险操作。
对协作决策、合规或支持场景,保存:
普通社交场景也至少标记“已编辑”。若历史可查看,要沿用评论读取权限,不能让撤权用户从历史接口读取旧内容。
客户端提交 comment_id、期望版本和新正文。服务端若发现版本已变化:
HTTP 条件请求可使用 ETag 与 If-Match 表达前置版本,但业务仍要定义冲突响应和恢复界面。
If-Match
线程有回复、审计要求或引用关系时,删除正文但保留占位:
法律请求、敏感信息泄露或保留期结束可能要求清除正文、附件、搜索索引和派生缓存。审计记录只保留允许保留的最小事件,不应通过“审计”无限保存被要求删除的内容。
与作者删除区分。界面可以说明“因违反政策被移除”,但不泄露审核内部细节。申诉路径由治理政策决定。
删除评论时同时处理附件引用、预览、CDN、下载 URL 和病毒扫描记录。只删数据库正文会留下可访问附件。
每个动作单独授权:
作者身份不自动赋予永久权限。作者离开组织后,评论可能保留署名快照,但其账户不能继续读取或修改。
@mention
发送时可先显示带 client_request_id 的临时项,但必须标为发送中。服务端成功后用正式 comment_id 替换;重试复用请求 ID,避免重复评论。
client_request_id
发送失败保留正文、锚点和附件选择,提供重试或复制。失败评论不应触发真实通知,也不能被其他客户端看到。
WebSocket 推送和 POST 响应可能乱序。以服务端序列和评论 ID 去重,不能因先收到推送再收到响应而显示两条。
合同文档有稳定块 ID 和版本号。法务选择一句“服务可随时终止”创建评论,另一名编辑者随后在该段前插入两段文字,并把目标句改为“服务可提前 30 日通知后终止”。
根评论保存:
contract-42
v18
clause-termination
插入前文不会影响块 ID。目标句修改后 exact 不再匹配,系统用块 ID 定位段落,并标记原引用已变化。线程显示原引用摘要和当前段落。
法务回复“30 日符合要求”,文档所有者将线程解决,记录版本 v21。之后另一编辑者把期限改为 7 日,系统不直接伪装成“仍已解决”;规则可以提示“解决后的锚点内容已变化”,由有权限者决定重开。
v21
作者编辑回复时保存历史。删除根评论后线程已有回复,因此显示 tombstone,回复仍可理解。若原评论包含误贴的个人证件号,治理操作执行 purge,同时清理版本历史、搜索索引和通知预览。
若只保存字符位置,段前插入会把评论挂到错误句子,且界面看似正常。重定位必须优先验证块身份和文本引用;无法确定时进入失联状态,不能猜最近位置。
支持工单同时包含客户可见回复和内部备注。客服、值班工程师、客户联系人和外部供应商具有不同可见范围。工单关闭后评论只读,重新打开后可继续讨论。
每条根评论在创建时明确:
customer-visible
internal
vendor-thread
回复继承线程可见范围,不能在内部线程中单条切换为客户可见,避免上下文泄露。需要对外发送时,创建新的客户可见回复并明确引用经过审查的内容。
供应商被移除后,历史线程读取立即失效;已发送邮件通知只包含最小摘要,不包含完整内部内容。客服可以解决“等待日志”线程,客户不能解决内部线程。
工单关闭后新评论接口拒绝写入,客户端保留草稿并解释状态已变化。重新打开不自动恢复已撤销供应商权限。
客户可以按政策删除自己尚未被处理的消息;内部备注遵守支持记录保留。版主移除辱骂内容时保留治理事件,但不让普通客服查看原文。
如果客户端用红色区分内部备注,但接口返回所有评论,客户仍可能从响应或辅助技术读取。可见范围必须在服务端查询与推送阶段过滤,颜色只负责提示作者。
评论数量不是协作质量。大量评论可能来自结构不清或自动通知噪声。
为支持文本选区评论的协作文档设计:
验收标准:
Comment 评论
Comment 是由明确主体创建、附着于内容或内容片段、可被回复和治理的协作记录。评论系统不仅保存一段文字,还要维护线程关系、锚点版本、编辑与删除历史、解决状态和每个动作的授权。
能力边界与前置知识
本文聚焦:
前置知识:
评论不是对象正文的替代品。已经形成的决定应写入权威内容或决策记录;评论线程保留讨论过程与来源。
评论资源模型
一个可维护的评论至少包含:
comment_idcontainer_idthread_idparent_comment_idauthor_idbodyanchorcreated_atupdated_atversionresolutiondeleted_statevisibilityW3C Web Annotation Data Model 将注释建模为 Body 与 Target 的关联,并提供 selector 与 state 表达目标片段和目标版本。产品可以借鉴这个结构,不必为了实现评论而完整采用 JSON-LD。
线程与回复
根评论
根评论建立主题、锚点和初始可见范围。回复继承线程锚点,除非产品明确支持回复附着到另一个片段。让每条回复各自漂移到不同锚点,会使“解决线程”没有清晰对象。
回复层级
深层嵌套会同时增加:
常见选择:
协作文档通常优先单层或有限层级,并用“回复某人”表达局部语境。
排序
线程内部通常按服务端创建序稳定排序;相同时间使用
comment_id或序列号消除不确定性。根线程可按锚点位置、最近活动或未解决优先排序,但切换排序不能改变线程身份。新回复插入后不能让键盘焦点和阅读位置突然跳到列表顶部。
锚点不是屏幕坐标
锚点组成
2
3
4
5
6
7
8
单纯保存
x=420, y=180只能对应某个缩放、布局和版本。可靠锚点应先识别稳定内容节点,再用位置或文本选择器细化。文本锚点
可组合:
Text Position Selector 体积小但对前文插入敏感;Text Quote Selector 用 exact、prefix、suffix 重定位,但重复文本可能产生多个匹配。二者结合并记录版本,可提高恢复概率。
字符位置要说明计数方式。W3C 模型以 Unicode code point 表达位置,并建议不要截断 grapheme cluster。JavaScript 字符串索引基于 UTF-16 code unit,不能直接假设与该模型相同。
画布锚点
优先保存图层、节点或组件实例 ID;局部归一化坐标只表达节点内部位置。节点移动时评论跟随节点,节点删除时线程进入失联状态。
若评论附着在像素渲染结果,还需记录画布版本、页面或帧 ID、缩放无关坐标和可选截图摘要。截图只能帮助回忆,不能替代可授权的目标数据。
时间媒体锚点
音视频评论保存媒体 ID、版本和时间范围。转码后若时间轴改变,需要媒资系统提供映射;不要按播放器当前像素位置保存。
锚点失联
目标删除、文本大改或版本不可读时:
线程状态
2
3
4
5
6
7
8
Open
线程仍需要关注。新建线程默认 open,但“评论”不一定都代表待办;产品可提供纯讨论与待解决两种动机,避免所有闲聊都进入未解决统计。
Resolved
解决表示讨论对应的问题已处理或无需处理,不代表评论被删除。需要记录:
默认折叠已解决线程可以减少噪声,但必须可查找和回看。
Reopened
重开不是把
resolved=false覆盖掉。它是新的状态事件,需要保留重开人、原因和版本。若内容修改使原问题重新出现,可由人明确重开;系统自动重开需有可解释规则。Archived
对象归档不一定删除评论。归档线程通常只读,并继承对象保留策略。
编辑
允许范围
作者可在策略允许期内编辑正文;版主可以处理违规内容,但不应伪装成作者编辑。编辑锚点、正文和可见范围是不同风险操作。
编辑历史
对协作决策、合规或支持场景,保存:
普通社交场景也至少标记“已编辑”。若历史可查看,要沿用评论读取权限,不能让撤权用户从历史接口读取旧内容。
并发编辑
客户端提交
comment_id、期望版本和新正文。服务端若发现版本已变化:HTTP 条件请求可使用 ETag 与
If-Match表达前置版本,但业务仍要定义冲突响应和恢复界面。删除与内容治理
软删除 Tombstone
线程有回复、审计要求或引用关系时,删除正文但保留占位:
硬删除 Purge
法律请求、敏感信息泄露或保留期结束可能要求清除正文、附件、搜索索引和派生缓存。审计记录只保留允许保留的最小事件,不应通过“审计”无限保存被要求删除的内容。
版主移除
与作者删除区分。界面可以说明“因违反政策被移除”,但不泄露审核内部细节。申诉路径由治理政策决定。
附件
删除评论时同时处理附件引用、预览、CDN、下载 URL 和病毒扫描记录。只删数据库正文会留下可访问附件。
权限模型
每个动作单独授权:
作者身份不自动赋予永久权限。作者离开组织后,评论可能保留署名快照,但其账户不能继续读取或修改。
富文本与安全
@mention保存身份节点,不靠重新解析显示字符串。离线、乐观更新与失败
临时评论
发送时可先显示带
client_request_id的临时项,但必须标为发送中。服务端成功后用正式comment_id替换;重试复用请求 ID,避免重复评论。失败
发送失败保留正文、锚点和附件选择,提供重试或复制。失败评论不应触发真实通知,也不能被其他客户端看到。
乱序
WebSocket 推送和 POST 响应可能乱序。以服务端序列和评论 ID 去重,不能因先收到推送再收到响应而显示两条。
案例一:合同段落上的审阅线程
输入
合同文档有稳定块 ID 和版本号。法务选择一句“服务可随时终止”创建评论,另一名编辑者随后在该段前插入两段文字,并把目标句改为“服务可提前 30 日通知后终止”。
锚点与线程
根评论保存:
contract-42。v18。clause-termination。插入前文不会影响块 ID。目标句修改后 exact 不再匹配,系统用块 ID 定位段落,并标记原引用已变化。线程显示原引用摘要和当前段落。
解决
法务回复“30 日符合要求”,文档所有者将线程解决,记录版本
v21。之后另一编辑者把期限改为 7 日,系统不直接伪装成“仍已解决”;规则可以提示“解决后的锚点内容已变化”,由有权限者决定重开。编辑和删除
作者编辑回复时保存历史。删除根评论后线程已有回复,因此显示 tombstone,回复仍可理解。若原评论包含误贴的个人证件号,治理操作执行 purge,同时清理版本历史、搜索索引和通知预览。
验证
失败分支
若只保存字符位置,段前插入会把评论挂到错误句子,且界面看似正常。重定位必须优先验证块身份和文本引用;无法确定时进入失联状态,不能猜最近位置。
案例二:客户工单中的内部与外部评论
输入
支持工单同时包含客户可见回复和内部备注。客服、值班工程师、客户联系人和外部供应商具有不同可见范围。工单关闭后评论只读,重新打开后可继续讨论。
可见范围
每条根评论在创建时明确:
customer-visible:客户联系人和内部处理者可读。internal:组织内部授权人员可读。vendor-thread:指定供应商与内部人员可读。回复继承线程可见范围,不能在内部线程中单条切换为客户可见,避免上下文泄露。需要对外发送时,创建新的客户可见回复并明确引用经过审查的内容。
权限与通知
供应商被移除后,历史线程读取立即失效;已发送邮件通知只包含最小摘要,不包含完整内部内容。客服可以解决“等待日志”线程,客户不能解决内部线程。
工单关闭后新评论接口拒绝写入,客户端保留草稿并解释状态已变化。重新打开不自动恢复已撤销供应商权限。
删除与审计
客户可以按政策删除自己尚未被处理的消息;内部备注遵守支持记录保留。版主移除辱骂内容时保留治理事件,但不让普通客服查看原文。
验证
失败分支
如果客户端用红色区分内部备注,但接口返回所有评论,客户仍可能从响应或辅助技术读取。可见范围必须在服务端查询与推送阶段过滤,颜色只负责提示作者。
无障碍与键盘
观测与调试
关键观测
评论数量不是协作质量。大量评论可能来自结构不清或自动通知噪声。
调试顺序
失败注入
综合练习:实现可治理的锚点线程
为支持文本选区评论的协作文档设计:
验收标准:
来源