# Suggestion 模块说明（统一入口）

本文档是 suggestion 模块的统一入口，遵循 `docs/DEVELOPER_GUIDE.md` 的“单一入口、避免分叉”原则。

## 1. 当前状态（Phase 2）

- 仅保留 Suggest 自动补全能力
- 不支持结果直达（`with_results` / `result_size` / `products[]` 已移除）
- 索引采用版本化发布：
  - 物理索引：`{ES_INDEX_NAMESPACE}search_suggestions_tenant_{tenant_id}_v<timestamp>`
  - 读别名：`{ES_INDEX_NAMESPACE}search_suggestions_tenant_{tenant_id}_current`
- 支持增量更新（watermark + overlap）

## 2. 文档导航（唯一推荐顺序）

1. `ARCHITECTURE_V2.md`：架构与设计原则
2. `RUNBOOK.md`：构建/发布/验证流程
3. `TROUBLESHOOTING.md`：常见问题排查

## 3. 命令入口

- 全量或增量构建：

```bash
./scripts/build_suggestions.sh <tenant_id> --mode full
./scripts/build_suggestions.sh <tenant_id> --mode incremental
```

- 一键重建 + 验证：

```bash
./scripts/rebuild_suggestions.sh <tenant_id>
```

## 4. API 约定（简版）

- 端点：`GET /search/suggestions`
- 参数：`q`, `size`, `language`
- Header：`X-Tenant-ID`

示例：

```bash
curl "http://localhost:6002/search/suggestions?q=shi&size=10&language=en" \
  -H "X-Tenant-ID: 162"
```