Bitzsoft.Integrations.ProjectManagement.JiraCloud 1.0.4

Bitzsoft.Integrations.ProjectManagement.JiraCloud

Atlassian Jira Cloud 项目管理适配器。将 IProjectManagementService 统一抽象接口全面适配到底层 Bitzsoft.Integrations.JiraCloud 单体连接器的 IJiraCloudClient，支持任务（Issue）创建、详情获取、信息更新、工作流状态流转与受控 JQL 检索。

功能特性

• 完整任务生命周期管理：全面支持 Issue 创建（CreateTaskAsync）、详情获取（GetTaskAsync）、字段更新（UpdateTaskAsync）与任务完成（CompleteTaskAsync）。
• 智能工作流状态跃迁（Transitions）：内置智能状态映射算法，自动发现目标状态（如 Done/Closed/Resolved、In Progress/Start Progress、To Do/Reopen 等），调用 Jira Cloud REST API 执行状态机跃迁（TransitionTaskAsync）。
• Issue 讨论评论追加：支持为指定 Issue 写入讨论评论（AddCommentAsync）。
• 受控 JQL 检索：基于 Project 与 Status 进行受控 JQL 检索（ListTasksAsync），内置内存级别指派人过滤。
• 多租户与动态上下文工厂：通过 IJiraCloudPmContextFactory 动态为每一次 API 调用装配 JiraCloudRequestContext（包含租户标识 TenantId、授权主体 AuthorizationSubject 及凭据 ProfileId），原生支持 SaaS 多租户隔离。
• 边界说明：Jira Cloud 项目创建（CreateProjectAsync）与项目列表查询（ListProjectsAsync）属于 Jira Admin 专属管理范畴，调用将抛出明确的 ProjectManagementException，请通过 Jira 管理界面或专用 Admin API 维护项目空间。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.JiraCloud

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

配置

在 appsettings.json 中配置 Jira Cloud 适配器调用上下文参数：

{
  "ProjectManagement": {
    "JiraCloud": {
      "TenantId": "tenant-default",
      "AuthorizationSubject": "system-operator",
      "ProfileId": "default"
    }
  }
}

配置项说明

注册服务

宿主应用须先通过 JiraCloud 单体注册底层 IJiraCloudClient，再注册本项目管理适配器：

using Bitzsoft.Integrations.JiraCloud;
using Microsoft.Extensions.DependencyInjection;

// 1. 注册底层 Jira Cloud 单体客户端
// services.AddBitzsoftJiraCloud(endpointProfile, issuePolicies, webhookPolicies, webhookReceivers);

// 2. 注册项目管理适配器（三种方式任选其一）：

// 方式 A：通过 IConfiguration 配置节注册（单租户或缺省配置推荐）
services.AddJiraCloudProjectManagement(configuration);

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

// 方式 B：使用固定上下文注册
var context = new JiraCloudRequestContext(
    tenantId: "tenant-1",
    authorizationSubject: "operator-user",
    profileId: "default");
services.AddJiraCloudProjectManagement(context);

// 方式 C：使用自定义上下文工厂（多租户 SaaS 架构强烈推荐）
services.AddJiraCloudProjectManagement<CustomTenantJiraCloudContextFactory>();

多租户工厂实现示例

using Bitzsoft.Integrations.JiraCloud;
using Bitzsoft.Integrations.ProjectManagement.JiraCloud;

public class CustomTenantJiraCloudContextFactory : IJiraCloudPmContextFactory
{
    private readonly ITenantProvider _tenantProvider;

    public CustomTenantJiraCloudContextFactory(ITenantProvider tenantProvider)
    {
        _tenantProvider = tenantProvider;
    }

    public JiraCloudRequestContext Create()
    {
        var currentTenantId = _tenantProvider.GetCurrentTenantId();
        var currentUser = _tenantProvider.GetCurrentUserId();
        return new JiraCloudRequestContext(
            tenantId: currentTenantId,
            authorizationSubject: currentUser,
            profileId: "default");
    }
}

使用示例（通用 IProjectManagementService）

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

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

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

    public async Task<PmTask> CreateIssueAsync(
        string projectKey,
        string summary,
        string description,
        string? assigneeAccountId = null,
        DateTimeOffset? dueDate = null,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateTaskRequest
        {
            ProjectId = projectKey,
            Name = summary,
            Description = description,
            AssigneeId = assigneeAccountId,
            DueDate = dueDate,
            Priority = TaskPriority.Medium
        };

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

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

    public async Task<PmResult> UpdateIssueAsync(
        string issueKey,
        string summary,
        string description,
        CancellationToken cancellationToken = default)
    {
        var request = new UpdateTaskRequest
        {
            TaskId = issueKey,
            Name = summary,
            Description = description
        };

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

    public async Task<PmResult> CompleteIssueAsync(
        string issueKey,
        CancellationToken cancellationToken = default)
    {
        // 内部自动执行 Transitions 跃迁至 Done 状态
        return await _pmService.CompleteTaskAsync(issueKey, cancellationToken);
    }

    public async Task<List<PmTask>> ListProjectIssuesAsync(
        string projectKey,
        CancellationToken cancellationToken = default)
    {
        var request = new ListTasksRequest
        {
            ProjectId = projectKey,
            Status = TaskStatus.InProgress,
            PageIndex = 1,
            PageSize = 50
        };

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

专有扩展能力（JiraCloudPmAdapter 增强操作）

JiraCloudPmAdapter 还提供了直接的工作流智能状态流转（TransitionTaskAsync）以及 Issue 评论追加（AddCommentAsync）能力：

using System;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement;
using Bitzsoft.Integrations.ProjectManagement.Dtos;
using Bitzsoft.Integrations.ProjectManagement.JiraCloud;

namespace YourNamespace;

public class JiraCloudAdvancedWorkflowService
{
    private readonly JiraCloudPmAdapter _adapter;

    public JiraCloudAdvancedWorkflowService(IProjectManagementService pmService)
    {
        if (pmService is JiraCloudPmAdapter adapter)
        {
            _adapter = adapter;
        }
        else
        {
            throw new InvalidOperationException("当前注册的 Provider 不是 JiraCloudPmAdapter");
        }
    }

    public async Task<bool> MoveIssueStateAsync(
        string issueKey,
        string targetStatus,
        string? note = null,
        CancellationToken cancellationToken = default)
    {
        // 智能匹配 In Progress / In Development / Done 等状态动作并执行流转
        var transitionResult = await _adapter.TransitionTaskAsync(issueKey, targetStatus, cancellationToken);
        if (!transitionResult.Success)
        {
            return false;
        }

        if (!string.IsNullOrWhiteSpace(note))
        {
            await _adapter.AddCommentAsync(issueKey, note, cancellationToken);
        }

        return true;
    }
}

依赖

相关包