EPA-014 WeChat WeCom Integrations
EAOS 的咨询和线上学习业务需要站内论坛、企业微信、微信群和微信服务号协同运行。本卷定义外部微信生态接入的系统边界：EAOS 负责身份、权益、社群、任务、积分和知识沉淀；外部渠道负责触达、提醒、陪伴和项目沟通。
Positioning
企业微信、微信群和微信服务号不是 EAOS 的替代品，而是学习交付的触点。所有关键业务事实必须回到 EAOS：
- 谁购买或兑换了学习产品。
- 谁获得了课程、资料、优惠券或咨询权益。
- 谁加入了哪个训练营或咨询社群。
- 哪些通知已发送，哪些通知失败。
- 哪些购买后提醒、公告提醒和打卡提醒已经进入触达队列。
- 哪些推荐码带来现金订单，哪些佣金仍待审核或已结算。
- 群内哪些共性问题回流为论坛主题、FAQ 或案例。
Channel Responsibilities
| Channel | Primary role | EAOS source of truth |
|---|---|---|
wecom_group | 训练营班主任服务、项目交付、任务催办 | LearningCommunity, CommunityMembership, CommunityChannelSyncJob |
wechat_group | 轻量交流、活动提醒、情绪支持 | LearningCommunity, CommunityTopic |
wechat_service_account | 报名确认、课程提醒、权益入口、续费提醒 | Entitlement, PurchaseOrder, RedemptionOrder, ReferralCommission |
forum | 问题沉淀、案例复盘、长期检索 | CommunityTopic, CommunityReply, CommunityReport |
Integration Boundary
第一阶段只做服务端适配层原型，不接真实商户或微信凭证。
允许：
- 在后台查看渠道同步任务。
- 对某个社群触发一次渠道同步检查。
- 对站内论坛渠道返回
synced。 - 对企业微信、微信群、服务号渠道返回
blocked_credentials，明确提示等待服务端凭证和回调配置。 - 购买、兑换、公告发布和任务打卡时写入
CommunityTouchpoint队列，并保存messageTitle、messageBody和actionUrl供运营预览。 - 写入审计日志，保留是谁触发了同步。
不允许：
- 在前端保存或展示企业微信、微信服务号、支付或商户密钥。
- 把用户手机号、OpenID、UnionID、群二维码等敏感标识写入公开页面。
- 在没有用户授权和合规审核前发送模板消息。
- 把微信群聊天记录当作长期知识库保存。
Core Workflow: Channel Sync Check
- 运营打开
/admin/。 - 运营在社群管理中点击“同步渠道”。
- Admin API 创建
CommunityChannelSyncJob。 forum渠道标记为synced。wecom_group、wechat_group、wechat_service_account标记为blocked_credentials。- 后台显示任务状态、渠道类型、供应方、目标和阻塞原因。
- 系统写入
community.channel.sync.requested审计日志。
Core Workflow: Learning Touchpoint Queue
购买后触达必须服务于“学员下一步去哪里学”。
- 学员购买或兑换带社群的产品。
- Commerce API 创建订单、权益和社群成员关系。
- 系统为企业微信、微信群和微信服务号生成
CommunityTouchpoint。 - 当前原型因没有真实凭证，外部渠道状态写为
blocked_credentials，并显示缺少凭证和回调配置。 - 后台展示触达队列和消息预览，运营能看到哪些提醒尚未真正发送，以及准备发送给学员的标题、正文和入口。
- 运营或服务端适配器可以把
queued触达标记为sent或failed，系统记录sentAt、lastError和尝试次数。 - 生产版服务端适配器读取队列，发送报名确认、课程入口、资料提醒、直播回放和答疑通知。
同一个触达队列还用于社群公告和任务打卡：公告发布时提醒成员查看资料或安排，任务打卡后可提醒班主任复核或继续学习。所有外部触达必须能回到 EAOS 的权益、学习中心、论坛和社群任务。
消息预览字段不是最终微信模板 ID，而是 EAOS 生成的业务文案草稿。生产适配器可以把它映射为服务号模板消息、企业微信群通知或微信群人工提醒，但发送前必须再次校验授权、频率和内容安全。
Production Adapter Requirements
生产版接入前必须重新核验企业微信和微信公众平台的官方文档、账号权限、IP 白名单、回调验签、消息模板、用户授权、频率限制和数据留存要求。
服务端适配器必须满足：
- 凭证只来自服务端环境变量或密钥管理服务。
- 回调验签失败必须拒绝处理。
- 消息发送失败要有重试、退避和人工处理入口。
- 用户标识要最小化保存，并能与 EAOS 用户、权益和社群成员关系映射。
- 二维码、入群链接和服务号跳转链接必须有过期时间和使用范围。
- 模板消息不得包含付费资源直链、私密群二维码、学生隐私或未授权课件内容，只能指向学习中心、社群页或论坛入口。
- 所有发送、同步、失败和人工重试都写入审计日志。
Data Objects
| Object | Key fields |
|---|---|
CommunityChannel | communityId, type, label, externalRef, status, purpose |
CommunityChannelSyncJob | communityId, channelId, channelType, provider, operation, status, lastError, finishedAt |
CommunityMembership | communityId, userId, role, status, sourceType, sourceId |
Entitlement | userId, productId, type, status, sourceType, sourceId |
CommunityAnnouncement | communityId, title, body, targetChannels, status |
CommunityTask | communityId, title, summary, pointsRuleCode, targetChannels |
CommunityTouchpoint | communityId, userId, channelType, provider, eventType, sourceId, messageTitle, messageBody, actionUrl, status, lastError |
AuditLog | actorId, action, target, metadata |
Acceptance
当前原型完成标准：
- 后台社群行提供“同步渠道”按钮。
- API 提供
GET /api/admin/channel-sync-jobs。 - API 提供
POST /api/admin/channel-sync-jobs。 - 后台展示渠道同步任务、阻塞原因和同步统计。
- 购买或兑换带社群产品后生成购买后触达队列。
- 发布社群公告、提交任务打卡后生成相应触达队列。
- 后台展示社群触达队列、消息预览、发送状态和
blocked_credentials数量。 - 后台可以把
queued触达标记为sent或failed，并能把failed触达重新排队。 prisma/schema.prisma有CommunityChannelSyncJob模型。- OpenAPI 覆盖渠道同步任务接口和 schema。
apps/api/test.mjs覆盖一次社群渠道同步检查。
生产版完成标准：
- 企业微信、微信群和微信服务号接入独立服务端适配器。
- 微信回调、授权、消息模板、失败重试、人工重试和审计全部可追踪。
- 购买或兑换后，服务号提醒、企微入群、论坛权益入口能按用户权益自动串联。
- 群内高价值问题能回流为论坛主题或案例库条目。