---

添加評論

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 訂閱以獲取實時更新
• Webhook：如果為項目配置，則觸發外部 webhook
• @提及處理：處理用戶提及並發送針對性通知
• 文件處理：提取並處理 HTML 內容中的任何嵌入圖片或文件

內容安全

• 所有 HTML 都使用行業標準庫進行清理
• 文件上傳會對類型和大小進行驗證
• 惡意內容會自動被剔除
• 用戶生成的內容在所有上下文中都會正確轉義

集成功能

• 活動提要：評論會出現在項目活動時間線中
• 搜索：評論內容可以在項目內進行搜索
• 通知：不同評論類型的可配置通知偏好
• 實時：評論會立即顯示給查看同一記錄的其他用戶
• 移動支持：評論在移動應用中完全支持

相關端點

• 列出評論：查詢評論以檢索現有記錄上的評論
• 更新評論：修改現有評論內容
• 刪除評論：在適當授權下刪除評論
• 列出記錄：查詢待辦事項以查找可以評論的記錄