294 lines
8.7 KiB
Markdown
294 lines
8.7 KiB
Markdown
# 过程背诵练习模块 - 需求与实现记录
|
||
|
||
## 项目信息
|
||
- **创建日期**: 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）
|
||
- ✅ 创建本需求记录文档
|
||
|
||
---
|
||
|
||
**备注**: 本模块已完成核心功能开发和移动端优化，可以正常使用。后续可根据用户反馈进行功能增强和体验优化。
|