更新换行算法和APP-PUSH

2026-02-10 11:39:33 +08:00
parent f03d36b5e9
commit ee2d9f44ea
105 changed files with 9967 additions and 233 deletions
--- a/Wrap/modules/integration/plan.md
+++ b/Wrap/modules/integration/plan.md
@@ -0,0 +1,77 @@
+# 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 更新记录变更文件
+
--- a/Wrap/modules/integration/spec.md
+++ b/Wrap/modules/integration/spec.md
@@ -0,0 +1,52 @@
+# integration（子模块规范）
+
+## 子模块名称
+
+integration（Home / Widget 接入）
+
+## 目标描述
+
+把 `wrapText()` 模块以一致参数口径接入到两端渲染链路中，并定义 UI 侧对 meta 的处理规则，确保：
+
+- Home 与 Widget 使用同一套配置/词库/版本号（`configVersion`）
+- 同场景下输出一致；不同测量能力导致差异时“可解释且可治理”
+- SYSTEM_DEFAULT 的语义不被 UI 误用
+
+## 输入/输出定义
+
+### 输入
+
+- Home（APP）侧输入：
+  - `text/lang/availableWidth/maxLines/fontSpec/context='APP'`
+  - 可选：`constraints/overflowMode/lineMode/configVersion/debug`
+- Widget（WIDGET）侧输入：
+  - `text/lang/availableWidth(profile)/maxLines/context='WIDGET'`
+  - 可选：`constraints/overflowMode/configVersion/debug`
+
+### 输出
+
+- UI 渲染消费：
+  - `lines[]`：逐行渲染或插入 `\n`
+  - `wrappedText`：用于一次性渲染或日志/缓存
+  - `meta`：用于调试、打点、兜底策略选择
+
+## 验收标准（可验证）
+
+- **参数映射一致**：
+  - 两端对 `lang/context/availableWidth/maxLines/overflowMode/lineMode` 的默认值与映射一致
+  - `configVersion` 必须随结果一起回传到 meta 或打点
+- **UI 兜底语义正确**：
+  - 当 `meta.fallback_type=SYSTEM_DEFAULT` 时：
+    - UI 允许选择“交给系统排版”（例如不插入 `\n` 或忽略 `lines[]`）
+    - 但不改变算法层返回值
+- **缓存与复用**：
+  - Home 可对同文案同参数缓存 `wrappedText/lines/breaks`
+  - Widget 可对固定 profile 文案缓存结果（避免频繁计算）
+- **回归可对齐**：
+  - Golden Cases 在 Home 与 Widget（固定 profile）下可跑通并对齐预期
+
+## 依赖与关联
+
+- **依赖**：全部核心模块（`core-contract`、`breakpoint-candidates`、`search-engine-*`、`scoring-tiebreak`、`overflow-fallback`、`golden-tests`）
+- **被依赖**：无（最终落地层）
+
--- a/Wrap/modules/integration/tasks.md
+++ b/Wrap/modules/integration/tasks.md
@@ -0,0 +1,63 @@
+# integration（任务清单）
+
+> 目标：实现 `wrapText()` 统一入口并串联所有子模块，供 Home/Widget 使用。
+
+## 0. 对齐与准备
+
+- [x] 阅读并对齐口径
+  - [x] 阅读 `spec_kit/Text Wrap/modules/integration/spec.md`
+  - [x] 阅读 `spec_kit/Text Wrap/modules/integration/plan.md`
+  - [x] 阅读 `spec_kit/Text Wrap/spec.md` 的对外接口定义
+
+## 1. 对外类型定义
+
+- [x] 新建 `client/src/features/textWrap/types.ts`
+  - [x] 定义 `WrapTextInput`（与大 spec 对齐）
+  - [x] 定义 `WrapTextMeta`（包含 configVersion/fallback_type/overflow_type/reason/breaks/scoreTopTerms）
+  - [x] 定义 `WrapTextOutput`
+
+## 2. 实现 wrapText() 入口
+
+- [x] 新建 `client/src/features/textWrap/wrapText.ts`
+  - [x] normalizeWhitespace（固定策略 NORMALIZE）
+  - [x] tokenize：
+    - [x] EN：tokenizeEN
+    - [x] TC：segmentGraphemes → Token[]
+  - [x] generateBreakpoints（接入 forbiddenBreakRanges）
+  - [x] 组装 scoring 的 lexicons：
+    - [x] protectedPhrases 来自 constraints.protectedPhrases（若有）
+  - [x] 搜索：
+    - [x] APP：searchBestLayoutApp（测量 mockable；fontSpec 缺字段报错由 width-measurement 保证）
+    - [x] WIDGET：searchBestLayoutWidget（默认 APPROX；可选 MEASURE）
+  - [x] 搜索失败/未覆盖 N：
+    - [x] 调用 applyOverflowFallback（overflowMode 默认：APP=CLIP，WIDGET=ELLIPSIS）
+  - [x] 汇总输出 meta：
+    - [x] configVersion
+    - [x] breaks（若可得）
+    - [x] scoreTopTerms（debug=true）
+    - [x] fallback_type/overflow_type/reason
+
+## 3. 导出
+
+- [x] 新建 `client/src/features/textWrap/index.ts`
+  - [x] 导出 types 与 `wrapText`
+
+## 4. 调整 Golden Tests 入口
+
+- [x] 将 `client/src/features/textWrap/golden/__tests__/golden.test.ts` 从测试 harness 切换为 `wrapText()`
+  - [x] 保持现有 fixtures 期望不变
+
+## 5. 单测补充（最小）
+
+- [x] 新建 `client/src/features/textWrap/__tests__/wrapText.integration.test.ts`
+  - [x] SYSTEM_DEFAULT：meta.fallback_type=SYSTEM_DEFAULT 且仍返回 lines/wrappedText
+
+## 6. 收尾
+
+- [x] `npm test`
+- [x] `npx tsc --noEmit`
+- [x] 将本 `tasks.md` 全部勾选完成
+- [x] 更新 `spec_kit/overview.md`
+  - [x] 标记 `integration` 已完成（阶段性）
+  - [x] 写入变更文件清单
+