專案活動

使用 Blue API 檢索和監控專案活動資訊流。

檢索專案活動

activityList 查詢提供對專案和公司的全面活動資訊流的訪問。當用戶執行創建待辦事項、評論或進行專案更改等操作時，系統會自動生成活動。

基本範例

query ProjectActivity {
  activityList(
    projectId: "your-project-id"
    first: 20
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

進階範例與過濾

query FilteredActivity {
  activityList(
    companyId: "your-company-id"
    categories: [CREATE_TODO, MARK_TODO_AS_COMPLETE, CREATE_COMMENT]
    userIds: ["user1-id", "user2-id"]
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-12-31T23:59:59Z"
    first: 50
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      uid
      category
      html
      createdAt
      updatedAt
      createdBy {
        id
        name
        email
      }
      affectedBy {
        id
        name
      }
      todo {
        id
        title
      }
      comment {
        id
        text
      }
      project {
        id
        name
        slug
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

輸入參數

activityList 查詢

參數	類型	必需	描述
`companyId`	String	否	根據公司 ID 或 slug 過濾活動
`projectId`	String	否	根據專案 ID 或 slug 過濾活動
`userId`	String	否	根據特定用戶過濾活動
`userIds`	[String!]	否	根據多個用戶過濾活動
`tagIds`	[String!]	否	根據待辦事項標籤過濾活動
`categories`	[ActivityCategory!]	否	根據特定活動類型過濾
`startDate`	DateTime	否	從此日期過濾活動
`endDate`	DateTime	否	過濾到此日期的活動
`skip`	Int	否	跳過此數量的記錄（偏移分頁）
`first`	Int	否	返回前 N 條記錄（游標分頁）
`last`	Int	否	返回最後 N 條記錄（游標分頁）
`after`	String	否	返回此游標之後的記錄
`before`	String	否	返回此游標之前的記錄
`orderBy`	ActivityOrderByInput	否	結果的排序順序

ActivityCategory 值

系統自動跟踪各種活動類型：

類別	描述
`CREATE_TODO`	創建了一個新的待辦事項/任務
`MARK_TODO_AS_COMPLETE`	待辦事項被標記為完成
`CREATE_COMMENT`	添加了一條評論
`CREATE_DISCUSSION`	開始了一個討論
`CREATE_STATUS_UPDATE`	發佈了一個狀態更新
`CREATE_TODO_LIST`	創建了一個新的待辦清單
`MOVE_TODO`	待辦事項在清單之間移動
`COPY_TODO`	待辦事項被複製
`ADD_USER_TO_PROJECT`	用戶被添加到專案中
`REMOVE_USER_FROM_PROJECT`	用戶從專案中被移除
`ARCHIVE_PROJECT`	專案被存檔
`UNARCHIVE_PROJECT`	專案被取消存檔
`CREATE_INVITATION`	用戶被邀請
`ACCEPT_INVITATION`	邀請被接受
`CREATE_CUSTOM_FIELD`	創建了一個自定義字段
`RECEIVE_FORM`	收到了一個表單提交

ActivityOrderByInput 值

值	描述
`createdAt_DESC`	最近的在前（默認）
`createdAt_ASC`	最舊的在前
`updatedAt_DESC`	最近更新的在前
`updatedAt_ASC`	最少更新的在前
`category_ASC`	按類別字母排序
`category_DESC`	按類別反向字母排序

回應字段

活動類型

字段	類型	描述
`id`	ID!	活動的唯一標識符
`uid`	String!	替代唯一標識符
`category`	ActivityCategory!	發生的活動類型
`html`	String!	活動的豐富 HTML 描述
`createdAt`	DateTime!	活動發生的時間
`updatedAt`	DateTime!	活動最後更新的時間
`createdBy`	User!	執行操作的用戶
`affectedBy`	User	受操作影響的用戶
`company`	Company	相關公司
`project`	Project	相關專案
`todo`	Todo	相關待辦事項（如適用）
`todoList`	TodoList	相關待辦清單（如適用）
`comment`	Comment	相關評論（如適用）
`discussion`	Discussion	相關討論（如適用）
`statusUpdate`	StatusUpdate	相關狀態更新（如適用）
`metadata`	String	附加活動元數據

ActivityList 回應

字段	類型	描述
`activities`	[Activity!]!	活動記錄的數組
`pageInfo`	PageInfo!	分頁信息
`totalCount`	Int!	符合過濾條件的活動總數

實時活動更新

使用 subscribeToActivity 訂閱活動變更：

subscription ActivityUpdates($companyId: String!, $projectId: String) {
  subscribeToActivity(companyId: $companyId, projectId: $projectId) {
    mutation
    node {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
  }
}

訂閱參數

參數	類型	必需	描述
`companyId`	String	否	訂閱公司範圍的活動
`projectId`	String	否	訂閱特定專案的活動

訂閱將通知您：

ACTIVITY_CREATED - 新活動
ACTIVITY_UPDATED - 修改的活動
ACTIVITY_DELETED - 移除的活動

過濾和隱私

自動過濾

活動資訊流根據以下條件自動過濾結果：

專案設置：僅顯示啟用活動追蹤的專案的活動
用戶權限：不同用戶角色看到不同的活動類型
專案成員資格：用戶僅看到他們有權訪問的專案的活動
公司成員資格：活動範圍限於用戶的公司

隱私考量

CLIENT 角色的用戶對某些管理活動的可見性有限
活動遵循專案級別的隱私設置
敏感操作可能不會生成公共活動

錯誤回應

無效的專案/公司

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

權限被拒絕

{
  "errors": [{
    "message": "You do not have permission to view activities for this project",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

無效的日期範圍

{
  "errors": [{
    "message": "Start date must be before end date",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

最佳實踐

使用分頁：活動資訊流可能很大，始終使用 first 參數
按專案過濾：公司範圍的活動資訊流可能會令人不知所措
實時更新：使用訂閱獲取即時活動資訊流
日期過濾：使用日期範圍進行歷史活動分析
類別過濾：按特定活動類型過濾以獲取專注的資訊流
用戶過濾：使用 userIds 跟踪特定團隊成員的活動

重要說明

活動是自動生成的，無法通過 API 手動創建
活動文本使用 HTML 格式進行豐富顯示
text 字段已棄用，取而代之的是 html
活動被永久存儲並提供完整的審計追蹤
實時訂閱需要 WebSocket 連接身份驗證

檢索專案活動

基本範例

進階範例與過濾

輸入參數

activityList 查詢

ActivityCategory 值

ActivityOrderByInput 值

回應字段

活動類型

ActivityList 回應

實時活動更新

訂閱參數

過濾和隱私

自動過濾

隱私考量

錯誤回應

無效的專案/公司

權限被拒絕

無效的日期範圍

最佳實踐

重要說明

AI 助手

我能幫助您什麼？