xianyu-auto-reply/自动发货功能说明.md

# 🚚 自动发货功能使用说明

## 📋 功能概述

自动发货功能可以在买家付款成功后，根据商品信息自动匹配发货规则，并发送对应的卡券内容给买家。

## 🎯 工作流程

### 1. 触发条件
- 系统收到"等待卖家发货"消息时自动触发
- 表示买家已完成付款，等待卖家发货

### 2. 商品信息获取
```
买家付款成功 → 提取商品ID → 调用闲鱼API → 获取商品详情
```

**获取的信息包括：**
- 商品标题
- 商品描述
- 商品分类
- 商品价格
- 其他相关信息

### 3. 智能匹配规则
```
商品信息 → 组合搜索文本 → 匹配发货规则 → 选择最佳规则
```

**匹配策略：**
- 优先匹配关键字长度较长的规则（更精确）
- 支持商品标题、描述、分类的综合匹配
- 支持模糊匹配和部分匹配

### 4. 自动发货执行
```
匹配规则 → 获取卡券内容 → 发送给买家 → 更新统计
```

## 🎫 卡券类型说明

### 1. API接口类型
**适用场景：** 需要动态获取内容的卡券
- 调用外部API获取实时数据
- 支持GET/POST请求
- 可配置请求头和参数
- 自动处理API响应

**配置示例：**
```json
{
  "url": "https://api.example.com/get-card",
  "method": "GET",
  "timeout": 10,
  "headers": "{\"Authorization\": \"Bearer token\"}",
  "params": "{\"type\": \"recharge\", \"amount\": 100}"
}
```

### 2. 固定文字类型
**适用场景：** 标准化的文字内容
- 发送预设的固定文字
- 适合使用说明、激活码等
- 内容固定不变

**内容示例：**
```
🎉 恭喜您获得VIP会员卡！

会员卡号：VIP2024001
有效期：2024年12月31日

专属权益：
✅ 免费配送
✅ 专属客服
✅ 会员折扣

感谢您的支持！
```

### 3. 批量数据类型
**适用场景：** 唯一性数据，如卡密
- 逐条消费预设数据
- 线程安全，防止重复发送
- 自动管理库存

**数据格式：**
```
CARD001:PASS001
CARD002:PASS002
CARD003:PASS003
```

## ⚙️ 配置步骤

### 1. 创建卡券
1. 登录管理界面
2. 点击"卡券管理"菜单
3. 点击"添加卡券"按钮
4. 选择卡券类型并配置相应参数
5. 启用卡券

### 2. 配置发货规则
1. 点击"自动发货"菜单
2. 点击"添加规则"按钮
3. 设置商品关键字
4. 选择对应的卡券
5. 设置发货数量
6. 启用规则

### 3. 关键字配置建议

**商品分类关键字：**
- `手机` - 匹配手机类商品
- `数码` - 匹配数码产品
- `服装` - 匹配服装类商品
- `鞋子` - 匹配鞋类商品
- `家居` - 匹配家居用品

**品牌关键字：**
- `iPhone` - 匹配iPhone商品
- `小米` - 匹配小米商品
- `华为` - 匹配华为商品

**功能关键字：**
- `充值` - 匹配充值类商品
- `会员` - 匹配会员服务
- `游戏` - 匹配游戏相关商品

## 📊 统计功能

### 发货统计
- 总发货次数
- 各规则发货次数
- 发货成功率
- 卡券消耗情况

### 库存管理
- 批量数据剩余数量
- 卡券启用状态
- 规则启用状态

## 🔧 高级配置

### 环境变量
```bash
# 启用自动发货
AUTO_DELIVERY_ENABLED=true

# 自动发货超时时间
AUTO_DELIVERY_TIMEOUT=30

# API卡券请求超时
API_CARD_TIMEOUT=10

# 批量数据并发保护
BATCH_DATA_LOCK_TIMEOUT=5
```

### 日志配置
系统会记录详细的发货日志：
- 商品信息获取日志
- 规则匹配日志
- 发货执行日志
- 错误处理日志

## 🚨 注意事项

### 1. 商品ID提取
- 系统会尝试从多个字段提取商品ID
- 如果提取失败，会使用默认ID
- 建议检查日志确认提取是否成功

### 2. API卡券配置
- 确保API地址可访问
- 检查请求头和参数格式
- 设置合适的超时时间
- 处理API异常情况

### 3. 批量数据管理
- 定期检查数据库存
- 及时补充批量数据
- 监控消耗速度
- 设置库存预警

### 4. 规则优先级
- 关键字越长，优先级越高
- 避免关键字冲突
- 定期优化匹配规则
- 测试匹配效果

## 🧪 测试方法

### 1. 功能测试
```bash
python test-item-info-delivery.py
```

### 2. 手动测试
1. 创建测试卡券和规则
2. 模拟"等待卖家发货"消息
3. 检查发货是否正常
4. 验证统计数据更新

### 3. 日志检查
查看日志文件确认：
- 商品信息获取是否成功
- 规则匹配是否正确
- 发货内容是否正确发送

## 🔍 故障排除

### 常见问题

**1. 未触发自动发货**
- 检查发货规则是否启用
- 检查卡券是否启用
- 检查关键字是否匹配
- 查看错误日志

**2. 商品信息获取失败**
- 检查Cookie是否有效
- 检查网络连接
- 检查商品ID是否正确
- 查看API调用日志

**3. 批量数据用完**
- 检查数据库存
- 及时补充数据
- 考虑使用其他类型卡券

**4. API卡券调用失败**
- 检查API地址和参数
- 检查网络连接
- 增加超时时间
- 查看API响应日志

## 📈 性能优化

### 1. 数据库优化
- 定期清理过期数据
- 优化查询索引
- 监控数据库性能

### 2. 网络优化
- 设置合适的超时时间
- 使用连接池
- 实现重试机制

### 3. 并发控制
- 批量数据消费使用锁机制
- 避免重复发货
- 控制并发数量

## 💡 最佳实践

1. **规则设计**：关键字要具体明确，避免过于宽泛
2. **库存管理**：定期检查批量数据库存，及时补充
3. **监控告警**：设置发货失败告警，及时处理异常
4. **测试验证**：新规则上线前充分测试
5. **日志分析**：定期分析发货日志，优化匹配规则

---

🎉 **自动发货功能让您的闲鱼店铺实现真正的自动化运营！**