Qiwei Dashboard 开发过程记录

项目背景

为 claude-code/claude-code-qiwe-assistant 项目构建一个本地 Web Dashboard，让用户可以通过浏览器直观地完成企微核心能力的操作，降低纯对话调用的门槛。第一期聚焦在客户群管理模块，同时搭建好账号状态、登录恢复等公共基础设施。

已完成的模块

1. Dashboard 基础设施

HTTP 桥接服务：mcp/src/dashboard/server.js
- 静态资源服务（HTML/CSS/JS）
- REST API 路由封装
- 异步 Job 队列（createJob / getJob）
- 文件上传与下载（/api/upload、/api/outputs）
- 状态汇总接口（/api/status）
- 登录相关接口（/api/login/start、/api/login/check、/api/login/verify）
- 群管理接口（/api/groups/*）
- 客户运营接口（新增）：/api/customer-ops/*
- 画像与标签接口（新增）：/api/portraits/*、/api/tags/*、/api/personal-labels/*
- 客户交接接口（新增）：/api/transfers/*
前端 SPA 骨架：mcp/src/dashboard/index.html
- 侧边栏导航、顶部账号切换器、主内容区、Toast 容器
- 新增导航项（客户运营、画像与标签、客户交接）
前端逻辑：mcp/src/dashboard/app.js
- 路由（hash 路由：#groups、#status、#customer-ops、#portraits、#transfers）
- API 客户端封装
- 状态管理（内存 + localStorage）
- 公共组件：Toast、Modal、Job Tracker、Account Switcher
- 新增页面渲染器：renderCustomerOpsPage、renderPortraitsPage、renderTransfersPage
样式系统：mcp/src/dashboard/styles.css
- 复用企微品牌色（#fa8c16）
- 卡片、表格、表单、按钮、Badge、进度条、骨架屏、动画
启动入口：scripts/start-dashboard.js
文档：skills/qiwei-dashboard/SKILL.md、README.md Dashboard 章节

2. 账号状态模块

实现位置：app.js 中 renderStatusPage、attemptAutoRecover、recoverLogin、syncAccountOnlineStatus 等函数。

显示当前账号在线/离线状态、订阅状态、鉴权配置状态
离线恢复登录按钮：账号离线时显示「恢复登录」按钮
自动恢复登录：检测到离线且 statusCode === 0（设备已配置）时，自动调用 /api/login/check?manual=true 尝试免扫码恢复
手动恢复时若无法免扫码，自动生成二维码/验证码流程
已保存账号状态同步：修复了已保存账号表格状态与当前状态不一致的问题

3. 客户群管理模块

实现位置：app.js 中 renderGroupsPage、renderGroupTable、renderGroupSyncCard、bindGroupSync、bindGroupFilters、bindGroupTableActions、confirmGroup、batchConfirmGroups、syncGroupMessages、openGroupDetailModal 等函数。

群列表展示

表格展示：群名、人数、识别结果、置信度、消息同步状态、命中关键词、操作
空状态提示
搜索过滤（按群名/roomId）
状态过滤（全部、自动确认、建议确认、已确认、已忽略）
显示切换按钮：「只看可能的客户群」/「展示全部状态的群聊」，默认展示全部群聊

扫描客户群

扫描范围：全部群、我创建的群、最近聊天里的群、从消息记录里找群
扫描深度（分页数）
客户群关键词、高置信度词配置
自动识别客户群开关
异步 Job 执行扫描，实时进度条
扫描结果统计卡片：扫描群数、自动确认、建议确认、普通群、已确认、已忽略

批量操作

全选本页/单选
批量确认为客户群：直接调用 confirm API，不弹窗
批量同步选中群消息

单行操作

确认：直接确认为客户群（不弹窗）
忽略：弹出原因输入框
同步消息：同步单个群消息
群详情（仅已确认群）：查看/编辑客户信息

客户信息自动识别

后端 qiwei-group-management-run.js 中 createRoomRecord 现在保存群成员列表
已确认群的「群详情」弹窗会自动从成员列表中识别客户：
- 优先选择 type === 2 的外部联系人
- 无明确标识时排除常见内部角色后取第一个
- 自动预填充客户姓名和客户企微 ID
用户可在弹窗中修改客户信息并保存

消息同步状态持久化

已同步消息的群状态保存在 localStorage
修复了刷新页面后同步状态丢失的问题（移除了账号离线时清空同步状态的逻辑）

4. 客户运营模块（新增）

实现位置：app.js 中 renderCustomerOpsPage、bindCustomerOpsPage 及相关渲染函数。

批量加好友

文本导入：每行 13800138000 张三，自动解析为可编辑表格
Excel 上传：通过 /api/upload 保存后读取 customers 列表追加到表格
默认验证消息模板，支持 {{name}}、{{phone}} 变量
表格中每行可单独编辑姓名和验证消息，留空则使用默认模板
顶部实时预览第一条验证消息
执行设置：每分钟速率限制（1-60）、最大重试次数（1-5）
异步 Job 执行，结果展示统计卡片 + 明细表格

好友状态检查

输入手机号列表，异步 Job 执行
结果展示：已确认、待通过、未找到统计 + 明细表格
状态徽标：已是好友、已被其他人添加、未添加、未找到

客户档案

通过手机号或 externalUserId 查询
展示 externalUserId、匹配联系人、相关群、本地画像

自动建群

输入成员 externalUserId、群名、协作成员、欢迎语
异步 Job 执行建群
展示 roomId、群名、成员数、协作成员邀请状态、欢迎语发送状态

5. 画像与标签模块（新增）

实现位置：app.js 中 renderPortraitsPage、bindPortraitsPage 及相关渲染函数。

客户画像

关键词模式：直接生成并保存画像
AI 分析模式：生成 context 文件，可下载后人工分析
手动保存画像 JSON：通过 prompt 输入 JSON 后保存

批量画像

输入多个 externalUserId，关键词模式批量生成

导出画像

异步 Job 导出全部本地画像为 Excel
结果提供下载链接

本地标签

按客户添加/移除/查询标签
查看全部去重标签

企微个人标签

同步企微个人标签列表
创建/更新/删除个人标签
应用标签到指定客户

6. 客户交接模块（新增）

实现位置：app.js 中 renderTransfersPage、bindTransfersPage 及相关渲染函数。

输入 fromUserId / toUserId
支持通过 externalUserIds 或已确认群 roomIds 指定客户
生成交接包预览文件，展示明细列表
执行交接：可移除原顾问、设置欢迎语
结果展示成功/失败/跳过统计与明细

7. Bug 修复与体验优化

问题	修复
账号状态页「已保存账号」状态与当前在线状态不一致	新增 `syncAccountOnlineStatus`，在渲染表格前先同步状态
刷新页面后已同步消息群显示「未同步」	移除 `checkExistingLogin` 中的 `resetSyncedGroups()` 无条件清空逻辑
账号离线时点击「扫描客户群」提示不明确	增加离线拦截，提示先恢复登录并跳转到状态页
离线时点击「同步消息」也会失败	同样增加离线拦截
Dashboard 从错误目录启动导致「网络请求失败」	在 README 和 Skill 文档中明确必须在项目目录下启动

尚未实现的内容（对比原始 plan）

原始 plan 中提到的以下模块已在本轮实现：

客户运营：批量加好友、检查好友状态、客户档案、自动建群
画像与标签：客户画像、本地标签、企微个人标签
客户交接：交接包预览、执行交接

当前尚未实现的扩展模块：

API Catalog
语音转写
Webhook & Relay
顾问 Playbook

当前 Dashboard 已完成 plan 中「系统状态」、「群管理」、「客户运营」、「画像与标签」、「客户交接」五个模块的核心功能。

与原始 plan 的差异

客户运营模块实现与 plan 的差异

Excel 上传流程
- Plan：前端直接解析 Excel。
- 实际：前端通过 /api/upload 上传文件拿到路径后，调用 qiweiBatchAddFriends 读取 Excel 并追加到表格。这样复用了后端已有的 readCustomersFromExcel 逻辑。
客户档案查询
- Plan：仅提及输入手机号查询。
- 实际：同时支持手机号或 externalUserId 查询。

群管理模块实现与 plan 的差异

确认客户群流程
- Plan：未明确描述确认流程细节
- 实际：单个/批量确认均不弹窗，确认后才通过「群详情」编辑客户信息
客户信息自动识别
- Plan：未提及
- 实际：基于群成员列表自动识别外部联系人并预填充客户信息
关键词配置
- Plan：独立的「关键词配置」折叠面板
- 实际：关键词配置集成在「扫描客户群」卡片中
同步群消息
- Plan：支持多选已确认群或「全部已确认群」，设置分页和每群消息上限
- 实际：支持多选已确认群批量同步，但暂不支持「全部已确认群」一键同步和分页设置
群列表默认展示
- Plan：未明确默认过滤行为
- 实际：默认展示全部群聊，可通过按钮切换为「只看可能的客户群」
添加已创建客户群按钮
- Plan：未明确
- 实际：曾经实现后已删除

Plan 修改建议

基于当前已完成的群管理模块，原始 plan 应在以下方面更新：

群管理确认流程需要明确
- 当前 plan 只写「行操作包括确认、拒绝、分析、同步消息」，未说明确认时是否弹窗、是否需要填写客户信息。
- 建议改为：「确认」操作不弹窗，直接标记为客户群；客户信息在确认后通过「群详情」编辑，并支持自动识别。
新增「客户信息自动识别」功能
- 当前 plan 完全未提及。
- 建议在群管理交互中增加：已确认群支持查看群成员，系统自动识别外部联系人并预填充客户姓名和企微 ID。
关键词配置位置调整
- Plan 中写「关键词配置折叠面板」。
- 实际实现中关键词配置集成在「扫描客户群」卡片内，以减少页面切换。Plan 应更新为「扫描客户群卡片内包含关键词/高置信度词输入」。
同步群消息范围调整
- Plan 写「多选已确认群或全部已确认群，设置分页和每群消息上限」。
- 当前仅实现「多选已确认群」批量同步。Plan 可拆分为已实现和后续增强：
  - 已实现：多选已确认群批量同步
  - 待实现：「全部已确认群」一键同步、分页/每群上限设置
群列表默认展示状态
- Plan 未明确默认过滤行为。
- 建议补充：默认展示全部扫描到的群聊，提供按钮切换为「只看可能的客户群」。
系统状态模块补充
- Plan 中系统状态只写「登录状态、订阅状态、全局 guid 输入」。
- 实际已实现：离线恢复登录按钮、自动恢复登录、已保存账号列表及状态同步。Plan 应补充这些功能。
新增文件清单修正
- Plan 中列出 mcp/src/dashboard/pages.js（可选拆分）。
- 当前未拆分，app.js 约 1300 行仍可维护。建议从 plan 中移除或标注为「未拆分」。
范围与优先级调整
- 当前实际只完成了系统状态 + 群管理。建议把客户运营、画像标签、客户交接明确标注为「待实现/第二期」，避免与实际进度混淆。
新增验证项
- Plan 的验证方案中应增加：
  - 账号离线时恢复登录按钮可用
  - 自动恢复登录成功/失败场景
  - 已同步消息状态刷新后保留
  - 批量确认客户群和群详情编辑
移除「添加已创建客户群」按钮
- 实际开发中曾实现该按钮，后已删除。Plan 中如提到手动添加群，应说明通过业务工具或后续在群列表中提供入口。

后续建议

群管理可补充「全部已确认群一键同步消息」和同步参数设置
客户信息自动识别可进一步优化：结合群名正则、AI 分析群消息等多维度识别
客户运营可补充「从已确认群批量导入客户」功能
画像模块可接入 Claude API 自动分析 context 文件并保存
增加 Dashboard 的使用统计和错误日志收集
按需扩展 API Catalog、语音转写、Webhook & Relay、顾问 Playbook 等模块

DASHBOARD-DEV-LOG.md 13 KB Histórico Raw