Skip to content

Comment 评论 ​

Comment 是由明确主体创建、附着于内容或内容片段、可被回复和治理的协作记录。评论系统不仅保存一段文字,还要维护线程关系、锚点版本、编辑与删除历史、解决状态和每个动作的授权。

能力边界与前置知识 ​

本文聚焦:

  • 评论、回复与线程的身份模型。
  • 文档、画布、时间轴和对象字段上的锚点。
  • 编辑、删除、解决、重开与并发操作。
  • 作者、对象成员、版主和外部协作者的权限边界。
  • 深链、通知、无障碍、审计与数据保留。

前置知识:

  • 能区分业务对象、内容版本和稳定对象 ID。
  • 理解可见入口与服务端授权不是同一件事。
  • 能为异步写入处理失败、重试、冲突和离线恢复。

评论不是对象正文的替代品。已经形成的决定应写入权威内容或决策记录;评论线程保留讨论过程与来源。

评论资源模型 ​

一个可维护的评论至少包含:

字段作用关键边界
comment_id评论稳定身份改文案、换锚点后不变
container_id所属文档、设计稿或工单决定主要授权范围
thread_id所属线程根评论与回复共享
parent_comment_id直接回复对象可选,不能形成环
author_id创建主体稳定 ID不用显示名作身份
body当前可展示内容富文本需安全解析
anchor指向整体对象或片段必须包含版本与恢复策略
created_at服务端创建时间不信任客户端时间
updated_at最近内容修改时间与状态变更时间分开
version并发控制版本编辑时比较
resolutionopen、resolved 等属于线程,不属于单条回复
deleted_stateactive、tombstone、purged删除不等于所有痕迹消失
visibility对象成员、受邀人、内部等读取时重新授权

W3C Web Annotation Data Model 将注释建模为 Body 与 Target 的关联,并提供 selector 与 state 表达目标片段和目标版本。产品可以借鉴这个结构,不必为了实现评论而完整采用 JSON-LD。

线程与回复 ​

根评论 ​

根评论建立主题、锚点和初始可见范围。回复继承线程锚点,除非产品明确支持回复附着到另一个片段。让每条回复各自漂移到不同锚点,会使“解决线程”没有清晰对象。

回复层级 ​

深层嵌套会同时增加:

  • 窄屏缩进。
  • 阅读顺序复杂度。
  • 通知目标歧义。
  • 删除父评论后的展示难度。
  • 分页和虚拟化成本。

常见选择:

模型适用代价
单层线程围绕一个锚点短讨论不能视觉表达回复分支
两层回复需要回复某人但保持主题平坦同层时间线仍可能交错
任意嵌套论坛式长期讨论移动端、排序和无障碍复杂
子线程某条回复产生独立议题需要线程间导航与状态

协作文档通常优先单层或有限层级,并用“回复某人”表达局部语境。

排序 ​

线程内部通常按服务端创建序稳定排序;相同时间使用 comment_id 或序列号消除不确定性。根线程可按锚点位置、最近活动或未解决优先排序,但切换排序不能改变线程身份。

新回复插入后不能让键盘焦点和阅读位置突然跳到列表顶部。

锚点不是屏幕坐标 ​

锚点组成 ​

mermaid
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 只能对应某个缩放、布局和版本。可靠锚点应先识别稳定内容节点,再用位置或文本选择器细化。

文本锚点 ​

可组合:

  • 文档或块的稳定 ID。
  • 内容版本 ID。
  • 选中文本的标准化引用。
  • 选区前缀与后缀。
  • 起止字符位置。

Text Position Selector 体积小但对前文插入敏感;Text Quote Selector 用 exact、prefix、suffix 重定位,但重复文本可能产生多个匹配。二者结合并记录版本,可提高恢复概率。

字符位置要说明计数方式。W3C 模型以 Unicode code point 表达位置,并建议不要截断 grapheme cluster。JavaScript 字符串索引基于 UTF-16 code unit,不能直接假设与该模型相同。

