Sales Chat Plugin for Tailchat

销售邀请追踪系统 - Tailchat 官方插件

功能特性

✅ 邀请追踪

• 创建邀请链接
• 生成二维码
• 点击/扫码/加入统计
• 邀请码管理

✅ 数据统计

• 个人业绩统计
• 团队排行榜
• 趋势分析
• 转化率追踪

✅ 管理功能

• 用户管理
• 群组管理
• 踢人/销户
• 权限控制

快速开始

1. 环境要求

• Node.js >= 18
• MongoDB >= 6
• Redis >= 6
• pnpm >= 8

2. 安装依赖

cd /Users/sion/Desktop/projects/tailchat-sales
pnpm install

3. 配置环境变量

# 复制配置文件
cp server/.env.example server/.env

# 编辑配置
vim server/.env

关键配置：

MONGO_URL=mongodb://localhost:27017/tailchat
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
INVITE_BASE_URL=http://localhost:11000

4. 启动开发环境

# 启动 Tailchat
cd server
pnpm dev

5. 运行测试

# 运行集成测试
./tests/integration_test.sh

API 文档

邀请管理

创建邀请

POST /api/plugin/com.msgbyte.saleschat/invite/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "groupId": "group-id",
  "expiresIn": 7
}

获取我的邀请列表

GET /api/plugin/com.msgbyte.saleschat/invite/my
Authorization: Bearer <token>

获取邀请详情

GET /api/plugin/com.msgbyte.saleschat/invite/:code

获取邀请统计

GET /api/plugin/com.msgbyte.saleschat/invite/:code/stats
Authorization: Bearer <token>

停用邀请

POST /api/plugin/com.msgbyte.saleschat/invite/:code/deactivate
Authorization: Bearer <token>

通过邀请加入

POST /api/plugin/com.msgbyte.saleschat/invite/join
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "invite-code"
}

数据统计

获取我的统计

GET /api/plugin/com.msgbyte.saleschat/stats/my
Authorization: Bearer <token>

获取团队统计

GET /api/plugin/com.msgbyte.saleschat/stats/team
Authorization: Bearer <token>

获取排行榜

GET /api/plugin/com.msgbyte.saleschat/stats/ranking
Authorization: Bearer <token>

管理功能

踢出用户

POST /api/plugin/com.msgbyte.saleschat/admin/kick
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "groupId": "group-id",
  "userId": "user-id",
  "reason": "违规操作"
}

删除用户

POST /api/plugin/com.msgbyte.saleschat/admin/delete
Authorization: Bearer <super-admin-token>
Content-Type: application/json

{
  "userId": "user-id",
  "type": "soft",
  "reason": "违规操作"
}

数据库结构

sales_invites（邀请表）

{
  code: String,           // 邀请码
  salesId: ObjectId,      // 销售ID
  groupId: ObjectId,      // 群组ID
  link: String,           // 邀请链接
  qrCodeUrl: String,      // 二维码URL
  createdAt: Date,        // 创建时间
  expiresAt: Date,        // 过期时间
  clickCount: Number,     // 点击次数
  scanCount: Number,      // 扫码次数
  joinCount: Number,      // 加入次数
  status: String          // 状态
}

sales_stats（统计表）

{
  salesId: ObjectId,      // 销售ID
  date: Date,             // 日期
  period: String,         // 周期：daily/weekly/monthly
  invitesCreated: Number, // 创建邀请数
  joins: Number,          // 加入数
  conversions: Number,    // 转化数
  revenue: Number         // 收入
}

access_logs（访问日志）

{
  inviteCode: String,     // 邀请码
  visitorId: String,      // 访客ID
  accessType: String,     // 访问类型：click/scan/join
  timestamp: Date,        // 时间戳
  ipAddress: String,      // IP地址
  userAgent: String       // User Agent
}

部署

Docker 部署

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f tailchat

# 停止服务
docker-compose down

环境变量

变量名	说明	默认值
MONGO_URL	MongoDB 连接串	mongodb://localhost:27017/tailchat
REDIS_URL	Redis 连接串	redis://localhost:6379
JWT_SECRET	JWT 密钥	-
INVITE_BASE_URL	邀请基础URL	http://localhost:11000
ADMIN_USERNAME	管理员用户名	admin
ADMIN_PASSWORD	管理员密码	admin123

迁移指南

从独立服务迁移

1. 导出数据

# 从原项目导出数据
cd /Users/sion/Desktop/projects/sales-chat/backend
node scripts/export-data.js > data-export.json

2. 导入数据

# 导入到 Tailchat 数据库
cd /Users/sion/Desktop/projects/tailchat-sales/server
node scripts/import-data.js data-export.json

3. 更新前端配置

# 修改 API 路径
# /api/invite/* → /api/plugin/com.msgbyte.saleschat/invite/*
# /api/stats/* → /api/plugin/com.msgbyte.saleschat/stats/*

4. 下线旧服务

# 停止独立服务
pm2 stop sales-chat-backend

# 启动 Tailchat
docker-compose up -d

客户端

Flutter 移动端

独立的 Flutter 应用，支持 iOS / Android / Web。

# 进入 Flutter 客户端目录
cd client/flutter

# 安装依赖
flutter pub get

# 运行应用
flutter run

# 构建 APK
flutter build apk

详见: client/flutter/README.md

Tailchat Web

集成在 Tailchat Web 中的插件界面。

# 启动 Tailchat Web 开发环境
cd client/web
pnpm dev

开发

项目结构

tailchat-sales/
├── server/                              # 后端服务
│   └── plugins/com.msgbyte.saleschat/   # 销售聊天插件
│       ├── package.json
│       ├── services/
│       │   ├── index.ts
│       │   ├── invite.service.ts
│       │   ├── stats.service.ts
│       │   └── admin.service.ts
│       ├── models/
│       └── test/
├── client/                              # 客户端
│   ├── flutter/                         # Flutter 独立应用 ⭐
│   │   ├── lib/
│   │   ├── android/
│   │   ├── ios/
│   │   └── web/
│   ├── web/                             # Tailchat Web
│   ├── mobile/                          # Tailchat Mobile (RN)
│   └── desktop/                         # Tailchat Desktop
└── tests/                               # 集成测试

添加新功能

1. 在 services/ 创建新服务
2. 在 models/ 创建数据模型
3. 在 services/index.ts 注册服务
4. 编写测试

故障排除

插件加载失败

• 检查 package.json 依赖
• 验证服务名称格式
• 查看 Tailchat 日志

API 404 错误

• 确认插件已加载
• 检查路由注册
• 验证权限配置

数据库连接失败

• 检查 MongoDB 运行状态
• 验证连接字符串
• 检查网络配置

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT

联系方式

• 原项目: /Users/sion/Desktop/projects/sales-chat/
• Tailchat: https://github.com/msgbyte/tailchat
• 文档: https://tailchat.msgbyte.com