TEST_DATA_GUIDE.md

# 测试数据构造指南 - SearchEngine
本文档说明如何构造测试数据，包括两种数据源的准备和导入流程。
---
## 快速开始
### 1. 构造 Mock 数据（tenant_id=1 和 tenant_id=2）
```bash
./scripts/mock_data.sh
```
功能：自动生成 tenant_id=1 的Mock数据，并从CSV导入 tenant_id=2 的数据到MySQL
---
### 2. 从 MySQL → Elasticsearch
```bash
# 导入 tenant_id=1 的数据（重建索引）
./scripts/ingest.sh 1 true
# 导入 tenant_id=2 的数据（重建索引）
./scripts/ingest.sh 2 true
```
**用法**：`./scripts/ingest.sh <tenant_id> [recreate_index]`
- `tenant_id`: 租户ID（1 或 2）
- `recreate_index`: 是否重建索引（`true`/`false`，默认：`false`）
---
## 完整工作流程
```bash
# 1. 构造并导入测试数据到MySQL
./scripts/mock_data.sh
# 2. 导入 tenant_id=1 的数据到ES
./scripts/ingest.sh 1 true
# 3. 导入 tenant_id=2 的数据到ES
./scripts/ingest.sh 2 true
```
---
## 目录
1. [数据说明](#数据说明)
2. [构造Mock数据（tenant_id=1）](#构造mock数据tenant_id1)
3. [从CSV导入数据（tenant_id=2）](#从csv导入数据tenant_id2)
4. [从MySQL导入到Elasticsearch](#从mysql导入到elasticsearch)
5. [完整工作流程](#完整工作流程)
6. [常见问题](#常见问题)
---
## 数据说明
系统支持两种测试数据源：
1. **Tenant ID = 1**: 自动生成的Mock数据（使用 `generate_test_data.py` 生成）
2. **Tenant ID = 2**: 从CSV文件导入的真实数据（使用 `import_tenant2_csv.py` 导入）
### 数据表结构
系统使用店匠标准表结构：
- **SPU表**: `shoplazza_product_spu` - 商品SPU数据
- **SKU表**: `shoplazza_product_sku` - 商品SKU数据
表结构详见 `INDEX_FIELDS_DOCUMENTATION.md`。
---
## 构造Mock数据（tenant_id=1）
### 使用一键脚本（推荐）
`mock_data.sh` 脚本会自动生成并导入 tenant_id=1 的Mock数据：
```bash
cd /home/tw/SearchEngine
./scripts/mock_data.sh
```
脚本会自动：
- 生成 1000 个SPU的Mock数据
- 导入数据到MySQL
- 自动计算起始ID，避免主键冲突
### 手动分步执行
如果需要自定义参数，可以分步执行：
#### 步骤1: 生成Mock测试数据
```bash
python scripts/generate_test_data.py \
    --num-spus 1000 \
    --tenant-id "1" \
    --output test_data_tenant1.sql \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码>
```
参数说明：
- `--num-spus`: 生成的SPU数量（默认：1000）
- `--tenant-id`: 租户ID（默认：1）
- `--output`: 输出的SQL文件路径
- `--db-host`, `--db-port`, `--db-database`, `--db-username`, `--db-password`: 数据库连接信息
#### 步骤2: 导入数据到MySQL
```bash
python scripts/import_test_data.py \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码> \
    --sql-file test_data_tenant1.sql \
    --tenant-id "1"
```
参数说明：
- `--sql-file`: SQL文件路径
- `--tenant-id`: 租户ID（用于清理旧数据）
- 其他参数：数据库连接信息
**注意**: 导入会先清理该 tenant_id 的旧数据，再导入新数据。
---
## 从CSV导入数据（tenant_id=2）
### 使用一键脚本（推荐）
`mock_data.sh` 脚本会自动从CSV文件导入 tenant_id=2 的数据：
```bash
cd /home/tw/SearchEngine
./scripts/mock_data.sh
```
**前提条件**: 确保CSV文件存在于以下路径：
```
data/customer1/goods_with_pic.5years_congku.csv.shuf.1w
```
如果CSV文件路径不同，需要修改 `scripts/mock_data.sh` 中的 `TENANT2_CSV_FILE` 变量。
### CSV文件格式要求
CSV文件需要包含以下列（列名不区分大小写）：
- `skuId` - SKU ID
- `name` - 商品名称
- `name_pinyin` - 拼音（可选）
- `create_time` - 创建时间（格式：YYYY-MM-DD HH:MM:SS）
- `ruSkuName` - 俄文SKU名称（可选）
- `enSpuName` - 英文SPU名称（可选）
- `categoryName` - 类别名称
- `supplierName` - 供应商名称
- `brandName` - 品牌名称
- `file_id` - 文件ID（可选）
- `days_since_last_update` - 更新天数（可选）
- `id` - 商品ID（可选）
- `imageUrl` - 图片URL（可选）
### 手动分步执行
如果需要自定义参数，可以分步执行：
#### 步骤1: 从CSV生成SQL文件
```bash
python scripts/import_tenant2_csv.py \
    --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
    --tenant-id "2" \
    --output customer1_data.sql \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码>
```
参数说明：
- `--csv-file`: CSV文件路径
- `--tenant-id`: 租户ID（默认：2）
- `--output`: 输出的SQL文件路径
- 其他参数：数据库连接信息
#### 步骤2: 导入数据到MySQL
```bash
python scripts/import_test_data.py \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码> \
    --sql-file customer1_data.sql \
    --tenant-id "2"
```
**注意**: 
- CSV导入会先清理该 tenant_id 的旧数据，再导入新数据
- 脚本会自动计算起始ID，避免主键冲突
---
## 从MySQL导入到Elasticsearch
数据导入到MySQL后，需要使用 `ingest.sh` 脚本将数据从MySQL导入到Elasticsearch。
### 基本用法
```bash
./scripts/ingest.sh <tenant_id> [recreate_index]
```
参数说明：
- `tenant_id`: **必需**，租户ID，用于筛选数据库中的数据
- `recreate_index`: 可选，是否删除并重建索引（true/false，默认：false）
### 使用示例
#### 重建索引并导入数据（推荐首次导入）
```bash
# 导入tenant_id=1的数据并重建索引
./scripts/ingest.sh 1 true
# 导入tenant_id=2的数据并重建索引
./scripts/ingest.sh 2 true
```
#### 增量导入（不重建索引）
```bash
# 增量导入tenant_id=1的数据
./scripts/ingest.sh 1 false
# 增量导入tenant_id=2的数据
./scripts/ingest.sh 2 false
```
### 手动执行
如果需要自定义参数，可以手动执行：
```bash
python scripts/ingest_shoplazza.py \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码> \
    --tenant-id 1 \
    --es-host http://localhost:9200 \
    --recreate \
    --batch-size 500
```
参数说明：
- `--db-host`, `--db-port`, `--db-database`, `--db-username`, `--db-password`: MySQL连接信息
- `--tenant-id`: 租户ID（必需）
- `--es-host`: Elasticsearch地址
- `--recreate`: 是否重建索引
- `--batch-size`: 批量处理大小（默认：500）
### 检查可用的 tenant_id
如果导入时显示 "No documents to index"，脚本会自动显示调试信息，包括：
- 该 tenant_id 的统计信息（总数、活跃数、已删除数）
- 数据库中存在的其他 tenant_id 列表
也可以直接查询数据库：
```sql
-- 查看有哪些 tenant_id
SELECT tenant_id, COUNT(*) as count, 
       SUM(CASE WHEN deleted = 0 THEN 1 ELSE 0 END) as active
FROM shoplazza_product_spu
GROUP BY tenant_id;
-- 检查特定 tenant_id 的数据
SELECT COUNT(*) FROM shoplazza_product_spu 
WHERE tenant_id = 2 AND deleted = 0;
```
**注意**: 
- 只有 `deleted=0` 的记录会被导入
- 首次运行会下载模型文件（BGE-M3和CN-CLIP），大约需要10-30分钟
- 确保MySQL中存在对应 tenant_id 的数据
---
## 完整工作流程
### 完整示例：构造并导入所有测试数据
```bash
# 1. 构造并导入 tenant_id=1 的Mock数据到MySQL
./scripts/mock_data.sh
# 脚本会自动完成：
#   - 生成 tenant_id=1 的Mock数据（1000个SPU）
#   - 从CSV导入 tenant_id=2 的数据
#   - 导入数据到MySQL
# 2. 从MySQL导入 tenant_id=1 的数据到ES
./scripts/ingest.sh 1 true
# 3. 从MySQL导入 tenant_id=2 的数据到ES
./scripts/ingest.sh 2 true
# 4. 验证数据导入
curl http://localhost:9200/search_products/_count
```
### 分步执行示例
如果需要更细粒度的控制，可以分步执行：
```bash
# ===== Part 1: 构造 tenant_id=1 的Mock数据 =====
# 1.1 生成Mock数据
python scripts/generate_test_data.py \
    --num-spus 1000 \
    --tenant-id "1" \
    --output test_data_tenant1.sql \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码>
# 1.2 导入到MySQL
python scripts/import_test_data.py \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码> \
    --sql-file test_data_tenant1.sql \
    --tenant-id "1"
# ===== Part 2: 从CSV导入 tenant_id=2 的数据 =====
# 2.1 从CSV生成SQL
python scripts/import_tenant2_csv.py \
    --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
    --tenant-id "2" \
    --output customer1_data.sql \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码>
# 2.2 导入到MySQL
python scripts/import_test_data.py \
    --db-host 120.79.247.228 \
    --db-port 3316 \
    --db-database saas \
    --db-username saas \
    --db-password <密码> \
    --sql-file customer1_data.sql \
    --tenant-id "2"
# ===== Part 3: 从MySQL导入到ES =====
# 3.1 导入 tenant_id=1 的数据到ES
./scripts/ingest.sh 1 true
# 3.2 导入 tenant_id=2 的数据到ES
./scripts/ingest.sh 2 true
# ===== Part 4: 验证 =====
# 4.1 检查ES中的数据量
curl http://localhost:9200/search_products/_count
# 4.2 测试搜索
curl -X POST http://localhost:6002/search/ \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 1" \
  -d '{"query": "玩具", "size": 10}'
```
---
## 常见问题
### Q1: 数据导入失败
**症状**: `Error during data ingestion`
**解决方案**:
```bash
# 检查MySQL数据是否存在
mysql -h 120.79.247.228 -P 3316 -u saas -p saas -e \
  "SELECT COUNT(*) FROM shoplazza_product_spu WHERE tenant_id=1"
# 检查ES索引是否存在
curl http://localhost:9200/search_products
# 查看详细错误日志
python scripts/ingest_shoplazza.py --tenant-id 1 --recreate
```
### Q2: CSV文件找不到
**症状**: `ERROR: CSV file not found`
**解决方案**:
```bash
# 检查CSV文件是否存在
ls -lh data/customer1/goods_with_pic.5years_congku.csv.shuf.1w
# 如果路径不同，修改 scripts/mock_data.sh 中的 TENANT2_CSV_FILE 变量
```
### Q3: 导入时没有数据
**症状**: `WARNING: No documents to index` 或 `Transformed 0 SPU documents`
**可能原因**:
1. 数据库中不存在该 tenant_id 的数据
2. 数据都被标记为 `deleted=1`
3. tenant_id 类型不匹配
**解决步骤**:
1. **查看调试信息**: 脚本会自动显示调试信息，包括：
   ```
   DEBUG: tenant_id=1000: total=0, active=0, deleted=0
   DEBUG: Available tenant_ids in shoplazza_product_spu:
     tenant_id=1: total=100, active=100
     tenant_id=2: total=50, active=50
   ```
2. **检查数据库**: 直接查询MySQL确认数据
   ```sql
   -- 查看有哪些 tenant_id
   SELECT tenant_id, COUNT(*) as count, 
          SUM(CASE WHEN deleted = 0 THEN 1 ELSE 0 END) as active
   FROM shoplazza_product_spu
   GROUP BY tenant_id;
   
   -- 检查特定 tenant_id 的数据
   SELECT COUNT(*) FROM shoplazza_product_spu 
   WHERE tenant_id = 2 AND deleted = 0;
   ```
3. **如果数据库中没有数据，需要先导入数据**:
   - 如果有CSV文件，使用CSV导入脚本
   - 如果没有CSV文件，可以使用mock数据生成脚本
4. **使用正确的 tenant_id**: 根据调试信息显示的可用 tenant_id，使用正确的值重新导入
   ```bash
   ./scripts/ingest.sh 2 true  # 使用调试信息中显示的 tenant_id
   ```
### Q4: 模型下载慢或失败
**症状**: 首次运行时模型下载很慢或超时
**解决方案**:
```bash
# 跳过embedding快速测试（不推荐，但可以快速验证流程）
# 注意：这会导致搜索功能不完整
# 或手动下载模型到指定目录
# TEXT_MODEL_DIR=/data/tw/models/bge-m3
# IMAGE_MODEL_DIR=/data/tw/models/cn-clip
```
### Q5: 内存不足
**症状**: `Out of memory`
**解决方案**:
```bash
# 减少批量大小
python scripts/ingest_shoplazza.py \
    --tenant-id 1 \
    --batch-size 200  # 默认500，可以减少到100-200
```
### Q6: 主键冲突
**症状**: `Duplicate entry` 错误
**解决方案**:
- Mock数据脚本会自动计算起始ID，避免冲突
- 如果仍有冲突，可以手动清理旧数据：
  ```sql
  DELETE FROM shoplazza_product_spu WHERE tenant_id = 1;
  DELETE FROM shoplazza_product_sku WHERE tenant_id = 1;
  ```
---
## 相关文档
- **使用文档**: `USAGE_GUIDE.md` - 环境、启动、配置、日志查看
- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明
- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南
- **README**: `README.md` - 项目概述和快速开始
---
**文档版本**: v2.0  
**最后更新**: 2024-12