画布锚点 ​

优先保存图层、节点或组件实例 ID;局部归一化坐标只表达节点内部位置。节点移动时评论跟随节点,节点删除时线程进入失联状态。

若评论附着在像素渲染结果,还需记录画布版本、页面或帧 ID、缩放无关坐标和可选截图摘要。截图只能帮助回忆,不能替代可授权的目标数据。

时间媒体锚点 ​

音视频评论保存媒体 ID、版本和时间范围。转码后若时间轴改变,需要媒资系统提供映射;不要按播放器当前像素位置保存。

锚点失联 ​

目标删除、文本大改或版本不可读时:

  • 保留线程,不静默移动到最近位置。
  • 标记“原位置已变化”。
  • 若可授权,显示原引用摘要和历史版本入口。
  • 允许有权限的人重新锚定。
  • 重新锚定记录旧锚点和操作者。

线程状态 ​

mermaid
stateDiagram-v2
    [*] --> Open
    Open --> Resolved: "有权限者确认议题已处理"
    Resolved --> Reopened: "后续变化使问题再次成立"
    Reopened --> Resolved: "再次确认"
    Open --> Archived: "容器归档或策略迁移"
    Resolved --> Archived
    Archived --> Open: "对象恢复且策略允许"

Open ​

线程仍需要关注。新建线程默认 open,但“评论”不一定都代表待办;产品可提供纯讨论与待解决两种动机,避免所有闲聊都进入未解决统计。

Resolved ​

解决表示讨论对应的问题已处理或无需处理,不代表评论被删除。需要记录:

  • 解决人。
  • 解决时间。
  • 可选解决说明。
  • 当时目标版本。

默认折叠已解决线程可以减少噪声,但必须可查找和回看。

Reopened ​

重开不是把 resolved=false 覆盖掉。它是新的状态事件,需要保留重开人、原因和版本。若内容修改使原问题重新出现,可由人明确重开;系统自动重开需有可解释规则。

Archived ​

对象归档不一定删除评论。归档线程通常只读,并继承对象保留策略。

编辑 ​

允许范围 ​

作者可在策略允许期内编辑正文;版主可以处理违规内容,但不应伪装成作者编辑。编辑锚点、正文和可见范围是不同风险操作。

编辑历史 ​

对协作决策、合规或支持场景,保存:

  • 版本号。
  • 修改者。
  • 修改时间。
  • 修改前后内容或差异。
  • 修改原因(策略要求时)。

普通社交场景也至少标记“已编辑”。若历史可查看,要沿用评论读取权限,不能让撤权用户从历史接口读取旧内容。

并发编辑 ​

客户端提交 comment_id、期望版本和新正文。服务端若发现版本已变化:

  • 返回冲突与当前版本。
  • 保留用户本地草稿。
  • 提供比较、复制或重新应用。
  • 不做最后写入者静默覆盖。

HTTP 条件请求可使用 ETag 与 If-Match 表达前置版本,但业务仍要定义冲突响应和恢复界面。

删除与内容治理 ​

软删除 Tombstone ​

线程有回复、审计要求或引用关系时,删除正文但保留占位:

  • “该评论已由作者删除。”
  • 评论 ID、线程关系和必要时间仍存在。
  • 不在普通界面显示已删除正文。
  • 回复顺序保持。

硬删除 Purge ​

法律请求、敏感信息泄露或保留期结束可能要求清除正文、附件、搜索索引和派生缓存。审计记录只保留允许保留的最小事件,不应通过“审计”无限保存被要求删除的内容。

版主移除 ​

与作者删除区分。界面可以说明“因违反政策被移除”,但不泄露审核内部细节。申诉路径由治理政策决定。

附件 ​

删除评论时同时处理附件引用、预览、CDN、下载 URL 和病毒扫描记录。只删数据库正文会留下可访问附件。

权限模型 ​

每个动作单独授权:

动作典型主体服务端检查
读取线程对象可读者且满足评论可见范围当前对象权限、线程范围、目标版本
创建根评论可评论者对象状态、锚点可见、限流
回复可评论者线程仍可回复、父评论可读
编辑正文作者或受控版主当前版本、编辑期限、对象策略
删除正文作者、版主或数据治理回复关系、保留策略、删除类型
解决线程议题负责人、对象编辑者等线程状态、业务角色
重开线程可解决者或评论者,依产品规则当前目标与状态
重新锚定对象编辑者新旧目标都可读写

作者身份不自动赋予永久权限。作者离开组织后,评论可能保留署名快照,但其账户不能继续读取或修改。

富文本与安全 ​

  • 正文采用结构化富文本或受控 Markdown;服务端清理不可信 HTML。
  • 链接采用安全协议白名单,外部链接明确目标。
  • 图片和附件先授权再下载,短期 URL 不进入正文。
  • @mention 保存身份节点,不靠重新解析显示字符串。
  • 代码块、表格和引用保留语义与键盘可访问性。
  • 评论搜索索引遵守当前对象权限与删除状态。
  • 限制体积、回复频率和附件数量,防止资源滥用。

离线、乐观更新与失败 ​

临时评论 ​

发送时可先显示带 client_request_id 的临时项,但必须标为发送中。服务端成功后用正式 comment_id 替换;重试复用请求 ID,避免重复评论。

失败 ​

发送失败保留正文、锚点和附件选择,提供重试或复制。失败评论不应触发真实通知,也不能被其他客户端看到。

乱序 ​

WebSocket 推送和 POST 响应可能乱序。以服务端序列和评论 ID 去重,不能因先收到推送再收到响应而显示两条。

案例一:合同段落上的审阅线程 ​

输入 ​

合同文档有稳定块 ID 和版本号。法务选择一句“服务可随时终止”创建评论,另一名编辑者随后在该段前插入两段文字,并把目标句改为“服务可提前 30 日通知后终止”。

锚点与线程 ​

根评论保存:

  • 文档 ID contract-42。
  • 版本 v18。
  • 段落块 ID clause-termination。
  • exact 引用、前后文。
  • 在标准化段落中的位置。

插入前文不会影响块 ID。目标句修改后 exact 不再匹配,系统用块 ID 定位段落,并标记原引用已变化。线程显示原引用摘要和当前段落。

解决 ​

法务回复“30 日符合要求”,文档所有者将线程解决,记录版本 v21。之后另一编辑者把期限改为 7 日,系统不直接伪装成“仍已解决”;规则可以提示“解决后的锚点内容已变化”,由有权限者决定重开。

编辑和删除 ​

作者编辑回复时保存历史。删除根评论后线程已有回复,因此显示 tombstone,回复仍可理解。若原评论包含误贴的个人证件号,治理操作执行 purge,同时清理版本历史、搜索索引和通知预览。

验证 ​

  • 在段前插入、段内修改、块移动和块删除条件下检查锚点。
  • 两人同时编辑同一回复,确认冲突不会静默覆盖。
  • 解决后修改目标,检查状态提示。
  • 外部审阅者撤权后无法从深链或历史接口读取线程。
  • 键盘可从段落锚点进入线程并返回原段落。

失败分支 ​

若只保存字符位置,段前插入会把评论挂到错误句子,且界面看似正常。重定位必须优先验证块身份和文本引用;无法确定时进入失联状态,不能猜最近位置。

案例二:客户工单中的内部与外部评论 ​

输入 ​

支持工单同时包含客户可见回复和内部备注。客服、值班工程师、客户联系人和外部供应商具有不同可见范围。工单关闭后评论只读,重新打开后可继续讨论。

可见范围 ​

每条根评论在创建时明确:

  • customer-visible:客户联系人和内部处理者可读。
  • internal:组织内部授权人员可读。
  • vendor-thread:指定供应商与内部人员可读。

回复继承线程可见范围,不能在内部线程中单条切换为客户可见,避免上下文泄露。需要对外发送时,创建新的客户可见回复并明确引用经过审查的内容。

