tangwang · tangwang · tangwang
Showing 48 changed files Show diff stats
api/app.py
api/indexer_app.py
api/routes/admin.py
config/__init__.py
config/config.yaml
config/config_loader.py
config/dictionaries/query_rewrite.dict
config/env_config.py
config/loader.py
config/query_rewrite.dict
config/schema.py
config/services_config.py
config/tenant_config_loader.py
config/utils.py
docs/config-system-review-and-redesign.md
docs/搜索API对接指南-00-总览与快速开始.md
docs/搜索API对接指南-01-搜索接口.md
docs/搜索API对接指南-02-搜索建议与即时搜索.md
docs/搜索API对接指南-03-获取文档.md
docs/搜索API对接指南-05-索引接口（Indexer）.md
@@ -86,8 +86,7 @@ limiter = Limiter(key_func=get_remote_address)
 # Add parent directory to path
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-from config.env_config import ES_CONFIG, DB_CONFIG
-from config import ConfigLoader
+from config import get_app_config
 from utils import ESClient
 from search import Searcher
 from query import QueryParser
@@ -99,7 +98,7 @@ _es_client: Optional[ESClient] = None
 _searcher: Optional[Searcher] = None
 _query_parser: Optional[QueryParser] = None
 _suggestion_service: Optional[SuggestionService] = None
-_config = None
+_app_config = None
 def init_service(es_host: str = "http://localhost:9200"):
