电商搜索引擎 SaaS

多租户、可配置、可扩展的电商搜索平台（Shoplazza 等独立站场景）。

README 用于给后续开发者建立统一认知：系统框架、模块边界、设计原则、研发流程与 CI 测试入口，帮助持续迭代时避免分叉设计与冗余代码。

---

1) 项目目标与边界

• 目标：在统一架构下支持关键词检索、语义检索、分面过滤、多语言、重排、图片检索。
• 边界：本仓库负责搜索核心能力与服务编排；业务方通过标准 HTTP API 对接。
• 核心约束：
  • 调用方稳定（API/Provider 契约优先）
  • 配置单一来源（config/config.yaml + .env 覆盖）
  • 扩展优先走插件化（provider/backend），避免散落式分叉实现

---

2) 快速开始

# 首次创建环境（默认基础依赖）
./scripts/create_venv.sh
./scripts/init_env.sh   # 从 .env.example 生成本地 .env（若不存在）
source activate.sh

# 推荐：一键拉起全部服务（含监控守护）
./run.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh up all

# 查看状态 + 健康检查（含 monitor daemon 状态）
./status.sh          # 薄封装：等价于 ./scripts/service_ctl.sh status

# 重启指定服务集合（示例：全部）
./restart.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh restart all

# 一键停止（含 monitor daemon）
./scripts/stop.sh all    # 薄封装：等价于 ./scripts/service_ctl.sh down all

服务管理全盘说明（入口职责、默认行为、全量启停方式）见：

• docs/Usage-Guide.md -> 服务管理总览

核心端口：

• 6002 backend（/search/*, /admin/*）
• 6004 indexer（/indexer/*）
• 6003 frontend
• 6010 eval-web（搜索评估 UI，./scripts/service_ctl.sh 服务名 eval-web）
• 6005 embedding（可选）
• 6006 translator（可选）
• 6007 reranker（可选）

更完整示例见 docs/QUICKSTART.md。

---

3) 总体架构（开发者视角）

• api/：统一 API 入口（search/admin/indexer app）
• search/：召回、排序、结果组织
• query/：查询解析、多语言处理、改写
• indexer/：MySQL 行数据 -> ES 文档的转换与索引流程
• providers/：能力调用抽象（embedding/rerank）
• translation/：翻译服务客户端、服务编排与后端实现
• reranker/：重排服务及后端实现
• embeddings/：向量服务（文本/图像）
• config/：配置加载与服务配置解析

关键设计：

• embedding / rerank 继续采用 Provider（调用方式）与 Backend（推理实现）分离
• translation 采用 一个 translator service + 多个 capability backend，业务侧统一调用 6006，不再做翻译 provider 选择

---

4) 设计原则（避免后续分叉）

• 单一配置源：服务地址、provider 选择、后端参数统一在 config/config.yaml，环境变量仅做覆盖。
• 接口契约优先：外部 API 契约与 provider 契约稳定，内部重构不影响调用方。
• 扩展走工厂：新增 provider/backend 必须在工厂函数中显式注册，禁止旁路分支。
• 简洁和规范优先：对待异常情况，分情况而定，如果是系统启动期间、加载资源/配置等出错，可以尽早暴露问题，不要fallback走一套跟配置不符合的另外一套机制，即尽量保证逻辑清晰、简洁；但是线上的服务如果遇到异常情况可以根据最佳实践选取应对方法，比如记录错误日志并且保证服务正常运行。规范优先，尽量用一套机制满足需求，而不是兼容各种不合理的情况，对于不合理的内容优先清理、重构，而不是兼容，以保证代码是简洁的。
• 可观测性优先：健康检查、关键日志、请求上下文必须可追踪。
• 测试优先保障契约：CI 首先保证接口契约和核心路径可用，再逐步扩展性能与业务测试。

---

5) 文档入口（建议阅读顺序）

步骤	文档
0. 全局规范（首读）	docs/DEVELOPER_GUIDE.md
1. 开发与配置	docs/QUICKSTART.md
2. 运行与排障	docs/Usage-Guide.md
3. API 详细说明	docs/搜索API对接指南.md
4. 快速参数速查	docs/搜索API速查表.md
5. 翻译专项	docs/翻译模块说明.md
6. 首次环境搭建、生产凭证	docs/QUICKSTART.md §1.4–1.8
7. TEI 文本向量专项	docs/TEI_SERVICE说明文档.md
8. CN-CLIP 图片向量专项	docs/CNCLIP_SERVICE说明文档.md

---

6) 持续集成测试（推荐最小集）

本仓库提供一套轻量、稳定、易维护的 CI 测试入口，覆盖以下服务契约：

• 搜索接口（search API）
• 索引接口（indexer API）
• 向量服务（embedding service）
• 翻译服务（translator service）
• 重排服务（reranker service）

本地运行：

source activate.sh
python -m pytest tests/ci -q

该测试集采用 mock/stub，不依赖真实 ES/MySQL/大模型服务，适合作为 PR 级快速回归门禁。

---

7) 代码质量与持续继承要求

• 新增功能必须补最小测试（至少覆盖 1 条成功路径 + 1 条参数异常路径）
• 修改公共协议时必须同步更新：
  • docs/QUICKSTART.md
  • 对应服务 README / API 文档
  • tests/ci 契约用例
• 禁止新增“临时分支逻辑”绕过 provider/backend 工厂
• 优先减少重复实现，复用现有转换链路与配置解析入口