权限与通知 ​

供应商被移除后,历史线程读取立即失效;已发送邮件通知只包含最小摘要,不包含完整内部内容。客服可以解决“等待日志”线程,客户不能解决内部线程。

工单关闭后新评论接口拒绝写入,客户端保留草稿并解释状态已变化。重新打开不自动恢复已撤销供应商权限。

删除与审计 ​

客户可以按政策删除自己尚未被处理的消息;内部备注遵守支持记录保留。版主移除辱骂内容时保留治理事件,但不让普通客服查看原文。

验证 ​

  • 四种身份分别读取同一工单和通知深链。
  • 尝试在内部线程创建外部可见回复。
  • 在输入期间关闭工单,确认草稿恢复。
  • 移除供应商后检查缓存、搜索和附件 URL。
  • 删除父评论后确认线程关系与审计最小化。

失败分支 ​

如果客户端用红色区分内部备注,但接口返回所有评论,客户仍可能从响应或辅助技术读取。可见范围必须在服务端查询与推送阶段过滤,颜色只负责提示作者。

无障碍与键盘 ​

  • 评论列表使用有意义的列表或文章结构,作者、时间、正文和操作关系可程序化理解。
  • “已编辑”“已解决”“原位置已变化”用文本表达。
  • 锚点按钮具有可识别名称,例如“打开第 4 段的 2 条评论”。
  • 打开侧栏后焦点进入线程标题或首个合理位置;关闭后返回原锚点。
  • 新回复成功可用简短状态消息,不把整条评论在 live region 中重复播报。
  • 操作菜单支持键盘并在关闭后恢复焦点。
  • 无限列表加载新回复时保持当前阅读位置。
  • 200% 文本缩放下不依赖横向缩进表达回复层级。

观测与调试 ​

关键观测 ​

  • 根评论创建、有效回复和解决所需时间。
  • 锚点失联与重新锚定比例,按内容类型和版本操作分组。
  • 编辑冲突、重复发送和离线重试。
  • 解决后重开及目标变更提示。
  • 权限拒绝、撤权后访问和缓存泄露告警。
  • 删除类型、索引清理延迟和附件残留检查。

评论数量不是协作质量。大量评论可能来自结构不清或自动通知噪声。

调试顺序 ​

  1. 固定主体、容器、线程和目标版本。
  2. 检查读取与动作权限。
  3. 检查锚点组成、标准化和重定位结果。
  4. 检查评论版本、状态事件和并发前置条件。
  5. 检查推送去重与排序。
  6. 检查删除后的正文、历史、索引和附件。
  7. 复测焦点、状态消息和窄屏布局。

失败注入 ​

  1. 评论创建后目标块被移动、修改或删除。
  2. 两人同时编辑同一评论。
  3. POST 响应丢失但推送已到达。
  4. 线程解决时另一人新增回复。
  5. 对象权限在侧栏打开期间撤销。
  6. 删除含附件与 mention 的根评论。
  7. 长线程分页时父评论位于上一页。
  8. 离线草稿恢复到已归档对象。

综合练习:实现可治理的锚点线程 ​

为支持文本选区评论的协作文档设计:

  1. 评论、线程、状态事件和编辑版本数据模型。
  2. 文本锚点与重定位算法的输入输出。
  3. open、resolved、reopened、archived 转移规则。
  4. 作者删除、版主移除和治理清除策略。
  5. 角色—动作授权矩阵。
  6. 离线、并发、推送乱序和撤权测试。
  7. 键盘、屏幕阅读器与长线程验收。

验收标准:

  • 评论身份、目标身份和显示名称彼此独立。
  • 锚点无法可靠恢复时不会静默挂到错误位置。
  • 编辑冲突保留双方内容。
  • 解决与删除都有可追踪状态事件。
  • 回复不会绕过根线程可见范围。
  • 撤权后深链、搜索、推送与附件同时失效。

来源 ​

从前端走向软件产品工程的长期路线图。