@@ -109,20 +108,20 @@ def init_service(es_host: str = &quot;http://localhost:9200&quot;):
     Args:
         es_host: Elasticsearch host URL
     """
-    global _es_client, _searcher, _query_parser, _suggestion_service, _config
+    global _es_client, _searcher, _query_parser, _suggestion_service, _app_config
     start_time = time.time()
     logger.info("Initializing search service (multi-tenant)")
     # Load configuration
     logger.info("Loading configuration...")
-    config_loader = ConfigLoader("config/config.yaml")
-    _config = config_loader.load_config()
+    _app_config = get_app_config()
+    search_config = _app_config.search
     logger.info("Configuration loaded")
     # Get ES credentials
-    es_username = os.getenv('ES_USERNAME') or ES_CONFIG.get('username')
-    es_password = os.getenv('ES_PASSWORD') or ES_CONFIG.get('password')
+    es_username = _app_config.infrastructure.elasticsearch.username
+    es_password = _app_config.infrastructure.elasticsearch.password
     # Connect to Elasticsearch
     logger.info(f"Connecting to Elasticsearch at {es_host}...")
@@ -139,15 +138,15 @@ def init_service(es_host: str = &quot;http://localhost:9200&quot;):
     # Initialize components
     logger.info("Initializing query parser...")
-    _query_parser = QueryParser(_config)
+    _query_parser = QueryParser(search_config)
     logger.info("Initializing searcher...")
-    _searcher = Searcher(_es_client, _config, _query_parser)
+    _searcher = Searcher(_es_client, search_config, _query_parser)
     logger.info("Initializing suggestion service...")
     _suggestion_service = SuggestionService(_es_client)
     elapsed = time.time() - start_time
-    logger.info(f"Search service ready! (took {elapsed:.2f}s) | Index: {_config.es_index_name}")
+    logger.info(f"Search service ready! (took {elapsed:.2f}s) | Index: {search_config.es_index_name}")
@@ -182,9 +181,9 @@ def get_suggestion_service() -&gt; SuggestionService:
 def get_config():
     """Get global config instance."""
-    if _config is None:
+    if _app_config is None:
         raise RuntimeError("Service not initialized")
-    return _config
+    return _app_config
 # Create FastAPI app with enhanced configuration
@@ -240,7 +239,7 @@ async def startup_event():
     except Exception as e:
         logger.warning(f"Failed to set thread pool size: {e}, using default")
-    es_host = os.getenv("ES_HOST", "http://localhost:9200")
+    es_host = get_app_config().infrastructure.elasticsearch.host
     logger.info("Starting E-Commerce Search API (Multi-Tenant)")
     logger.info(f"Elasticsearch Host: {es_host}")
@@ -38,8 +38,7 @@ logger = logging.getLogger(__name__)
 # Add parent directory to path
 sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-from config.env_config import ES_CONFIG  # noqa: E402
-from config import ConfigLoader  # noqa: E402
+from config import get_app_config  # noqa: E402
 from utils import ESClient  # noqa: E402
 from utils.db_connector import create_db_connection  # noqa: E402
 from indexer.incremental_service import IncrementalIndexerService  # noqa: E402
@@ -55,7 +54,7 @@ from .service_registry import (
 _es_client: Optional[ESClient] = None
-_config = None
+_app_config = None
 _incremental_service: Optional[IncrementalIndexerService] = None
 _bulk_indexing_service: Optional[BulkIndexingService] = None
 _suggestion_builder: Optional[SuggestionIndexBuilder] = None
@@ -68,20 +67,19 @@ def init_indexer_service(es_host: str = &quot;http://localhost:9200&quot;):
     This mirrors the indexing-related initialization logic in api.app.init_service
     but without search-related components.
     """
-    global _es_client, _config, _incremental_service, _bulk_indexing_service, _suggestion_builder
+    global _es_client, _app_config, _incremental_service, _bulk_indexing_service, _suggestion_builder
     start_time = time.time()
     logger.info("Initializing Indexer service")
     # Load configuration (kept for parity/logging; indexer routes don't depend on it)
     logger.info("Loading configuration...")
-    config_loader = ConfigLoader("config/config.yaml")
-    _config = config_loader.load_config()
+    _app_config = get_app_config()
     logger.info("Configuration loaded")
     # Get ES credentials
-    es_username = os.getenv("ES_USERNAME") or ES_CONFIG.get("username")
-    es_password = os.getenv("ES_PASSWORD") or ES_CONFIG.get("password")
+    es_username = _app_config.infrastructure.elasticsearch.username
+    es_password = _app_config.infrastructure.elasticsearch.password
     # Connect to Elasticsearch
     logger.info(f"Connecting to Elasticsearch at {es_host} for indexer...")
@@ -97,11 +95,12 @@ def init_indexer_service(es_host: str = &quot;http://localhost:9200&quot;):
     set_es_client(_es_client)
     # Initialize indexing services (DB is required here)
-    db_host = os.getenv("DB_HOST")
-    db_port = int(os.getenv("DB_PORT", 3306))
-    db_database = os.getenv("DB_DATABASE")
-    db_username = os.getenv("DB_USERNAME")
-    db_password = os.getenv("DB_PASSWORD")
+    db_config = _app_config.infrastructure.database
+    db_host = db_config.host
+    db_port = db_config.port
+    db_database = db_config.database
+    db_username = db_config.username
+    db_password = db_config.password
     if all([db_host, db_database, db_username, db_password]):
         logger.info("Initializing database connection for indexing services...")
@@ -166,7 +165,7 @@ async def startup_event():
     except Exception as e:
         logger.warning(f"Failed to set thread pool size: {e}, using default")
-    es_host = os.getenv("ES_HOST", "http://localhost:9200")
+    es_host = get_app_config().infrastructure.elasticsearch.host
     logger.info("Starting Indexer API service")
     logger.info(f"Elasticsearch Host: {es_host}")
     try:
@@ -176,14 +175,11 @@ async def startup_event():
         # Eager warmup: build per-tenant transformer bundles at startup to avoid
         # first-request latency (config/provider/encoder + transformer wiring).
         try:
-            if _incremental_service is not None and _config is not None:
+            if _incremental_service is not None and _app_config is not None:
                 tenants = []
-                # config.tenant_config shape: {"default": {...}, "tenants": {"1": {...}, ...}}
-                tc = getattr(_config, "tenant_config", None) or {}
-                if isinstance(tc, dict):
-                    tmap = tc.get("tenants")
-                    if isinstance(tmap, dict):
-                        tenants = [str(k) for k in tmap.keys()]
+                tmap = _app_config.tenants.tenants
+                if isinstance(tmap, dict):
+                    tenants = [str(k) for k in tmap.keys()]
                 # If no explicit tenants configured, skip warmup.
                 if tenants:
                     warm = _incremental_service.warmup_transformers(tenants)
@@ -3,7 +3,6 @@ Admin API routes for configuration and management.
 """
 from fastapi import APIRouter, HTTPException, Request
-from typing import Dict
 from ..models import HealthResponse, ErrorResponse
 from indexer.mapping_generator import get_tenant_index_name
@@ -42,22 +41,12 @@ async def health_check():
 @router.get("/config")
 async def get_configuration():
     """
-    Get current search configuration (sanitized).
+    Get the effective application configuration (sanitized).
     """
     try:
         from ..app import get_config
-        config = get_config()
-
-        return {
-            "es_index_name": config.es_index_name,
-            "num_field_boosts": len(config.field_boosts),
-            "multilingual_fields": config.query_config.multilingual_fields,
-            "shared_fields": config.query_config.shared_fields,
-            "core_multilingual_fields": config.query_config.core_multilingual_fields,
-            "supported_languages": config.query_config.supported_languages,
-            "spu_enabled": config.spu_config.enabled
-        }
+        return get_config().sanitized_dict()
     except HTTPException:
         raise
@@ -65,45 +54,21 @@ async def get_configuration():
         raise HTTPException(status_code=500, detail=str(e))
-@router.post("/rewrite-rules")
-async def update_rewrite_rules(rules: Dict[str, str]):
-    """
-    Update query rewrite rules.
-
-    Args:
-        rules: Dictionary of pattern -> replacement mappings
-    """
+@router.get("/config/meta")
+async def get_configuration_meta():
+    """Get configuration metadata for observability."""
     try:
-        from ..app import get_query_parser
-
-        query_parser = get_query_parser()
-        query_parser.update_rewrite_rules(rules)
-
-        return {
-            "status": "success",
-            "message": f"Updated {len(rules)} rewrite rules"
-        }
-
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
-
-
-@router.get("/rewrite-rules")
-async def get_rewrite_rules():
-    """
-    Get current query rewrite rules.
-    """
-    try:
-        from ..app import get_query_parser
-
-        query_parser = get_query_parser()
-        rules = query_parser.get_rewrite_rules()
+        from ..app import get_config
+        config = get_config()
         return {
-            "rules": rules,
-            "count": len(rules)
+            "environment": config.runtime.environment,
+            "config_hash": config.metadata.config_hash,
+            "loaded_files": list(config.metadata.loaded_files),
+            "deprecated_keys": list(config.metadata.deprecated_keys),
         }
-
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
-"""
-Configuration package for search engine.
+"""Unified configuration package exports."""
-Provides configuration loading, validation, and utility functions.
-"""
-
-from .config_loader import (
-    SearchConfig,
-    QueryConfig,
-    IndexConfig,
-    SPUConfig,
+from config.config_loader import ConfigLoader, ConfigurationError
+from config.loader import AppConfigLoader, get_app_config, reload_app_config
+from config.schema import (
+    AppConfig,
     FunctionScoreConfig,
+    IndexConfig,
+    QueryConfig,
     RerankConfig,
-    ConfigLoader,
-    ConfigurationError
-)
-
-from .utils import (
-    get_match_fields_for_index,
-    get_domain_fields
+    SPUConfig,
+    SearchConfig,
+    ServicesConfig,
 )
-from .services_config import (
-    get_translation_config,
-    get_embedding_config,
-    get_rerank_config,
+from config.services_config import (
     get_embedding_backend_config,
-    get_rerank_backend_config,
-    get_translation_base_url,
-    get_embedding_text_base_url,
+    get_embedding_config,
+    get_embedding_image_backend_config,
     get_embedding_image_base_url,
+    get_embedding_text_base_url,
+    get_rerank_backend_config,
+    get_rerank_config,
     get_rerank_service_url,
+    get_translation_base_url,
     get_translation_cache_config,
-    ServiceConfig,
+    get_translation_config,
 )
+from config.utils import get_domain_fields, get_match_fields_for_index
 __all__ = [
-    # Main config classes
-    'SearchConfig',
-    'QueryConfig',
-    'IndexConfig',
-    'SPUConfig',
-    'FunctionScoreConfig',
-    'RerankConfig',
-    
-    # Loader and utilities
-    'ConfigLoader',
-    'ConfigurationError',
-    'get_match_fields_for_index',
-    'get_domain_fields',
-    'get_translation_config',
-    'get_embedding_config',
-    'get_rerank_config',
-    'get_embedding_backend_config',
-    'get_rerank_backend_config',
-    'get_translation_base_url',
-    'get_embedding_text_base_url',
-    'get_embedding_image_base_url',
-    'get_rerank_service_url',
-    'get_translation_cache_config',
-    'ServiceConfig',
+    "AppConfig",
+    "AppConfigLoader",
+    "ConfigLoader",
+    "ConfigurationError",
+    "FunctionScoreConfig",
+    "IndexConfig",
+    "QueryConfig",
+    "RerankConfig",
+    "SPUConfig",
+    "SearchConfig",
+    "ServicesConfig",
+    "get_app_config",
+    "reload_app_config",
+    "get_domain_fields",
+    "get_match_fields_for_index",
+    "get_translation_config",
+    "get_embedding_config",
+    "get_rerank_config",
+    "get_embedding_backend_config",
+    "get_embedding_image_backend_config",
+    "get_rerank_backend_config",
+    "get_translation_base_url",
+    "get_embedding_text_base_url",
+    "get_embedding_image_base_url",
+    "get_rerank_service_url",
+    "get_translation_cache_config",
 ]
@@ -5,6 +5,14 @@
 # Elasticsearch Index
 es_index_name: "search_products"
+# Config assets
+assets:
+  query_rewrite_dictionary_path: "config/dictionaries/query_rewrite.dict"
+
+# Product content understanding (LLM enrich-content) configuration
+product_enrich:
+  max_workers: 40
+
 # ES Index Settings (基础设置)
 es_settings:
   number_of_shards: 1
@@ -211,6 +219,19 @@ services:
         device: "cuda"
         batch_size: 32
         normalize_embeddings: true
+    # 服务内图片后端（embedding 进程启动时读取）
+    image_backend: "clip_as_service"  # clip_as_service | local_cnclip
+    image_backends:
+      clip_as_service:
+        server: "grpc://127.0.0.1:51000"
+        model_name: "CN-CLIP/ViT-L-14"
+        batch_size: 8
+        normalize_embeddings: true
+      local_cnclip:
+        model_name: "ViT-L-14"
+        device: null
+        batch_size: 8
+        normalize_embeddings: true
   rerank:
     provider: "http"
     base_url: "http://127.0.0.1:6007"
@@ -218,6 +239,9 @@ services:
       http:
         base_url: "http://127.0.0.1:6007"
         service_url: "http://127.0.0.1:6007/rerank"
+    request:
+      max_docs: 1000
+      normalize: true
     # 服务内后端（reranker 进程启动时读取）
     backend: "qwen3_vllm"  # bge | qwen3_vllm | qwen3_transformers | dashscope_rerank
     backends:
 """
-Configuration loader and validator for search engine configurations.
+Compatibility wrapper for search-behavior config access.
-This module handles loading, parsing, and validating YAML configuration files
-that define how search should be executed (NOT how data should be indexed).
-
-索引结构由 mappings/search_products.json 定义。
-此配置只定义搜索行为：字段权重、搜索域、查询策略等。
+The unified loader lives in :mod:`config.loader`. This module now exposes the
+search subtree only, so existing search/indexer code can consume a single
+source-of-truth search config without reparsing YAML separately.
 """
-import yaml
-from typing import Dict, Any, List, Optional
-from dataclasses import dataclass, field
-from pathlib import Path
-
-
-@dataclass
-class IndexConfig:
-    """Configuration for an index domain (e.g., default, title, brand)."""
-    name: str
-    label: str
-    fields: List[str]  # List of field names to include in this search domain
-    boost: float = 1.0
-    example: Optional[str] = None
-
-
-@dataclass
-class QueryConfig:
-    """Configuration for query processing."""
-    supported_languages: List[str] = field(default_factory=lambda: ["zh", "en"])
-    default_language: str = "en"
-    
-    # Feature flags
-    enable_text_embedding: bool = True
-    enable_query_rewrite: bool = True
-
-    # Query rewrite dictionary (loaded from external file)
-    rewrite_dictionary: Dict[str, str] = field(default_factory=dict)
-    
-    # Embedding field names
-    text_embedding_field: Optional[str] = "title_embedding"
-    image_embedding_field: Optional[str] = None
-        
-    # Source fields configuration
-    source_fields: Optional[List[str]] = None
-    
-    # KNN boost configuration
-    knn_boost: float = 0.25  # Boost value for KNN (embedding recall)
-    
-    # Dynamic text fields for multi-language retrieval
-    multilingual_fields: List[str] = field(
-        default_factory=lambda: ["title", "brief", "description", "vendor", "category_path", "category_name_text"]
-    )
-    shared_fields: List[str] = field(
-        default_factory=lambda: ["tags", "option1_values", "option2_values", "option3_values"]
-    )
-    core_multilingual_fields: List[str] = field(
-        default_factory=lambda: ["title", "brief", "vendor", "category_name_text"]
-    )
-    
-    # Unified text strategy tuning
-    base_minimum_should_match: str = "75%"
-    translation_minimum_should_match: str = "75%"
-    translation_boost: float = 0.4
-    translation_boost_when_source_missing: float = 1.0
-    source_boost_when_missing: float = 0.6
-    original_query_fallback_boost_when_translation_missing: float = 0.2
-    tie_breaker_base_query: float = 0.9
-
-    # Query-time translation model selection (configurable)
-    # - zh_to_en_model: model for zh -> en
-    # - en_to_zh_model: model for en -> zh
-    # - default_translation_model: fallback model for all other language pairs
-    zh_to_en_model: str = "opus-mt-zh-en"
-    en_to_zh_model: str = "opus-mt-en-zh"
-    default_translation_model: str = "nllb-200-distilled-600m"
-
-
-@dataclass
-class SPUConfig:
-    """Configuration for SPU aggregation."""
-    enabled: bool = False
-    spu_field: Optional[str] = None
-    inner_hits_size: int = 3
-    # 配置哪些option维度参与检索（进索引、以及在线搜索）
-    searchable_option_dimensions: List[str] = field(default_factory=lambda: ['option1', 'option2', 'option3'])
-
-
-@dataclass
-class FunctionScoreConfig:
-    """Function Score配置（ES层打分规则）"""
-    score_mode: str = "sum"
-    boost_mode: str = "multiply"
-    functions: List[Dict[str, Any]] = field(default_factory=list)
-
-
-@dataclass
-class RerankConfig:
-    """重排配置（provider/URL 在 services.rerank）"""
-    enabled: bool = True
-    rerank_window: int = 384
-    timeout_sec: float = 15.0
-    weight_es: float = 0.4
-    weight_ai: float = 0.6
-    rerank_query_template: str = "{query}"
-    rerank_doc_template: str = "{title}"
-
-
-@dataclass
-class SearchConfig:
-    """Complete configuration for search engine (multi-tenant)."""
-    
-    # 字段权重配置（用于搜索）
-    field_boosts: Dict[str, float]
-    
-    # Legacy index domains (deprecated; kept for compatibility)
-    indexes: List[IndexConfig]
-    
-    # Query processing
-    query_config: QueryConfig
-    
-    # Function Score configuration (ES层打分)
-    function_score: FunctionScoreConfig
-    
-    # Rerank configuration (本地重排)
-    rerank: RerankConfig
-    
-    # SPU configuration
-    spu_config: SPUConfig
-    
-    # ES index settings
-    es_index_name: str
-    
-    # Tenant configuration
-    tenant_config: Dict[str, Any] = field(default_factory=dict)
-    
-    # ES settings
-    es_settings: Dict[str, Any] = field(default_factory=dict)
-    # Extensible service/provider registry (translation/embedding/rerank/...)
-    services: Dict[str, Any] = field(default_factory=dict)
+from __future__ import annotations
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
-class ConfigurationError(Exception):
-    """Raised when configuration validation fails."""
-    pass
+from config.loader import AppConfigLoader, ConfigurationError
+from config.schema import (
+    FunctionScoreConfig,
+    IndexConfig,
+    QueryConfig,
+    RerankConfig,
+    SPUConfig,
+    SearchConfig,
+)
 class ConfigLoader:
-    """Loads and validates unified search engine configuration from YAML file."""
-    
-    def __init__(self, config_file: Optional[Path] = None):
-        """
-        Initialize config loader.
-        
-        Args:
-            config_file: Path to config YAML file (defaults to config/config.yaml)
-        """
-        if config_file is None:
-            config_file = Path(__file__).parent / "config.yaml"
-        self.config_file = Path(config_file)
-    
-    def _load_rewrite_dictionary(self) -> Dict[str, str]:
-        """Load query rewrite dictionary from external file."""
-        rewrite_file = Path(__file__).parent / "rewrite_dictionary.txt"
-        rewrite_dict = {}
-        
-        if not rewrite_file.exists():
-            return rewrite_dict
-        
-        try:
-            with open(rewrite_file, 'r', encoding='utf-8') as f:
-                for line in f:
-                    line = line.strip()
-                    if not line or line.startswith('#'):
-                        continue
-                    
-                    parts = line.split('\t')
-                    if len(parts) >= 2:
-                        original = parts[0].strip()
-                        replacement = parts[1].strip()
-                        if original and replacement:
-                            rewrite_dict[original] = replacement
-        except Exception as e:
-            print(f"Warning: Failed to load rewrite dictionary: {e}")
-        
-        return rewrite_dict
-    
-    def load_config(self, validate: bool = True) -> SearchConfig:
-        """
-        Load unified configuration from YAML file.
-        
-        Args:
-            validate: Whether to validate configuration after loading
-        
-        Returns:
-            SearchConfig object
-        
-        Raises:
-            ConfigurationError: If config file not found, invalid, or validation fails
-        """
-        if not self.config_file.exists():
-            raise ConfigurationError(f"Configuration file not found: {self.config_file}")
-        
-        try:
-            with open(self.config_file, 'r', encoding='utf-8') as f:
-                config_data = yaml.safe_load(f)
-        except yaml.YAMLError as e:
-            raise ConfigurationError(f"Invalid YAML in {self.config_file}: {e}")
-        
-        config = self._parse_config(config_data)
-        
-        # Auto-validate configuration
-        if validate:
-            errors = self.validate_config(config)
-            if errors:
-                error_msg = "Configuration validation failed:\n" + "\n".join(f"  - {err}" for err in errors)
-                raise ConfigurationError(error_msg)
-        
-        return config
-    
-    def _parse_config(self, config_data: Dict[str, Any]) -> SearchConfig:
-        """Parse configuration dictionary into SearchConfig object."""
-        
-        # Parse field_boosts
-        field_boosts = config_data.get("field_boosts", {})
-        if not isinstance(field_boosts, dict):
-            raise ConfigurationError("field_boosts must be a dictionary")
-        
-        # Parse indexes (deprecated; compatibility only)
-        indexes = []
-        for index_data in config_data.get("indexes", []):
-            indexes.append(self._parse_index_config(index_data))
-        
-        # Parse query config
-        query_config_data = config_data.get("query_config", {})
-        rewrite_dictionary = self._load_rewrite_dictionary()
-        search_fields_cfg = query_config_data.get("search_fields", {})
-        text_strategy_cfg = query_config_data.get("text_query_strategy", {})
+    """Load the unified app config and return the search subtree."""
-        query_config = QueryConfig(
-            supported_languages=query_config_data.get("supported_languages") or ["zh", "en"],
-            default_language=query_config_data.get("default_language") or "en",
-            enable_text_embedding=query_config_data.get("enable_text_embedding", True),
-            enable_query_rewrite=query_config_data.get("enable_query_rewrite", True),
-            rewrite_dictionary=rewrite_dictionary,
-            text_embedding_field=query_config_data.get("text_embedding_field"),
-            image_embedding_field=query_config_data.get("image_embedding_field"),
-            source_fields=query_config_data.get("source_fields"),
-            knn_boost=query_config_data.get("knn_boost", 0.25),
-            multilingual_fields=search_fields_cfg.get(
-                "multilingual_fields",
-                ["title", "brief", "description", "vendor", "category_path", "category_name_text"],
-            ),
-            shared_fields=search_fields_cfg.get(
-                "shared_fields",
-                ["tags", "option1_values", "option2_values", "option3_values"],
-            ),
-            core_multilingual_fields=search_fields_cfg.get(
-                "core_multilingual_fields",
-                ["title", "brief", "vendor", "category_name_text"],
-            ),
-            base_minimum_should_match=str(text_strategy_cfg.get("base_minimum_should_match", "75%")),
-            translation_minimum_should_match=str(text_strategy_cfg.get("translation_minimum_should_match", "75%")),
-            translation_boost=float(text_strategy_cfg.get("translation_boost", 0.4)),
-            translation_boost_when_source_missing=float(
-                text_strategy_cfg.get("translation_boost_when_source_missing", 1.0)
-            ),
-            source_boost_when_missing=float(text_strategy_cfg.get("source_boost_when_missing", 0.6)),
-            original_query_fallback_boost_when_translation_missing=float(
-                text_strategy_cfg.get("original_query_fallback_boost_when_translation_missing", 0.2)
-            ),
-            tie_breaker_base_query=float(text_strategy_cfg.get("tie_breaker_base_query", 0.9)),
-            zh_to_en_model=str(query_config_data.get("zh_to_en_model") or "opus-mt-zh-en"),
-            en_to_zh_model=str(query_config_data.get("en_to_zh_model") or "opus-mt-en-zh"),
-            default_translation_model=str(
-                query_config_data.get("default_translation_model") or "nllb-200-distilled-600m"
-            ),
-        )
-        
-        # Parse Function Score configuration
-        fs_data = config_data.get("function_score", {})
-        function_score = FunctionScoreConfig(
-            score_mode=fs_data.get("score_mode") or "sum",
-            boost_mode=fs_data.get("boost_mode") or "multiply",
-            functions=fs_data.get("functions") or []
-        )
-        
-        # Parse Rerank (provider/URL in services.rerank)
-        rerank_data = config_data.get("rerank", {})
-        rerank = RerankConfig(
-            enabled=bool(rerank_data.get("enabled", True)),
-            rerank_window=int(rerank_data.get("rerank_window", 384)),
-            timeout_sec=float(rerank_data.get("timeout_sec", 15.0)),
-            weight_es=float(rerank_data.get("weight_es", 0.4)),
-            weight_ai=float(rerank_data.get("weight_ai", 0.6)),
-            rerank_query_template=str(rerank_data.get("rerank_query_template") or "{query}"),
-            rerank_doc_template=str(rerank_data.get("rerank_doc_template") or "{title}"),
-        )
-        
-        # Parse SPU config
-        spu_data = config_data.get("spu_config", {})
-        spu_config = SPUConfig(
-            enabled=spu_data.get("enabled", False),
-            spu_field=spu_data.get("spu_field"),
-            inner_hits_size=spu_data.get("inner_hits_size", 3),
-            searchable_option_dimensions=spu_data.get("searchable_option_dimensions", ['option1', 'option2', 'option3'])
-        )
-        
-        # Parse tenant config
-        tenant_config_data = config_data.get("tenant_config", {})
+    def __init__(self, config_file: Optional[Path] = None) -> None:
+        self._loader = AppConfigLoader(config_file=Path(config_file) if config_file is not None else None)
-        # Parse extensible services/provider registry
-        services_data = config_data.get("services", {}) or {}
-        if not isinstance(services_data, dict):
-            raise ConfigurationError("services must be a dictionary if provided")
+    def load_config(self, validate: bool = True) -> SearchConfig:
+        return self._loader.load(validate=validate).search
-        return SearchConfig(
-            field_boosts=field_boosts,
-            indexes=indexes,
-            query_config=query_config,
-            function_score=function_score,
-            rerank=rerank,
-            spu_config=spu_config,
-            tenant_config=tenant_config_data,
-            es_index_name=config_data.get("es_index_name", "search_products"),
-            es_settings=config_data.get("es_settings", {}),
-            services=services_data
-        )
-    
-    def _parse_index_config(self, index_data: Dict[str, Any]) -> IndexConfig:
-        """Parse index configuration from dictionary."""
-        return IndexConfig(
-            name=index_data["name"],
-            label=index_data.get("label", index_data["name"]),
-            fields=index_data.get("fields", []),
-            boost=index_data.get("boost", 1.0),
-            example=index_data.get("example")
-        )
-    
     def validate_config(self, config: SearchConfig) -> List[str]:
-        """
-        Validate configuration for common errors.
-        
-        Args:
-            config: SearchConfig to validate
-        
-        Returns:
-            List of error messages (empty if valid)
-        """
-        errors = []
-        
-        # Validate es_index_name
+        errors: List[str] = []
         if not config.es_index_name:
             errors.append("es_index_name is required")
-        
-        # Validate field_boosts
         if not config.field_boosts:
             errors.append("field_boosts is empty")
-        
-        for field_name, boost in config.field_boosts.items():
-            if not isinstance(boost, (int, float)):
-                errors.append(f"field_boosts['{field_name}']: boost must be a number, got {type(boost).__name__}")
-            elif boost < 0:
-                errors.append(f"field_boosts['{field_name}']: boost must be non-negative")
-        
-        # Validate indexes (deprecated, optional)
-        index_names = set()
-        for index in config.indexes:
-            # Check for duplicate index names
-            if index.name in index_names:
-                errors.append(f"Duplicate index name: {index.name}")
-            index_names.add(index.name)
-            
-            # Validate fields in index
-            if not index.fields:
-                errors.append(f"Index '{index.name}': fields list is empty")
-        
-        # Validate SPU config
-        if config.spu_config.enabled:
-            if not config.spu_config.spu_field:
-                errors.append("SPU aggregation enabled but no spu_field specified")
-        
-        # Validate query config
-        if not config.query_config.supported_languages:
-            errors.append("At least one supported language must be specified")
-        
         if config.query_config.default_language not in config.query_config.supported_languages:
-            errors.append(
-                f"Default language '{config.query_config.default_language}' "
-                f"not in supported languages: {config.query_config.supported_languages}"
-            )
-        
-        # Validate dynamic search fields
-        def _validate_str_list(name: str, values: List[str]) -> None:
-            if not isinstance(values, list) or not values:
-                errors.append(f"query_config.{name} must be a non-empty list[str]")
-                return
-            for i, val in enumerate(values):
-                if not isinstance(val, str) or not val.strip():
-                    errors.append(f"query_config.{name}[{i}] must be a non-empty string")
-        
-        _validate_str_list("multilingual_fields", config.query_config.multilingual_fields)
-        _validate_str_list("shared_fields", config.query_config.shared_fields)
-        _validate_str_list("core_multilingual_fields", config.query_config.core_multilingual_fields)
-        
-        core_set = set(config.query_config.core_multilingual_fields)
-        multi_set = set(config.query_config.multilingual_fields)
-        if not core_set.issubset(multi_set):
-            errors.append("query_config.core_multilingual_fields must be subset of multilingual_fields")
-        
-        # Validate text query strategy numbers
-        for name in (
-            "translation_boost",
-            "translation_boost_when_source_missing",
-            "source_boost_when_missing",
-            "original_query_fallback_boost_when_translation_missing",
-            "tie_breaker_base_query",
-        ):
-            value = getattr(config.query_config, name, None)
-            if not isinstance(value, (int, float)):
-                errors.append(f"query_config.{name} must be a number")
-            elif value < 0:
-                errors.append(f"query_config.{name} must be non-negative")
-
-        # Validate source_fields tri-state semantics
-        source_fields = config.query_config.source_fields
-        if source_fields is not None:
-            if not isinstance(source_fields, list):
-                errors.append("query_config.source_fields must be null or list[str]")
-            else:
-                for idx, field_name in enumerate(source_fields):
-                    if not isinstance(field_name, str) or not field_name.strip():
-                        errors.append(
-                            f"query_config.source_fields[{idx}] must be a non-empty string"
-                        )
-
-        # Validate tenant config shape (default must exist in config)
-        tenant_cfg = config.tenant_config
-        if not isinstance(tenant_cfg, dict):
-            errors.append("tenant_config must be an object")
-        else:
-            default_cfg = tenant_cfg.get("default")
-            if not isinstance(default_cfg, dict):
-                errors.append("tenant_config.default must be configured")
-            else:
-                index_languages = default_cfg.get("index_languages")
-                if not isinstance(index_languages, list) or len(index_languages) == 0:
-                    errors.append("tenant_config.default.index_languages must be a non-empty list")
-
+            errors.append("default_language must be included in supported_languages")
+        if config.spu_config.enabled and not config.spu_config.spu_field:
+            errors.append("spu_field is required when SPU is enabled")
         return errors
-    
+
     def to_dict(self, config: SearchConfig) -> Dict[str, Any]:
-        """Convert SearchConfig to dictionary representation."""
-        
-        # Build query_config dict
-        query_config_dict = {
-            "supported_languages": config.query_config.supported_languages,
-            "default_language": config.query_config.default_language,
-            "enable_text_embedding": config.query_config.enable_text_embedding,
-            "enable_query_rewrite": config.query_config.enable_query_rewrite,
-            "text_embedding_field": config.query_config.text_embedding_field,
-            "image_embedding_field": config.query_config.image_embedding_field,
-            "source_fields": config.query_config.source_fields,
-            "search_fields": {
-                "multilingual_fields": config.query_config.multilingual_fields,
-                "shared_fields": config.query_config.shared_fields,
-                "core_multilingual_fields": config.query_config.core_multilingual_fields,
-            },
-            "text_query_strategy": {
-                "base_minimum_should_match": config.query_config.base_minimum_should_match,
-                "translation_minimum_should_match": config.query_config.translation_minimum_should_match,
-                "translation_boost": config.query_config.translation_boost,
-                "translation_boost_when_source_missing": config.query_config.translation_boost_when_source_missing,
-                "source_boost_when_missing": config.query_config.source_boost_when_missing,
-                "original_query_fallback_boost_when_translation_missing": (
-                    config.query_config.original_query_fallback_boost_when_translation_missing
-                ),
-                "tie_breaker_base_query": config.query_config.tie_breaker_base_query,
-            }
-        }
-        
-        return {
-            "es_index_name": config.es_index_name,
-            "es_settings": config.es_settings,
-            "field_boosts": config.field_boosts,
-            "indexes": [self._index_to_dict(index) for index in config.indexes],
-            "query_config": query_config_dict,
-            "function_score": {
-                "score_mode": config.function_score.score_mode,
-                "boost_mode": config.function_score.boost_mode,
-                "functions": config.function_score.functions
-            },
-            "rerank": {
-                "enabled": config.rerank.enabled,
-                "rerank_window": config.rerank.rerank_window,
-                "timeout_sec": config.rerank.timeout_sec,
-                "weight_es": config.rerank.weight_es,
-                "weight_ai": config.rerank.weight_ai,
-                "rerank_query_template": config.rerank.rerank_query_template,
-                "rerank_doc_template": config.rerank.rerank_doc_template,
-            },
-            "spu_config": {
-                "enabled": config.spu_config.enabled,
-                "spu_field": config.spu_config.spu_field,
-                "inner_hits_size": config.spu_config.inner_hits_size,
-                "searchable_option_dimensions": config.spu_config.searchable_option_dimensions
-            },
-            "services": config.services,
-        }
-    
-    def _index_to_dict(self, index: IndexConfig) -> Dict[str, Any]:
-        """Convert IndexConfig to dictionary."""
-        result = {
-            "name": index.name,
-            "label": index.label,
-            "fields": index.fields,
-            "boost": index.boost
-        }
-        
-        if index.example:
-            result["example"] = index.example
-        
-        return result
+        return asdict(config)
@@ -0,0 +1,2 @@
+玩具	category.keyword:玩具 OR default:玩具
+消防	category.keyword:消防 OR default:消防
 """
-Centralized configuration management for saas-search.
+Compatibility accessors for infrastructure/runtime environment settings.
-Loads configuration from environment variables and .env file.
-This module provides a single point for loading .env and setting defaults.
-All configuration variables are exported directly - no need for getter functions.
+All values are derived from the unified application config. This module no
+longer owns any independent loading or precedence rules.
 """
-import os
-from pathlib import Path
-from dotenv import load_dotenv
-
-# Load .env file from project root
-PROJECT_ROOT = Path(__file__).parent.parent
-load_dotenv(PROJECT_ROOT / '.env')
-
-
-# Elasticsearch Configuration
-ES_CONFIG = {
-    'host': os.getenv('ES_HOST', 'http://localhost:9200'),
-    'username': os.getenv('ES_USERNAME'),
-    'password': os.getenv('ES_PASSWORD'),
-}
-
-# Runtime environment & index namespace
-# RUNTIME_ENV: 当前运行环境，建议使用 prod / uat / test / dev 等枚举值
-RUNTIME_ENV = os.getenv('RUNTIME_ENV', 'prod')
-# ES_INDEX_NAMESPACE: 用于按环境隔离索引的命名空间前缀，例如 "uat_" / "test_"
-# 为空字符串时表示不加前缀（通常是 prod 环境）
-ES_INDEX_NAMESPACE = os.getenv('ES_INDEX_NAMESPACE')
-if ES_INDEX_NAMESPACE is None:
-    # 未显式配置时，非 prod 环境默认加 "<env>_" 前缀，prod 环境默认不加前缀
-    ES_INDEX_NAMESPACE = '' if RUNTIME_ENV == 'prod' else f'{RUNTIME_ENV}_'
-
-# Redis Configuration
-REDIS_CONFIG = {
-    'host': os.getenv('REDIS_HOST', 'localhost'),
-    'port': int(os.getenv('REDIS_PORT', 6479)),
-    'snapshot_db': int(os.getenv('REDIS_SNAPSHOT_DB', 0)),
-    'password': os.getenv('REDIS_PASSWORD'),
-    'socket_timeout': int(os.getenv('REDIS_SOCKET_TIMEOUT', 1)),
-    'socket_connect_timeout': int(os.getenv('REDIS_SOCKET_CONNECT_TIMEOUT', 1)),
-    'retry_on_timeout': os.getenv('REDIS_RETRY_ON_TIMEOUT', 'False').lower() == 'true',
-    'cache_expire_days': int(os.getenv('REDIS_CACHE_EXPIRE_DAYS', 360*2)),  # 6 months
-    # Embedding 缓存 key 前缀，例如 "embedding"
-    'embedding_cache_prefix': os.getenv('REDIS_EMBEDDING_CACHE_PREFIX', 'embedding'),
-}
-
-# DeepL API Key
-DEEPL_AUTH_KEY = os.getenv('DEEPL_AUTH_KEY')
-
-# DashScope API Key (for Qwen models)
-DASHSCOPE_API_KEY = os.getenv('DASHSCOPE_API_KEY')
-
-# API Service Configuration
-API_HOST = os.getenv('API_HOST', '0.0.0.0')
-API_PORT = int(os.getenv('API_PORT', 6002))
-# Indexer service
-INDEXER_HOST = os.getenv('INDEXER_HOST', '0.0.0.0')
-INDEXER_PORT = int(os.getenv('INDEXER_PORT', 6004))
-# Optional dependent services
-# EMBEDDING_HOST / EMBEDDING_PORT are only used by the optional combined embedding mode.
-EMBEDDING_HOST = os.getenv('EMBEDDING_HOST', '127.0.0.1')
-EMBEDDING_PORT = int(os.getenv('EMBEDDING_PORT', 6005))
-EMBEDDING_TEXT_HOST = os.getenv('EMBEDDING_TEXT_HOST', '127.0.0.1')
-EMBEDDING_TEXT_PORT = int(os.getenv('EMBEDDING_TEXT_PORT', 6005))
-EMBEDDING_IMAGE_HOST = os.getenv('EMBEDDING_IMAGE_HOST', '127.0.0.1')
-EMBEDDING_IMAGE_PORT = int(os.getenv('EMBEDDING_IMAGE_PORT', 6008))
-TRANSLATION_HOST = os.getenv('TRANSLATION_HOST', '127.0.0.1')
-TRANSLATION_PORT = int(os.getenv('TRANSLATION_PORT', 6006))
-RERANKER_HOST = os.getenv('RERANKER_HOST', '127.0.0.1')
-RERANKER_PORT = int(os.getenv('RERANKER_PORT', 6007))
-RERANK_PROVIDER = os.getenv('RERANK_PROVIDER', 'http')
-# API_BASE_URL: 如果未设置，根据API_HOST构建（0.0.0.0使用localhost）
-API_BASE_URL = os.getenv('API_BASE_URL')
-if not API_BASE_URL:
-    API_BASE_URL = f'http://localhost:{API_PORT}' if API_HOST == '0.0.0.0' else f'http://{API_HOST}:{API_PORT}'
-INDEXER_BASE_URL = os.getenv('INDEXER_BASE_URL') or (
-    f'http://localhost:{INDEXER_PORT}' if INDEXER_HOST == '0.0.0.0' else f'http://{INDEXER_HOST}:{INDEXER_PORT}'
-)
-EMBEDDING_TEXT_SERVICE_URL = os.getenv('EMBEDDING_TEXT_SERVICE_URL') or (
-    f'http://{EMBEDDING_TEXT_HOST}:{EMBEDDING_TEXT_PORT}'
-)
-EMBEDDING_IMAGE_SERVICE_URL = os.getenv('EMBEDDING_IMAGE_SERVICE_URL') or (
-    f'http://{EMBEDDING_IMAGE_HOST}:{EMBEDDING_IMAGE_PORT}'
-)
-RERANKER_SERVICE_URL = os.getenv('RERANKER_SERVICE_URL') or f'http://{RERANKER_HOST}:{RERANKER_PORT}/rerank'
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from config.loader import get_app_config
+
+
+def _app():
+    return get_app_config()
+
+
+def _runtime():
+    return _app().runtime
-# Model IDs / paths
-TEXT_MODEL_DIR = os.getenv('TEXT_MODEL_DIR', os.getenv('TEXT_MODEL_ID', 'Qwen/Qwen3-Embedding-0.6B'))
-IMAGE_MODEL_DIR = os.getenv('IMAGE_MODEL_DIR', '/data/tw/models/cn-clip')
-# Cache Directory
-CACHE_DIR = os.getenv('CACHE_DIR', '.cache')
+def _infra():
+    return _app().infrastructure
-# MySQL Database Configuration (Shoplazza)
-DB_CONFIG = {
-    'host': os.getenv('DB_HOST'),
-    'port': int(os.getenv('DB_PORT', 3306)) if os.getenv('DB_PORT') else 3306,
-    'database': os.getenv('DB_DATABASE'),
-    'username': os.getenv('DB_USERNAME'),
-    'password': os.getenv('DB_PASSWORD'),
-}
+def _elasticsearch_dict() -> Dict[str, Any]:
+    cfg = _infra().elasticsearch
+    return {
+        "host": cfg.host,
+        "username": cfg.username,
+        "password": cfg.password,
+    }
-def print_config():
-    """Print current configuration (with sensitive data masked)."""
-    print("=" * 60)
-    print("saas-search Configuration")
-    print("=" * 60)
-    print("\nElasticsearch:")
-    print(f"  Host: {ES_CONFIG['host']}")
-    print(f"  Username: {ES_CONFIG['username']}")
-    print(f"  Password: {'*' * 10 if ES_CONFIG['password'] else 'None'}")
+def _redis_dict() -> Dict[str, Any]:
+    cfg = _infra().redis
+    return {
+        "host": cfg.host,
+        "port": cfg.port,
+        "snapshot_db": cfg.snapshot_db,
+        "password": cfg.password,
+        "socket_timeout": cfg.socket_timeout,
+        "socket_connect_timeout": cfg.socket_connect_timeout,
+        "retry_on_timeout": cfg.retry_on_timeout,
+        "cache_expire_days": cfg.cache_expire_days,
+        "embedding_cache_prefix": cfg.embedding_cache_prefix,
+        "anchor_cache_prefix": cfg.anchor_cache_prefix,
+        "anchor_cache_expire_days": cfg.anchor_cache_expire_days,
+    }
-    print("\nRedis:")
-    print(f"  Host: {REDIS_CONFIG['host']}")
-    print(f"  Port: {REDIS_CONFIG['port']}")
-    print(f"  Password: {'*' * 10 if REDIS_CONFIG['password'] else 'None'}")
-    print("\nDeepL:")
-    print(f"  API Key: {'*' * 10 if DEEPL_AUTH_KEY else 'None (translation disabled)'}")
+def _db_dict() -> Dict[str, Any]:
+    cfg = _infra().database
+    return {
+        "host": cfg.host,
+        "port": cfg.port,
+        "database": cfg.database,
+        "username": cfg.username,
+        "password": cfg.password,
+    }
+
+
+ES_CONFIG = _elasticsearch_dict()
+REDIS_CONFIG = _redis_dict()
+DB_CONFIG = _db_dict()
+
+RUNTIME_ENV = _runtime().environment
+ES_INDEX_NAMESPACE = _runtime().index_namespace
+
+DEEPL_AUTH_KEY = _infra().secrets.deepl_auth_key
+DASHSCOPE_API_KEY = _infra().secrets.dashscope_api_key
+
+API_HOST = _runtime().api_host
+API_PORT = _runtime().api_port
+INDEXER_HOST = _runtime().indexer_host
+INDEXER_PORT = _runtime().indexer_port
+EMBEDDING_HOST = _runtime().embedding_host
+EMBEDDING_PORT = _runtime().embedding_port
+EMBEDDING_TEXT_HOST = _runtime().embedding_host
+EMBEDDING_TEXT_PORT = _runtime().embedding_text_port
+EMBEDDING_IMAGE_HOST = _runtime().embedding_host
+EMBEDDING_IMAGE_PORT = _runtime().embedding_image_port
+TRANSLATION_HOST = _runtime().translator_host
+TRANSLATION_PORT = _runtime().translator_port
+RERANKER_HOST = _runtime().reranker_host
+RERANKER_PORT = _runtime().reranker_port
+
+API_BASE_URL = f"http://localhost:{API_PORT}" if API_HOST == "0.0.0.0" else f"http://{API_HOST}:{API_PORT}"
+INDEXER_BASE_URL = (
+    f"http://localhost:{INDEXER_PORT}" if INDEXER_HOST == "0.0.0.0" else f"http://{INDEXER_HOST}:{INDEXER_PORT}"
+)
+EMBEDDING_TEXT_SERVICE_URL = _app().services.embedding.get_provider_config().get("text_base_url")
+EMBEDDING_IMAGE_SERVICE_URL = _app().services.embedding.get_provider_config().get("image_base_url")
+RERANKER_SERVICE_URL = (
+    _app().services.rerank.get_provider_config().get("service_url")
+    or _app().services.rerank.get_provider_config().get("base_url")
+)
+
-    print("\nAPI Service:")
-    print(f"  Host: {API_HOST}")
-    print(f"  Port: {API_PORT}")
+def get_es_config() -> Dict[str, Any]:
+    return dict(ES_CONFIG)
-    print("\nModels:")
-    print(f"  Text Model: {TEXT_MODEL_DIR}")
-    print(f"  Image Model: {IMAGE_MODEL_DIR}")
-    print("\nCache:")
-    print(f"  Cache Directory: {CACHE_DIR}")
+def get_db_config() -> Dict[str, Any]:
+    return dict(DB_CONFIG)
-    print("\nMySQL Database:")
-    print(f"  Host: {DB_CONFIG['host']}")
-    print(f"  Port: {DB_CONFIG['port']}")
-    print(f"  Database: {DB_CONFIG['database']}")
-    print(f"  Username: {DB_CONFIG['username']}")
-    print(f"  Password: {'*' * 10 if DB_CONFIG['password'] else 'None'}")
-    print("=" * 60)
+def get_redis_config() -> Dict[str, Any]:
+    return dict(REDIS_CONFIG)
-if __name__ == "__main__":
-    print_config()
+def print_config() -> None:
+    config = _app().sanitized_dict()
+    print(config)
@@ -0,0 +1,589 @@
+"""
+Unified application configuration loader.
+
+This module is the single source of truth for loading, merging, normalizing,
+and validating application configuration.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from copy import deepcopy
+from dataclasses import asdict
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+import yaml
+
+try:
+    from dotenv import load_dotenv as _load_dotenv  # type: ignore
+except Exception:  # pragma: no cover
+    _load_dotenv = None
+
+from config.schema import (
+    AppConfig,
+    AssetsConfig,
+    ConfigMetadata,
+    DatabaseSettings,
+    ElasticsearchSettings,
+    EmbeddingServiceConfig,
+    FunctionScoreConfig,
+    IndexConfig,
+    InfrastructureConfig,
+    QueryConfig,
+    ProductEnrichConfig,
+    RedisSettings,
+    RerankConfig,
+    RerankServiceConfig,
+    RuntimeConfig,
+    SearchConfig,
+    SecretsConfig,
+    ServicesConfig,
+    SPUConfig,
+    TenantCatalogConfig,
+    TranslationServiceConfig,
+)
+from translation.settings import build_translation_config
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration validation fails."""
+
+
+def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    result = deepcopy(base)
+    for key, value in (override or {}).items():
+        if (
+            key in result
+            and isinstance(result[key], dict)
+            and isinstance(value, dict)
+        ):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = deepcopy(value)
+    return result
+
+
+def _load_yaml(path: Path) -> Dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    if not isinstance(data, dict):
+        raise ConfigurationError(f"Configuration file root must be a mapping: {path}")
+    return data
+
+
+def _read_rewrite_dictionary(path: Path) -> Dict[str, str]:
+    rewrite_dict: Dict[str, str] = {}
+    if not path.exists():
+        return rewrite_dict
+
+    with open(path, "r", encoding="utf-8") as handle:
+        for raw_line in handle:
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split("\t")
+            if len(parts) < 2:
+                continue
+            original = parts[0].strip()
+            replacement = parts[1].strip()
+            if original and replacement:
+                rewrite_dict[original] = replacement
+    return rewrite_dict
+
+
+class AppConfigLoader:
+    """Load the unified application configuration."""
+
+    def __init__(
+        self,
+        *,
+        config_dir: Optional[Path] = None,
+        config_file: Optional[Path] = None,
+        env_file: Optional[Path] = None,
+    ) -> None:
+        self.config_dir = Path(config_dir or Path(__file__).parent)
+        self.config_file = Path(config_file) if config_file is not None else None
+        self.project_root = self.config_dir.parent
+        self.env_file = Path(env_file) if env_file is not None else self.project_root / ".env"
+
+    def load(self, validate: bool = True) -> AppConfig:
+        self._load_env()
+        raw_config, loaded_files = self._load_raw_config()
+        app_config = self._build_app_config(raw_config, loaded_files)
+        if validate:
+            self._validate(app_config)
+        return app_config
+
+    def _load_env(self) -> None:
+        if _load_dotenv is not None:
+            _load_dotenv(self.env_file, override=False)
+            return
+        _load_env_file_fallback(self.env_file)
+
+    def _load_raw_config(self) -> Tuple[Dict[str, Any], List[str]]:
+        env_name = (os.getenv("APP_ENV") or os.getenv("RUNTIME_ENV") or "prod").strip().lower() or "prod"
+        loaded_files: List[str] = []
+        raw: Dict[str, Any] = {}
+
+        if self.config_file is not None:
+            config_path = self.config_file
+            if not config_path.exists():
+                raise ConfigurationError(f"Configuration file not found: {config_path}")
+            raw = _deep_merge(raw, _load_yaml(config_path))
+            loaded_files.append(str(config_path))
+        else:
+            base_path = self.config_dir / "base.yaml"
+            legacy_path = self.config_dir / "config.yaml"
+            primary_path = base_path if base_path.exists() else legacy_path
+            if not primary_path.exists():
+                raise ConfigurationError(f"Configuration file not found: {primary_path}")
+            raw = _deep_merge(raw, _load_yaml(primary_path))
+            loaded_files.append(str(primary_path))
+
+            env_path = self.config_dir / "environments" / f"{env_name}.yaml"
+            if env_path.exists():
+                raw = _deep_merge(raw, _load_yaml(env_path))
+                loaded_files.append(str(env_path))
+
+        tenant_dir = self.config_dir / "tenants"
+        if tenant_dir.is_dir():
+            tenant_files = sorted(tenant_dir.glob("*.yaml"))
+            if tenant_files:
+                tenant_config = {"default": {}, "tenants": {}}
+                default_path = tenant_dir / "_default.yaml"
+                if default_path.exists():
+                    tenant_config["default"] = _load_yaml(default_path)
+                    loaded_files.append(str(default_path))
+                for tenant_path in tenant_files:
+                    if tenant_path.name == "_default.yaml":
+                        continue
+                    tenant_config["tenants"][tenant_path.stem] = _load_yaml(tenant_path)
+                    loaded_files.append(str(tenant_path))
+                raw["tenant_config"] = tenant_config
+
+        return raw, loaded_files
+
+    def _build_app_config(self, raw: Dict[str, Any], loaded_files: List[str]) -> AppConfig:
+        assets_cfg = raw.get("assets") if isinstance(raw.get("assets"), dict) else {}
+        rewrite_path = (
+            assets_cfg.get("query_rewrite_dictionary_path")
+            or assets_cfg.get("rewrite_dictionary_path")
+            or self.config_dir / "dictionaries" / "query_rewrite.dict"
+        )
+        rewrite_path = Path(rewrite_path)
+        if not rewrite_path.is_absolute():
+            rewrite_path = (self.project_root / rewrite_path).resolve()
+        if not rewrite_path.exists():
+            legacy_rewrite_path = (self.config_dir / "query_rewrite.dict").resolve()
+            if legacy_rewrite_path.exists():
+                rewrite_path = legacy_rewrite_path
+
+        rewrite_dictionary = _read_rewrite_dictionary(rewrite_path)
+        search_config = self._build_search_config(raw, rewrite_dictionary)
+        services_config = self._build_services_config(raw.get("services") or {})
+        tenants_config = self._build_tenants_config(raw.get("tenant_config") or {})
+        runtime_config = self._build_runtime_config()
+        infrastructure_config = self._build_infrastructure_config(runtime_config.environment)
+
+        product_enrich_raw = raw.get("product_enrich") if isinstance(raw.get("product_enrich"), dict) else {}
+        product_enrich_config = ProductEnrichConfig(
+            max_workers=int(product_enrich_raw.get("max_workers", 40)),
+        )
+
+        metadata = ConfigMetadata(
+            loaded_files=tuple(loaded_files),
+            config_hash="",
+            deprecated_keys=tuple(self._detect_deprecated_keys(raw)),
+        )
+
+        app_config = AppConfig(
+            runtime=runtime_config,
+            infrastructure=infrastructure_config,
+            product_enrich=product_enrich_config,
+            search=search_config,
+            services=services_config,
+            tenants=tenants_config,
+            assets=AssetsConfig(query_rewrite_dictionary_path=rewrite_path),
+            metadata=metadata,
+        )
+
+        config_hash = self._compute_hash(app_config)
+        return AppConfig(
+            runtime=app_config.runtime,
+            infrastructure=app_config.infrastructure,
+            product_enrich=app_config.product_enrich,
+            search=app_config.search,
+            services=app_config.services,
+            tenants=app_config.tenants,
+            assets=app_config.assets,
+            metadata=ConfigMetadata(
+                loaded_files=app_config.metadata.loaded_files,
+                config_hash=config_hash,
+                deprecated_keys=app_config.metadata.deprecated_keys,
+            ),
+        )
+
+    def _build_search_config(self, raw: Dict[str, Any], rewrite_dictionary: Dict[str, str]) -> SearchConfig:
+        field_boosts = raw.get("field_boosts") or {}
+        if not isinstance(field_boosts, dict):
+            raise ConfigurationError("field_boosts must be a mapping")
+
+        indexes: List[IndexConfig] = []
+        for item in raw.get("indexes") or []:
+            if not isinstance(item, dict):
+                raise ConfigurationError("indexes items must be mappings")
+            indexes.append(
+                IndexConfig(
+                    name=str(item["name"]),
+                    label=str(item.get("label") or item["name"]),
+                    fields=list(item.get("fields") or []),
+                    boost=float(item.get("boost", 1.0)),
+                    example=item.get("example"),
+                )
+            )
+
+        query_cfg = raw.get("query_config") if isinstance(raw.get("query_config"), dict) else {}
+        search_fields = query_cfg.get("search_fields") if isinstance(query_cfg.get("search_fields"), dict) else {}
+        text_strategy = (
+            query_cfg.get("text_query_strategy")
+            if isinstance(query_cfg.get("text_query_strategy"), dict)
+            else {}
+        )
+        query_config = QueryConfig(
+            supported_languages=list(query_cfg.get("supported_languages") or ["zh", "en"]),
+            default_language=str(query_cfg.get("default_language") or "en"),
+            enable_text_embedding=bool(query_cfg.get("enable_text_embedding", True)),
+            enable_query_rewrite=bool(query_cfg.get("enable_query_rewrite", True)),
+            rewrite_dictionary=rewrite_dictionary,
+            text_embedding_field=query_cfg.get("text_embedding_field"),
+            image_embedding_field=query_cfg.get("image_embedding_field"),
+            source_fields=query_cfg.get("source_fields"),
+            knn_boost=float(query_cfg.get("knn_boost", 0.25)),
+            multilingual_fields=list(
+                search_fields.get(
+                    "multilingual_fields",
+                    ["title", "brief", "description", "vendor", "category_path", "category_name_text"],
+                )
+            ),
+            shared_fields=list(
+                search_fields.get(
+                    "shared_fields",
+                    ["tags", "option1_values", "option2_values", "option3_values"],
+                )
+            ),
+            core_multilingual_fields=list(
+                search_fields.get(
+                    "core_multilingual_fields",
+                    ["title", "brief", "vendor", "category_name_text"],
+                )
+            ),
+            base_minimum_should_match=str(text_strategy.get("base_minimum_should_match", "75%")),
+            translation_minimum_should_match=str(text_strategy.get("translation_minimum_should_match", "75%")),
+            translation_boost=float(text_strategy.get("translation_boost", 0.4)),
+            translation_boost_when_source_missing=float(
+                text_strategy.get("translation_boost_when_source_missing", 1.0)
+            ),
+            source_boost_when_missing=float(text_strategy.get("source_boost_when_missing", 0.6)),
+            original_query_fallback_boost_when_translation_missing=float(
+                text_strategy.get("original_query_fallback_boost_when_translation_missing", 0.2)
+            ),
+            tie_breaker_base_query=float(text_strategy.get("tie_breaker_base_query", 0.9)),
+            zh_to_en_model=str(query_cfg.get("zh_to_en_model") or "opus-mt-zh-en"),
+            en_to_zh_model=str(query_cfg.get("en_to_zh_model") or "opus-mt-en-zh"),
+            default_translation_model=str(
+                query_cfg.get("default_translation_model") or "nllb-200-distilled-600m"
+            ),
+        )
+
+        function_score_cfg = raw.get("function_score") if isinstance(raw.get("function_score"), dict) else {}
+        rerank_cfg = raw.get("rerank") if isinstance(raw.get("rerank"), dict) else {}
+        spu_cfg = raw.get("spu_config") if isinstance(raw.get("spu_config"), dict) else {}
+
+        return SearchConfig(
+            field_boosts={str(key): float(value) for key, value in field_boosts.items()},
+            indexes=indexes,
+            query_config=query_config,
+            function_score=FunctionScoreConfig(
+                score_mode=str(function_score_cfg.get("score_mode") or "sum"),
+                boost_mode=str(function_score_cfg.get("boost_mode") or "multiply"),
+                functions=list(function_score_cfg.get("functions") or []),
+            ),
+            rerank=RerankConfig(
+                enabled=bool(rerank_cfg.get("enabled", True)),
+                rerank_window=int(rerank_cfg.get("rerank_window", 384)),
+                timeout_sec=float(rerank_cfg.get("timeout_sec", 15.0)),
+                weight_es=float(rerank_cfg.get("weight_es", 0.4)),
+                weight_ai=float(rerank_cfg.get("weight_ai", 0.6)),
+                rerank_query_template=str(rerank_cfg.get("rerank_query_template") or "{query}"),
+                rerank_doc_template=str(rerank_cfg.get("rerank_doc_template") or "{title}"),
+            ),
+            spu_config=SPUConfig(
+                enabled=bool(spu_cfg.get("enabled", False)),
+                spu_field=spu_cfg.get("spu_field"),
+                inner_hits_size=int(spu_cfg.get("inner_hits_size", 3)),
+                searchable_option_dimensions=list(
+                    spu_cfg.get("searchable_option_dimensions") or ["option1", "option2", "option3"]
+                ),
+            ),
+            es_index_name=str(raw.get("es_index_name") or "search_products"),
+            es_settings=dict(raw.get("es_settings") or {}),
+        )
+
+    def _build_services_config(self, raw: Dict[str, Any]) -> ServicesConfig:
+        if not isinstance(raw, dict):
+            raise ConfigurationError("services must be a mapping")
+
+        translation_raw = raw.get("translation") if isinstance(raw.get("translation"), dict) else {}
+        normalized_translation = build_translation_config(translation_raw)
+        translation_config = TranslationServiceConfig(
+            endpoint=str(normalized_translation["service_url"]).rstrip("/"),
+            timeout_sec=float(normalized_translation["timeout_sec"]),
+            default_model=str(normalized_translation["default_model"]),
+            default_scene=str(normalized_translation["default_scene"]),
+            cache=dict(normalized_translation["cache"]),
+            capabilities={str(key): dict(value) for key, value in normalized_translation["capabilities"].items()},
+        )
+
+        embedding_raw = raw.get("embedding") if isinstance(raw.get("embedding"), dict) else {}
+        embedding_provider = str(embedding_raw.get("provider") or "http").strip().lower()
+        embedding_providers = dict(embedding_raw.get("providers") or {})
+        if embedding_provider not in embedding_providers:
+            raise ConfigurationError(f"services.embedding.providers.{embedding_provider} must be configured")
+        embedding_backend = str(embedding_raw.get("backend") or "").strip().lower()
+        embedding_backends = {
+            str(key).strip().lower(): dict(value)
+            for key, value in dict(embedding_raw.get("backends") or {}).items()
+        }
+        if embedding_backend not in embedding_backends:
+            raise ConfigurationError(f"services.embedding.backends.{embedding_backend} must be configured")
+        image_backend = str(embedding_raw.get("image_backend") or "clip_as_service").strip().lower()
+        image_backends = {
+            str(key).strip().lower(): dict(value)
+            for key, value in dict(embedding_raw.get("image_backends") or {}).items()
+        }
+        if not image_backends:
+            image_backends = {
+                "clip_as_service": {
+                    "server": "grpc://127.0.0.1:51000",
+                    "model_name": "CN-CLIP/ViT-L-14",
+                    "batch_size": 8,
+                    "normalize_embeddings": True,
+                },
+                "local_cnclip": {
+                    "model_name": "ViT-L-14",
+                    "device": None,
+                    "batch_size": 8,
+                    "normalize_embeddings": True,
+                },
+            }
+        if image_backend not in image_backends:
+            raise ConfigurationError(f"services.embedding.image_backends.{image_backend} must be configured")
+
+        embedding_config = EmbeddingServiceConfig(
+            provider=embedding_provider,
+            providers=embedding_providers,
+            backend=embedding_backend,
+            backends=embedding_backends,
+            image_backend=image_backend,
+            image_backends=image_backends,
+        )
+
+        rerank_raw = raw.get("rerank") if isinstance(raw.get("rerank"), dict) else {}
+        rerank_provider = str(rerank_raw.get("provider") or "http").strip().lower()
+        rerank_providers = dict(rerank_raw.get("providers") or {})
+        if rerank_provider not in rerank_providers:
+            raise ConfigurationError(f"services.rerank.providers.{rerank_provider} must be configured")
+        rerank_backend = str(rerank_raw.get("backend") or "").strip().lower()
+        rerank_backends = {
+            str(key).strip().lower(): dict(value)
+            for key, value in dict(rerank_raw.get("backends") or {}).items()
+        }
+        if rerank_backend not in rerank_backends:
+            raise ConfigurationError(f"services.rerank.backends.{rerank_backend} must be configured")
+        rerank_request = dict(rerank_raw.get("request") or {})
+        rerank_request.setdefault("max_docs", 1000)
+        rerank_request.setdefault("normalize", True)
+
+        rerank_config = RerankServiceConfig(
+            provider=rerank_provider,
+            providers=rerank_providers,
+            backend=rerank_backend,
+            backends=rerank_backends,
+            request=rerank_request,
+        )
+
+        return ServicesConfig(
+            translation=translation_config,
+            embedding=embedding_config,
+            rerank=rerank_config,
+        )
+
+    def _build_tenants_config(self, raw: Dict[str, Any]) -> TenantCatalogConfig:
+        if not isinstance(raw, dict):
+            raise ConfigurationError("tenant_config must be a mapping")
+        default_cfg = raw.get("default") if isinstance(raw.get("default"), dict) else {}
+        tenants_cfg = raw.get("tenants") if isinstance(raw.get("tenants"), dict) else {}
+        return TenantCatalogConfig(
+            default=dict(default_cfg),
+            tenants={str(key): dict(value) for key, value in tenants_cfg.items()},
+        )
+
+    def _build_runtime_config(self) -> RuntimeConfig:
+        environment = (os.getenv("APP_ENV") or os.getenv("RUNTIME_ENV") or "prod").strip().lower() or "prod"
+        namespace = os.getenv("ES_INDEX_NAMESPACE")
+        if namespace is None:
+            namespace = "" if environment == "prod" else f"{environment}_"
+
+        return RuntimeConfig(
+            environment=environment,
+            index_namespace=namespace,
+            api_host=os.getenv("API_HOST", "0.0.0.0"),
+            api_port=int(os.getenv("API_PORT", 6002)),
+            indexer_host=os.getenv("INDEXER_HOST", "0.0.0.0"),
+            indexer_port=int(os.getenv("INDEXER_PORT", 6004)),
+            embedding_host=os.getenv("EMBEDDING_HOST", "127.0.0.1"),
+            embedding_port=int(os.getenv("EMBEDDING_PORT", 6005)),
+            embedding_text_port=int(os.getenv("EMBEDDING_TEXT_PORT", 6005)),
+            embedding_image_port=int(os.getenv("EMBEDDING_IMAGE_PORT", 6008)),
+            translator_host=os.getenv("TRANSLATION_HOST", "127.0.0.1"),
+            translator_port=int(os.getenv("TRANSLATION_PORT", 6006)),
+            reranker_host=os.getenv("RERANKER_HOST", "127.0.0.1"),
+            reranker_port=int(os.getenv("RERANKER_PORT", 6007)),
+        )
+
+    def _build_infrastructure_config(self, environment: str) -> InfrastructureConfig:
+        del environment
+        return InfrastructureConfig(
+            elasticsearch=ElasticsearchSettings(
+                host=os.getenv("ES_HOST", "http://localhost:9200"),
+                username=os.getenv("ES_USERNAME"),
+                password=os.getenv("ES_PASSWORD"),
+            ),
+            redis=RedisSettings(
+                host=os.getenv("REDIS_HOST", "localhost"),
+                port=int(os.getenv("REDIS_PORT", 6479)),
+                snapshot_db=int(os.getenv("REDIS_SNAPSHOT_DB", 0)),
+                password=os.getenv("REDIS_PASSWORD"),
+                socket_timeout=int(os.getenv("REDIS_SOCKET_TIMEOUT", 1)),
+                socket_connect_timeout=int(os.getenv("REDIS_SOCKET_CONNECT_TIMEOUT", 1)),
+                retry_on_timeout=os.getenv("REDIS_RETRY_ON_TIMEOUT", "false").strip().lower() == "true",
+                cache_expire_days=int(os.getenv("REDIS_CACHE_EXPIRE_DAYS", 360 * 2)),
+                embedding_cache_prefix=os.getenv("REDIS_EMBEDDING_CACHE_PREFIX", "embedding"),
+                anchor_cache_prefix=os.getenv("REDIS_ANCHOR_CACHE_PREFIX", "product_anchors"),
+                anchor_cache_expire_days=int(os.getenv("REDIS_ANCHOR_CACHE_EXPIRE_DAYS", 30)),
+            ),
+            database=DatabaseSettings(
+                host=os.getenv("DB_HOST"),
+                port=int(os.getenv("DB_PORT", 3306)) if os.getenv("DB_PORT") else 3306,
+                database=os.getenv("DB_DATABASE"),
+                username=os.getenv("DB_USERNAME"),
+                password=os.getenv("DB_PASSWORD"),
+            ),
+            secrets=SecretsConfig(
+                dashscope_api_key=os.getenv("DASHSCOPE_API_KEY"),
+                deepl_auth_key=os.getenv("DEEPL_AUTH_KEY"),
+            ),
+        )
+
+    def _validate(self, app_config: AppConfig) -> None:
+        errors: List[str] = []
+
+        if not app_config.search.es_index_name:
+            errors.append("search.es_index_name is required")
+
+        if not app_config.search.field_boosts:
+            errors.append("search.field_boosts cannot be empty")
+        else:
+            for field_name, boost in app_config.search.field_boosts.items():
+                if boost < 0:
+                    errors.append(f"field_boosts.{field_name} must be non-negative")
+
+        query_config = app_config.search.query_config
+        if not query_config.supported_languages:
+            errors.append("query_config.supported_languages must not be empty")
+        if query_config.default_language not in query_config.supported_languages:
+            errors.append("query_config.default_language must be included in supported_languages")
+        for name, values in (
+            ("multilingual_fields", query_config.multilingual_fields),
+            ("shared_fields", query_config.shared_fields),
+            ("core_multilingual_fields", query_config.core_multilingual_fields),
+        ):
+            if not values:
+                errors.append(f"query_config.{name} must not be empty")
+
+        if not set(query_config.core_multilingual_fields).issubset(set(query_config.multilingual_fields)):
+            errors.append("query_config.core_multilingual_fields must be a subset of multilingual_fields")
+
+        if app_config.search.spu_config.enabled and not app_config.search.spu_config.spu_field:
+            errors.append("spu_config.spu_field is required when spu_config.enabled is true")
+
+        if not app_config.tenants.default or not app_config.tenants.default.get("index_languages"):
+            errors.append("tenant_config.default.index_languages must be configured")
+
+        if app_config.metadata.deprecated_keys:
+            errors.append(
+                "Deprecated tenant config keys are not supported: "
+                + ", ".join(app_config.metadata.deprecated_keys)
+            )
+
+        embedding_provider_cfg = app_config.services.embedding.get_provider_config()
+        if not embedding_provider_cfg.get("text_base_url"):
+            errors.append("services.embedding.providers.<provider>.text_base_url is required")
+        if not embedding_provider_cfg.get("image_base_url"):
+            errors.append("services.embedding.providers.<provider>.image_base_url is required")
+
+        rerank_provider_cfg = app_config.services.rerank.get_provider_config()
+        if not rerank_provider_cfg.get("service_url") and not rerank_provider_cfg.get("base_url"):
+            errors.append("services.rerank.providers.<provider>.service_url or base_url is required")
+
+        if errors:
+            raise ConfigurationError("Configuration validation failed:\n" + "\n".join(f"  - {err}" for err in errors))
+
+    def _compute_hash(self, app_config: AppConfig) -> str:
+        payload = asdict(app_config)
+        payload["metadata"]["config_hash"] = ""
+        payload["infrastructure"]["elasticsearch"]["password"] = "***" if payload["infrastructure"]["elasticsearch"].get("password") else None
+        payload["infrastructure"]["database"]["password"] = "***" if payload["infrastructure"]["database"].get("password") else None
+        payload["infrastructure"]["redis"]["password"] = "***" if payload["infrastructure"]["redis"].get("password") else None
+        payload["infrastructure"]["secrets"]["dashscope_api_key"] = "***" if payload["infrastructure"]["secrets"].get("dashscope_api_key") else None
+        payload["infrastructure"]["secrets"]["deepl_auth_key"] = "***" if payload["infrastructure"]["secrets"].get("deepl_auth_key") else None
+        blob = json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+
+    def _detect_deprecated_keys(self, raw: Dict[str, Any]) -> Iterable[str]:
+        # Translation-era legacy flags have been removed; keep the hook for future
+        # deprecations, but currently no deprecated keys are detected.
+        return ()
+
+
+@lru_cache(maxsize=1)
+def get_app_config() -> AppConfig:
+    """Return the process-global application configuration."""
+
+    return AppConfigLoader().load()
+
+
+def reload_app_config() -> AppConfig:
+    """Clear the cached configuration and reload it."""
+
+    get_app_config.cache_clear()
+    return get_app_config()
+
+
+def _load_env_file_fallback(path: Path) -> None:
+    if not path.exists():
+        return
+    with open(path, "r", encoding="utf-8") as handle:
+        for raw_line in handle:
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if key and key not in os.environ:
+                os.environ[key] = value
@@ -0,0 +1,315 @@
+"""
+Typed configuration schema for the unified application configuration.
+
+This module defines the normalized in-memory structure used by all services.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class IndexConfig:
+    """Deprecated compatibility shape for legacy diagnostics/tests."""
+
+    name: str
+    label: str
+    fields: List[str]
+    boost: float = 1.0
+    example: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class QueryConfig:
+    """Configuration for query processing."""
+
+    supported_languages: List[str] = field(default_factory=lambda: ["zh", "en"])
+    default_language: str = "en"
+    enable_text_embedding: bool = True
+    enable_query_rewrite: bool = True
+    rewrite_dictionary: Dict[str, str] = field(default_factory=dict)
+    text_embedding_field: Optional[str] = "title_embedding"
+    image_embedding_field: Optional[str] = None
+    source_fields: Optional[List[str]] = None
+    knn_boost: float = 0.25
+    multilingual_fields: List[str] = field(
+        default_factory=lambda: [
+            "title",
+            "brief",
+            "description",
+            "vendor",
+            "category_path",
+            "category_name_text",
+        ]
+    )
+    shared_fields: List[str] = field(
+        default_factory=lambda: ["tags", "option1_values", "option2_values", "option3_values"]
+    )
+    core_multilingual_fields: List[str] = field(
+        default_factory=lambda: ["title", "brief", "vendor", "category_name_text"]
+    )
+    base_minimum_should_match: str = "75%"
+    translation_minimum_should_match: str = "75%"
+    translation_boost: float = 0.4
+    translation_boost_when_source_missing: float = 1.0
+    source_boost_when_missing: float = 0.6
+    original_query_fallback_boost_when_translation_missing: float = 0.2
+    tie_breaker_base_query: float = 0.9
+    zh_to_en_model: str = "opus-mt-zh-en"
+    en_to_zh_model: str = "opus-mt-en-zh"
+    default_translation_model: str = "nllb-200-distilled-600m"
+
+
+@dataclass(frozen=True)
+class SPUConfig:
+    """SPU aggregation/search configuration."""
+
+    enabled: bool = False
+    spu_field: Optional[str] = None
+    inner_hits_size: int = 3
+    searchable_option_dimensions: List[str] = field(
+        default_factory=lambda: ["option1", "option2", "option3"]
+    )
+
+
+@dataclass(frozen=True)
+class FunctionScoreConfig:
+    """Function score configuration."""
+
+    score_mode: str = "sum"
+    boost_mode: str = "multiply"
+    functions: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class RerankConfig:
+    """Search-time rerank configuration."""
+
+    enabled: bool = True
+    rerank_window: int = 384
+    timeout_sec: float = 15.0
+    weight_es: float = 0.4
+    weight_ai: float = 0.6
+    rerank_query_template: str = "{query}"
+    rerank_doc_template: str = "{title}"
+
+
+@dataclass(frozen=True)
+class SearchConfig:
+    """Search behavior configuration shared by backend and indexer."""
+
+    field_boosts: Dict[str, float]
+    indexes: List[IndexConfig] = field(default_factory=list)
+    query_config: QueryConfig = field(default_factory=QueryConfig)
+    function_score: FunctionScoreConfig = field(default_factory=FunctionScoreConfig)
+    rerank: RerankConfig = field(default_factory=RerankConfig)
+    spu_config: SPUConfig = field(default_factory=SPUConfig)
+    es_index_name: str = "search_products"
+    es_settings: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TranslationServiceConfig:
+    """Translator service configuration."""
+
+    endpoint: str
+    timeout_sec: float
+    default_model: str
+    default_scene: str
+    cache: Dict[str, Any]
+    capabilities: Dict[str, Dict[str, Any]]
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "service_url": self.endpoint,
+            "timeout_sec": self.timeout_sec,
+            "default_model": self.default_model,
+            "default_scene": self.default_scene,
+            "cache": self.cache,
+            "capabilities": self.capabilities,
+        }
+
+
+@dataclass(frozen=True)
+class EmbeddingServiceConfig:
+    """Embedding service configuration."""
+
+    provider: str
+    providers: Dict[str, Any]
+    backend: str
+    backends: Dict[str, Dict[str, Any]]
+    image_backend: str
+    image_backends: Dict[str, Dict[str, Any]]
+
+    def get_provider_config(self) -> Dict[str, Any]:
+        return dict(self.providers.get(self.provider, {}) or {})
+
+    def get_backend_config(self) -> Dict[str, Any]:
+        return dict(self.backends.get(self.backend, {}) or {})
+
+    def get_image_backend_config(self) -> Dict[str, Any]:
+        return dict(self.image_backends.get(self.image_backend, {}) or {})
+
+
+@dataclass(frozen=True)
+class RerankServiceConfig:
+    """Reranker service configuration."""
+
+    provider: str
+    providers: Dict[str, Any]
+    backend: str
+    backends: Dict[str, Dict[str, Any]]
+    request: Dict[str, Any]
+
+    def get_provider_config(self) -> Dict[str, Any]:
+        return dict(self.providers.get(self.provider, {}) or {})
+
+    def get_backend_config(self) -> Dict[str, Any]:
+        return dict(self.backends.get(self.backend, {}) or {})
+
+
+@dataclass(frozen=True)
+class ServicesConfig:
+    """All service-level configuration."""
+
+    translation: TranslationServiceConfig
+    embedding: EmbeddingServiceConfig
+    rerank: RerankServiceConfig
+
+
+@dataclass(frozen=True)
+class TenantCatalogConfig:
+    """Tenant catalog configuration."""
+
+    default: Dict[str, Any]
+    tenants: Dict[str, Dict[str, Any]]
+
+    def get_raw(self) -> Dict[str, Any]:
+        return {
+            "default": dict(self.default),
+            "tenants": {str(key): dict(value) for key, value in self.tenants.items()},
+        }
+
+
+@dataclass(frozen=True)
+class ElasticsearchSettings:
+    host: str = "http://localhost:9200"
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RedisSettings:
+    host: str = "localhost"
+    port: int = 6479
+    snapshot_db: int = 0
+    password: Optional[str] = None
+    socket_timeout: int = 1
+    socket_connect_timeout: int = 1
+    retry_on_timeout: bool = False
+    cache_expire_days: int = 720
+    embedding_cache_prefix: str = "embedding"
+    anchor_cache_prefix: str = "product_anchors"
+    anchor_cache_expire_days: int = 30
+
+
+@dataclass(frozen=True)
+class DatabaseSettings:
+    host: Optional[str] = None
+    port: int = 3306
+    database: Optional[str] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class SecretsConfig:
+    dashscope_api_key: Optional[str] = None
+    deepl_auth_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class InfrastructureConfig:
+    elasticsearch: ElasticsearchSettings
+    redis: RedisSettings
+    database: DatabaseSettings
+    secrets: SecretsConfig
+
+
+@dataclass(frozen=True)
+class ProductEnrichConfig:
+    """Configuration for LLM-based product content understanding (enrich-content)."""
+
+    max_workers: int = 40
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    environment: str = "prod"
+    index_namespace: str = ""
+    api_host: str = "0.0.0.0"
+    api_port: int = 6002
+    indexer_host: str = "0.0.0.0"
+    indexer_port: int = 6004
+    embedding_host: str = "127.0.0.1"
+    embedding_port: int = 6005
+    embedding_text_port: int = 6005
+    embedding_image_port: int = 6008
+    translator_host: str = "127.0.0.1"
+    translator_port: int = 6006
+    reranker_host: str = "127.0.0.1"
+    reranker_port: int = 6007
+
+
+@dataclass(frozen=True)
+class AssetsConfig:
+    query_rewrite_dictionary_path: Path
+
+
+@dataclass(frozen=True)
+class ConfigMetadata:
+    loaded_files: Tuple[str, ...]
+    config_hash: str
+    deprecated_keys: Tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Root application configuration."""
+
+    runtime: RuntimeConfig
+    infrastructure: InfrastructureConfig
+    product_enrich: ProductEnrichConfig
+    search: SearchConfig
+    services: ServicesConfig
+    tenants: TenantCatalogConfig
+    assets: AssetsConfig
+    metadata: ConfigMetadata
+
+    def sanitized_dict(self) -> Dict[str, Any]:
+        data = asdict(self)
+        data["infrastructure"]["elasticsearch"]["password"] = _mask_secret(
+            data["infrastructure"]["elasticsearch"].get("password")
+        )
+        data["infrastructure"]["database"]["password"] = _mask_secret(
+            data["infrastructure"]["database"].get("password")
+        )
+        data["infrastructure"]["redis"]["password"] = _mask_secret(
+            data["infrastructure"]["redis"].get("password")
+        )
+        data["infrastructure"]["secrets"]["dashscope_api_key"] = _mask_secret(
+            data["infrastructure"]["secrets"].get("dashscope_api_key")
+        )
+        data["infrastructure"]["secrets"]["deepl_auth_key"] = _mask_secret(
+            data["infrastructure"]["secrets"].get("deepl_auth_key")
+        )
+        return data
+
+
+def _mask_secret(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return value
+    return "***"
 """
-Services configuration - single source for translation, embedding, rerank.
+Unified service configuration accessors.
-Translation is modeled as:
-- one translator service endpoint used by business callers
-- multiple translation capabilities loaded inside the translator service
+This module is now a thin adapter over ``config.loader.get_app_config`` and
+contains no independent parsing or precedence logic.
 """
 from __future__ import annotations
-import os
-from dataclasses import dataclass, field
-from functools import lru_cache
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-import yaml
-from translation.settings import TranslationConfig, build_translation_config, get_translation_cache
-
-
-@dataclass
-class ServiceConfig:
-    """Config for one capability (embedding/rerank)."""
-
-    provider: str
-    providers: Dict[str, Any] = field(default_factory=dict)
-
-    def get_provider_cfg(self) -> Dict[str, Any]:
-        p = (self.provider or "").strip().lower()
-        return self.providers.get(p, {}) if isinstance(self.providers, dict) else {}
-
-
-def _load_services_raw(config_path: Optional[Path] = None) -> Dict[str, Any]:
-    if config_path is None:
-        config_path = Path(__file__).parent / "config.yaml"
-    path = Path(config_path)
-    if not path.exists():
-        raise FileNotFoundError(f"services config file not found: {path}")
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = yaml.safe_load(f)
-    except Exception as exc:
-        raise RuntimeError(f"failed to parse services config from {path}: {exc}") from exc
-    if not isinstance(data, dict):
-        raise RuntimeError(f"invalid config format in {path}: expected mapping root")
-    services = data.get("services")
-    if not isinstance(services, dict):
-        raise RuntimeError("config.yaml must contain a valid 'services' mapping")
-    return services
-
-
-def _resolve_provider_name(env_name: str, config_provider: Any, capability: str) -> str:
-    provider = os.getenv(env_name) or config_provider
-    if not provider:
-        raise ValueError(
-            f"services.{capability}.provider is required "
-            f"(or set env override {env_name})"
-        )
-    return str(provider).strip().lower()
-
-
-def _resolve_translation() -> TranslationConfig:
-    raw = _load_services_raw()
-    cfg = raw.get("translation", {}) if isinstance(raw.get("translation"), dict) else {}
-    return build_translation_config(cfg)
-
-
-def _resolve_embedding() -> ServiceConfig:
-    raw = _load_services_raw()
-    cfg = raw.get("embedding", {}) if isinstance(raw.get("embedding"), dict) else {}
-    providers = cfg.get("providers", {}) if isinstance(cfg.get("providers"), dict) else {}
-
-    provider = _resolve_provider_name(
-        env_name="EMBEDDING_PROVIDER",
-        config_provider=cfg.get("provider"),
-        capability="embedding",
-    )
-    if provider != "http":
-        raise ValueError(f"Unsupported embedding provider: {provider}")
-
-    env_text_url = os.getenv("EMBEDDING_TEXT_SERVICE_URL")
-    env_image_url = os.getenv("EMBEDDING_IMAGE_SERVICE_URL")
-    if provider == "http":
-        providers = dict(providers)
-        http_cfg = dict(providers.get("http", {}))
-        if env_text_url:
-            http_cfg["text_base_url"] = env_text_url.rstrip("/")
-        if env_image_url:
-            http_cfg["image_base_url"] = env_image_url.rstrip("/")
-        if not http_cfg.get("text_base_url"):
-            raise ValueError("services.embedding.providers.http.text_base_url is required")
-        if not http_cfg.get("image_base_url"):
-            raise ValueError("services.embedding.providers.http.image_base_url is required")
-        providers["http"] = http_cfg
-
-    return ServiceConfig(provider=provider, providers=providers)
-
-
-def _resolve_rerank() -> ServiceConfig:
-    raw = _load_services_raw()
-    cfg = raw.get("rerank", {}) if isinstance(raw.get("rerank"), dict) else {}
-    providers = cfg.get("providers", {}) if isinstance(cfg.get("providers"), dict) else {}
-
-    provider = _resolve_provider_name(
-        env_name="RERANK_PROVIDER",
-        config_provider=cfg.get("provider"),
-        capability="rerank",
-    )
-    if provider != "http":
-        raise ValueError(f"Unsupported rerank provider: {provider}")
-
-    env_url = os.getenv("RERANKER_SERVICE_URL")
-    if env_url:
-        url = env_url.rstrip("/")
-        if not url.endswith("/rerank"):
-            url = f"{url}/rerank" if "/rerank" not in url else url
-        providers = dict(providers)
-        providers["http"] = dict(providers.get("http", {}))
-        providers["http"]["base_url"] = url.replace("/rerank", "")
-        providers["http"]["service_url"] = url
-
-    return ServiceConfig(provider=provider, providers=providers)
-
-
-def get_rerank_backend_config() -> tuple[str, dict]:
-    raw = _load_services_raw()
-    cfg = raw.get("rerank", {}) if isinstance(raw.get("rerank"), dict) else {}
-    backends = cfg.get("backends", {}) if isinstance(cfg.get("backends"), dict) else {}
-    name = os.getenv("RERANK_BACKEND") or cfg.get("backend")
-    if not name:
-        raise ValueError("services.rerank.backend is required (or env RERANK_BACKEND)")
-    name = str(name).strip().lower()
-    backend_cfg = backends.get(name, {}) if isinstance(backends.get(name), dict) else {}
-    if not backend_cfg:
-        raise ValueError(f"services.rerank.backends.{name} is required")
-    return name, backend_cfg
-
-
-def get_embedding_backend_config() -> tuple[str, dict]:
-    raw = _load_services_raw()
-    cfg = raw.get("embedding", {}) if isinstance(raw.get("embedding"), dict) else {}
-    backends = cfg.get("backends", {}) if isinstance(cfg.get("backends"), dict) else {}
-    name = os.getenv("EMBEDDING_BACKEND") or cfg.get("backend")
-    if not name:
-        raise ValueError("services.embedding.backend is required (or env EMBEDDING_BACKEND)")
-    name = str(name).strip().lower()
-    backend_cfg = backends.get(name, {}) if isinstance(backends.get(name), dict) else {}
-    if not backend_cfg:
-        raise ValueError(f"services.embedding.backends.{name} is required")
-    return name, backend_cfg
-
-
-@lru_cache(maxsize=1)
-def get_translation_config() -> TranslationConfig:
-    return _resolve_translation()
-
-
-@lru_cache(maxsize=1)
-def get_embedding_config() -> ServiceConfig:
-    return _resolve_embedding()
-
-
-@lru_cache(maxsize=1)
-def get_rerank_config() -> ServiceConfig:
-    return _resolve_rerank()
+from typing import Any, Dict, Tuple
+
+from config.loader import get_app_config
+from config.schema import EmbeddingServiceConfig, RerankServiceConfig, TranslationServiceConfig
+
+
+def get_translation_config() -> Dict[str, Any]:
+    return get_app_config().services.translation.as_dict()
+
+
+def get_embedding_config() -> EmbeddingServiceConfig:
+    return get_app_config().services.embedding
+
+
+def get_rerank_config() -> RerankServiceConfig:
+    return get_app_config().services.rerank
 def get_translation_base_url() -> str:
-    return str(get_translation_config()["service_url"])
+    return get_app_config().services.translation.endpoint
 def get_translation_cache_config() -> Dict[str, Any]:
-    return get_translation_cache(get_translation_config())
+    return dict(get_app_config().services.translation.cache)
 def get_embedding_text_base_url() -> str:
-    provider_cfg = get_embedding_config().providers.get("http", {})
-    base = os.getenv("EMBEDDING_TEXT_SERVICE_URL") or provider_cfg.get("text_base_url")
+    provider_cfg = get_app_config().services.embedding.get_provider_config()
+    base = provider_cfg.get("text_base_url")
     if not base:
-        raise ValueError("Embedding text HTTP base_url is not configured")
+        raise ValueError("Embedding text base_url is not configured")
     return str(base).rstrip("/")
 def get_embedding_image_base_url() -> str:
-    provider_cfg = get_embedding_config().providers.get("http", {})
-    base = os.getenv("EMBEDDING_IMAGE_SERVICE_URL") or provider_cfg.get("image_base_url")
+    provider_cfg = get_app_config().services.embedding.get_provider_config()
+    base = provider_cfg.get("image_base_url")
     if not base:
-        raise ValueError("Embedding image HTTP base_url is not configured")
+        raise ValueError("Embedding image base_url is not configured")
     return str(base).rstrip("/")
+def get_embedding_backend_config() -> Tuple[str, Dict[str, Any]]:
+    cfg = get_app_config().services.embedding
+    return cfg.backend, cfg.get_backend_config()
+
+
+def get_embedding_image_backend_config() -> Tuple[str, Dict[str, Any]]:
+    cfg = get_app_config().services.embedding
+    return cfg.image_backend, cfg.get_image_backend_config()
+
+
+def get_rerank_backend_config() -> Tuple[str, Dict[str, Any]]:
+    cfg = get_app_config().services.rerank
+    return cfg.backend, cfg.get_backend_config()
+
+
 def get_rerank_base_url() -> str:
-    base = (
-        os.getenv("RERANKER_SERVICE_URL")
-        or get_rerank_config().providers.get("http", {}).get("service_url")
-        or get_rerank_config().providers.get("http", {}).get("base_url")
-    )
+    provider_cfg = get_app_config().services.rerank.get_provider_config()
+    base = provider_cfg.get("service_url") or provider_cfg.get("base_url")
     if not base:
-        raise ValueError("Rerank HTTP base_url is not configured")
+        raise ValueError("Rerank service URL is not configured")
     return str(base).rstrip("/")
 def get_rerank_service_url() -> str:
-    """Backward-compatible alias."""
     return get_rerank_base_url()
@@ -2,12 +2,13 @@
 租户配置加载器。
 从统一配置文件（config.yaml）加载租户配置，包括主语言和索引语言（index_languages）。
-支持旧配置 translate_to_en / translate_to_zh 的兼容解析。
 """
 import logging
 from typing import Dict, Any, Optional, List
+from config.loader import get_app_config
+
 logger = logging.getLogger(__name__)
 # 支持的索引语言：code -> display name（供商家勾选主市场语言等场景使用）
@@ -83,25 +84,13 @@ def resolve_index_languages(
 ) -> List[str]:
     """
     从租户配置解析 index_languages。
-    若存在 index_languages 则用之；否则按旧配置 translate_to_en / translate_to_zh 推导。
+    若配置缺失或非法，则回退到默认配置。
     """
-    if "index_languages" in tenant_config:
-        normalized = normalize_index_languages(
-            tenant_config["index_languages"],
-            tenant_config.get("primary_language") or "en",
-        )
-        return normalized if normalized else list(default_index_languages)
-    primary = (tenant_config.get("primary_language") or "en").strip().lower()
-    to_en = bool(tenant_config.get("translate_to_en"))
-    to_zh = bool(tenant_config.get("translate_to_zh"))
-    langs: List[str] = []
-    if primary and primary in SOURCE_LANG_CODE_MAP:
-        langs.append(primary)
-    for code in ("en", "zh"):
-        if code not in langs and ((code == "en" and to_en) or (code == "zh" and to_zh)):
-            if code in SOURCE_LANG_CODE_MAP:
-                langs.append(code)
-    return langs if langs else list(default_index_languages)
+    normalized = normalize_index_languages(
+        tenant_config.get("index_languages"),
+        tenant_config.get("primary_language") or "en",
+    )
+    return normalized if normalized else list(default_index_languages)
 class TenantConfigLoader:
@@ -122,15 +111,8 @@ class TenantConfigLoader:
             return self._config
         try:
-            from config import ConfigLoader
-
-            config_loader = ConfigLoader()
-            search_config = config_loader.load_config()
-            tenant_cfg = search_config.tenant_config
-            if not isinstance(tenant_cfg, dict):
-                raise RuntimeError("tenant_config must be an object")
-
-            default_cfg = tenant_cfg.get("default")
+            tenant_cfg = get_app_config().tenants
+            default_cfg = tenant_cfg.default
             if not isinstance(default_cfg, dict):
                 raise RuntimeError("tenant_config.default must be configured in config.yaml")
             default_primary = (default_cfg.get("primary_language") or "en").strip().lower()
@@ -143,7 +125,7 @@ class TenantConfigLoader:
                     "tenant_config.default.index_languages must include at least one supported language"
                 )
