项目活动

使用 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助手

我能帮您什么？