# 企微社群运营实施记录

> 对应方案：`qiwei-group-operations-product-development-spec.md`  
> 开始日期：2026-07-18  
> 当前阶段：Phase 3 受控自动化底座已完成，真实自动发送保持关闭

## 状态说明

- `完成`：代码已落地并通过对应本地验证。
- `进行中`：已有实现，但仍缺集成或真实环境验证。
- `待开始`：尚未开发。
- `受阻`：需要真实账号、业务规则或外部权限。

## 已完成

### 2026-07-18

| 工作项 | 状态 | 产物/说明 |
|---|---|---|
| 产品与技术方案 | 完成 | `docs/specs/qiwei-group-operations-product-development-spec.md` |
| `qiwei-group-operations` Skill 骨架 | 完成 | 主 `SKILL.md` + 数据模型、质检规则、输出契约三份渐进引用 |
| Skill UI 元数据 | 完成 | `skills/qiwei-group-operations/agents/openai.yaml` |
| 社群运营 SQLite 数据层 | 完成 | 群主档、SOP/版本、计划/计划项、消息、质检、审计；所有业务表带 `account_key` |
| SOP 版本管理 | 完成 | 创建草稿、创建版本、发布、指定版本回滚、审计 |
| 每日运营计划 | 完成 | 从已发布 SOP 生成待审核计划，同群同日幂等，支持模板变量 |
| 计划项人工闭环 | 完成 | 批准、拒绝、跳过、标记人工已执行；真实自动发送保持关闭 |
| 确定性质检 MVP | 完成 | 投诉/退款等风险词、客户问题超时未回应、稳定指纹去重、原消息证据 |
| 每日运营简报 | 完成 | 群数、已发布 SOP、今日任务、完成率、待审核、高风险和未闭环事项 |
| MCP 工具 | 完成 | 新增 8 个工具：上下文、计划、话术、质检、简报、SOP、计划执行、质检处理 |
| Dashboard API | 完成 | 新增 `/api/group-ops/*` 读取、发布、计划、审核和质检处理接口 |
| Dashboard MVP | 完成 | 新增“社群运营”导航、运营指标、SOP、计划生成、今日工作台、质检预警 |
| 可访问性与响应式基础 | 完成 | 表单 label、按钮禁用态、键盘 focus、375px/平板布局、减少动态效果 |
| 本地 smoke 脚本 | 完成 | 覆盖账号隔离、SOP 发布、计划幂等、审核执行、风险质检和闭环 |
| 发布检查接入 | 完成 | `release-check.js` 已加入 `group-ops:check` 与 `group-ops:smoke` |
| 群消息兼容入库 | 完成 | webhook 与历史同步成功落盘后，按设备 `guid` 兼容写入账号隔离的社群运营群/消息表；缺少 guid 时安全跳过新表 |

### 2026-07-18 · Phase 2

| 工作项 | 状态 | 产物/说明 |
|---|---|---|
| 按门店批量生成计划 | 完成 | 支持显式群列表或门店范围；逐群幂等，部分失败不回滚成功项 |
| 跨门店运营对比 | 完成 | 展示群数、今日任务、完成数、执行率、未闭环与高风险；无任务时显示数据不足 |
| 群活跃趋势与生命周期建议 | 完成 | 对比近 7 天与前 7 天消息、活跃成员、最近消息、风险，并给出可解释建议和覆盖率 |
| 整改任务主账 | 完成 | 质检项可创建整改任务，支持负责人、期限、优先级、状态和审计 |
| 企微官方待办衔接 | 完成 | 精确匹配内部成员且人工确认后创建真实待办；本地完成可同步官方完成状态 |
| 质检阈值配置 | 完成 | 账号级 SLA、风险词、禁止承诺配置并留审计；消息质检自动采用当前配置 |
| 误报反馈评测集 | 完成 | `false_positive` 不删除历史结论，独立保存反馈记录并统计误报率 |
| 质量评测脚本 | 完成 | `scripts/group-operations-quality-eval.js` 输出 precision/recall 并纳入发布检查 |
| 优秀话术沉淀 | 完成 | 从已执行且有最终内容的计划项汇总高频话术，不把未发送草稿计入 |
| SOP 版本治理 | 完成 | 版本列表、结构差异、影响群/门店预览、指定版本发布和回滚 |
| Dashboard 五视图 | 完成 | 运营总览、今日工作台、群洞察、SOP 版本、质检督导；移动端响应式与键盘焦点保持一致 |
| Phase 2 MCP/API | 完成 | 新增批量计划、运营洞察、整改任务 3 个 MCP 工具，总计 86 个；Dashboard API 完成对应闭环 |

### 2026-07-18 · Phase 3

