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

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

## 📋 功能概述

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

## 🎯 核心特性

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

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

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

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

## 🗄️ 数据库结构

### 商品信息表 (item_info)
```sql
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接口

### 获取所有商品
```http
GET /items
Authorization: Bearer {token}
```

### 获取指定账号商品
```http
GET /items/cookie/{cookie_id}
Authorization: Bearer {token}
```

### 获取商品详情
```http
GET /items/{cookie_id}/{item_id}
Authorization: Bearer {token}
```

### 更新商品详情
```http
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. **查看日志**
   ```bash
   # 查看商品信息收集日志
   grep "商品信息" logs/xianyu_*.log
   
   # 查看自动发货日志
   grep "自动发货" logs/xianyu_*.log
   ```

2. **数据库查询**
   ```python
   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. **监控系统日志**
   - 关注商品信息收集日志
   - 监控自动发货匹配情况
   - 及时处理异常情况

---

🎉 **商品管理功能让您的闲鱼自动发货更加智能和准确！**