xianyu-auto-reply/商品管理功能说明.md

🛍️ 商品管理功能使用说明

📋 功能概述

新增的商品管理功能可以自动收集和管理各个闲鱼账号的商品信息，为自动发货提供更准确的商品数据支持。

🎯 核心特性

1. 自动商品信息收集

• 消息触发收集：接收消息时自动提取商品ID并保存到数据库
• API获取详情：通过闲鱼API获取完整商品信息
• 智能去重：商品ID唯一，避免重复存储
• 增量更新：有详情的商品不会被空数据覆盖

2. 多账号商品管理

• 账号隔离：每个Cookie账号的商品信息独立管理
• 批量查看：支持查看所有账号或指定账号的商品
• 筛选功能：可按账号ID筛选商品列表

3. 商品详情编辑

• 可视化编辑：提供专门的编辑界面修改商品详情
• JSON格式：支持复杂的商品信息结构
• 实时保存：修改后立即保存到数据库

4. 自动发货增强

• 优先级策略：优先使用API获取商品信息，失败时从数据库获取
• 智能匹配：基于商品标题、描述、分类进行关键词匹配
• 容错机制：API失败时自动降级到数据库数据

🗄️ 数据库结构

商品信息表 (item_info)

CREATE TABLE item_info (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    cookie_id TEXT NOT NULL,              -- 所属账号ID
    item_id TEXT NOT NULL,                -- 商品ID
    item_title TEXT,                      -- 商品标题
    item_description TEXT,                -- 商品描述
    item_category TEXT,                   -- 商品分类
    item_price TEXT,                      -- 商品价格
    item_detail TEXT,                     -- 完整商品详情(JSON)
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(cookie_id, item_id)            -- 联合唯一索引
);

🚀 使用方法

1. 访问商品管理

1. 登录系统后，点击侧边栏"商品管理"菜单
2. 系统会自动加载所有账号的商品信息

2. 筛选商品

1. 使用"筛选账号"下拉框选择特定账号
2. 点击"刷新"按钮更新商品列表

3. 编辑商品详情

1. 在商品列表中点击"编辑详情"按钮
2. 在弹出的编辑框中修改商品详情（JSON格式）
3. 点击"保存"按钮保存修改

4. 商品信息自动收集

• 无需手动操作：系统会在以下情况自动收集商品信息：
  • 接收到闲鱼消息时
  • 自动发货时获取商品详情
  • 调用商品信息API时

🔧 技术实现

1. 数据收集流程

接收消息 → 提取商品ID → 调用API获取详情 → 保存到数据库
    ↓
如果API失败 → 仅保存商品ID → 后续可手动补充详情

2. 自动发货增强流程

触发自动发货 → 优先调用API获取商品信息
    ↓
API成功 → 使用API数据进行关键词匹配
    ↓
API失败 → 从数据库获取商品信息 → 使用数据库数据匹配

3. 数据更新策略

• 新商品：直接插入数据库
• 已存在且无详情：更新为有详情的数据
• 已存在且有详情：跳过更新，保护现有数据

📊 API接口

获取所有商品

GET /items
Authorization: Bearer {token}

获取指定账号商品

GET /items/cookie/{cookie_id}
Authorization: Bearer {token}

获取商品详情

GET /items/{cookie_id}/{item_id}
Authorization: Bearer {token}

更新商品详情

PUT /items/{cookie_id}/{item_id}
Content-Type: application/json
Authorization: Bearer {token}

{
    "item_detail": "{JSON格式的商品详情}"
}

🎨 界面功能

商品列表显示

• 账号ID：商品所属的闲鱼账号
• 商品ID：闲鱼商品的唯一标识
• 商品标题：从API获取的商品标题
• 商品分类：商品所属分类
• 价格：商品价格信息
• 更新时间：最后更新时间
• 操作按钮：编辑详情功能

编辑详情界面

• 大文本框：支持编辑大量JSON数据
• 格式验证：保存前验证JSON格式
• 实时保存：修改后立即生效

🔍 故障排除

常见问题

1. 商品信息为空

   • 原因：API获取失败，只保存了商品ID
   • 解决：手动编辑商品详情，补充信息

2. 自动发货匹配失败

   • 原因：商品信息不完整，关键词匹配失败
   • 解决：编辑商品详情，添加相关关键词

3. 商品重复显示

   • 原因：不同账号可能有相同商品ID
   • 说明：这是正常现象，系统按账号隔离

调试方法

1. 查看日志

   # 查看商品信息收集日志
   grep "商品信息" logs/xianyu_*.log
   
   # 查看自动发货日志
   grep "自动发货" logs/xianyu_*.log
   

2. 数据库查询

   from db_manager import db_manager
   
   # 查看所有商品
   items = db_manager.get_all_items()
   print(f"共有 {len(items)} 个商品")
   
   # 查看特定账号商品
   items = db_manager.get_items_by_cookie("account_id")
   print(f"该账号有 {len(items)} 个商品")
   

💡 最佳实践

1. 定期检查商品信息

   • 定期查看商品管理页面
   • 补充缺失的商品详情
   • 优化关键词匹配规则

2. 合理设置发货规则

   • 根据商品信息设置精确的关键词
   • 利用商品分类进行规则匹配
   • 测试匹配效果

3. 监控系统日志

   • 关注商品信息收集日志
   • 监控自动发货匹配情况
   • 及时处理异常情况

🔧 故障排除

常见问题及解决方案

问题1：商品信息收集失败

• 检查网络连接是否正常
• 确认Cookie是否有效
• 验证商品ID格式是否正确
• 查看详细错误日志

问题2：商品详情获取失败

• 检查API服务是否可用
• 确认商品是否存在
• 验证请求参数是否正确
• 检查API配置

问题3：数据库操作失败

• 检查数据库文件权限
• 确认磁盘空间是否充足
• 验证数据格式是否正确
• 查看数据库错误日志

性能优化建议

1. 定期清理：清理无效的商品信息
2. 索引优化：为常用查询字段建立索引
3. 批量操作：使用批量操作提高效率
4. 缓存机制：缓存常用的商品信息

📊 数据统计

商品统计信息

• 总商品数量：系统中所有商品的总数
• 有效商品数：包含完整信息的商品数量
• 账号分布：各账号的商品数量分布
• 分类统计：不同分类的商品数量

使用统计

• 收集成功率：商品信息收集的成功率
• API调用次数：商品详情API的调用统计
• 匹配成功率：自动发货匹配的成功率
• 处理速度：商品信息处理的平均速度

🚀 未来规划

即将推出的功能

1. 商品分析：基于商品数据的深度分析
2. 价格监控：监控商品价格变化趋势
3. 库存管理：集成库存管理功能
4. 销量统计：统计商品销售数据

长期发展方向

1. 智能推荐：基于商品数据的智能推荐
2. 自动定价：根据市场数据自动调整价格
3. 竞品分析：分析同类商品的竞争情况
4. 数据挖掘：深度挖掘商品数据价值

---

🎉 商品管理功能为您的闲鱼自动发货提供了强大的数据支持，让自动化运营更加智能和精准！通过持续优化和功能扩展，将为您带来更好的使用体验。