| 工作项 | 状态 | 产物/说明 |
|---|---|---|
| 自动化策略版本 | 完成 | 策略草稿、不可变版本、人工激活、历史策略保留；激活后强制保持暂停 |
| 群与内容白名单 | 完成 | 只有显式 `allowedGroupIds` 和 `allowedTypes` 才能通过执行闸门 |
| 时间窗与灰度 | 完成 | 使用 Asia/Shanghai 判断星期和时间窗；按 roomId 稳定哈希命中灰度比例 |
| 单群频控 | 完成 | 单群每日、近 7 天发送上限，基于成功回执计数 |
| 内容与风险闸门 | 完成 | 未批准、未到时间、高风险未闭环、变量未替换、禁止承诺和重复发送全部拦截 |
| 幂等与回执 | 完成 | 保存幂等键、策略版本、决策、模式、状态、外部消息 ID、错误和完成时间 |
| 连续失败熔断 | 完成 | 达到策略阈值自动熔断；后续项目全部阻止，只能人工确认复位 |
| 一键暂停/恢复 | 完成 | 暂停立即生效；恢复必须人工确认；状态变化全量审计 |
| dry-run | 完成 | 支持预演和记录 dry-run，不调用 Fmode、不改变计划项发送状态 |
| 真实发送三重保护 | 完成 | 仅 `auto` 策略 + `execute=true/confirmed=true` + `QIWEI_GROUP_OPS_LIVE_SEND=1` 才可能调用 `/msg/sendText` |
| 自动化 Dashboard | 完成 | 新增策略、状态、白名单、时间窗、灰度、频控、熔断、预演、dry-run 和执行日志视图 |
| Phase 3 MCP/API | 完成 | 新增 `qiwei_group_ops_automation`，总计 87 个 MCP 工具 |
| 自动化专项测试 | 完成 | 覆盖暂停、白名单、灰度、时间窗、连续失败熔断、人工复位、dry-run 和真实发送阻断 |

### 2026-07-18 · 规格对照审查修复

| 工作项 | 状态 | 产物/说明 |
|---|---|---|
| SOP 草稿与发布版本隔离 | 完成 | 创建新草稿不再停用当前已发布 SOP；生成计划只读取当前发布快照，实际话术与 `playbook_version_id` 保持一致 |
| 有效回应判定 | 完成 | 客户问题后的无关、寒暄或占位消息不再算有效回应；新增意图与关键词相关性规则，并支持后续有效回复自动闭环 |
| 质检时间范围 | 完成 | 消息质检支持 `startAt` / `endAt`，避免每次扫描全部历史消息 |
| 发送回执未知保护 | 完成 | 网络超时、连接重置等结果不确定场景记录为 `unknown`，在人工核对回执前锁住同一幂等键，避免自动重发 |
| 批次熔断即时生效 | 完成 | 每个发送项执行前重新计算安全闸门；批次中途触发熔断后，后续项目立即转为拦截 |
| 账号级增量消息同步 | 完成 | 每个企微账号只调用一次增量消息流，按 `fromRoomId` 分流到目标群；完整拉取后保存账号级 `travelSyncKey` 游标，分页未完成时不推进游标 |
| SOP 发布/回滚确认 | 完成 | MCP/API 必须显式传 `confirmed=true`；Dashboard 先展示影响范围并由用户确认 |
| 可解释群健康分 | 完成 | 新增每日评分表，按 SOP、响应、风险、互动分项计算；缺少数据时排除对应权重并展示覆盖率、分项证据量和健康分布 |
| 审查回归测试 | 完成 | 新增未发布草稿隔离、版本审计一致性、无关/有效回复、回执未知锁定、健康分覆盖率和发布确认测试 |
| RBAC 权限框架与模拟验收 | 完成 | 新增总部管理员、区域经理、门店经理、执行员工、只读审计者角色；支持账号级 `userId` 绑定与门店范围；新增角色管理 MCP，当前总计 88 个 MCP 工具；覆盖首次初始化、跨门店拒绝、非总部发布 SOP 拒绝及审计者执行拒绝 |

## 进行中

| 工作项 | 状态 | 剩余内容 |
|---|---|---|
| Phase 0 账号隔离 | 进行中 | 新模块数据已隔离；旧 `outputs/groups/*` 和历史消息路径仍需迁移为账号目录 |
| 真实样本质量评测 | 进行中 | 评测脚本与内置回归集已完成；仍缺 1,000 条脱敏消息和业务人员阈值校准 |

## 受阻或需业务确认

