# 使用指南
  
  本文档提供完整的使用指南，包括环境准备、数据导入、服务启动、测试等。
  
  ## 目录
  
  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