Tai.WeCom.EntityFrameworkCore 2.0.0

Tai.WeCom

自动发布使用模块版本标签和 NuGet Trusted Publishing，配置与操作见发布指南。

ABP 可复用模块，为企业微信（WeCom）提供外部联系人、客户群的数据同步与管理功能。

WeCom 是 tenant-only 模块：所有业务数据和凭据都必须属于具体租户，不支持 Host 侧使用。

特性

• 外部联系人同步 — 通过企业微信 API 全量拉取外部联系人（客户）数据，支持分页批量获取
• 客户群同步 — 全量同步客户群（外部群）信息及群成员，支持游标分页
• 回调事件处理 — 接收企业微信回调事件（URL 验证 + 事件接收），AES 解密与签名校验
• 增量更新 — 通过 change_external_contact / change_external_chat 回调事件实现联系人、客户群的增量同步
• 变更日志审计 — 记录外部联系人与客户群的每一次变更（新增、编辑、删除、解散等），支持回溯
• 同步任务管理 — 可触发、查询全量同步任务，跟踪进度（Pending → Running → Completed/Failed）
• Access Token 管理 — 自动获取、缓存和提前刷新企业微信 Access Token
• 失败回调重试 — 支持手动触发失败回调事件的重新处理

项目结构

src/
├── Tai.WeCom.Domain.Shared                     # 常量、枚举、错误码、本地化
├── Tai.WeCom.Domain                            # 实体、领域服务、API 客户端、Token 服务、加解密、Setting 定义
├── Tai.WeCom.Application.Contracts             # 应用服务接口与 DTO
├── Tai.WeCom.Application                       # 应用服务实现、后台同步任务
├── Tai.WeCom.EntityFrameworkCore              # EF Core DbContext、实体映射、仓储实现
├── Tai.WeCom.HttpApi                           # API 控制器
├── Tai.WeCom.HttpApi.Client                    # C# HTTP 客户端代理
└── Tai.WeCom.Installer                         # 便捷安装模块（聚合所有依赖）
test/
├── Tai.WeCom.TestBase
├── Tai.WeCom.Domain.Tests
├── Tai.WeCom.Application.Tests
└── Tai.WeCom.EntityFrameworkCore.Tests

快速开始

1. 安装模块

将以下项目引用添加到宿主应用的对应层：

dotnet add package Tai.WeCom.Application
dotnet add package Tai.WeCom.HttpApi
# 仅需要客户端代理时
dotnet add package Tai.WeCom.HttpApi.Client

在宿主模块中添加 DependsOn：

[DependsOn(typeof(TaiWeComApplicationModule))]
[DependsOn(typeof(TaiWeComHttpApiModule))]
public class YourHostModule : AbpModule { }

也可使用 TaiWeComInstallerModule（已聚合上述所有模块依赖）：

[DependsOn(typeof(TaiWeComInstallerModule))]
public class YourHostModule : AbpModule { }

2. 配置 Settings

在目标租户上下文中，通过 ABP Setting Management 配置以下项。模块只读取 Tenant Setting 和代码内默认值，不会回退到 Host、Global 或 appsettings.json 中的 WeCom 凭据。

3. 配置企业微信回调 URL

在企业微信管理后台，将回调 URL 配置为：

https://your-domain/api/wecom/callback

回调 URL 必须携带 ABP 租户解析参数，例如：

https://your-domain/api/wecom/callback?__tenant=your-tenant

模块自动处理 URL 验证（GET）和事件接收（POST），通过 Token + AES 签名保证安全。缺少有效 租户上下文时，回调会被拒绝。

4. 从非多租户版本升级

2.0.0 是破坏性升级。生成并执行宿主 EF Core migration 前必须：

1. 排空或显式清理旧版已入队的 WeCom 后台任务；旧 payload 没有 TenantId，升级后不会按 Host 任务继续执行。
2. 为旧 WeCom 表中 TenantId IS NULL 的记录选择明确策略：回填到指定租户、删除，或中止 迁移等待人工处理。禁止静默回填为 Guid.Empty。
3. 删除旧 TenantKey 列（若曾部署过包含该列的预览版本），将所有 WeCom 表的 TenantId 改为 NOT NULL，并重新创建以 TenantId 开头的业务唯一索引。
4. 更新所有直接构造 WeCom 领域实体的宿主代码，为公开构造函数传入非空 tenantId。

API 参考

回调接口（匿名访问）

# URL 验证（企业微信回调配置时调用）
GET /api/wecom/callback?__tenant=your-tenant&msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx

# 事件接收（外部联系人/客户群变更回调）
POST /api/wecom/callback?__tenant=your-tenant&msg_signature=xxx&timestamp=xxx&nonce=xxx

同步管理

# 触发全量同步外部联系人
POST /api/wecom/sync/contacts

# 触发全量同步客户群
POST /api/wecom/sync/group-chats

# 查询同步任务详情
GET /api/wecom/sync/tasks/{id}

# 查询同步任务列表
GET /api/wecom/sync/tasks

# 重试失败的回调事件
POST /api/wecom/sync/retry-failed-callbacks

外部联系人

# 分页查询外部联系人列表
GET /api/wecom/external-contacts

# 根据 ID 获取外部联系人详情
GET /api/wecom/external-contacts/{id}

# 根据 ExternalUserId 获取外部联系人详情
GET /api/wecom/external-contacts/by-external-user-id/{externalUserId}

# 获取外部联系人的跟进成员列表
GET /api/wecom/external-contacts/{id}/follow-users

# 分页查询外部联系人变更日志
GET /api/wecom/external-contacts/change-logs

客户群

# 分页查询客户群列表
GET /api/wecom/external-group-chats

# 根据 ID 获取客户群详情
GET /api/wecom/external-group-chats/{id}

# 根据 ChatId 获取客户群详情
GET /api/wecom/external-group-chats/by-chat-id/{chatId}

# 获取客户群成员列表
GET /api/wecom/external-group-chats/{id}/members

# 分页查询客户群变更日志
GET /api/wecom/external-group-chats/change-logs

数据模型

同步任务生命周期

Pending → Running → Completed
                 → Failed

全量同步通过 ABP 后台作业执行，适合大量数据的分页分批处理。每个同步任务记录已处理数、错误数和总数，便于追踪进度。

回调事件处理

收到事件 → Pending → Processing → Completed
                                → Failed

回调事件首先落库（5 秒内返回 success），然后通过后台作业异步处理。处理失败的记录可手动重试。

变更日志

每次外部联系人或客户群数据变更（无论是通过 API 回调还是全量同步）都会写入变更日志，记录变更前后的数据快照、变更摘要、变更来源（Callback / FullSync）。

回调事件类型

技术栈

• .NET 10 / ABP 10.6.1
• 企业微信服务端 API（外部联系人、客户群、回调）
• EF Core（数据持久化与仓储）
• ABP Distributed Cache（Access Token 缓存）
• ABP Background Jobs（长耗时全量同步异步执行）
• AES 加解密（回调消息安全）

消费宿主需使用 .NET 10 SDK，并将 ABP 包统一升级到 10.6.1。现有 AutoMapper 映射方式保持不变；Volo.Abp.AutoMapper 10.6.1 仍依赖 AutoMapper 14.0.0，NuGet 会报告 GHSA-rvv3-g6hj-g44x。升级 ABP 本身不会消除该警告，未将其屏蔽。

Nuget

dotnet pack Tai.WeCom.slnx --configuration Release --output nupkgs

dotnet nuget push "nupkgs/*.nupkg" --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json --skip-duplicate

License

MIT