From 670c701f0ec255b609be6d2272e5efd27208bb73 Mon Sep 17 00:00:00 2001 From: tangwang Date: Fri, 14 Nov 2025 14:06:00 +0800 Subject: [PATCH] 文档完善 --- README.md | 659 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ 环境相关.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------------------------------------------------------- 2 files changed, 194 insertions(+), 652 deletions(-) diff --git a/README.md b/README.md index ad0ba55..fa3060c 100644 --- a/README.md +++ b/README.md @@ -1,616 +1,111 @@ -# 电商搜索引擎 SaaS 系统 +# 电商搜索引擎 SaaS -一个可配置的多租户搜索引擎，专为跨境电商独立站（店匠 Shoplazza）设计。 +一个针对跨境独立站（店匠 Shoplazza 等）的多租户可配置搜索平台。README 作为项目导航入口，帮助你在不同阶段定位到更详细的文档。 -## 系统特性 +## 核心能力速览 -- **多语言支持**：支持中文、英文、俄文、阿拉伯文、西班牙文、日文，支持自动翻译 -- **语义搜索**：基于 BGE-M3 文本向量和 CN-CLIP 图片向量的语义检索 -- **混合排序**：结合 BM25 文本相关性和语义相似度 -- **布尔表达式**：支持 AND、OR、RANK、ANDNOT 操作符，支持括号优先级 -- **灵活过滤**：精确匹配过滤器和数值范围过滤器 -- **分面搜索**：动态生成过滤选项，提供分组统计 -- **可配置化**：客户特定的字段定义、分析器、排序表达式 -- **多租户隔离**：通过 `tenant_id` 实现数据隔离，共享统一索引 -- **RESTful API**：基于 FastAPI 的完整 API 服务 -- **前端界面**：提供可视化搜索测试界面 +- **多语言 + 自动翻译**：中文、英文、俄文等语言检测与路由（BGE-M3、DeepL） +- **语义 + 关键词混排**：BM25、dense vector（BGE-M3/CN-CLIP）融合 +- **布尔与分面**：AND / OR / ANDNOT / RANK、Terms & Range facets +- **多租户隔离**：共享 `search_products` 索引，通过 `tenant_id` 严格隔离 +- **可配置化**：字段/索引域/排序表达式/查询改写全部配置驱动 +- **脚本化流水线**：Mock/CSV 数据 → MySQL → Elasticsearch → API/前端 -## 系统架构 +## 快速上手（概览） -### 数据模型 +| 步骤 | 去哪里看 | 摘要 | +|------|---------|------| +| 1. 准备环境 | `环境相关.md` / `USAGE_GUIDE.md` | Conda/依赖、Elasticsearch、MySQL、必需的变量 | +| 2. 构造测试数据 | `TEST_DATA_GUIDE.md` | Tenant1 Mock、Tenant2 CSV、`mock_data.sh` / `ingest.sh` | +| 3. 启动与验证 | `USAGE_GUIDE.md` | `run.sh` 一键启动、分步脚本、日志与健康检查 | +| 4. 理解架构 | `设计文档.md` | 数据流、配置系统、查询/搜索/索引模块 | +| 5. 接入搜索 API | `API_DOCUMENTATION.md` / `API_INTEGRATION_GUIDE.md` | REST 端点、参数、响应、最佳实践 | +| 6. 查字段定义 | `INDEX_FIELDS_DOCUMENTATION.md` | `search_products` 映射、字段来源、类型与用途 | -- **SPU 级别索引**：所有租户共享 `search_products` 索引 -- **嵌套结构**：每个 SPU 文档包含嵌套的 `variants` 数组（SKU 变体） -- **租户隔离**：通过 `tenant_id` 字段实现多租户数据隔离 -- **数据源**：MySQL 数据库（`shoplazza_product_spu` 和 `shoplazza_product_sku` 表） +> README 仅保留最常用命令的“索引”。细节以主题文档为准。 -### 技术栈 - -- **后端框架**：Python 3.8+ / FastAPI -- **搜索引擎**：Elasticsearch 8.x -- **数据库**：MySQL（店匠数据表） -- **向量模型**： - - 文本向量：BGE-M3（1024维） - - 图片向量：CN-CLIP（1024维） -- **翻译服务**：DeepL API -- **前端**：HTML + JavaScript - -## 快速开始 - -### 1. 环境准备 - -#### 安装依赖 - -```bash -pip install -r requirements.txt -``` - -#### 启动 Elasticsearch - -```bash -# 使用 Docker -docker run -d \ - --name elasticsearch \ - -p 9200:9200 \ - -e "discovery.type=single-node" \ - -e "ES_JAVA_OPTS=-Xms2g -Xmx2g" \ - elasticsearch:8.11.0 -``` - -#### 配置环境变量（可选） - -创建 `.env` 文件： +### Runtimes & 命令示例 ```bash -DB_HOST=120.79.247.228 -DB_PORT=3316 -DB_DATABASE=saas -DB_USERNAME=saas -DB_PASSWORD=your_password -ES_HOST=http://localhost:9200 -``` - -### 2. 脚本体系 - -项目提供统一的脚本系统，管理完整的工作流程： - -#### 脚本说明 +# 1. 安装依赖与准备服务 +pip install -r requirements.txt # 详见 USAGE_GUIDE.md +docker run -d --name es -p 9200:9200 elasticsearch:8.11.0 -| 脚本 | 功能 | 说明 | -|------|------|------| -| `restart.sh` | 重启服务 | 停止并重新启动前后端服务 | -| `run.sh` | 启动服务 | 启动前端和后端服务 | -| `scripts/mock_data.sh` | 数据导入 | 将 Mock 数据或 CSV 数据导入 MySQL | -| `scripts/ingest.sh` | 数据索引 | 从 MySQL 导入数据到 Elasticsearch | - -### 3. 手动启动 API 服务（可选） - -如果不想使用脚本，可以手动启动： - -```bash -python -m api.app \ - --host 0.0.0.0 \ - --port 6002 \ - --es-host http://localhost:9200 \ - --reload -``` +# 2. 构造测试数据并导入 MySQL +./scripts/mock_data.sh # 详见 TEST_DATA_GUIDE.md -### 4. 测试搜索 +# 3. 从 MySQL 注入到 Elasticsearch +./scripts/ingest.sh 1 true +./scripts/ingest.sh 2 true -#### 简单搜索 +# 4. 启动服务 +./run.sh -```bash +# 5. 调用文本搜索 API curl -X POST http://localhost:6002/search/ \ -H "Content-Type: application/json" \ - -d '{ - "query": "蓝牙耳机", - "size": 10 - }' -``` - -#### 带过滤器的搜索 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具", - "size": 10, - "filters": { - "categoryName_keyword": "玩具" - }, - "range_filters": { - "min_price": { - "gte": 50, - "lte": 200 - } - } - }' -``` - -#### 布尔表达式搜索 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "蓝牙 AND (耳机 OR 音响)", - "size": 10 - }' -``` - -#### 图片搜索 - -```bash -curl -X POST http://localhost:6002/search/image \ - -H "Content-Type: application/json" \ - -d '{ - "image_url": "https://oss.essa.cn/example.jpg", - "size": 10 - }' -``` - -#### 分面搜索 - -```bash -curl -X POST http://localhost:6002/search/ \ - -H "Content-Type: application/json" \ - -d '{ - "query": "玩具", - "size": 10, - "facets": [ - { - "field": "categoryName_keyword", - "label": "分类" - }, - { - "field": "brandName_keyword", - "label": "品牌" - } - ] - }' -``` - -## 项目结构 - -``` -SearchEngine/ -├── api/ # API 服务 -│ ├── app.py # FastAPI 应用主入口 -│ ├── models.py # 请求/响应模型 -│ └── routes/ # API 路由 -│ ├── search.py # 搜索接口 -│ └── admin.py # 管理接口 -├── config/ # 配置系统 -│ ├── field_types.py # 字段类型定义 -│ ├── config_loader.py # 配置加载器 -│ └── schema/ # 租户配置文件 -│ └── base/ # Base 配置（店匠通用） -│ └── config.yaml -├── indexer/ # 数据索引 -│ ├── mapping_generator.py # ES mapping 生成器 -│ ├── spu_transformer.py # SPU 数据转换器 -│ ├── bulk_indexer.py # 批量索引器 -│ └── ingest_shoplazza.py # 店匠数据导入脚本 -├── query/ # 查询处理 -│ ├── query_parser.py # 查询解析器 -│ ├── language_detector.py # 语言检测 -│ ├── translator.py # 翻译服务 -│ └── query_rewriter.py # 查询改写 -├── search/ # 搜索执行 -│ ├── searcher.py # 主搜索器 -│ ├── multilang_query_builder.py # 多语言查询构建器 -│ ├── boolean_parser.py # 布尔表达式解析器 -│ ├── es_query_builder.py # ES 查询构建器 -│ └── ranking_engine.py # 排序引擎 -├── embeddings/ # 向量编码 -│ ├── text_encoder.py # BGE-M3 文本编码器 -│ └── image_encoder.py # CN-CLIP 图片编码器 -├── utils/ # 工具类 -│ ├── db_connector.py # MySQL 连接器 -│ ├── es_client.py # ES 客户端封装 -│ └── cache.py # 向量缓存 -├── scripts/ # 脚本工具 -│ ├── mock_data.sh # Mock 数据导入脚本 -│ ├── ingest.sh # 数据索引脚本 -│ ├── generate_test_data.py # 生成测试数据 -│ ├── import_tenant2_csv.py # Tenant2 CSV 导入脚本 -│ └── import_test_data.py # 数据导入脚本 -├── frontend/ # 前端界面 -│ └── unified.html # 统一搜索界面 -├── data/ # 数据文件 -│ └── customer1/ # customer1 测试数据 -├── run.sh # 启动脚本 -├── restart.sh # 重启脚本 -└── requirements.txt # Python 依赖 -``` - -## 配置系统 - -### 配置文件结构 - -配置文件位于 `config/schema/{tenant_id}/config.yaml`，Base 配置位于 `config/schema/base/config.yaml`。 - -### 配置内容 - -#### 1. 字段定义 (fields) - -定义 ES 索引的字段结构： - -```yaml -fields: - title_zh: - type: TEXT - analyzer: chinese_ecommerce - index: true - store: true - boost: 2.0 - title_en: - type: TEXT - analyzer: english - index: true - store: true - categoryName_keyword: - type: KEYWORD - index: true - store: true - min_price: - type: FLOAT - index: true - store: true - title_embedding: - type: TEXT_EMBEDDING - dimension: 1024 - similarity: dot_product -``` - -#### 2. 查询域配置 (indexes) - -定义多域查询配置： - -```yaml -indexes: - default: - fields: ["title_zh", "title_en", "title_ru"] - weights: {"title_zh": 2.0, "title_en": 1.5} - title: - fields: ["title_zh", "title_en"] - brand: - fields: ["brandName_keyword"] -``` - -#### 3. 查询配置 (query_config) - -多语言和翻译配置： - -```yaml -query_config: - languages: ["zh", "en", "ru"] - auto_translate: true - translation_api: "deepl" - enable_embeddings: true - embedding_model: "bge-m3" -``` - -#### 4. 排序配置 (ranking) - -相关性排序表达式： - -```yaml -ranking: - expression: "bm25() + 0.2*text_embedding_relevance() + general_score*2" - enable_function_score: true -``` - -#### 5. SPU 配置 (spu_config) - -SPU 聚合配置： - -```yaml -spu_config: - enabled: true - spu_field: "product_id" - inner_hits_size: 3 -``` - -### 字段类型 - -| 类型 | 说明 | 示例 | -|------|------|------| -| `TEXT` | 文本字段，支持分词 | 商品标题、描述 | -| `KEYWORD` | 关键词字段，精确匹配 | 分类、品牌 | -| `TEXT_EMBEDDING` | 文本向量（1024维） | 语义搜索 | -| `IMAGE_EMBEDDING` | 图片向量（1024维） | 图片搜索 | -| `INT/LONG` | 整数类型 | 库存、ID | -| `FLOAT/DOUBLE` | 浮点数类型 | 价格 | -| `DATE` | 日期类型 | 创建时间 | -| `BOOLEAN` | 布尔类型 | 是否上架 | - -### 分析器 - -| 分析器 | 说明 | 适用语言 | -|--------|------|----------| -| `chinese_ecommerce` | 中文电商分词器（Ansj） | 中文 | -| `english` | 英文分析器 | 英文 | -| `russian` | 俄文分析器 | 俄文 | -| `arabic` | 阿拉伯文分析器 | 阿拉伯文 | -| `spanish` | 西班牙文分析器 | 西班牙文 | -| `japanese` | 日文分析器 | 日文 | -| `standard` | 标准分析器 | 通用 | -| `keyword` | 关键词分析器 | 精确匹配 | - -## API 接口 - -### 搜索接口 - -#### 1. 文本搜索 - -**端点**: `POST /search/` - -**请求示例**: - -```json -{ - "query": "蓝牙耳机", - "size": 10, - "from": 0, - "filters": { - "categoryName_keyword": "电子产品" - }, - "range_filters": { - "min_price": { - "gte": 50, - "lte": 500 - } - }, - "facets": [ - { - "field": "categoryName_keyword", - "label": "分类" - } - ], - "sort_by": "min_price", - "sort_order": "asc" -} + -H "X-Tenant-ID: 1" \ + -d '{"query": "玩具", "size": 10}' ``` -#### 2. 图片搜索 +## 文档地图 -**端点**: `POST /search/image` +| 文档 | 内容提要 | 适用场景 | +|------|----------|----------| +| `环境相关.md` | 系统要求、Conda/依赖、外部服务账号、常用端口 | 首次部署、环境核对 | +| `USAGE_GUIDE.md` | 环境准备、服务启动、配置、日志、验证手册 | 日常运维、调试 | +| `TEST_DATA_GUIDE.md` | 两个租户的模拟/CSV数据构造 & MySQL→ES流程 | 数据准备、联调 | +| `设计文档.md` | 架构、配置系统、索引/查询/排序模块细节 | 研发/扩展功能 | +| `INDEX_FIELDS_DOCUMENTATION.md` | `search_products` 字段、类型、来源、嵌套结构 | 新增字段、数据对齐 | +| `API_DOCUMENTATION.md` | REST API（搜索/图片/管理）详解、示例、响应格式 | API 使用、测试 | +| `API_INTEGRATION_GUIDE.md` | 客户对接指引、最佳实践、错误处理、语言说明 | 第三方集成、SDK 开发 | +| `API_QUICK_REFERENCE.md` | 常用请求体速查表 | 支持团队快速查阅 | +| `环境相关.md` + `.env` 模板 | 运行依赖账号、端口、密钥对照表 | 交付 & 运维 | -**请求示例**: +更多补充材料： -```json -{ - "image_url": "https://oss.essa.cn/example.jpg", - "size": 10, - "filters": { - "categoryName_keyword": "玩具" - } -} -``` - -#### 3. 获取文档 - -**端点**: `GET /search/{doc_id}` - -### 管理接口 - -#### 1. 健康检查 - -**端点**: `GET /admin/health` - -#### 2. 获取配置 - -**端点**: `GET /admin/config?tenant_id=1` - -#### 3. 索引统计 - -**端点**: `GET /admin/stats?tenant_id=1` - -#### 4. 查询改写规则 +- `TEST_DATA_GUIDE.md`：包含完整工作流脚本示例 +- `商品数据源入ES配置规范.md`：数据源映射约定 +- `MULTILANG_FEATURE.md`：多语言处理细节 -**端点**: -- `GET /admin/rewrite-rules?tenant_id=1` - 获取规则 -- `POST /admin/rewrite-rules` - 更新规则 +## 关键工作流指引 -详细 API 文档请参考 `API_DOCUMENTATION.md`。 +- **数据构建 → MySQL → Elasticsearch** + - `scripts/mock_data.sh`：Tenant1 Mock + Tenant2 CSV 一条龙 + - `scripts/ingest.sh [recreate]`：驱动 `indexer/` 模块写入 `search_products` + - 详解：`TEST_DATA_GUIDE.md` -## 高级功能 - -### 布尔表达式 - -支持的操作符（优先级从高到低）： - -1. `()` - 括号 -2. `ANDNOT` - 排除 -3. `AND` - 必须全部匹配 -4. `OR` - 任意匹配 -5. `RANK` - 排序提升 - -**示例**: - -``` -蓝牙 AND (耳机 OR 音响) ANDNOT 便宜 -laptop AND (gaming OR professional) ANDNOT cheap -``` - -### 查询改写 - -配置品牌/分类映射： - -```yaml -rewrite_dictionary: - "苹果": "brand:苹果 OR name:iPhone" - "玩具": "category:玩具" -``` +- **搜索服务 & API** + - `api/`（FastAPI）承载 REST API，`search/` + `query/` 负责查询解析与下发 + - API、分页、过滤、Facet、KNN 等：`API_DOCUMENTATION.md` + - 对接案例与错误码：`API_INTEGRATION_GUIDE.md` -### 排序表达式 +- **配置驱动能力** + - `config/schema/{tenant_id}/config.yaml`：字段定义、索引域、排序表达式、SPU 聚合 + - 详解与设计理念：`设计文档.md`、`INDEX_FIELDS_DOCUMENTATION.md` -可配置的相关性排序： +## 仓库结构（概览） ``` -bm25() + 0.2*text_embedding_relevance() + general_score*2 + timeliness(end_time) +api/ FastAPI 服务与路由 +config/ 字段/索引/查询配置体系 +indexer/ MySQL → ES 管道（mapping / transformer / bulk） +query/ 查询解析、改写、翻译、embedding +search/ 多语言构建、布尔解析、排序引擎 +scripts/ 数据/服务脚本（mock_data, ingest, run 等） +frontend/ 简易调试页面 +docs/ 运营及中文资料 ``` -支持的函数： -- `bm25()` - BM25 相关性分数 -- `text_embedding_relevance()` - 文本向量相似度 -- `image_embedding_relevance()` - 图片向量相似度 -- `field_value(field_name)` - 字段值 -- `timeliness(date_field)` - 时间衰减 - -### 多语言查询 - -系统自动检测查询语言，并支持： - -- **自动翻译**：将查询翻译到配置的所有语言 -- **语言路由**：根据语言选择对应的字段 -- **混合查询**：同时查询多个语言字段 - -### SPU 聚合 - -启用 SPU 聚合后，每个 SPU 只返回一个代表性 SKU： - -```yaml -spu_config: - enabled: true - spu_field: "product_id" - inner_hits_size: 3 # 每个 SPU 内部返回的 SKU 数量 -``` - -## 数据导入 - -### MySQL 表结构 - -系统使用店匠的标准表结构： - -- **SPU 表**: `shoplazza_product_spu` -- **SKU 表**: `shoplazza_product_sku` - -### 数据导入流程 - -1. **生成 SQL**：使用 `scripts/generate_test_data.py` 或 `scripts/import_tenant2_csv.py` 生成 SQL 文件 -2. **导入 MySQL**：使用 `scripts/mock_data.sh` 或 `scripts/import_test_data.py` 导入数据 -3. **索引到 ES**：使用 `scripts/ingest.sh` 或 `scripts/ingest_shoplazza.py` 将数据索引到 Elasticsearch - -### CSV 数据格式 - -CSV 文件应包含以下字段： - -- `skuId` - SKU ID -- `name` - 商品名称（中文） -- `name_pinyin` - 拼音 -- `create_time` - 创建时间 -- `ruSkuName` - 俄文名称 -- `enSpuName` - 英文名称 -- `categoryName` - 分类名称 -- `supplierName` - 供应商名称 -- `brandName` - 品牌名称 -- `file_id` - 文件 ID -- `id` - 商品 ID -- `imageUrl` - 图片 URL - -## 性能优化 - -### 1. 向量缓存 - -启用向量缓存可以避免重复计算： - -```python -# 在配置中启用缓存 -cache: - enabled: true - ttl: 3600 # 缓存过期时间（秒） -``` +## 常用参考 -### 2. 批量处理 - -调整批量大小以优化性能： - -- **数据转换批量大小**：默认 100（根据内存调整） -- **索引批量大小**：默认 500（根据 ES 性能调整） - -### 3. GPU 加速 - -使用 GPU 加速向量计算： - -```bash -# 安装 CUDA 版本的 PyTorch -pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 -``` - -### 4. ES 分片配置 - -根据数据量配置 ES 分片： - -```yaml -# 在 mapping 生成器中配置 -settings: - number_of_shards: 3 - number_of_replicas: 1 -``` - -## 开发指南 - -### 运行测试 - -```bash -pytest tests/ -``` - -### 代码格式化 - -```bash -black . -``` - -### 类型检查 - -```bash -mypy . -``` - -### 日志查看 - -```bash -# 查看服务日志 -tail -f logs/search_service.log -``` - -## 常见问题 - -### 1. 如何添加新的租户？ - -1. 创建配置文件 `config/schema/{tenant_id}/config.yaml` -2. 导入数据到 MySQL（使用 `scripts/mock_data.sh`） -3. 索引数据到 ES（使用 `scripts/ingest.sh {tenant_id}`） - -### 2. 如何修改排序规则？ - -编辑配置文件中的 `ranking.expression` 字段。 - -### 3. 如何添加新的分析器？ - -在 `config/field_types.py` 中定义新的分析器，然后在字段配置中使用。 - -### 4. 向量计算很慢怎么办？ - -- 启用向量缓存 -- 使用 GPU 加速 -- 减少批量大小 - -### 5. 如何调试搜索查询？ - -在 API 请求中设置 `debug: true`，返回详细的调试信息。 - -## 相关文档 - -- **API 文档**: `API_DOCUMENTATION.md` -- **设计文档**: `设计文档.md` -- **部署指南**: `DEPLOYMENT.md` -- **用户指南**: `USER_GUIDE.md` +- **运行/排障**：`USAGE_GUIDE.md`、`环境相关.md` +- **功能设计**：`设计文档.md` +- **字段/数据对齐**：`INDEX_FIELDS_DOCUMENTATION.md` +- **API 对接**：`API_DOCUMENTATION.md`、`API_INTEGRATION_GUIDE.md` +- **测试数据**：`TEST_DATA_GUIDE.md` ## 许可证 专有软件 - 保留所有权利 + diff --git a/环境相关.md b/环境相关.md index 9f04a3c..841674a 100644 --- a/环境相关.md +++ b/环境相关.md @@ -1,76 +1,123 @@ -环境使用： + + +## 2. Python 运行环境 + +```bash +# 1. 激活 Conda source /home/tw/miniconda3/etc/profile.d/conda.sh conda activate searchengine +# 如果部署到新机器，不存在 searchengine 环境时，需要初始化环境： +cd /home/tw/SearchEngine +pip install -r requirements.txt +``` + +--- + +## 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=essa +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 `essa`, password `4hOaLaf41y2VuI8y` | +| **Redis（可选）** | host `localhost`, port `6479`, password `BMfv5aI31kgHWtlx` | +| **DeepL** | `c9293ab4-ad25-479b-919f-ab4e63b429ed` | + +> 所有凭证仅用于本地/测试环境，生产环境需替换并妥善保管。 + +--- + +## 6. 店匠数据源说明 + +SearchEngine 以 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. 相关脚本 + +- `scripts/mock_data.sh`：一次性生成 Tenant1 Mock + Tenant2 CSV 数据并导入 MySQL +- `scripts/ingest.sh [recreate]`：从 MySQL 写入 Elasticsearch +- `run.sh` / `restart.sh`：服务启动/重启 + +更多脚本参数、日志与验证命令参见 `USAGE_GUIDE.md` 与 `TEST_DATA_GUIDE.md`。 -店匠是类似于shopify的独立站SAAS。我们要为基于店匠的独立站（一般为跨境电商独立站）做搜索SAAS。 - - -## 商品数据 - 数据源 - mysql -店匠的商品结构如下： - -数据库配置： - -## mysql数据源 -host: 120.79.247.228 -port: 3316 -username: saas -password: P89cZHS5d7dFyc9R - - -ES_CONFIG = { - 'host': 'http://localhost:9200', - 'username': 'essa', - 'password': '4hOaLaf41y2VuI8y' -} - -REDIS_CONFIG = { - 'host': 'localhost', - 'port': 6479, - 'password': 'BMfv5aI31kgHWtlx' -} - -DEEPL_AUTH_KEY = "c9293ab4-ad25-479b-919f-ab4e63b429ed" - - - - - -### 店匠主表 -shoplazza_product_sku -shoplazza_product_spu - -主表sku表的结构为： -id bigint(20) -spu_id bigint(20) -shop_id bigint(20) -shoplazza_id varchar(64) -shoplazza_product_id varchar(64) -shoplazza_image_id varchar(64) -title varchar(500) -sku varchar(100) -barcode varchar(100) -position int(11) -price decimal(10,2) -compare_at_price decimal(10,2) -cost_price decimal(10,2) -option1 varchar(255) -option2 varchar(255) -option3 varchar(255) -inventory_quantity int(11) -weight decimal(10,2) -weight_unit varchar(10) -image_src varchar(500) -wholesale_price json -note text -extend json -shoplazza_created_at datetime -shoplazza_updated_at datetime -tenant_id bigint(20) -creator varchar(64) -create_time datetime -updater varchar(64) -update_time datetime -deleted bit(1) -- libgit2 0.21.2