161 lines
6.2 KiB
Markdown
161 lines
6.2 KiB
Markdown
# width-measurement（任务清单）
|
||
|
||
> 对应计划：`spec_kit/Text Wrap/modules/width-measurement/plan.md`
|
||
>
|
||
> 状态含义：`[ ]` 未完成，`[x]` 已完成。
|
||
> 执行完本清单后，需要在 `spec_kit/overview.md` 的 `Text Wrap` 条目下补充“已完成编码/任务执行完毕”的标记（见最后一节）。
|
||
|
||
---
|
||
|
||
## 0. 任务标记规则
|
||
|
||
- 用勾选框标记执行状态：
|
||
- `[ ]` 未完成
|
||
- `[x]` 已完成
|
||
- 每个任务必须可独立验收（有明确产出与检查方式）。
|
||
- 所有代码注释必须为简体中文，并把“缓存 key / 降级语义 / 报错口径”写死，避免后续模块漂移。
|
||
|
||
---
|
||
|
||
## 1. 前置检查（依赖与约束确认）
|
||
|
||
- [x] 1.1 确认 `availableWidth` 由设备侧传入（本模块不内置 widgetProfiles）
|
||
- **验收**：在本模块实现中不引入任何固定宽度常量表；仅消费上层传入的宽度与 profile。
|
||
|
||
- [x] 1.2 确认 APP 测量方案采用成熟库（默认 `react-native-text-size`）
|
||
- **验收**：`client/package.json` 中存在该依赖（或团队等价成熟方案），并且测量封装函数仅依赖该库/注入点。
|
||
|
||
---
|
||
|
||
## 2. 依赖与目录骨架（客户端侧实现）
|
||
|
||
- [x] 2.1 新建目录 `client/src/features/textWrap/measure/`
|
||
- **产出**（建议文件）：
|
||
- `types.ts`（FontSpec/ContextProfile/MeasureResult）
|
||
- `errors.ts`（缺字段报错）
|
||
- `fontSpecKey.ts`
|
||
- `cache.ts`（两级缓存 + 上限）
|
||
- `measureWidthImpl.ts`（对接成熟测量库）
|
||
- `measureWidthCached.ts`
|
||
- `measureSliceWidthCached.ts`
|
||
- `__tests__/widthMeasurement.test.ts`
|
||
- `index.ts`（统一导出）
|
||
- **验收**：目录存在，TS 可正常 import（不报路径错误）。
|
||
|
||
- [x] 2.2 新增依赖 `react-native-text-size`（如项目未安装）
|
||
- **命令**（示例）：
|
||
- `cd client && npm install react-native-text-size`
|
||
- **验收**：
|
||
- 安装成功
|
||
- `npm test` 不受影响（后续任务再补充本模块测试）
|
||
|
||
---
|
||
|
||
## 3. fontSpec 强校验（缺失直接报错）
|
||
|
||
- [x] 3.1 定义 `FontSpec` 类型（必须字段：`fontSize/fontFamily/fontWeight`）
|
||
- **验收**：类型层面可表达“必填字段”，并在运行时也做校验。
|
||
|
||
- [x] 3.2 实现运行时校验与错误（简体中文）
|
||
- **要求**：
|
||
- 缺失任一字段直接抛错
|
||
- 错误信息包含：缺失字段名 + 建议调用方补齐的位置（例如 `wrapText({ fontSpec: ... })`）
|
||
- 禁止隐式默认值
|
||
- **验收**：单测断言会抛错且错误信息包含缺失字段名。
|
||
|
||
---
|
||
|
||
## 4. fontSpecKey 与 contextProfile（确定性 key 体系）
|
||
|
||
- [x] 4.1 实现 `buildFontSpecKey(fontSpec)`
|
||
- **规则**：`fontFamily|fontWeight|fontSize`（顺序固定）
|
||
- **验收**：同输入同输出；fontSize 非有限数时报错。
|
||
|
||
- [x] 4.2 定义 `contextProfile` 拼接规则并实现 helper
|
||
- **要求**：
|
||
- APP：`APP|<platform>|<scale?>`（字段顺序固定）
|
||
- WIDGET：`WIDGET|<widgetSize?>`（无 widgetSize 时为 `WIDGET`）
|
||
- **验收**：输出字符串稳定；不同 profile 必须产生不同缓存 key。
|
||
|
||
---
|
||
|
||
## 5. 两级缓存（有上限 + 确定性）
|
||
|
||
- [x] 5.1 实现缓存容器（模块级常驻）
|
||
- **要求**：
|
||
- 字符串测量缓存（textKey）
|
||
- 切片测量缓存（sliceKey）
|
||
- 容量上限策略：LRU 优先；若不引入依赖，先 Map + 超限清空（并预留打点钩子）
|
||
- **验收**：单测可验证缓存命中会减少底层测量调用次数。
|
||
|
||
- [x] 5.2 定义 key 生成规则并实现
|
||
- **规则**：
|
||
- `textKey = <contextProfile>|<fontSpecKey>|<text>`
|
||
- `sliceKey = <contextProfile>|<fontSpecKey>|<start>|<end>`
|
||
- **验收**：key 生成不依赖对象遍历顺序；同输入同 key。
|
||
|
||
---
|
||
|
||
## 6. 测量实现与降级（approx mode）
|
||
|
||
- [x] 6.1 实现 `measureWidthImpl(text, fontSpec)`（APP）
|
||
- **要求**：
|
||
- 依赖成熟库测量宽度
|
||
- 返回值必须校验：有限且非负
|
||
- **验收**：在单测中用 mock 替代真实库，验证封装逻辑与校验逻辑即可（不做像素级断言）。
|
||
|
||
- [x] 6.2 实现 `measureWidthCached(...)`
|
||
- **行为**：
|
||
- 正常测量：返回 `{ width:number, meta:{ isApprox:false } }`
|
||
- 进入 approx：返回 `{ width:null, meta:{ isApprox:true, reason } }`
|
||
- **approx 触发条件**（任一满足）：
|
||
- 未提供测量能力 / context=WIDGET 且上层不启用测量 -> `WIDTH_UNKNOWN`
|
||
- 抛错/NaN/Infinity/负数 -> `MEASURE_FAILED`
|
||
- **验收**：单测覆盖两类 reason。
|
||
|
||
- [x] 6.3 实现 `measureSliceWidthCached(...)`（切片测量）
|
||
- **要求**：
|
||
- 通过 `joinTokens(start,end)` 生成切片文本
|
||
- 使用切片缓存避免 DP 反复测量
|
||
- **验收**：单测验证同 sliceKey 不重复调用底层测量。
|
||
|
||
---
|
||
|
||
## 7. 单元测试（Vitest）
|
||
|
||
- [x] 7.1 新建 `__tests__/widthMeasurement.test.ts` 并覆盖以下用例
|
||
- **fontSpec 报错**：缺字段必抛错（错误信息含字段名）
|
||
- **缓存命中**：同 key 不重复调用底层测量 mock
|
||
- **缓存隔离**：不同 `contextProfile/fontSpecKey` 不互相污染
|
||
- **降级**：
|
||
- 缺测量能力 -> `width=null` + `WIDTH_UNKNOWN`
|
||
- 测量抛错/NaN -> `width=null` + `MEASURE_FAILED`
|
||
- **验收**：`npm test` 稳定通过。
|
||
|
||
---
|
||
|
||
## 8. 最终自检清单（合入前）
|
||
|
||
- [x] 8.1 `npm test` 通过（包含本模块新增用例）
|
||
- **验收**：不影响现有测试文件。
|
||
|
||
- [x] 8.2 `npx tsc --noEmit` 通过（或项目既有 TS 检查命令通过）
|
||
- **验收**：无类型错误。
|
||
|
||
- [x] 8.3 注释与口径自检（简体中文）
|
||
- **检查点**：
|
||
- `fontSpec` 缺字段“必须报错”
|
||
- key 生成规则与 contextProfile 口径
|
||
- approx mode 的 reason 语义（WIDTH_UNKNOWN / MEASURE_FAILED）
|
||
- **验收**：后续模块开发者只看代码也不会产生歧义。
|
||
|
||
---
|
||
|
||
## 9. 文档回写（任务清单执行完毕后必须做）
|
||
|
||
- [x] 9.1 在 `spec_kit/overview.md` 的 `Text Wrap` 条目下补充执行状态
|
||
- **建议写法**：
|
||
- 增加一行：`- **已完成编码（阶段性）**：width-measurement（宽度测量与降级）`
|
||
- **验收**：overview 能反映该子模块已完成，便于全局追踪。
|
||
|