官方文档：平台介绍 - QiWe API｜企微 API 开发文档
一、业务痛点与技术背景
典型企业微信 SCRM SOP：
新客户添加 → 打标签 → 发送欢迎与资料 → 进入培育序列 → 到期未回复转销售 → 成交打标 → 拉入客户群
用脚本硬编码会导致：销售规则变更要发版、无法灰度、跨系统补偿困难。应使用可视化/配置化工作流，QiWe API 作为 Action Provider。
二、核心架构设计与数据流转
Trigger: friend_added | order_paid | timer | crm_stage_changed │ ▼ Flow Engine (版本化定义) │ ├─ Condition (标签/阶段/企微群) ├─ Action.qiwe.* (经 Outbound Gateway) ├─ Action.crm.* └─ Wait / Split / Join / Human Task │ ▼ Instance State DB + Timeline（客户旅程）三、关键代码与配置示例
3.1 SOP 定义
id: new_customer_sop version: 5 trigger: { type: qiwe_event, event: external_friend_added } steps: - id: tag_new action: qiwe.add_tags params: { tags: ["新客", "未首购"] } - id: welcome action: qiwe.send_text params: { template: "ent_welcome_v5" } - id: send_deck action: qiwe.send_file params: { file_asset: "product_deck.pdf" } - id: wait_2d action: delay params: { days: 2 } - id: check_reply action: condition when: "stats.customer_replied == false" then: - action: crm.assign_owner params: { pool: "sales_a" } - action: qiwe.send_text params: { template: "sales_followup" } else: - action: qiwe.add_tags params: { tags: ["互动中"] }3.2 Action Provider
class QiWeActions: def __init__(self, gateway, client): self.gateway = gateway self.client = client def add_tags(self, ctx, tags): return self.client.call("/contact/addTag", { "guid": ctx["guid"], "userId": ctx["customer_id"], "tags": tags, }) def send_text(self, ctx, template): content = render(template, ctx) return self.gateway.enqueue({ "client_msg_id": f"{ctx['instance_id']}:send_text:{template}", "guid": ctx["guid"], "to_id": ctx["customer_id"], "chat_type": "user", "priority": 1, "kind": "text", "payload": {"content": content}, })3.3 与 CRM 阶段联动
onCrmStageChanged(async (e) => { if (e.stage === "won") { await flow.start("post_sale_onboarding", { customerId: e.customerId, guid: e.qiweGuid, }); } });3.4 人工任务
高客单报价发送前 → human_task(销售经理审批) 通过 → send_file(报价单) 驳回 → 通知草稿修改者，流程 park四、生产环境避坑与安全风控
步骤幂等：
instance_id + step_id作为 client_msg_id。版本冻结：旧客户继续跑 v5，新客可切 v6。
Delay 持久化：用调度器，勿
sleep在消费协程。失败策略：可配置 retry / skip / park，禁止静默吞错。
效果分析：按 step 漏斗看欢迎语与资料转化。
能力清单见文首官方文档。
五、本篇交付清单
SCRM SOP 配置模型
QiWe Action Provider
CRM 联动与人工审批
幂等与版本化要点
