Tai.WeCom.EntityFrameworkCore 2.1.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

客户联系 / 消息推送

所有接口要求有效租户上下文与 WeCom.MassMessages 权限。创建、提醒、停止和同步另需 对应的 .Create、.Remind、.Stop、.Sync 子权限，Host 侧不能调用。

POST /api/wecom/mass-messages                       # 创建企业群发
POST /api/wecom/mass-messages/{id}/remind           # 提醒成员群发
POST /api/wecom/mass-messages/{id}/stop             # 停止企业群发
GET  /api/wecom/mass-messages                      # 分页查询数据库记录
GET  /api/wecom/mass-messages/{id}                 # 查询数据库记录详情
GET  /api/wecom/mass-messages/{id}/tasks           # 分页查询成员发送任务
GET  /api/wecom/mass-messages/{id}/results         # 分页查询接收者发送详情
POST /api/wecom/mass-messages/sync                # 立即同步并启用定时同步
POST /api/wecom/mass-messages/sync-range          # 补录指定历史区间并启用定时同步

id 是模块返回的本地 GUID，messageId 是企业微信的 msgid。列表查询支持 messageId、chatType、creator、startTime、endTime、skipCount 和 maxResultCount。 列表时间筛选使用 Unix 秒；发送详情支持 userId、status 和分页参数。所有 GET 接口直接 查询数据库，不访问企业微信，因此同步完成后的历史记录可长期查询。

创建请求沿用企业微信的字段名称，例如发送给客户：

{
  "chat_type": "single",
  "sender": "member-userid",
  "external_userid": ["customer-external-userid"],
  "text": { "content": "客户通知内容" },
  "attachments": [
    { "msgtype": "image", "image": { "media_id": "uploaded-image-media-id" } }
  ]
}

发送给客户群时设 chat_type=group，必须提供 sender，可通过 chat_id_list 指定客户群。 支持 tag_filter.group_list[].tag_list 筛选客户；标签组内为或关系，组间为且关系。 文字最多 4000 个 UTF-8 字节，附件最多 9 个，支持 image、link、miniprogram、video、file。 附件内容使用对应的企业微信原始 JSON 字段；图片可先通过下述上传 API 获取 media_id。创建结果中的 failListJson 保存无法发送的客户或群 ID，requestJson 保存原始创建请求，contentJson 保存最新消息快照。

创建接口只创建任务并通知成员，成员确认后才发送给客户或客户群。提醒频率限制由 企业微信校验（24 小时内每个群发最多三次）；停止只阻止继续发送，不撤回已发送的消息。 企业微信返回失败时，不更新本地提醒时间或停止时间。外部调用与数据库提交不能组成 原子事务：如果企业微信已经成功但本地提交失败，应先用同步接口对账；不要自动重试创建 而生成重复的外部任务。

定时同步与执行状态

创建群发或首次调用同步接口，会为当前租户保存同步检查点。默认 ABP Background Worker 每 5 分钟处理一次已注册租户，服务重启后仍能继续。首次回溯最近 30 天，此后从上次成功 时间前 1 小时开始重叠同步；长区间切成最多 7 天的请求，客户群与客户群发均查询，导入 企业创建和成员个人创建的记录。三层接口的游标分页都会完整读取。

未完成的本地任务会持续刷新执行结果，即使它们已超出列表查询区间；停止后还会刷新一次 最终结果。按租户、msgid 去重记录，按记录、成员、接收者去重发送详情。任务状态为 0 未发送、2 已发送；接收者状态为 0 未发送、1 已发送、2 客户不是好友、3 客户已收到其他 群发。客户群未选择目标时，官方不会返回未发送的接收者记录。resultsComplete 仅在至少 存在一项成员任务、全部成员已发送且已知接收者都处于终态时成立。

一次同步失败不会推进成功检查点，后续周期重新同步；每个租户有独立作用域、工作单元和 同步锁，一个租户失败不阻断其他租户。定时同步使用非事务工作单元，已保存的部分记录 可以保留，后续通过幂等更新补齐。同步时间由 ABP IClock 提供。

历史补录请求的时间建议使用带时区的 ISO 8601；开始时间不能早于 Unix epoch，结束时间 不能在未来。补录不推进自动同步检查点，例如：

{
  "startTime": "2026-01-01T00:00:00Z",
  "endTime": "2026-02-01T00:00:00Z"
}

宿主可配置周期，或在只承担 HTTP 请求的进程中关闭 Worker：

Configure<WeComMassMessageSyncOptions>(options =>
{
    options.IsEnabled = true;
    options.PeriodMilliseconds = 300000;
});

