# SCRM企业微信渠道活码

**Repository Path**: cxguo1990_admin/wechat-scrm

## Basic Information

- **Project Name**: SCRM企业微信渠道活码
- **Description**: 基于企业微信的渠道活码管理：创建不同渠道的专属二维码。
自动打标签：客户扫码后自动识别来源并打上对应标签。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业微信渠道活码系统

基于 Next.js 开发的企业微信 SCRM 系统，实现渠道活码功能，自动识别客户来源并打标签。

## 扫码可搭建

![输入图片说明](public/%E6%B8%A0%E9%81%93%E7%A0%81%20-%20gitee.png)
## 功能特性

```
这里输入代码
```

- 📱 **渠道活码管理**：创建不同渠道的专属二维码，支持查看和下载
- 🏷️ **标签管理**：创建和管理企业微信标签组和标签，支持编辑和删除
- 🤖 **自动打标签**：客户扫码后自动识别来源并打上对应标签
- 👥 **客户管理**：查看客户列表，支持手动同步客户信息和标签
- 📊 **数据统计**：查看各渠道的客户数量和统计数据
- 🔄 **实时回调**：接收企业微信事件回调，实时处理客户添加
- 🔐 **权限验证**：密码登录保护系统，防止未授权访问

## 技术栈

- **前端框架**: Next.js 15 (App Router)
- **UI 组件**: shadcn/ui + Radix UI + Tailwind CSS
- **状态管理**: React Hooks
- **通知组件**: Sonner (Toast)
- **数据库**: SQLite/MySQL + Prisma ORM
- **API 集成**: 企业微信 API
- **部署**: PM2 + Nginx

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填写配置：

```bash
cp .env.example .env
```

配置说明：

```env
# 数据库配置（开发环境使用 SQLite，生产环境可使用 MySQL）
DATABASE_URL="file:./dev.db"
# 或使用 MySQL
# DATABASE_URL="mysql://username:password@localhost:3306/wechat_scrm"

# 企业微信配置
WECHAT_CORP_ID="你的企业ID"
WECHAT_CORP_SECRET="你的应用Secret"
WECHAT_AGENT_ID="你的应用AgentId"

# 回调配置
WECHAT_TOKEN="自定义Token"
WECHAT_ENCODING_AES_KEY="企业微信生成的EncodingAESKey"

# 应用配置
NEXT_PUBLIC_API_URL="http://localhost:3000"

# 管理员密码（用于登录系统）
ADMIN_PASSWORD="your_password"

# 演示模式（可选，设置为 true 可在没有真实企业微信配置时测试功能）
WECHAT_DEMO_MODE="false"
```

### 3. 初始化数据库

```bash
npx prisma generate
npx prisma db push
```

### 4. 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000

### 5. 登录系统

使用 `.env` 中配置的 `ADMIN_PASSWORD` 登录系统。

## 企业微信配置

### 1. 创建应用

1. 登录企业微信管理后台
2. 进入"应用管理" -> "自建应用"
3. 创建新应用，获取 AgentId 和 Secret

### 2. 配置 API 权限

在应用详情页面，配置以下权限：

- 客户联系 - 客户基础信息
- 客户联系 - 客户标签
- 客户联系 - 联系我

### 3. 配置回调 URL

1. 在应用详情页面，点击"接收消息"
2. 设置回调 URL: `https://your-domain.com/api/wechat/callback`
3. 填写 Token 和 EncodingAESKey（需要与 .env 中配置一致）
4. 保存配置

### 4. 配置可信域名

在应用详情页面，配置"网页授权及JS-SDK"可信域名。

## 使用说明

### 1. 标签管理

在"标签管理"页面可以：
- 创建新的标签组和标签
- 编辑标签组中的标签（添加、修改、删除）
- 删除整个标签组
- 同步企业微信标签到本地

**注意**：只能编辑由本应用创建的标签，企业微信后台或其他应用创建的标签无法编辑（会提示权限错误）。

### 2. 创建渠道活码

1. 访问"渠道管理"页面
2. 点击"创建渠道"按钮
3. 填写渠道名称、描述
4. 选择要自动打的标签（可选）
5. 点击创建，系统自动生成二维码

### 3. 查看和下载二维码

在渠道列表中，点击"查看二维码"按钮，可以：
- 查看二维码图片
- 点击"下载二维码"按钮保存图片（文件名为渠道名称）

### 4. 客户管理

在"客户管理"页面可以：
- 查看所有客户列表
- 按渠道筛选客户
- 手动同步单个客户的信息和标签
- 查看客户的标签信息

### 5. 客户添加流程

