78 lines
2.3 KiB
Markdown
78 lines
2.3 KiB
Markdown
# integration（技术计划）
|
||
|
||
## 1. 计划目标
|
||
|
||
实现对外统一入口 `wrapText()`（纯函数风格），把已完成的子模块串成可复用算法模块，供 Home（APP）与 Widget（WIDGET）调用：
|
||
|
||
- 参数口径统一：`lang/context/availableWidth/maxLines/overflowMode/lineMode/configVersion/debug`
|
||
- 输出统一：`lines[]/wrappedText/meta`，且 meta 可用于治理与 UI 兜底
|
||
- 当 `meta.fallback_type=SYSTEM_DEFAULT` 时，UI 可选择交给系统排版（算法层仅标记，不擅自改变 UI 行为）
|
||
|
||
## 2. 入口签名（与大 spec 对齐）
|
||
|
||
实现并导出：
|
||
|
||
```ts
|
||
wrapText({
|
||
text,
|
||
lang,
|
||
availableWidth,
|
||
maxLines,
|
||
context,
|
||
fontSpec?,
|
||
overflowMode?,
|
||
lineMode?,
|
||
constraints?,
|
||
configVersion?,
|
||
debug?
|
||
}) => { lines, wrappedText, meta }
|
||
```
|
||
|
||
## 3. 组装流程（按执行顺序）
|
||
|
||
1. **normalizeWhitespace**（core-contract）
|
||
2. **tokenize**
|
||
- EN：tokenizeEN
|
||
- TC：segmentGraphemes → Token[]
|
||
3. **breakpoint-candidates**
|
||
- generateBreakpoints（传入 constraints.forbiddenBreakRanges）
|
||
4. **search**
|
||
- APP：searchBestLayoutApp（DP+TopK，测量优先）
|
||
- WIDGET：searchBestLayoutWidget（Beam，默认 APPROX；可选 MEASURE）
|
||
5. **overflow-fallback**
|
||
- 当搜索失败或未覆盖到 N：按 overflowMode 执行（ELLIPSIS/CLIP/SYSTEM_DEFAULT）
|
||
6. **meta 汇总**
|
||
- breaks（若可得）
|
||
- scoreTopTerms（debug=true 时）
|
||
- fallback_type/overflow_type/reason
|
||
- configVersion
|
||
|
||
## 4. 默认值与映射（固定，确定性）
|
||
|
||
- `overflowMode`：
|
||
- APP 默认 `CLIP`
|
||
- WIDGET 默认 `ELLIPSIS`
|
||
- `lineMode`：默认 `AUTO`
|
||
- `configVersion`：默认 `'v1'`（若调用方未传）
|
||
- WIDGET widthMode：默认 `APPROX`
|
||
|
||
## 5. 代码落位（客户端）
|
||
|
||
- `client/src/features/textWrap/`
|
||
- `wrapText.ts`（入口实现）
|
||
- `types.ts`（对外输入/输出类型）
|
||
- `index.ts`（统一导出）
|
||
|
||
## 6. 测试与回归
|
||
|
||
- 将 `golden-tests` 的测试入口从测试 harness 切换为正式 `wrapText()`（期望不变）
|
||
- 增加 1 个 integration 单测：验证 `SYSTEM_DEFAULT` meta 语义不变
|
||
|
||
## 7. 完成定义（DoD）
|
||
|
||
- `wrapText()` 可在 APP/WIDGET 两种 context 下运行
|
||
- 输出 meta 字段可用于 UI 治理与回溯（含 configVersion）
|
||
- 全量 `npm test` 与 `tsc --noEmit` 通过
|
||
- overview 更新记录变更文件
|
||
|