# 会话激活功能使用指南

## 📋 功能概述

会话激活页面是一个全新的独立功能模块，用于管理项目群聊的激活和沟通。该模块提供了以下核心功能：

### ✨ 核心功能

1. **用户源聊天记录筛选** - 一键过滤客户消息，快速查看客户历史沟通记录
2. **三种入群方式** - 支持二维码、链接、手动拉群三种方式
3. **入群自动化文案** - 群创建后自动发送项目介绍文案
4. **超时未回复提醒** - 10分钟未回复自动推送通知
5. **辅助回复功能** - AI智能生成3-5条备选回复
6. **移动端完美适配** - 响应式设计，支持手机端操作

---

## 🚀 快速开始

### 1. 路由配置

在项目路由配置文件中添加会话激活页面路由：

```typescript
// 在 app.routes.ts 或相应的路由配置文件中添加
{
  path: 'wxwork/:cid/project/:projectId/chat-activation',
  component: ChatActivationComponent,
  canActivate: [WxAuthGuard]
}
```

### 2. 导航到页面

从项目详情页跳转到会话激活页面：

```typescript
// 在项目详情组件中
navigateToChatActivation() {
  this.router.navigate([
    '/wxwork', 
    this.cid, 
    'project', 
    this.projectId, 
    'chat-activation'
  ], {
    queryParams: {
      chatId: this.groupChat?.get('chat_id') // 可选：直接指定群聊ID
    }
  });
}
```

### 3. 数据库准备

确保 Parse 数据库中存在以下表和字段：

#### GroupChat 表
```javascript
{
  chat_id: String,          // 企微群聊ID
  name: String,             // 群聊名称
  project: Pointer,         // 关联项目
  company: String,          // 公司ID
  member_list: Array,       // 成员列表
  messages: Array,          // 消息列表
  introSent: Boolean,       // 是否已发送群介绍
  introSentAt: Date,        // 群介绍发送时间
  joinQrcode: Object,       // 入群二维码信息
  joinUrl: Object           // 入群链接信息
}
```

#### Project 表
```javascript
{
  title: String,            // 项目名称
  description: String,      // 项目描述
  contact: Pointer,         // 客户信息
  assignee: Pointer,        // 执行技术
  department: Pointer       // 部门（包含leader）
}
```

#### ContactInfo 表
```javascript
{
  external_userid: String,  // 企微外部联系人ID
  name: String,             // 客户姓名
  mobile: String,           // 手机号
  company: String           // 公司ID
}
```

---

## 📖 功能详解

### 1️⃣ 用户源聊天记录筛选

**功能说明**：
- 点击"客户消息"按钮，自动过滤群内其他成员信息
- 仅显示客户（用户源）的所有历史聊天记录
- 无需手动翻找，提高工作效率

**实现原理**：
```typescript
// 根据 member_list 判断消息发送者是否为客户
const isCustomer = msg.from === customerUserId || 
                   memberList.some((m: any) => 
                     m.type === 2 && m.userid === msg.from
                   );
```

**使用方法**：
1. 进入会话激活页面
2. 在聊天记录卡片中点击"客户消息"筛选按钮
3. 系统自动显示客户的所有消息

---

### 2️⃣ 三种入群方式

#### 方式一：二维码入群
- 点击"查看二维码"按钮
- 弹出二维码图片
- 客户扫码即可加入群聊

#### 方式二：复制链接入群
- 点击"复制链接"按钮
- 系统自动复制入群链接到剪贴板
- 分享链接给客户即可

#### 方式三：手动拉群
- 点击"管理成员"按钮
- 跳转到成员管理页面
- 手动添加客户到群聊

**数据获取**：
```typescript
// 从企微API获取入群方式
const chatInfo = await this.wecorp.externalContact.groupChat.get(this.chatId);
// 保存到数据库
this.groupChat.set('joinQrcode', { qr_code: chatInfo.group_chat.qr_code });
this.groupChat.set('joinUrl', { join_url: chatInfo.group_chat.join_url });
```

---

### 3️⃣ 入群自动化文案

**功能说明**：
- 群创建完成后，系统自动生成项目介绍文案
- 文案包含：项目主管、执行技术、项目需求
- 点击"自动发送群介绍"按钮即可发送

**文案模板**：
```
欢迎加入【项目名称】项目群！

👤 项目主管：XXX
🔧 执行技术：XXX
📋 项目需求：XXX

我们将为您提供专业的服务，有任何问题随时沟通！
```

