shiyue/ittoview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49dcbc4e5925ffb08aec4912190a6c325d99faa5
ittoview/docs/过程背诵练习-需求与实现.md
ittoview 32172bec2d docs(练习): 添加过程背诵练习模块需求与实现记录 
via [HAPI](https://hapi.run)

Co-Authored-By: HAPI <noreply@hapi.run>
2026-03-01 14:38:27 +00:00

8.7 KiB
Raw Blame History

过程背诵练习模块 - 需求与实现记录

项目信息

  • 创建日期: 2026-03-01
  • 模块名称: 过程背诵练习 (Process Practice)
  • 路由地址: /process-practice
  • 提交记录:
    • 初始实现: cc8dd1e
    • 移动端优化: da04583

需求概述

创建一个交互式背诵练习模块，帮助用户记忆 PMP 项目管理的 10 个知识领域和 49 个过程。

核心功能需求

1. 矩阵布局

  • 显示知识领域 × 过程组的矩阵（10行 × 5列）
  • 表头：5个过程组（启动、规划、执行、监控、收尾）
  • 知识领域格子横跨5列
  • 过程格子按过程组分列显示
  • 空单元格置灰显示（如范围管理-启动过程组）

2. 背诵对象

  • 知识领域（10个）：如"整合管理"（去除"项目"前缀）
  • 过程（49个）：如"制定项目章程"
  • 总计：59个格子需要背诵

3. 输入交互

  • 动态输入框：根据答案长度显示对应数量的横线
  • 实时验证：逐字符验证，错误标红，正确显示绿色
  • 答对后自动跳转到下一个格子（延迟300ms）
  • 支持中文输入法（监听 compositionStart/End）
  • 支持批量粘贴（固定长度数组，避免错位）

4. 辅助信息

  • 知识领域格子：显示敏捷裁剪因素（tailoringFactors）
  • 过程格子：显示主要作用（purpose）
  • 位置：固定在底部，输入框下方
  • 移动端优化：限高可滚动，只显示前2个裁剪因素

5. 格子切换

  • TAB键：按顺序切换（KA01 → P1.1 → P1.2 → ... → KA02 → ...）
  • 点击格子：直接切换到目标格子
  • 自动跳过：空单元格不可聚焦
  • 允许回顾：可以点击已答对的格子重新查看

6. 长按显示答案

  • 支持触摸、鼠标和键盘（空格键）
  • 长按600ms后显示答案
  • 松开后隐藏答案
  • 3秒后自动隐藏
  • 显示答案期间锁定输入区域

7. 进度跟踪

  • 顶部显示进度条
  • 显示已答对数量 / 总数量
  • 进度条动画效果

8. 无障碍支持

  • aria-live 区域通告答案显示/隐藏
  • tabIndex 控制键盘导航
  • aria-describedby 关联辅助信息
  • scrollIntoView 确保格子可见
  • role="button" 和 aria-current 标记

技术实现

文件结构

src/
├── utils/
│   └── practice.ts                    # 工具函数
├── hooks/
│   └── useLongPress.ts                # 长按 Hook
├── components/
│   └── practice/
│       ├── KnowledgeAreaCell.tsx      # 知识领域格子
│       ├── ProcessCell.tsx            # 过程格子
│       ├── InputArea.tsx              # 输入区域
│       ├── HintInfo.tsx               # 辅助信息
│       └── PracticeMatrix.tsx         # 矩阵组件
├── pages/
│   └── ProcessPracticePage.tsx        # 主页面
├── App.tsx                            # 路由配置
└── components/layout/Sidebar.tsx      # 导航菜单

核心算法

1. 格子顺序生成 (generateCellSequence)

// 顺序：KA01 → P1.1 → P1.2 → ... → P1.7 → KA02 → P2.1 → ...
// 总计：10个知识领域 + 49个过程 = 59个格子

2. 答案标准化 (normalizeAnswer)

// 去除空格、标点
// 只对知识领域去除"项目"前缀
// 过程名称保留"项目"字样

3. 输入验证逻辑

  • 使用原始答案长度渲染横线
  • 使用标准化答案进行验证
  • 逐字符比对，维护 charStatuses 数组
  • 完整答案验证后触发跳转或错误提示

4. 长按检测 (useLongPress)

  • onPointerDown 启动600ms定时器
  • onPointerUp/Leave/Cancel 清理定时器
  • 支持键盘空格键长按
  • 阻止 contextMenu 事件

样式设计

桌面端

  • 矩阵格子：p-4, gap-3, min-h-60px
  • 字体大小：text-sm, text-base
  • 输入框：w-10, h-12, text-2xl

移动端优化

  • 矩阵格子：p-2, gap-2, min-h-40px
  • 字体大小：text-xs, text-sm
  • 输入框：保持原大小（便于输入）
  • 底部固定区域：分层显示输入框和辅助信息
  • 辅助信息：max-h-32, overflow-y-auto

状态管理

// 格子顺序
cellSequence: CellInfo[]

// 答题记录
answeredCells: Map<string, boolean>

// 当前焦点
currentCellId: string | null

// 输入状态
userInput: string[]
charStatuses: CharStatus[]
isComposing: boolean
lastErrorTimestamp: number | null

// 长按显示答案
showAnswerForCell: { cellId, answer, expiresAt } | null
inputLocked: boolean

实现进度

✅ 已完成功能

  1. 基础框架

    • 创建工具函数和类型定义
    • 创建长按 Hook
    • 创建格子组件
    • 创建输入区域组件
    • 创建辅助信息组件
    • 创建矩阵组件
    • 创建主页面组件

  2. 核心功能

    • 格子顺序生成（59个格子）
    • 答案标准化（知识领域去除"项目"）
    • 动态输入框（根据答案长度）
    • 实时验证（逐字符验证）
    • 自动跳转（答对后300ms延迟）
    • TAB键切换（按顺序，跳过空格）
    • 点击格子切换（允许回顾）
    • 长按显示答案（支持多端）
    • 进度跟踪（顶部进度条）

  3. 输入法支持

    • 监听 compositionStart/End
    • 输入法期间暂停验证
    • 确认后立即验证

  4. 批量粘贴

    • 创建固定长度数组
    • 不足部分保留空字符串
    • 避免输入框数量错位

  5. 无障碍支持

    • aria-live 通告
    • tabIndex 控制
    • aria-describedby 关联
    • scrollIntoView 滚动
    • role 和 aria-current

  6. 移动端优化

    • 压缩间距和内边距
    • 减小字体大小
    • 底部固定区域分层
    • 辅助信息限高可滚动
    • 修复吸顶位置冲突

🔧 已修复问题

  1. Codex Review 后的改进

    • 修复批量粘贴数组长度问题
    • 格子可聚焦（支持键盘长按）
    • 允许回顾已答对的格子
    • 修复表头吸顶位置冲突

  2. 移动端样式问题

    • 底部区域布局重构
    • 压缩矩阵格子尺寸
    • 辅助信息区域优化
    • 主内容区域底部内边距

📝 待优化项（可选）

  1. 性能优化

    • 虚拟滚动（如果格子数量增加）
    • 使用 React.memo 优化格子渲染
    • 防抖输入验证（目前已有 requestAnimationFrame）

  2. 功能增强

    • 添加"重置"按钮（清空所有答题记录）
    • 添加"跳过"按钮（跳过当前格子）
    • 保存练习进度到 localStorage
    • 统计答题时间和错误次数
    • 提供"只练习知识领域"或"只练习过程"模式

  3. 用户体验

    • 添加音效反馈（答对/答错）
    • 添加震动反馈（移动端）
    • 提供快捷键说明（帮助面板）
    • 添加"提示"按钮（显示首字母）

数据依赖

知识领域数据

  • 文件：src/data/knowledge-areas.json
  • 字段：id, name, order, color, tailoringFactors

过程数据

  • 文件：src/data/processes.json
  • 字段：id, code, name, knowledgeAreaId, processGroupId, order, purpose

过程组数据

  • 文件：src/data/process-groups.json
  • 字段：id, name, order, color

测试要点

功能测试

  1. 访问 /process-practice 页面
  2. 验证矩阵初始状态（所有格子空白占位）
  3. 输入"整合管理"，验证格子显示"1.整合管理"
  4. 验证自动跳转到下一个格子
  5. 测试 TAB 键切换顺序
  6. 测试点击格子切换
  7. 测试长按显示答案（600ms）
  8. 测试输入法输入
  9. 测试批量粘贴
  10. 完成所有59个格子的答题

边界测试

  • 第一个格子按 Shift+Tab（不应有反应）
  • 最后一个格子按 Tab（不应有反应）
  • 长按空单元格（不应有反应）
  • 快速连续输入（验证防抖）
  • 输入错误后按 Escape（验证清空输入）

移动端测试

  • 验证底部固定区域不遮挡内容
  • 验证辅助信息区域可滚动
  • 验证格子尺寸适配小屏幕
  • 验证触摸长按功能

相关文档

  • 需求设计文档：docs/需求设计文档.md
  • 实现计划：/root/.claude/plans/iridescent-cooking-bee.md
  • CLAUDE.md：/home/ittoview/CLAUDE.md

更新日志

2026-03-01

  • ✅ 完成初始实现（提交 cc8dd1e）
  • ✅ 修复 Codex Review 发现的问题
  • ✅ 优化移动端布局和样式（提交 da04583）
  • ✅ 创建本需求记录文档

备注: 本模块已完成核心功能开发和移动端优化，可以正常使用。后续可根据用户反馈进行功能增强和体验优化。