docs(练习): 添加过程背诵练习模块需求与实现记录

via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run>
2026-03-01 14:38:27 +00:00
parent da04583703
commit 32172bec2d
1 changed files with 293 additions and 0 deletions
--- a/docs/过程背诵练习-需求与实现.md
+++ b/docs/过程背诵练习-需求与实现.md
@@ -0,0 +1,293 @@
+# 过程背诵练习模块 - 需求与实现记录
+
+## 项目信息
+- **创建日期**: 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`)
+```typescript
+// 顺序：KA01 → P1.1 → P1.2 → ... → P1.7 → KA02 → P2.1 → ...
+// 总计：10个知识领域 + 49个过程 = 59个格子
+```
+
+#### 2. 答案标准化 (`normalizeAnswer`)
+```typescript
+// 去除空格、标点
+// 只对知识领域去除"项目"前缀
+// 过程名称保留"项目"字样
+```
+
+#### 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
+
+### 状态管理
+
+```typescript
+// 格子顺序
+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. **基础框架**
+   - [x] 创建工具函数和类型定义
+   - [x] 创建长按 Hook
+   - [x] 创建格子组件
+   - [x] 创建输入区域组件
+   - [x] 创建辅助信息组件
+   - [x] 创建矩阵组件
+   - [x] 创建主页面组件
+
+2. **核心功能**
+   - [x] 格子顺序生成（59个格子）
+   - [x] 答案标准化（知识领域去除"项目"）
+   - [x] 动态输入框（根据答案长度）
+   - [x] 实时验证（逐字符验证）
+   - [x] 自动跳转（答对后300ms延迟）
+   - [x] TAB键切换（按顺序，跳过空格）
+   - [x] 点击格子切换（允许回顾）
+   - [x] 长按显示答案（支持多端）
+   - [x] 进度跟踪（顶部进度条）
+
+3. **输入法支持**
+   - [x] 监听 compositionStart/End
+   - [x] 输入法期间暂停验证
+   - [x] 确认后立即验证
+
+4. **批量粘贴**
+   - [x] 创建固定长度数组
+   - [x] 不足部分保留空字符串
+   - [x] 避免输入框数量错位
+
+5. **无障碍支持**
+   - [x] aria-live 通告
+   - [x] tabIndex 控制
+   - [x] aria-describedby 关联
+   - [x] scrollIntoView 滚动
+   - [x] role 和 aria-current
+
+6. **移动端优化**
+   - [x] 压缩间距和内边距
+   - [x] 减小字体大小
+   - [x] 底部固定区域分层
+   - [x] 辅助信息限高可滚动
+   - [x] 修复吸顶位置冲突
+
+### 🔧 已修复问题
+
+1. **Codex Review 后的改进**
+   - [x] 修复批量粘贴数组长度问题
+   - [x] 格子可聚焦（支持键盘长按）
+   - [x] 允许回顾已答对的格子
+   - [x] 修复表头吸顶位置冲突
+
+2. **移动端样式问题**
+   - [x] 底部区域布局重构
+   - [x] 压缩矩阵格子尺寸
+   - [x] 辅助信息区域优化
+   - [x] 主内容区域底部内边距
+
+### 📝 待优化项（可选）
+
+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）
+- ✅ 创建本需求记录文档
+
+---
+
+**备注**: 本模块已完成核心功能开发和移动端优化，可以正常使用。后续可根据用户反馈进行功能增强和体验优化。