**实现代码**：
```typescript
// 生成文案
generateIntroTemplate() {
  const leader = this.project.get('department')?.get('leader');
  const assignee = this.project.get('assignee');
  const projectTitle = this.project.get('title') || '项目';
  
  this.introTemplate = `欢迎加入【${projectTitle}】项目群！\n\n` +
                      `👤 项目主管：${leader?.get('name') || '待定'}\n` +
                      `🔧 执行技术：${assignee?.get('name') || '待定'}\n` +
                      `📋 项目需求：${this.project.get('description') || '详见需求文档'}\n\n` +
                      `我们将为您提供专业的服务，有任何问题随时沟通！`;
}

// 发送文案
async sendGroupIntro() {
  await this.wecorp.message.sendText({
    chatid: this.chatId,
    text: { content: this.introTemplate }
  });
  
  // 标记已发送
  this.groupChat.set('introSent', true);
  this.groupChat.set('introSentAt', new Date());
  await this.groupChat.save();
}
```

---

### 4️⃣ 超时未回复提醒

**功能说明**：
- 系统每分钟检查一次未回复的客户消息
- 如果客户消息超过10分钟未回复，自动发送通知
- 通知内容：群名称、客户姓名、消息内容
- 群聊列表页显示红色"未回复"标识

**实现原理**：
```typescript
// 启动定时检查
private startUnreadCheck() {
  this.checkTimer = setInterval(() => {
    this.checkUnreadMessages();
  }, 60 * 1000); // 每分钟检查一次
}

// 检查未回复消息
private async checkUnreadMessages() {
  const unreadMessages = this.messages.filter(m => m.needsReply);
  
  for (const msg of unreadMessages) {
    const timeDiff = Date.now() - msg.time.getTime();
    
    // 10分钟未回复，发送通知
    if (timeDiff >= 10 * 60 * 1000 && timeDiff < 11 * 60 * 1000) {
      await this.sendUnreadNotification(msg);
    }
  }
}

// 发送通知
private async sendUnreadNotification(message: ChatMessage) {
  const groupName = this.groupChat?.get('name') || '项目群';
  const notificationText = `【${groupName}】客户消息已超10分钟未回复，请及时处理！\n\n` +
                          `客户：${message.senderName}\n` +
                          `消息：${message.content}`;
  
  await this.wecorp.message.sendText({
    touser: userId,
    agentid: '1000017',
    text: { content: notificationText }
  });
}
```

**判断逻辑**：
- 消息是客户发送的
- 消息时间超过10分钟
- 后续没有技术人员的回复消息

---

### 5️⃣ 辅助回复功能

**功能说明**：
- 点击未回复消息的"快速回复"按钮
- 系统根据客户消息内容智能生成3-5条备选回复
- 点击任意一条即可直接发送到群聊

**智能匹配规则**：

| 关键词 | 建议回复 |
|--------|----------|
| 需求、要求、想要 | "您说的需求已记录，我会在1小时内反馈详细方案给您。" |
| 进度、什么时候、多久 | "目前项目进度正常，预计本周五前完成，届时会第一时间通知您。" |
| 修改、调整、改 | "收到，我会马上按您的要求进行调整，调整完成后发送给您确认。" |
| 通用 | "好的，我明白了，马上处理。" |

**实现代码**：
```typescript
async generateSuggestedReplies(message: ChatMessage) {
  const content = message.content.toLowerCase();
  this.suggestedReplies = [];
  
  // 根据关键词匹配回复
  if (content.includes('需求') || content.includes('要求')) {
    this.suggestedReplies.push({
      id: '1',
      text: '您说的需求已记录，我会在1小时内反馈详细方案给您。',
      icon: '📝'
    });
  }
  
  if (content.includes('进度') || content.includes('什么时候')) {
    this.suggestedReplies.push({
      id: '2',
      text: '目前项目进度正常，预计本周五前完成，届时会第一时间通知您。',
      icon: '⏰'
    });
  }
  
  // 通用回复
  this.suggestedReplies.push({
    id: '3',
    text: '好的，我明白了，马上处理。',
    icon: '👌'
  });
  
  // 限制最多5条
  this.suggestedReplies = this.suggestedReplies.slice(0, 5);
}

// 发送建议回复
async sendSuggestedReply(reply: SuggestedReply) {
  await this.wecorp.message.sendText({
    chatid: this.chatId,
    text: { content: reply.text }
  });
  
  // 刷新消息列表
  await this.loadChatMessages();
}
```

---

## 📱 移动端适配

### 响应式断点

| 屏幕尺寸 | 布局调整 |
|----------|----------|
| > 768px | 桌面端：三列网格布局 |
| 481px - 768px | 平板端：两列布局 |
| ≤ 480px | 手机端：单列布局 |

### 移动端优化

1. **入群方式卡片**：手机端改为单列垂直排列
2. **筛选按钮**：手机端改为垂直堆叠，按钮宽度100%
3. **消息列表**：手机端消息头部信息垂直排列
4. **辅助回复面板**：手机端从底部弹出，最大高度80vh
5. **触摸优化**：所有按钮最小高度44px，符合iOS触摸规范

### 关键CSS代码

