110 lines
3.9 KiB
Markdown
110 lines
3.9 KiB
Markdown
# Text Wrap（大需求总览）
|
||
|
||
> 本文件只保留高层背景、总览与模块拆分；各子模块可独立实现与验收。
|
||
> 详细算法口径以 `设计说明文档/文档换行算法.md`（v1.2.1）为准。
|
||
|
||
## 1. Overview（背景/目标/非目标）
|
||
|
||
Home 页面与 iOS 桌面小组件（Widget）都会展示“情绪文案/正念短句”。若依赖系统默认换行，会出现不可控、不可解释、跨端不一致的问题。
|
||
|
||
本需求要求把“文案换行算法”从 UI 组件中**独立成一个可复用模块**，用于：
|
||
|
||
- Home 页面文案渲染
|
||
- Widget 文案渲染（允许测量能力不同，但规则与决策必须一致）
|
||
|
||
### 目标
|
||
|
||
- **确定性**：同输入（含配置版本）必定同输出
|
||
- **跨端一致口径**：索引体系、断点定义、关键词命中与 tie-break 规则完全一致
|
||
- **可治理**：支持 debug meta、线上打点、Golden Case 回归
|
||
- **可复用**：算法作为纯函数核心，UI 仅消费 `lines[]/wrappedText/meta`
|
||
|
||
### 非目标
|
||
|
||
- 不做语义理解/情绪识别/机器学习
|
||
- 不做通用排版引擎
|
||
- 不承诺 Widget 场景做到像 App 一样的像素级测量（Widget 可使用估算/常量）
|
||
|
||
## 2. 对外接口（统一口径）
|
||
|
||
模块对外暴露 `wrapText()`（纯函数）：
|
||
|
||
```ts
|
||
wrapText({
|
||
text: string,
|
||
lang: 'TC' | 'EN',
|
||
availableWidth: number,
|
||
maxLines: number,
|
||
context: 'APP' | 'WIDGET',
|
||
fontSpec?: { fontSize: number; fontWeight?: string; fontFamily?: string },
|
||
overflowMode?: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT',
|
||
lineMode?: 'AUTO' | 'FIXED',
|
||
constraints?: {
|
||
protectedPhrases?: string[];
|
||
forbiddenBreakRanges?: Array<{ start: number; end: number }>;
|
||
},
|
||
configVersion?: string,
|
||
debug?: boolean
|
||
}) => {
|
||
lines: string[];
|
||
wrappedText: string;
|
||
meta?: {
|
||
configVersion?: string;
|
||
fallback_type?: 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT';
|
||
overflow_type?: 'NONE' | 'ELLIPSIS' | 'CLIP';
|
||
reason?: 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'WIDOW' | 'PARTICLE' | 'TOO_LONG';
|
||
breaks?: number[];
|
||
scoreTopTerms?: Array<{ key: string; delta: number; detail?: any }>;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3. 模块拆分（modules）与依赖关系
|
||
|
||
### 3.1 `modules/` 目录结构
|
||
|
||
```text
|
||
spec_kit/Text Wrap/
|
||
├ spec.md
|
||
└ modules/
|
||
├ core-contract/spec.md
|
||
├ grapheme-segmentation/spec.md
|
||
├ width-measurement/spec.md
|
||
├ breakpoint-candidates/spec.md
|
||
├ scoring-tiebreak/spec.md
|
||
├ search-engine-app/spec.md
|
||
├ search-engine-widget/spec.md
|
||
├ overflow-fallback/spec.md
|
||
├ golden-tests/spec.md
|
||
└ integration/spec.md
|
||
```
|
||
|
||
### 3.2 模块职责概览
|
||
|
||
- **`core-contract`**：EN/TC token 索引体系、文本重组、EN 关键词命中“全词等值”、配置/版本化与确定性比较口径 ✅
|
||
- **`grapheme-segmentation`**：TC 字符簇分割的推荐实现与无库兜底 + 回归样例 ✅
|
||
- **`width-measurement`**：测量接口、缓存、宽度不可用降级（approx mode）与打点 ✅
|
||
- **`breakpoint-candidates`**：候选断点生成（PUNCT/SPACE/BALANCE）、去重排序、约束过滤与规模上限 ✅
|
||
- **`scoring-tiebreak`**：评分项顺序、可解释 breakdown、tieKey/tie-break 规则与整数分/EPS ✅
|
||
- **`search-engine-app`**：APP 场景 DP + TopK 的确定性实现
|
||
- **`search-engine-widget`**：WIDGET 场景 Beam Search 的确定性实现
|
||
- **`overflow-fallback`**：ELLIPSIS/CLIP/SYSTEM_DEFAULT 语义、ellipsis 细则与兜底链路
|
||
- **`golden-tests`**：Golden Cases 与性质测试（确定性、近似单调性、maxLines 不变差）
|
||
- **`integration`**：Home/Widget 接入约定（参数映射、渲染策略、fallback 语义对齐）
|
||
|
||
## 4. 实现顺序（推荐）
|
||
|
||
> 目标是“先锁口径，再做搜索与评分，再做溢出与回归”，避免后期重构。
|
||
|
||
1. `core-contract`
|
||
2. `grapheme-segmentation`
|
||
3. `width-measurement`
|
||
4. `breakpoint-candidates`
|
||
5. `scoring-tiebreak`
|
||
6. `search-engine-app`
|
||
7. `search-engine-widget`
|
||
8. `overflow-fallback`
|
||
9. `golden-tests`
|
||
10. `integration`
|
||
|