# 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 的差异

1. **Excel 上传流程**
   - Plan：前端直接解析 Excel。
   - 实际：前端通过 `/api/upload` 上传文件拿到路径后，调用 `qiweiBatchAddFriends` 读取 Excel 并追加到表格。这样复用了后端已有的 `readCustomersFromExcel` 逻辑。

2. **客户档案查询**
   - Plan：仅提及输入手机号查询。
   - 实际：同时支持手机号或 externalUserId 查询。

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

1. **确认客户群流程**
   - Plan：未明确描述确认流程细节
   - 实际：单个/批量确认均不弹窗，确认后才通过「群详情」编辑客户信息

2. **客户信息自动识别**
   - Plan：未提及
   - 实际：基于群成员列表自动识别外部联系人并预填充客户信息

3. **关键词配置**
   - Plan：独立的「关键词配置」折叠面板
   - 实际：关键词配置集成在「扫描客户群」卡片中

4. **同步群消息**
   - Plan：支持多选已确认群或「全部已确认群」，设置分页和每群消息上限
   - 实际：支持多选已确认群批量同步，但暂不支持「全部已确认群」一键同步和分页设置

5. **群列表默认展示**
   - Plan：未明确默认过滤行为
   - 实际：默认展示全部群聊，可通过按钮切换为「只看可能的客户群」

6. **添加已创建客户群按钮**
   - Plan：未明确
   - 实际：曾经实现后已删除

## Plan 修改建议

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

1. **群管理确认流程需要明确**
   - 当前 plan 只写「行操作包括确认、拒绝、分析、同步消息」，未说明确认时是否弹窗、是否需要填写客户信息。
   - 建议改为：「确认」操作不弹窗，直接标记为客户群；客户信息在确认后通过「群详情」编辑，并支持自动识别。

2. **新增「客户信息自动识别」功能**
   - 当前 plan 完全未提及。
   - 建议在群管理交互中增加：已确认群支持查看群成员，系统自动识别外部联系人并预填充客户姓名和企微 ID。

3. **关键词配置位置调整**
   - Plan 中写「关键词配置折叠面板」。
   - 实际实现中关键词配置集成在「扫描客户群」卡片内，以减少页面切换。Plan 应更新为「扫描客户群卡片内包含关键词/高置信度词输入」。

4. **同步群消息范围调整**
   - Plan 写「多选已确认群或全部已确认群，设置分页和每群消息上限」。
   - 当前仅实现「多选已确认群」批量同步。Plan 可拆分为已实现和后续增强：
     - 已实现：多选已确认群批量同步
     - 待实现：「全部已确认群」一键同步、分页/每群上限设置

5. **群列表默认展示状态**
   - Plan 未明确默认过滤行为。
   - 建议补充：默认展示全部扫描到的群聊，提供按钮切换为「只看可能的客户群」。

6. **系统状态模块补充**
   - Plan 中系统状态只写「登录状态、订阅状态、全局 guid 输入」。
   - 实际已实现：离线恢复登录按钮、自动恢复登录、已保存账号列表及状态同步。Plan 应补充这些功能。

7. **新增文件清单修正**
   - Plan 中列出 `mcp/src/dashboard/pages.js`（可选拆分）。
   - 当前未拆分，app.js 约 1300 行仍可维护。建议从 plan 中移除或标注为「未拆分」。

8. **范围与优先级调整**
   - 当前实际只完成了系统状态 + 群管理。建议把客户运营、画像标签、客户交接明确标注为「待实现/第二期」，避免与实际进度混淆。

9. **新增验证项**
   - Plan 的验证方案中应增加：
     - 账号离线时恢复登录按钮可用
     - 自动恢复登录成功/失败场景
     - 已同步消息状态刷新后保留
     - 批量确认客户群和群详情编辑

10. **移除「添加已创建客户群」按钮**
    - 实际开发中曾实现该按钮，后已删除。Plan 中如提到手动添加群，应说明通过业务工具或后续在群列表中提供入口。

## 后续建议

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