# 使用指南

本文档提供完整的使用指南，包括环境准备、数据导入、服务启动、测试等。

## 目录

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