-            tenants_cfg = tenant_cfg.get("tenants", {})
+            tenants_cfg = tenant_cfg.tenants
             if not isinstance(tenants_cfg, dict):
                 raise RuntimeError("tenant_config.tenants must be an object")
 """Configuration helper functions for dynamic multi-language search fields."""
 from typing import Dict, List
-from .config_loader import SearchConfig
+
+from config.schema import SearchConfig
 def _format_field_with_boost(field_name: str, boost: float) -> str:
@@ -0,0 +1,738 @@
+# Configuration System Review And Redesign
+
+## 1. Goal
+
+This document reviews the current configuration system and proposes a practical redesign for long-term maintainability.
+
+The target is a configuration system that is:
+
+- unified in loading and ownership
+- clear in boundaries and precedence
+- visible in effective behavior
+- easy to evolve across development, deployment, and operations
+
+This review is based on the current implementation, not only on the intended architecture in docs.
+
+## 2. Project Context
+
+The repo already defines the right architectural direction:
+
+- `config/config.yaml` should be the main configuration source for search behavior and service wiring
+- `.env` should mainly carry deployment-specific values and secrets
+- provider/backend expansion should stay centralized instead of spreading through business code
+
+That direction is described in:
+
+- [`README.md`](/data/saas-search/README.md)
+- [`docs/DEVELOPER_GUIDE.md`](/data/saas-search/docs/DEVELOPER_GUIDE.md)
+- [`docs/QUICKSTART.md`](/data/saas-search/docs/QUICKSTART.md)
+- [`translation/README.md`](/data/saas-search/translation/README.md)
+
+The problem is not the architectural intent. The problem is that the current implementation only partially follows it.
+
+## 3. Current-State Review
+
+### 3.1 What exists today
+
+The current system effectively has several configuration channels:
+
+- `config/config.yaml`
+  - search behavior
+  - rerank behavior
+  - services registry
+  - tenant config
+- `config/config_loader.py`
+  - parses search behavior and tenant config into `SearchConfig`
+  - also injects some defaults from code
+- `config/services_config.py`
+  - reparses `config/config.yaml` again, independently
+  - resolves translation, embedding, rerank service config
+  - also applies env overrides
+- `config/env_config.py`
+  - loads `.env`
+  - defines ES, Redis, DB, host/port, service URLs, namespace, model path defaults
+- service-local config modules
+  - [`embeddings/config.py`](/data/saas-search/embeddings/config.py)
+  - [`reranker/config.py`](/data/saas-search/reranker/config.py)
+- startup scripts
+  - derive defaults from shell env, Python config, and YAML in different combinations
+- inline fallbacks in business logic
+  - query parsing
+  - indexing
+  - service startup
+
+### 3.2 Main findings
+
+#### Finding A: there is no single loader for the full effective configuration
+
+`ConfigLoader` and `services_config` both parse `config/config.yaml`, but they do so separately and with different responsibilities.
+
+- [`config/config_loader.py`](/data/saas-search/config/config_loader.py#L148)
+- [`config/services_config.py`](/data/saas-search/config/services_config.py#L33)
+
+Impact:
+
+- the same file is loaded twice through different code paths
+- search config and services config can drift in interpretation
+- alternative config paths are hard to support cleanly
+- tests and tools cannot ask one place for the full effective config tree
+
+#### Finding B: precedence is not explicit, stable, or globally enforced
+
+Current precedence differs by subsystem:
+
+- search behavior mostly comes from YAML plus code defaults
+- embedding and rerank allow env overrides for provider/backend/url
+- translation intentionally blocks some env overrides
+- startup scripts still choose host/port and mode via env
+- some values are reconstructed from other env vars
+
+Examples:
+
+- env override for embedding provider/url/backend:
+  - [`config/services_config.py`](/data/saas-search/config/services_config.py#L52)
+  - [`config/services_config.py`](/data/saas-search/config/services_config.py#L68)
+  - [`config/services_config.py`](/data/saas-search/config/services_config.py#L139)
+- host/port and service URL reconstruction:
+  - [`config/env_config.py`](/data/saas-search/config/env_config.py#L55)
+  - [`config/env_config.py`](/data/saas-search/config/env_config.py#L75)
+- translator host/port still driven by startup env:
+  - [`scripts/start_translator.sh`](/data/saas-search/scripts/start_translator.sh#L28)
+
+Impact:
+
+- operators cannot reliably predict the effective configuration by reading one file
+- the same setting category behaves differently across services
+- incidents become harder to debug because source-of-truth depends on the code path
+
+#### Finding C: defaults are duplicated across YAML and code
+
+There are several layers of default values:
+
+- dataclass defaults in `QueryConfig`
+- fallback defaults in `ConfigLoader._parse_config`
+- defaults in `config.yaml`
+- defaults in `env_config.py`
+- defaults in `embeddings/config.py`
+- defaults in `reranker/config.py`
+- defaults in startup scripts
+
+Examples:
+
+- query defaults duplicated in dataclass and parser:
+  - [`config/config_loader.py`](/data/saas-search/config/config_loader.py#L24)
+  - [`config/config_loader.py`](/data/saas-search/config/config_loader.py#L240)
+- embedding defaults duplicated in YAML, `services_config`, `embeddings/config.py`, and startup script:
+  - [`config/config.yaml`](/data/saas-search/config/config.yaml#L196)
+  - [`embeddings/config.py`](/data/saas-search/embeddings/config.py#L14)
+  - [`scripts/start_embedding_service.sh`](/data/saas-search/scripts/start_embedding_service.sh#L29)
+- reranker defaults duplicated in YAML and `reranker/config.py`:
+  - [`config/config.yaml`](/data/saas-search/config/config.yaml#L214)
+  - [`reranker/config.py`](/data/saas-search/reranker/config.py#L6)
+
+Impact:
+
+- changing a default is risky because there may be multiple hidden copies
+- code review cannot easily tell whether a value is authoritative or dead legacy
+- “same config” may behave differently across processes
+
+#### Finding D: config is still embedded in runtime logic
+
+Some important behavior remains encoded as inline fallback logic rather than declared config.
+
+Examples:
+
+- query-time translation target languages fallback to `["en", "zh"]`:
+  - [`query/query_parser.py`](/data/saas-search/query/query_parser.py#L339)
+- indexer text handling and LLM enrichment also fallback to `["en", "zh"]`:
+  - [`indexer/document_transformer.py`](/data/saas-search/indexer/document_transformer.py#L216)
+  - [`indexer/document_transformer.py`](/data/saas-search/indexer/document_transformer.py#L310)
+  - [`indexer/document_transformer.py`](/data/saas-search/indexer/document_transformer.py#L649)
+
+Impact:
+
+- configuration is not fully visible in config files
+- behavior can silently change when tenant config is missing or malformed
+- “default behavior” is spread across business modules
+
+#### Finding E: some configuration assets are not managed as first-class config
+
+Query rewrite is configured through an external file, but the file path is hardcoded and currently inconsistent with the repository content.
+
+- loader expects:
+  - [`config/config_loader.py`](/data/saas-search/config/config_loader.py#L162)
+- repo currently contains:
+  - [`config/query_rewrite.dict`](/data/saas-search/config/query_rewrite.dict)
+
+There is also an admin API that mutates rewrite rules in memory only:
+
+- [`api/routes/admin.py`](/data/saas-search/api/routes/admin.py#L68)
+- [`query/query_parser.py`](/data/saas-search/query/query_parser.py#L622)
+
+Impact:
+
+- rewrite rules are neither cleanly file-backed nor fully runtime-managed
+- restart behavior is unclear
+- configuration visibility and persistence are weak
+
+#### Finding F: visibility is limited
+
+The system exposes only a small sanitized subset at `/admin/config`.
+
+- [`api/routes/admin.py`](/data/saas-search/api/routes/admin.py#L42)
+
+At the same time, the true effective config includes:
+
+- tenant overlays
+- env overrides
+- service backend selections
+- script-selected modes
+- hidden defaults in code
+
+Impact:
+
+- there is no authoritative “effective config” view
+- debugging configuration mismatches requires source reading
+- operators cannot easily verify what each process actually started with
+
+#### Finding G: the indexer does not really consume the unified config as a first-class dependency
+
+Indexer startup explicitly says config is loaded only for parity/logging and routes do not depend on it.
+
+- [`api/indexer_app.py`](/data/saas-search/api/indexer_app.py#L76)
+
+Impact:
+
+- configuration is not truly system-wide
+- search-side and indexer-side behavior can drift
+- the current “unified config” is only partially unified
+
+#### Finding H: docs still carry legacy and mixed mental models
+
+Most high-level docs describe the desired centralized model, but some implementation/docs still expose legacy concepts such as `translate_to_en` and `translate_to_zh`.
+
+- desired model:
+  - [`README.md`](/data/saas-search/README.md#L78)
+  - [`docs/DEVELOPER_GUIDE.md`](/data/saas-search/docs/DEVELOPER_GUIDE.md#L207)
+  - [`translation/README.md`](/data/saas-search/translation/README.md#L161)
+- legacy tenant translation flags still documented:
+  - [`indexer/README.md`](/data/saas-search/indexer/README.md#L39)
+
+Impact:
+
+- new developers may follow old mental models
+- cleanup work keeps getting deferred because old and new systems appear both “supported”
+
+## 4. Design Principles For The Redesign
+
+The redesign should follow these rules.
+
+### 4.1 One logical configuration system
+
+It is acceptable to have multiple files, but not multiple loaders with overlapping ownership.
+
+There must be one loader pipeline that produces one typed `AppConfig`.
+
+### 4.2 Configuration files declare, parser code interprets, env provides runtime injection
+
+Responsibilities should be:
+
+- configuration files
+  - declare non-secret desired behavior and non-secret deployable settings
+- parsing logic
+  - load, merge, validate, normalize, and expose typed config
+  - never invent hidden business behavior
+- environment variables
+  - carry secrets and a small set of runtime/process values
+  - do not redefine business behavior casually
+
+### 4.3 One precedence rule for the whole system
+
+Every config category should follow the same merge model unless explicitly exempted.
+
+### 4.4 No silent implicit fallback for business behavior
+
+Fail fast at startup when required config is missing or invalid.
+
+Do not silently fall back to legacy behavior such as hardcoded language lists.
+
+### 4.5 Effective configuration must be observable
+
+Every service should be able to show:
+
+- config version or hash
+- source files loaded
+- environment name
+- sanitized effective configuration
+
+## 5. Recommended Target Design
+
+## 5.1 Boundary model
+
+Use three clear layers.
+
+### Layer 1: repository-managed static config
+
+Purpose:
+
+- search behavior
+- tenant behavior
+- provider/backend registry
+- non-secret service topology defaults
+- feature switches
+
+Examples:
+
+- field boosts
+- query strategy
+- rerank fusion parameters
+- tenant language plans
+- translation capability registry
+- embedding backend selection default
+
+### Layer 2: environment-specific overlays
+
+Purpose:
+
+- per-environment non-secret differences
+- service endpoints by environment
+- resource sizing defaults by environment
+- dev/test/prod operational differences
+
+Examples:
+
+- local embedding URL vs production URL
+- dev rerank backend vs prod rerank backend
+- lower concurrency in local development
+
+### Layer 3: environment variables
+
+Purpose:
+
+- secrets
+- bind host/port
+- external infrastructure credentials
+- container-orchestrator last-mile injection
+
+Examples:
+
+- `ES_HOST`, `ES_USERNAME`, `ES_PASSWORD`
+- `DB_HOST`, `DB_USERNAME`, `DB_PASSWORD`
+- `REDIS_HOST`, `REDIS_PASSWORD`
+- `DASHSCOPE_API_KEY`, `DEEPL_AUTH_KEY`
+- `API_HOST`, `API_PORT`, `INDEXER_PORT`, `TRANSLATION_PORT`
+
+Rule:
+
+- environment variables should not be the normal path for choosing business behavior such as translation model, embedding backend, or tenant language policy
+- if an env override is allowed for a non-secret field, it must be explicitly listed and documented as an operational override, not a hidden convention
+
+## 5.2 Unified precedence
+
+Recommended precedence:
+
+1. schema defaults in code
+2. `config/base.yaml`
+3. `config/environments/<env>.yaml`
+4. tenant overlay from `config/tenants/`
+5. environment variables for the explicitly allowed runtime keys
+6. CLI flags for the current process only
+
+Important rule:
+
+- only one module may implement this merge logic
+- no business module may call `os.getenv()` directly for configuration
+
+## 5.3 Recommended directory structure
+
+```text
+config/
+  schema.py
+  loader.py
+  sources.py
+  base.yaml
+  environments/
+    dev.yaml
+    test.yaml
+    prod.yaml
+  tenants/
+    _default.yaml
+    1.yaml
+    162.yaml
+    170.yaml
+  dictionaries/
+    query_rewrite.dict
+  README.md
+.env.example
+```
+
+Notes:
+
+- `base.yaml` contains shared defaults and feature behavior
+- `environments/*.yaml` contains environment-specific non-secret overrides
+- `tenants/*.yaml` contains tenant-specific overrides only
+- `dictionaries/` stores first-class config assets such as rewrite dictionaries
+- `schema.py` defines the typed config model
+- `loader.py` is the only entry point that loads and merges config
+
+If the team prefers fewer files, `tenants.yaml` is also acceptable. The key requirement is not “one file”, but “one loading model with clear ownership”.
+
+## 5.4 Typed configuration model
+
+Introduce one root object, for example:
+
+```python
+class AppConfig(BaseModel):
+    runtime: RuntimeConfig
+    infrastructure: InfrastructureConfig
+    search: SearchConfig
+    services: ServicesConfig
+    tenants: TenantCatalogConfig
+    assets: ConfigAssets
+```
+
+Suggested subtrees:
+
+- `runtime`
+  - environment name
+  - config revision/hash
+  - bind addresses/ports
+- `infrastructure`
+  - ES
+  - DB
+  - Redis
+  - index namespace
+- `search`
+  - field boosts
+  - query config
+  - function score
+  - rerank behavior
+  - spu config
+- `services`
+  - translation
+  - embedding
+  - rerank
+- `tenants`
+  - default tenant config
+  - tenant overrides
+- `assets`
+  - rewrite dictionary path
+
+Benefits:
+
+- one validated object shared by backend, indexer, translator, embedding, reranker
+- one place for defaults
+- one place for schema evolution
+
+## 5.5 Loading flow
+
+Recommended loading flow:
+
+1. determine `APP_ENV` or `RUNTIME_ENV`
+2. load schema defaults
+3. load `config/base.yaml`
+4. load `config/environments/<env>.yaml` if present
+5. load tenant files
+6. inject first-class assets such as rewrite dictionary
+7. apply allowed env overrides
+8. validate the final `AppConfig`
+9. freeze and cache the config object
+10. expose a sanitized effective-config view
+
+Important:
+
+- every process should call the same loader
+- services should receive a resolved `AppConfig`, not re-open YAML independently
+
+## 5.6 Clear responsibility split
+
+### Configuration files are responsible for
+
+- what the system should do
+- what providers/backends are available
+- which features are enabled
+- tenant language/index policies
+- non-secret service topology
+
+### Parser/loader code is responsible for
+
+- locating sources
+- merge precedence
+- type validation
+- normalization
+- deprecation warnings
+- producing the final immutable config object
+
+### Environment variables are responsible for
+
+- secrets
+- bind addresses/ports
+- infrastructure endpoints when the deployment platform injects them
+- a very small set of documented operational overrides
+
+### Business code is not responsible for
+
+- inventing defaults for missing config
+- loading YAML directly
+- calling `os.getenv()` for normal application behavior
+
+## 5.7 How to handle service config
+
+Unify all service-facing config under one structure:
+
+```yaml
+services:
+  translation:
+    endpoint: "http://translator:6006"
+    timeout_sec: 10
+    default_model: "llm"
+    default_scene: "general"
+    capabilities: ...
+  embedding:
+    endpoint:
+      text: "http://embedding:6005"
+      image: "http://embedding-image:6008"
+    backend: "tei"
+    backends: ...
+  rerank:
+    endpoint: "http://reranker:6007/rerank"
+    backend: "qwen3_vllm"
+    backends: ...
+```
+
+Rules:
+
+- `endpoint` is how callers reach the service
+- `backend` is how the service itself is implemented
+- only the service process cares about `backend`
+- only callers care about `endpoint`
+- both still belong to the same config tree, because they are part of one system
+
+## 5.8 How to handle tenant config
+
+Tenant config should become explicit policy, not translation-era leftovers.
+
+Recommended tenant fields:
+
+- `primary_language`
+- `index_languages`
+- `search_languages`
+- `translation_policy`
+- `facet_policy`
+- optional tenant-specific ranking overrides
+
+Avoid keeping `translate_to_en` and `translate_to_zh` as active concepts in the long-term model.
+
+If compatibility is needed, support them only in the loader as deprecated aliases and emit warnings.
+
+## 5.9 How to handle rewrite rules and similar assets
+
+Treat them as declared config assets.
+
+Recommended rules:
+
+- file path declared in config
+- one canonical location under `config/dictionaries/`
+- loader validates presence and format
+- admin runtime updates either:
+  - are removed, or
+  - write back through a controlled persistence path
+
+Do not keep a hybrid model where startup loads one file and admin mutates only in memory.
+
+## 5.10 Observability improvements
+
+Add the following:
+
+- `config dump` CLI that prints sanitized effective config
+- startup log with config hash, environment, and config file list
+- `/admin/config/effective` endpoint returning sanitized effective config
+- `/admin/config/meta` endpoint returning:
+  - environment
+  - config hash
+  - loaded source files
+  - deprecated keys in use
+
+This is important for operations and for multi-service debugging.
+
+## 6. Practical Refactor Plan
+
+The refactor should be incremental.
+
+### Phase 1: establish the new config core without changing behavior
+
+- create `config/schema.py`
+- create `config/loader.py`
+- move all current defaults into schema models
+- make loader read current `config/config.yaml`
+- make loader read `.env` only for approved keys
+- expose one `get_app_config()`
+
+Result:
+
+- same behavior, but one typed root config becomes available
+
+### Phase 2: remove duplicate readers
+
+- make `services_config.py` a thin adapter over `get_app_config()`
+- make `tenant_config_loader.py` read from `get_app_config()`
+- stop reparsing YAML in `services_config.py`
+- stop service modules from depending on legacy local config modules for behavior
+
+Result:
+
+- one parsing path
+- fewer divergence risks
+
+### Phase 3: move hidden defaults out of business logic
+
+- remove hardcoded fallback language lists from query/indexer modules
+- require tenant defaults to come from config schema only
+- remove duplicate behavior defaults from service code
+
+Result:
+
+- behavior becomes visible and reviewable
+
+### Phase 4: clean service startup configuration
+
+- make startup scripts ask the unified loader for resolved values
+- keep only bind host/port and secret injection in shell env
+- retire or reduce `embeddings/config.py` and `reranker/config.py`
+
+Result:
+
+- startup behavior matches runtime config model
+
+### Phase 5: split config files by responsibility
+
+- keep a single root loader
+- split current giant `config.yaml` into:
+  - `base.yaml`
+  - `environments/<env>.yaml`
+  - `tenants/*.yaml`
+  - `dictionaries/query_rewrite.dict`
+
+Result:
+
+- config remains unified logically, but is easier to read and maintain physically
+
+### Phase 6: deprecate legacy compatibility
+
+- deprecate `translate_to_en` and `translate_to_zh`
+- deprecate env-based backend/provider selection except for explicitly approved keys
+- remove old code paths after one or two release cycles
+
+Result:
+
+- the system becomes simpler instead of carrying two generations forever
+
+## 7. Concrete Rules To Adopt
+
+These rules should be documented and enforced in code review.
+
+### Rule 1
+
+Only `config/loader.py` may load config files or `.env`.
+
+### Rule 2
+
+Only `config/loader.py` may read `os.getenv()` for application config.
+
+### Rule 3
+
+Business modules receive typed config objects and do not read files or env directly.
+
+### Rule 4
+
+Each config key has one owner.
+
+Examples:
+
+- `search.query.knn_boost` belongs to search behavior config
+- `services.embedding.backend` belongs to service implementation config
+- `infrastructure.redis.password` belongs to env/secrets
+
+### Rule 5
+
+Every fallback must be either:
+
+- declared in schema defaults, or
+- rejected at startup
+
+No hidden fallback in runtime logic.
+
+### Rule 6
+
+Every configuration asset must be visible in one of these places only:
+
+- config file
+- env var
+- generated runtime metadata
+
+Not inside parser code as an implicit constant.
+
+## 8. Recommended Naming Conventions
+
+Suggested conventions:
+
+- config keys use noun-based hierarchical names
+- avoid mixing transport and implementation concepts in one field
+- use `endpoint` for caller-facing addresses
+- use `backend` for service-internal implementation choice
+- use `enabled` only for true feature toggles
+- use `default_*` only when a real selection happens at runtime
+
+Examples:
+
+- good: `services.rerank.endpoint`
+- good: `services.rerank.backend`
+- good: `tenants.default.index_languages`
+- avoid: `service_url`, `base_url`, `provider`, `backend`, and script env all meaning slightly different things without a common model
+
+## 9. Highest-Priority Cleanup Items
+
+If the team wants the shortest path to improvement, start here:
+
+1. build one root `AppConfig`
+2. make `services_config.py` stop reparsing YAML
+3. declare rewrite dictionary path explicitly and fix the current mismatch
+4. remove hardcoded `["en", "zh"]` fallbacks from query/indexer logic
+5. replace `/admin/config` with an effective-config endpoint
+6. retire `embeddings/config.py` and `reranker/config.py` as behavior sources
+7. deprecate legacy tenant translation flags
+
+## 10. Expected Outcome
+
+After the redesign:
+
+- developers can answer “where does this setting come from?” in one step
+- operators can see effective config without reading source code
+- backend, indexer, translator, embedding, and reranker all share one model
+- tenant behavior is explicit instead of partially implicit
+- migration becomes safer because defaults and precedence are centralized
+- adding a new provider/backend becomes configuration extension, not configuration archaeology
+
+## 11. Summary
+
+The current system has the right intent but not yet the right implementation shape.
+
+Today the main problems are:
+
+- duplicate config loaders
+- inconsistent precedence
+- duplicated defaults
+- config hidden in runtime logic
+- weak effective-config visibility
+- leftover legacy concepts
+
+The recommended direction is:
+
+- one root typed config
+- one loader pipeline
+- explicit layered sources
+- narrow env responsibility
+- no hidden business fallbacks
+- observable effective config
+
+That design is practical to implement incrementally in this repository and aligns well with the project's multi-tenant, multi-service, provider/backend-based architecture.
@@ -0,0 +1,110 @@
+# 搜索API对接指南-00-总览与快速开始
+
+本文档旨在为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。
+拆分目录：
+- `-01-搜索接口（POST /search/ 与响应）`
+- `-02-搜索建议与即时搜索`
+- `-03-获取文档（GET /search/{doc_id}）`
+- `-05-索引接口（Indexer）`
+- `-06-管理接口（Admin）`
+- `-07-微服务接口（Embedding/Reranker/Translation）`
+- `-08-数据模型与字段速查`
+- `-10-接口级压测脚本`
+
+## 快速开始
+
+### 1.1 基础信息
+
+- **Base URL**: `http://43.166.252.75:6002`
+- **协议**: HTTP/HTTPS
+- **数据格式**: JSON
+- **字符编码**: UTF-8
+- **请求方法**: POST（搜索接口）
+
+**重要提示**: `tenant_id` 通过 HTTP Header `X-Tenant-ID` 传递，不在请求体中。
+
+**环境与凭证**：MySQL、Redis、Elasticsearch 等外部服务的 AI 生产地址与凭证见 [QUICKSTART.md §1.6](./QUICKSTART.md#16-外部服务与-env含生产凭证)。
+
+### 1.2 最简单的搜索请求
+
+```bash
+curl -X POST "http://43.166.252.75:6002/search/" \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 162" \
+  -d '{"query": "芭比娃娃"}'
+```
+
+### 1.3 带过滤与分页的搜索
+
+```bash
+curl -X POST "http://43.166.252.75:6002/search/" \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 162" \
+  -d '{
+    "query": "芭比娃娃",
+    "size": 5,
+    "from": 10,
+    "range_filters": {
+      "min_price": {
+        "gte": 50,
+        "lte": 200
+      },
+      "create_time": {
+        "gte": "2020-01-01T00:00:00Z" 
+      }
+    },
+    "sort_by": "price",
+    "sort_order": "asc"
+  }'
+```
+
+### 1.4 开启分面的搜索
+
+```bash
+curl -X POST "http://43.166.252.75:6002/search/" \
+  -H "Content-Type: application/json" \
+  -H "X-Tenant-ID: 162" \
+  -d '{
+    "query": "芭比娃娃",
+    "facets": [
+      {"field": "category1_name", "size": 10, "type": "terms"},
+      {"field": "specifications.color", "size": 10, "type": "terms"},
+      {"field": "specifications.size", "size": 10, "type": "terms"}
+    ],
+    "min_score": 0.2
+  }'
+```
+
+---
+
+## 接口概览
+
+| 接口 | HTTP Method | Endpoint | 说明 |
+|------|------|------|------|
+| 搜索 | POST | `/search/` | 执行搜索查询 |
+| 搜索建议 | GET | `/search/suggestions` | 搜索建议（自动补全/热词，多语言） |
+| 即时搜索 | GET | `/search/instant` | 即时搜索预留接口（当前返回 `501 Not Implemented`） |
+| 获取文档 | GET | `/search/{doc_id}` | 获取单个文档 |
+| 全量索引 | POST | `/indexer/reindex` | 全量索引接口（导入数据，不删除索引，仅推荐自测使用） |
+| 增量索引 | POST | `/indexer/index` | 增量索引接口（指定SPU ID列表进行索引，支持自动检测删除和显式删除，仅推荐自测使用） |
+| 查询文档 | POST | `/indexer/documents` | 查询SPU文档数据（不写入ES） |
+| 构建ES文档（正式对接） | POST | `/indexer/build-docs` | 基于上游提供的 MySQL 行数据构建 ES doc，不写入 ES，供 Java 等调用后自行写入 |
+| 构建ES文档（测试用） | POST | `/indexer/build-docs-from-db` | 仅在测试/调试时使用，根据 `tenant_id + spu_ids` 内部查库并构建 ES doc |
+| 内容理解字段生成 | POST | `/indexer/enrich-content` | 根据商品标题批量生成 qanchors、semantic_attributes、tags，供微服务组合方式使用 |
+| 索引健康检查 | GET | `/indexer/health` | 检查索引服务状态 |
+| 健康检查 | GET | `/admin/health` | 服务健康检查 |
+| 获取配置 | GET | `/admin/config` | 获取租户配置 |
+| 索引统计 | GET | `/admin/stats` | 获取租户索引统计信息（需 tenant_id） |
+
+**微服务（独立端口或 Indexer 内，外部可直连）**：
+
+| 服务 | 端口 | 接口 | 说明 |
+|------|------|------|------|
+| 向量服务（文本） | 6005 | `POST /embed/text` | 文本向量化 |
+| 向量服务（图片） | 6008 | `POST /embed/image` | 图片向量化 |
+| 翻译服务 | 6006 | `POST /translate` | 文本翻译（支持 qwen-mt / llm / deepl / 本地模型） |
+| 重排服务 | 6007 | `POST /rerank` | 检索结果重排 |
+| 内容理解（Indexer 内） | 6004 | `POST /indexer/enrich-content` | 根据商品标题生成 qanchors、tags 等，供 indexer 微服务组合方式使用 |
+
+---
+
@@ -0,0 +1,903 @@
+# 搜索API对接指南-01-搜索接口（POST /search/ 与响应）
+
+本篇以 `POST /search/` 为主线，包含：
+- 请求参数：`3.2`、过滤器：`3.3`、分面：`3.4`、SKU筛选维度：`3.5`
+- 响应格式：第 `4` 章（4.1~4.5）
+- 常见场景示例：第 `8` 章（示例整体并入本篇，避免散落）
+
+## 搜索接口
+
+### 3.1 接口信息
+
+- **端点**: `POST /search/`
+- **描述**: 执行文本搜索查询，支持多语言、过滤器和分面搜索
+- **租户标识**：`tenant_id` 通过 HTTP 请求头 **`X-Tenant-ID`** 传递（推荐）；也可通过 URL query 参数 **`tenant_id`** 传递。**不要放在请求体中。**
+
+**请求示例（推荐）**:
+
+```python
+url = f"{base_url.rstrip('/')}/search/"
+headers = {
+    "Content-Type": "application/json",
+    "X-Tenant-ID": "162",  # 租户ID，必填
+}
+response = requests.post(url, headers=headers, json={"query": "芭比娃娃"})
+```
+
+### 3.2 请求参数
+
+#### 完整请求体结构
+
+```json
+{
+  "query": "string (required)",
+  "size": 10,
+  "from": 0,
+  "language": "zh",
+  "filters": {},
+  "range_filters": {},
+  "facets": [],
+  "sort_by": "string",
+  "sort_order": "desc",
+  "min_score": 0.0,
+  "sku_filter_dimension": ["string"],
+  "debug": false,
+  "enable_rerank": null,
+  "rerank_query_template": "{query}",
+  "rerank_doc_template": "{title}",
+  "user_id": "string",
+  "session_id": "string"
+}
+```
+
+#### 参数详细说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `query` | string | Y | - | 搜索查询字符串（统一文本检索策略） |
+| `size` | integer | N | 10 | 返回结果数量（1-100） |
+| `from` | integer | N | 0 | 分页偏移量（用于分页） |
+| `language` | string | N | "zh" | 返回语言：`zh`（中文）或 `en`（英文）。后端会根据此参数选择对应的中英文字段返回 |
+| `filters` | object | N | null | 精确匹配过滤器（见[过滤器详解](#33-过滤器详解)） |
+| `range_filters` | object | N | null | 数值范围过滤器（见[过滤器详解](#33-过滤器详解)） |
+| `facets` | array | N | null | 分面配置（见[分面配置](#34-分面配置)） |
+| `sort_by` | string | N | null | 排序字段名。支持：`price`（价格）、`sales`（销量）、`create_time`（创建时间）、`update_time`（更新时间）。默认按相关性排序 |
+| `sort_order` | string | N | "desc" | 排序方向：`asc`（升序）或 `desc`（降序）。注意：`price`+`asc`=价格从低到高，`price`+`desc`=价格从高到低（后端自动映射为min_price或max_price） |
+| `min_score` | float | N | null | 最小相关性分数阈值 |
+| `sku_filter_dimension` | array[string] | N | null | 子SKU筛选维度列表（见[SKU筛选维度](#35-sku筛选维度)） |
+| `debug` | boolean | N | false | 是否返回调试信息 |
+| `enable_rerank` | boolean/null | N | null | 是否开启重排（调用外部重排服务对 ES 结果进行二次排序）。不传/传 null 使用服务端 `rerank.enabled`（默认开启）。开启后会先对 ES TopN（`rerank_window`）重排，再按分页截取；若 `from+size>1000`，则不重排，直接按分页从 ES 返回 |
+| `rerank_query_template` | string | N | null | 重排 query 模板（可选）。支持 `{query}` 占位符；不传则使用服务端配置 |
+| `rerank_doc_template` | string | N | null | 重排 doc 模板（可选）。支持 `{title} {brief} {vendor} {description} {category_path}`；不传则使用服务端配置 |
+| `user_id` | string | N | null | 用户ID（用于个性化，预留） |
+| `session_id` | string | N | null | 会话ID（用于分析，预留） |
+
+### 3.3 过滤器详解
+
+#### 3.3.1 精确匹配过滤器 (filters)
+
+用于精确匹配或多值匹配。对于普通字段，数组表示 OR 逻辑（匹配任意一个值）；对于 specifications 字段，按维度分组处理。**任意字段名加 `_all` 后缀**表示多值 AND 逻辑（必须同时匹配所有值）。
+
+**格式**:
+
+```json
+{
+  "filters": {
+    "category_name": "手机",                      // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "category1_name": "服装",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "category2_name": "男装",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "category3_name": "衬衫",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "vendor.zh.keyword": ["奇乐", "品牌A"],      // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "tags": "手机",                              // 可以为单值 或者 数组 匹配数组中任意一个（OR）
+    "tags_all": ["手机", "促销", "新品"],        // *_all：多值为 AND，必须同时包含所有标签
+    "category1_name_all": ["服装", "男装"],     // 同上，适用于任意可过滤字段
+    // specifications 嵌套过滤（特殊格式）
+    "specifications": {
+      "name": "color",
+      "value": "white"
+    }
+  }
+}
+```
+
+**支持的值类型**:
+- 字符串：精确匹配
+- 整数：精确匹配
+- 布尔值：精确匹配
+- 数组：匹配任意值（OR 逻辑）；若字段名以 `_all` 结尾，则数组表示 AND 逻辑（必须同时匹配所有值）
+- 对象：specifications 嵌套过滤（见下文）
+
+**`*_all` 语义（多值 AND）**:
+- 任意过滤字段均可使用 `_all` 后缀，对应 ES 字段名为去掉 `_all` 后的名称。
+- 例如：`tags_all: ["A", "B"]` 表示文档的 `tags` 必须**同时包含** A 和 B；`vendor.zh.keyword_all: ["奇乐", "品牌A"]` 表示同时匹配两个品牌（通常用于 keyword 多值场景）。
+- `specifications_all`：传列表 `[{"name":"color","value":"white"},{"name":"size","value":"256GB"}]` 时，表示所有列出的规格条件都要满足（与 `specifications` 多维度时的 AND 一致；若同维度多值则要求文档同时满足多个值，一般用于嵌套多值场景）。
+
+**Specifications 嵌套过滤**:
+
+`specifications` 是嵌套字段，支持按规格名称和值进行过滤。
+
+**单个规格过滤**:
+
+```json
+{
+  "filters": {
+    "specifications": {
+      "name": "color",
+      "value": "white"
+    }
+  }
+}
+```
+
+查询规格名称为"color"且值为"white"的商品。
+
+**多个规格过滤（按维度分组）**:
+
+```json
+{
+  "filters": {
+    "specifications": [
+      {"name": "color", "value": "white"},
+      {"name": "size", "value": "256GB"}
+    ]
+  }
+}
+```
+
+查询同时满足所有规格的商品（color=white **且** size=256GB）。
+
+**相同维度的多个值（OR 逻辑）**:
+
+```json
+{
+  "filters": {
+    "specifications": [
+      {"name": "size", "value": "3"},
+      {"name": "size", "value": "4"},
+      {"name": "size", "value": "5"},
+      {"name": "color", "value": "green"}
+    ]
+  }
+}
+```
+
+查询满足 (size=3 **或** size=4 **或** size=5) **且** color=green 的商品。
+
+**过滤逻辑说明**:
+- **不同维度**（不同的 `name`）之间是 **AND** 关系（求交集）
+- **相同维度**（相同的 `name`）的多个值之间是 **OR** 关系（求并集）
+
+**常用过滤字段**（详见[常用字段列表](./搜索API对接指南-08-数据模型与字段速查.md#93-常用字段列表)）:
+- `category_name`: 类目名称
+- `category1_name`, `category2_name`, `category3_name`: 多级类目
+- `category_id`: 类目ID
+- `vendor.zh.keyword`, `vendor.en.keyword`: 供应商/品牌（使用keyword子字段）
+- `tags`: 标签（keyword类型，支持数组）
+- `option1_name`, `option2_name`, `option3_name`: 选项名称
+- `specifications`: 规格过滤（嵌套字段，格式见上文）
+- 以上任意字段均可加 `_all` 后缀表示多值 AND，如 `tags_all`、`category1_name_all`。
+
+#### 3.3.2 范围过滤器 (range_filters)
+
+用于数值字段的范围过滤。
+
+**格式**:
+
+```json
+{
+  "range_filters": {
+    "min_price": {
+      "gte": 50,    // 大于等于
+      "lte": 200    // 小于等于
+    },
+    "max_price": {
+      "gt": 100     // 大于
+    },
+    "create_time": {
+      "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
+    }
+  }
+}
+```
+
+**支持的操作符**:
+- `gte`: 大于等于 (>=)
+- `gt`: 大于 (>)
+- `lte`: 小于等于 (<=)
+- `lt`: 小于 (<)
+
+**注意**: 至少需要指定一个操作符。
+
+**常用范围字段**（详见[常用字段列表](./搜索API对接指南-08-数据模型与字段速查.md#93-常用字段列表)）:
+- `min_price`: 最低价格
+- `max_price`: 最高价格
+- `compare_at_price`: 原价
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+
+### 3.4 分面配置
+
+用于生成分面统计（分组聚合），常用于构建筛选器UI。
+
+#### 3.4.1 配置格式
+
+```json
+{
+  "facets": [
+    {
+      "field": "category1_name",
+      "size": 15,
+      "type": "terms",
+      "disjunctive": false
+    },
+    {
+      "field": "brand_name",
+      "size": 10,
+      "type": "terms",
+      "disjunctive": true
+    },
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms",
+      "disjunctive": true
+    },
+    {
+      "field": "min_price",
+      "type": "range",
+      "ranges": [
+        {"key": "0-50", "to": 50},
+        {"key": "50-100", "from": 50, "to": 100},
+        {"key": "100-200", "from": 100, "to": 200},
+        {"key": "200+", "from": 200}
+      ]
+    }
+  ]
+}
+```
+
+#### 3.4.2 Facet 字段说明
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `field` | string | 是 | - | 分面字段名 |
+| `size` | int | 否 | 10 | 返回的分面值数量（1-100） |
+| `type` | string | 否 | "terms" | 分面类型：`terms`（词条聚合）或 `range`（范围聚合） |
+| `disjunctive` | bool | 否 | false | 是否支持多选（disjunctive faceting）。启用后，选中该分面的过滤器时，仍会显示其他可选项 |
+| `ranges` | array | 否 | null | 范围配置（仅 `type="range"` 时需要） |
+
+#### 3.4.3 disjunctive字段说明
+
+**重要特性**: `disjunctive` 字段控制分面的行为模式。启用后，选中该分面的过滤器时，仍会显示其他可选项
+
+**标准模式 (disjunctive: false)**:
+- **行为**: 选中某个分面值后，该分面只显示选中的值
+- **适用场景**: 层级类目、互斥选择
+- **示例**: 类目下钻（玩具 > 娃娃 > 芭比）
+
+**Multi-Select 模式 (disjunctive: true)** ⭐:
+- **行为**: 选中某个分面值后，该分面仍显示所有可选项
+- **适用场景**: 颜色、品牌、尺码等可切换属性
+- **示例**: 选择了"红色"后，仍能看到"蓝色"、"绿色"等选项
+
+**推荐配置**:
+
+| 分面类型 | disjunctive | 原因 |
+|---------|-------------|------|
+| 颜色 | `true` | 用户需要切换颜色 |
+| 品牌 | `true` | 用户需要比较品牌 |
+| 尺码 | `true` | 用户需要查看其他尺码 |
+| 类目 | `false` | 层级下钻 |
+| 价格区间 | `false` | 互斥选择 |
+
+#### 3.4.4 规格分面说明
+
+`specifications` 是嵌套字段，支持两种分面模式：
+
+**模式1：所有规格名称的分面**:
+
+```json
+{
+  "facets": [
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
+  ]
+}
+```
+
+返回所有规格名称（name）及其对应的值（value）列表。每个 name 会生成一个独立的分面结果。
+
+**模式2：指定规格名称的分面**:
+
+```json
+{
+  "facets": [
+    {
+      "field": "specifications.color",
+      "size": 20,
+      "type": "terms",
+      "disjunctive": true
+    },
+    {
+      "field": "specifications.size",
+      "size": 15,
+      "type": "terms",
+      "disjunctive": true
+    }
+  ]
+}
+```
+
+只返回指定规格名称的值列表。格式：`specifications.{name}`，其中 `{name}` 是规格名称（如"color"、"size"、"material"）。
+
+**返回格式示例**:
+
+```json
+{
+  "facets": [
+    {
+      "field": "specifications.color",
+      "label": "color",
+      "type": "terms",
+      "values": [
+        {"value": "white", "count": 50, "selected": true},  // ✓ selected 字段由后端标记
+        {"value": "black", "count": 30, "selected": false},
+        {"value": "red", "count": 20, "selected": false}
+      ]
+    },
+    {
+      "field": "specifications.size",
+      "label": "size",
+      "type": "terms",
+      "values": [
+        {"value": "256GB", "count": 40, "selected": false},
+        {"value": "512GB", "count": 20, "selected": false}
+      ]
+    }
+  ]
+}
+```
+
+### 3.5 SKU筛选维度
+
+**功能说明**:
+`sku_filter_dimension` 用于控制搜索列表页中 **每个 SPU 下方可切换的子款式（子 SKU）维度**，为字符串列表。  
+在店铺的 **主题装修配置** 中，商家可以为店铺设置一个或多个子款式筛选维度（例如 `color`、`size`），前端列表页会在每个 SPU 下展示这些维度对应的子 SKU 列表，用户可以通过点击不同维度值（如不同颜色）来切换展示的子款式。  
+当指定 `sku_filter_dimension` 后，后端会根据店铺的这项配置，从所有 SKU 中筛选出这些维度组合对应的子 SKU 数据：系统会按指定维度**组合**对 SKU 进行分组，每个维度组合只返回第一个 SKU（从简实现，选择该组合下的第一款），其余不在这些维度组合中的子 SKU 将不返回。
+
+**支持的维度值**:
+1. **直接选项字段**: `option1`、`option2`、`option3`
+   - 直接使用对应的 `option1_value`、`option2_value`、`option3_value` 字段进行分组
+   
+2. **规格/选项名称**: 通过 `option1_name`、`option2_name`、`option3_name` 匹配
+   - 例如：如果 `option1_name` 为 `"color"`，则可以使用 `sku_filter_dimension: ["color"]` 来按颜色分组
+
+**示例**:
+
+**按颜色筛选（假设 option1_name = "color"）**:
+
+```json
+{
+  "query": "芭比娃娃",
+  "sku_filter_dimension": ["color"]
+}
+```
+
+**按选项1筛选**:
+
+```json
+{
+  "query": "芭比娃娃",
+  "sku_filter_dimension": ["option1"]
+}
+```
+
+**按颜色 + 尺寸组合筛选（假设 option1_name = "color", option2_name = "size"）**:
+
+```json
+{
+  "query": "芭比娃娃",
+  "sku_filter_dimension": ["color", "size"]
+}
+```
+
+## 响应格式说明
+
+### 4.1 标准响应结构
+
+```json
+{
+  "results": [
+    {
+      "spu_id": "12345",
+      "title": "芭比时尚娃娃",
+      "brief": "高品质芭比娃娃",
+      "description": "详细描述...",
+      "vendor": "美泰",
+      "category": "玩具",
+      "category_path": "玩具/娃娃/时尚",
+      "category_name": "时尚",
+      "category_id": "cat_001",
+      "category_level": 3,
+      "category1_name": "玩具",
+      "category2_name": "娃娃",
+      "category3_name": "时尚",
+      "tags": ["娃娃", "玩具", "女孩"],
+      "price": 89.99,
+      "compare_at_price": 129.99,
+      "currency": "USD",
+      "image_url": "https://example.com/image.jpg",
+      "in_stock": true,
+      "sku_prices": [89.99, 99.99, 109.99],
+      "sku_weights": [100, 150, 200],
+      "sku_weight_units": ["g", "g", "g"],
+      "total_inventory": 500,
+      "option1_name": "color",
+      "option2_name": "size",
+      "option3_name": null,
+      "specifications": [
+        {"sku_id": "sku_001", "name": "color", "value": "pink"},
+        {"sku_id": "sku_001", "name": "size", "value": "standard"}
+      ],
+      "skus": [
+        {
+          "sku_id": "67890",
+          "price": 89.99,
+          "compare_at_price": 129.99,
+          "sku": "BARBIE-001",
+          "stock": 100,
+          "weight": 0.1,
+          "weight_unit": "kg",
+          "option1_value": "pink",
+          "option2_value": "standard",
+          "option3_value": null,
+          "image_src": "https://example.com/sku1.jpg"
+        }
+      ],
+      "relevance_score": 8.5
+    }
+  ],
+  "total": 118,
+  "max_score": 8.5,
+  "facets": [
+    {
+      "field": "category1_name",
+      "label": "category1_name",
+      "type": "terms",
+      "values": [
+        {
+          "value": "玩具",
+          "label": "玩具",
+          "count": 85,
+          "selected": false
+        }
+      ]
+    },
+    {
+      "field": "specifications.color",
+      "label": "color",
+      "type": "terms",
+      "values": [
+        {
+          "value": "pink",
+          "label": "pink",
+          "count": 30,
+          "selected": false
+        }
+      ]
+    }
+  ],
+  "query_info": {
+    "original_query": "芭比娃娃",
+    "query_normalized": "芭比娃娃",
+    "rewritten_query": "芭比娃娃",
+    "detected_language": "zh",
+    "translations": {
+      "en": "barbie doll"
+    },
+    "domain": "default"
+  },
+  "suggestions": [],
+  "related_searches": [],
+  "took_ms": 45,
+  "performance_info": null,
+  "debug_info": null
+}
+```
+
+### 4.2 响应字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `results` | array | 搜索结果列表（SpuResult对象数组） |
+| `results[].spu_id` | string | SPU ID |
+| `results[].title` | string | 商品标题 |
+| `results[].price` | float | 价格（min_price） |
+| `results[].skus` | array | SKU列表（如果指定了`sku_filter_dimension`，则按维度过滤后的SKU） |
+| `results[].relevance_score` | float | 相关性分数 |
+| `total` | integer | 匹配的总文档数 |
+| `max_score` | float | 最高相关性分数 |
+| `facets` | array | 分面统计结果 |
+| `query_info` | object | query处理信息 |
+| `took_ms` | integer | 搜索耗时（毫秒） |
+| `debug_info` | object/null | 调试信息，仅当请求传 `debug=true` 时返回 |
+
+#### 4.2.1 query_info 说明
+
+`query_info` 包含本次搜索的查询解析与处理结果：
+
+| 子字段 | 类型 | 说明 |
+|--------|------|------|
+| `original_query` | string | 用户原始查询 |
+| `query_normalized` | string | 归一化后的查询（去空白、大小写等预处理，用于后续解析与改写） |
+| `rewritten_query` | string | 重写后的查询（同义词/词典扩展等） |
+| `detected_language` | string | 检测到的查询语言（如 `zh`、`en`） |
+| `translations` | object | 翻译结果，键为语言代码，值为翻译文本 |
+| `domain` | string | 查询域（如 `default`、`title`、`brand` 等） |
+
+#### 4.2.2 debug_info 说明
+
+`debug_info` 主要用于检索效果评估、融合打分分析与 bad case 排查。
+
+`debug_info.query_analysis` 常见字段：
+
+| 子字段 | 类型 | 说明 |
+|--------|------|------|
+| `original_query` | string | 原始查询 |
+| `query_normalized` | string | 归一化后的查询 |
+| `rewritten_query` | string | 重写后的查询 |
+| `detected_language` | string | 检测到的语言 |
+| `translations` | object | 翻译结果 |
+| `query_text_by_lang` | object | 实际参与检索的多语言 query 文本 |
+| `search_langs` | array[string] | 实际参与检索的语言列表 |
+| `supplemental_search_langs` | array[string] | 因 mixed query 补入的附加语言列表 |
+| `has_vector` | boolean | 是否生成了向量 |
+
+`debug_info.per_result[]` 常见字段：
+
+| 子字段 | 类型 | 说明 |
+|--------|------|------|
+| `spu_id` | string | 结果 SPU ID |
+| `es_score` | float | ES 原始 `_score` |
+| `rerank_score` | float | 重排分数 |
+| `text_score` | float | 文本相关性大分（由 `base_query` / `base_query_trans_*` / `fallback_original_query_*` 聚合而来） |
+| `text_source_score` | float | `base_query` 分数 |
+| `text_translation_score` | float | `base_query_trans_*` 里的最大分数 |
+| `text_fallback_score` | float | `fallback_original_query_*` 里的最大分数 |
+| `text_primary_score` | float | 文本大分中的主证据部分 |
+| `text_support_score` | float | 文本大分中的辅助证据部分 |
+| `knn_score` | float | `knn_query` 分数 |
+| `fused_score` | float | 最终融合分数 |
+| `matched_queries` | object/array | ES named queries 命中详情 |
+
+### 4.3 SpuResult字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `spu_id` | string | SPU ID |
+| `title` | string | 商品标题（根据language参数自动选择 `title.zh` 或 `title.en`） |
+| `brief` | string | 商品短描述（根据language参数自动选择） |
+| `description` | string | 商品详细描述（根据language参数自动选择） |
+| `vendor` | string | 供应商/品牌（根据language参数自动选择） |
+| `category` | string | 类目（兼容字段，等同于category_name） |
+| `category_path` | string | 类目路径（多级，用于面包屑，根据language参数自动选择） |
+| `category_name` | string | 类目名称（展示用，根据language参数自动选择） |
+| `category_id` | string | 类目ID |
+| `category_level` | integer | 类目层级（1/2/3） |
+| `category1_name` | string | 一级类目名称 |
+| `category2_name` | string | 二级类目名称 |
+| `category3_name` | string | 三级类目名称 |
+| `tags` | array[string] | 标签列表 |
+| `price` | float | 价格（min_price） |
+| `compare_at_price` | float | 原价 |
+| `currency` | string | 货币单位（默认USD） |
+| `image_url` | string | 主图URL |
+| `in_stock` | boolean | 是否有库存（任意SKU有库存即为true） |
+| `sku_prices` | array[float] | 所有SKU价格列表 |
+| `sku_weights` | array[integer] | 所有SKU重量列表 |
+| `sku_weight_units` | array[string] | 所有SKU重量单位列表 |
+| `total_inventory` | integer | 总库存 |
+| `sales` | integer | 销量（展示销量） |
+| `option1_name` | string | 选项1名称（如"color"） |
+| `option2_name` | string | 选项2名称（如"size"） |
+| `option3_name` | string | 选项3名称 |
+| `specifications` | array[object] | 规格列表（与ES specifications字段对应） |
+| `skus` | array | SKU 列表 |
+| `relevance_score` | float | 相关性分数（默认为 ES 原始分数；当开启 AI 搜索时为融合后的最终分数） |
+
+### 4.4 SkuResult字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sku_id` | string | SKU ID |
+| `price` | float | 价格 |
+| `compare_at_price` | float | 原价 |
+| `sku` | string | SKU编码（sku_code） |
+| `stock` | integer | 库存数量 |
+| `weight` | float | 重量 |
+| `weight_unit` | string | 重量单位 |
+| `option1_value` | string | 选项1取值（如color值） |
+| `option2_value` | string | 选项2取值（如size值） |
+| `option3_value` | string | 选项3取值 |
+| `image_src` | string | SKU图片地址 |
+
+### 4.5 多语言字段说明
+
+- `title`, `brief`, `description`, `vendor`, `category_path`, `category_name` 会根据请求的 `language` 参数自动选择对应的中英文字段
+- `language="zh"`: 优先返回 `*_zh` 字段，如果为空则回退到 `*_en` 字段
+- `language="en"`: 优先返回 `*_en` 字段，如果为空则回退到 `*_zh` 字段
+
+---
+
+## 8. 常见场景示例
+
+以下示例仅展示**请求体**（body）；实际调用时请加上请求头 `X-Tenant-ID: <租户ID>`（或 URL 参数 `tenant_id`），参见 [3.1 接口信息](#31-接口信息)。
+
+### 8.1 基础搜索与排序
+
+**按价格从低到高排序**:
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "price",
+  "sort_order": "asc"
+}
+```
+
+**按价格从高到低排序**:
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "price",
+  "sort_order": "desc"
+}
+```
+
+**按销量从高到低排序**:
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0,
+  "sort_by": "sales",
+  "sort_order": "desc"
+}
+```
+
+**按默认（相关性）排序**:
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "from": 0
+}
+```
+
+### 8.2 过滤搜索
+
+**需求**: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "category_name": "益智玩具"
+  },
+  "range_filters": {
+    "min_price": {
+      "gte": 50,
+      "lte": 200
+    }
+  }
+}
+```
+
+**需求**: 搜索"手机"，筛选多个品牌，价格范围
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "vendor.zh.keyword": ["品牌A", "品牌B"]
+  },
+  "range_filters": {
+    "min_price": {
+      "gte": 50,
+      "lte": 200
+    }
+  }
+}
+```
+
+### 8.3 分面搜索
+
+**需求**: 搜索"玩具"，获取类目和规格的分面统计，用于构建筛选器
+
+```json
+{
+  "query": "玩具",
+  "size": 20,
+  "language": "zh",
+  "facets": [
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications", "size": 10, "type": "terms"}
+  ]
+}
+```
+
+**需求**: 搜索"手机"，获取价格区间和规格的分面统计
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "facets": [
+    {
+      "field": "min_price",
+      "type": "range",
+      "ranges": [
+        {"key": "0-50", "to": 50},
+        {"key": "50-100", "from": 50, "to": 100},
+        {"key": "100-200", "from": 100, "to": 200},
+        {"key": "200+", "from": 200}
+      ]
+    },
+    {
+      "field": "specifications",
+      "size": 10,
+      "type": "terms"
+    }
+  ]
+}
+```
+
+### 8.4 规格过滤与分面
+
+**需求**: 搜索"手机"，筛选color为"white"的商品
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "specifications": {
+      "name": "color",
+      "value": "white"
+    }
+  }
+}
+```
+
+**需求**: 搜索"手机"，筛选color为"white"且size为"256GB"的商品
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "specifications": [
+      {"name": "color", "value": "white"},
+      {"name": "size", "value": "256GB"}
+    ]
+  }
+}
+```
+
+**需求**: 搜索"手机"，筛选size为"3"、"4"或"5"，且color为"green"的商品
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "specifications": [
+      {"name": "size", "value": "3"},
+      {"name": "size", "value": "4"},
+      {"name": "size", "value": "5"},
+      {"name": "color", "value": "green"}
+    ]
+  }
+}
+```
+
+**需求**: 搜索"手机"，获取所有规格的分面统计
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "facets": [
+    {"field": "specifications", "size": 10, "type": "terms"}
+  ]
+}
+```
+
+**需求**: 只获取"color"和"size"规格的分面统计
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "facets": [
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
+  ]
+}
+```
+
+**需求**: 搜索"手机"，筛选类目和规格，并获取对应的分面统计
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "language": "zh",
+  "filters": {
+    "category_name": "手机",
+    "specifications": {
+      "name": "color",
+      "value": "white"
+    }
+  },
+  "facets": [
+    {"field": "category1_name", "size": 15, "type": "terms"},
+    {"field": "category2_name", "size": 10, "type": "terms"},
+    {"field": "specifications.color", "size": 20, "type": "terms"},
+    {"field": "specifications.size", "size": 15, "type": "terms"}
+  ]
+}
+```
+
+### 8.5 SKU筛选
+
+**需求**: 搜索"芭比娃娃"，每个SPU下按颜色筛选，每种颜色只显示一个SKU
+
+```json
+{
+  "query": "芭比娃娃",
+  "size": 20,
+  "sku_filter_dimension": ["color"]
+}
+```
+
+**说明**:
+- 如果 `option1_name` 为 `"color"`，则使用 `sku_filter_dimension: ["color"]` 可以按颜色分组
+- 每个SPU下，每种颜色只会返回第一个SKU
+- 如果维度不匹配，返回所有SKU（不进行过滤）
+
+### 8.6 分页查询
+
+**需求**: 获取第2页结果（每页20条）
+
+```json
+{
+  "query": "手机",
+  "size": 20,
+  "from": 20
+}
+```
+
+---
+
@@ -0,0 +1,81 @@
+# 搜索API对接指南-02-搜索建议与即时搜索
+
+本篇面向前端联想词/搜索框团队，独立阅读 `GET /search/suggestions` 与 `GET /search/instant`。
+
+## 搜索接口
+
+### 3.7 搜索建议接口
+
+- **端点**: `GET /search/suggestions`
+- **描述**: 返回搜索建议（自动补全/热词），支持多语言。
+
+#### 查询参数
+
+| 参数 | 类型 | 必填 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `q` | string | Y | - | 查询字符串（至少 1 个字符） |
+| `size` | integer | N | 10 | 返回建议数量（1-50） |
+| `language` | string | N | `en` | 请求语言，如 `zh` / `en` / `ar` / `ru`，用于路由到对应语种 suggestion 索引 |
+| `debug` | bool | N | `false` | 是否开启调试（目前主要用于排查 suggestion 排序与语言解析） |
+
+> **租户标识**：同 [-01-搜索接口](./搜索API对接指南-01-搜索接口.md#31-接口信息)，通过请求头 `X-Tenant-ID` 或 query 参数 `tenant_id` 传递。
+
+#### 响应示例
+
+```json
+{
+  "query": "iph",
+  "language": "en",
+  "resolved_language": "en",
+  "suggestions": [
+    {
+      "text": "iphone 15",
+      "lang": "en",
+      "score": 12.37,
+      "rank_score": 5.1,
+      "sources": ["query_log", "qanchor"],
+      "lang_source": "log_field",
+      "lang_confidence": 1.0,
+      "lang_conflict": false
+    }
+  ],
+  "took_ms": 12
+}
+```
+
+#### 请求示例
+
+```bash
+curl "http://localhost:6002/search/suggestions?q=芭&size=5&language=zh" \
+  -H "X-Tenant-ID: 162"
+```
+
+### 3.8 即时搜索接口
+
+> ⚠️ 当前版本未开放该能力。接口会明确返回 `501 Not Implemented`，避免误用未完成实现。
+
+- **端点**: `GET /search/instant`
+- **描述**: 即时搜索预留端点，后续会在独立实现完成后开放。
+
+#### 查询参数
+
+| 参数 | 类型 | 必填 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `q` | string | Y | - | 搜索查询（至少 2 个字符） |
+| `size` | integer | N | 5 | 返回结果数量（1-20） |
+
+#### 请求示例
+
+```bash
+curl "http://localhost:6002/search/instant?q=玩具&size=5"
+```
+
+#### 当前响应
+
+```json
+{
+  "error": "/search/instant is not implemented yet. Use POST /search/ for production traffic.",
+  "status_code": 501
+}
+```
+
@@ -0,0 +1,40 @@
+# 搜索API对接指南-03-获取文档（GET /search/{doc_id}）
+
+用于点击结果后的详情页回源，或排查某个文档在检索侧的字段情况。
+
+## 搜索接口
+
+### 3.9 获取单个文档
+
+- **端点**: `GET /search/{doc_id}`
+- **描述**: 根据文档 ID 获取单个商品详情，用于点击结果后的详情页或排查问题。
+- **租户标识**：同 [-01-搜索接口](./搜索API对接指南-01-搜索接口.md#31-接口信息)，通过请求头 `X-Tenant-ID` 或 query 参数 `tenant_id` 传递。
+
+#### 路径参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `doc_id` | string | 商品或文档 ID |
+
+#### 响应示例
+
+```json
+{
+  "id": "12345",
+  "source": {
+    "title": {
+      "zh": "芭比时尚娃娃"
+    },
+    "min_price": 89.99,
+    "category1_name": "玩具"
+  }
+}
+```
+
+#### 请求示例
+
+```bash
+curl "http://localhost:6002/search/12345" -H "X-Tenant-ID: 162"
+# 或使用 query 参数：curl "http://localhost:6002/search/12345?tenant_id=162"
+```
+
@@ -0,0 +1,767 @@
+# 搜索API对接指南-05-索引接口（Indexer）
+
+本篇覆盖数据同步/索引构建相关的所有接口（原文第 5 章），用于 `external indexer` 和 `Indexer 服务` 的对接。
+
+## 索引接口
+
+本节内容与 `api/routes/indexer.py` 中的索引相关服务一致，包含以下接口：
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 全量重建索引 | POST | `/indexer/reindex` | 将指定租户所有 SPU 导入 ES（不删现有索引） |
+| 增量索引 | POST | `/indexer/index` | 按 SPU ID 列表索引/删除，支持自动检测删除与显式删除 |
+| 查询文档 | POST | `/indexer/documents` | 按 SPU ID 列表查询 ES 文档，不写入 ES |
+| 构建 ES 文档（正式） | POST | `/indexer/build-docs` | 由上游提供 MySQL 行数据，返回 ES-ready 文档，不写 ES |
+| 构建 ES 文档（测试） | POST | `/indexer/build-docs-from-db` | 由本服务查库并构建文档，仅测试/调试用 |
+| 内容理解字段生成 | POST | `/indexer/enrich-content` | 根据商品标题批量生成 qanchors、semantic_attributes、tags（供微服务组合方式使用） |
+| 索引健康检查 | GET | `/indexer/health` | 检查索引服务与数据库连接状态 |
+
+#### 5.0 支撑外部 indexer 的三种方式
+
+本服务对**外部 indexer 程序**（如 Java 索引系统）提供三种对接方式，可按需选择：
+
+| 方式 | 说明 | 适用场景 |
+|------|------|----------|
+| **1）doc 填充接口** | 调用 `POST /indexer/build-docs` 或 `POST /indexer/build-docs-from-db`，由本服务基于 MySQL 行数据构建完整 ES 文档（含多语言、向量、规格等），**不写入 ES**，由调用方自行写入。 | 希望一站式拿到 ES-ready doc，由己方控制写 ES 的时机与索引名。 |
+| **2）微服务组合** | 单独调用**翻译**、**向量化**、**内容理解字段生成**等接口，由 indexer 程序自己组装 doc 并写入 ES。翻译与向量化为独立微服务（见第 7 节）；内容理解为 Indexer 服务内接口 `POST /indexer/enrich-content`。 | 需要灵活编排、或希望将 LLM/向量等耗时步骤与主链路解耦（如异步补齐 qanchors/tags）。 |
+| **3）本服务直接写 ES** | 调用全量索引 `POST /indexer/reindex`、增量索引 `POST /indexer/index`（指定 SPU ID 列表），由本服务从 MySQL 拉数并直接写入 ES。 | 自建运维、联调或不需要由 Java 写 ES 的场景。 |
+
+- **方式 1** 与 **方式 2** 下，ES 的写入方均为外部 indexer（或 Java），职责清晰。
+- **方式 3** 下，本服务同时负责读库、构建 doc 与写 ES。
+
+### 5.1 为租户创建索引
+
+为租户创建索引需要两个步骤：
+
+1. **创建索引结构**（可选，仅在需要更新 mapping 或在新环境首次创建时执行）
+   - 使用脚本创建 ES 索引结构（基于 `mappings/search_products.json`）
+   - 如果索引已存在，会提示用户确认（会删除现有数据）
+
+2. **导入数据**（必需）
+   - 使用全量索引接口 `/indexer/reindex` 导入数据
+
+**创建索引结构（支持多环境 namespace）**：
+
+```bash
+# 以 UAT 环境为例：
+# 1. 准备 UAT 环境的 .env（包含 UAT 的 ES_HOST/DB_HOST 等）
+# 2. 设置环境前缀（也可以直接在 .env 中配置）：
+export RUNTIME_ENV=uat
+export ES_INDEX_NAMESPACE=uat_
+
+# 3. 为 tenant_id=170 创建索引结构
+./scripts/create_tenant_index.sh 170
+```
+
+脚本会自动从项目根目录的 `.env` 文件加载 ES 配置，并根据 `ES_INDEX_NAMESPACE` 创建：
+
+- prod 环境（ES_INDEX_NAMESPACE 为空）：`search_products_tenant_170`
+- UAT 环境（ES_INDEX_NAMESPACE=uat_）：`uat_search_products_tenant_170`
+
+**注意事项**：
+- ⚠️ 如果索引已存在，脚本会提示确认，确认后会删除现有数据
+- 创建索引后，**必须**调用 `/indexer/reindex` 导入数据
+- 如果只是更新数据而不需要修改索引结构，直接使用 `/indexer/reindex` 即可
+
+---
+
+### 5.2 全量索引接口
+
+- **端点**: `POST /indexer/reindex`
+- **描述**: 全量索引，将指定租户的所有SPU数据导入到ES索引（不会删除现有索引）。**推荐仅用于自测/运维场景**；生产环境下更推荐由 Java 等上游控制调度与写 ES。
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "162",
+  "batch_size": 500
+}
+```
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `tenant_id` | string | Y | - | 租户ID |
+| `batch_size` | integer | N | 500 | 批量导入大小 |
+
+#### 响应格式
+
+**成功响应（200 OK）**（示例，实际 `index_name` 会带上 tenant 和环境前缀）:
+
+```json
+{
+  "success": true,
+  "total": 1000,
+  "indexed": 1000,
+  "failed": 0,
+  "elapsed_time": 12.34,
+  "index_name": "search_products_tenant_162",
+  "tenant_id": "162"
+}
+```
+
+**错误响应**:
+- `400 Bad Request`: 参数错误
+- `503 Service Unavailable`: 服务未初始化
+
+#### 请求示例
+
+**全量索引（不会删除现有索引）**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/reindex" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "batch_size": 500
+  }'
+```
+
+**查看日志**:
+
+```bash
+# 查看API日志（包含索引操作日志）
+tail -f logs/api.log
+
+# 或者查看所有日志文件
+tail -f logs/*.log
+```
+
+> ⚠️ **重要提示**：如需 **创建索引结构**，请参考 [5.1 为租户创建索引](#51-为租户创建索引) 章节，使用 `./scripts/create_tenant_index.sh <tenant_id>`。创建后需要调用 `/indexer/reindex` 导入数据。
+
+**查看索引日志**:
+
+索引操作的所有关键信息都会记录到 `logs/indexer.log` 文件中（JSON 格式），包括：
+- 请求开始和结束时间
+- 租户ID、SPU ID、操作类型
+- 每个SPU的处理状态
+- ES批量写入结果
+- 成功/失败统计和详细错误信息
+
+```bash
+# 实时查看索引日志（包含全量和增量索引的所有操作）
+tail -f logs/indexer.log
+
+# 使用 grep 查询（简单方式）
+# 查看全量索引日志
+grep "\"index_type\":\"bulk\"" logs/indexer.log | tail -100
+
+# 查看增量索引日志
+grep "\"index_type\":\"incremental\"" logs/indexer.log | tail -100
+
+# 查看特定租户的索引日志
+grep "\"tenant_id\":\"162\"" logs/indexer.log | tail -100
+
+# 使用 jq 查询（推荐，更精确的 JSON 查询）
+# 安装 jq: sudo apt-get install jq 或 brew install jq
+
+# 查看全量索引日志
+cat logs/indexer.log | jq 'select(.index_type == "bulk")' | tail -100
+
+# 查看增量索引日志
+cat logs/indexer.log | jq 'select(.index_type == "incremental")' | tail -100
+
+# 查看特定租户的索引日志
+cat logs/indexer.log | jq 'select(.tenant_id == "162")' | tail -100
+
+# 查看失败的索引操作
+cat logs/indexer.log | jq 'select(.operation == "request_complete" and .failed_count > 0)'
+
+# 查看特定SPU的处理日志
+cat logs/indexer.log | jq 'select(.spu_id == "123")'
+
+# 查看最近的索引请求统计
+cat logs/indexer.log | jq 'select(.operation == "request_complete") | {timestamp, index_type, tenant_id, total_count, success_count, failed_count, elapsed_time}'
+```
+
+### 5.3 增量索引接口
+
+- **端点**: `POST /indexer/index`
+- **描述**: 增量索引接口，根据指定的SPU ID列表进行索引，直接将数据写入ES。用于增量更新指定商品。**推荐仅作为内部/调试入口**；正式对接建议改用 `/indexer/build-docs`，由上游写 ES。
+
+**删除说明**：
+- `spu_ids`中的SPU：如果数据库`deleted=1`，自动从ES删除，响应状态为`deleted`
+- `delete_spu_ids`中的SPU：直接删除，响应状态为`deleted`、`not_found`或`failed`
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "162",
+  "spu_ids": ["123", "456", "789"],
+  "delete_spu_ids": ["100", "101"]
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tenant_id` | string | Y | 租户ID |
+| `spu_ids` | array[string] | N | SPU ID列表（1-100个），要索引的SPU。如果为空，则只执行删除操作 |
+| `delete_spu_ids` | array[string] | N | 显式指定要删除的SPU ID列表（1-100个），可选。无论数据库状态如何，都会从ES中删除这些SPU |
+
+**注意**：
+- `spu_ids` 和 `delete_spu_ids` 不能同时为空
+- 每个列表最多支持100个SPU ID
+- 如果SPU在`spu_ids`中且数据库`deleted=1`，会自动从ES删除（自动检测删除）
+
+#### 响应格式
+
+```json
+{
+  "spu_ids": [
+    {
+      "spu_id": "123",
+      "status": "indexed"
+    },
+    {
+      "spu_id": "456",
+      "status": "deleted"
+    },
+    {
+      "spu_id": "789",
+      "status": "failed",
+      "msg": "SPU not found (unexpected)"
+    }
+  ],
+  "delete_spu_ids": [
+    {
+      "spu_id": "100",
+      "status": "deleted"
+    },
+    {
+      "spu_id": "101",
+      "status": "not_found"
+    },
+    {
+      "spu_id": "102",
+      "status": "failed",
+      "msg": "Failed to delete from ES: Connection timeout"
+    }
+  ],
+  "total": 6,
+  "success_count": 4,
+  "failed_count": 2,
+  "elapsed_time": 1.23,
+  "index_name": "search_products",
+  "tenant_id": "162"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `spu_ids` | array | spu_ids对应的响应列表，每个元素包含 `spu_id` 和 `status` |
+| `spu_ids[].status` | string | 状态：`indexed`（已索引）、`deleted`（已删除，自动检测）、`failed`（失败） |
+| `spu_ids[].msg` | string | 当status为`failed`时，包含失败原因（可选） |
+| `delete_spu_ids` | array | delete_spu_ids对应的响应列表，每个元素包含 `spu_id` 和 `status` |
+| `delete_spu_ids[].status` | string | 状态：`deleted`（已删除）、`not_found`（ES中不存在）、`failed`（失败） |
+| `delete_spu_ids[].msg` | string | 当status为`failed`时，包含失败原因（可选） |
+| `total` | integer | 总处理数量（spu_ids数量 + delete_spu_ids数量） |
+| `success_count` | integer | 成功数量（indexed + deleted + not_found） |
+| `failed_count` | integer | 失败数量 |
+| `elapsed_time` | float | 耗时（秒） |
+| `index_name` | string | 索引名称 |
+| `tenant_id` | string | 租户ID |
+
+**状态说明**：
+- `spu_ids` 的状态：
+  - `indexed`: SPU已成功索引到ES
+  - `deleted`: SPU在数据库中被标记为deleted=1，已从ES删除（自动检测）
+  - `failed`: 处理失败，会包含`msg`字段说明失败原因
+- `delete_spu_ids` 的状态：
+  - `deleted`: SPU已从ES成功删除
+  - `not_found`: SPU在ES中不存在（也算成功，可能已经被删除过）
+  - `failed`: 删除失败，会包含`msg`字段说明失败原因
+
+#### 请求示例
+
+**示例1：普通增量索引（自动检测删除）**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/index" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": ["123", "456", "789"]
+  }'
+```
+
+说明：如果SPU 456在数据库中`deleted=1`，会自动从ES删除，在响应中`spu_ids`列表里456的状态为`deleted`。
+
+**示例2：显式删除（批量删除）**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/index" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": ["123", "456"],
+    "delete_spu_ids": ["100", "101", "102"]
+  }'
+```
+
+说明：SPU 100、101、102会被显式删除，无论数据库状态如何。
+
+**示例3：仅删除（不索引）**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/index" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": [],
+    "delete_spu_ids": ["100", "101"]
+  }'
+```
+
+说明：只执行删除操作，不进行索引。
+
+**示例4：混合操作（索引+删除）**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/index" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": ["123", "456", "789"],
+    "delete_spu_ids": ["100", "101"]
+  }'
+```
+
+说明：同时执行索引和删除操作。
+
+#### 日志说明
+
+增量索引操作的所有关键信息都会记录到 `logs/indexer.log` 文件中（JSON格式），包括：
+- 请求开始和结束时间
+- 每个SPU的处理状态（获取、转换、索引、删除）
+- ES批量写入结果
+- 成功/失败统计
+- 详细的错误信息
+
+日志查询方式请参考[5.1节查看索引日志](#51-全量重建索引接口)部分。
+
+### 5.4 查询文档接口
+
+- **端点**: `POST /indexer/documents`
+- **描述**: 查询文档接口，根据SPU ID列表获取ES文档数据（**不写入ES**）。用于查看、调试或验证SPU数据。
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "162",
+  "spu_ids": ["123", "456", "789"]
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tenant_id` | string | Y | 租户ID |
+| `spu_ids` | array[string] | Y | SPU ID列表（1-100个） |
+
+#### 响应格式
+
+```json
+{
+  "success": [
+    {
+      "spu_id": "123",
+      "document": {
+        "tenant_id": "162",
+        "spu_id": "123",
+        "title": {
+          "zh": "商品标题"
+        },
+        ...
+      }
+    },
+    {
+      "spu_id": "456",
+      "document": {...}
+    }
+  ],
+  "failed": [
+    {
+      "spu_id": "789",
+      "error": "SPU not found or deleted"
+    }
+  ],
+  "total": 3,
+  "success_count": 2,
+  "failed_count": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | array | 成功获取的SPU列表，每个元素包含 `spu_id` 和 `document`（完整的ES文档数据） |
+| `failed` | array | 失败的SPU列表，每个元素包含 `spu_id` 和 `error`（失败原因） |
+| `total` | integer | 总SPU数量 |
+| `success_count` | integer | 成功数量 |
+| `failed_count` | integer | 失败数量 |
+
+#### 请求示例
+
+**单个SPU查询**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/documents" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": ["123"]
+  }'
+```
+
+**批量SPU查询**:
+
+```bash
+curl -X POST "http://localhost:6004/indexer/documents" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "162",
+    "spu_ids": ["123", "456", "789"]
+  }'
+```
+
+#### 与 `/indexer/index` 的区别
+
+| 接口 | 功能 | 是否写入ES | 返回内容 |
+|------|------|-----------|----------|
+| `/indexer/documents` | 查询SPU文档数据 | 否 | 返回完整的ES文档数据 |
+| `/indexer/index` | 增量索引 | 是 | 返回成功/失败列表和统计信息 |
+
+**使用场景**：
+- `/indexer/documents`：用于查看、调试或验证SPU数据，不修改ES索引
+- `/indexer/index`：用于实际的增量索引操作，将更新的SPU数据同步到ES
+
+### 5.5 索引健康检查接口
+
+- **端点**: `GET /indexer/health`
+- **描述**: 检查索引服务健康状态（与 `api/routes/indexer.py` 中 `indexer_health_check` 一致）
+
+#### 响应格式
+
+```json
+{
+  "status": "available",
+  "database": "connected",
+  "preloaded_data": {
+    "category_mappings": 150
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | string | `available`（服务可用）、`unavailable`（未初始化）、`error`（异常） |
+| `database` | string | 数据库连接状态，如 `connected` 或 `disconnected: ...` |
+| `preloaded_data.category_mappings` | integer | 已加载的分类映射数量 |
+
+#### 请求示例
+
+```bash
+curl -X GET "http://localhost:6004/indexer/health"
+```
+
+### 5.6 文档构建接口（正式对接推荐）
+
+#### 5.6.1 `POST /indexer/build-docs`
+
+- **描述**:  
+  基于调用方（通常是 Java 索引程序）提供的 **MySQL 行数据** 构建 ES 文档（doc），**不写入 ES**。  
+  由本服务负责“如何构建 doc”（多语言、翻译、向量、规格聚合等），由调用方负责“何时调度 + 如何写 ES”。
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "170",
+  "items": [
+    {
+      "spu": { "id": 223167, "tenant_id": 170, "title": "..." },
+      "skus": [
+        { "id": 3988393, "spu_id": 223167, "price": 25.99, "compare_at_price": 25.99 }
+      ],
+      "options": []
+    }
+  ]
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tenant_id` | string | Y | 租户 ID |
+| `items` | array | Y | 需构建 doc 的 SPU 列表（每项含 `spu`、`skus`、`options`），**单次最多 200 条** |
+
+> `spu` / `skus` / `options` 字段应当直接使用从 `shoplazza_product_spu` / `shoplazza_product_sku` / `shoplazza_product_option` 查询出的行字段。
+
+#### 请求示例（完整 curl）
+
+> 完整请求体参考 `scripts/test_build_docs_api.py` 中的 `build_sample_request()`。
+
+```bash
+# 单条 SPU 示例（含 spu、skus、options）
+curl -X POST "http://localhost:6004/indexer/build-docs" \
+  -H "Content-Type: application/json" \
+  -d '{
+  "tenant_id": "162",
+  "items": [
+    {
+      "spu": {
+        "id": 10001,
+        "tenant_id": "162",
+        "title": "测试T恤 纯棉短袖",
+        "brief": "舒适纯棉，多色可选",
+        "description": "这是一款适合日常穿着的纯棉T恤，透气吸汗。",
+        "vendor": "测试品牌",
+        "category": "服装/上衣/T恤",
+        "category_id": 100,
+        "category_level": 2,
+        "category_path": "服装/上衣/T恤",
+        "fake_sales": 1280,
+        "image_src": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg",
+        "tags": "T恤,纯棉,短袖,夏季",
+        "create_time": "2024-01-01T00:00:00Z",
+        "update_time": "2024-01-01T00:00:00Z"
+      },
+      "skus": [
+        {
+          "id": 20001,
+          "spu_id": 10001,
+          "price": 99.0,
+          "compare_at_price": 129.0,
+          "sku": "SKU-TSHIRT-001",
+          "inventory_quantity": 50,
+          "option1": "黑色",
+          "option2": "M",
+          "option3": null
+        },
+        {
+          "id": 20002,
+          "spu_id": 10001,
+          "price": 99.0,
+          "compare_at_price": 129.0,
+          "sku": "SKU-TSHIRT-002",
+          "inventory_quantity": 30,
+          "option1": "白色",
+          "option2": "L",
+          "option3": null
+        }
+      ],
+      "options": [
+        {"id": 1, "position": 1, "name": "颜色"},
+        {"id": 2, "position": 2, "name": "尺码"}
+      ]
+    }
+  ]
+}'
+```
+
+生产环境替换 `localhost:6004` 为实际 Indexer 地址，如 `http://43.166.252.75:6004`。
+
+#### 响应示例（节选）
+
+```json
+{
+  "tenant_id": "170",
+  "docs": [
+    {
+      "tenant_id": "170",
+      "spu_id": "223167",
+      "title": { "en": "...", "zh": "..." },
+      "tags": ["Floerns", "Clothing", "Shoes & Jewelry"],
+      "skus": [
+        {
+          "sku_id": "3988393",
+          "price": 25.99,
+          "compare_at_price": 25.99,
+          "stock": 100
+        }
+      ],
+      "min_price": 25.99,
+      "max_price": 25.99,
+      "compare_at_price": 25.99,
+      "total_inventory": 100,
+      "title_embedding": [/* 1024 维向量 */]
+      // 其余字段与 mappings/search_products.json 一致
+    }
+  ],
+  "total": 1,
+  "success_count": 1,
+  "failed_count": 0,
+  "failed": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tenant_id` | string | 租户 ID |
+| `docs` | array | 构建成功的 ES 文档列表，与 `mappings/search_products.json` 一致 |
+| `total` | integer | 请求的 items 总数 |
+| `success_count` | integer | 成功构建数量 |
+| `failed_count` | integer | 失败数量 |
+| `failed` | array | 失败项列表，每项含 `spu_id`、`error` |
+
+#### 使用建议
+
+- **生产环境推荐流程**：
+  1. Java 根据业务逻辑决定哪些 SPU 需要（全量/增量）处理；
+  2. Java 从 MySQL 查询 SPU/SKU/Option 行，拼成 `items`；
+  3. 调用 `/indexer/build-docs` 获取 ES-ready `docs`；
+  4. Java 使用自己的 ES 客户端写入 `search_products_tenant_{tenant_id}`。
+
+### 5.7 文档构建接口（测试 / 自测）
+
+#### 5.7.1 `POST /indexer/build-docs-from-db`
+
+- **描述**:  
+  仅用于测试/调试：调用方只提供 `tenant_id` 和 `spu_ids`，由 indexer 服务内部从 MySQL 查询 SPU/SKU/Option，然后调用与 `/indexer/build-docs` 相同的文档构建逻辑，返回 ES-ready doc。**生产环境请使用 `/indexer/build-docs`，由上游查库并写 ES。**
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "170",
+  "spu_ids": ["223167", "223168"]
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tenant_id` | string | Y | 租户 ID |
+| `spu_ids` | array[string] | Y | SPU ID 列表，**单次最多 200 个** |
+
+#### 响应格式
+
+与 `/indexer/build-docs` 相同：`tenant_id`、`docs`、`total`、`success_count`、`failed_count`、`failed`。
+
+#### 请求示例
+
+```bash
+curl -X POST "http://127.0.0.1:6004/indexer/build-docs-from-db" \
+  -H "Content-Type: application/json" \
+  -d '{"tenant_id": "170", "spu_ids": ["223167"]}'
+```
+
+返回结构与 `/indexer/build-docs` 相同，可直接用于对比 ES 实际文档或调试字段映射问题。
+
+### 5.8 内容理解字段生成接口
+
+- **端点**: `POST /indexer/enrich-content`
+- **描述**: 根据商品内容信息批量生成 **qanchors**（锚文本）、**semantic_attributes**（语义属性）、**tags**（细分标签），供外部 indexer 在「微服务组合」方式下自行拼装 doc 时使用。请求以 `items[]` 传入商品内容字段（必填/可选见下表）。内部逻辑与 `indexer.product_enrich` 一致，支持多语言与 Redis 缓存；单次请求在线程池中执行，避免阻塞其他接口。
+
+#### 请求参数
+
+```json
+{
+  "tenant_id": "170",
+  "items": [
+    {
+      "spu_id": "223167",
+      "title": "纯棉短袖T恤 夏季男装",
+      "brief": "夏季透气纯棉短袖，舒适亲肤",
+      "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
+      "image_url": "https://example.com/images/223167.jpg"
+    },
+    {
+      "spu_id": "223168",
+      "title": "12PCS Dolls with Bottles",
+      "image_url": "https://example.com/images/223168.jpg"
+    }
+  ],
+  "languages": ["zh", "en"]
+}
+```
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `tenant_id` | string | Y | - | 租户 ID。目前仅用于记录日志，不产生实际作用|
+| `items` | array | Y | - | 待分析列表；**单次最多 50 条** |
+| `languages` | array[string] | N | `["zh", "en"]` | 目标语言，需在支持范围内：`zh`、`en`、`de`、`ru`、`fr` |
+
+`items[]` 字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `spu_id` | string | Y | SPU ID，用于回填结果；目前仅用于记录日志，不产生实际作用|
+| `title` | string | Y | 商品标题 |
+| `image_url` | string | N | 商品主图 URL；当前会参与内容缓存键，后续可用于图像/多模态内容理解 |
+| `brief` | string | N | 商品简介/短描述；当前会参与内容缓存键 |
+| `description` | string | N | 商品详情/长描述；当前会参与内容缓存键 |
+
+缓存说明：
+
+- 内容缓存键仅由 `target_lang + items[]` 中会影响内容理解结果的输入文本构成，目前包括：`title`、`brief`、`description`、`image_url` 的规范化内容 hash。
+- `tenant_id`、`spu_id` 只用于请求归属与结果回填，不参与缓存键。
+- 因此，输入内容不变时可跨请求直接命中缓存；任一输入字段变化时，会自然落到新的缓存 key。
+
+批量请求建议：
+- **全量**：强烈建议 尽可能 **20 个 SPU/doc** 攒成一个批次后再请求一次。
+- **增量**：可按时效要求设置时间窗口（例如 **5 分钟**），在窗口内尽可能攒到 **20 个**；达到 20 或窗口到期就发送一次请求。
+- 允许超过20，服务内部会拆分成小批次逐个处理。也允许小于20，但是将造成费用和耗时的成本上升，特别是每次请求一个doc的情况。
+
+#### 响应格式
+
+```json
+{
+  "tenant_id": "170",
+  "total": 2,
+  "results": [
+    {
+      "spu_id": "223167",
+      "qanchors": {
+        "zh": "短袖T恤,纯棉,男装,夏季",
+        "en": "cotton t-shirt, short sleeve, men, summer"
+      },
+      "semantic_attributes": [
+        { "lang": "zh", "name": "tags", "value": "纯棉" },
+        { "lang": "zh", "name": "usage_scene", "value": "日常" },
+        { "lang": "en", "name": "tags", "value": "cotton" }
+      ],
+      "tags": ["纯棉", "短袖", "男装", "cotton", "short sleeve"]
+    },
+    {
+      "spu_id": "223168",
+      "qanchors": { "en": "dolls, toys, 12pcs" },
+      "semantic_attributes": [],
+      "tags": ["dolls", "toys"]
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `results` | array | 与请求 `items` 一一对应，每项含 `spu_id`、`qanchors`、`semantic_attributes`、`tags` |
+| `results[].qanchors` | object | 按语言键的锚文本（逗号分隔短语），可写入 ES 文档的 `qanchors.{lang}` |
+| `results[].semantic_attributes` | array | 语义属性列表，每项为 `{ "lang", "name", "value" }`，可写入 ES 的 `semantic_attributes` nested 字段 |
+| `results[].tags` | array | 从语义属性中抽取的 `name=tags` 的 value 集合，可与业务原有 `tags` 合并后写入 ES 的 `tags` 字段 |
+| `results[].error` | string | 若该条处理失败（如 LLM 异常），会在此字段返回错误信息 |
+
+**错误响应**:
+- `400`: `items` 为空或超过 50 条
+- `503`: 未配置 `DASHSCOPE_API_KEY`，内容理解服务不可用
+
+#### 请求示例
+
+```bash
+curl -X POST "http://localhost:6004/indexer/enrich-content" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "170",
+    "items": [
+      {
+        "spu_id": "223167",
+        "title": "纯棉短袖T恤 夏季男装",
+        "brief": "夏季透气纯棉短袖，舒适亲肤",
+        "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
+        "image_url": "https://example.com/images/223167.jpg"
+      }
+    ],
+    "languages": ["zh", "en"]
+  }'
+```
+
+---
+
@@ -0,0 +1,53 @@
+# 搜索API对接指南-06-管理接口（Admin）
+
+用于查看服务健康状态、获取租户配置与索引统计信息（原文第 6 章）。
+
+## 管理接口
+
+### 6.1 健康检查
+
+- **端点**: `GET /admin/health`
+- **描述**: 检查服务与依赖（如 Elasticsearch）状态。
+
+```json
+{
+  "status": "healthy",
+  "elasticsearch": "connected",
+  "tenant_id": "tenant1"
+}
+```
+
+### 6.2 获取配置
+
+- **端点**: `GET /admin/config`
+- **描述**: 返回当前租户的脱敏配置，便于核对索引及排序表达式。
+
+```json
+{
+  "tenant_id": "tenant1",
+  "tenant_name": "Tenant1 Test Instance",
+  "es_index_name": "search_tenant1",
+  "num_fields": 20,
+  "num_indexes": 4,
+  "supported_languages": ["zh", "en", "ru"],
+  "spu_enabled": false
+}
+```
+
+### 6.3 索引统计
+
+- **端点**: `GET /admin/stats`
+- **描述**: 获取指定租户索引文档数量与磁盘大小，方便监控。
+- **租户标识**：通过请求头 `X-Tenant-ID` 或 query 参数 `tenant_id` 传递（必填）。
+
+```json
+{
+  "tenant_id": "162",
+  "index_name": "search_products_tenant_162",
+  "document_count": 10000,
+  "size_mb": 523.45
+}
+```
+
+---
+
@@ -0,0 +1,401 @@
+# 搜索API对接指南-07-微服务接口（Embedding-Reranker-Translation）
+
+本篇覆盖向量服务（Embedding）、重排服务（Reranker）、翻译服务（Translation）以及 Indexer 服务内的内容理解字段生成（原文第 7 章）。
+
+## 7. 微服务接口（向量、重排、翻译）
+
+以下三个微服务独立部署，**外部系统可直接调用**。它们被搜索后端（6002）和索引服务（6004）内部使用，也可供其他业务系统直接对接。
+
+| 服务 | 默认端口 | Base URL | 说明 |
+|------|----------|----------|------|
+| 向量服务（文本） | 6005 | `http://localhost:6005` | 文本向量化，用于 query/doc 语义检索 |
+| 向量服务（图片） | 6008 | `http://localhost:6008` | 图片向量化，用于以图搜图 |
+| 翻译服务 | 6006 | `http://localhost:6006` | 多语言翻译（云端与本地模型统一入口） |
+| 重排服务 | 6007 | `http://localhost:6007` | 对检索结果进行二次排序 |
+
+生产环境请将 `localhost` 替换为实际服务地址。
+服务管理入口与完整启停规则见：`docs/Usage-Guide.md` -> `服务管理总览`。
+
+### 7.1 向量服务（Embedding）
+
+- **Base URL**:
+  - 文本：`http://localhost:6005`（可通过 `EMBEDDING_TEXT_SERVICE_URL` 覆盖）
+  - 图片：`http://localhost:6008`（可通过 `EMBEDDING_IMAGE_SERVICE_URL` 覆盖）
+- **启动**:
+  - 文本：`./scripts/start_embedding_text_service.sh`
+  - 图片：`./scripts/start_embedding_image_service.sh`
+- **依赖**:
+  - 文本向量后端默认走 TEI（`http://127.0.0.1:8080`）
+  - 图片向量依赖 `cnclip`（`grpc://127.0.0.1:51000`）
+  - TEI 默认使用 GPU（`TEI_DEVICE=cuda`）；当配置为 GPU 且不可用时会启动失败（不会自动降级到 CPU）
+  - cnclip 默认使用 `cuda`；若配置为 `cuda` 但 GPU 不可用会启动失败（不会自动降级到 `cpu`）
+  - 当前单机部署建议保持单实例，通过**文本/图片拆分 + 独立限流**隔离压力
+
+补充说明：
+
+- 文本和图片现在已经拆成**不同进程 / 不同端口**，避免图片下载与编码波动影响文本向量化。
+- 服务端对 text / image 有**独立 admission control**：
+  - `TEXT_MAX_INFLIGHT`
+  - `IMAGE_MAX_INFLIGHT`
+- 当超过处理能力时，服务会直接返回过载错误，而不是无限排队。
+- `GET /health` 会返回各自的 `limits`、`stats`、`cache_enabled` 等状态；`GET /ready` 用于就绪探针。
+
+#### 7.1.1 `POST /embed/text` — 文本向量化
+
+将文本列表转为 1024 维向量，用于语义搜索、文档索引等。
+
+**请求体**（JSON 数组）:
+
+```json
+["文本1", "文本2", "文本3"]
+```
+
+**响应**（JSON 数组，与输入一一对应）:
+
+```json
+[[0.01, -0.02, ...], [0.03, 0.01, ...], ...]
+```
+
+**完整 curl 示例**:
+
+```bash
+curl -X POST "http://localhost:6005/embed/text?normalize=true" \
+  -H "Content-Type: application/json" \
+  -d '["芭比娃娃 儿童玩具", "纯棉T恤 短袖"]'
+```
+
+#### 7.1.2 `POST /embed/image` — 图片向量化
+
+将图片 URL 或路径转为向量，用于以图搜图。
+
+前置条件：`cnclip` 服务已启动（默认端口 `51000`）。若未启动，图片 embedding 服务启动会失败或请求返回错误。
+
+**请求体**（JSON 数组）:
+
+```json
+["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
+```
+
+**响应**（JSON 数组，与输入一一对应）:
+
+```json
+[[0.01, -0.02, ...], [0.03, 0.01, ...], ...]
+```
+
+**完整 curl 示例**:
+
+```bash
+curl -X POST "http://localhost:6008/embed/image?normalize=true" \
+  -H "Content-Type: application/json" \
+  -d '["https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"]'
+```
+
+#### 7.1.3 `GET /health` — 健康检查
+
+```bash
+curl "http://localhost:6005/health"
+curl "http://localhost:6008/health"
+```
+
+返回中会包含：
+
+- `service_kind`：`text` / `image` / `all`
+- `cache_enabled`：text/image Redis 缓存是否可用
+- `limits`：当前 inflight limit、active、rejected_total 等
+- `stats`：request_total、cache_hits、cache_misses、avg_latency_ms 等
+
+#### 7.1.4 `GET /ready` — 就绪检查
+
+```bash
+curl "http://localhost:6005/ready"
+curl "http://localhost:6008/ready"
+```
+
+#### 7.1.5 缓存与限流说明
+
+- 文本与图片都会先查 Redis 向量缓存。
+- Redis 中 value 仍是 **BF16 bytes**，读取后恢复成 `float32` 返回。
+- cache key 已区分 `normalize=true/false`，避免不同归一化策略命中同一条缓存。
+- 当服务端发现请求是 **full-cache-hit** 时，会直接返回，不占用模型并发槽位。
+- 当服务端发现超过 `TEXT_MAX_INFLIGHT` / `IMAGE_MAX_INFLIGHT` 时，会直接拒绝，而不是无限排队。
+
+#### 7.1.6 TEI 统一调优建议（主服务）
+
+使用单套主服务即可同时兼顾：
+- 在线 query 向量化（低延迟，常见 `batch=1~4`）
+- 索引构建向量化（高吞吐，常见 `batch=15~20`）
+
+统一启动（主链路）：
+
+```bash
+./scripts/start_tei_service.sh
+./scripts/service_ctl.sh restart embedding
+```
+
+默认端口：
+- TEI: `http://127.0.0.1:8080`
+- 文本向量服务（`/embed/text`）: `http://127.0.0.1:6005`
+- 图片向量服务（`/embed/image`）: `http://127.0.0.1:6008`
+
+当前主 TEI 启动默认值（已按 T4/短文本场景调优）：
+- `TEI_MAX_BATCH_TOKENS=4096`
+- `TEI_MAX_CLIENT_BATCH_SIZE=24`
+- `TEI_DTYPE=float16`
+
+### 7.2 重排服务（Reranker）
+
+- **Base URL**: `http://localhost:6007`（可通过 `RERANKER_SERVICE_URL` 覆盖）
+- **启动**: `./scripts/start_reranker.sh`
+
+说明：默认后端为 `qwen3_vllm`（`Qwen/Qwen3-Reranker-0.6B`），需要可用 GPU 显存。
+
+补充：`docs` 的请求大小与模型推理 `batch size` 解耦。即使一次传入 1000 条文档，服务端也会按 `services.rerank.backends.qwen3_vllm.infer_batch_size` 自动拆分；若 `sort_by_doc_length=true`，会先按文档长度排序后分批，减少 padding，再按原输入顺序返回分数。`length_sort_mode` 可选 `char`（更快）或 `token`（更精确）。
+
+#### 7.2.1 `POST /rerank` — 结果重排
+
+根据 query 与 doc 的相关性对文档列表重新打分排序。
+
+**请求体**:
+```json
+{
+  "query": "玩具 芭比",
+  "docs": [
+    "12PCS 6 Types of Dolls with Bottles",
+    "纯棉T恤 短袖 夏季"
+  ],
+  "normalize": true
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `query` | string | Y | 搜索查询 |
+| `docs` | array[string] | Y | 待重排的文档列表（单次最多由服务端配置限制） |
+| `normalize` | boolean | N | 是否对分数做 sigmoid 归一化，默认 true |
+
+**响应**:
+```json
+{
+  "scores": [0.92, 0.15],
+  "meta": {
+    "service_elapsed_ms": 45.2,
+    "input_docs": 2,
+    "unique_docs": 2
+  }
+}
+```
+
+**完整 curl 示例**:
+```bash
+curl -X POST "http://localhost:6007/rerank" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "玩具 芭比",
+    "docs": ["12PCS 6 Types of Dolls with Bottles", "纯棉T恤 短袖"],
+    "top_n":386,
+    "normalize": true
+  }'
+```
+
+#### 7.2.2 `GET /health` — 健康检查
+
+```bash
+curl "http://localhost:6007/health"
+```
+
+### 7.3 翻译服务（Translation）
+
+- **Base URL**: `http://localhost:6006`（以 `config/config.yaml -> services.translation.service_url` 为准）
+- **启动**: `./scripts/start_translator.sh`
+
+#### 7.3.1 `POST /translate` — 文本翻译
+
+支持 translator service 内所有已启用 capability，适用于商品名称、描述、query 等电商场景。当前可配置能力包括 `qwen-mt`、`llm`、`deepl` 以及本地模型 `nllb-200-distilled-600m`、`opus-mt-zh-en`、`opus-mt-en-zh`。
+
+**请求体**（支持单条字符串或字符串列表）:
+```json
+{
+  "text": "商品名称",
+  "target_lang": "en",
+  "source_lang": "zh",
+  "model": "qwen-mt",
+  "scene": "sku_name"
+}
+```
+
+也支持批量列表形式:
+```json
+{
+  "text": ["商品名称1", "商品名称2"],
+  "target_lang": "en",
+  "source_lang": "zh",
+  "model": "qwen-mt",
+  "scene": "sku_name"
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `text` | string \| string[] | Y | 待翻译文本，既支持单条字符串，也支持字符串列表（批量翻译） |
+| `target_lang` | string | Y | 目标语言：`zh`、`en`、`ru` 等 |
+| `source_lang` | string | N | 源语言。云端模型可不传；`nllb-200-distilled-600m` 建议显式传入 |
+| `model` | string | N | 已启用 capability 名称，如 `qwen-mt`、`llm`、`deepl`、`nllb-200-distilled-600m`、`opus-mt-zh-en`、`opus-mt-en-zh` |
+| `scene` | string | N | 翻译场景参数，与 `model` 配套使用；当前标准值为 `sku_name`、`ecommerce_search_query`、`general` |
+
+说明：
+- 外部接口不接受 `prompt`；LLM prompt 由服务端按 `scene` 自动生成。
+- 传入未定义的 `scene` 或未启用的 `model` 会返回 `400`。
+
+**SKU 名称场景选型建议**:
+- 批量 SKU 名称翻译，优先考虑本地大吞吐方案时，可使用 `"model": "nllb-200-distilled-600m"`（该模型"scene":参数无效）。
+- 如果目标是更高质量，且可以接受更慢速度与额外 LLM API 费用，可使用 `"model": "llm"` + `"scene": "sku_name"`。
+- 如果是en-zh互译、期待更高的速度，可以考虑`opus-mt-zh-en` / `opus-mt-en-zh`。（质量未详细评测，一些文章说比blib-200-600m更好，但是我看了些case感觉要差不少）
+
+**实时翻译选型建议**:
+- 在线 query 翻译如果只是 `en/zh` 互译，优先使用 `opus-mt-zh-en` 或 `opus-mt-en-zh`，它们是当前已测本地模型里延迟最低的一档。
+- 如果涉及其他语言，或对质量要求高于本地轻量模型，优先考虑 `deepl`。
+- `nllb-200-distilled-600m` 不建议作为在线 query 翻译默认方案；我们在 `Tesla T4` 上测到 `batch_size=1` 时，`zh -> en` p50 约 `292.54 ms`、p95 约 `624.12 ms`，`en -> zh` p50 约 `481.61 ms`、p95 约 `1171.71 ms`。
+
+**Batch Size / 调用方式建议**:
+- 本接口支持 `text: string[]`；离线或批量索引翻译时，应尽量合并请求，让底层 backend 发挥批处理能力。
+- `nllb-200-distilled-600m` 在当前 `Tesla T4` 压测中，推荐配置是 `batch_size=16`、`max_new_tokens=64`、`attn_implementation=sdpa`；继续升到 `batch_size=32` 虽可能提高吞吐，但 tail latency 会明显变差。
+- 在线 query 场景可直接把“单条请求”理解为 `batch_size=1`；更关注 request latency，而不是离线吞吐。
+- `opus-mt-zh-en` / `opus-mt-en-zh` 当前生产配置也是 `batch_size=16`，适合作为中英互译的低延迟本地默认值；若走在线单条调用，同样按 `batch_size=1` 理解即可。
+- `llm` 按单条请求即可。
+
+**响应**:
+```json
+{
+  "text": "商品名称",
+  "target_lang": "en",
+  "source_lang": "zh",
+  "translated_text": "Product name",
+  "status": "success",
+  "model": "qwen-mt",
+  "scene": "sku_name"
+}
+```
+
+当请求为列表形式时，`text` 与 `translated_text` 均为等长数组:
+```json
+{
+  "text": ["商品名称1", "商品名称2"],
+  "target_lang": "en",
+  "source_lang": "zh",
+  "translated_text": ["Product name 1", "Product name 2"],
+  "status": "success",
+  "model": "qwen-mt",
+  "scene": "sku_name"
+}
+```
+
+> **失败语义（批量）**：当 `text` 为列表时，如果其中某条翻译失败，对应位置返回 `null`（即 `translated_text[i] = null`），并保持数组长度与顺序不变；接口整体仍返回 `status="success"`，用于避免“部分失败”导致整批请求失败。
+
+> **实现提示（可忽略）**：服务端会尽可能使用底层 backend 的批量能力（若支持），否则自动拆分逐条翻译；无论采用哪种方式，上述批量契约保持一致。
+
+**完整 curl 示例**:
+
+中文 → 英文:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "商品名称",
+    "target_lang": "en",
+    "source_lang": "zh"
+  }'
+```
+
+俄文 → 英文:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Название товара",
+    "target_lang": "en",
+    "source_lang": "ru"
+  }'
+```
+
+使用 DeepL 模型:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "商品名称",
+    "target_lang": "en",
+    "source_lang": "zh",
+    "model": "deepl"
+  }'
+```
+
+使用本地 OPUS 模型（中文 → 英文）:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "蓝牙耳机",
+    "target_lang": "en",
+    "source_lang": "zh",
+    "model": "opus-mt-zh-en",
+    "scene": "sku_name"
+  }'
+```
+
+使用本地 NLLB 做 SKU 名称批量翻译:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": ["商品名称1", "商品名称2", "商品名称3"],
+    "target_lang": "en",
+    "source_lang": "zh",
+    "model": "nllb-200-distilled-600m",
+    "scene": "sku_name"
+  }'
+```
+
+使用 LLM 做高质量 SKU 名称翻译:
+```bash
+curl -X POST "http://localhost:6006/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "男士偏光飞行员太阳镜",
+    "target_lang": "en",
+    "source_lang": "zh",
+    "model": "llm",
+    "scene": "sku_name"
+  }'
+```
+
+#### 7.3.2 `GET /health` — 健康检查
+
+```bash
+curl "http://localhost:6006/health"
+```
+
+典型响应：
+```json
+{
+  "status": "healthy",
+  "service": "translation",
+  "default_model": "llm",
+  "default_scene": "general",
+  "available_models": ["qwen-mt", "llm", "opus-mt-zh-en"],
+  "enabled_capabilities": ["qwen-mt", "llm", "opus-mt-zh-en"],
+  "loaded_models": ["llm"]
+}
+```
+
+### 7.4 内容理解字段生成（Indexer 服务内）
+
+内容理解字段生成接口部署在 **Indexer 服务**（默认端口 6004）内，与「翻译、向量化」等独立端口微服务并列，供采用**微服务组合**方式的 indexer 调用。
+
+- **Base URL**: Indexer 服务地址，如 `http://localhost:6004`
+- **路径**: `POST /indexer/enrich-content`
+- **说明**: 根据商品标题批量生成 `qanchors`、`semantic_attributes`、`tags`，用于拼装 ES 文档。内部使用大模型（需配置 `DASHSCOPE_API_KEY`），支持多语言与 Redis 缓存；单次最多 50 条，建议批量调用以提升效率。
+
+请求/响应格式、示例及错误码见 [-05-索引接口（Indexer）](./搜索API对接指南-05-索引接口（Indexer）.md#58-内容理解字段生成接口)。
+
+---
+
@@ -0,0 +1,97 @@
+# 搜索API对接指南-08-数据模型与字段速查
+
+本篇覆盖原文第 9 章：商品字段定义、字段类型速查、常用字段列表、支持的分析器。
+
+## 9. 数据模型
+
+### 9.1 商品字段定义
+
+| 字段名 | 类型 | 描述 |
+|--------|------|------|
+| `tenant_id` | keyword | 租户ID（多租户隔离） |
+| `spu_id` | keyword | SPU ID |
+| `title.<lang>` | object/text | 商品标题（多语言对象，如 `title.zh`, `title.en`） |
+| `brief.<lang>` | object/text | 商品短描述（多语言对象，如 `brief.zh`, `brief.en`） |
+| `description.<lang>` | object/text | 商品详细描述（多语言对象，如 `description.zh`, `description.en`） |
+| `vendor.<lang>` | object/text | 供应商/品牌（多语言对象，且带 keyword 子字段，如 `vendor.zh.keyword`） |
+| `category_path.<lang>` | object/text | 类目路径（多语言对象，用于搜索，如 `category_path.zh`） |
+| `category_name_text.<lang>` | object/text | 类目名称（多语言对象，用于搜索，如 `category_name_text.zh`） |
+| `category_id` | keyword | 类目ID |
+| `category_name` | keyword | 类目名称（用于过滤） |
+| `category_level` | integer | 类目层级 |
+| `category1_name`, `category2_name`, `category3_name` | keyword | 多级类目名称（用于过滤和分面） |
+| `tags` | keyword | 标签（数组） |
+| `specifications` | nested | 规格（嵌套对象数组） |
+| `option1_name`, `option2_name`, `option3_name` | keyword | 选项名称 |
+| `min_price`, `max_price` | float | 最低/最高价格 |
+| `compare_at_price` | float | 原价 |
+| `sku_prices` | float | SKU价格列表（数组） |
+| `sku_weights` | long | SKU重量列表（数组） |
+| `sku_weight_units` | keyword | SKU重量单位列表（数组） |
+| `total_inventory` | long | 总库存 |
+| `sales` | long | 销量（展示销量） |
+| `skus` | nested | SKU详细信息（嵌套对象数组） |
+| `create_time`, `update_time` | date | 创建/更新时间 |
+| `title_embedding` | dense_vector | 标题向量（1024维，仅用于搜索） |
+| `image_embedding` | nested | 图片向量（嵌套，仅用于搜索） |
+
+> 所有租户共享统一的索引结构。文本字段支持中英文双语，后端根据 `language` 参数自动选择对应字段返回。
+
+### 9.2 字段类型速查
+
+| 类型 | ES Mapping | 用途 |
+|------|------------|------|
+| `text` | `text` | 全文检索（支持中英文分析器） |
+| `keyword` | `keyword` | 精确匹配、聚合、排序 |
+| `integer` | `integer` | 整数 |
+| `long` | `long` | 长整数 |
+| `float` | `float` | 浮点数 |
+| `date` | `date` | 日期时间 |
+| `nested` | `nested` | 嵌套对象（specifications, skus, image_embedding） |
+| `dense_vector` | `dense_vector` | 向量字段（title_embedding，仅用于搜索） |
+
+### 9.3 常用字段列表
+
+#### 过滤字段
+
+- `category_name`: 类目名称
+- `category1_name`, `category2_name`, `category3_name`: 多级类目
+- `category_id`: 类目ID
+- `vendor.zh.keyword`, `vendor.en.keyword`: 供应商/品牌（使用keyword子字段）
+- `tags`: 标签（keyword类型）
+- `option1_name`, `option2_name`, `option3_name`: 选项名称
+- `specifications`: 规格过滤（嵌套字段，格式见[过滤器详解](./搜索API对接指南-01-搜索接口.md#33-过滤器详解)）
+
+#### 范围字段
+
+- `min_price`: 最低价格
+- `max_price`: 最高价格
+- `compare_at_price`: 原价
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+
+#### 排序字段
+
+- `price`: 价格（后端自动根据sort_order映射：asc→min_price，desc→max_price）
+- `sales`: 销量
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+- `relevance_score`: 相关性分数（默认，不指定sort_by时使用）
+
+**注意**: 前端只需传 `price`，后端会自动处理：
+- `sort_by: "price"` + `sort_order: "asc"` → 按 `min_price` 升序（价格从低到高）
+- `sort_by: "price"` + `sort_order: "desc"` → 按 `max_price` 降序（价格从高到低）
+
+### 9.4 支持的分析器
+
+| 分析器 | 语言 | 描述 |
+|--------|------|------|
+| `index_ik` | 中文 | 中文索引分析器（用于中文字段） |
+| `query_ik` | 中文 | 中文查询分析器（用于中文字段） |
+| `hanlp_index` ⚠️ TODO（暂不支持） | 中文 | 中文索引分析器（用于中文字段） |
+| `hanlp_standard` ⚠️ TODO（暂不支持） | 中文 | 中文查询分析器（用于中文字段） |
+| `english` | 英文 | 标准英文分析器（用于英文字段） |
+| `lowercase` | - | 小写标准化器（用于keyword子字段） |
+
+---
+
@@ -0,0 +1,61 @@
+# 搜索API对接指南-10-接口级压测脚本
+
+原文第 10 章：压测脚本与用例。
+
+## 10. 接口级压测脚本
+
+仓库提供统一压测脚本：`scripts/perf_api_benchmark.py`，用于对以下接口做并发压测：
+
+- 后端搜索：`POST /search/`
+- 搜索建议：`GET /search/suggestions`
+- 向量服务：`POST /embed/text`
+- 翻译服务：`POST /translate`
+- 重排服务：`POST /rerank`
+
+说明：脚本对 `embed_text` 场景会校验返回向量内容有效性（必须是有限数值，不允许 `null/NaN/Inf`），不是只看 HTTP 200。
+
+### 10.1 快速示例
+
+```bash
+# suggest 压测（tenant 162）
+python scripts/perf_api_benchmark.py \
+  --scenario backend_suggest \
+  --tenant-id 162 \
+  --duration 30 \
+  --concurrency 50
+
+# search 压测
+python scripts/perf_api_benchmark.py \
+  --scenario backend_search \
+  --tenant-id 162 \
+  --duration 30 \
+  --concurrency 20
+
+# 全链路压测（search + suggest + embedding + translate + rerank）
+python scripts/perf_api_benchmark.py \
+  --scenario all \
+  --tenant-id 162 \
+  --duration 60 \
+  --concurrency 30 \
+  --output perf_reports/all.json
+```
+
+### 10.2 自定义用例
+
+可通过 `--cases-file` 覆盖默认请求模板。示例文件：
+
+```bash
+scripts/perf_cases.json.example
+```
+
+执行示例：
+
+```bash
+python scripts/perf_api_benchmark.py \
+  --scenario all \
+  --tenant-id 162 \
+  --cases-file scripts/perf_cases.json.example \
+  --duration 60 \
+  --concurrency 40
+```
+
-"""
-Embedding module configuration.
+"""Embedding service compatibility config derived from unified app config."""
-This module is intentionally a plain Python file (no env var parsing, no extra deps).
-Edit values here to configure:
-- server host/port
-- local model settings (paths/devices/batch sizes)
-"""
+from __future__ import annotations
 from typing import Optional
-import os
+
+from config.loader import get_app_config
 class EmbeddingConfig(object):
-    # Server
-    HOST = os.getenv("EMBEDDING_HOST", "0.0.0.0")
-    PORT = int(os.getenv("EMBEDDING_PORT", 6005))
-
-    # Text backend defaults
-    TEXT_MODEL_ID = os.getenv("TEXT_MODEL_ID", "Qwen/Qwen3-Embedding-0.6B")
-    # Keep TEXT_MODEL_DIR as an alias so code can refer to one canonical text model value.
-    TEXT_MODEL_DIR = TEXT_MODEL_ID
-    TEXT_DEVICE = os.getenv("TEXT_DEVICE", "cuda")  # "cuda" or "cpu"
-    TEXT_BATCH_SIZE = int(os.getenv("TEXT_BATCH_SIZE", "32"))
-    TEXT_NORMALIZE_EMBEDDINGS = os.getenv("TEXT_NORMALIZE_EMBEDDINGS", "true").lower() in ("1", "true", "yes")
-    TEI_BASE_URL = os.getenv("TEI_BASE_URL", "http://127.0.0.1:8080")
-    TEI_TIMEOUT_SEC = int(os.getenv("TEI_TIMEOUT_SEC", "60"))
-
-    # Image embeddings
-    # Option A: clip-as-service (Jina CLIP server, recommended)
-    USE_CLIP_AS_SERVICE = os.getenv("USE_CLIP_AS_SERVICE", "true").lower() in ("1", "true", "yes")
-    CLIP_AS_SERVICE_SERVER = os.getenv("CLIP_AS_SERVICE_SERVER", "grpc://127.0.0.1:51000")
-    CLIP_AS_SERVICE_MODEL_NAME = os.getenv("CLIP_AS_SERVICE_MODEL_NAME", "CN-CLIP/ViT-L-14")
-
-    # Option B: local CN-CLIP (when USE_CLIP_AS_SERVICE=false)
-    IMAGE_MODEL_NAME = os.getenv("IMAGE_MODEL_NAME", "ViT-L-14")
-    IMAGE_DEVICE = None  # type: Optional[str]  # "cuda" / "cpu" / None(auto)
-
-    # Service behavior
-    IMAGE_BATCH_SIZE = 8
-    IMAGE_NORMALIZE_EMBEDDINGS = os.getenv("IMAGE_NORMALIZE_EMBEDDINGS", "true").lower() in ("1", "true", "yes")
+    def __init__(self) -> None:
+        app_config = get_app_config()
+        runtime = app_config.runtime
+        services = app_config.services.embedding
+        text_backend = services.get_backend_config()
+        image_backend = services.get_image_backend_config()
+
+        self.HOST = runtime.embedding_host
+        self.PORT = runtime.embedding_port
+
+        self.TEXT_MODEL_ID = str(text_backend.get("model_id") or "Qwen/Qwen3-Embedding-0.6B")
+        self.TEXT_MODEL_DIR = self.TEXT_MODEL_ID
+        self.TEXT_DEVICE = str(text_backend.get("device") or "cuda")
+        self.TEXT_BATCH_SIZE = int(text_backend.get("batch_size", 32))
+        self.TEXT_NORMALIZE_EMBEDDINGS = bool(text_backend.get("normalize_embeddings", True))
+        self.TEI_BASE_URL = str(text_backend.get("base_url") or "http://127.0.0.1:8080")
+        self.TEI_TIMEOUT_SEC = int(text_backend.get("timeout_sec", 60))
+
+        self.USE_CLIP_AS_SERVICE = services.image_backend == "clip_as_service"
+        self.CLIP_AS_SERVICE_SERVER = str(image_backend.get("server") or "grpc://127.0.0.1:51000")
+        self.CLIP_AS_SERVICE_MODEL_NAME = str(image_backend.get("model_name") or "CN-CLIP/ViT-L-14")
+
+        self.IMAGE_MODEL_NAME = str(image_backend.get("model_name") or "ViT-L-14")
+        self.IMAGE_DEVICE = image_backend.get("device")  # type: Optional[str]
+        self.IMAGE_BATCH_SIZE = int(image_backend.get("batch_size", 8))
+        self.IMAGE_NORMALIZE_EMBEDDINGS = bool(image_backend.get("normalize_embeddings", True))
 CONFIG = EmbeddingConfig()
@@ -9,8 +9,8 @@ from PIL import Image
 logger = logging.getLogger(__name__)
+from config.loader import get_app_config
 from config.services_config import get_embedding_image_base_url
-from config.env_config import REDIS_CONFIG
 from embeddings.cache_keys import build_image_cache_key
 from embeddings.redis_embedding_cache import RedisEmbeddingCache
@@ -24,10 +24,11 @@ class CLIPImageEncoder:
     def __init__(self, service_url: Optional[str] = None):
         resolved_url = service_url or get_embedding_image_base_url()
+        redis_config = get_app_config().infrastructure.redis
         self.service_url = str(resolved_url).rstrip("/")
         self.endpoint = f"{self.service_url}/embed/image"
         # Reuse embedding cache prefix, but separate namespace for images to avoid collisions.
-        self.cache_prefix = str(REDIS_CONFIG.get("embedding_cache_prefix", "embedding")).strip() or "embedding"
+        self.cache_prefix = str(redis_config.embedding_cache_prefix).strip() or "embedding"
         logger.info("Creating CLIPImageEncoder instance with service URL: %s", self.service_url)
         self.cache = RedisEmbeddingCache(
             key_prefix=self.cache_prefix,
@@ -20,7 +20,7 @@ try:
 except ImportError:  # pragma: no cover - runtime fallback for minimal envs
     redis = None  # type: ignore[assignment]
-from config.env_config import REDIS_CONFIG
+from config.loader import get_app_config
 from embeddings.bf16 import decode_embedding_from_redis, encode_embedding_for_redis
 logger = logging.getLogger(__name__)
@@ -37,7 +37,8 @@ class RedisEmbeddingCache:
     ):
         self.key_prefix = (key_prefix or "").strip() or "embedding"
         self.namespace = (namespace or "").strip()
-        self.expire_time = expire_time or timedelta(days=REDIS_CONFIG.get("cache_expire_days", 180))
+        redis_config = get_app_config().infrastructure.redis
+        self.expire_time = expire_time or timedelta(days=redis_config.cache_expire_days)
         if redis_client is not None:
             self.redis_client = redis_client
@@ -50,13 +51,13 @@ class RedisEmbeddingCache:
         try:
             client = redis.Redis(
-                host=REDIS_CONFIG.get("host", "localhost"),
-                port=REDIS_CONFIG.get("port", 6479),
-                password=REDIS_CONFIG.get("password"),
+                host=redis_config.host,
+                port=redis_config.port,
+                password=redis_config.password,
                 decode_responses=False,
-                socket_timeout=REDIS_CONFIG.get("socket_timeout", 1),
-                socket_connect_timeout=REDIS_CONFIG.get("socket_connect_timeout", 1),
-                retry_on_timeout=REDIS_CONFIG.get("retry_on_timeout", False),
+                socket_timeout=redis_config.socket_timeout,
+                socket_connect_timeout=redis_config.socket_connect_timeout,
+                retry_on_timeout=redis_config.retry_on_timeout,
                 health_check_interval=10,
             )
             client.ping()
@@ -470,16 +470,8 @@ def load_models():
             if backend_name == "tei":
                 from embeddings.text_embedding_tei import TEITextModel
-                base_url = (
-                    os.getenv("TEI_BASE_URL")
-                    or backend_cfg.get("base_url")
-                    or CONFIG.TEI_BASE_URL
-                )
-                timeout_sec = int(
-                    os.getenv("TEI_TIMEOUT_SEC")
-                    or backend_cfg.get("timeout_sec")
-                    or CONFIG.TEI_TIMEOUT_SEC
-                )
+                base_url = backend_cfg.get("base_url") or CONFIG.TEI_BASE_URL
+                timeout_sec = int(backend_cfg.get("timeout_sec") or CONFIG.TEI_TIMEOUT_SEC)
                 logger.info("Loading text backend: tei (base_url=%s)", base_url)
                 _text_model = TEITextModel(
                     base_url=str(base_url),
@@ -488,11 +480,7 @@ def load_models():
             elif backend_name == "local_st":
                 from embeddings.text_embedding_sentence_transformers import Qwen3TextModel
-                model_id = (
-                    os.getenv("TEXT_MODEL_ID")
-                    or backend_cfg.get("model_id")
-                    or CONFIG.TEXT_MODEL_ID
-                )
+                model_id = backend_cfg.get("model_id") or CONFIG.TEXT_MODEL_ID
                 logger.info("Loading text backend: local_st (model=%s)", model_id)
                 _text_model = Qwen3TextModel(model_id=str(model_id))
                 _start_text_batch_worker()
@@ -9,13 +9,11 @@ import requests
 logger = logging.getLogger(__name__)
+from config.loader import get_app_config
 from config.services_config import get_embedding_text_base_url
 from embeddings.cache_keys import build_text_cache_key
 from embeddings.redis_embedding_cache import RedisEmbeddingCache
-# Try to import REDIS_CONFIG, but allow import to fail
-from config.env_config import REDIS_CONFIG
-
 class TextEmbeddingEncoder:
     """
@@ -24,10 +22,11 @@ class TextEmbeddingEncoder:
     def __init__(self, service_url: Optional[str] = None):
         resolved_url = service_url or get_embedding_text_base_url()
+        redis_config = get_app_config().infrastructure.redis
         self.service_url = str(resolved_url).rstrip("/")
         self.endpoint = f"{self.service_url}/embed/text"
-        self.expire_time = timedelta(days=REDIS_CONFIG.get("cache_expire_days", 180))
-        self.cache_prefix = str(REDIS_CONFIG.get("embedding_cache_prefix", "embedding")).strip() or "embedding"
+        self.expire_time = timedelta(days=redis_config.cache_expire_days)
+        self.cache_prefix = str(redis_config.embedding_cache_prefix).strip() or "embedding"
         logger.info("Creating TextEmbeddingEncoder instance with service URL: %s", self.service_url)
         self.cache = RedisEmbeddingCache(
@@ -13,7 +13,6 @@ import numpy as np
 import logging
 import re
 from typing import Dict, Any, Optional, List
-from config import ConfigLoader
 from indexer.product_enrich import analyze_products
 logger = logging.getLogger(__name__)
@@ -13,7 +13,7 @@ from indexer.mapping_generator import get_tenant_index_name
 from indexer.indexer_logger import (
     get_indexer_logger, log_index_request, log_index_result, log_spu_processing
 )
-from config import ConfigLoader
+from config import get_app_config
 from translation import create_translation_client
 # Configure logger
@@ -51,7 +51,7 @@ class IncrementalIndexerService:
     def _eager_init(self) -> None:
         """Strict eager initialization. Any dependency failure should fail fast."""
-        self._config = ConfigLoader("config/config.yaml").load_config()
+        self._config = get_app_config().search
         self._searchable_option_dimensions = (
             getattr(self._config.spu_config, "searchable_option_dimensions", None)
             or ["option1", "option2", "option3"]
@@ -7,7 +7,7 @@
 import logging
 from typing import Dict, Any, Optional
 from sqlalchemy import Engine, text
-from config import ConfigLoader
+from config import get_app_config
 from config.tenant_config_loader import get_tenant_config_loader
 from indexer.document_transformer import SPUDocumentTransformer
 from translation import create_translation_client
@@ -92,8 +92,7 @@ def create_document_transformer(
         or config is None
     ):
         if config is None:
-            config_loader = ConfigLoader()
-            config = config_loader.load_config()
+            config = get_app_config().search
         if searchable_option_dimensions is None:
             searchable_option_dimensions = config.spu_config.searchable_option_dimensions
@@ -9,7 +9,7 @@ import json
 import logging
 from pathlib import Path
-from config.env_config import ES_INDEX_NAMESPACE
+from config.loader import get_app_config
 logger = logging.getLogger(__name__)
@@ -30,7 +30,7 @@ def get_tenant_index_name(tenant_id: str) -&gt; str:
     其中 ES_INDEX_NAMESPACE 由 config.env_config.ES_INDEX_NAMESPACE 控制，
     用于区分 prod/uat/test 等不同运行环境。
     """
-    prefix = ES_INDEX_NAMESPACE or ""
+    prefix = get_app_config().runtime.index_namespace or ""
     return f"{prefix}search_products_tenant_{tenant_id}"
@@ -12,15 +12,18 @@ import logging
 import re
 import time
 import hashlib
+import uuid
+import threading
 from collections import OrderedDict
 from datetime import datetime
+from concurrent.futures import ThreadPoolExecutor
 from typing import List, Dict, Tuple, Any, Optional
 import redis
 import requests
 from pathlib import Path
-from config.env_config import REDIS_CONFIG
+from config.loader import get_app_config
 from config.tenant_config_loader import SOURCE_LANG_CODE_MAP
 from indexer.product_enrich_prompts import (
     SYSTEM_MESSAGE,
@@ -31,6 +34,9 @@ from indexer.product_enrich_prompts import (
 # 配置
 BATCH_SIZE = 20
+# enrich-content LLM 批次并发 worker 上限（线程池；仅对 uncached batch 并发）
+_APP_CONFIG = get_app_config()
+CONTENT_UNDERSTANDING_MAX_WORKERS = int(_APP_CONFIG.product_enrich.max_workers)
 # 华北2（北京）：https://dashscope.aliyuncs.com/compatible-mode/v1
 # 新加坡：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
 # 美国（弗吉尼亚）：https://dashscope-us.aliyuncs.com/compatible-mode/v1
@@ -56,6 +62,24 @@ timestamp = datetime.now().strftime(&quot;%Y%m%d_%H%M%S&quot;)
 log_file = LOG_DIR / f"product_enrich_{timestamp}.log"
 verbose_log_file = LOG_DIR / "product_enrich_verbose.log"
 _logged_shared_context_keys: "OrderedDict[str, None]" = OrderedDict()
+_logged_shared_context_lock = threading.Lock()
+
+_content_understanding_executor: Optional[ThreadPoolExecutor] = None
+_content_understanding_executor_lock = threading.Lock()
+
+
+def _get_content_understanding_executor() -> ThreadPoolExecutor:
+    """
+    使用模块级单例线程池，避免同一进程内多次请求叠加创建线程池导致并发失控。
+    """
+    global _content_understanding_executor
+    with _content_understanding_executor_lock:
+        if _content_understanding_executor is None:
+            _content_understanding_executor = ThreadPoolExecutor(
+                max_workers=CONTENT_UNDERSTANDING_MAX_WORKERS,
+                thread_name_prefix="product-enrich-llm",
+            )
+        return _content_understanding_executor
 # 主日志 logger：执行流程、批次信息等
 logger = logging.getLogger("product_enrich")
@@ -91,19 +115,20 @@ logger.info(&quot;Verbose LLM logs are written to: %s&quot;, verbose_log_file)
 # Redis 缓存（用于 anchors / 语义属性）
-ANCHOR_CACHE_PREFIX = REDIS_CONFIG.get("anchor_cache_prefix", "product_anchors")
-ANCHOR_CACHE_EXPIRE_DAYS = int(REDIS_CONFIG.get("anchor_cache_expire_days", 30))
+_REDIS_CONFIG = _APP_CONFIG.infrastructure.redis
+ANCHOR_CACHE_PREFIX = _REDIS_CONFIG.anchor_cache_prefix
+ANCHOR_CACHE_EXPIRE_DAYS = int(_REDIS_CONFIG.anchor_cache_expire_days)
 _anchor_redis: Optional[redis.Redis] = None
 try:
     _anchor_redis = redis.Redis(
-        host=REDIS_CONFIG.get("host", "localhost"),
-        port=REDIS_CONFIG.get("port", 6479),
-        password=REDIS_CONFIG.get("password"),
+        host=_REDIS_CONFIG.host,
+        port=_REDIS_CONFIG.port,
+        password=_REDIS_CONFIG.password,
         decode_responses=True,
-        socket_timeout=REDIS_CONFIG.get("socket_timeout", 1),
-        socket_connect_timeout=REDIS_CONFIG.get("socket_connect_timeout", 1),
-        retry_on_timeout=REDIS_CONFIG.get("retry_on_timeout", False),
+        socket_timeout=_REDIS_CONFIG.socket_timeout,
+        socket_connect_timeout=_REDIS_CONFIG.socket_connect_timeout,
+        retry_on_timeout=_REDIS_CONFIG.retry_on_timeout,
         health_check_interval=10,
     )
     _anchor_redis.ping()
@@ -242,19 +267,21 @@ def _hash_text(text: str) -&gt; str:
 def _mark_shared_context_logged_once(shared_context_key: str) -> bool:
-    if shared_context_key in _logged_shared_context_keys:
-        _logged_shared_context_keys.move_to_end(shared_context_key)
-        return False
+    with _logged_shared_context_lock:
+        if shared_context_key in _logged_shared_context_keys:
+            _logged_shared_context_keys.move_to_end(shared_context_key)
+            return False
-    _logged_shared_context_keys[shared_context_key] = None
-    if len(_logged_shared_context_keys) > LOGGED_SHARED_CONTEXT_CACHE_SIZE:
-        _logged_shared_context_keys.popitem(last=False)
-    return True
+        _logged_shared_context_keys[shared_context_key] = None
+        if len(_logged_shared_context_keys) > LOGGED_SHARED_CONTEXT_CACHE_SIZE:
+            _logged_shared_context_keys.popitem(last=False)
+        return True
 def reset_logged_shared_context_keys() -> None:
     """测试辅助：清理已记录的共享 prompt key。"""
-    _logged_shared_context_keys.clear()
+    with _logged_shared_context_lock:
+        _logged_shared_context_keys.clear()
 def create_prompt(
@@ -625,7 +652,9 @@ def process_batch(
             "final_results": results_with_ids,
         }
-        batch_log_file = LOG_DIR / f"batch_{batch_num:04d}_{timestamp}.json"
+        # 并发写 batch json 日志时，保证文件名唯一避免覆盖
+        batch_call_id = uuid.uuid4().hex[:12]
+        batch_log_file = LOG_DIR / f"batch_{batch_num:04d}_{timestamp}_{batch_call_id}.json"
         with open(batch_log_file, "w", encoding="utf-8") as f:
             json.dump(batch_log, f, ensure_ascii=False, indent=2)
@@ -707,28 +736,70 @@ def analyze_products(
     bs = max(1, min(req_bs, BATCH_SIZE))
     total_batches = (len(uncached_items) + bs - 1) // bs
+    batch_jobs: List[Tuple[int, List[Tuple[int, Dict[str, str]]], List[Dict[str, str]]]] = []
     for i in range(0, len(uncached_items), bs):
         batch_num = i // bs + 1
         batch_slice = uncached_items[i : i + bs]
         batch = [item for _, item in batch_slice]
+        batch_jobs.append((batch_num, batch_slice, batch))
+
+    # 只有一个批次时走串行，减少线程池创建开销与日志/日志文件的不可控交织
+    if total_batches <= 1 or CONTENT_UNDERSTANDING_MAX_WORKERS <= 1:
+        for batch_num, batch_slice, batch in batch_jobs:
+            logger.info(
+                f"[analyze_products] Processing batch {batch_num}/{total_batches}, "
+                f"size={len(batch)}, target_lang={target_lang}"
+            )
+            batch_results = process_batch(batch, batch_num=batch_num, target_lang=target_lang)
+
+            for (original_idx, product), item in zip(batch_slice, batch_results):
+                results_by_index[original_idx] = item
+                title_input = str(item.get("title_input") or "").strip()
+                if not title_input:
+                    continue
+                if item.get("error"):
+                    # 不缓存错误结果，避免放大临时故障
+                    continue
+                try:
+                    _set_cached_anchor_result(product, target_lang, item)
+                except Exception:
+                    # 已在内部记录 warning
+                    pass
+    else:
+        max_workers = min(CONTENT_UNDERSTANDING_MAX_WORKERS, len(batch_jobs))
         logger.info(
-            f"[analyze_products] Processing batch {batch_num}/{total_batches}, "
-            f"size={len(batch)}, target_lang={target_lang}"
+            "[analyze_products] Using ThreadPoolExecutor for uncached batches: "
+            "max_workers=%s, total_batches=%s, bs=%s, target_lang=%s",
+            max_workers,
+            total_batches,
+            bs,
+            target_lang,
         )
-        batch_results = process_batch(batch, batch_num=batch_num, target_lang=target_lang)
-        for (original_idx, product), item in zip(batch_slice, batch_results):
-            results_by_index[original_idx] = item
-            title_input = str(item.get("title_input") or "").strip()
-            if not title_input:
-                continue
-            if item.get("error"):
-                # 不缓存错误结果，避免放大临时故障
-                continue
-            try:
-                _set_cached_anchor_result(product, target_lang, item)
-            except Exception:
-                # 已在内部记录 warning
-                pass
+        # 只把“LLM 调用 + markdown 解析”放到线程里；Redis get/set 保持在主线程，避免并发写入带来额外风险。
+        # 注意：线程池是模块级单例，因此这里的 max_workers 主要用于日志语义（实际并发受单例池上限约束）。
+        executor = _get_content_understanding_executor()
+        future_by_batch_num: Dict[int, Any] = {}
+        for batch_num, _batch_slice, batch in batch_jobs:
+            future_by_batch_num[batch_num] = executor.submit(
+                process_batch, batch, batch_num=batch_num, target_lang=target_lang
+            )
+
+        # 按 batch_num 回填，确保输出稳定（results_by_index 是按原始 input index 映射的）
+        for batch_num, batch_slice, _batch in batch_jobs:
+            batch_results = future_by_batch_num[batch_num].result()
+            for (original_idx, product), item in zip(batch_slice, batch_results):
+                results_by_index[original_idx] = item
+                title_input = str(item.get("title_input") or "").strip()
+                if not title_input:
+                    continue
+                if item.get("error"):
+                    # 不缓存错误结果，避免放大临时故障
+                    continue
+                try:
+                    _set_cached_anchor_result(product, target_lang, item)
+                except Exception:
+                    # 已在内部记录 warning
+                    pass
     return [item for item in results_by_index if item is not None]
@@ -16,8 +16,7 @@ import json
 # Add parent directory to path
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from config import ConfigLoader
-from config.env_config import ES_CONFIG
+from config import get_app_config
 from utils import ESClient
 from search import Searcher
 from suggestion import SuggestionIndexBuilder
@@ -61,8 +60,7 @@ def cmd_serve_indexer(args):
 def cmd_search(args):
     """Test search from command line."""
     # Load config
-    config_loader = ConfigLoader("config/config.yaml")
-    config = config_loader.load_config()
+    config = get_app_config().search
     # Initialize ES and searcher
     es_client = ESClient(hosts=[args.es_host])
@@ -106,8 +104,9 @@ def cmd_search(args):
 def cmd_build_suggestions(args):
     """Build/update suggestion index for a tenant."""
     # Initialize ES client with optional authentication
-    es_username = os.getenv("ES_USERNAME") or ES_CONFIG.get("username")
-    es_password = os.getenv("ES_PASSWORD") or ES_CONFIG.get("password")
+    es_cfg = get_app_config().infrastructure.elasticsearch
+    es_username = es_cfg.username
+    es_password = es_cfg.password
     if es_username and es_password:
         es_client = ESClient(hosts=[args.es_host], username=es_username, password=es_password)
     else:
@@ -117,11 +116,12 @@ def cmd_build_suggestions(args):
         return 1
     # Build DB config directly from environment to avoid dotenv dependency
-    db_host = os.getenv("DB_HOST")
-    db_port = int(os.getenv("DB_PORT", "3306"))
-    db_name = os.getenv("DB_DATABASE")
-    db_user = os.getenv("DB_USERNAME")
-    db_pass = os.getenv("DB_PASSWORD")
+    db_cfg = get_app_config().infrastructure.database
+    db_host = db_cfg.host
+    db_port = db_cfg.port
+    db_name = db_cfg.database
+    db_user = db_cfg.username
+    db_pass = db_cfg.password
     if not all([db_host, db_name, db_user, db_pass]):
         print("ERROR: DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD must be set in environment")
         return 1
@@ -170,7 +170,7 @@ def main():
     serve_parser = subparsers.add_parser('serve', help='Start API service (multi-tenant)')
     serve_parser.add_argument('--host', default='0.0.0.0', help='Host to bind to')
     serve_parser.add_argument('--port', type=int, default=6002, help='Port to bind to')
-    serve_parser.add_argument('--es-host', default=ES_CONFIG.get('host', 'http://localhost:9200'), help='Elasticsearch host')
+    serve_parser.add_argument('--es-host', default=get_app_config().infrastructure.elasticsearch.host, help='Elasticsearch host')
     serve_parser.add_argument('--reload', action='store_true', help='Enable auto-reload')
     # Serve-indexer command
@@ -180,14 +180,14 @@ def main():
     )
     serve_indexer_parser.add_argument('--host', default='0.0.0.0', help='Host to bind to')
     serve_indexer_parser.add_argument('--port', type=int, default=6004, help='Port to bind to')
-    serve_indexer_parser.add_argument('--es-host', default=ES_CONFIG.get('host', 'http://localhost:9200'), help='Elasticsearch host')
+    serve_indexer_parser.add_argument('--es-host', default=get_app_config().infrastructure.elasticsearch.host, help='Elasticsearch host')
     serve_indexer_parser.add_argument('--reload', action='store_true', help='Enable auto-reload')
     # Search command
     search_parser = subparsers.add_parser('search', help='Test search from command line')
     search_parser.add_argument('query', help='Search query')
     search_parser.add_argument('--tenant-id', required=True, help='Tenant ID (required)')
-    search_parser.add_argument('--es-host', default=ES_CONFIG.get('host', 'http://localhost:9200'), help='Elasticsearch host')
+    search_parser.add_argument('--es-host', default=get_app_config().infrastructure.elasticsearch.host, help='Elasticsearch host')
     search_parser.add_argument('--size', type=int, default=10, help='Number of results')
     search_parser.add_argument('--no-translation', action='store_true', help='Disable translation')
     search_parser.add_argument('--no-embedding', action='store_true', help='Disable embeddings')
@@ -199,7 +199,7 @@ def main():
         help='Build tenant suggestion index (full/incremental)'
     )
     suggest_build_parser.add_argument('--tenant-id', required=True, help='Tenant ID')
-    suggest_build_parser.add_argument('--es-host', default=ES_CONFIG.get('host', 'http://localhost:9200'), help='Elasticsearch host')
+    suggest_build_parser.add_argument('--es-host', default=get_app_config().infrastructure.elasticsearch.host, help='Elasticsearch host')
     suggest_build_parser.add_argument(
         '--mode',
         choices=['full', 'incremental'],
@@ -336,13 +336,13 @@ class QueryParser:
         translations = {}
         translation_futures = {}
         translation_executor = None
-        index_langs = ["en", "zh"]
+        index_langs: List[str] = []
         try:
             # 根据租户配置的 index_languages 决定翻译目标语言
             from config.tenant_config_loader import get_tenant_config_loader
             tenant_loader = get_tenant_config_loader()
             tenant_cfg = tenant_loader.get_tenant_config(tenant_id or "default")
-            raw_index_langs = tenant_cfg.get("index_languages") or ["en", "zh"]
+            raw_index_langs = tenant_cfg.get("index_languages") or []
             index_langs = []
             seen_langs = set()
             for lang in raw_index_langs:
@@ -618,17 +618,3 @@ class QueryParser:
                 queries.append(translation)
         return queries
-
-    def update_rewrite_rules(self, rules: Dict[str, str]) -> None:
-        """
-        Update query rewrite rules.
-
-        Args:
-            rules: Dictionary of pattern -> replacement mappings
-        """
-        for pattern, replacement in rules.items():
-            self.rewriter.add_rule(pattern, replacement)
-
-    def get_rewrite_rules(self) -> Dict[str, str]:
-        """Get current rewrite rules."""
-        return self.rewriter.get_rules()
@@ -63,43 +63,19 @@ class DashScopeRerankBackend:
       - max_retries: int, default 1
       - retry_backoff_sec: float, default 0.2
-    Env overrides:
-      - RERANK_DASHSCOPE_ENDPOINT
-      - RERANK_DASHSCOPE_MODEL
-      - RERANK_DASHSCOPE_TIMEOUT_SEC
-      - RERANK_DASHSCOPE_TOP_N_CAP
-      - RERANK_DASHSCOPE_BATCHSIZE
     """
     def __init__(self, config: Dict[str, Any]) -> None:
         self._config = config or {}
-        self._model_name = str(
-            os.getenv("RERANK_DASHSCOPE_MODEL")
-            or self._config.get("model_name")
-            or "qwen3-rerank"
-        )
+        self._model_name = str(self._config.get("model_name") or "qwen3-rerank")
         self._endpoint = str(
-            os.getenv("RERANK_DASHSCOPE_ENDPOINT")
-            or self._config.get("endpoint")
-            or "https://dashscope.aliyuncs.com/compatible-api/v1/reranks"
+            self._config.get("endpoint") or "https://dashscope.aliyuncs.com/compatible-api/v1/reranks"
         ).strip()
         self._api_key_env = str(self._config.get("api_key_env") or "").strip()
         self._api_key = str(os.getenv(self._api_key_env) or "").strip().strip('"').strip("'")
-        self._timeout_sec = float(
-            os.getenv("RERANK_DASHSCOPE_TIMEOUT_SEC")
-            or self._config.get("timeout_sec")
-            or 15.0
-        )
-        self._top_n_cap = int(
-            os.getenv("RERANK_DASHSCOPE_TOP_N_CAP")
-            or self._config.get("top_n_cap")
-            or 0
-        )
-        self._batchsize = int(
-            os.getenv("RERANK_DASHSCOPE_BATCHSIZE")
-            or self._config.get("batchsize")
-            or 0
-        )
+        self._timeout_sec = float(self._config.get("timeout_sec") or 15.0)
+        self._top_n_cap = int(self._config.get("top_n_cap") or 0)
+        self._batchsize = int(self._config.get("batchsize") or 0)
         self._instruct = str(self._config.get("instruct") or "").strip()
         self._max_retries = int(self._config.get("max_retries", 1))
         self._retry_backoff_sec = float(self._config.get("retry_backoff_sec", 0.2))
-"""Reranker service configuration (simple Python config)."""
+"""Reranker service compatibility config derived from unified app config."""
-import os
+from __future__ import annotations
+
+from config.loader import get_app_config
 class RerankerConfig(object):
-    # Server
-    HOST = os.getenv("RERANKER_HOST", "0.0.0.0")
-    PORT = int(os.getenv("RERANKER_PORT", 6007))
-
-    # Model
-    MODEL_NAME = "Qwen/Qwen3-Reranker-0.6B"
-    DEVICE = None  # None -> auto (cuda if available)
-    USE_FP16 = True
-    BATCH_SIZE = 64
-    MAX_LENGTH = 512
-    CACHE_DIR = "./model_cache"
-    ENABLE_WARMUP = True
-
-    # Request limits
-    MAX_DOCS = 1000
-
-    # Output
-    NORMALIZE = True
+    def __init__(self) -> None:
+        app_config = get_app_config()
+        runtime = app_config.runtime
+        service = app_config.services.rerank
+        backend = service.get_backend_config()
+        request = service.request
+
+        self.HOST = runtime.reranker_host
+        self.PORT = runtime.reranker_port
+
+        self.MODEL_NAME = str(backend.get("model_name") or "Qwen/Qwen3-Reranker-0.6B")
+        self.DEVICE = backend.get("device")
+        self.USE_FP16 = bool(backend.get("use_fp16", True))
+        self.BATCH_SIZE = int(backend.get("batch_size", backend.get("infer_batch_size", 64)))
+        self.MAX_LENGTH = int(backend.get("max_length", 512))
+        self.CACHE_DIR = str(backend.get("cache_dir") or "./model_cache")
+        self.ENABLE_WARMUP = bool(backend.get("enable_warmup", True))
+
+        self.MAX_DOCS = int(request.get("max_docs", 1000))
+        self.NORMALIZE = bool(request.get("normalize", True))
 CONFIG = RerankerConfig()
@@ -18,7 +18,7 @@ from typing import Any, Dict, Iterator, List, Optional, Tuple
 from sqlalchemy import text
-from config.env_config import ES_INDEX_NAMESPACE
+from config.loader import get_app_config
 from config.tenant_config_loader import get_tenant_config_loader
 from suggestion.mapping import build_suggestion_mapping
 from utils.es_client import ESClient
@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 def _index_prefix() -> str:
-    return ES_INDEX_NAMESPACE or ""
+    return get_app_config().runtime.index_namespace or ""
 def get_suggestion_alias_name(tenant_id: str) -> str:
@@ -45,7 +45,8 @@ def test_analyze_products_caps_batch_size_to_20(monkeypatch):
     )
     assert len(out) == 45
-    assert seen_batch_sizes == [20, 20, 5]
+    # 并发执行时 batch 调用顺序可能变化，因此校验“批大小集合”而不是严格顺序
+    assert sorted(seen_batch_sizes) == [5, 20, 20]
 def test_analyze_products_uses_min_batch_size_1(monkeypatch):
@@ -3,7 +3,6 @@
 from __future__ import annotations
 import logging
-import os
 import re
 from typing import List, Optional, Sequence, Tuple, Union
@@ -24,7 +23,7 @@ class DeepLTranslationBackend:
         timeout: float,
         glossary_id: Optional[str] = None,
     ) -> None:
-        self.api_key = api_key or os.getenv("DEEPL_AUTH_KEY")
+        self.api_key = api_key
         self.api_url = api_url
         self.timeout = float(timeout)
         self.glossary_id = glossary_id
@@ -3,13 +3,11 @@
 from __future__ import annotations
 import logging
-import os
 import time
 from typing import List, Optional, Sequence, Union
 from openai import OpenAI
-from config.env_config import DASHSCOPE_API_KEY
 from translation.languages import LANGUAGE_LABELS
 from translation.prompts import TRANSLATION_PROMPTS
 from translation.scenes import normalize_scene_name
@@ -52,11 +50,13 @@ class LLMTranslationBackend:
         model: str,
         timeout_sec: float,
         base_url: str,
+        api_key: Optional[str],
     ) -> None:
         self.capability_name = capability_name
         self.model = model
         self.timeout_sec = float(timeout_sec)
         self.base_url = base_url
+        self.api_key = api_key
         self.client = self._create_client()
     @property
@@ -64,12 +64,11 @@ class LLMTranslationBackend:
         return True
     def _create_client(self) -> Optional[OpenAI]:
-        api_key = DASHSCOPE_API_KEY or os.getenv("DASHSCOPE_API_KEY")
-        if not api_key:
+        if not self.api_key:
             logger.warning("DASHSCOPE_API_KEY not set; llm translation unavailable")
             return None
         try:
-            return OpenAI(api_key=api_key, base_url=self.base_url)
+            return OpenAI(api_key=self.api_key, base_url=self.base_url)
         except Exception as exc:
             logger.error("Failed to initialize llm translation client: %s", exc, exc_info=True)
             return None
@@ -3,14 +3,12 @@
 from __future__ import annotations
 import logging
-import os
 import re
 import time
 from typing import List, Optional, Sequence, Union
 from openai import OpenAI
-from config.env_config import DASHSCOPE_API_KEY
 from translation.languages import QWEN_LANGUAGE_CODES
 logger = logging.getLogger(__name__)
@@ -64,7 +62,7 @@ class QwenMTTranslationBackend:
     @staticmethod
     def _default_api_key(model: str) -> Optional[str]:
         del model
-        return DASHSCOPE_API_KEY or os.getenv("DASHSCOPE_API_KEY")
+        return None
     def translate(
         self,
@@ -6,9 +6,12 @@ import hashlib
 import logging
 from typing import Mapping, Optional
-import redis
+try:
+    import redis
+except ImportError:  # pragma: no cover - runtime fallback for minimal envs
+    redis = None  # type: ignore[assignment]
-from config.env_config import REDIS_CONFIG
+from config.loader import get_app_config
 logger = logging.getLogger(__name__)
@@ -70,15 +73,19 @@ class TranslationCache:
     @staticmethod
     def _init_redis_client() -> Optional[redis.Redis]:
+        if redis is None:
+            logger.warning("redis package is not installed; translation cache disabled")
+            return None
+        redis_config = get_app_config().infrastructure.redis
         try:
             client = redis.Redis(
-                host=REDIS_CONFIG.get("host", "localhost"),
-                port=REDIS_CONFIG.get("port", 6479),
-                password=REDIS_CONFIG.get("password"),
+                host=redis_config.host,
+                port=redis_config.port,
+                password=redis_config.password,
                 decode_responses=True,
-                socket_timeout=REDIS_CONFIG.get("socket_timeout", 1),
-                socket_connect_timeout=REDIS_CONFIG.get("socket_connect_timeout", 1),
-                retry_on_timeout=REDIS_CONFIG.get("retry_on_timeout", False),
+                socket_timeout=redis_config.socket_timeout,
+                socket_connect_timeout=redis_config.socket_connect_timeout,
+                retry_on_timeout=redis_config.retry_on_timeout,
                 health_check_interval=10,
             )
             client.ping()
@@ -7,7 +7,7 @@ from typing import List, Optional, Sequence, Union
 import requests
-from config.services_config import get_translation_config
+from config.loader import get_app_config
 from translation.settings import normalize_translation_model, normalize_translation_scene
 logger = logging.getLogger(__name__)
@@ -24,7 +24,7 @@ class TranslationServiceClient:
         default_scene: Optional[str] = None,
         timeout_sec: Optional[float] = None,
     ) -> None:
-        cfg = get_translation_config()
+        cfg = get_app_config().services.translation.as_dict()
         self.base_url = str(base_url or cfg["service_url"]).rstrip("/")
         self.default_model = normalize_translation_model(cfg, default_model or cfg["default_model"])
         self.default_scene = normalize_translation_scene(cfg, default_scene or cfg["default_scene"])
@@ -5,7 +5,8 @@ from __future__ import annotations
 import logging
 from typing import Dict, List, Optional
-from config.services_config import get_translation_config
+from config.loader import get_app_config
+from config.schema import AppConfig
 from translation.cache import TranslationCache
 from translation.protocols import TranslateInput, TranslateOutput, TranslationBackendProtocol
 from translation.settings import (
@@ -22,8 +23,9 @@ logger = logging.getLogger(__name__)
 class TranslationService:
     """Owns translation backends and routes calls by model and scene."""
-    def __init__(self, config: Optional[TranslationConfig] = None) -> None:
-        self.config = config or get_translation_config()
+    def __init__(self, config: Optional[TranslationConfig] = None, app_config: Optional[AppConfig] = None) -> None:
+        self._app_config = app_config or get_app_config()
+        self.config = config or self._app_config.services.translation.as_dict()
         self._enabled_capabilities = self._collect_enabled_capabilities()
         if not self._enabled_capabilities:
             raise ValueError("No enabled translation backends found in services.translation.capabilities")
@@ -85,7 +87,7 @@ class TranslationService:
             capability_name=name,
             model=str(cfg["model"]).strip(),
             base_url=str(cfg["base_url"]).strip(),
-            api_key=cfg.get("api_key"),
+            api_key=self._app_config.infrastructure.secrets.dashscope_api_key,
             timeout=int(cfg["timeout_sec"]),
             glossary_id=cfg.get("glossary_id"),
         )
@@ -94,7 +96,7 @@ class TranslationService:
         from translation.backends.deepl import DeepLTranslationBackend
         return DeepLTranslationBackend(
-            api_key=cfg.get("api_key"),
+            api_key=self._app_config.infrastructure.secrets.deepl_auth_key,
             api_url=str(cfg["api_url"]).strip(),
             timeout=float(cfg["timeout_sec"]),
             glossary_id=cfg.get("glossary_id"),
@@ -108,6 +110,7 @@ class TranslationService:
             model=str(cfg["model"]).strip(),
             timeout_sec=float(cfg["timeout_sec"]),
             base_url=str(cfg["base_url"]).strip(),
+            api_key=self._app_config.infrastructure.secrets.dashscope_api_key,
         )
     def _create_local_nllb_backend(self, *, name: str, cfg: Dict[str, object]) -> TranslationBackendProtocol:
@@ -5,10 +5,9 @@ Elasticsearch client wrapper.
 from elasticsearch import Elasticsearch
 from elasticsearch.helpers import bulk
 from typing import Dict, Any, List, Optional
-import os
 import logging
-from config.env_config import ES_CONFIG
+from config.loader import get_app_config
 logger = logging.getLogger(__name__)
@@ -33,7 +32,7 @@ class ESClient:
             **kwargs: Additional ES client parameters
         """
         if hosts is None:
-            hosts = [os.getenv('ES_HOST', 'http://localhost:9200')]
+            hosts = [get_app_config().infrastructure.elasticsearch.host]
         # Build client config
         client_config = {
@@ -325,16 +324,9 @@ def get_es_client_from_env() -&gt; ESClient:
     Returns:
         ESClient instance
     """
-    if ES_CONFIG:
-        return ESClient(
-            hosts=[ES_CONFIG['host']],
-            username=ES_CONFIG.get('username'),
-            password=ES_CONFIG.get('password')
-        )
-    else:
-        # Fallback to env variables
-        return ESClient(
-            hosts=[os.getenv('ES_HOST', 'http://localhost:9200')],
-            username=os.getenv('ES_USERNAME'),
-            password=os.getenv('ES_PASSWORD')
-        )
+    cfg = get_app_config().infrastructure.elasticsearch
+    return ESClient(
+        hosts=[cfg.host],
+        username=cfg.username,
+        password=cfg.password,
+    )