127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# grapheme-segmentation（任务清单）
|
||
|
||
> 对应计划：`spec_kit/Text Wrap/modules/grapheme-segmentation/plan.md`
|
||
>
|
||
> 状态含义：`[ ]` 未完成，`[x]` 已完成。
|
||
> 执行完本清单后，需要在 `spec_kit/overview.md` 的 `Text Wrap` 条目下补充“已完成编码/任务执行完毕”的标记（见最后一节）。
|
||
|
||
---
|
||
|
||
## 0. 任务标记规则
|
||
|
||
- 用勾选框标记执行状态：
|
||
- `[ ]` 未完成
|
||
- `[x]` 已完成
|
||
- 每个任务必须可独立验收（有明确产出与检查方式）。
|
||
- 所有代码注释必须为简体中文，且把“分割口径”写清楚，避免跨端实现漂移。
|
||
|
||
---
|
||
|
||
## 1. 前置检查（环境能力与策略选择）
|
||
|
||
- [x] 1.1 确认运行时是否支持 `Intl.Segmenter`（Expo/RN 当前引擎）
|
||
- **方式**：在本地运行/测试环境中打印或断言 `globalThis.Intl?.Segmenter` 是否存在
|
||
- **验收**：记录结论：存在/不存在；若不存在，fallback 必须覆盖所有必测样例。
|
||
|
||
- [x] 1.2 确认 fallback 策略选择为“方案 A：`grapheme-splitter`”
|
||
- **要求**：若项目明确禁止新增依赖，需要在本任务中写明原因并切换到“方案 B（手写最低可用）”，同时补齐更高测试覆盖
|
||
- **验收**：plan 与实际实现策略一致（不出现“文档写 A、代码做 B”的漂移）。
|
||
|
||
---
|
||
|
||
## 2. 依赖与目录骨架（客户端侧实现）
|
||
|
||
- [x] 2.1 新建目录 `client/src/features/textWrap/grapheme/`
|
||
- **产出**（建议文件）：
|
||
- `segmentGraphemes.ts`（对外纯函数）
|
||
- `strategies/intlSegmenter.ts`
|
||
- `strategies/fallback.ts`
|
||
- `types.ts`（返回结构与 meta 类型）
|
||
- `__tests__/segmentGraphemes.test.ts`
|
||
- **验收**：目录存在，TS 可正常 import（不报路径错误）。
|
||
|
||
- [x] 2.2（方案 A）新增依赖 `grapheme-splitter` 并锁定到 `client/package.json`
|
||
- **验收**：
|
||
- `npm install grapheme-splitter` 成功
|
||
- `npm test` 仍能通过（不破坏现有测试）
|
||
|
||
---
|
||
|
||
## 3. 纯函数实现（分割 + meta）
|
||
|
||
- [x] 3.1 实现 `segmentGraphemes(text, mode)` 的返回契约
|
||
- **要求**：
|
||
- 返回 `{ clusters, meta }`
|
||
- `clusters.join('') === text`（不丢字符/不改顺序）
|
||
- `text==''` 时 `clusters==[]`
|
||
- **验收**：为上述约束写入单测并通过。
|
||
|
||
- [x] 3.2 实现优先策略 `Intl.Segmenter`（`mode='PREFERRED'` 时优先）
|
||
- **要求**：
|
||
- `meta.strategy='INTL_SEGMENTER'`
|
||
- `meta.hadFallback=false`
|
||
- **验收**：在支持该能力的环境中，至少 1 个常规输入能走到该策略（可通过 meta 断言）。
|
||
|
||
- [x] 3.3 实现 fallback 策略（满足所有必测“不拆”样例）
|
||
- **触发条件**（任一满足即 fallback）：
|
||
- `mode='FALLBACK'`
|
||
- `Intl.Segmenter` 不存在
|
||
- `Intl.Segmenter` 抛错/返回异常结果（空/丢字符）
|
||
- **要求**：
|
||
- `meta.strategy='FALLBACK'`
|
||
- `meta.hadFallback=true`
|
||
- **验收**：必测样例全部通过（见 4.2）。
|
||
|
||
---
|
||
|
||
## 4. 单元测试（Vitest）
|
||
|
||
- [x] 4.1 基础性质测试
|
||
- **覆盖**：
|
||
- 可逆性：`clusters.join('') === input`
|
||
- 确定性：同输入多次调用输出一致
|
||
- 空字符串：`'' -> []`
|
||
- **验收**：测试通过且不会出现偶现失败。
|
||
|
||
- [x] 4.2 必测回归样例（文档要求：每个都必须“不拆”为 1 个 cluster）
|
||
- **样例**：
|
||
- `👨👩👧👦`
|
||
- `🇸🇬`
|
||
- `👍🏽`
|
||
- `😮💨`
|
||
- `e\u0301`（组合字符形式）
|
||
- **断言**：
|
||
- `clusters.length === 1`
|
||
- `clusters[0] === input`
|
||
- **验收**：在本地 `npm test` 中稳定通过。
|
||
|
||
- [x] 4.3 跨策略一致性测试（在支持 `Intl.Segmenter` 的环境中执行）
|
||
- **内容**：同一输入在 `PREFERRED` 与强制 `FALLBACK` 下输出 clusters 一致
|
||
- **验收**：一致；若不一致，必须新增回归样例并在文档中写明差异与治理方式（`configVersion`）。
|
||
|
||
---
|
||
|
||
## 5. 最终自检清单（合入前）
|
||
|
||
- [x] 5.1 `npm test` 通过（包含本模块新增用例）
|
||
- **验收**：不影响现有测试文件。
|
||
|
||
- [x] 5.2 `npx tsc --noEmit` 通过（或项目既有 TS 检查命令通过）
|
||
- **验收**：无类型错误。
|
||
|
||
- [x] 5.3 注释与口径自检（简体中文）
|
||
- **检查点**：
|
||
- 明确“字符簇不拆”的边界意义（后续断点仅能在 clusters 边界）
|
||
- 明确 fallback 触发条件与 meta 含义
|
||
- **验收**：后续模块开发者只看代码也不会产生歧义。
|
||
|
||
---
|
||
|
||
## 6. 文档回写（任务清单执行完毕后必须做）
|
||
|
||
- [x] 6.1 在 `spec_kit/overview.md` 的 `Text Wrap` 条目下补充执行状态
|
||
- **建议写法**：
|
||
- 增加一行：`- **已完成编码（阶段性）**：grapheme-segmentation（TC 字符簇分割）`
|
||
- **验收**：overview 能反映该子模块已完成，便于全局追踪。
|
||
|