文档完善

tangwang
1 parent d586fd1f
Showing 9 changed files with 933 additions and 1004 deletions Show diff stats
.env
.env.example
TEST_DATA_GUIDE.md
USAGE_GUIDE.md
USER_GUIDE.md
docs/店匠相关资料/python-app-demo/main.py
scripts/import_tenant2_csv.py
scripts/mock_data.sh
user_guide.md
@@ -11,9 +11,6 @@ REDIS_PASSWORD=BMfv5aI31kgHWtlx
 # DeepL Translation API
 DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
  
-# Customer Configuration
-CUSTOMER_ID=customer1
-
 # API Service Configuration
 API_HOST=0.0.0.0
 API_PORT=6002
@@ -26,8 +23,8 @@ DB_USERNAME=saas
 DB_PASSWORD=P89cZHS5d7dFyc9R
  
 # Model Directories
-TEXT_MODEL_DIR=/data/tw/models/bge-m3
-IMAGE_MODEL_DIR=/data/tw/models/cn-clip
+TEXT_MODEL_DIR=/data/tw/models/bge-m3 # 已经改为web请求了，不使用本地模型
+IMAGE_MODEL_DIR=/data/tw/models/cn-clip # 已经改为web请求了，不使用本地模型
  
 # Cache Directory
 CACHE_DIR=.cache
@@ -14,16 +14,13 @@ REDIS_PASSWORD=
 # DeepL Translation API
 DEEPL_AUTH_KEY=
  
-# Customer Configuration
-CUSTOMER_ID=customer1
-
 # API Service Configuration
 API_HOST=0.0.0.0
 API_PORT=6002
  
 # Embedding Models
-TEXT_MODEL_DIR=/data/tw/models/bge-m3
-IMAGE_MODEL_DIR=/data/tw/models/cn-clip
+TEXT_MODEL_DIR=/data/tw/models/bge-m3 # 已经改为web请求了，不使用本地模型
+IMAGE_MODEL_DIR=/data/tw/models/cn-clip # 已经改为web请求了，不使用本地模型
  
 # Cache Directory
 CACHE_DIR=.cache
