更新

artifacts/wecom-member-sync/frontend.md

@@ -0,0 +1,45 @@
+# 企业微信获客成员范围同步：前端修复
+
+## 诊断
+
+- 单独开关原先只检查 `sync_error`，为空就提示“企微多人路由范围已重新计算”；该字段无法区分同步已确认、任务仍在排队、活跃租约导致未执行等情况。
+- 批量保存原先只提示后台同步，没有主动消费成功入队的方案；分钟任务未运行时本地规则可以长期与官方链接不一致。
+- `is_in_remote_range` 来自官方链接上次确认的 `range_user_json`，并非本地 enabled 状态。“待移出”代表成员仍在记录中的企微范围，确实可能继续获客。
+- 原有 `syncRemoteLinks` 是企业微信链接列表导入接口，会扫描 `listLinks/getLink` 并 upsert，本次没有将它误用为推送当前方案成员范围的入口。
+
+## 最终行为
+
+- 接入新的 `POST /firstvisit.wecomPromotion/syncMemberRange`，只提交指定 `pool_id`，使用 120 秒超时并关闭 HTTP 自动重试。
+- 保存方案、保存成员规则、单独切换成员，仅在后端明确返回 `sync_status: synced` 时提示企微成员范围已确认同步；旧服务端缺少该字段时保守显示尚未确认同步。
+- 批量保存成功且 `sync_queued` 的方案立即进行专用范围同步，最多并发 2 个，全部等待结束再完成交互。对话框页脚显示同步进度，未完成时禁止关闭。
+- 按方案保留本地保存结果、企微同步结果及具体错误。保存失败或同步未确认的方案保持勾选，允许重试；pending 不做无界重复请求。
+- 方案顶部提供“同步成员范围”，结果列表提供“重试同步”。权限沿用方案 `can_operate`，必须已有官方链接。
+- 页面明确展示“当前计划”和“上次企微确认”成员及确认时间，保留服务端 `last_error`；行状态改为“企微范围内”“待移出（仍在企微）”“待加入企微”“未在企微范围”。
+
+## 文件
+
+- `admin/src/views/first_visit/wecom_promotion/index.vue`
+- `admin/src/api/first_visit.ts`
+- `admin/tests/wecom-promotion-member-sync.test.cjs`
+
+## 验证
+
+命令：`cd admin && node --test tests/wecom-promotion-member-sync.test.cjs`
+
+7 项通过，使用 Vue SFC 真实 setup 编译后执行，并编译模板及 SCSS；API 均为测试替身，不连接数据库或企业微信。
+
+1. 本地禁用而远端仍包含的成员明确显示待移出，展示实际同步错误。
+2. 单成员切换不把空错误和计划入队误判为企微同步成功。
+3. 单成员规则保存保留企微失败原因，只接受明确 synced 确认。
+4. 方案保存 pending 时保持警告。
+5. 手动重试只调用指定方案专用接口，并检查操作权限。
+6. 批量同步最多两并发，等待全部结果；本地保存失败项不会请求企微同步。
+7. 批量保存部分失败和企微超时保留逐项错误与选择，不误报整体成功。
+
+`git diff --check` 对修改文件通过。
+
+全量 `npx vue-tsc --noEmit --pretty false` 已执行，退出 1。报错位于工作区其他文件（处方、聊天、录音、装修、医生统计等）；本次修改的获客助手页面和 `first_visit.ts` 无报错。未为本次修复扩展修改这些独立模块。
+
+## 验证边界
+
+没有访问业务数据库、真实企微凭据，也没有发送消息或调用企业微信修改接口。尚未对真实已投放链接执行修复后的同步；需部署匹配的前后端后，在目标方案点击“同步成员范围”，以远端回读确认结果为准。