docs: 企微化流程环境变量清单与部署指南（回调/回流/催办/复盘）

.env.app.example

@@ -50,6 +50,17 @@ WECOM_AGENT_ID=
 WECOM_SECRET=
 WECOM_NOTIFY_DUE_DAYS=3
 WECOM_NOTIFY_ENABLED=true
+# 数据回流通知（可选）：KOC 提交链接/截图、每日采集摘要推运营群机器人，默认关闭。
+WECOM_FEEDBACK_ENABLED=false
+# 超期升级催办（可选）：超期任务升级运营群机器人 + 项目总群交互卡片，默认关闭。
+WECOM_ESCALATION_ENABLED=false
+# 超期 N 天自动释放（可选）：从 due_at 起算，超期内容自动回到可领取池，0 = 关闭（默认），最大 90。
+WECOM_AUTO_RELEASE_DAYS=0
+# 企微回调（可选）：交互卡片「已处理」回执落库。需在企微后台「接收消息」配置回调 URL
+# https://<APP_ORIGIN>/api/wecom-callback + 下方 Token / EncodingAESKey，默认关闭。
+WECOM_CALLBACK_ENABLED=false
+WECOM_CALLBACK_TOKEN=
+WECOM_CALLBACK_ENCODING_AES_KEY=
 
 # ── 调度与入口 ────────────────────────────────────────────
 # 每天北京时间 09:00 自动执行采集计划，生产保持 true。

CLAUDE.md

@@ -93,6 +93,11 @@ WECOM_SECRET           — 企业微信自建应用 Secret（可选）
 WECOM_ROBOT_WEBHOOK    — 企业微信群机器人 webhook（当日催办汇总，可选）
 WECOM_NOTIFY_DUE_DAYS  — 临期阈值，默认 3，取值 1–30（可选）
 WECOM_NOTIFY_ENABLED   — 企业微信通知总开关，默认 true（可选）
