Bitzsoft.Integrations.ProjectManagement.Yunxiao 1.0.4

Bitzsoft.Integrations.ProjectManagement.Yunxiao

阿里云效（Aliyun Yunxiao Projex / Codeup）项目管理连接器实现。遵循项目管理通用抽象规范，实现通用 IProjectManagementService 接口、专属的 IYunxiaoProjectManagementService 接口、IYunxiaoWorkitemClient 工作项客户端契约，并提供统一的 IYunxiaoClient 门面服务。

功能特性

• 通用契约对齐：完整实现 IProjectManagementService 抽象规范，支持项目空间查询、任务创建、详情获取、属性更新、任务完成与分页列表检索。
• Projex 空间协作检索：支持组织级项目协作空间的检索与关键词搜索（SearchProjectsAsync）。
• 工作项多维度检索：支持跨空间、多分类（需求 Req、缺陷 Bug、任务 Task）、标题模糊匹配精准组合检索（SearchWorkitemsAsync）。
• 工作项详情与自定义字段：全面提取工作项正文、状态、负责人、关联版本及自定义字段详细信息（GetWorkitemDetailAsync）。
• 工作项状态机转换：支持将需求、缺陷或任务平滑流转到指定目标状态（UpdateWorkitemStatusAsync）。
• 讨论与评论互动：支持在工作项下发布 Markdown 格式评论（AddCommentAsync）并读取历史讨论列表（GetCommentsAsync）。
• 敏捷迭代管理：支持查询项目空间下的敏捷迭代（Sprint）列表（ListIterationsAsync）。
• Codeup 代码合并请求：支持直接在云效 Codeup 代码仓库创建 Merge Request（CreateMergeRequestAsync）。
• 灵活的鉴权模型：原生支持云效个人访问令牌（PAT，x-yunxiao-token 标头）以及阿里云 RAM OpenAPI AccessKey HMAC 签名鉴权。
• 连通性探测自检：提供端到端 API 凭证连通性测试接口（TestConnectionAsync）。
• 工业级弹性韧性：集成 Polly 标准韧性管道（429/503 指数退避重试与熔断保护）及全量出站请求审计日志（RequestLogging）。

安装

dotnet add package Bitzsoft.Integrations.ProjectManagement.Yunxiao

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

配置

在 appsettings.json 中配置阿里云效连接器参数：

{
  "ProjectManagement": {
    "Yunxiao": {
      "BaseUrl": "https://openapi-rdc.aliyuncs.com",
      "Token": "your-codeup-pat-token",
      "OrganizationId": "your-aliyun-org-id",
      "SpaceId": "your-default-space-id",
      "Timeout": "00:00:30",
      "AccessKeyId": "optional-ram-access-key-id",
      "AccessKeySecret": "optional-ram-access-key-secret",
      "SignatureMethod": "HMAC-SHA1",
      "SignatureVersion": "1.0"
    }
  }
}

配置项说明

注册服务

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

using Microsoft.Extensions.DependencyInjection;

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

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

// 方式 2：通过委托手动配置注册
services.AddBitzsoftYunxiaoProjectManagement(options =>
{
    options.BaseUrl = "https://openapi-rdc.aliyuncs.com";
    options.Token = "your-codeup-pat-token";
    options.OrganizationId = "your-aliyun-org-id";
    options.SpaceId = "your-default-space-id";
    options.Timeout = TimeSpan.FromSeconds(30);
});

使用示例（通用 IProjectManagementService）

以下代码演示如何在业务类中通过依赖注入使用通用的 IProjectManagementService 契约操作阿里云效空间与工作项：

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

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

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

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

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

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

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

专有扩展能力（IYunxiaoProjectManagementService）

当业务需要调用云效专属功能（如空间多条件搜索、工作项状态机转换、评论互动、Codeup 代码合并请求发起）时，可直接注入专属接口 IYunxiaoProjectManagementService：

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement.Yunxiao;

namespace YourNamespace;

public class YunxiaoAdvancedWorkflowService
{
    private readonly IYunxiaoProjectManagementService _yunxiaoService;

    public YunxiaoAdvancedWorkflowService(IYunxiaoProjectManagementService yunxiaoService)
    {
        _yunxiaoService = yunxiaoService;
    }

    public async Task<List<YunxiaoWorkitemItem>> SearchBugsAsync(
        string spaceId,
        string keyword,
        CancellationToken cancellationToken = default)
    {
        return await _yunxiaoService.SearchWorkitemsAsync(
            spaceId: spaceId,
            category: "Bug",
            keyword: keyword,
            pageNumber: 1,
            pageSize: 50,
            ct: cancellationToken);
    }

    public async Task<bool> TransitionWorkitemAndCommentAsync(
        string workitemId,
        string targetStatus,
        string comment,
        CancellationToken cancellationToken = default)
    {
        // 1. 流转工作项状态机
        var updated = await _yunxiaoService.UpdateWorkitemStatusAsync(
            workitemId,
            targetStatus,
            ct: cancellationToken);

        // 2. 追加讨论评论
        if (updated && !string.IsNullOrWhiteSpace(comment))
        {
            await _yunxiaoService.AddCommentAsync(
                workitemId,
                comment,
                formatType: "MARKDOWN",
                ct: cancellationToken);
        }

        return updated;
    }

    public async Task<YunxiaoMergeRequestResult> CreateCodeupMergeRequestAsync(
        string repositoryId,
        string sourceBranch,
        string targetBranch,
        string title,
        string description,
        CancellationToken cancellationToken = default)
    {
        var request = new CreateYunxiaoMergeRequest
        {
            RepositoryId = repositoryId,
            SourceBranch = sourceBranch,
            TargetBranch = targetBranch,
            Title = title,
            Description = description
        };

        return await _yunxiaoService.CreateMergeRequestAsync(request, ct: cancellationToken);
    }
}

企业级统一门面（IYunxiaoClient）

云效连接器提供了聚合四大子系统的统一门面服务 IYunxiaoClient，涵盖项目协作、CI/CD 流水线、构建制品仓库与 Codeup 代码库管理：

using System.Threading;
using System.Threading.Tasks;
using Bitzsoft.Integrations.ProjectManagement.Yunxiao;

namespace YourNamespace;

public class YunxiaoDevOpsSuiteService
{
    private readonly IYunxiaoClient _yunxiaoClient;

    public YunxiaoDevOpsSuiteService(IYunxiaoClient yunxiaoClient)
    {
        _yunxiaoClient = yunxiaoClient;
    }

    public async Task RunDevOpsPipelineAsync(
        string pipelineId,
        string repoId,
        string branchName,
        CancellationToken cancellationToken = default)
    {
        // 1. Codeup 代码库与分支检索
        var branch = await _yunxiaoClient.Codeup.GetBranchAsync(repoId, branchName, cancellationToken);

        // 2. 触发 CI/CD 流水线运行
        var runResult = await _yunxiaoClient.Pipeline.RunPipelineAsync(pipelineId, null, cancellationToken);

        // 3. 轮询流水线运行状态至终态
        if (runResult != null)
        {
            await _yunxiaoClient.Pipeline.PollPipelineRunUntilTerminalAsync(
                pipelineId,
                runResult.PipelineRunId,
                ct: cancellationToken);
        }
    }
}

依赖

相关包