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

Bitzsoft.Integrations.TeamWork.Feishu

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

功能特性

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

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

鉴权机制

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

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

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.TeamWork.Feishu

PackageReference

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

配置

appsettings.json

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

配置在 DI 注册时经 FeishuOptionsValidator 校验，AppId/AppSecret 缺失将启动即失败。

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.TeamWork.Feishu;

builder.Services.AddBitzsoftFeishuTeamWork(
    builder.Configuration, "TeamWork:Feishu");

委托配置

builder.Services.AddBitzsoftFeishuTeamWork(opts =>
{
    opts.AppId = "your-app-id";
    opts.AppSecret = "your-app-secret";
});

第三方请求日志

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftFeishuTeamWork(configuration, "TeamWork:Feishu");

使用示例

核心接口

using Bitzsoft.Integrations.TeamWork.Interfaces;
using Bitzsoft.Integrations.TeamWork.Models.Message;

public class MyService(ITeamWorkOrgProvider org, ITeamWorkMessageProvider 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 calendar)
{
    var eventId = await calendar.CreateEventAsync(new CalendarEventRequest
    {
        Summary = "周会",
        Start = DateTimeOffset.Parse("2026-06-14T10:00:00Z"),
        End = DateTimeOffset.Parse("2026-06-14T11:00:00Z"),
        AttendeeUserIds = new[] { "ou_xxx" }
    });
}

if (provider is ITeamWorkDocumentProvider doc)
{
    var docId = await doc.CreateDocumentAsync(new DocumentCreateRequest { Title = "需求文档" });
    var content = await doc.GetDocumentContentAsync(docId);
}

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 单元测试保证逻辑正确。

依赖

相关包

• Bitzsoft.Integrations.TeamWork -- 协同办公抽象层
• Bitzsoft.Integrations.TeamWork.All -- 聚合包（自动注册全部供应商）
• Bitzsoft.Integrations.TeamWork.DingTalk -- 钉钉实现
• Bitzsoft.Integrations.TeamWork.WeCom -- 企业微信实现
• Bitzsoft.Integrations.Compatibility -- 基础工具库