Bitzsoft.Integrations.TeamWork.DingTalk 1.0.0-alpha.7

Bitzsoft.Integrations.TeamWork.DingTalk

钉钉协同办公服务实现 — 对接钉钉开放平台 API。

功能特性

基于 Bitzsoft.Integrations.TeamWork 抽象层实现钉钉 6 个核心能力：

• 组织架构：部门递归遍历、员工分页查询与增删改（/topapi/v2）
• 消息推送：工作通知（文本）、卡片消息（Markdown）、消息撤回（corpconversation）
• 统一待办：创建（按办理人）、查询、标记完成；撤回钉钉不支持（抛 NotSupportedException）（workrecord）
• 审批流：发起、状态查询（含 RUNNING/COMPLETED/TERMINATED → 统一枚举映射）、撤回（processinstance）
• SSO 登录：新版 OAuth2 扫码授权、授权码换令牌、令牌刷新、令牌校验、用户信息（login.dingtalk.com + api.dingtalk.com/v1.0）
• 健康检查：通过轻量级鉴权调用探活

认证机制

钉钉两代 API 共存，本实现按场景分别对接：

DingTalkAuthHandler 仅对 oapi.dingtalk.com 请求追加 access_token 查询参数（显式排除 gettoken 路径防自递归），SSO 请求透传。令牌缓存采用双重检查锁 + SemaphoreSlim，提前 5 分钟刷新，避免边界过期与并发击穿。

安装

dotnet add package Bitzsoft.Integrations.TeamWork.DingTalk

<PackageReference Include="Bitzsoft.Integrations.TeamWork.DingTalk" Version="*" />

配置

{
  "TeamWork": {
    "DingTalk": {
      "AppKey": "钉钉应用 AppKey",
      "AppSecret": "钉钉应用 AppSecret",
      "AgentId": 123456,
      "BaseUrl": "https://oapi.dingtalk.com",
      "NewApiBaseUrl": "https://api.dingtalk.com",
      "LoginBaseUrl": "https://login.dingtalk.com",
      "CallbackToken": "回调 Token（可选）",
      "CallbackAesKey": "回调加解密 AES Key（可选）"
    }
  }
}

配置在 DI 注册时经 DingTalkOptionsValidator 校验，AppKey/AppSecret/AgentId 缺失或 URL 非 HTTPS 将启动即失败（fail-fast）。

注册服务

using Bitzsoft.Integrations.TeamWork.DingTalk;

services.AddBitzsoftDingTalkTeamWork(configuration, "TeamWork:DingTalk");

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftDingTalkTeamWork(configuration, "TeamWork:DingTalk");

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftDingTalkTeamWork(configuration, "TeamWork:DingTalk");

使用示例

// 按接口注入使用
public class NoticeService(ITeamWorkMessageProvider message, ITeamWorkSsoProvider sso)
{
    public Task<MessageSendResult> NotifyAsync(IReadOnlyList<string> userIds) =>
        message.SendWorkNotificationAsync(new WorkNotificationRequest
        {
            ToUserIds = userIds,
            Title = "系统通知",
            Content = "您有一条新待办"
        });

    public string BuildLoginUrl(string redirectUri) => sso.GetAuthorizationUrl(redirectUri);
}

平台限制说明

• 部门接口（listsub）仅返回下一级子部门，GetDepartmentsAsync 内部递归获取整棵子树。
• 员工接口（user/list）按部门查询，GetEmployeesAsync 默认查根部门直接成员；全公司员工需遍历各部门。
• 待办（workrecord）仅支持标记完成，RecallTodoAsync 抛 NotSupportedException。

目标框架

• .NET 5.0
• .NET 8.0
• .NET 10.0

相关包