+WECOM_FEEDBACK_ENABLED — 数据回流通知（提交/采集摘要推运营群），默认 false（可选）
+WECOM_ESCALATION_ENABLED — 超期升级催办（运营群+交互卡片），默认 false（可选）
+WECOM_AUTO_RELEASE_DAYS — 超期 N 天自动释放，从 due_at 起算，0=关闭（可选）
+WECOM_CALLBACK_ENABLED — 企微回调开关（交互卡片回执），默认 false（可选）
+WECOM_CALLBACK_TOKEN / WECOM_CALLBACK_ENCODING_AES_KEY — 企微回调密钥（/api/wecom-callback）
 ```
 
 ## Commands

dev.vars_exp

@@ -26,6 +26,16 @@ WECOM_ROBOT_WEBHOOK=
 WECOM_NOTIFY_DUE_DAYS=3
 # 企业微信通知总开关，默认 true；临时关闭设为 false
 WECOM_NOTIFY_ENABLED=true
+# 数据回流通知（可选）：KOC 提交链接/截图、采集摘要推运营群机器人，默认关闭
+WECOM_FEEDBACK_ENABLED=false
+# 超期升级催办（可选）：超期任务升级运营群 + 项目总群交互卡片，默认关闭
+WECOM_ESCALATION_ENABLED=false
+# 超期 N 天自动释放（可选）：从 due_at 起算，0 = 关闭（默认），最大 90
+WECOM_AUTO_RELEASE_DAYS=0
+# 企微回调（可选）：交互卡片「已处理」回执落库；回调 URL 为 /api/wecom-callback，默认关闭
+WECOM_CALLBACK_ENABLED=false
+WECOM_CALLBACK_TOKEN=
+WECOM_CALLBACK_ENCODING_AES_KEY=
 
 # 本地测试：让 /api/bootstrap 自动 seed 3 个测试 partner + 5 条待发布 distribution
 # 上线后改为 false

docs/KOC LOOP 私有化部署指南.md

@@ -65,6 +65,11 @@ cp .env.app.example .env.app
 | `WECOM_ROBOT_WEBHOOK` | 企业微信群机器人 webhook，用于当日催办汇总 |
 | `WECOM_NOTIFY_DUE_DAYS` | 临期阈值，默认 3，超过则不在催办；可填 1–30 |
 | `WECOM_NOTIFY_ENABLED` | 企业微信通知总开关，默认 `true`；临时关闭设为 `false` |
+| `WECOM_FEEDBACK_ENABLED` | 数据回流通知，默认 `false`；开启后 KOC 提交链接/截图与每日采集摘要推送运营群机器人 |
+| `WECOM_ESCALATION_ENABLED` | 超期升级催办，默认 `false`；开启后超期任务升级运营群机器人 + 项目总群交互卡片 |
+| `WECOM_AUTO_RELEASE_DAYS` | 超期 N 天自动释放内容回可领取池，从 `due_at` 起算，`0` = 关闭（默认），最大 90 |
+| `WECOM_CALLBACK_ENABLED` | 企微回调开关，默认 `false`；开启后支持交互卡片「已处理」回执落库，需配置回调 URL 与密钥 |
+| `WECOM_CALLBACK_TOKEN` / `WECOM_CALLBACK_ENCODING_AES_KEY` | 企微后台「接收消息」里生成的回调 Token 与 EncodingAESKey |
 
 企业微信变量全部选填：不填则临期催办与汇总都跳过，不影响其他功能。所有变量都可以在「合作方」页面顶部「企业微信连通性」面板查看就绪状态，并用「测试群机器人」「测试发送」按钮验证。
 
@@ -229,7 +234,7 @@ docker compose --env-file .env.app \
 
 ## 11. 企业微信自建应用与群机器人配置
 
-KOC LOOP 的企业微信通知是**单向外发**：每天 09:00 与定时采集一同触发，给合作方绑定的外部联系人推送临期催办，再向群机器人发送当日汇总。不需要 OAuth 回调，也不需要拉通讯录。
+KOC LOOP 的企业微信通知默认是**单向外发**：每天 09:00 与定时采集一同触发，给合作方绑定的外部联系人推送临期催办，再向群机器人发送当日汇总。基础催办不需要回调，也不需要拉通讯录；交互卡片回执等进阶能力见第 12 章。
 
 ### 11.1 群机器人（用于当日催办汇总）
 
@@ -280,3 +285,36 @@ KOC LOOP 的企业微信通知是**单向外发**：每天 09:00 与定时采集
 使用流程：后台「任务中心」→ 任务行「发布到企微群」→ 弹窗内「同步群列表」（拉取客户联系下的正常状态客户群）→ 勾选目标群、确认文案 → 「创建群发」。创建成功后平台返回 msgid 并落库 `wecom_group_pushes`，各群主在企微客户端收到群发助手提醒，**点击发送后**消息（含 KOC 领取链接）才出现在群里。
 
 限制与注意：每个客户群每月最多接收「当月天数」条企业群发；群主使用的企业微信客户端需 ≥4.1.10 才能免选群直接发送；无效的 chat_id 会进入失败列表但不影响其他群。
+
+## 12. 以企微为中心的业务流程（一键推送 / 回流通知 / 分层催办 / 回调卡片 / 复盘报表）
+
+在 11.2 自建应用与 11.5 企业群发的基础上，以下能力全部由环境变量独立控制，默认关闭，不配置则对现有流程零影响。推送记录统一落库 `wecom_push_logs`（迁移 `mysql/0011_wecom_push_logs.sql`，`npm run db:migrate` 自动执行）。
+
+### 12.1 任务一键推送
+
+后台「任务中心」→ 任务行「一键推送」：一次把任务送达三类对象 —— ①项目总群成员应用消息（复用项目推送）②已绑定企微的 KOC 个人直达（弹层默认全选，可搜索/取消勾选）③可选创建任务群企业群发。同一任务当日重复推送会先提示，确认后可强制再推。KOC 消息里的领取链接在企微内置浏览器打开时自动完成 OAuth 静默登录，KOC 无需输任何身份。
+
+### 12.2 数据回流通知（`WECOM_FEEDBACK_ENABLED`）
+
+开启后：KOC 提交发布链接 / 截图 → 运营群机器人收到提醒（合作方 / 任务 / 标题 / 链接）；每天 09:00 定时采集结束后推送批次摘要，采集失败会附告警清单。通知失败不影响提交与采集主流程。
+
+### 12.3 超期升级与自动释放（`WECOM_ESCALATION_ENABLED` / `WECOM_AUTO_RELEASE_DAYS`）
+
+催办分三层：临期（默认 3 天内）直达合作方本人（原有逻辑不变）→ 超期（`due_at` 已过）升级运营群机器人汇总 + 项目总群成员收到 template_card 交互卡片（按钮「查看任务」跳转、「已处理」回执落库）→ 超期 N 天（`WECOM_AUTO_RELEASE_DAYS`，从 `due_at` 起算）自动把仍未发布的 distribution 释放回可领取池，已提交截图或已回填链接的不释放。两层开关独立；也可在「合作方」页点「跑一次超期升级」手动触发。
+
+### 12.4 企微回调配置（`WECOM_CALLBACK_ENABLED`）
+
+交互卡片「已处理」按钮需要公网回调才能回执。步骤：
+
+1. 登录企业微信管理后台 → 应用管理 → 自建 → 打开 11.2 的应用；
+2. 「接收消息」→ 设置 API 接收 → 回调 URL 填 `https://<APP_ORIGIN>/api/wecom-callback`（必须公网 80/443 可达，与 APP_ORIGIN 一致）；
+3. Token 与 EncodingAESKey 随机生成后，分别填入 `WECOM_CALLBACK_TOKEN`、`WECOM_CALLBACK_ENCODING_AES_KEY`，保存时企微会向该 URL 发 GET 验证，服务端自动应答；
+4. 「企业可信 IP」（开发者接口）加入服务器出口 IP，否则 access_token 类接口全部返回 `60020`；
+5. 应用「可见范围」包含接收卡片的运营成员；
+6. `WECOM_CALLBACK_ENABLED=true` 并重启服务；关闭时回调路由直接 403，可随时回退。
+
+回执写入 `wecom_push_logs`（`push_kind = card_ack`），在任务推送记录里可见「卡片确认」条目。回调地址、Token 或密钥配错时企微保存验证不通过，逐项核对第 2、3 步。
+
+### 12.5 复盘报表
+
+后台「复盘报表」（管理员可见）：按任务汇总领取 / 发布 / 完成数、完成率、曝光阅读与 D2/D5/D7/最新互动数据，支持状态、类型、关键词筛选，一键导出带 BOM 的 CSV（Excel 直接打开不乱码）。无需环境变量。