## 1. 系统要求

- **操作系统**：Linux（推荐 Ubuntu 18.04+）
- **Conda**：Miniconda3 或 Anaconda（用于 Python 环境隔离）
- **Python**：3.10（由 Conda 环境提供）
- **内存**：建议 8GB+（含模型与 ES）
- **磁盘**：10GB+（含模型与索引）

---

## 2. Python 运行环境

本项目历史上使用 Conda 管理环境；目前推荐使用 **venv**（更轻量、对 CI/容器更友好）。项目根目录下的 `activate.sh` 已升级为 **优先激活 `.venv`，并兼容 Conda 回退**，且会自动加载当前目录下的 `.env`（忽略注释与空行）。

### 2.1 venv（推荐）

首次创建 venv：

```bash
cd /data/saas-search
./scripts/create_venv.sh
source activate.sh
```

如需运行本地 embedding / 图像编码服务（torch/transformers 等依赖较重）：

```bash
cd /data/saas-search
INSTALL_ML=1 ./scripts/create_venv.sh
source activate.sh
```

日常使用：

```bash
cd /data/saas-search
source activate.sh
```

### 2.2 Conda（兼容旧流程）

`activate.sh` 会在未发现 `.venv` 时回退激活 Conda 环境 `searchengine`。若在新机器上部署，请先设置本机 Conda 路径再执行：

```bash
# 你的 conda 在 ~/anaconda3/bin/conda，则 CONDA_ROOT=~/anaconda3
export CONDA_ROOT=$HOME/anaconda3   # 或你的 Conda 安装路径（如 /home/ubuntu/anaconda3）
source activate.sh
```

**新机器首次部署（创建 Conda 环境）**：若本机尚未创建 `searchengine` 环境，任选其一：

- **方式 A（推荐，与 environment.yml 一致）**：
  ```bash
  cd /data/saas-search
  export CONDA_ROOT=$HOME/anaconda3   # 或你的 Conda 安装路径
  conda env create -f environment.yml
  source activate.sh
  ```
- **方式 B（仅 pip）**：
  ```bash
  conda create -n searchengine python=3.10 -y
  conda activate searchengine
  cd /data/saas-search
  pip install -r requirements.txt
  ```

之后日常使用执行 `source activate.sh` 即可（如需可先 `export CONDA_ROOT=...`）。

---

## 3. 外部服务与端口

| 服务 | 默认地址 | 说明 |
|------|----------|------|
| Elasticsearch | `http://localhost:9200` | 可通过 Docker 单节点启动 |
| MySQL | `120.79.247.228:3316` | 存放店匠 SPU/SKU 数据 |
| Redis（可选） | `localhost:6479` | Embedding/翻译缓存 |

示例：使用 Docker 启动 Elasticsearch

```bash
docker run -d \
  --name elasticsearch \
  -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \
  elasticsearch:8.11.0
```

---

## 4. 环境变量与 `.env` 模板

在项目根目录创建 `.env`，并根据环境替换敏感信息：

```env
# MySQL
DB_HOST=120.79.247.228
DB_PORT=3316
DB_DATABASE=saas
DB_USERNAME=saas
DB_PASSWORD=P89cZHS5d7dFyc9R

# Elasticsearch
ES_HOST=http://localhost:9200
ES_USERNAME=saas
ES_PASSWORD=4hOaLaf41y2VuI8y

# Redis（可选）
REDIS_HOST=localhost
REDIS_PORT=6479
REDIS_PASSWORD=BMfv5aI31kgHWtlx

# DeepL 翻译
DEEPL_AUTH_KEY=c9293ab4-ad25-479b-919f-ab4e63b429ed

# API
API_HOST=0.0.0.0
API_PORT=6002
```

---

## 5. 服务凭证速查

| 项目 | 值 |
|------|----|
| **MySQL** | host `120.79.247.228`, port `3316`, user `saas`, password `P89cZHS5d7dFyc9R` |
| **Elasticsearch** | host `http://localhost:9200`, user `saas`, password `4hOaLaf41y2VuI8y` |
| **Redis（可选）** | host `localhost`, port `6479`, password `BMfv5aI31kgHWtlx` |
| **DeepL** | `c9293ab4-ad25-479b-919f-ab4e63b429ed` |

> 所有凭证仅用于本地/测试环境，生产环境需替换并妥善保管。

---

## 6. 店匠数据源说明

saas-search 以 MySQL 中的店匠标准表为权威数据源：

- `shoplazza_product_spu`：SPU 商品主表
- `shoplazza_product_sku`：SKU 变体表

### `shoplazza_product_sku` 字段节选

| 字段 | 类型 | 描述 |
|------|------|------|
| `id` | bigint(20) | SKU 主键 |
| `spu_id` | bigint(20) | 对应 SPU |
| `shop_id` | bigint(20) | 店铺 ID |
| `shoplazza_product_id` | varchar(64) | 店匠商品 ID |
| `title` | varchar(500) | 变体标题 |
| `sku` | varchar(100) | SKU 编码 |
| `price` | decimal(10,2) | 售价 |
| `compare_at_price` | decimal(10,2) | 原价 |
| `option1/2/3` | varchar(255) | 颜色/尺码等选项 |
| `inventory_quantity` | int(11) | 库存 |
| `image_src` | varchar(500) | 图片 |
| `tenant_id` | bigint(20) | 租户 |
| `create_time` | datetime | 创建时间 |
| `update_time` | datetime | 更新时间 |
| `deleted` | bit(1) | 逻辑删除标记 |

> 完整字段、索引映射与 ES 对应关系详见 `INDEX_FIELDS_DOCUMENTATION.md`。

---

## 7. 相关脚本

- **`activate.sh`**（项目根目录）：激活 Conda 环境 `searchengine` 并加载 `.env`，**日常开发/部署以本脚本为准**。
- `scripts/mock_data.sh`：一次性生成 Tenant1 Mock + Tenant2 CSV 数据并导入 MySQL
- `scripts/ingest.sh <tenant_id> [recreate]`：从 MySQL 写入 Elasticsearch
- `run.sh` / `restart.sh`：服务启动/重启（内部会调用 `start_backend.sh` 等，同样使用 `CONDA_ROOT`）

**新机器部署**：若 Conda 未安装在默认路径（如 `/home/tw/miniconda3`），请在执行上述脚本前设置 `CONDA_ROOT`。例如你的 conda 是 `~/anaconda3/bin/conda`（即 `/home/ubuntu/anaconda3/bin/conda`），则设置：`export CONDA_ROOT=$HOME/anaconda3`。可将该行写入 `~/.bashrc` 或部署说明。

更多脚本参数、日志与验证命令参见 `Usage-Guide.md` 与 `测试数据指南.md`。