Bitzsoft.Integrations.ProjectManagement.Tapd 1.0.4

Bitzsoft.Integrations.ProjectManagement.Tapd

腾讯敏捷协作平台 TAPD OpenAPI 项目与工单连接器实现。遵循项目管理通用抽象规范，实现 IProjectManagementService 接口与专属的 ITapdProjectManagementService 扩展接口。

功能特性

• 通用契约对齐：实现 IProjectManagementService 抽象规范，统一映射 TAPD 项目空间（Workspace）、需求（Stories）、缺陷（Bugs）与子任务（Tasks）。
• 灵活鉴权模型：原生支持 HTTP Basic 鉴权（ApiUser + ApiPassword）以及 OAuth2 AccessToken（Bearer）鉴权模式。
• 三态敏捷工作流支持：提供需求（Stories）、缺陷（Bugs）、子任务（Tasks）全生命周期操作，支持不同实体专有数据结构与属性。
• 状态字典双向映射：内置 TAPD 各实体工作流状态字典（规划中、开发中、测试中、已解决、已验证、已关闭、已拒绝等）与统一 TaskStatus 状态枚举的双向映射。
• 状态流转与流转动作：支持精准流转需求（ChangeStoryStatusAsync）、缺陷（ChangeBugStatusAsync）与子任务（ChangeTaskStatusAsync）的工作流状态。
• 事项评论互动：支持在指定事项（需求、缺陷、任务）下发布讨论评论（AddCommentAsync）。
• 企业私有化支持：支持指定私有部署网关地址（BaseUrl）与自签名 SSL 证书信任（AllowInsecureCertificates）。
• 工业级弹性韧性：集成 Polly 标准韧性管道（429/503 指数退避重试与熔断保护）及全量出站请求审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.Tapd

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

配置

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

{
  "ProjectManagement": {
    "Tapd": {
      "BaseUrl": "https://api.tapd.cn",
      "ApiUser": "your-api-user",
      "ApiPassword": "your-api-password",
      "AccessToken": "optional-oauth-access-token",
      "CompanyId": "your-company-id",
      "DefaultWorkspaceId": "1000001",
      "AllowInsecureCertificates": false,
      "UserAgent": "Bitzsoft-Tapd/1.0"
    }
  }
}

配置项说明

注册服务

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

using Microsoft.Extensions.DependencyInjection;

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

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

// 方式 2：通过委托手动配置注册
services.AddBitzsoftTapdProjectManagement(options =>
{
    options.BaseUrl = "https://api.tapd.cn";
    options.ApiUser = "your-api-user";
    options.ApiPassword = "your-api-password";
    options.DefaultWorkspaceId = "1000001";
    options.AllowInsecureCertificates = false;
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 TAPD 工作项：

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 TapdTaskAppService
{
    private readonly IProjectManagementService _pmService;

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

    public async Task<PmTask> CreateStoryAsync(
        string workspaceId,
        string title,
        string description,
        string? owner = null,
        DateTimeOffset? dueDate = null,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateTaskRequest
        {
            ProjectId = workspaceId,
            Name = title,
            Description = description,
            AssigneeId = owner,
            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<List<PmTask>> ListWorkspaceTasksAsync(
        string workspaceId,
        CancellationToken cancellationToken = default)
    {
        var request = new ListTasksRequest
        {
            ProjectId = workspaceId,
            Status = TaskStatus.InProgress,
            PageIndex = 1,
            PageSize = 30
        };

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

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

专有扩展能力（ITapdProjectManagementService）

当业务需要针对 TAPD 的需求（Stories）、缺陷（Bugs）与子任务（Tasks）三态进行差异化精准操作、执行细粒度状态机流转或追加评论时，可直接注入专属接口 ITapdProjectManagementService：

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

namespace YourNamespace;

public class TapdAdvancedWorkflowService
{
    private readonly ITapdProjectManagementService _tapdService;

    public TapdAdvancedWorkflowService(ITapdProjectManagementService tapdService)
    {
        _tapdService = tapdService;
    }

    public async Task<TapdStory> CreateStoryWithWorkflowAsync(
        string workspaceId,
        string storyName,
        string description,
        string owner,
        CancellationToken cancellationToken = default)
    {
        var request = new TapdCreateStoryRequest
        {
            WorkspaceId = workspaceId,
            Name = storyName,
            Description = description,
            Owner = owner,
            Priority = "High"
        };

        return await _tapdService.CreateStoryAsync(request, cancellationToken);
    }

    public async Task<TapdBug> ReportBugAsync(
        string workspaceId,
        string title,
        string description,
        string currentOwner,
        CancellationToken cancellationToken = default)
    {
        var request = new TapdCreateBugRequest
        {
            WorkspaceId = workspaceId,
            Title = title,
            Description = description,
            CurrentOwner = currentOwner,
            Priority = "urgent",
            Severity = "fatal"
        };

        return await _tapdService.CreateBugAsync(request, cancellationToken);
    }

    public async Task<bool> AdvanceBugWorkflowAsync(
        string workspaceId,
        string bugId,
        string nextStatus,
        string comment,
        string author,
        CancellationToken cancellationToken = default)
    {
        var statusChanged = await _tapdService.ChangeBugStatusAsync(
            workspaceId,
            bugId,
            nextStatus,
            cancellationToken);

        if (statusChanged && !string.IsNullOrWhiteSpace(comment))
        {
            await _tapdService.AddCommentAsync(
                workspaceId,
                "bug",
                bugId,
                comment,
                author,
                cancellationToken);
        }

        return statusChanged;
    }

    public async Task<List<TapdStory>> GetActiveStoriesAsync(
        string workspaceId,
        CancellationToken cancellationToken = default)
    {
        return await _tapdService.ListStoriesAsync(
            workspaceId,
            pageIndex: 1,
            pageSize: 50,
            status: "developing",
            cancellationToken: cancellationToken);
    }
}

依赖

相关包