如何在.NET系统中快速集成飞书任务分配能力
<blockquote><p>想象一下这样的场景：客户焦急地等待问题解决，而你的团队却在一堆邮件、Excel表格和零散的IM消息中手忙脚乱。这是不是很多企业每天都在上演的真实写照？</p>
</blockquote>
<p>在数字化转型的浪潮中，我们不仅要让系统"能用"，更要让团队"好用"。飞书就像是协作世界的"超级英雄"，它能让原本各自为战的业务系统手拉手，让信息像流水一样顺畅流动。</p>
<p>今天，就让我们一起踏上一段奇妙的旅程——借助Mud.Feishu这个强大的开源工具，为我们的.NET业务系统装上"协作翅膀"，实现从传统的工单处理到现代化的全链路任务协同的华丽转身。</p>
<h2 id="为什么我们的系统需要协作升级">为什么我们的系统需要"协作升级"？</h2>
<h3 id="当孤岛遇上协作那些年我们一起踩过的坑">当孤岛遇上协作：那些年我们一起踩过的坑</h3>
<p>还记得那个尴尬的下午吗？客户在电话那头焦急地询问："我的问题解决得怎么样了？" 而你却在三个不同的系统之间来回切换，试图拼凑出完整的答案。</p>
<p>随着企业越来越大，业务越来越复杂，我们的传统系统就像一个个独立的"小岛"，虽然每个小岛上都有宝藏（数据），但它们之间却没有桥梁：</p>
<ol>
<li>
<p><strong>信息都在各自的"保险柜"里</strong>：客服用一套系统，技术用另一套，产品还有自己的系统。想要看全局？那可真是个挑战！</p>
</li>
<li>
<p><strong>沟通还在"石器时代"</strong>：邮件一来一回可能要等几小时，重要消息可能淹没在收件箱里，IM聊天记录又容易被刷屏遗忘。</p>
</li>
<li>
<p><strong>任务进展像"盲人摸象"</strong>：谁在负责什么？进行到哪一步了？这些问题往往需要开会问一圈才能搞清楚。</p>
</li>
<li>
<p><strong>跨部门协作像"跨越大海"</strong>：技术说这是产品问题，产品说这是客服问题，客户的问题在部门之间"漂流"，最后不了了之。</p>
</li>
</ol>
<h3 id="飞书api给传统系统装上智能大脑">飞书API给传统系统装上"智能大脑"</h3>
<p>如果说传统系统是"单机版"，那么飞书API就是让它们连入"互联网"的魔法棒。飞书不仅仅是又一个办公软件，它的任务管理API就像是协作世界的"通用语言"：</p>
<ul>
<li>
<p><strong>开放的"乐高积木"</strong>：丰富的API接口就像乐高积木，你可以随心所欲地搭建适合自己的协作场景。</p>
</li>
<li>
<p><strong>实时"心跳感应"</strong>：基于WebSocket的推送机制让任务状态变化像心跳一样实时传递，告别"刷新查看"的等待时代。</p>
</li>
<li>
<p><strong>移动"随身助手"</strong>：无论你在咖啡厅还是在路上，手机上的任务提醒和更新都不会错过重要事项。</p>
</li>
<li>
<p><strong>企业"安全卫士"</strong>：完善的权限管理和数据加密，让敏感信息在开放协作的同时依然安全可靠。</p>
</li>
</ul>
<h3 id="为什么net是最佳选择">为什么.NET是最佳选择</h3>
<p>在众多技术栈中，.NET就像是那个稳重又有内涵的"理想伴侣"，特别适合承担企业级集成的重任：</p>
<ul>
<li>
<p><strong>稳如泰山的"老司机"</strong>：.NET平台经过多年历练，性能稳定可靠，就像一个经验丰富的老司机，能在复杂的业务环境中稳健前行。</p>
</li>
<li>
<p><strong>微软"靠山"很给力</strong>：有微软这样的技术巨头长期支持，不用担心技术路线突然变卦，开发路上更有安全感。</p>
</li>
<li>
<p><strong>与时俱进"新青年"</strong>：从.NET 6.0开始，整个平台焕然一新，异步编程和并发处理能力让复杂场景的处理变得游刃有余。</p>
</li>
<li>
<p><strong>工具链"豪华套餐"</strong>：Visual Studio就像是一把"瑞士军刀"，配合NuGet这个"百宝箱"，开发效率自然节节攀升。</p>
</li>
</ul>
<h2 id="一个真实的应用场景客服小王的一天">一个真实的应用场景：客服小王的一天</h2>
<h3 id="小王的日常折磨传统工单系统的困境">小王的"日常折磨"：传统工单系统的困境</h3>
<p>让我们跟随客服小王，看看她是如何在传统工单系统中"挣扎"的：</p>
<p>早上9点，小王刚坐下就收到了客户的紧急投诉。她迅速在系统中创建了工单，然后发送邮件给技术部门的老李。两个小时过去了，老李才回复说这个问题需要产品部门的小张确认...</p>
<p>这听起来是不是很熟悉？传统工单系统就像是一个"信息传递游戏"，每个人都在等待，客户却在焦虑。让我们看看小王的工作流程图：</p>
<div class="mermaid">graph TD
A[客户提交工单] --> B[邮件通知客服]
B --> C[手动分配处理人]
C --> D
D --> E
E --> F[手动更新状态]
F --> G[邮件回复客户]
style B fill:#ffcccc
style D fill:#ffcccc
style E fill:#ffcccc
style G fill:#ffcccc
</div><p>看到那些红色的步骤了吗？每一步都是小王工作中的"痛点"。</p>
<h3 id="三个让小王头疼的大难题">三个让小王"头疼"的大难题</h3>
<h4 id="️-难题一任务消失在信息黑洞里">🌫️ 难题一：任务消失在"信息黑洞"里</h4>
<p>小王每天都在玩"捉迷藏"游戏：</p>
<ul>
<li><strong>邮件森林</strong>：重要的任务分配邮件可能被淹没在收件箱的数百封邮件中</li>
<li><strong>IM聊天刷屏</strong>：关键信息在群聊里被各种表情包和闲聊淹没</li>
<li><strong>管理层的"望远镜"</strong>：想要了解整体进度？那就得一个个去问，就像用望远镜看星星</li>
<li><strong>客户的"猜谜游戏"</strong>：客户打电话问进度，小王只能尴尬地说"我帮您问问"</li>
</ul>
<h4 id="-难题二跨部门协作像拼图游戏">🧩 难题二：跨部门协作像"拼图游戏"</h4>
<p>工单在不同部门之间传递，就像是在玩拼图，但总少了几块：</p>
<ul>
<li><strong>系统"方言"不同</strong>：客服系统、技术系统、产品系统各自说各自的"语言"</li>
<li><strong>信息"接力赛"中的掉棒</strong>：工单在传递过程中，重要的背景信息"不翼而飞"</li>
<li><strong>责任"皮球游戏"</strong>：这到底是技术问题还是产品问题？大家开始踢皮球</li>
<li><strong>知识"孤岛"</strong>：解决方案和个人经验都留在了各自的大脑里，无法形成团队财富</li>
</ul>
<h4 id="-难题三优先级管理像无头苍蝇">⏰ 难题三：优先级管理像"无头苍蝇"</h4>
<p>传统系统就像是没有导航的司机：</p>
<ul>
<li><strong>SLA"定时炸弹"</strong>：重要的工单快要到期了，但系统不会自动提醒</li>
<li><strong>进度"盲人摸象"</strong>：哪个工单会超时？只能凭感觉猜测</li>
<li><strong>管理层"雾里看花"</strong>：想要全局视图？抱歉，系统只支持单点查看</li>
<li><strong>资源调配"拍脑袋"</strong>：谁该处理什么任务？更多靠经验而非数据</li>
</ul>
<h3 id="小王的逆袭当工单系统遇上飞书">小王的"逆袭"：当工单系统遇上飞书</h3>
<p>现在，让我们看看当飞书任务管理介入后，小王的工作发生了怎样的神奇变化：</p>
<div class="mermaid">graph TD
A[客户提交工单] --> B[✨ 自动创建飞书任务]
B --> C[🎯 智能分配责任人]
C --> D[📱 实时状态同步]
D --> E[🤝 多方协同处理]
E --> F[⏰ 自动预警提醒]
F --> G[🎉 完成自动通知]
style B fill:#ccffcc
style C fill:#ccffcc
style D fill:#ccffcc
style E fill:#ccffcc
style F fill:#ccffcc
style G fill:#ccffcc
</div><p>看到那些绿色步骤了吗？每一个都代表着小王工作效率的飞跃提升！</p>
<p><strong>小王的"幸福感提升清单"</strong>：</p>
<ul>
<li>
<p>🚀 <strong>从手工到自动化</strong>：原来要人工操作的步骤，现在系统自动搞定，小王终于有时间喝杯咖啡了</p>
</li>
<li>
<p>🔍 <strong>从黑盒到透明</strong>：任务进展一目了然，管理层再也不用追着她问进度，客户也能自己查看状态</p>
</li>
<li>
<p>🌉 <strong>从孤岛到通途</strong>：统一的协作平台让跨部门合作变得像"左邻右舍"一样自然</p>
</li>
<li>
<p>😊 <strong>从被动到主动</strong>：客户收到实时更新通知，满意度直线上升，小王的KPI也跟着水涨船高</p>
</li>
</ul>
<h2 id="搭积木的艺术构建我们的协作桥梁">搭积木的艺术：构建我们的协作桥梁</h2>
<h3 id="先看看我们的家底现有系统是什么样的">先看看我们的"家底"：现有系统是什么样的</h3>
<p>在企业级应用的世界里，.NET系统就像是精心设计的"建筑"，主要有两种常见的"建筑风格"：</p>
<h4 id="经典的处理流程">经典的处理流程</h4>
<div class="mermaid">graph TB
subgraph "表现层 Presentation Layer"
A
B[前端应用 React/Vue]
end
subgraph "业务逻辑层 Business Logic Layer"
C[工单管理服务]
D[客户管理服务]
E[通知服务]
end
subgraph "数据访问层 Data Access Layer"
F
G
end
A --> C
A --> D
B --> A
C --> F
D --> F
E --> C
F --> G
</div><h4 id="微服务的现代布局">微服务的现代布局</h4>
<div class="mermaid">graph TB
subgraph "API网关"
A
end
subgraph "微服务集群"
B[工单服务]
C[用户服务]
D[通知服务]
E[订单服务]
end
subgraph "基础设施"
F
G
H
end
A --> B
A --> C
A --> D
A --> E
B --> F
B --> G
C --> F
D --> F
E --> H
</div><h3 id="使用飞书后优化的系统流程">使用飞书后优化的系统流程</h3>
<p>现在到了最激动人心的部分！我们要在现有系统和飞书之间搭建一座"智能桥梁"。这个桥不是用砖块，而是用代码和智慧搭建的：</p>
<div class="mermaid">graph TB
subgraph "业务应用层"
A[工单管理系统]
B[客户支持系统]
C[项目管理系统]
end
subgraph "飞书集成适配层"
D
E
F
end
subgraph "同步服务层"
G[任务同步服务]
H[事件路由服务]
I[状态同步服务]
end
subgraph "监控与回退机制"
J[健康监控]
K[重试机制]
L[降级策略]
end
subgraph "飞书平台"
M[飞书任务API]
N[飞书WebSocket]
O[飞书事件订阅]
end
A --> G
B --> G
C --> G
G --> D
G --> E
G --> F
D --> M
E --> N
F --> O
G --> H
H --> I
G --> J
J --> K
K --> L
</div><h4 id="适配层组件交互流程">适配层组件交互流程</h4>
<div class="mermaid">sequenceDiagram
participant B as 业务系统
participant S as 同步服务
participant A as 适配层
participant F as 飞书平台
participant W as WebSocket/Webhook
Note over B,W: 双向数据同步流程
B->>S: 创建/更新工单
S->>A: 调用任务API
A->>F: HTTP API调用
F-->>A: 返回结果
A-->>S: 同步完成
S-->>B: 更新关联ID
Note over F,W: 实时事件推送
F->>W: 任务状态变更
W->>A: 事件通知
A->>S: 处理业务逻辑
S->>B: 更新工单状态
</div><h4 id="适配层mudfeishu封装">适配层（Mud.Feishu封装）</h4>
<p>Mud.Feishu提供了完整的飞书API封装：</p>
<ul>
<li><strong>HTTP API客户端</strong>：基于<code>IFeishuTenantV2Task</code>接口，提供完整的任务管理能力</li>
<li><strong>WebSocket客户端</strong>：实时事件订阅，支持自动重连和心跳检测</li>
<li><strong>Webhook处理器</strong>：HTTP回调事件处理，支持事件路由和中间件模式</li>
</ul>
<p>Mud.Feishu源码仓库：Gitee,Github</p>
<pre><code class="language-csharp">// 核心接口定义示例
public interface IFeishuTaskAdapter
{
Task<string> CreateTaskAsync(CreateTaskRequest request);
Task<TaskInfo> GetTaskAsync(string taskGuid);
Task<bool> UpdateTaskAsync(string taskGuid, UpdateTaskRequest request);
Task<bool> DeleteTaskAsync(string taskGuid);
}
</code></pre>
<h4 id="同步服务双向事件驱动">同步服务（双向/事件驱动）</h4>
<p>同步服务负责业务系统与飞书之间的数据同步：</p>
<pre><code class="language-csharp">public class TaskSyncService
{
private readonly IFeishuTaskAdapter _feishuAdapter;
private readonly ITicketRepository _ticketRepository;
private readonly ILogger<TaskSyncService> _logger;
// 双向同步逻辑
public async Task SyncTicketToTaskAsync(string ticketId)
{
var ticket = await _ticketRepository.GetByIdAsync(ticketId);
if (ticket?.FeishuTaskId == null)
{
var taskRequest = MapTicketToTask(ticket);
var result = await _feishuAdapter.CreateTaskAsync(taskRequest);
ticket.FeishuTaskId = result;
await _ticketRepository.UpdateAsync(ticket);
}
}
}
</code></pre>
<h4 id="监控与回退机制">监控与回退机制</h4>
<p>确保集成系统的稳定性和可靠性：</p>
<ul>
<li><strong>健康监控</strong>：定期检查API可用性和连接状态</li>
<li><strong>重试机制</strong>：网络异常时自动重试，支持指数退避策略</li>
<li><strong>降级策略</strong>：飞书服务不可用时，系统可降级到本地任务管理</li>
</ul>
<h3 id="数据同步策略">数据同步策略</h3>
<h4 id="实时同步关键状态变更">实时同步（关键状态变更）</h4>
<p>通过WebSocket和Webhook实现关键状态的实时同步：</p>
<div class="mermaid">graph LR
subgraph "实时事件流"
A[飞书任务状态变更] --> B
B --> C[事件路由器]
C --> D[状态同步服务]
D --> E[业务系统]
end
subgraph "批量补偿流"
F[定时任务触发] --> G[数据对账服务]
G --> H[差异检测]
H --> I[数据修复]
I --> E
end
</div><pre><code class="language-csharp">// WebSocket事件处理示例
public class TaskEventHandler : IFeishuEventHandler
{
public string SupportedEventType => "task.status_changed";
public async Task HandleAsync(EventData eventData, CancellationToken cancellationToken = default)
{
switch (eventData.EventType)
{
case "task.status_changed":
await HandleTaskStatusChanged(eventData);
break;
case "task.assignee_updated":
await HandleAssigneeUpdated(eventData);
break;
}
}
}
</code></pre>
<h4 id="批量补偿定时对账">批量补偿（定时对账）</h4>
<p>定时执行批量对账，确保数据一致性：</p>
<pre><code class="language-csharp">public class TaskReconciliationService : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
await ReconcileTasksAsync();
await Task.Delay(TimeSpan.FromHours(1), stoppingToken);
}
}
}
</code></pre>
<h3 id="安全方案">安全方案</h3>
<h4 id="oauth-20流程">OAuth 2.0流程</h4>
<p>基于Mud.Feishu的令牌管理机制：</p>
<pre><code class="language-csharp">// 配置示例
builder.Services.AddFeishuServices()
.ConfigureFrom(builder.Configuration)
.AddTaskApi()
.AddTokenManagers()
.Build();
</code></pre>
<h4 id="api密钥管理">API密钥管理</h4>
<ul>
<li>应用密钥安全存储（环境变量/密钥管理服务）</li>
<li>访问令牌自动刷新和缓存</li>
<li>权限最小化原则，按需申请API权限</li>
</ul>
<h4 id="ip白名单">IP白名单</h4>
<p>在飞书开放平台配置服务端IP白名单，增强安全性。</p>
<h2 id="动手时间一步步打造你的飞书集成模块">动手时间：一步步打造你的飞书集成模块</h2>
<h3 id="1-准备工作让一切就绪">1. 准备工作：让一切就绪</h3>
<h4 id="第一步和飞书握手创建应用">第一步：和飞书"握手"——创建应用</h4>
<p>让我们先到飞书开放平台这个"游乐场"注册我们的"入场券"：</p>
<ol>
<li>
<p><strong>打开大门</strong>：访问 https://open.feishu.cn/，就像走进一个充满可能性的新世界</p>
</li>
<li>
<p><strong>领取身份卡</strong>：创建企业自建应用</p>
<ul>
<li>给它起个响亮的名字："客户支持工单集成助手"</li>
<li>写个自我介绍："我是来帮大家告别工单混乱的小能手"</li>
</ul>
</li>
<li>
<p><strong>申请通行证</strong>：配置应用权限</p>
<ul>
<li>任务管理全权限：读取、创建、更新、删除（就像给了一把万能钥匙）</li>
<li>任务清单查看权：知道任务放在哪个"房间"</li>
<li>用户基本信息权：认识团队里的每个"小伙伴"</li>
<li>事件订阅权：能够监听任务世界的"风吹草动"</li>
</ul>
</li>
<li>
<p><strong>设置专属热线</strong>：配置事件订阅</p>
<ul>
<li>提供你的"电话号码"（请求网址）：<code>https://your-domain.com/api/feishu/webhook</code></li>
<li>准备"暗号"（验证Token）：只有你懂的验证字符串</li>
<li>配置"保险箱"（数据加密密钥）：用AES-256保护敏感信息</li>
</ul>
</li>
</ol>
<h4 id="第二步搭建我们的开发工作室">第二步：搭建我们的"开发工作室"</h4>
<p>现在让我们创建一个干净的.NET项目，并邀请我们的"得力助手"们加入：</p>
<pre><code class="language-xml"><Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Mud.Feishu" Version="1.0.9" />
<PackageReference Include="Mud.Feishu.WebSocket" Version="1.0.9" />
<PackageReference Include="Mud.Feishu.Webhook" Version="1.0.9" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.0" />
</ItemGroup>
</Project>
</code></pre>
<h4 id="基础配置文件">基础配置文件</h4>
<pre><code class="language-json">{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"Feishu": {
"AppId": "cli_xxxxxxxxxxxxxxxx",
"AppSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"BaseUrl": "https://open.feishu.cn",
"TimeOut": "30",
"RetryCount": 3
},
"Feishu:WebSocket": {
"AutoReconnect": true,
"MaxReconnectAttempts": 5,
"ReconnectDelayMs": 5000,
"HeartbeatIntervalMs": 30000,
"EnableLogging": true
},
"FeishuWebhook": {
"RoutePrefix": "api/feishu/webhook",
"VerificationToken": "your_verification_token",
"EncryptKey": "your_encrypt_key",
"EnableRequestLogging": true
},
"ConnectionStrings": {
"DefaultConnection": "Server=.;Database=TicketSystem;Trusted_Connection=true;"
}
}
</code></pre>
<h3 id="2-核心魔法让代码活起来">2. 核心魔法：让代码活起来</h3>
<h4 id="认证服务让系统记住我是谁">认证服务：让系统"记住"我是谁</h4>
<p>想象一下，每次调用飞书API都要重新登录是多么繁琐。幸运的是，Mud.Feishu已经为我们准备了一个"智能门卫"，它会自动处理认证和刷新token这些烦人的事情。我们只需要告诉它"密码"在哪里就行：</p>
<div class="mermaid">graph TB
subgraph "服务注册架构"
A[.NET Host Builder] --> B[飞书API服务]
A --> C
A --> D
A --> E[自定义业务服务]
B --> F
B --> G[任务API客户端]
C --> H
C --> I[事件处理器1]
C --> J[事件处理器2]
D --> K
D --> L[事件处理器]
E --> M[任务同步服务]
E --> N[通知服务]
end
</div><pre><code class="language-csharp">// Program.cs - 服务注册
var builder = WebApplication.CreateBuilder(args);
// 注册飞书服务
builder.Services.AddFeishuServices()
.ConfigureFrom(builder.Configuration)
.AddTaskApi()
.AddTokenManagers()
.Build();
// 注册WebSocket服务
builder.Services.AddFeishuWebSocketServiceBuilder()
.ConfigureFrom(builder.Configuration)
.UseMultiHandler()
.AddHandler<TaskEventHandler>()
.AddHandler<TicketEventHandler>()
.Build();
// 注册Webhook服务
builder.Services.AddFeishuWebhookServiceBuilder(builder.Configuration)
.AddHandler<TaskWebhookHandler>()
.Build();
// 自定义服务注册
builder.Services.AddScoped<IFeishuTaskService, FeishuTaskService>();
builder.Services.AddScoped<ITicketSyncService, TicketSyncService>();
</code></pre>
<h4 id="任务api客户端开箱即用的飞书-net-sdk">任务API客户端：开箱即用的飞书 .net SDK</h4>
<pre><code class="language-csharp">public interface IFeishuTaskService
{
Task<string> CreateTaskFromTicketAsync(Ticket ticket);
Task<bool> UpdateTaskAsync(string taskGuid, UpdateTaskRequest request);
Task<TaskInfo?> GetTaskAsync(string taskGuid);
Task<bool> DeleteTaskAsync(string taskGuid);
Task<bool> AddTaskMemberAsync(string taskGuid, string userId, string role);
Task<List<TaskInfo>> GetTasksByProjectAsync(string projectKey);
}
public class FeishuTaskService : IFeishuTaskService
{
private readonly IFeishuTenantV2Task _taskApi;
private readonly ILogger<FeishuTaskService> _logger;
private readonly IMapper _mapper;
public FeishuTaskService(
IFeishuTenantV2Task taskApi,
ILogger<FeishuTaskService> logger,
IMapper mapper)
{
_taskApi = taskApi ?? throw new ArgumentNullException(nameof(taskApi));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
_mapper = mapper ?? throw new ArgumentNullException(nameof(mapper));
}
public async Task<string> CreateTaskFromTicketAsync(Ticket ticket)
{
try
{
var createRequest = _mapper.Map<CreateTaskRequest>(ticket);
// 设置任务清单
createRequest.Tasklists = new[]
{
new TaskInTaskListInfo
{
TasklistGuid = GetTaskListByPriority(ticket.Priority),
CustomFields = GetCustomFieldsForTicket(ticket)
}
};
// 设置任务成员
var assignees = await GetAssigneesForTicket(ticket);
createRequest.Members = assignees.Select(u => new TaskMemberInfo
{
UserId = u.FeishuUserId,
UserType = UserType.User,
TaskRole = TaskRole.Assignee
}).ToArray();
// 设置截止时间
if (ticket.DueDate.HasValue)
{
createRequest.Due = new TaskTime
{
Timestamp = ((DateTimeOffset)ticket.DueDate.Value).ToUnixTimeMilliseconds().ToString()
};
}
// 设置提醒
if (ticket.Priority == TicketPriority.High)
{
createRequest.Reminders = new[]
{
new TaskReminder
{
MinutesBefore = 60, // 1小时前提醒
ReminderType = ReminderType.Push
}
};
}
var result = await _taskApi.CreateTaskAsync(createRequest);
if (result?.Code == 0 && result.Data != null)
{
_logger.LogInformation("成功创建飞书任务，工单ID: {TicketId}, 任务ID: {TaskGuid}",
ticket.Id, result.Data.Task.Guid);
return result.Data.Task.Guid;
}
_logger.LogError("创建飞书任务失败，工单ID: {TicketId}, 错误: {Error}",
ticket.Id, result?.Msg);
throw new FeishuException($"创建飞书任务失败: {result?.Msg}");
}
catch (Exception ex)
{
_logger.LogError(ex, "创建飞书任务时发生异常，工单ID: {TicketId}", ticket.Id);
throw;
}
}
public async Task<bool> UpdateTaskAsync(string taskGuid, UpdateTaskRequest request)
{
try
{
var result = await _taskApi.UpdateTaskAsync(taskGuid, request);
var success = result?.Code == 0;
if (success)
{
_logger.LogInformation("成功更新飞书任务，任务ID: {TaskGuid}", taskGuid);
}
else
{
_logger.LogWarning("更新飞书任务失败，任务ID: {TaskGuid}, 错误: {Error}",
taskGuid, result?.Msg);
}
return success;
}
catch (Exception ex)
{
_logger.LogError(ex, "更新飞书任务时发生异常，任务ID: {TaskGuid}", taskGuid);
return false;
}
}
public async Task<TaskInfo?> GetTaskAsync(string taskGuid)
{
try
{
var result = await _taskApi.GetTaskByIdAsync(taskGuid);
return result?.Code == 0 ? result.Data?.Task : null;
}
catch (Exception ex)
{
_logger.LogError(ex, "获取飞书任务详情时发生异常，任务ID: {TaskGuid}", taskGuid);
return null;
}
}
public async Task<bool> DeleteTaskAsync(string taskGuid)
{
try
{
var result = await _taskApi.DeleteTaskByIdAsync(taskGuid);
var success = result?.Code == 0;
if (success)
{
_logger.LogInformation("成功删除飞书任务，任务ID: {TaskGuid}", taskGuid);
}
return success;
}
catch (Exception ex)
{
_logger.LogError(ex, "删除飞书任务时发生异常，任务ID: {TaskGuid}", taskGuid);
return false;
}
}
private string GetTaskListByPriority(TicketPriority priority)
{
return priority switch
{
TicketPriority.High => "high_priority_tasklist_guid",
TicketPriority.Medium => "medium_priority_tasklist_guid",
TicketPriority.Low => "low_priority_tasklist_guid",
_ => "default_tasklist_guid"
};
}
private CustomFieldValue[] GetCustomFieldsForTicket(Ticket ticket)
{
return new[]
{
new CustomFieldValue
{
FieldId = "ticket_id_field",
TextValue = ticket.Id
},
new CustomFieldValue
{
FieldId = "customer_field",
TextValue = ticket.CustomerName
},
new CustomFieldValue
{
FieldId = "project_field",
SingleSelectValue = new EnumValue
{
Id = ticket.ProjectId.ToString()
}
}
};
}
}
</code></pre>
<h4 id="websocket处理器飞书事件快递员">WebSocket处理器：飞书事件"快递员"</h4>
<pre><code class="language-csharp">public class TaskEventHandler : IFeishuEventHandler
{
private readonly IFeishuTaskService _taskService;
private readonly ITicketSyncService _syncService;
private readonly ILogger<TaskEventHandler> _logger;
public TaskEventHandler(
IFeishuTaskService taskService,
ITicketSyncService syncService,
ILogger<TaskEventHandler> logger)
{
_taskService = taskService;
_syncService = syncService;
_logger = logger;
}
public string SupportedEventType => "task.status_changed";
public async Task HandleAsync(EventData eventData, CancellationToken cancellationToken = default)
{
try
{
switch (eventData.EventType)
{
case "task.status_changed":
await HandleTaskStatusChangedAsync(eventData);
break;
case "task.assignee_updated":
await HandleAssigneeUpdatedAsync(eventData);
break;
case "task.comment_added":
await HandleCommentAddedAsync(eventData);
break;
default:
_logger.LogDebug("收到未处理的任务事件类型: {EventType}", eventData.EventType);
break;
}
}
catch (Exception ex)
{
_logger.LogError(ex, "处理飞书任务事件时发生异常，事件类型: {EventType}", eventData.EventType);
}
}
private async Task HandleTaskStatusChangedAsync(EventData eventData)
{
var taskEvent = JsonSerializer.Deserialize<TaskStatusChangedEvent>(eventData.Data.ToString());
_logger.LogInformation("任务状态变更，任务ID: {TaskGuid}, 新状态: {Status}",
taskEvent.Task.Guid, taskEvent.Task.Status);
// 同步到工单系统
await _syncService.SyncTaskStatusToTicketAsync(taskEvent.Task.Guid, taskEvent.Task.Status);
// 发送通知
if (taskEvent.Task.Status == "done")
{
await NotifyTaskCompletedAsync(taskEvent.Task);
}
}
private async Task HandleAssigneeUpdatedAsync(EventData eventData)
{
var taskEvent = JsonSerializer.Deserialize<AssigneeUpdatedEvent>(eventData.Data.ToString());
_logger.LogInformation("任务负责人更新，任务ID: {TaskGuid}", taskEvent.Task.Guid);
// 同步分配人信息到工单
await _syncService.SyncTaskAssigneeToTicketAsync(taskEvent.Task.Guid, taskEvent.Task.Members);
}
private async Task NotifyTaskCompletedAsync(TaskInfo task)
{
// 发送飞书通知到相关群组
// 这里可以调用飞书消息API发送通知
}
}
</code></pre>
<h3 id="3-业务领域适配">3. 业务领域适配</h3>
<h4 id="对象映射设计工单--飞书任务字段对照表">对象映射设计：工单 ↔ 飞书任务字段对照表</h4>
<div class="mermaid">graph LR
subgraph "工单系统"
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
end
subgraph "映射转换"
H
I[业务规则引擎]
J[数据转换器]
end
subgraph "飞书任务"
K --> L
K --> M
K --> N
K --> O
K --> P
K --> Q
end
B --> H
C --> H
D --> I
E --> I
F --> J
G --> J
H --> L
I --> N
J --> O
J --> P
style H fill:#e1f5fe
style I fill:#e8f5e8
style J fill:#fff3e0
</div><p>使用AutoMapper进行对象映射配置：</p>
<pre><code class="language-csharp">public class FeishuMappingProfile : Profile
{
public FeishuMappingProfile()
{
// 工单 -> 飞书任务创建请求
CreateMap<Ticket, CreateTaskRequest>()
.ForMember(dest => dest.Summary, opt => opt.MapFrom(src => $"[工单#{src.Id}] {src.Title}"))
.ForMember(dest => dest.Description, opt => opt.MapFrom(src => BuildTaskDescription(src)))
.ForMember(dest => dest.Start, opt => opt.MapFrom(src => src.CreatedDate.HasValue
? new TasksStartTime { Timestamp = ((DateTimeOffset)src.CreatedDate.Value).ToUnixTimeMilliseconds().ToString() }
: null))
.ForMember(dest => dest.Mode, opt => opt.MapFrom(src => src.AssigneeCount > 1 ? 2 : 1)) // 或签/会签
.ForMember(dest => dest.IsMilestone, opt => opt.MapFrom(src => src.Priority == TicketPriority.High));
// 飞书任务 -> 工单状态更新
CreateMap<TaskInfo, TicketStatusUpdate>()
.ForMember(dest => dest.TicketId, opt => opt.MapFrom(src => ExtractTicketId(src.Extra)))
.ForMember(dest => dest.Status, opt => opt.MapFrom(src => MapTaskStatusToTicketStatus(src.Status)))
.ForMember(dest => dest.CompletedAt, opt => opt.MapFrom(src => ParseCompletedAt(src.CompletedAt)));
}
private string BuildTaskDescription(Ticket ticket)
{
var description = new StringBuilder();
description.AppendLine($"**客户：** {ticket.CustomerName}");
description.AppendLine($"**项目：** {ticket.ProjectName}");
description.AppendLine($"**优先级：** {ticket.Priority}");
description.AppendLine();
description.AppendLine("**问题描述：**");
description.AppendLine(ticket.Description);
if (!string.IsNullOrEmpty(ticket.Attachments))
{
description.AppendLine();
description.AppendLine("**附件：**");
description.AppendLine(ticket.Attachments);
}
return description.ToString();
}
private TicketStatus MapTaskStatusToTicketStatus(string? taskStatus)
{
return taskStatus switch
{
"todo" => TicketStatus.InProgress,
"done" => TicketStatus.Resolved,
_ => TicketStatus.Open
};
}
}
</code></pre>
<h4 id="同步策略实现">同步策略实现</h4>
<pre><code class="language-csharp">public class TicketSyncService : ITicketSyncService
{
private readonly IFeishuTaskService _feishuTaskService;
private readonly ITicketRepository _ticketRepository;
private readonly INotificationService _notificationService;
private readonly ILogger<TicketSyncService> _logger;
// 实时事件监听（工单创建/更新）
public async Task HandleTicketCreatedAsync(Ticket ticket)
{
try
{
// 只为高优先级工单创建飞书任务
if (ticket.Priority >= TicketPriority.Medium)
{
var taskGuid = await _feishuTaskService.CreateTaskFromTicketAsync(ticket);
ticket.FeishuTaskId = taskGuid;
await _ticketRepository.UpdateAsync(ticket);
_logger.LogInformation("为新工单创建飞书任务，工单ID: {TicketId}, 任务ID: {TaskGuid}",
ticket.Id, taskGuid);
// 发送通知
await _notificationService.NotifyTaskCreatedAsync(ticket, taskGuid);
}
}
catch (Exception ex)
{
_logger.LogError(ex, "处理工单创建事件时发生异常，工单ID: {TicketId}", ticket.Id);
}
}
// 定时全量同步（防丢失）
public async Task ReconcileTasksAsync()
{
_logger.LogInformation("开始执行任务对账...");
try
{
// 获取所有关联了飞书任务的工单
var ticketsWithTasks = await _ticketRepository.GetTicketsWithFeishuTasksAsync();
foreach (var ticket in ticketsWithTasks)
{
if (string.IsNullOrEmpty(ticket.FeishuTaskId))
continue;
// 检查飞书任务是否存在且状态一致
var task = await _feishuTaskService.GetTaskAsync(ticket.FeishuTaskId);
if (task == null)
{
_logger.LogWarning("飞书任务不存在，工单ID: {TicketId}, 任务ID: {TaskGuid}",
ticket.Id, ticket.FeishuTaskId);
// 重新创建任务
var newTaskGuid = await _feishuTaskService.CreateTaskFromTicketAsync(ticket);
ticket.FeishuTaskId = newTaskGuid;
await _ticketRepository.UpdateAsync(ticket);
}
else if (MapTaskStatusToTicketStatus(task.Status) != ticket.Status)
{
// 状态不一致，同步飞书任务状态到工单
await SyncTaskStatusToTicketAsync(ticket.FeishuTaskId, task.Status);
}
}
_logger.LogInformation("任务对账完成");
}
catch (Exception ex)
{
_logger.LogError(ex, "执行任务对账时发生异常");
}
}
public async Task SyncTaskStatusToTicketAsync(string taskGuid, string taskStatus)
{
try
{
var ticketId = ExtractTicketIdFromTask(taskGuid);
if (string.IsNullOrEmpty(ticketId))
return;
var ticket = await _ticketRepository.GetByIdAsync(ticketId);
if (ticket == null)
return;
var newStatus = MapTaskStatusToTicketStatus(taskStatus);
if (ticket.Status != newStatus)
{
ticket.Status = newStatus;
ticket.StatusUpdatedBy = "FeishuSync";
ticket.StatusUpdatedAt = DateTime.UtcNow;
await _ticketRepository.UpdateAsync(ticket);
_logger.LogInformation("同步飞书任务状态到工单，任务ID: {TaskGuid}, 工单ID: {TicketId}, 新状态: {Status}",
taskGuid, ticketId, newStatus);
}
}
catch (Exception ex)
{
_logger.LogError(ex, "同步飞书任务状态到工单时发生异常，任务ID: {TaskGuid}", taskGuid);
}
}
}
</code></pre>
<h4 id="容错设计异常分类重试策略死信队列">容错设计：异常分类、重试策略、死信队列</h4>
<pre><code class="language-csharp">public class FaultTolerantTaskService : IFeishuTaskService
{
private readonly IFeishuTaskService _innerService;
private readonly IAsyncPolicy _retryPolicy;
private readonly ILogger<FaultTolerantTaskService> _logger;
private readonly IDeadLetterQueue _deadLetterQueue;
public FaultTolerantTaskService(
IFeishuTaskService innerService,
ILogger<FaultTolerantTaskService> logger,
IDeadLetterQueue deadLetterQueue)
{
_innerService = innerService;
_logger = logger;
_deadLetterQueue = deadLetterQueue;
// 配置重试策略
_retryPolicy = Policy
.Handle<FeishuApiException>(ex => ex.IsTransient)
.Or<HttpRequestException>()
.WaitAndRetryAsync(
retryCount: 3,
sleepDurationProvider: retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
onRetry: (outcome, timespan, retryAttempt, context) =>
{
_logger.LogWarning("操作失败，准备第{RetryAttempt}次重试，延迟{Delay}ms",
retryAttempt, timespan.TotalMilliseconds);
});
}
public async Task<string> CreateTaskFromTicketAsync(Ticket ticket)
{
try
{
return await _retryPolicy.ExecuteAsync(() => _innerService.CreateTaskFromTicketAsync(ticket));
}
catch (Exception ex)
{
// 非临时性异常或重试次数耗尽，加入死信队列
await _deadLetterQueue.EnqueueAsync(new DeadLetterMessage
{
Operation = "CreateTask",
Data = ticket,
Exception = ex,
Timestamp = DateTime.UtcNow
});
_logger.LogError(ex, "创建飞书任务失败并加入死信队列，工单ID: {TicketId}", ticket.Id);
throw;
}
}
}
</code></pre>
<h3 id="4-关键代码片段">4. 关键代码片段</h3>
<h4 id="oauth-20授权流程实现含刷新逻辑">OAuth 2.0授权流程实现（含刷新逻辑）</h4>
<p>Mud.Feishu已经内置了完整的OAuth流程，我们只需要配置：</p>
<pre><code class="language-csharp">// appsettings.json中的配置
{
"Feishu": {
"AppId": "cli_xxxxxxxxxxxxxxxx",
"AppSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
// 服务注册
builder.Services.AddFeishuApiService(builder.Configuration);
</code></pre>
<h4 id="创建任务并关联工单的完整示例">创建任务并关联工单的完整示例</h4>
<pre><code class="language-csharp">
")]
public class TicketController : ControllerBase
{
private readonly ITicketService _ticketService;
private readonly IFeishuTaskService _feishuTaskService;
private readonly ITicketSyncService _syncService;
public async Task<IActionResult> CreateTicket( CreateTicketRequest request)
{
try
{
// 1. 创建工单
var ticket = await _ticketService.CreateTicketAsync(request);
// 2. 如果是高优先级工单，自动创建飞书任务
if (ticket.Priority >= TicketPriority.Medium)
{
var taskGuid = await _feishuTaskService.CreateTaskFromTicketAsync(ticket);
ticket.FeishuTaskId = taskGuid;
await _ticketService.UpdateTicketAsync(ticket);
}
return Ok(new { TicketId = ticket.Id, FeishuTaskId = ticket.FeishuTaskId });
}
catch (Exception ex)
{
_logger.LogError(ex, "创建工单时发生异常");
return StatusCode(500, new { Error = "创建工单失败" });
}
}
public async Task<IActionResult> UpdateTicketStatus(string id, UpdateStatusRequest request)
{
try
{
var ticket = await _ticketService.GetTicketAsync(id);
if (ticket == null)
return NotFound();
// 更新工单状态
ticket.Status = request.Status;
await _ticketService.UpdateTicketAsync(ticket);
// 同步到飞书任务
if (!string.IsNullOrEmpty(ticket.FeishuTaskId))
{
var updateRequest = new UpdateTaskRequest
{
Status = MapTicketStatusToTaskStatus(request.Status),
CompletedAt = request.Status == TicketStatus.Resolved ?
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString() : null
};
await _feishuTaskService.UpdateTaskAsync(ticket.FeishuTaskId, updateRequest);
}
return Ok();
}
catch (Exception ex)
{
_logger.LogError(ex, "更新工单状态时发生异常，工单ID: {TicketId}", id);
return StatusCode(500, new { Error = "更新状态失败" });
}
}
}
</code></pre>
<h4 id="websocket处理器与业务逻辑解耦设计">WebSocket处理器与业务逻辑解耦设计</h4>
<pre><code class="language-csharp">public class FeishuWebSocketBackgroundService : BackgroundService
{
private readonly IFeishuWebSocketManager _webSocketManager;
private readonly IEnumerable<IFeishuWebSocketEventHandler> _handlers;
private readonly ILogger<FeishuWebSocketBackgroundService> _logger;
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
// 启动WebSocket连接
await _webSocketManager.StartAsync(stoppingToken);
// 订阅事件
_webSocketManager.MessageReceived += async (sender, e) =>
{
await HandleMessageAsync(e.Message);
};
_webSocketManager.Error += async (sender, e) =>
{
_logger.LogError(e.Exception, "WebSocket连接发生错误");
await HandleErrorAsync(e.Exception);
};
_webSocketManager.Disconnected += async (sender, e) =>
{
_logger.LogWarning("WebSocket连接断开，原因: {Reason}", e.CloseStatusDescription);
await HandleDisconnectionAsync();
};
// 保持服务运行
while (!stoppingToken.IsCancellationRequested)
{
await Task.Delay(1000, stoppingToken);
}
}
private async Task HandleMessageAsync(FeishuWebSocketMessage message)
{
var tasks = _handlers.Select(handler =>
SafeHandleAsync(handler, message));
await Task.WhenAll(tasks);
}
private async Task SafeHandleAsync(IFeishuWebSocketEventHandler handler, FeishuWebSocketMessage message)
{
try
{
await handler.HandleAsync(message);
}
catch (Exception ex)
{
_logger.LogError(ex, "事件处理器处理消息时发生异常，处理器类型: {HandlerType}",
handler.GetType().Name);
}
}
}
</code></pre>
<h2 id="应用场景落地详解">应用场景落地详解</h2>
<h3 id="-场景一让工单活起来自动飞书任务生成">🔧 场景一：让工单"活"起来——自动飞书任务生成</h3>
<h4 id="工单到任务的变身过程">工单到任务的"变身"过程</h4>
<div class="mermaid">sequenceDiagram
participant C as 客户/系统
participant T as 工单系统
participant E as 事件总线
participant S as 同步服务
participant F as 飞书API
participant N as 通知服务
Note over C,N: 工单自动生成飞书任务流程
C->>T: 提交工单
T->>T: 验证工单信息
T->>T: 保存工单到数据库
alt 高优先级工单
T->>E: 发布工单创建事件
E->>S: 订阅事件处理
S->>S: 检查是否需要创建任务
S->>F: 调用飞书任务API
F-->>S: 返回任务ID
S->>T: 更新工单关联ID
S->>N: 发送创建通知
end
alt 客户标记紧急
T->>E: 发布紧急标记事件
E->>S: 处理紧急事件
S->>F: 创建或更新任务优先级
S->>N: 发送紧急通知
end
alt SLA预警
T->>E: 发布SLA预警事件
E->>S: 处理SLA预警
S->>F: 创建任务并设置提醒
end
</div><h4 id="什么时候该变身触发时机揭秘">什么时候该"变身"？——触发时机揭秘</h4>
<p>就像超级英雄有自己的"变身"条件，我们的工单也需要在合适的时机才生成飞书任务：</p>
<pre><code class="language-csharp">public class TaskCreationTrigger
{
// 1. 高优先级工单创建时自动触发
public async Task HandleTicketCreatedAsync(TicketCreatedEvent @event)
{
if (@event.Ticket.Priority >= TicketPriority.High)
{
await CreateFeishuTaskAsync(@event.Ticket);
}
}
// 2. 客户标记紧急时触发
public async Task HandleTicketMarkedUrgentAsync(TicketMarkedUrgentEvent @event)
{
// 如果还没有飞书任务，立即创建
if (string.IsNullOrEmpty(@event.Ticket.FeishuTaskId))
{
await CreateFeishuTaskAsync(@event.Ticket);
}
else
{
// 更新现有任务优先级
await UpdateTaskPriorityAsync(@event.Ticket.FeishuTaskId, TicketPriority.High);
}
}
// 3. SLA即将超时预警时触发
public async Task HandleSLAWarningAsync(SLAWarningEvent @event)
{
if (@event.Ticket.Priority >= TicketPriority.Medium)
{
await CreateFeishuTaskAsync(@event.Ticket);
}
}
}
</code></pre>
<h4 id="实现步骤">实现步骤</h4>
<p><strong>第一步：监听工单领域事件</strong></p>
<pre><code class="language-csharp">
public class TicketsController : ControllerBase
{
private readonly ITicketService _ticketService;
private readonly IEventBus _eventBus;
private readonly ILogger<TicketsController> _logger;
public async Task<IActionResult> CreateTicket( CreateTicketRequest request)
{
var ticket = await _ticketService.CreateTicketAsync(request);
// 发布领域事件
await _eventBus.PublishAsync(new TicketCreatedEvent { Ticket = ticket });
return CreatedAtAction(nameof(GetTicket), new { id = ticket.Id }, ticket);
}
public async Task<IActionResult> MarkAsUrgent(string id)
{
var ticket = await _ticketService.MarkAsUrgentAsync(id);
// 发布紧急标记事件
await _eventBus.PublishAsync(new TicketMarkedUrgentEvent { Ticket = ticket });
return Ok(ticket);
}
}
</code></pre>
<p><strong>第二步：构建飞书任务</strong></p>
<pre><code class="language-csharp">public class FeishuTaskBuilder
{
private readonly IUserService _userService;
private readonly IProjectService _projectService;
public async Task<CreateTaskRequest> BuildTaskAsync(Ticket ticket)
{
var task = new CreateTaskRequest
{
Summary = $"[工单#{ticket.Id}] {ticket.Title}",
Description = await BuildDescriptionAsync(ticket),
Extra = JsonSerializer.Serialize(new { TicketId = ticket.Id }),
ClientToken = Guid.NewGuid().ToString() // 幂等Token
};
// 设置截止时间
if (ticket.SlaDeadline.HasValue)
{
task.Due = new TaskTime
{
Timestamp = ((DateTimeOffset)ticket.SlaDeadline.Value).ToUnixTimeMilliseconds().ToString()
};
}
// 设置开始时间
task.Start = new TasksStartTime
{
Timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString()
};
// 设置任务模式
task.Mode = ticket.Assignees?.Count > 1 ? 2 : 1; // 多人时用或签
// 设置里程碑标识
task.IsMilestone = ticket.Priority == TicketPriority.High;
// 设置提醒规则
task.Reminders = BuildReminders(ticket);
// 设置任务成员
task.Members = await BuildTaskMembersAsync(ticket);
// 设置所属清单
task.Tasklists = new[]
{
new TaskInTaskListInfo
{
TasklistGuid = await GetTaskListGuidAsync(ticket),
CustomFields = await BuildCustomFieldsAsync(ticket)
}
};
return task;
}
private async Task<string> BuildDescriptionAsync(Ticket ticket)
{
var description = new StringBuilder();
// 基本信息
description.AppendLine($"**客户：** {ticket.CustomerName}");
description.AppendLine($"**联系电话：** {ticket.CustomerPhone}");
description.AppendLine($"**项目：** {ticket.ProjectName}");
description.AppendLine($"**优先级：** {GetPriorityDisplay(ticket.Priority)}");
description.AppendLine($"**创建时间：** {ticket.CreatedAt:yyyy-MM-dd HH:mm:ss}");
if (ticket.SlaDeadline.HasValue)
{
description.AppendLine($"**SLA截止时间：** {ticket.SlaDeadline:yyyy-MM-dd HH:mm:ss}");
}
description.AppendLine();
// 问题描述
description.AppendLine("## 问题描述");
description.AppendLine(ticket.Description);
// 附件信息
if (!string.IsNullOrEmpty(ticket.Attachments))
{
description.AppendLine();
description.AppendLine("## 相关附件");
description.AppendLine(ticket.Attachments);
}
// 处理历史
if (ticket.History?.Any() == true)
{
description.AppendLine();
description.AppendLine("## 处理历史");
foreach (var history in ticket.History.Take(3))
{
description.AppendLine($"- {history.CreatedAt:MM-dd HH:mm} {history.Operator}：{history.Action}");
}
}
return description.ToString();
}
private TaskReminder[] BuildReminders(Ticket ticket)
{
var reminders = new List<TaskReminder>();
// 高优先级任务设置多个提醒
if (ticket.Priority == TicketPriority.High)
{
reminders.Add(new TaskReminder
{
MinutesBefore = 120, // 2小时前提醒
ReminderType = ReminderType.Push
});
reminders.Add(new TaskReminder
{
MinutesBefore = 60, // 1小时前提醒
ReminderType = ReminderType.Push
});
}
else if (ticket.Priority == TicketPriority.Medium)
{
reminders.Add(new TaskReminder
{
MinutesBefore = 240, // 4小时前提醒
ReminderType = ReminderType.Push
});
}
return reminders.ToArray();
}
private async Task<TaskMemberInfo[]> BuildTaskMembersAsync(Ticket ticket)
{
var members = new List<TaskMemberInfo>();
// 添加负责人
if (!string.IsNullOrEmpty(ticket.AssigneeId))
{
var assignee = await _userService.GetByIdAsync(ticket.AssigneeId);
if (assignee?.FeishuUserId != null)
{
members.Add(new TaskMemberInfo
{
UserId = assignee.FeishuUserId,
UserType = UserType.User,
TaskRole = TaskRole.Assignee
});
}
}
// 添加关注人
if (ticket.Watchers?.Any() == true)
{
foreach (var watcherId in ticket.Watchers)
{
var watcher = await _userService.GetByIdAsync(watcherId);
if (watcher?.FeishuUserId != null)
{
members.Add(new TaskMemberInfo
{
UserId = watcher.FeishuUserId,
UserType = UserType.User,
TaskRole = TaskRole.Follower
});
}
}
}
// 添加项目经理作为关注人
var project = await _projectService.GetByIdAsync(ticket.ProjectId);
if (project?.ManagerFeishuUserId != null)
{
members.Add(new TaskMemberInfo
{
UserId = project.ManagerFeishuUserId,
UserType = UserType.User,
TaskRole = TaskRole.Follower
});
}
return members.ToArray();
}
}
</code></pre>
<p><strong>第三步：调用API并保存关联ID</strong></p>
<pre><code class="language-csharp">public class TaskCreationService
{
private readonly IFeishuTaskService _feishuTaskService;
private readonly ITicketRepository _ticketRepository;
private readonly ILogger<TaskCreationService> _logger;
public async Task<string> CreateFeishuTaskAsync(Ticket ticket)
{
try
{
// 检查是否已存在任务
if (!string.IsNullOrEmpty(ticket.FeishuTaskId))
{
_logger.LogWarning("工单已存在飞书任务，工单ID: {TicketId}, 任务ID: {TaskGuid}",
ticket.Id, ticket.FeishuTaskId);
return ticket.FeishuTaskId;
}
// 创建飞书任务
var taskRequest = await _taskBuilder.BuildTaskAsync(ticket);
var taskGuid = await _feishuTaskService.CreateTaskAsync(taskRequest);
// 保存关联关系
ticket.FeishuTaskId = taskGuid;
ticket.FeishuTaskCreatedAt = DateTime.UtcNow;
await _ticketRepository.UpdateAsync(ticket);
_logger.LogInformation("成功为工单创建飞书任务，工单ID: {TicketId}, 任务ID: {TaskGuid}",
ticket.Id, taskGuid);
return taskGuid;
}
catch (Exception ex)
{
_logger.LogError(ex, "为工单创建飞书任务失败，工单ID: {TicketId}", ticket.Id);
throw;
}
}
}
</code></pre>
<p><strong>第四步：发送内部通知</strong></p>
<pre><code class="language-csharp">public class NotificationService
{
private readonly IFeishuMessageService _messageService;
private readonly IProjectService _projectService;
public async Task NotifyTaskCreatedAsync(Ticket ticket, string taskGuid)
{
try
{
var project = await _projectService.GetByIdAsync(ticket.ProjectId);
var message = new CardMessageRequest
{
ReceiveIdType = "chat_id",
ReceiveId = project.FeishuGroupId,
Card = new InteractiveCard
{
Header = new CardHeader
{
Title = "🎯 新工单转飞书任务",
Template = "blue"
},
Elements = new List<ICardElement>
{
new CardMarkdown
{
Content = $"**工单编号：** #{ticket.Id}\n" +
$"**客户：** {ticket.CustomerName}\n" +
$"**优先级：** {GetPriorityEmoji(ticket.Priority)} {ticket.Priority}\n" +
$"**负责人：** {ticket.AssigneeName}"
},
new CardButton
{
Text = new CardText
{
Content = "查看任务详情",
Tag = "plain_text"
},
Type = "template",
Url = $"https://.feishu.cn/messenger/collection/task/detail/{taskGuid}"
}
}
}
};
await _messageService.SendCardMessageAsync(message);
}
catch (Exception ex)
{
_logger.LogError(ex, "发送任务创建通知失败，工单ID: {TicketId}", ticket.Id);
}
}
private string GetPriorityEmoji(TicketPriority priority)
{
return priority switch
{
TicketPriority.High => "🔴",
TicketPriority.Medium => "🟡",
TicketPriority.Low => "🟢",
_ => "⚪"
};
}
}
</code></pre>
<h4 id="注意事项">注意事项</h4>
<ol>
<li><strong>避免重复创建</strong>：使用幂等Token和数据库唯一性约束</li>
<li><strong>字段默认值处理</strong>：合理设置任务的默认优先级和截止时间</li>
<li><strong>异常处理</strong>：网络异常时的重试机制和本地缓存</li>
<li><strong>性能优化</strong>：批量处理和异步操作</li>
</ol>
<h3 id="-场景二任务状态双向同步">🔄 场景二：任务状态双向同步</h3>
<h4 id="状态同步流程图">状态同步流程图</h4>
<div class="mermaid">graph TB
subgraph "飞书 → 系统"
A[飞书任务状态变更] --> B
B --> C[事件验证器]
C --> D[状态映射器]
D --> E[业务规则校验]
E --> F[更新工单状态]
F --> G[记录操作日志]
G --> H[发送通知]
end
subgraph "系统 → 飞书"
I[工单状态变更] --> J[状态映射器]
J --> K
K --> L[更新飞书任务]
L --> M[异常重试]
M --> N[成功确认]
end
subgraph "双向映射规则"
O --> P
Q --> R
S --> T
P --> O
R --> Q
T --> S
end
</div><h4 id="飞书--系统通过webhook接收任务更新">飞书 → 系统：通过Webhook接收任务更新</h4>
<p><strong>状态映射配置</strong></p>
<pre><code class="language-csharp">public class TaskStatusMapper
{
private static readonly Dictionary<string, TicketStatus> StatusMapping = new()
{
{ "todo", TicketStatus.InProgress },
{ "done", TicketStatus.Resolved },
{ "archived", TicketStatus.Closed }
};
public TicketStatus MapTaskStatusToTicketStatus(string taskStatus)
{
return StatusMapping.TryGetValue(taskStatus, out var ticketStatus)
? ticketStatus
: TicketStatus.Open;
}
public string MapTicketStatusToTaskStatus(TicketStatus ticketStatus)
{
return ticketStatus switch
{
TicketStatus.Open => "todo",
TicketStatus.InProgress => "todo",
TicketStatus.Resolved => "done",
TicketStatus.Closed => "archived",
_ => "todo"
};
}
}
</code></pre>
<p><strong>Webhook事件处理器</strong></p>
<pre><code class="language-csharp">public class TaskWebhookHandler : IFeishuEventHandler
{
private readonly ITicketSyncService _syncService;
private readonly IOperationLogService _logService;
private readonly ILogger<TaskWebhookHandler> _logger;
public string SupportedEventType => "task.status_changed";
public async Task HandleAsync(EventData eventData, CancellationToken cancellationToken = default)
{
try
{
switch (eventData.EventType)
{
case "task.status_changed":
await HandleStatusChangedAsync(eventData);
break;
case "task.assignee_updated":
await HandleAssigneeUpdatedAsync(eventData);
break;
case "task.deleted":
await HandleTaskDeletedAsync(eventData);
break;
default:
_logger.LogDebug("未处理的任务事件类型: {EventType}", eventData.EventType);
break;
}
}
catch (Exception ex)
{
_logger.LogError(ex, "处理飞书任务Webhook事件失败");
throw;
}
}
private async Task HandleStatusChangedAsync(EventData eventData)
{
var taskEvent = JsonSerializer.Deserialize<TaskStatusChangedEvent>(eventData.Event.ToString());
// 校验业务规则
if (!await ValidateStatusTransitionAsync(taskEvent))
{
_logger.LogWarning("任务状态转换不符合业务规则，任务ID: {TaskGuid}", taskEvent.Task.Guid);
return;
}
// 更新工单状态
await _syncService.SyncTaskStatusToTicketAsync(taskEvent.Task.Guid, taskEvent.Task.Status);
// 记录操作日志
await _logService.LogAsync(new OperationLog
{
TicketId = ExtractTicketId(taskEvent.Task.Extra),
Action = "StatusChanged",
OldValue = taskEvent.OldStatus,
NewValue = taskEvent.Task.Status,
Operator = "FeishuSync",
Timestamp = DateTime.UtcNow,
Source = "FeishuTask"
});
}
private async Task<bool> ValidateStatusTransitionAsync(TaskStatusChangedEvent taskEvent)
{
// 业务规则：不允许从"完成"状态回退到其他状态
if (taskEvent.OldStatus == "done" && taskEvent.Task.Status != "done")
{
// 检查是否有特殊权限
var hasSpecialPermission = await HasSpecialPermissionAsync(taskEvent.Operator.UserId);
return hasSpecialPermission;
}
// 业务规则：只有负责人可以修改任务状态
var isAssignee = taskEvent.Task.Members?.Any(m =>
m.UserId == taskEvent.Operator.UserId && m.TaskRole == TaskRole.Assignee) ?? false;
return isAssignee;
}
}
</code></pre>
<p><strong>系统 → 飞书：工单解决后自动关闭任务</strong></p>
<pre><code class="language-csharp">public class TicketStatusHandler
{
private readonly IFeishuTaskService _feishuTaskService;
private readonly IEventBus _eventBus;
public async Task HandleTicketStatusChangedAsync(TicketStatusChangedEvent @event)
{
try
{
if (!string.IsNullOrEmpty(@event.Ticket.FeishuTaskId))
{
var updateRequest = new UpdateTaskRequest
{
Status = _statusMapper.MapTicketStatusToTaskStatus(@event.NewStatus),
CompletedAt = @event.NewStatus == TicketStatus.Resolved
? DateTimeOffset.UtcNow.ToUnixTimeMilliseconds().ToString()
: null
};
var success = await _feishuTaskService.UpdateTaskAsync(@event.Ticket.FeishuTaskId, updateRequest);
if (success)
{
_logger.LogInformation("成功同步工单状态到飞书任务，工单ID: {TicketId}, 任务ID: {TaskGuid}",
@event.Ticket.Id, @event.Ticket.FeishuTaskId);
}
}
}
catch (Exception ex)
{
_logger.LogError(ex, "同步工单状态到飞书任务失败，工单ID: {TicketId}", @event.Ticket.Id);
// 发送到重试队列
await _retryQueue.EnqueueAsync(new RetryMessage
{
Data = @event,
Timestamp = DateTime.UtcNow,
RetryCount = 0
});
}
}
}
</code></pre>
<h3 id="-场景三智能跨部门任务分配">👥 场景三：智能跨部门任务分配</h3>
<h4 id="智能分配规则引擎">智能分配规则引擎</h4>
<div class="mermaid">graph TD
A[工单输入] --> B[规则引擎]
B --> C[工单类型规则]
B --> D
B --> E[工作负载规则]
B --> F[可用性规则]
C --> C1{技术问题?}
C1 -->|是| C2[技术支持团队]
C1 -->|否| C3{功能需求?}
C3 -->|是| C4[产品团队]
C1 -->|否| C5{Bug报告?}
C5 -->|是| C6[开发团队]
C3 -->|否| C7[客户服务团队]
D --> D1
D1 --> D2[优先级调整]
E --> E1[当前工作量评估]
E1 --> E2[负载均衡分配]
F --> F1[在线状态检查]
F1 --> F2[技能匹配]
C2 --> G[候选人池]
C4 --> G
C6 --> G
C7 --> G
D2 --> G
E2 --> G
F2 --> G
G --> H[最终分配决策]
H --> I[任务分配执行]
</div><h4 id="规则引擎设计">规则引擎设计</h4>
<pre><code class="language-csharp">public class TaskAssignmentRuleEngine
{
private readonly IUserService _userService;
private readonly IProjectService _projectService;
private readonly ISLAService _slaService;
public async Task<AssignmentResult> AssignTaskAsync(Ticket ticket)
{
var rules = new List<IAssignmentRule>
{
new TicketTypeAssignmentRule(_userService),
new SLAAssignmentRule(_slaService),
new WorkloadAssignmentRule(_userService),
new AvailabilityAssignmentRule(_userService)
};
foreach (var rule in rules)
{
var result = await rule.EvaluateAsync(ticket);
if (result.IsMatch)
{
return result;
}
}
// 默认分配规则
return await GetDefaultAssignmentAsync(ticket);
}
}
public class TicketTypeAssignmentRule : IAssignmentRule
{
public async Task<AssignmentResult> EvaluateAsync(Ticket ticket)
{
return ticket.Type switch
{
TicketType.TechnicalIssue => await AssignToTechnicalSupportAsync(ticket),
TicketType.FeatureRequest => await AssignToProductAsync(ticket),
TicketType.BugReport => await AssignToDevelopmentAsync(ticket),
TicketType.CustomerComplaint => await AssignToCustomerServiceAsync(ticket),
_ => AssignmentResult.NoMatch()
};
}
private async Task<AssignmentResult> AssignToTechnicalSupportAsync(Ticket ticket)
{
var techSupportTeam = await _userService.GetUsersByRoleAsync("TechnicalSupport");
var availableMember = techSupportTeam
.Where(u => u.IsAvailable && u.CurrentWorkload < u.MaxWorkload)
.OrderBy(u => u.CurrentWorkload)
.FirstOrDefault();
return availableMember != null
? AssignmentResult.Success(availableMember.Id, "按工单类型分配到技术支持")
: AssignmentResult.NoMatch();
}
}
</code></pre>
<p><strong>SLA截止时间与提醒规则</strong></p>
<pre><code class="language-csharp">public class SLAService
{
public async Task<DateTime?> CalculateSLADeadlineAsync(Ticket ticket)
{
var slaConfig = await GetSLAConfigAsync(ticket.Priority, ticket.Type);
var businessHours = await GetBusinessHoursAsync(ticket.CustomerId);
var deadline = CalculateBusinessDeadline(DateTime.UtcNow, slaConfig.ResponseHours, businessHours);
return deadline;
}
public async Task SetupSLARemindersAsync(string ticketId, DateTime deadline)
{
var reminders = new List<SLAReminder>
{
new SLAReminder
{
TicketId = ticketId,
TriggerTime = deadline.AddHours(-2), // 提前2小时
Type = ReminderType.Warning,
Message = "工单即将超过SLA时间，请尽快处理"
},
new SLAReminder
{
TicketId = ticketId,
TriggerTime = deadline.AddMinutes(-30), // 提前30分钟
Type = ReminderType.Urgent,
Message = "工单SLA即将超时，紧急处理"
}
};
await SaveRemindersAsync(reminders);
}
}
</code></pre>
<p><strong>子任务依赖支持</strong></p>
<pre><code class="language-csharp">public class SubTaskManager
{
public async Task<string> CreateSubTaskAsync(string parentTaskGuid, SubTaskRequest request)
{
var subTaskRequest = new CreateSubTaskRequest
{
Summary = request.Title,
Description = request.Description,
Due = request.DueDate.HasValue
? new TaskTime { Timestamp = ((DateTimeOffset)request.DueDate.Value).ToUnixTimeMilliseconds().ToString() }
: null,
Members = request.AssigneeId != null
? new[] { new TaskMemberInfo { UserId = request.AssigneeId, TaskRole = TaskRole.Assignee } }
: null
};
var result = await _taskApi.CreateSubTaskAsync(parentTaskGuid, subTaskRequest);
return result?.Data?.SubTask?.Guid;
}
public async Task SetupTaskDependenciesAsync(string taskGuid, List<TaskDependency> dependencies)
{
foreach (var dependency in dependencies)
{
var addRequest = new AddTaskDependenciesRequest
{
Dependencies = new[]
{
new TaskDependencyInfo
{
TaskGuid = dependency.DependentTaskGuid,
DependencyType = dependency.Type
}
}
};
await _taskApi.AddTaskDependenciesByIdAsync(taskGuid, addRequest);
}
}
}
</code></pre>
<h2 id="项目仓库">项目仓库</h2>
<p><strong>Mud.Feishu Gitee源码仓库</strong>：Gitee<br>
<strong>Mud.Feishu Github源码仓库</strong>：Github</p><br><br>
来源：https://www.cnblogs.com/mudtools/p/19415554
頁:
[1]