Bitzsoft.Integrations.TeamWork.Feishu 1.0.0-alpha.9

Bitzsoft.Integrations.TeamWork.Feishu

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

实现状态

已完整实现 6 个核心接口（组织架构 / 消息推送 / 统一待办 / 审批流 / SSO / 健康检查）及飞书特有的日历、文档扩展接口，全部接入飞书开放平台真实 API，配套 47 个单元测试（net8.0 / net10.0 全绿）。

鉴权机制

飞书采用 Bearer 头鉴权，本包内置两类服务端令牌的自动管理：

• 令牌由 FeishuTokenManager 缓存，双重检查锁防止并发刷新，提前 300 秒刷新，业务失败返回令牌失效类错误码时自动失效并重试。
• 业务接口令牌由 FeishuHttpClient 按请求注入 Authorization: Bearer <token> 头；SSO 的 OIDC/用户信息接口由调用方显式传入 Bearer 令牌。

功能特性

基于 Bitzsoft.Integrations.TeamWork 抽象层实现飞书能力：

• 组织架构：部门列表（fetch_child 分页）、用户增删改查（contact v3）
• 消息推送：文本 / 交互卡片消息（im v1，多接收人逐条发送）、撤回
• 统一待办：任务创建（多办理人）、标记完成、列表、撤回（task v2）
• 审批流：发起、状态查询、撤回（approval v4）
• SSO 登录：OAuth2 / OIDC 授权码模式，授权、换令牌、刷新、用户信息
• 健康检查：以刷新 tenant_access_token 验证配置与连通性
• 日历管理（飞书特有）：事件增删改查（calendar v4，自动解析主日历）
• 文档协作（飞书特有）：创建（含初始正文块）、内容获取（标题 + 纯文本）、更新（docx v1）

安装

dotnet add package Bitzsoft.Integrations.TeamWork.Feishu

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

配置

{
  "TeamWork": {
    "Feishu": {
      "AppId": "飞书应用 App ID",
      "AppSecret": "飞书应用 App Secret",
      "BaseUrl": "https://open.feishu.cn",
      "EncryptKey": "事件订阅 Encrypt Key（可选）",
      "VerificationToken": "事件订阅 Verification Token（可选）"
    }
  }
}

注册服务

using Bitzsoft.Integrations.TeamWork.Feishu;

// 方式一：绑定配置节
services.AddBitzsoftFeishuTeamWork(configuration, "TeamWork:Feishu");

// 方式二：委托配置
services.AddBitzsoftFeishuTeamWork(opts =>
{
    opts.AppId = configuration["TeamWork:Feishu:AppId"];
    opts.AppSecret = configuration["TeamWork:Feishu:AppSecret"];
});

第三方请求日志

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

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

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

使用示例

public class MyService
{
    private readonly ITeamWorkOrgProvider _org;
    private readonly ITeamWorkMessageProvider _message;
    private readonly ITeamWorkCalendarProvider _calendar; // 注入扩展接口

    public MyService(ITeamWorkOrgProvider org, ITeamWorkMessageProvider message)
    {
        _org = org;
        _message = message;
    }

    public Task<IReadOnlyList<DepartmentInfo>> GetDepts() => _org.GetDepartmentsAsync();

    public async Task NotifyAsync(string openId, string text)
    {
        await _message.SendWorkNotificationAsync(new WorkNotificationRequest
        {
            ToUserIds = new[] { openId },
            Content = text
        });
    }
}

飞书实现了 ITeamWorkCalendarProvider 与 ITeamWorkDocumentProvider 扩展接口，使用前用 is 判断：

if (provider is ITeamWorkCalendarProvider calendarProvider)
{
    var eventId = await calendarProvider.CreateEventAsync(new CalendarEventRequest
    {
        Summary = "周会",
        Start = DateTimeOffset.Parse("2026-06-14T10:00:00Z"),
        End = DateTimeOffset.Parse("2026-06-14T11:00:00Z"),
        AttendeeUserIds = new[] { "ou_xxx" }
    });
}

SSO 单点登录

var sso = (ITeamWorkSsoProvider)provider;

// 1. 引导用户访问授权页
var authUrl = sso.GetAuthorizationUrl("https://app/callback", state: "xyz");

// 2. 回调拿到 code，换取用户访问令牌
var token = await sso.GetAccessTokenAsync(code, "https://app/callback");

// 3. 获取用户信息
var user = await sso.GetUserInfoAsync(token.AccessToken);

已知限制

• 待办状态：飞书任务仅支持标记完成（TodoStatus.Done），其余状态抛 NotSupportedException。
• 待办查询：GetTodosAsync(userId) 以应用身份返回可见任务，userId 不参与过滤（按指定用户精确过滤需 user_access_token）。
• 日历事件定位：事件读取 / 更新 / 删除基于主日历（抽象接口仅传 eventId）。若创建时指定了非主日历的 CalendarId，需自行维护 calendar_id。
• 审批表单：FormData 按 {name, value} 数组序列化为 JSON 字符串；复杂控件（附件、明细组等）需按实际审批模板定制。
• 真实联调：需企业提供 AppId / AppSecret 测试环境；本包以 mock 单元测试保证逻辑正确。

目标框架

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

相关包