Bitzsoft.Integrations.ProjectManagement.JiraDataCenter 1.0.4

Bitzsoft.Integrations.ProjectManagement.JiraDataCenter

Atlassian Jira Server / Data Center 私有化部署连接器实现。遵循项目管理通用抽象规范，实现 IProjectManagementService 接口与专属的 IJiraDataCenterProjectManagementService 扩展接口。

功能特性

• 通用契约对齐：实现 IProjectManagementService 抽象规范，支持 Jira Issue 的创建、详情查询、属性更新、完成以及按项目状态过滤列表。
• 双模鉴权机制：支持企业级 Bearer PAT（Personal Access Token）认证与传统 HTTP Basic（Username + Password）认证。
• 企业内网与私有部署适配：原生支持 Jira REST API v2，支持自签名 SSL 证书信任配置（AllowInsecureCertificates）。
• 原生 JQL 查询语法：支持使用原生 Jira Query Language (JQL) 进行高阶复杂条件检索（SearchIssuesByJqlAsync）。
• 工作流状态跃迁（Transitions）：
  • 查询指定 Issue 当前可用的工作流跃迁动作列表（GetTransitionsAsync）
  • 根据 Transition ID 执行跃迁（DoTransitionAsync）
  • 智能状态流转（TransitionTaskAsync）：智能匹配 Done/In Progress/To Do 等状态分类与状态名称完成跃迁
• Issue 讨论评论：支持直接为 Issue 追加协作评论（AddCommentAsync）。
• 工业级弹性韧性：集成 Polly 标准韧性管道（429/503 指数退避重试与熔断保护）及全量出站请求审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.JiraDataCenter

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

配置

在 appsettings.json 中配置 Jira Data Center 连接器参数：

{
  "ProjectManagement": {
    "JiraDataCenter": {
      "BaseUrl": "https://jira.example.com",
      "PersonalAccessToken": "your-jira-bearer-pat-token",
      "Username": "optional-basic-username",
      "Password": "optional-basic-password",
      "DefaultProjectKey": "PROJ",
      "DefaultIssueType": "Task",
      "AllowInsecureCertificates": false
    }
  }
}

配置项说明

注册服务

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

using Microsoft.Extensions.DependencyInjection;

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

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

// 方式 2：通过委托手动配置注册
services.AddBitzsoftJiraDataCenterProjectManagement(options =>
{
    options.BaseUrl = "https://jira.example.com";
    options.PersonalAccessToken = "your-jira-bearer-pat-token";
    options.DefaultProjectKey = "PROJ";
    options.DefaultIssueType = "Task";
    options.AllowInsecureCertificates = false;
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作 Jira Data Center 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 JiraDataCenterTaskAppService
{
    private readonly IProjectManagementService _pmService;

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

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

        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<List<PmTask>> ListProjectIssuesAsync(
        string projectKey,
        CancellationToken cancellationToken = default)
    {
        var request = new ListTasksRequest
        {
            ProjectId = projectKey,
            Status = TaskStatus.InProgress,
            PageIndex = 1,
            PageSize = 25
        };

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

    public async Task<PmResult> CompleteIssueAsync(
        string issueKey,
        CancellationToken cancellationToken = default)
    {
        // 内部将智能流转至 Done 类别的工作流状态
        return await _pmService.CompleteTaskAsync(issueKey, cancellationToken);
    }
}

专有扩展能力（IJiraDataCenterProjectManagementService）

当业务需要深度使用 Jira 原生高级能力（如编写原生 JQL 查询、精准获取与执行工作流 Transitions 状态流转、追加评论）时，可直接注入专属接口 IJiraDataCenterProjectManagementService：

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

namespace YourNamespace;

public class JiraDataCenterWorkflowService
{
    private readonly IJiraDataCenterProjectManagementService _jiraDcService;

    public JiraDataCenterWorkflowService(IJiraDataCenterProjectManagementService jiraDcService)
    {
        _jiraDcService = jiraDcService;
    }

    public async Task<List<PmTask>> QueryIssuesByJqlAsync(
        string projectKey,
        string fixVersion,
        CancellationToken cancellationToken = default)
    {
        var jql = $"project = '{projectKey}' AND fixVersion = '{fixVersion}' AND statusCategory != Done ORDER BY priority DESC";
        return await _jiraDcService.SearchIssuesByJqlAsync(jql, startAt: 0, maxResults: 50, cancellationToken);
    }

    public async Task<bool> TransitionIssueWorkflowAsync(
        string issueKey,
        string targetStateName,
        string comment,
        CancellationToken cancellationToken = default)
    {
        // 1. 智能匹配并执行工作流跃迁
        var result = await _jiraDcService.TransitionTaskAsync(issueKey, targetStateName, cancellationToken);
        if (!result.Success)
        {
            return false;
        }

        // 2. 追加流转备注评论
        if (!string.IsNullOrWhiteSpace(comment))
        {
            await _jiraDcService.AddCommentAsync(issueKey, comment, cancellationToken);
        }

        return true;
    }

    public async Task<List<JiraDataCenterTransitionDto>> GetAvailableTransitionsAsync(
        string issueKey,
        CancellationToken cancellationToken = default)
    {
        return await _jiraDcService.GetTransitionsAsync(issueKey, cancellationToken);
    }
}

依赖

相关包