| 工作项 | 状态 | 阻塞条件 |
|---|---|---|
| 真实自动群消息发送 | 受阻 | `/msg/sendText`、`/msg/sendGroupMsg` 需真实账号完成回执、频控、超时幂等 smoke |
| 20 群连续试点 | 受阻 | 需要确定 3 家门店、20 个授权客户群及负责人 |
| 公司级正式 SOP | 受阻 | 需要业务方提供或审核群类型、服务 SLA、禁用词、升级人工规则和首批话术 |
| 正式角色映射 | 受阻 | 权限框架与模拟测试已完成；需要提供真实总部、区域、门店、审计者的 `userId` 及门店范围后才能启用生产绑定 |
| 数据保留与合规 | 受阻 | 需要确认群消息保留期限、脱敏范围和内部授权 |
| 官方待办 live smoke | 受阻 | 同步逻辑与人工确认保护已完成；需要已初始化的企微官方 CLI 和测试成员完成真实创建/完成验证 |

## 后续开发顺序

1. 把 webhook 和历史同步改为“账号级一次增量拉取，按 roomId 分流入库”。
2. 为旧群列表、确认映射和消息缓存增加账号命名空间及迁移脚本。
3. 完成真实发送接口 smoke 后，仅对白名单和人工批准项开放发送。
4. 用 1,000 条脱敏消息扩充评测集，校准投诉与未回应识别阈值。
5. 用真实企微官方 CLI 完成整改待办创建和完成状态 live smoke。
6. 开展 20 群、14 天真实试点并在本文件记录指标。

## 验证记录

| 日期 | 验证 | 结果 |
|---|---|---|
| 2026-07-18 | `npm run group-ops:check` | 通过 |
| 2026-07-18 | `npm run group-ops:smoke` | 首次发现消息表占位符错误，修复后通过 |
| 2026-07-18 | Skill `quick_validate.py` | 通过；`Skill is valid!` |
| 2026-07-18 | `npm run check` | 通过 |
| 2026-07-18 | Dashboard 本地 HTTP smoke（4322） | `/api/group-ops/overview` 返回 `ok`，首页包含 `group-ops` 导航 |
| 2026-07-18 | `npm run package:smoke` | 通过；18 skills、83 MCP tools、0 forbidden files |
| 2026-07-18 | `npm run release:check` | 最终通过 11 组发布检查；同步修复 webhook 旧测试期望、Relay 测试隔离、画像 Excel 复用现有导出组件及输出目录 manifest 基线 |
| 2026-07-18 | Phase 2 `npm run group-ops:smoke` | 通过；覆盖 SOP v2/影响预览/回滚、门店批量计划、配置、反馈、整改任务、群洞察和优秀话术 |
| 2026-07-18 | `npm run group-ops:eval` | 通过；内置 4 个规则样本，precision=1、recall=1，仅作为回归测试，不代替真实评测集 |
| 2026-07-18 | Phase 2 Dashboard 隔离 API smoke | 通过；SOP 创建/预览/发布、计划、质检设置、整改任务、门店和群洞察全部返回 `ok` |
| 2026-07-18 | Phase 2 Skill `quick_validate.py` | 通过；`Skill is valid!` |

### 2026-07-18 · 当前登录账号 live smoke

| 验证 | 结果 |
|---|---|
| Fmode 设备登录 | 通过；设备在线，状态码 2 |
| 包月订阅 | 通过；1/1 席位已使用，订阅有效，自动续费开启 |
| 自建外部群读取 | 通过；读取 6 个外部群，接口无错误 |
| 群分类缓存 | 通过；4 个 `IMPORTED`、2 个 `SUGGESTED`，未自动确认真实客户群 |
| 单群详情分析 | 通过；候选群详情可读，保持 `SUGGESTED`，未误改为已确认 |
| 单页历史消息同步 | 接口通过；所选群本页新增 0 条，因此本次未验证真实消息质检样本 |
| 企微官方待办 live smoke | 未执行；当前官方 CLI 尚未安装、未授权 |

本次 live smoke 只执行读取、分析和本地缓存更新，没有发消息、建群、修改群资料或创建真实企微待办。

### 2026-07-18 · Phase 3 自动化验证

| 验证 | 结果 |
|---|---|
| `npm run group-ops:smoke` | 通过；策略、暂停、时间窗、灰度、频控、三次失败熔断和人工复位通过 |
| `npm run group-ops:auto-smoke` | 通过；dry-run 不调用真实网关，环境开关关闭时真实执行被强制阻断 |
| Phase 3 Dashboard 隔离 API smoke | 通过；激活后 `paused=1`、人工恢复后 `paused=0`、预演通过 1 项、dry-run 1 项、真实执行被环境开关阻断 |
| 当前真实发送开关 | `QIWEI_GROUP_OPS_LIVE_SEND` 未开启，未向当前登录账号的任何群发送测试消息 |
| `npm run release:check` | 通过 12 组发布检查；18 个 Skills、87 个 MCP 工具、148 个打包条目、0 个禁入文件 |