```scss
@media (max-width: 768px) {
  .join-methods-grid {
    grid-template-columns: 1fr !important;
  }
  
  .filter-bar {
    flex-direction: column;
    .filter-btn {
      width: 100%;
    }
  }
}

@media (max-width: 480px) {
  .page-header {
    padding: 12px 16px;
    .page-title {
      font-size: 18px;
    }
  }
  
  .messages-list {
    max-height: 400px;
    .message-item {
      padding: 12px;
    }
  }
}
```

---

## 🔧 技术实现

### 核心依赖

```typescript
import { WxworkSDK, WxworkCorp, WxworkAuth } from 'fmode-ng/core';
import { FmodeParse, FmodeObject } from 'fmode-ng/parse';
```

### 数据流程

```
1. 初始化SDK → WxworkAuth.authenticateAndLogin()
2. 加载项目数据 → Parse.Query('Project').get()
3. 加载群聊数据 → Parse.Query('GroupChat').first()
4. 加载消息列表 → groupChat.get('messages')
5. 筛选客户消息 → 根据member_list判断
6. 检测未回复 → 定时器每分钟检查
7. 发送通知 → wecorp.message.sendText()
```

### 状态管理

```typescript
// 加载状态
loading: boolean = true;
loadingMessages: boolean = false;
sendingIntro: boolean = false;

// 筛选状态
showOnlyCustomer: boolean = false;
showOnlyUnread: boolean = false;

// 统计数据
totalMessages: number = 0;
customerMessageCount: number = 0;
unreadCount: number = 0;
```

---

## 🎨 UI设计规范

### 颜色方案

| 用途 | 颜色值 | 说明 |
|------|--------|------|
| 主色调 | #007aff | iOS蓝色 |
| 成功色 | #34c759 | 绿色 |
| 警告色 | #ff9500 | 橙色 |
| 危险色 | #ff3b30 | 红色 |
| 背景色 | #f5f7fa | 浅灰色 |

### 圆角规范

- 卡片：16px
- 按钮：10-12px
- 小元素：6-8px
- 圆形按钮：50%

### 阴影规范

```scss
// 卡片阴影
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);

// 悬停阴影
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12);

// 按钮阴影
box-shadow: 0 4px 12px rgba(0, 122, 255, 0.3);
```

---

## ⚠️ 注意事项

### 1. 企微环境要求
- 必须在企业微信环境中运行
- 需要正确配置企微应用的agentid
- 确保应用有发送消息的权限

### 2. 数据库配置
- 确保Parse数据库连接正常
- GroupChat表必须包含messages字段
- 消息数据结构需符合企微API返回格式

### 3. 权限控制
- 使用WxAuthGuard保护路由
- 确保用户已登录并授权
- 检查用户是否有操作权限

### 4. 性能优化
- 消息列表限制最大高度，避免渲染过多DOM
- 使用虚拟滚动（可选）处理大量消息
- 定时器在组件销毁时清理

### 5. 错误处理
- 所有API调用都应包含try-catch
- 网络错误时显示友好提示
- 数据加载失败时提供重试机制

---

## 🐛 常见问题

### Q1: 消息列表为空？
**A**: 检查以下几点：
1. GroupChat表是否有messages字段
2. messages数据格式是否正确
3. 企微API是否返回消息数据
4. 网络连接是否正常

### Q2: 入群二维码不显示？
**A**: 
1. 检查企微API是否返回qr_code
2. 确认群聊是否开启了入群验证
3. 二维码可能已过期，需要重新生成

### Q3: 未回复提醒不工作？
**A**:
1. 检查定时器是否正常启动
2. 确认企微应用有发送消息权限
3. 检查agentid配置是否正确

### Q4: 辅助回复发送失败？
**A**:
1. 确认企微应用有群聊发送消息权限
2. 检查chatId是否正确
3. 查看控制台错误日志

---

## 📚 扩展功能建议

### 1. 消息搜索
添加搜索框，支持按关键词搜索历史消息

### 2. 消息导出
支持导出聊天记录为Excel或PDF

### 3. 智能回复升级
接入AI大模型，生成更智能的回复建议

### 4. 数据统计
添加回复率、响应时间等统计图表

### 5. 多群管理
支持同时管理多个项目群聊

---

## 📞 技术支持

如有问题，请联系技术团队或查阅以下文档：
- 企微API文档：https://developer.work.weixin.qq.com/
- fmode-ng文档：内部文档库
- Parse文档：https://docs.parseplatform.org/

---

## 📝 更新日志

### v1.0.0 (2025-11-01)
- ✅ 初始版本发布
- ✅ 实现用户源聊天记录筛选
- ✅ 实现三种入群方式
- ✅ 实现入群自动化文案
- ✅ 实现超时未回复提醒
- ✅ 实现辅助回复功能
- ✅ 完成移动端适配
- ✅ 对接Parse数据库

---

**文档版本**: v1.0.0  
**最后更新**: 2025年11月1日  
**维护者**: 开发团队