## 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`。