chat/README.md

# Sales Chat Plugin for Tailchat

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

## 功能特性

✅ **邀请追踪**
- 创建邀请链接
- 生成二维码
- 点击/扫码/加入统计
- 邀请码管理

✅ **数据统计**
- 个人业绩统计
- 团队排行榜
- 趋势分析
- 转化率追踪

✅ **管理功能**
- 用户管理
- 群组管理
- 踢人/销户
- 权限控制

## 快速开始

### 1. 环境要求

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

### 2. 安装依赖

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

### 3. 配置环境变量

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

# 编辑配置
vim server/.env
```

关键配置：
```env
MONGO_URL=mongodb://localhost:27017/tailchat
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key
INVITE_BASE_URL=http://localhost:11000
```

### 4. 启动开发环境

```bash
# 启动 Tailchat
cd server
pnpm dev
```

### 5. 运行测试

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

## API 文档

### 邀请管理

#### 创建邀请
```http
POST /api/plugin/com.msgbyte.saleschat/invite/create
Authorization: Bearer <token>
Content-Type: application/json

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

#### 获取我的邀请列表
```http
GET /api/plugin/com.msgbyte.saleschat/invite/my
Authorization: Bearer <token>
```

#### 获取邀请详情
```http
GET /api/plugin/com.msgbyte.saleschat/invite/:code
```

#### 获取邀请统计
```http
GET /api/plugin/com.msgbyte.saleschat/invite/:code/stats
Authorization: Bearer <token>
```

#### 停用邀请
```http
POST /api/plugin/com.msgbyte.saleschat/invite/:code/deactivate
Authorization: Bearer <token>
```

#### 通过邀请加入
```http
POST /api/plugin/com.msgbyte.saleschat/invite/join
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "invite-code"
}
```

### 数据统计

#### 获取我的统计
```http
GET /api/plugin/com.msgbyte.saleschat/stats/my
Authorization: Bearer <token>
```

#### 获取团队统计
```http
GET /api/plugin/com.msgbyte.saleschat/stats/team
Authorization: Bearer <token>
```

#### 获取排行榜
```http
GET /api/plugin/com.msgbyte.saleschat/stats/ranking
Authorization: Bearer <token>
```

### 管理功能

#### 踢出用户
```http
POST /api/plugin/com.msgbyte.saleschat/admin/kick
Authorization: Bearer <admin-token>
Content-Type: application/json

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

#### 删除用户
```http
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（邀请表）
```javascript
{
  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（统计表）
```javascript
{
  salesId: ObjectId,      // 销售ID
  date: Date,             // 日期
  period: String,         // 周期：daily/weekly/monthly
  invitesCreated: Number, // 创建邀请数
  joins: Number,          // 加入数
  conversions: Number,    // 转化数
  revenue: Number         // 收入
}
```

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

## 部署

### Docker 部署

```bash
# 构建镜像
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. **导出数据**
```bash
# 从原项目导出数据
cd /Users/sion/Desktop/projects/sales-chat/backend
node scripts/export-data.js > data-export.json
```

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

3. **更新前端配置**
```bash
# 修改 API 路径
# /api/invite/* → /api/plugin/com.msgbyte.saleschat/invite/*
# /api/stats/* → /api/plugin/com.msgbyte.saleschat/stats/*
```

4. **下线旧服务**
```bash
# 停止独立服务
pm2 stop sales-chat-backend

# 启动 Tailchat
docker-compose up -d
```

## 客户端

### Flutter 移动端

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

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

# 安装依赖
flutter pub get

# 运行应用
flutter run

# 构建 APK
flutter build apk
```

详见: [client/flutter/README.md](client/flutter/README.md)

### Tailchat Web

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

```bash
# 启动 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