默认调度从共享 WeCom 数据库中读取已注册的租户 ID，仅在此步骤临时关闭租户过滤器； 群发数据与凭据访问始终在恢复后的租户作用域内进行。独立数据库租户需要宿主在对应的 租户作用域中调度 WeComMassMessageManager.SyncAsync()。同步锁依赖 ABP Distributed Locking 抽象，默认使用进程内实现；多实例宿主应配置共享锁 Provider（如 Redis）并加载 AbpDistributedLockingModule。企业微信应用必须具有客户联系消息推送权限及相应成员 可见范围，模块使用现有租户凭据和 Token 服务。

数据库接入与升级

新增四张表：WeComMassMessages、WeComMassMessageTasks、WeComMassMessageResults、 WeComMassMessageSyncStates（实际前缀由 WeComDbProperties 决定）。所有表的 TenantId 非空，业务唯一索引以租户开头，子表通过群发记录关联并级联删除。

直接使用 WeComDbContext 的宿主会获得新模型；实现 IWeComDbContext 并使用 ReplaceDbContext 的宿主需补充以下 DbSet，继续调用 builder.ConfigureWeCom()：

public DbSet<WeComMassMessage> MassMessages { get; set; } = null!;
public DbSet<WeComMassMessageTask> MassMessageTasks { get; set; } = null!;
public DbSet<WeComMassMessageResult> MassMessageResults { get; set; } = null!;
public DbSet<WeComMassMessageSyncState> MassMessageSyncStates { get; set; } = null!;

这些类型位于 Tai.WeCom.MassMessaging。数据库驱动、迁移和 ModelSnapshot 属于实际 消费宿主，本模块不绑定数据库驱动或发布宿主迁移。部署前必须在宿主的迁移项目生成 并应用 migration，确保四张表存在，再启动 Worker，例如：

dotnet ef migrations add AddWeComMassMessaging --project <host-migrations-project> --startup-project <host-project>
dotnet ef database update --project <host-migrations-project> --startup-project <host-project>

官方协议参考：创建企业群发、 提醒成员群发、 停止企业群发、 群发记录、任务和执行结果。

数据模型

同步任务生命周期

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

按客户添加时间查询

GET /api/wecom/external-contacts 新增以下可选查询参数（Unix 秒，区间为左闭右开）：

两组条件同时传入时取交集；在数据库筛选后统计、分页，每个客户只返回一次。时间上界必须大于 下界，单边筛选也受支持。列表和详情均返回 firstAddedTime，列表中的 externalUserId 可以用于 POST /api/wecom/mass-messages 的 external_userid。

GET /api/wecom/external-contacts?firstAddedStartTime=1700000000&firstAddedEndTime=1700086400&skipCount=0&maxResultCount=100

FirstAddedTime 是可空的 Unix 秒字段，保存所有已知成员关系的最早添加时间。全量同步和客户 回调都会更新它，只允许向更早更新；删除关系和重新添加不会使它变晚。成员关系自己的 WeComCreateTime 则按最新快照更新，因此可以查询重新添加的时间。首次时间未知的客户不会 匹配首次添加时间筛选。此前未保存且企业微信不再返回的历史关系无法还原；该字段代表已知最早时间。

首次添加时间升级迁移

本仓库没有 wecom 数据库宿主、数据库驱动或迁移基线，迁移和 ModelSnapshot 必须在实际消费 宿主生成。在宿主的 EF Core 迁移项目执行：

dotnet ef migrations add AddWeComExternalContactFirstAddedTime

确认生成的迁移和 ModelSnapshot 包含：

• ExternalContacts.FirstAddedTime 可空 long 列，不设置默认值。
• ExternalContacts(TenantId, FirstAddedTime) 索引。
• ContactFollowUsers(TenantId, WeComCreateTime, ExternalContactId) 索引。

实际表前缀和 Schema 以宿主配置为准。在部署新版应用和开启同步前应用迁移；租户独立数据库 需要逐库升级。本次不自动回填历史数据，由消费方自行处理。历史客户首次时间初始为 null， 后续同步会逐步记录已知最早时间。首次时间筛选不会返回尚未回填或同步的未知客户。

Down 使用生成的删除索引和列操作；回滚会丢失已积累的首次时间，回滚前应保留数据备份。 模块测试使用 SQLite 验证模型、筛选和同步，不能代替实际宿主的 Schema 迁移验证。

上传群发图片

POST /api/wecom/media/images 接收 multipart/form-data，文件字段名为 file。要求租户上下文， 并具备 WeCom.MassMessages 和 WeCom.MassMessages.UploadImage 权限。

curl -X POST 'https://your-host/api/wecom/media/images' \
  -H 'Authorization: Bearer <access-token>' \
  -H '__tenant: <tenant-id>' \
  -F 'file=@image.png'

响应示例（时间为 Unix 秒）：

{
  "mediaId": "uploaded-image-media-id",
  "createdAt": 1700000000,
  "expiresAt": 1700259200
}

将 mediaId 放入创建群发的图片附件：

