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. **定期更新**：根据商品变化及时更新匹配规则

### 库存管理策略
1. **实时监控**：定期检查批量数据库存状态
2. **预警机制**：设置库存低于阈值时的告警
3. **自动补充**：配置自动补充机制或定期手动补充
4. **分批管理**：将卡券分批次管理，避免一次性消耗完

### 质量控制措施
1. **测试验证**：新规则上线前在测试环境充分测试
2. **灰度发布**：新规则先在部分商品上试运行
3. **监控告警**：设置发货失败率告警，及时处理异常
4. **人工审核**：重要商品可设置人工审核环节

### 数据分析优化
1. **日志分析**：定期分析发货日志，识别问题模式
2. **成功率统计**：监控各规则的匹配成功率
3. **用户反馈**：收集买家反馈，优化发货内容
4. **性能监控**：监控发货响应时间，优化处理流程

## 🔧 故障排除

### 常见问题及解决方案

**问题1：发货规则不匹配**
- 检查关键字是否正确
- 确认商品信息是否完整
- 验证匹配逻辑是否合理
- 查看详细的匹配日志

**问题2：API接口调用失败**
- 检查API地址是否正确
- 验证请求参数和格式
- 确认网络连接状态
- 查看API服务状态

**问题3：批量数据消耗过快**
- 检查匹配规则是否过于宽泛
- 确认是否有重复发货
- 调整匹配策略
- 增加库存补充频率

**问题4：发货消息发送失败**
- 检查账号连接状态
- 验证消息格式是否正确
- 确认网络连接稳定
- 查看WebSocket连接日志

### 调试技巧
1. **开启详细日志**：在配置中开启DEBUG级别日志
2. **单步测试**：使用测试功能验证单个规则
3. **模拟环境**：在测试环境模拟真实场景
4. **监控面板**：使用系统监控面板查看实时状态

## 📈 性能优化

### 系统性能优化
1. **缓存机制**：缓存商品信息，减少API调用
2. **异步处理**：使用异步处理提高并发能力
3. **连接池**：优化数据库连接池配置
4. **资源限制**：合理设置系统资源限制

### 业务流程优化
1. **规则优化**：优化匹配算法，提高匹配效率
2. **批量处理**：支持批量发货操作
3. **智能调度**：根据系统负载智能调度任务
4. **预处理**：预处理商品信息，提高匹配速度

## 🔐 安全考虑

### 数据安全
1. **敏感信息加密**：卡券内容加密存储
2. **访问控制**：严格的权限控制机制
3. **审计日志**：完整的操作审计日志
4. **备份恢复**：定期备份重要数据

### 业务安全
1. **防重复发货**：严格的重复发货检测
2. **异常监控**：实时监控异常发货行为
3. **人工干预**：支持紧急情况下的人工干预
4. **风险控制**：设置发货频率和数量限制

---

🎉 **自动发货功能让您的闲鱼店铺实现真正的自动化运营！通过合理配置和优化，可以大大提高运营效率和用户体验。**