@@ -0,0 +1,481 @@
+# 测试数据构造指南 - SearchEngine
+
+本文档说明如何构造测试数据，包括两种数据源的准备和导入流程。
+
+## 目录
+
+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
+
@@ -0,0 +1,441 @@
+# 使用指南 - SearchEngine
+
+本文档提供完整的使用指南，包括环境准备、服务启动、配置说明、日志查看等。
+
+## 目录
+
+1. [环境准备](#环境准备)
+2. [服务启动](#服务启动)
+3. [配置说明](#配置说明)
+4. [查看日志](#查看日志)
+5. [测试验证](#测试验证)
+6. [常见问题](#常见问题)
+
+---
+
+## 环境准备
+
+### 系统要求
+
+- **操作系统**: Linux (推荐 CentOS 7+ / Ubuntu 18.04+)
+- **Python**: 3.8+
+- **内存**: 建议 8GB+
+- **磁盘**: 10GB+ (包含模型文件)
+- **Elasticsearch**: 8.x (可通过Docker运行)
+
+### 安装依赖
+
+#### 1. 安装Python依赖
+
+```bash
+cd /home/tw/SearchEngine
+pip install -r requirements.txt
+```
+
+#### 2. 启动Elasticsearch
+
+**方式1: 使用Docker（推荐）**
+
+```bash
+docker run -d \
+  --name elasticsearch \
+  -p 9200:9200 \
+  -e "discovery.type=single-node" \
+  -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \
+  elasticsearch:8.11.0
+```
+
+**方式2: 本地安装**
+
+参考 [Elasticsearch官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/8.11/install-elasticsearch.html)
+
+#### 3. 配置环境变量
+
+创建 `.env` 文件：
+
+```bash
+# MySQL配置
+DB_HOST=120.79.247.228
+DB_PORT=3316
+DB_DATABASE=saas
+DB_USERNAME=saas
+DB_PASSWORD=your_password
+
+# Elasticsearch配置
+ES_HOST=http://localhost:9200
+ES_USERNAME=essa
+ES_PASSWORD=4hOaLaf41y2VuI8y
+
+# Redis配置（可选，用于缓存）
+REDIS_HOST=localhost
+REDIS_PORT=6479
+REDIS_PASSWORD=BMfv5aI31kgHWtlx
+
+# DeepL翻译API（可选）
+DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
+
+# API服务配置
+API_HOST=0.0.0.0
+API_PORT=6002
+```
+
+---
+
+## 服务启动
+
+### 方式1: 一键启动（推荐）
+
+```bash
+cd /home/tw/SearchEngine
+./run.sh
+```
+
+这个脚本会自动：
+1. 创建日志目录
+2. 启动后端API服务（后台运行）
+3. 启动前端Web界面（后台运行）
+4. 等待服务就绪
+
+启动完成后，访问：
+- **前端界面**: http://localhost:6003
+- **后端API**: http://localhost:6002
+- **API文档**: http://localhost:6002/docs
+
+### 方式2: 分步启动
+
+#### 启动后端服务
+
+```bash
+./scripts/start_backend.sh
+```
+
+后端API会在 http://localhost:6002 启动
+
+#### 启动前端服务
+
+```bash
+./scripts/start_frontend.sh
+```
+
+前端界面会在 http://localhost:6003 启动
+
+### 方式3: 手动启动
+
+#### 启动后端API服务
+
+```bash
+python -m api.app \
+  --host 0.0.0.0 \
+  --port 6002 \
+  --es-host http://localhost:9200 \
+  --reload
+```
+
+#### 启动前端服务（可选）
+
+```bash
+# 使用Python简单HTTP服务器
+cd frontend
+python -m http.server 6003
+```
+
+### 停止服务
+
+```bash
+# 停止后端
+kill $(cat logs/backend.pid)
+
+# 停止前端
+kill $(cat logs/frontend.pid)
+
+# 或使用停止脚本
+./scripts/stop.sh
+```
+
+### 服务端口
+
+| 服务 | 端口 | URL |
+|------|------|-----|
+| Elasticsearch | 9200 | http://localhost:9200 |
+| Backend API | 6002 | http://localhost:6002 |
+| Frontend Web | 6003 | http://localhost:6003 |
+| API Docs | 6002 | http://localhost:6002/docs |
+
+---
+
+## 配置说明
+
+### 环境配置文件 (.env)
+
+主要配置项说明：
+
+```bash
+# Elasticsearch配置
+ES_HOST=http://localhost:9200
+ES_USERNAME=essa
+ES_PASSWORD=4hOaLaf41y2VuI8y
+
+# MySQL配置
+DB_HOST=120.79.247.228
+DB_PORT=3316
+DB_DATABASE=saas
+DB_USERNAME=saas
+DB_PASSWORD=your_password
+
+# Redis配置（可选，用于缓存）
+REDIS_HOST=localhost
+REDIS_PORT=6479
+REDIS_PASSWORD=BMfv5aI31kgHWtlx
+
+# DeepL翻译API
+DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
+
+# API服务配置
+API_HOST=0.0.0.0
+API_PORT=6002
+```
+
+### 修改配置
+
+1. 编辑 `.env` 文件
+2. 重启相关服务
+
+---
+
+## 查看日志
+
+### 日志文件位置
+
+日志文件存储在 `logs/` 目录下：
+
+- `logs/backend.log` - 后端服务日志
+- `logs/frontend.log` - 前端服务日志
+- `logs/search_engine.log` - 应用主日志（按天轮转）
+- `logs/errors.log` - 错误日志（按天轮转）
+
+### 查看实时日志
+
+```bash
+# 查看后端日志
+tail -f logs/backend.log
+
+# 查看前端日志
+tail -f logs/frontend.log
+
+# 查看应用主日志
+tail -f logs/search_engine.log
+
+# 查看错误日志
+tail -f logs/errors.log
+```
+
+### 日志级别
+
+日志级别可以通过环境变量 `LOG_LEVEL` 设置：
+
+```bash
+# 在 .env 文件中设置
+LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+### 日志轮转
+
+日志文件按天自动轮转，保留30天的历史日志。
+
+---
+
+## 测试验证
+
+### 1. 健康检查
+
+```bash
+curl http://localhost:6002/admin/health
+```
+
+**预期响应**:
+```json
+{
+  "status": "healthy",
+  "elasticsearch": "connected"
+}
+```
+
+### 2. 索引统计
+
+```bash
+curl http://localhost:6002/admin/stats
+```
+
+### 3. 简单搜索测试
+
+```bash
+curl -X POST http://localhost:6002/search/ \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 2" \
+  -d '{
+    "query": "玩具",
+    "size": 10
+  }'
+```
+
+或者通过查询参数：
+
+```bash
+curl -X POST "http://localhost:6002/search/?tenant_id=2" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "玩具",
+    "size": 10
+  }'
+```
+
+### 4. 带过滤器的搜索
+
+```bash
+curl -X POST http://localhost:6002/search/ \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 2" \
+  -d '{
+    "query": "玩具",
+    "size": 10,
+    "filters": {
+      "categoryName_keyword": ["玩具", "益智玩具"]
+    },
+    "range_filters": {
+      "price": {"gte": 50, "lte": 200}
+    }
+  }'
+```
+
+### 5. 分面搜索测试
+
+```bash
+curl -X POST http://localhost:6002/search/ \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 2" \
+  -d '{
+    "query": "玩具",
+    "size": 10,
+    "facets": [
+      {"field": "categoryName_keyword", "size": 15},
+      {"field": "brandName_keyword", "size": 15}
+    ]
+  }'
+```
+
+### 6. 图片搜索测试
+
+```bash
+curl -X POST http://localhost:6002/search/image \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 2" \
+  -d '{
+    "image_url": "https://oss.essa.cn/example.jpg",
+    "size": 10
+  }'
+```
+
+### 7. 前端界面测试
+
+访问 http://localhost:6003 或 http://localhost:6002/ 进行可视化测试。
+
+**注意**: 所有搜索接口都需要通过 `X-Tenant-ID` 请求头或 `tenant_id` 查询参数指定租户ID。
+
+---
+
+## 常见问题
+
+### Q1: MySQL连接失败
+
+**症状**: `Failed to connect to MySQL`
+
+**解决方案**:
+```bash
+# 检查MySQL服务状态
+mysql -h 120.79.247.228 -P 3316 -u saas -p -e "SELECT 1"
+
+# 检查配置
+cat .env | grep DB_
+```
+
+### Q2: Elasticsearch连接失败
+
+**症状**: `Failed to connect to Elasticsearch`
+
+**解决方案**:
+```bash
+# 检查ES服务状态
+curl http://localhost:9200
+
+# 检查ES版本
+curl http://localhost:9200 | grep version
+
+# 确认配置
+cat .env | grep ES_
+```
+
+### Q3: 服务启动失败
+
+**症状**: `Address already in use` 或端口被占用
+
+**解决方案**:
+```bash
+# 查看占用端口的进程
+lsof -i :6002  # 后端
+lsof -i :6003  # 前端
+lsof -i :9200  # ES
+
+# 杀掉进程
+kill -9 <PID>
+
+# 或修改端口配置
+```
+
+### Q4: 搜索无结果
+
+**症状**: 搜索返回空结果
+
+**解决方案**:
+```bash
+# 检查ES中是否有数据
+curl http://localhost:9200/search_products/_count
+
+# 检查tenant_id过滤是否正确
+curl -X POST http://localhost:6002/search/ \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 2" \
+  -d '{"query": "*", "size": 10, "debug": true}'
+```
+
+### Q5: 前端无法连接后端
+
+**症状**: CORS错误
+
+**解决方案**:
+- 确保后端在 http://localhost:6002 运行
+- 检查浏览器控制台错误信息
+- 检查后端日志中的CORS配置
+
+### Q6: 翻译不工作
+
+**症状**: 翻译返回原文
+
+**解决方案**:
+- 检查DEEPL_AUTH_KEY是否正确
+- 如果没有API key，系统会使用mock模式（返回原文）
+
+---
+
+## 相关文档
+
+- **测试数据构造文档**: `TEST_DATA_GUIDE.md` - 如何构造和导入测试数据
+- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南
+- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明
+- **设计文档**: `设计文档.md` - 系统架构和设计说明
+- **README**: `README.md` - 项目概述和快速开始
+
+---
+
+**文档版本**: v2.0  
+**最后更新**: 2024-12
+
@@ -1,539 +0,0 @@
-# 使用指南 - SearchEngine
-
-## 快速启动（推荐）
-
-### 一键启动所有服务
-
-```bash
-cd /data/tw/SearchEngine
-./start_all.sh
-```
-
-这个脚本会自动完成：
-1. 设置conda环境
-2. 检查并导入测试数据（如果需要）
-3. 启动后端API服务（后台运行）
-4. 启动前端Web界面
-
-启动完成后，访问：
-- **前端界面**: http://localhost:6003
-- **后端API**: http://localhost:6002
-- **API文档**: http://localhost:6002/docs
-
-### 停止服务
-
-```bash
-# 停止后端
-kill $(cat logs/backend.pid)
-
-# 前端按 Ctrl+C
-```
-
----
-
-## 分步启动（自定义）
-
-### 1. 环境设置
-
-```bash
-cd /data/tw/SearchEngine
-./setup.sh
-```
-
-这会：
-- 创建/激活conda环境 `searchengine`
-- 加载配置文件
-- 检查Elasticsearch连接
-
-### 2. 数据导入
-
-#### 2.1 从MySQL导入到Elasticsearch
-
-数据导入脚本需要指定 `tenant_id` 参数，用于从MySQL中筛选对应租户的数据。
-
-**基本用法**：
-```bash
-./scripts/ingest.sh <tenant_id> [recreate_index]
-```
-
-参数说明：
-- `tenant_id`: **必需**，租户ID，用于筛选数据库中的数据
-- `recreate_index`: 可选，是否删除并重建索引（true/false，默认：false）
-
-**示例**：
-
-快速测试（tenant_id=2，重建索引）：
-```bash
-./scripts/ingest.sh 2 true
-```
-
-增量导入（tenant_id=2，不重建索引）：
-```bash
-./scripts/ingest.sh 2 false
-```
-
-**检查可用的 tenant_id**：
-
-如果导入时显示 "No documents to index"，脚本会自动显示调试信息，包括：
-- 该 tenant_id 的统计信息（总数、活跃数、已删除数）
-- 数据库中存在的其他 tenant_id 列表
-
-#### 2.2 构造测试数据（Mock Data）
-
-`mock_data.sh` 脚本用于构造完整的测试数据，包含两部分：
-
-1. **tenant_id=1**: 自动生成的mock数据（1000条SPU）
-2. **tenant_id=2**: 从CSV文件导入的数据（10000条SPU）
-
-**使用方法**：
-
-将CSV文件放在 `data/customer1/goods_with_pic.5years_congku.csv.shuf.1w`，然后直接运行：
-```bash
-./scripts/mock_data.sh
-```
-
-脚本会自动：
-- 生成 tenant_id=1 的mock数据并导入MySQL
-- 从CSV文件读取数据，生成 tenant_id=2 的数据并导入MySQL
-- 自动计算起始ID，避免主键冲突
-
-**注意**：
-- 所有配置（数据库地址、CSV路径等）都写死在脚本中，这是测试数据构造脚本，不需要配置化
-- 如果CSV文件路径不同，需要修改 `scripts/mock_data.sh` 中的 `TENANT2_CSV_FILE` 变量
-
-**手动分步执行**（如果需要自定义参数）：
-
-1. **生成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 <密码>
-```
-
-2. **导入SQL到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文件格式要求**：
-
-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（可选）
-
-**注意**: 
-- 首次运行会下载模型文件（BGE-M3和CN-CLIP），大约需要10-30分钟
-- 确保MySQL中存在对应 tenant_id 的数据（`shoplazza_product_spu` 和 `shoplazza_product_sku` 表）
-- 只有 `deleted=0` 的记录会被导入
-- CSV导入会先清理该 tenant_id 的旧数据，再导入新数据
-
-### 3. 启动后端
-
-```bash
-./scripts/start_backend.sh
-```
-
-后端API会在 http://localhost:6002 启动
-
-### 4. 启动前端
-
-```bash
-./scripts/start_frontend.sh
-```
-
-前端界面会在 http://localhost:6003 启动
-
----
-
-## 配置说明
-
-### 环境配置文件 (.env)
-
-```bash
-# Elasticsearch配置
-ES_HOST=http://localhost:9200
-ES_USERNAME=essa
-ES_PASSWORD=4hOaLaf41y2VuI8y
-
-# Redis配置（可选，用于缓存）
-REDIS_HOST=localhost
-REDIS_PORT=6479
-REDIS_PASSWORD=BMfv5aI31kgHWtlx
-
-# DeepL翻译API
-DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed
-
-# 客户配置
-TENANT_ID=tenant1
-
-# API服务配置
-API_HOST=0.0.0.0
-API_PORT=6002
-```
-
-### 修改配置
-
-1. 编辑 `.env` 文件
-2. 重启相关服务
-
----
-
-## 使用Web界面
-
-### 搜索功能
-
-1. **简单搜索**: 直接输入关键词
-   - 中文: "芭比娃娃"
-   - 英文: "fire control set"
-   - 俄文: "Наборы для пожаротушения"
-
-2. **布尔搜索**: 使用操作符
-   - AND: "toy AND barbie"
-   - OR: "barbie OR doll"
-   - ANDNOT: "toy ANDNOT cheap"
-   - 组合: "toy AND (barbie OR doll) ANDNOT cheap"
-
-3. **域搜索**: 指定搜索域
-   - 品牌: "brand:ZHU LIN"
-   - 类别: "category:玩具"
-
-### 搜索选项
-
-- **启用翻译**: 自动翻译查询到其他语言
-- **启用语义搜索**: 使用embedding进行语义匹配
-- **启用自定义排序**: 使用配置的ranking表达式
-- **结果数量**: 10/20/50条
-
----
-
-## API使用
-
-### 搜索接口（v3.0 更新）
-
-**基础搜索**（需要指定 tenant_id）：
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -H "X-Tenant-ID: 2" \
-  -d '{
-    "query": "芭比娃娃",
-    "size": 20
-  }'
-```
-
-或者通过查询参数：
-```bash
-curl -X POST "http://localhost:6002/search/?tenant_id=2" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "芭比娃娃",
-    "size": 20
-  }'
-```
-
-**带过滤器的搜索**：
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -H "X-Tenant-ID: 2" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "filters": {
-      "categoryName_keyword": ["玩具", "益智玩具"]
-    },
-    "range_filters": {
-      "price": {"gte": 50, "lte": 200}
-    }
-  }'
-```
-
-**带分面搜索**：
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -H "X-Tenant-ID: 2" \
-  -d '{
-    "query": "玩具",
-    "size": 20,
-    "facets": [
-      {"field": "categoryName_keyword", "size": 15},
-      {"field": "brandName_keyword", "size": 15}
-    ]
-  }'
-```
-
-### 图片搜索
-
-```bash
-curl -X POST http://localhost:6002/search/image \
-  -H "Content-Type: application/json" \
-  -H "X-Tenant-ID: 2" \
-  -d '{
-    "image_url": "https://oss.essa.cn/example.jpg",
-    "size": 10
-  }'
-```
-
-**注意**: 所有搜索接口都需要通过 `X-Tenant-ID` 请求头或 `tenant_id` 查询参数指定租户ID。
-
-### 健康检查
-
-```bash
-curl http://localhost:6002/admin/health
-```
-
-### 查看配置
-
-```bash
-curl http://localhost:6002/admin/config
-```
-
-### 索引统计
-
-```bash
-curl http://localhost:6002/admin/stats
-```
-
----
-
-## 常见问题
-
-### 1. Elasticsearch连接失败
-
-**问题**: `Failed to connect to Elasticsearch`
-
-**解决**:
-```bash
-# 检查ES是否运行
-curl http://localhost:9200
-
-# 检查配置
-cat .env | grep ES_
-```
-
-### 2. 导入数据时内存不足
-
-**问题**: `Out of memory`
-
-**解决**:
-```bash
-# 减少batch size或跳过embedding
-./scripts/ingest.sh 1000 true
-```
-
-### 3. 模型下载失败
-
-**问题**: 模型文件下载超时
-
-**解决**:
-- 检查网络连接
-- 使用国内镜像源
-- 手动下载模型到指定目录
-
-### 4. 翻译不工作
-
-**问题**: 翻译返回原文
-
-**解决**:
-- 检查DEEPL_AUTH_KEY是否正确
-- 如果没有API key，系统会使用mock模式（返回原文）
-
-### 5. 前端无法连接后端
-
-**问题**: CORS错误
-
-**解决**:
-- 确保后端在 http://localhost:6002 运行
-- 检查浏览器控制台错误信息
-
-### 6. 数据导入时没有数据
-
-**问题**: `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 = 1000 AND deleted = 0;
-   ```
-
-3. **如果数据库中没有数据，需要先导入数据**:
-   - 如果有CSV文件，使用CSV导入脚本（见"2.2 从CSV导入数据到MySQL"）
-   - 如果没有CSV文件，可以使用mock数据生成脚本
-
-4. **使用正确的 tenant_id**: 根据调试信息显示的可用 tenant_id，使用正确的值重新导入
-   ```bash
-   ./scripts/ingest.sh 2 true  # 使用调试信息中显示的 tenant_id
-   ```
-
----
-
-## 开发和调试
-
-### 查看日志
-
-```bash
-# 后端日志
-tail -f logs/backend.log
-
-# 实时日志（如果前台运行）
-./scripts/start_backend.sh
-```
-
-### Python命令行测试
-
-```bash
-# 激活环境
-source /home/tw/miniconda3/etc/profile.d/conda.sh
-conda activate searchengine
-
-# 测试搜索（需要指定 tenant_id）
-python -c "
-from config import ConfigLoader
-from utils.es_client import ESClient
-from search.searcher import Searcher
-from config.env_config import ES_CONFIG
-
-config_loader = ConfigLoader('config/config.yaml')
-config = config_loader.load_config()
-
-es_client = ESClient(hosts=[ES_CONFIG['host']],
-                     username=ES_CONFIG.get('username'),
-                     password=ES_CONFIG.get('password'))
-
-searcher = Searcher(config, es_client)
-result = searcher.search('芭比娃娃', tenant_id='2', size=5)
-
-print(f'找到 {result.total} 个结果')
-for hit in result.hits:
-    print(f'  - {hit[\"title\"]} (分数: {hit[\"_score\"]:.4f})')
-"
-```
-
-### 重新导入数据
-
-```bash
-# 删除现有索引并重新导入（需要指定 tenant_id）
-./scripts/ingest.sh <tenant_id> true
-
-# 例如：导入 tenant_id=2 的数据并重建索引
-./scripts/ingest.sh 2 true
-```
-
-### 检查数据库中的 tenant_id
-
-如果不知道应该使用哪个 tenant_id，可以：
-
-1. **运行导入脚本查看调试信息**（即使没有数据也会显示）:
-   ```bash
-   ./scripts/ingest.sh 999 true
-   ```
-   脚本会显示数据库中存在的 tenant_id 列表
-
-2. **直接查询数据库**:
-   ```bash
-   mysql -h 120.79.247.228 -P 3316 -u saas -p saas -e \
-     "SELECT tenant_id, COUNT(*) as count FROM shoplazza_product_spu GROUP BY tenant_id;"
-```
-
----
-
-## 性能优化
-
-### 1. 使用embedding缓存
-
-首次生成embedding后会自动缓存到 `.cache/` 目录，后续导入会更快。
-
-### 2. 批量大小调整
-
-```bash
-# 修改批量大小（在ingest_tenant1.py中）
---batch-size 200  # 默认100
-```
-
-### 3. GPU加速
-
-确保CUDA可用以加速embedding生成：
-```bash
-python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
-```
-
----
-
-## 项目结构
-
-```
-SearchEngine/
-├── .env                    # 环境配置
-├── setup.sh                # 环境设置脚本
-├── start_all.sh            # 一键启动脚本
-├── scripts/                # 运行脚本
-│   ├── ingest.sh           # 数据导入
-│   ├── start_backend.sh    # 启动后端
-│   └── start_frontend.sh   # 启动前端
-├── frontend/               # Web前端
-│   ├── index.html
-│   └── static/
-├── logs/                   # 日志文件
-├── config/                 # 配置模块
-├── indexer/                # 数据导入
-├── query/                  # 查询处理
-├── search/                 # 搜索引擎
-├── embeddings/             # 向量模型
-└── api/                    # REST API
-```
-
----
-
-## 支持
-
-遇到问题请查看：
-- **日志**: `logs/backend.log`
-- **API文档**: http://localhost:6002/docs
-- **配置**: `config/schema/tenant1_config.yaml`
@@ -69,7 +69,7 @@ def auth():
     if not shop:
         return jsonify({"error": "shop parameter is required"}), 400
  
-    scopes = "read_customer"
+    scopes = "read_tenant"
     state = secrets.token_hex(16)  # 生成随机state
  
     auth_url = (
@@ -117,8 +117,8 @@ def auth_callback():
  
         # 这里可以调用Shoplazza OpenAPI获取更多数据
         # headers = {"Access-Token": token_data.get("access_token")}
-        # customers_url = f"https://{shop}/openapi/2022-01/customers"
-        # customers_response = requests.get(customers_url, headers=headers)
+        # tenants_url = f"https://{shop}/openapi/2022-01/tenants"
+        # tenants_response = requests.get(tenants_url, headers=headers)
         # return redirect(LAST_URL)
  
     except requests.exceptions.RequestException as e:
@@ -303,7 +303,7 @@ def generate_sql_inserts(spus: list, skus: list, output_file: str):
         output_file: Output file path
     """
     with open(output_file, 'w', encoding='utf-8') as f:
-        f.write("-- SPU Data from customer1 CSV\n")
+        f.write("-- SPU Data from tenant2 CSV\n")
         f.write("INSERT INTO shoplazza_product_spu (\n")
         f.write("    id, shop_id, shoplazza_id, handle, title, brief, description, spu,\n")
         f.write("    vendor, vendor_url, seo_title, seo_description, seo_keywords,\n")
@@ -345,7 +345,7 @@ def generate_sql_inserts(spus: list, skus: list, output_file: str):
             else:
                 f.write(";\n\n")
  
-        f.write("-- SKU Data from customer1 CSV\n")
+        f.write("-- SKU Data from tenant2 CSV\n")
         f.write("INSERT INTO shoplazza_product_sku (\n")
         f.write("    id, spu_id, shop_id, shoplazza_id, shoplazza_product_id, shoplazza_image_id,\n")
         f.write("    title, sku, barcode, position, price, compare_at_price, cost_price,\n")
@@ -425,7 +425,7 @@ def main():
     parser.add_argument('--csv-file', required=True, help='CSV file path')
     parser.add_argument('--tenant-id', default='2', help='Tenant ID (default: 2)')
     parser.add_argument('--start-spu-id', type=int, default=None, help='Starting SPU ID (default: auto-calculate from DB)')
-    parser.add_argument('--output', default='customer1_data.sql', help='Output SQL file (default: customer1_data.sql)')
+    parser.add_argument('--output', default='tenant2_data.sql', help='Output SQL file (default: tenant2_data.sql)')
     parser.add_argument('--db-host', help='Database host (for auto-calculating start IDs)')
     parser.add_argument('--db-port', type=int, default=3306, help='Database port (default: 3306)')
     parser.add_argument('--db-database', help='Database name (for auto-calculating start IDs)')
@@ -121,7 +121,7 @@ echo -e &quot;\n${YELLOW}========================================${NC}&quot;
 echo -e "${YELLOW}Part 2/2: 生成并导入 tenant_id=2 的CSV数据${NC}"
 echo -e "${YELLOW}========================================${NC}"
  
-TENANT2_SQL_FILE="customer1_data.sql"
+TENANT2_SQL_FILE="tenant2_data.sql"
  
 echo -e "\n${YELLOW}Step 2.1: 从CSV生成数据${NC}"
 python scripts/import_tenant2_csv.py \
@@ -1,448 +0,0 @@
-# 使用指南
-
-本文档提供完整的使用指南，包括环境准备、数据导入、服务启动、测试等。
-
-## 目录
-
-1. [环境准备](#环境准备)
-2. [数据准备](#数据准备)
-3. [数据导入](#数据导入)
-4. [服务启动](#服务启动)
-5. [测试验证](#测试验证)
-6. [常见问题](#常见问题)
-
----
-
-## 环境准备
-
-### 系统要求
-
-- **操作系统**: Linux (推荐 CentOS 7+ / Ubuntu 18.04+)
-- **Python**: 3.8+
-- **内存**: 建议 8GB+
-- **磁盘**: 10GB+ (包含模型文件)
-- **Elasticsearch**: 8.x (可通过Docker运行)
-
-### 安装依赖
-
-#### 1. 安装Python依赖
-
-```bash
-cd /home/tw/SearchEngine
-pip install -r requirements.txt
-```
-
-#### 2. 启动Elasticsearch
-
-**方式1: 使用Docker（推荐）**
-
-```bash
-docker run -d \
-  --name elasticsearch \
-  -p 9200:9200 \
-  -e "discovery.type=single-node" \
-  -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \
-  elasticsearch:8.11.0
-```
-
-**方式2: 本地安装**
-
-参考 [Elasticsearch官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/8.11/install-elasticsearch.html)
-
-#### 3. 配置环境变量（可选）
-
-创建 `.env` 文件：
-
-```bash
-# MySQL配置
-DB_HOST=120.79.247.228
-DB_PORT=3316
-DB_DATABASE=saas
-DB_USERNAME=saas
-DB_PASSWORD=your_password
-
-# Elasticsearch配置
-ES_HOST=http://localhost:9200
-
-# DeepL翻译API（可选）
-DEEPL_AUTH_KEY=your_deepl_api_key
-```
-
----
-
-## 数据准备
-
-### Mock数据说明
-
-项目提供了两套写死的Mock数据，用于测试：
-
-1. **Tenant ID = 1**: 生成的Mock数据（100个SPU）
-2. **Tenant ID = 2**: 从CSV导入的真实数据
-
-### 数据表结构
-
-系统使用店匠标准表结构：
-
-- **SPU表**: `shoplazza_product_spu` - 商品SPU数据
-- **SKU表**: `shoplazza_product_sku` - 商品SKU数据
-
-表结构详见 `INDEX_FIELDS_DOCUMENTATION.md`。
-
----
-
-## 数据导入
-
-### 步骤1: 导入Mock数据到MySQL
-
-#### 方式1: 使用脚本（推荐）
-
-```bash
-# 导入tenant_id=1的Mock数据（默认100个SPU）
-./scripts/mock_data.sh
-
-# 指定tenant_id和SPU数量
-./scripts/mock_data.sh 1 200
-
-# 使用显式参数
-./scripts/mock_data.sh --mode mock --tenant-id 1 --num-spus 200
-```
-
-#### 方式2: 导入CSV数据（tenant_id=2）
-
-```bash
-# 导入customer1的CSV数据
-./scripts/mock_data.sh --mode csv \
-  --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
-  --tenant-id 2 \
-  --start-spu-id 1
-```
-
-#### 方式3: 手动导入SQL
-
-```bash
-# 导入tenant_id=1的测试数据
-mysql -h 120.79.247.228 -P 3316 -u saas -p saas < test_data_tenant1.sql
-
-# 导入tenant_id=2的CSV数据
-mysql -h 120.79.247.228 -P 3316 -u saas -p saas < customer1_data.sql
-```
-
-### 步骤2: 从MySQL导入数据到Elasticsearch
-
-#### 使用脚本（推荐）
-
-```bash
-# 导入tenant_id=1的数据
-./scripts/ingest.sh 1
-
-# 重建索引并导入数据
-./scripts/ingest.sh 1 true
-
-# 导入tenant_id=2的数据
-./scripts/ingest.sh 2
-```
-
-#### 手动执行
-
-```bash
-python scripts/ingest_shoplazza.py \
-    --db-host 120.79.247.228 \
-    --db-port 3316 \
-    --db-database saas \
-    --db-username saas \
-    --db-password your_password \
-    --tenant-id 1 \
-    --config base \
-    --es-host http://localhost:9200 \
-    --recreate \
-    --batch-size 500
-```
-
-### 完整工作流程示例
-
-```bash
-# 1. 导入tenant_id=1的Mock数据（100个SPU）
-./scripts/mock_data.sh 1 100
-
-# 2. 导入tenant_id=2的CSV数据
-./scripts/mock_data.sh --mode csv \
-  --csv-file data/customer1/goods_with_pic.5years_congku.csv.shuf.1w \
-  --tenant-id 2
-
-# 3. 将两个租户的数据导入ES
-./scripts/ingest.sh 1
-./scripts/ingest.sh 2
-
-# 4. 验证数据导入
-curl http://localhost:9200/search_products/_count
-```
-
----
-
-## 服务启动
-
-### 方式1: 使用启动脚本（推荐）
-
-```bash
-# 启动前端和后端服务
-./run.sh
-
-# 重启所有服务
-./restart.sh
-```
-
-### 方式2: 手动启动
-
-#### 启动后端API服务
-
-```bash
-python -m api.app \
-  --host 0.0.0.0 \
-  --port 6002 \
-  --es-host http://localhost:9200 \
-  --reload
-```
-
-#### 启动前端服务（可选）
-
-```bash
-# 使用Python简单HTTP服务器
-cd frontend
-python -m http.server 6003
-```
-
-### 服务端口
-
-| 服务 | 端口 | URL |
-|------|------|-----|
-| Elasticsearch | 9200 | http://localhost:9200 |
-| Backend API | 6002 | http://localhost:6002 |
-| Frontend Web | 6003 | http://localhost:6003 |
-| API Docs | 6002 | http://localhost:6002/docs |
-
----
-
-## 测试验证
-
-### 1. 健康检查
-
-```bash
-curl http://localhost:6002/admin/health
-```
-
-**预期响应**:
-```json
-{
-  "status": "healthy",
-  "elasticsearch": "connected"
-}
-```
-
-### 2. 索引统计
-
-```bash
-curl http://localhost:6002/admin/stats
-```
-
-### 3. 简单搜索测试
-
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 10
-  }'
-```
-
-### 4. 带过滤器的搜索
-
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 10,
-    "filters": {
-      "category_keyword": "益智玩具"
-    },
-    "range_filters": {
-      "min_price": {
-        "gte": 50,
-        "lte": 200
-      }
-    }
-  }'
-```
-
-### 5. 分面搜索测试
-
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具",
-    "size": 10,
-    "facets": [
-      "category_keyword",
-      "vendor_keyword"
-    ]
-  }'
-```
-
-### 6. 布尔表达式搜索
-
-```bash
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "玩具 AND (乐高 OR 芭比)",
-    "size": 10
-  }'
-```
-
-### 7. 图片搜索测试
-
-```bash
-curl -X POST http://localhost:6002/search/image \
-  -H "Content-Type: application/json" \
-  -d '{
-    "image_url": "https://example.com/image.jpg",
-    "size": 10
-  }'
-```
-
-### 8. 前端界面测试
-
-访问 http://localhost:6003 或 http://localhost:6002/ 进行可视化测试。
-
----
-
-## 常见问题
-
-### Q1: MySQL连接失败
-
-**症状**: `Failed to connect to MySQL`
-
-**解决方案**:
-```bash
-# 检查MySQL服务状态
-mysql -h 120.79.247.228 -P 3316 -u saas -p -e "SELECT 1"
-
-# 检查配置
-cat .env | grep DB_
-```
-
-### Q2: Elasticsearch连接失败
-
-**症状**: `Failed to connect to Elasticsearch`
-
-**解决方案**:
-```bash
-# 检查ES服务状态
-curl http://localhost:9200
-
-# 检查ES版本
-curl http://localhost:9200 | grep version
-
-# 确认配置
-cat .env | grep ES_
-```
-
-### Q3: 数据导入失败
-
-**症状**: `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
-```
-
-### Q4: 服务启动失败
-
-**症状**: `Address already in use` 或端口被占用
-
-**解决方案**:
-```bash
-# 查看占用端口的进程
-lsof -i :6002  # 后端
-lsof -i :6003  # 前端
-lsof -i :9200  # ES
-
-# 杀掉进程
-kill -9 <PID>
-
-# 或修改端口配置
-```
-
-### Q5: 模型下载慢或失败
-
-**症状**: 首次运行时模型下载很慢或超时
-
-**解决方案**:
-```bash
-# 跳过embedding快速测试
-./scripts/ingest.sh 1 true
-
-# 或手动下载模型到指定目录
-# TEXT_MODEL_DIR=/data/tw/models/bge-m3
-# IMAGE_MODEL_DIR=/data/tw/models/cn-clip
-```
-
-### Q6: 搜索无结果
-
-**症状**: 搜索返回空结果
-
-**解决方案**:
-```bash
-# 检查ES中是否有数据
-curl http://localhost:9200/search_products/_count
-
-# 检查tenant_id过滤是否正确
-curl -X POST http://localhost:6002/search/ \
-  -H "Content-Type: application/json" \
-  -d '{"query": "*", "size": 10, "debug": true}'
-
-# 查看调试信息
-```
-
-### Q7: 向量计算很慢
-
-**症状**: 生成embedding很慢
-
-**解决方案**:
-- 使用GPU加速（如果可用）
-- 减少批量大小
-- 启用向量缓存
-- 首次导入时跳过embedding，后续再生成
-
----
-
-## 下一步
-
-1. **查看API文档**: 参考 `API_INTEGRATION_GUIDE.md` 了解完整的API接口
-2. **查看字段说明**: 参考 `INDEX_FIELDS_DOCUMENTATION.md` 了解索引字段
-3. **查看设计文档**: 参考 `设计文档.md` 了解系统架构
-4. **自定义配置**: 编辑 `config/config.yaml` 调整搜索配置
-
----
-
-## 相关文档
-
-- **API接口文档**: `API_INTEGRATION_GUIDE.md` - 完整的API对接指南
-- **字段说明文档**: `INDEX_FIELDS_DOCUMENTATION.md` - 索引字段详细说明
-- **设计文档**: `设计文档.md` - 系统架构和设计说明
-- **README**: `README.md` - 项目概述和快速开始
-
----
-
-**文档版本**: v1.0  
-**最后更新**: 2024-12
-