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

🚚 自动发货功能使用说明

📋 功能概述

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

🎯 工作流程

1. 触发条件

• 系统收到"等待卖家发货"消息时自动触发
• 表示买家已完成付款，等待卖家发货

2. 商品信息获取

买家付款成功 → 提取商品ID → 调用闲鱼API → 获取商品详情

获取的信息包括：

• 商品标题
• 商品描述
• 商品分类
• 商品价格
• 其他相关信息

3. 智能匹配规则

商品信息 → 组合搜索文本 → 匹配发货规则 → 选择最佳规则

匹配策略：

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

4. 自动发货执行

匹配规则 → 获取卡券内容 → 发送给买家 → 更新统计

🎫 卡券类型说明

1. API接口类型

适用场景： 需要动态获取内容的卡券

• 调用外部API获取实时数据
• 支持GET/POST请求
• 可配置请求头和参数
• 自动处理API响应

配置示例：

{
  "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商品
• 小米 - 匹配小米商品
• 华为 - 匹配华为商品

功能关键字：

• 充值 - 匹配充值类商品
• 会员 - 匹配会员服务
• 游戏 - 匹配游戏相关商品

📊 统计功能

发货统计

• 总发货次数
• 各规则发货次数
• 发货成功率
• 卡券消耗情况

库存管理

• 批量数据剩余数量
• 卡券启用状态
• 规则启用状态

🔧 高级配置

环境变量

# 启用自动发货
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. 功能测试

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. 风险控制：设置发货频率和数量限制

---

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