# 企业微信外部客户引流与识别系统 PRD

## 需求概述

实现一个基于企业微信的外部客户引流与识别系统，根据用户与企业的关系状态（是否已添加为外部联系人），引导用户进入不同的业务流程。

## 核心需求点

1. 用户的入口(二维码) 二维码是哪里生成的? 需要带什么参数?
2. 用户扫码后, 判断当前用户是否已添加该企业微信的外部用户
3. 如果是该企业的外部客户, 跳转到该企业的具体应用页面, 如果不是该企业的外部客户则生成添加企业的二维码页面(这里的逻辑该如何处理)

## 技术方案

### 1. 二维码生成方案

#### 1.1 使用企业微信「联系我」接口

api doc: [客户联系「联系我」管理](https://developer.work.weixin.qq.com/document/path/92228)

**接口地址**: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_contact_way`

**推荐配置**（临时会话模式）:
```javascript
{
  type: 1,                      // 单人联系
  scene: 2,                     // 通过二维码联系
  user: ["service_staff_id"],   // 接待人员UserID
  is_temp: true,                // 开启临时会话
  expires_in: 86400,            // 二维码有效期（秒）
  chat_expires_in: 86400,       // 会话有效期（秒）
  state: "channel_source_001",  // 渠道标识参数
  skip_verify: true,            // 无需验证直接添加
  conclusions: {
    text: {
      content: "感谢咨询，如需长期服务请添加我们"
    }
  }
}
```

| 参数            | 必须 | 说明                                                                                                   |
| --------------- | ---- | ------------------------------------------------------------------------------------------------------ |
| access_token    | 是   | 调用接口凭证                                                                                           |
| type            | 是   | 联系方式类型，1-单人，2-多人                                                                           |
| scene           | 是   | 场景，1-在小程序中联系，2-通过二维码联系                                                               |
| style           | 否   | 在小程序中联系时使用的控件样式，详见附表                                                               |
| remark          | 否   | 联系方式的备注信息，用于助记，不超过30个字符                                                           |
| skip_verify     | 否   | 外部客户添加时是否无需验证，默认为true                                                                 |
| state           | 否   | 企业自定义的state参数，用于区分不同的添加渠道，在调用"获取客户详情"时会返回该参数值，不超过30个字符    |
| user            | 否   | 使用该联系方式的用户userID列表，在type为1时为必填，且只能有一个                                        |
| party           | 否   | 使用该联系方式的部门id列表，只在type为2时有效                                                          |
| is_temp         | 否   | 是否临时会话模式，true表示使用临时会话模式，默认为false                                                |
| expires_in      | 否   | 临时会话二维码有效期，以秒为单位。该参数仅在is_temp为true时有效，默认7天，最多为14天                   |
| chat_expires_in | 否   | 临时会话有效期，以秒为单位。该参数仅在is_temp为true时有效，默认为添加好友后24小时，最多为14天          |
| unionid         | 否   | 可进行临时会话的客户unionid，该参数仅在is_temp为true时有效，如不指定则不进行限制                       |
| is_exclusive    | 否   | 是否开启同一外部企业客户只能添加同一个员工，默认为否，开启后，同一个企业的客户会优先添加到同一个跟进人 |
| mark_source     | 否   | 是否标记客户添加来源为该应用创建的「联系我」，默认为true；仅对「营销获客」应用生效                     |
| conclusions     | 否   | 结束语，会话结束时自动发送给客户，可参考"结束语定义"，仅在is_temp为true时有效                          |

**关键参数说明**:
- `state`: 自定义状态参数，用于识别不同引流渠道，建议格式：`channel_{渠道ID}_{场景ID}`
- `is_temp`: 临时会话模式，不占用企业「联系我」配额，适合首次接触
- `user`: 指定接待人员，可以是固定客服或根据业务规则分配

#### 1.2 二维码参数设计

**必需参数**:
- `state`: 渠道标识（如：`channel_website_homepage`）
- `user`: 接待人员ID（可配置轮询规则）

**可选参数**:
- `expires_in`: 二维码有效期（建议7天内）
- `chat_expires_in`: 会话有效期（建议24小时）
- `conclusions`: 会话结束语（引导正式添加）

### 2. 客户识别与分流逻辑

#### 2.1 客户状态判断流程

```javascript
// 用户扫码后的处理流程
async function handleCustomerScan(qrCodeState, externalUserId) {
  // Step 1: 解析渠道信息
  const channelInfo = parseChannelState(qrCodeState);
  
  // Step 2: 获取客户详情
  const customerDetail = await getExternalContactDetail(externalUserId);
  
  // Step 3: 判断客户状态
  if (customerDetail.external_contact) {
    // 已是外部客户 -> 跳转应用
    return {
      action: "redirect_to_app",
      url: `https://your-app.com/dashboard?channel=${channelInfo.source}&user=${externalUserId}`
    };
  } else {
    // 非外部客户 -> 生成添加二维码
    const addContactWay = await generatePermanentContactWay(channelInfo);
    return {
      action: "show_add_qrcode",
      qrCode: addContactWay.qr_code,
      message: "请添加我们以获得完整服务",
      expiresIn: addContactWay.expires_in
    };
  }
}
```

#### 2.2 相关接口

**获取客户详情**:
- 接口: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get`
- 参数: `external_userid`（从扫码回调中获取）
- 返回: 客户基本信息、添加状态、标签等

**批量获取客户详情**:
- 接口: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user`
- 用于验证客户是否已添加

### 3. 分流处理方案

#### 3.1 已添加客户流程

1. **触发条件**: 客户已在企业外部联系人列表中
2. **处理动作**:
   - 直接跳转到企业应用页面
   - 传递客户标识和渠道参数
   - 可根据客户标签进行个性化页面展示
3. **示例URL**: `https://app.yourcompany.com/home?external_userid=xxx&source=channel_001`

#### 3.2 未添加客户流程

1. **触发条件**: 客户不在企业外部联系人列表中
2. **处理动作**:
   - 生成永久「联系我」二维码（非临时会话）
   - 展示引导页面，说明添加后的服务内容
   - 记录引流渠道，用于后续数据分析
3. **二维码配置**:
```javascript
{
  type: 1,
  scene: 2,
  user: ["service_staff_id"],
  is_temp: false,              // 永久添加
  state: "permanent_add_xxx",  // 记录来源
  skip_verify: true,
  remark: "官网引流转化"
}
```

### 4. 接口调用流程

#### 4.1 初始化阶段

1. 调用 `add_contact_way` 接口生成引流二维码
2. 保存返回的 `config_id` 和 `qr_code` URL
3. 将二维码部署到各引流渠道

#### 4.2 用户扫码阶段

1. 用户扫码后，企业微信推送事件到回调URL
2. 回调事件包含 `external_userid` 和 `state` 参数
3. 后端接收事件，调用 `get_external_contact` 获取客户详情
4. 根据客户状态执行分流逻辑

#### 4.3 事件回调处理

**回调事件类型**:
- `change_external_contact`: 外部联系人变更事件
- `add_external_contact`: 添加外部联系人事件
- `del_external_contact`: 删除外部联系人事件

**关键参数**:
- `UserID`: 接待人员的企业微信ID
- `ExternalUserID`: 外部联系人ID
- `State`: 二维码中的state参数