{
  "msgtype": "image",
  "image": { "media_id": "uploaded-image-media-id" }
}

按企业微信上传临时素材文档， 图片支持 JPG/JPEG、PNG，大小必须大于 5 字节且不超过 10MB，media_id 有效期为三天。 本接口检查扩展名、文件头和大小，再以 media 字段转发给企业微信；最终图片有效性由企业微信 校验。创建时间来自企业微信响应，过期时间为创建时间加三天，过期后需要重新上传。

上传只转发到企业微信，不保存图片文件或新增数据库记录，因此不需要数据库迁移。宿主或反向 代理的请求体限制需要允许 10MB 图片及 multipart 开销；模块接口限制为 10MB + 64KB。 进程内调用 IWeComMediaAppService.UploadImageAsync(UploadWeComImageDto) 使用文件名及字节数组； 该进程内入口不生成 JSON 远程接口，外部客户端使用上面的显式 multipart API。 自定义 IWeComApiClient 实现需要适配新增 UploadImageAsync 方法。

素材管理的 REST API

素材使用独立权限 WeCom.Media；同步上传还需 WeCom.Media.Upload，创建异步任务还需 WeCom.Media.CreateUploadJob。所有调用都要求租户上下文，使用该租户的企业微信凭据。 已有 /api/wecom/media/images 保留原有群发权限和响应行为，新调用建议使用以下资源接口。

资源名称使用复数名词，创建使用 POST，查询使用 GET。按 HTTP Semantics 区分同步创建和异步受理， 不将 202 当成上传成功。任务失败是资源状态，查询仍返回 200，status=failed 并带 errorCode、errorMessage；接口调用本身失败则使用 ABP 错误响应。本模块将 WeCom:ApiCallFailed 映射为 502、WeCom:TenantRequired 映射为 400，这些映射也适用于模块其他接口。 参数校验使用 400，认证/授权错误使用 401/403；超过 HTTP 请求体限制由宿主返回 413。

同步临时素材

依据上传临时素材：

模块校验大小、扩展名和图片文件头；语音时长、媒体完整性等由企业微信校验。type 默认为 image。media_id 从企业微信创建时间起三天有效，过期需重新上传。语音上传能力不代表客户群发 支持语音附件；群发附件类型仍以群发接口协议为准。

curl -X POST 'https://your-host/api/wecom/media' \
  -H 'Authorization: Bearer <access-token>' -H '__tenant: <tenant-id>' \
  -F 'type=file' -F 'file=@document.pdf'

永久图片

企业微信当前上传图片接口返回长期有效 的图片 URL，不返回永久 media_id；它与微信公众号的永久素材接口不同。图片不超过 2MB， 返回 URL 用于企业微信允许的图片展示场景，不能作为通用外部站点图片 CDN。官方限制为每企业 每天最多 1000 张、每月最多 3000 张，由企业微信校验。

curl -X POST 'https://your-host/api/wecom/media/image-urls' \
  -H 'Authorization: Bearer <access-token>' -H '__tenant: <tenant-id>' \
  -F 'file=@image.png'

创建企业群发的图片附件可以使用此 接口返回的 url 填入 image.pic_url；不能使用任意外部图片 URL 代替。

异步上传任务

依据异步上传临时素材，目前仅支持 scene=1（客户联系入群欢迎语素材）、type=video|file，大小大于 5 字节且不超过 200MB。 视频要求 MP4，图片和语音不支持异步上传。CDN URL 必须支持 Range 分块下载，下载和 MD5、大小 检查由企业微信执行；本模块不访问或下载 URL。腾讯云 COS 链接需要公有读权限。

文件名上限 128 UTF-8 字节、URL 上限 1024 UTF-8 字节，MD5 为 32 位十六进制字符串。 jobId 上限 128 UTF-8 字节，官方查询有效期为 60 分钟，调用方需要及时查询并保存完成结果。 本模块采用主动查询方式，不保存任务或定时刷新，也不自动处理 upload_media_job_finish 回调。

POST /api/wecom/media/jobs
Content-Type: application/json

{
  "scene": 1,
  "type": "video",
  "fileName": "large.mp4",
  "url": "https://your-cdn/large.mp4",
  "md5": "00000000000000000000000000000000"
}

202 响应的 Location 可用于 GET 查询，status 为 processing、completed 或 failed。 仅完成状态返回 mediaId、createdAt、expiresAt；失败状态返回企业微信的任务错误码和消息。 异步产出的 media_id 同样三天有效，但使用范围与普通临时素材不同，不能直接用于企业群发。

三种模式都不新增数据库记录或保存本地文件，无新增迁移。宿主上传限制需要允许最大 20MB 同步文件及 multipart 开销。上传和任务查询为显式 HTTP API；进程内入口仍为 IWeComMediaAppService，新增接口方法及 IWeComApiClient 的同步素材方法需要自定义实现适配。