---

添加评论

createComment 变更允许您向 Blue 中的记录添加评论。评论支持丰富的 HTML 内容、文件附件、@提及，并与活动提要和通知系统自动集成。

基本示例

向记录添加简单的文本评论：

mutation AddComment {
  createComment(
    input: {
      html: "<p>This task is progressing well!</p>"
      text: "This task is progressing well!"
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
    }
  ) {
    id
    html
    text
    createdAt
    user {
      id
      name
    }
  }
}

高级示例

添加带有丰富格式、图像和 TipTap 编辑器处理的评论：

mutation AddCommentAdvanced {
  createComment(
    input: {
      html: "<p>Here's my <strong>feedback</strong> on this task:</p><ul><li>Great progress on the design</li><li>Need to review the API integration</li></ul><p>Attaching screenshot:</p><img src='data:image/png;base64,iVBOR...' />"
      text: "Here's my feedback on this task: - Great progress on the design - Need to review the API integration Attaching screenshot:"
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
      tiptap: true
    }
  ) {
    id
    html
    text
    createdAt
    user {
      id
      name
      avatar
    }
    activity {
      id
    }
    isRead
    isSeen
  }
}

输入参数

CreateCommentInput

参数	类型	必需	描述
html	String!	✅ 是	评论的 HTML 内容（将进行安全处理）
text	String!	✅ 是	评论内容的纯文本版本
category	CommentCategory!	✅ 是	被评论的实体类型（对于记录使用 TODO）
categoryId	String!	✅ 是	被评论的实体（记录）的 ID
tiptap	Boolean	否	启用 TipTap 编辑器特定的 HTML 安全处理和处理

CommentCategory 值

值	描述
TODO	对记录/待办事项的评论
DISCUSSION	对讨论线程的评论
STATUS_UPDATE	对状态更新的评论

响应字段

该变更返回一个包含详细信息的 Comment 对象：

字段	类型	描述
id	ID!	评论的唯一标识符
uid	String!	备用唯一标识符
html	String!	评论的 HTML 内容
text	String!	评论的纯文本版本
category	CommentCategory!	被评论的实体类型
createdAt	DateTime!	评论创建的时间
updatedAt	DateTime!	评论最后更新的时间
deletedAt	DateTime	评论被删除的时间（如果仍然有效则为 null）
deletedBy	User	删除评论的用户
user	User!	创建评论的用户
activity	Activity	关联的活动记录
discussion	Discussion	关联的讨论（如果类别为 DISCUSSION）
statusUpdate	StatusUpdate	关联的状态更新（如果类别为 STATUS_UPDATE）
todo	Todo	关联的记录（如果类别为 TODO）
isRead	Boolean	当前用户是否已阅读此评论
isSeen	Boolean	当前用户是否已查看此评论
aiSummary	Boolean	此评论是否由 AI 生成

所需权限

用户必须具有适当的项目访问权限才能对记录进行评论：

访问级别	可以添加评论
OWNER	✅ 是
ADMIN	✅ 是
MEMBER	✅ 是
CLIENT	✅ 是
COMMENT_ONLY	✅ 是
VIEW_ONLY	❌ 否

重要：用户必须是包含记录的项目的成员，并且必须没有 VIEW_ONLY 访问级别。

错误响应

UnauthorizedError

{
  "errors": [{
    "message": "You don't have permission to comment on this record",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

何时：用户没有权限对指定的记录/实体进行评论。

ValidationError

{
  "errors": [{
    "message": "Invalid input parameters",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

何时：缺少必需字段或包含无效数据。

CommentNotFoundError

{
  "errors": [{
    "message": "Record not found",
    "extensions": {
      "code": "COMMENT_NOT_FOUND"
    }
  }]
}

何时：指定的 categoryId 与现有记录不对应。

UserInputError

{
  "errors": [{
    "message": "Content validation failed",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

何时：HTML 内容未能通过安全处理或包含恶意代码。

重要说明

内容处理

• HTML 安全处理：所有 HTML 内容会自动进行安全处理，以防止 XSS 攻击
• 文件提取：嵌入 HTML 中的图像和附件会被提取并存储在 S3 中
• TipTap 模式：当 tiptap: true 时，使用专门的安全处理来处理 TipTap 编辑器内容
• @提及：评论中的用户提及会自动处理并触发通知

性能考虑

• 评论会自动编入搜索索引
• 大型图像附件会异步处理
• 每条评论都会为项目时间线创建一个活动记录

副作用

添加评论会触发多个自动化流程：

• 活动创建：在项目时间线中创建一个可见的活动记录
• 搜索索引：评论内容会添加到项目搜索索引中
• 通知：向相关用户发送电子邮件、推送和应用内通知
• 实时更新：将评论发布到 GraphQL 订阅以进行实时更新
• Webhooks：如果为项目配置，则触发外部 webhook
• @提及处理：处理用户提及并发送定向通知
• 文件处理：提取并处理 HTML 内容中的任何嵌入图像或文件

内容安全

• 所有 HTML 都使用行业标准库进行安全处理
• 文件上传会验证类型和大小
• 恶意内容会被自动剔除
• 用户生成的内容在所有上下文中都会被正确转义

集成功能

• 活动提要：评论会出现在项目活动时间线中
• 搜索：评论内容可以在项目中搜索
• 通知：可配置不同评论类型的通知偏好
• 实时：其他查看同一记录的用户会立即看到评论
• 移动支持：评论在移动应用中完全支持

相关端点

• 列出评论：查询评论以检索现有记录上的评论
• 更新评论：修改现有评论内容
• 删除评论：在适当授权下删除评论
• 列出记录：查询待办事项以查找可以评论的记录