offline_tasks/FIX_NAME_MAPPING.md

# 商品名称映射问题修复
## 问题描述
在Debug模式生成的明文文件中，商品名称显示为"Unknown"：
```
[7] i2i:swing:3667845
--------------------------------------------------------------------------------
  1. ID:3588590(Unknown) - Score:0.2857
  2. ID:3623446(Unknown) - Score:...
```
## 根本原因
数据类型不匹配导致名称映射失败：
1. **fetch_name_mappings()** 从数据库获取的映射，key是**字符串类型**：
   ```python
   mappings['item'] = dict(zip(df['id'].astype(str), df['name']))
   # 结果: {'12345': '香蕉干', '67890': '芒果干', ...}
   ```
2. **item_name_map** 从DataFrame创建的映射，key是**整数类型**：
   ```python
   item_name_map = dict(zip(df['item_id'].unique(), ...))
   # 结果: {12345: '香蕉干', 67890: '芒果干', ...}
   ```
3. **更新操作失败**：
   ```python
   name_mappings['item'].update(item_name_map)
   # int类型的key和str类型的key不匹配，实际上没有更新成功
   ```
4. **查询时找不到**：
   ```python
   name = name_mappings.get('item', {}).get(str(item_id), 'Unknown')
   # 将int的item_id转为str查询，但dict中只有int类型的key，所以返回'Unknown'
   ```
## 修复方案
### 方法1：统一转为字符串（已采用）
```python
# 修改前
item_name_map = dict(zip(df['item_id'].unique(), df.groupby('item_id')['item_name'].first()))
# 修改后（key转为字符串）
item_name_map = dict(zip(df['item_id'].unique().astype(str), df.groupby('item_id')['item_name'].first()))
```
### 方法2：update时转换（备选）
```python
# 转换key类型后再更新
name_mappings['item'].update({str(k): v for k, v in item_name_map.items()})
```
## 验证修复
修复后运行debug模式：
```bash
cd /home/tw/recommendation/offline_tasks
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10 --debug
```
检查明文文件：
```bash
more output/debug/i2i_swing_*_readable.txt
```
应该看到：
```
[7] i2i:swing:3667845(商品名称)
--------------------------------------------------------------------------------
  1. ID:3588590(香蕉干) - Score:0.2857
  2. ID:3623446(芒果干) - Score:0.2143
```
## 数据库字段确认
正确的查询关系：
```sql
SELECT 
    pgs.id as 'sku_id',
    pgs.name as '商品名称',
    ss.name as '供应商名称',
    pc_1.name as '一级类目',
    pc_2.name as '二级类目'
FROM prd_goods_sku pgs
LEFT JOIN sup_supplier ss ON pgs.supplier_id = ss.id
LEFT JOIN prd_category pc_1 ON ...
```
## 其他脚本
这个问题也可能存在于其他脚本，需要同样修复：
- ✅ i2i_swing.py (已修复)
- ⚠️ i2i_session_w2v.py (如果有debug功能需要检查)
- ⚠️ i2i_deepwalk.py (如果有debug功能需要检查)
- ⚠️ i2i_content_similar.py (如果有debug功能需要检查)
- ⚠️ interest_aggregation.py (如果有debug功能需要检查)
## 预防措施
为避免类似问题，建议：
1. **统一数据类型约定**：
   - 所有ID映射的key统一使用字符串类型
   - 在debug_utils.py中明确文档说明
2. **添加类型检查**：
   ```python
   def safe_update_mapping(target_dict, source_dict):
       """安全更新映射，自动转换key类型"""
       for k, v in source_dict.items():
           target_dict[str(k)] = v
   ```
3. **添加调试日志**：
   ```python
   if debug:
       logger.debug(f"更新前: {len(name_mappings['item'])} 个名称")
       name_mappings['item'].update(item_name_map)
       logger.debug(f"更新后: {len(name_mappings['item'])} 个名称")
   ```
---
**状态**: ✅ 已修复  
**影响范围**: i2i_swing.py  
**修复时间**: 2025-10-16
## 补充修复 - 主输出文件
问题同样存在于主输出文件中：
```
1070176 Unknown 2786217:0.4000
2786217 Unknown 1070176:0.4000
```
### 原因
主输出代码中使用整数item_id作为key查询：
```python
for item_id, sims in result.items():
    item_name = item_name_map.get(item_id, 'Unknown')  # item_id是int，但map的key是str
```
### 修复
统一转换为字符串：
```python
for item_id, sims in result.items():
    item_name = item_name_map.get(str(item_id), 'Unknown')  # 转换为字符串查询
```
### 验证
```bash
# 重新运行
python3 scripts/i2i_swing.py --lookback_days 7 --top_n 10
# 检查输出
more output/i2i_swing_20251016.txt
```
应该看到：
```
1070176	商品名称A	2786217:0.4000
2786217	商品名称B	1070176:0.4000
```
---
**更新时间**: 2025-10-16 20:30  
**状态**: ✅ 完全修复