# search-engine-app（子模块规范）

## 子模块名称

search-engine-app（APP 搜索器：DP + TopK）

## 目标描述

在 APP 场景实现多行换行的确定性组合搜索：

- 使用 DP + TopK 生成候选 layout
- 对每个候选应用硬约束过滤
- 调用 `scoring-tiebreak` 计算评分与 tieKey
- 保留 TopK 并在结束时选最优

要求性能可控且输出完全确定性。

## 输入/输出定义

### 输入

- `tokens: Token[]`
- `breakpoints: Breakpoint[]`（来自 `breakpoint-candidates`）
- `availableWidth: number`
- `maxLines: number`
- `lineMode: 'AUTO' | 'FIXED'`
- `context: 'APP'`
- `measure: { measureWidth?: fn; fontSpec?: any; cache: ... }`（来自 `width-measurement` 的实现）
- `config: { topK: number }`

### 输出

- `bestLayout: { breaks: number[]; lines: string[]; wrappedText: string; meta?: { breaks: number[]; scoreTopTerms?: ... } }`
- 若无解：返回可解释的 fallback（由 `overflow-fallback` 统一处理语义）

## 验收标准（可验证）

- **确定性**：同输入（tokens/breakpoints/availableWidth/maxLines/configVersion）必定同输出（breaks 与 lines 完全一致）
- **TopK 维护一致**：
  - K 默认 10（可配置但必须固定）
  - 排序：score desc；tieKey 逐项比较
  - 去重：同 breaks 序列只保留最高分
- **lineMode=FIXED 行为**：
  - 优先选刚好 `maxLines` 的解；无解时按固定降级链路处理并打点
- **复杂度可控**：超长输入触发裁剪/兜底并返回 reason（如 `TOO_LONG`）

## 依赖与关联

- **依赖**：`core-contract`、`width-measurement`、`breakpoint-candidates`、`scoring-tiebreak`、`overflow-fallback`
- **被依赖**：`integration`、`golden-tests`