1. 客户扫描渠道二维码
2. 添加企业微信好友
3. 系统自动接收回调通知
4. 识别客户来源渠道
5. 自动为客户打上对应标签
6. 记录客户信息到数据库

## 数据库结构

### channels（渠道表）

- id: 渠道ID
- name: 渠道名称
- state: 唯一标识（用于识别来源）
- qr_code_url: 二维码图片URL
- config_id: 企业微信配置ID
- tag_ids: 标签ID列表（JSON）
- description: 渠道描述
- is_active: 是否启用

### customers（客户表）

- id: 客户ID
- external_user_id: 企业微信外部联系人ID
- name: 客户名称
- avatar: 头像URL
- channel_id: 来源渠道ID
- tags: 标签列表（JSON）
- wechat_tags: 企业微信标签ID列表（JSON）
- add_time: 添加时间

### corp_tags（企业标签表）

- id: 标签ID
- tag_id: 企业微信标签ID
- name: 标签名称
- group_id: 所属标签组ID
- group_name: 标签组名称
- order: 排序
- created_at: 创建时间

### wechat_config（企业微信配置表）

- corp_id: 企业ID
- corp_secret: 应用Secret
- agent_id: 应用AgentId
- token: 回调Token
- encoding_aes_key: 回调加密Key

## API 接口

### 认证

- `POST /api/auth/login` - 登录
- `POST /api/auth/logout` - 登出
- `GET /api/auth/check` - 检查登录状态

### 渠道管理

- `GET /api/channels` - 获取渠道列表
- `POST /api/channels` - 创建渠道
- `GET /api/channels/[id]` - 获取渠道详情
- `DELETE /api/channels/[id]` - 删除渠道

### 客户管理

- `GET /api/customers` - 获取客户列表
- `GET /api/customers?channelId=xxx` - 获取指定渠道的客户
- `POST /api/customers/sync` - 同步单个客户信息

### 标签管理

- `GET /api/tags` - 获取标签列表
- `POST /api/tags` - 创建标签组
- `PUT /api/tags` - 编辑标签组
- `DELETE /api/tags` - 删除标签组
- `POST /api/tags/sync` - 同步企业微信标签

### 企业微信

- `GET /api/wechat/tags` - 获取企业微信标签列表
- `POST /api/wechat/callback` - 接收企业微信回调

## 部署

### 使用 PM2 部署

1. 安装 PM2

```bash
npm install -g pm2
```

2. 构建项目

```bash
npm run build
```

3. 使用 PM2 启动

```bash
pm2 start npm --name "wechat-scrm" -- start
```

4. 设置开机自启

```bash
pm2 startup
pm2 save
```

### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 禁用缓存，确保更新后立即生效
        proxy_cache off;
        proxy_no_cache 1;
        proxy_cache_bypass 1;
    }
}
```

## 注意事项

1. 确保服务器有公网 IP 或使用内网穿透工具（如 ngrok）
2. 回调 URL 必须使用 HTTPS（开发环境可使用 HTTP）
3. 企业微信 access_token 有效期为 7200 秒，系统会自动缓存和刷新
4. 标签需要在企业微信后台预先创建，或通过系统的"标签管理"功能创建
5. 只能编辑由本应用创建的标签，其他应用或后台创建的标签无法编辑
6. 建议定期备份数据库
7. 修改代码后需要重新构建并重启服务（`npm run build && pm2 restart wechat-scrm`）
8. 如使用 Nginx 代理，建议禁用缓存以确保更新立即生效

## 常见问题

### 1. 登录后没有跳转？

- 检查浏览器是否禁用了 Cookie
- 确认 HTTPS 环境下 Cookie 的 secure 属性设置正确
- 尝试清除浏览器缓存和 Cookie 后重新登录

### 2. 回调接收不到？

- 检查回调 URL 是否正确配置
- 确认服务器防火墙已开放端口
- 查看企业微信后台的回调日志

### 3. 标签打不上？

- 确认应用有"客户标签"权限
- 检查标签 ID 是否正确
- 查看服务器日志排查错误

### 4. 标签无法编辑？

- 只能编辑由本应用创建的标签
- 企业微信后台或其他应用创建的标签会提示"无权限"错误
- 建议通过系统的"标签管理"功能创建标签

### 5. 二维码生成失败？

- 检查企业微信配置是否正确
- 确认应用有"联系我"权限
- 查看 access_token 是否过期

### 6. 部署后更新不生效？

- 检查 Nginx 是否启用了缓存
- 确认已重新构建项目（`npm run build`）
- 重启 PM2 服务（`pm2 restart wechat-scrm`）
- 清除浏览器缓存

## License

MIT