mindfulness/spec_kit/Text Wrap/modules/grapheme-segmentation/tasks.md

grapheme-segmentation（任务清单）

对应计划：spec_kit/Text Wrap/modules/grapheme-segmentation/plan.md

状态含义：[ ] 未完成，[x] 已完成。
执行完本清单后，需要在 spec_kit/overview.md 的 Text Wrap 条目下补充“已完成编码/任务执行完毕”的标记（见最后一节）。

---

0. 任务标记规则

• 用勾选框标记执行状态：
  • [ ] 未完成
  • [x] 已完成
• 每个任务必须可独立验收（有明确产出与检查方式）。
• 所有代码注释必须为简体中文，且把“分割口径”写清楚，避免跨端实现漂移。

---

1. 前置检查（环境能力与策略选择）

• 1.1 确认运行时是否支持 Intl.Segmenter（Expo/RN 当前引擎）

  • 方式：在本地运行/测试环境中打印或断言 globalThis.Intl?.Segmenter 是否存在
  • 验收：记录结论：存在/不存在；若不存在，fallback 必须覆盖所有必测样例。

• 1.2 确认 fallback 策略选择为“方案 A：grapheme-splitter”

  • 要求：若项目明确禁止新增依赖，需要在本任务中写明原因并切换到“方案 B（手写最低可用）”，同时补齐更高测试覆盖
  • 验收：plan 与实际实现策略一致（不出现“文档写 A、代码做 B”的漂移）。

---

2. 依赖与目录骨架（客户端侧实现）

• 2.1 新建目录 client/src/features/textWrap/grapheme/

  • 产出（建议文件）：
    • segmentGraphemes.ts（对外纯函数）
    • strategies/intlSegmenter.ts
    • strategies/fallback.ts
    • types.ts（返回结构与 meta 类型）
    • __tests__/segmentGraphemes.test.ts
  • 验收：目录存在，TS 可正常 import（不报路径错误）。

• 2.2（方案 A）新增依赖 grapheme-splitter 并锁定到 client/package.json

  • 验收：
    • npm install grapheme-splitter 成功
    • npm test 仍能通过（不破坏现有测试）

---

3. 纯函数实现（分割 + meta）

• 3.1 实现 segmentGraphemes(text, mode) 的返回契约

  • 要求：
    • 返回 { clusters, meta }
    • clusters.join('') === text（不丢字符/不改顺序）
    • text=='' 时 clusters==[]
  • 验收：为上述约束写入单测并通过。

• 3.2 实现优先策略 Intl.Segmenter（mode='PREFERRED' 时优先）

  • 要求：
    • meta.strategy='INTL_SEGMENTER'
    • meta.hadFallback=false
  • 验收：在支持该能力的环境中，至少 1 个常规输入能走到该策略（可通过 meta 断言）。

• 3.3 实现 fallback 策略（满足所有必测“不拆”样例）

  • 触发条件（任一满足即 fallback）：
    • mode='FALLBACK'
    • Intl.Segmenter 不存在
    • Intl.Segmenter 抛错/返回异常结果（空/丢字符）
  • 要求：
    • meta.strategy='FALLBACK'
    • meta.hadFallback=true
  • 验收：必测样例全部通过（见 4.2）。

---

4. 单元测试（Vitest）

• 4.1 基础性质测试

  • 覆盖：
    • 可逆性：clusters.join('') === input
    • 确定性：同输入多次调用输出一致
    • 空字符串：'' -> []
  • 验收：测试通过且不会出现偶现失败。

• 4.2 必测回归样例（文档要求：每个都必须“不拆”为 1 个 cluster）

  • 样例：
    • 👨‍👩‍👧‍👦
    • 🇸🇬
    • 👍🏽
    • 😮‍💨
    • e\u0301（组合字符形式）
  • 断言：
    • clusters.length === 1
    • clusters[0] === input
  • 验收：在本地 npm test 中稳定通过。

• 4.3 跨策略一致性测试（在支持 Intl.Segmenter 的环境中执行）

  • 内容：同一输入在 PREFERRED 与强制 FALLBACK 下输出 clusters 一致
  • 验收：一致；若不一致，必须新增回归样例并在文档中写明差异与治理方式（configVersion）。

---

5. 最终自检清单（合入前）

• 5.1 npm test 通过（包含本模块新增用例）

  • 验收：不影响现有测试文件。

• 5.2 npx tsc --noEmit 通过（或项目既有 TS 检查命令通过）

  • 验收：无类型错误。

• 5.3 注释与口径自检（简体中文）

  • 检查点：
    • 明确“字符簇不拆”的边界意义（后续断点仅能在 clusters 边界）
    • 明确 fallback 触发条件与 meta 含义
  • 验收：后续模块开发者只看代码也不会产生歧义。

---

6. 文档回写（任务清单执行完毕后必须做）

• 6.1 在 spec_kit/overview.md 的 Text Wrap 条目下补充执行状态
  • 建议写法：
    • 增加一行：- **已完成编码（阶段性）**：grapheme-segmentation（TC 字符簇分割）
  • 验收：overview 能反映该子模块已完成，便于全局追踪。