Bitzsoft.Integrations.ProjectManagement.Teambition 1.0.4

Bitzsoft.Integrations.ProjectManagement.Teambition

Teambition（阿里巴巴旗下 / 钉钉生态）协作平台 Open API 项目管理连接器实现。遵循项目管理通用抽象规范，实现通用 IProjectManagementService 接口。

功能特性

• 通用契约对齐：完整实现 IProjectManagementService 抽象规范，支持项目列表查询、任务创建、详情获取、信息修改、任务标记完成（isDone = true）与条件列表查询。
• 自动凭据维护：支持 AppKey + AppSecret 机制，底层自动向 Teambition 开放平台换取 access_token 并在每个 API 请求的 Query 参数中无缝注入，内置令牌过期自愈机制。
• 阿里钉钉协同生态：全面适配 Teambition 项目与任务模型，支持项目分组、截止时间与指派人关联。
• 企业多租户隔离：支持自定义 Open API 服务基地址，适配公有云或混合云专有环境。
• 工业级弹性韧性：内置 Polly 标准韧性管道（429 Too Many Requests / 503 Service Unavailable 指数退避重试与熔断保护）及出站审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.Teambition

<PackageReference Include="Bitzsoft.Integrations.ProjectManagement.Teambition" Version="1.0.0" />

配置

在 appsettings.json 中配置 Teambition 连接器参数：

{
  "ProjectManagement": {
    "Teambition": {
      "AppKey": "your-teambition-app-key",
      "AppSecret": "your-teambition-app-secret",
      "BaseUrl": "https://open.teambition.com/api"
    }
  }
}

配置项说明

注册服务

支持通过配置源绑定或委托方式进行依赖注入注册：

using Microsoft.Extensions.DependencyInjection;

// 方式 1：通过 IConfiguration 绑定注册（推荐，默认读取 ProjectManagement:Teambition）
services.AddTeambitionProjectManagement(configuration);

// 自定义配置节路径：
// services.AddTeambitionProjectManagement(configuration, "Integrations:Teambition");

// 方式 2：通过委托手动配置注册
services.AddTeambitionProjectManagement(options =>
{
    options.AppKey = "your-teambition-app-key";
    options.AppSecret = "your-teambition-app-secret";
    options.BaseUrl = "https://open.teambition.com/api";
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 Teambition 项目与敏捷任务：

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement;
using Bitzsoft.Integrations.ProjectManagement.Dtos;
using TaskStatus = Bitzsoft.Integrations.ProjectManagement.Dtos.TaskStatus;

namespace YourNamespace;

public class TeambitionTaskAppService
{
    private readonly IProjectManagementService _pmService;

    public TeambitionTaskAppService(IProjectManagementService pmService)
    {
        _pmService = pmService;
    }

    public async Task<List<PmProject>> GetProjectsAsync(
        CancellationToken cancellationToken = default)
    {
        return await _pmService.ListProjectsAsync(cancellationToken);
    }

    public async Task<PmTask> CreateTaskAsync(
        string projectId,
        string taskName,
        string description,
        string? assigneeId = null,
        DateTimeOffset? dueDate = null,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateTaskRequest
        {
            ProjectId = projectId,
            Name = taskName,
            Description = description,
            AssigneeId = assigneeId,
            DueDate = dueDate,
            Priority = TaskPriority.High
        };

        return await _pmService.CreateTaskAsync(request, cancellationToken);
    }

    public async Task<PmTask> GetTaskDetailAsync(
        string taskId,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.GetTaskAsync(taskId, cancellationToken);
    }

    public async Task<PmTask> UpdateTaskAsync(
        string taskId,
        string newName,
        string? newDescription = null,
        CancellationToken cancellationToken = default)
    {
        var request = new UpdateTaskRequest
        {
            Name = newName,
            Description = newDescription
        };

        return await _pmService.UpdateTaskAsync(taskId, request, cancellationToken);
    }

    public async Task<PmResult> MarkTaskCompletedAsync(
        string taskId,
        CancellationToken cancellationToken = default)
    {
        return await _pmService.CompleteTaskAsync(taskId, cancellationToken);
    }

    public async Task<List<PmTask>> ListTasksAsync(
        string projectId,
        TaskStatus? status = null,
        CancellationToken cancellationToken = default)
    {
        var query = new TaskQuery
        {
            ProjectId = projectId,
            Status = status
        };

        return await _pmService.ListTasksAsync(query, cancellationToken);
    }
}

架构与鉴权原理

Teambition 连接器内部采用双层 Client 协同与自动令牌换取设计：

• Token 自动流转：通过 TeambitionTokenManager 维护应用 Token 生命周期，并具备并发信号量防穿透控制。
• 请求参数注入：业务请求发送时，内部 TeambitionHttpClient 自动将有效 access_token 追加至 URL Query 字符串，对上层调用方完全透明。

异常处理与弹性策略

连接器集成了基于 Polly 的指数退避重试与熔断机制：

• 限流防护：当触发 Teambition 接口限流（HTTP 429）或服务端瞬时抖动（HTTP 503）时，系统自动按照指数递增等待时间进行重试。
• 401 自愈：当遇到令牌失效错误时，底层自动触发凭据失效并重试，提升服务健壮性。

依赖

相关包